Examples

Platform spec article

Examples

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

Host version gate (Rust pseudocode)

A JIT host can refuse to run when versions diverge:

let expected = beskid_abi::BESKID_RUNTIME_ABI_VERSION;
let actual = unsafe { beskid_runtime::beskid_runtime_abi_version() };
if actual != expected {
    panic!("runtime ABI {actual} != compiler ABI {expected}");
}

Production CLIs should surface this as a structured error rather than a raw panic.

Additive symbol (no bump)

Suppose maintainers add fiber_debug_trace to RUNTIME_EXPORT_SYMBOLS and beskid_runtime, but no released compiler lowering emits calls to it yet. Older artifacts keep working; newer compilers may call the symbol once lowering lands. No BESKID_RUNTIME_ABI_VERSION change is required (ABI-005).

Breaking rename (bump required)

Renaming fiber_join export to fiber_join_status without updating every BUILTIN_SPECS consumer breaks link compatibility. The fix set is:

1. BESKID_RUNTIME_ABI_VERSION += 1
2. Synchronized symbols.rs, builtins.rs, runtime #[unsafe(no_mangle)] names, and docs
3. Rebuild and republish CLI, VSIX, and prebuilt runtime bundles together

Inspecting the export list

Maintainers compare:

• compiler/crates/beskid_abi/src/symbols.rs → RUNTIME_EXPORT_SYMBOLS
• compiler/crates/beskid_runtime/src/lib.rs → pub use builtins::{ … }

Every JIT-resolved builtin must appear in both lists with identical spelling.

Related topics

• Verification and traceability — automated parity checks
• Legacy: Runtime ABI (v0.1)