Design model

Platform spec article

Design model

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

• Area
  ABI and host boundary

  Parent area

• Feature
  ABI versioning and compatibility

  Parent feature hub

• Feature
  Builtins and symbols

  Symbol tables versioned with ABI bumps

Purpose

Define how the compiler, JIT/AOT backends, and Beskid runtime agree on a single numeric ABI version and a frozen export surface so generated code never calls missing or mis-typed runtime entrypoints.

Primary actors

Actor	Responsibility
beskid_abi	Owns BESKID_RUNTIME_ABI_VERSION, RUNTIME_EXPORT_SYMBOLS, and builtin signature metadata consumed by codegen.
beskid_codegen / beskid_engine	Declares imports from BUILTIN_SPECS and validates user Extern shapes before linking.
beskid_runtime	Implements #[unsafe(no_mangle)] exports; beskid_runtime_abi_version() returns the compile-time constant.
Host tooling	JIT session and AOT link steps load the same runtime artifact the compiler was built against (or an explicitly compatible newer runtime).

Subsystem boundaries

• In scope: ABI integer version, additive vs breaking symbol changes, JIT symbol registration parity with AOT, and migration expectations when bumping BESKID_RUNTIME_ABI_VERSION in compiler/crates/beskid_abi/src/version.rs.
• Out of scope: Language-level Extern syntax (FFI and extern), C link-time profiles (C ABI profile), and per-builtin semantics (Builtins and symbols).

Version and symbol model

The ABI version is a u32 exposed as beskid_runtime_abi_version. The reference tree currently pins BESKID_RUNTIME_ABI_VERSION = 2. A bump is required when any of the following change incompatibly:

• C layout of BeskidStr, BeskidArray, or interop payload offsets referenced by lowering.
• Name, parameter count, or AbiParamKind / AbiReturnKind of a builtin in BUILTIN_SPECS.
• Semantics that generated code already depends on (for example making gc_write_barrier a no-op when lowering assumes barriers run).

Additive changes (new symbols appended to RUNTIME_EXPORT_SYMBOLS, new optional runtime features) should not require a version bump if existing artifacts keep working without recompilation.

Compatibility diagram

flowchart LR
  abi[beskid_abi version + symbols]
  codegen[Codegen artifact]
  jit[JIT / AOT linker]
  rt[beskid_runtime exports]
  abi --> codegen
  abi --> jit
  jit -->|resolve imports| rt
  codegen --> jit

Codegen and the engine read the same beskid_abi crate revision at build time. At run time, hosts should treat a lower runtime version than the compiler expects as a hard compatibility failure before executing user code.

Platform assumptions (v0.2 baseline)

Reference implementations target 64-bit pointers and Linux x86_64 for syscall-backed builtins; other hosts may stub behavior but must preserve symbol names and Cranelift signature shapes declared in BUILTIN_SPECS.

Related topics

• Flow and algorithm — JIT registration and version check ordering
• Contracts and edge cases — normative ABI-00x requirements
• Legacy bridge: Runtime ABI (v0.1)