Contracts and edge cases

Platform spec article

Contracts and edge cases

Back to Runtime feature flags ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0014-cargo-features-not-abi-version Cargo features are separate from ABI version Accepted

   Optional runtime capabilities toggle code paths without bumping BESKID_RUNTIME_ABI_VERSION.

   Context

   CI and VSIX builds enable different beskid_runtime features. Confusing feature gates with ABI bumps breaks compatibility checks.

   Decision

   Concept	Rule
   BESKID_RUNTIME_ABI_VERSION	Changes only on breaking layout/signature per D-EXEC-ABI-0002
   Cargo features	metrics, arrays_backing, sched — build-time toggles
   Additive exports	New feature-gated symbols may ship without ABI bump if old artifacts never import them
   Shipped binaries	Must document enabled features in release notes
   Tests	Compiler tests enable features explicitly when validating optional paths

   Consequences

   Mismatch (test expects arrays_backing, default runtime does not) fails logically without ABI version inequality.

   Verification anchors

   beskid_runtime/Cargo.toml; design model feature table.

   Open full ADR page

2. 0015-arrays-backing-feature arrays_backing gates array element storage Accepted

   Without the feature, array_new may emit header-only arrays with null backing.

   Context

   Array lowering depends on whether the linked runtime allocates element storage behind BeskidArray headers.

   Decision

   arrays_backing	Behavior
   Enabled	array_new allocates element storage; ptr non-null when length > 0
   Disabled	Header-only arrays; ptr may be null
   ABI	Symbol list unchanged; semantics differ by build — document in release matrices
   Alignment	Shipped CLI/VSIX should enable arrays_backing for reference user workflows

   Consequences

   Conformance and doc tests must pin feature set when asserting array behavior.

   Verification anchors

   beskid_runtime array_new; runtime JIT tests with feature flags.

   Open full ADR page

Articles

• Contracts and edge cases MUST/SHOULD rules for optional runtime features and toolchain alignment. article Standard Reviewed Fri May 22
• Design model Cargo feature gates, runtime build capabilities, and compiler alignment expectations. article Standard Reviewed Fri May 22
• Examples Building runtime with features, array backing expectations, and engine extern_dlopen. article Standard Reviewed Fri May 22
• FAQ and troubleshooting Optional runtime features vs ABI version, array backing surprises, and CI alignment. article Standard Reviewed Fri May 22
• Flow and algorithm Selecting runtime features at build time and validating behavior at run time. article Standard Reviewed Fri May 22
• Verification and traceability Cargo feature definitions, conditional compilation gates, and CI matrix expectations. article Standard Reviewed Fri May 22

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 2 SpecSection(s) · 1 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  Runtime feature flags

  Parent feature hub

Normative requirements

ID	Requirement
RFF-001	Optional runtime features must not change BESKID_RUNTIME_ABI_VERSION unless they alter existing symbol signatures or layouts.
RFF-002	Default CI/release runtime builds must document which features are enabled in build notes or manifests.
RFF-003	Tests that require arrays_backing must enable the feature on beskid_runtime dependency.
RFF-004	metrics exports must be absent from baseline RUNTIME_EXPORT_SYMBOLS when built without metrics.
RFF-005	Compiler lowering must not assume element backing exists unless workspace policy enables arrays_backing.
RFF-006	extern_dlopen must remain off by default on beskid_engine for production toolchains.
RFF-007	Phase B GC must be opt-in for v0.3; the runtime must boot in Phase A unless BESKID_RUNTIME_PHASE_B=1 or set_runtime_phase(RuntimePhase::PhaseB) flips it.
RFF-008	Optional preemption must stay disabled by default; enabling it via BESKID_RUNTIME_PREEMPT=1 or set_preemption_enabled(true) must not change observable semantics of fiber-only programs beyond inserting yield points.

Feature behavior table

Feature	Without	With
arrays_backing	array_new.ptr == null	Backing store allocated
metrics	No rt_metrics_*	Counters exposed
sched	Default scheduler only	Experimental sched hooks
Phase B GC (BESKID_RUNTIME_PHASE_B)	Single-mutator Phase A; channel pointer payloads still routed through external roots but barriers no-op outside marking	Multiple mutators may attach via attach_phase_b_mutator; gc_write_barrier active on pointer-payload channel ops
Preemption (BESKID_RUNTIME_PREEMPT)	runtime_preempt_check is a no-op	runtime_preempt_check yields the current fiber (or OS thread if off-scheduler)

Edge cases

Case	Outcome
Test expects backing, runtime default	Tests fail allocation or pointer reads — fix features, not ABI
User enables metrics locally	JIT must link extra symbols only if codegen calls them
VSIX runtime vs CLI runtime feature mismatch	Subtle array/GC test failures — align Open VSX build matrix

Related topics

• ABI versioning
• Legacy mention: Runtime ABI v0.1 arrays_backing