Contracts and edge cases

Platform spec article

Contracts and edge cases

Back to ABI versioning and compatibility ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0001-hard-abi-version-check Hard ABI version check before user code Accepted

   Hosts reject mismatched compiler and runtime ABI integers before executing generated code.

   Context

   JIT and CLI hosts may load a beskid_runtime artifact built separately from the active compiler. Without an explicit version gate, stale toolchains call builtins with wrong layouts or missing symbols.

   Decision

   Rule	Detail
   Version surface	beskid_runtime_abi_version() returns BESKID_RUNTIME_ABI_VERSION (u32 in beskid_abi)
   Host check	Hosts should fail before user main when runtime version ≠ compiler-embedded constant (ABI-003)
   Diagnostics	Failure messages must name both integers and recommend aligning CLI/VSIX/runtime release sets

   Consequences

   Release matrices document paired compiler/runtime builds. Conformance should assert version parity in JIT smoke tests (beskid_tests runtime/jit).

   Verification anchors

   compiler/crates/beskid_abi/src/version.rs; beskid_engine JIT module setup; ABI-001–ABI-003 in contracts and edge cases.

   Open full ADR page

2. 0002-breaking-changes-bump-version Breaking ABI changes require version bump Accepted

   Layout, signature, or semantic breaks must increment BESKID_RUNTIME_ABI_VERSION.

   Context

   Additive runtime symbols and Cargo feature gates are easy to confuse with ABI-stable changes. Silent signature drift breaks AOT/JIT link steps or causes undefined behavior at call sites.

   Decision

   Trigger	Action
   BeskidStr / BeskidArray / interop payload layout change	Must increment BESKID_RUNTIME_ABI_VERSION (ABI-004)
   Builtin rename, arity change, or AbiParamKind / AbiReturnKind change	Must bump version
   Semantics relied on by lowering change (e.g. barrier no-op)	Must bump version
   New symbol appended, older artifacts never import it	May ship without bump (ABI-005)
   Optional Cargo features only	Must not bump ABI version

   Reference tree pins version 2 until the next breaking change.

   Consequences

   Release notes should list bumped versions and removed symbols. Renaming without bump is a release-process violation.

   Verification anchors

   beskid_abi symbol tables; RUNTIME_EXPORT_SYMBOLS parity checks in CI.

   Open full ADR page

Articles

• Contracts and edge cases MUST/SHOULD rules for ABI version bumps, symbol stability, and mixed toolchain failures. article Standard Reviewed Fri May 22
• Design model ABI version negotiation, symbol stability, and compiler–runtime compatibility boundaries. article Standard Reviewed Fri May 22
• Examples ABI version checks, symbol parity, and migration scenarios for toolchain maintainers. article Standard Reviewed Fri May 22
• FAQ and troubleshooting Common ABI mismatch failures and maintainer guidance for version bumps. article Standard Reviewed Fri May 22
• Flow and algorithm JIT symbol registration, ABI version export, and compatibility check ordering. article Standard Reviewed Fri May 22
• Verification and traceability Tests and crate paths that pin ABI version and runtime export symbol parity. 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
  ABI versioning and compatibility

  Parent feature hub

Normative requirements

ID	Requirement
ABI-001	RUNTIME_EXPORT_SYMBOLS in beskid_abi must list every symbol the JIT registers and the runtime exports with #[unsafe(no_mangle)] under the same spelling.
ABI-002	BUILTIN_SPECS must be the sole source of Cranelift import signatures for runtime builtins; hand-written CLIF calls must not invent alternate calling conventions.
ABI-003	Hosts should reject execution when beskid_runtime_abi_version() ≠ BESKID_RUNTIME_ABI_VERSION compiled into the active compiler.
ABI-004	Breaking layout or signature changes must increment BESKID_RUNTIME_ABI_VERSION; silent mismatches are forbidden.
ABI-005	Additive symbols may ship without a version bump only if older generated code never imports them and older runtimes ignore unknown symbols safely.
ABI-006	JIT and AOT for the same release must target identical beskid_abi revision (same symbol set and signatures).

Edge cases

Scenario	Expected behavior
Stale VSIX / CLI with fresh runtime	Version check fails fast with actionable diagnostics before running user main.
Renamed builtin without version bump	Link or JIT finalize fails (MissingFunction) or undefined behavior if forced—treated as a release process violation.
Optional runtime features (arrays_backing, metrics)	Do not change BESKID_RUNTIME_ABI_VERSION; see Runtime feature flags.
Dynamic Extern symbols	Resolved addresses are extras in BeskidJitModule::new_with_symbols; they are not part of RUNTIME_EXPORT_SYMBOLS.

SHOULD guidance

• Release notes should document ABI bumps and list removed or renamed symbols.
• Conformance fixtures should assert symbol list parity between symbols.rs and beskid_runtime::lib.rs re-exports.

Related topics

• Extern dispatch and policy — user library symbols outside RUNTIME_EXPORT_SYMBOLS
• Rust ABI profile — runtime export calling convention vocabulary