ABI versioning and compatibility

Platform spec feature

ABI versioning and compatibility

Back to ABI and host boundary ◎ Open 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

• Area
  ABI and host boundary

  Parent area

• Area
  Runtime

  Runtime exports implement ABI compatibility commitments

• Area
  Codegen and IR

  Lowering consumes ABI version and symbol constraints

What this feature specifies

ABI versioning and compatibility defines one operational contract that a newcomer can follow end-to-end: first the model, then execution flow, then strict guarantees, concrete examples, and verification guidance.

Implementation anchors

• AbiVersion and compatibility definitions in compiler/crates/beskid_abi/src/lib.rs
• RUNTIME_EXPORT_SYMBOLS in compiler/crates/beskid_abi/src/symbols.rs
• JIT/runtime symbol loading in compiler/crates/beskid_engine/src/jit_module.rs
• Runtime exports in compiler/crates/beskid_runtime/src/lib.rs

Decisions

No open decisions. Closed choices are normative ADRs under adr/ (D-EXEC-ABI-0001, D-EXEC-ABI-0002); use the reader ADRs tab for expandable detail.

Articles

• Hard ABI version check before user codeHosts reject mismatched compiler and runtime ABI integers before executing generated code.
• Contracts and edge casesMUST/SHOULD rules for ABI version bumps, symbol stability, and mixed toolchain failures.
• Design modelABI version negotiation, symbol stability, and compiler–runtime compatibility boundaries.
• ExamplesABI version checks, symbol parity, and migration scenarios for toolchain maintainers.
• FAQ and troubleshootingCommon ABI mismatch failures and maintainer guidance for version bumps.
• Flow and algorithmJIT symbol registration, ABI version export, and compatibility check ordering.
• Verification and traceabilityTests and crate paths that pin ABI version and runtime export symbol parity.