Flow and algorithm

Platform spec article

Flow and algorithm

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

Purpose

Document the end-to-end algorithm from compiler build through JIT/AOT link to first user entry, including where ABI version and export symbols are validated.

See the design model diagram for actor boundaries.

JIT session setup

1. Construct BeskidJitModule (compiler/crates/beskid_engine/src/jit_module.rs) with an optional extras table for resolved user Extern addresses when dynamic linking is enabled.
2. On first compile, call declare_builtin_imports once, wiring every name in BUILTIN_SPECS to the in-process beskid_runtime function pointer of the same symbol string.
3. Declare user functions and validated extern imports from the CodegenArtifact, emit string literals and type descriptors, then define and finalize Cranelift bodies.
4. Before transferring control to generated code, the host should call beskid_runtime_abi_version() and compare the result to BESKID_RUNTIME_ABI_VERSION embedded in the compiler’s beskid_abi dependency (ABI-003).

AOT / bundled runtime path

1. Backend emits object code that imports the same symbol names listed in RUNTIME_EXPORT_SYMBOLS.
2. Link step resolves symbols against the bundled beskid_runtime static or shared library built for the target triple.
3. Packaging must record the ABI version used at link time in release metadata when distributing standalone binaries (tooling convention; see verification).

Symbol registration algorithm

For each BuiltinFnSpec entry in compiler/crates/beskid_abi/src/builtins.rs:

1. Map symbol to a host extern "C-unwind" function in beskid_runtime::builtins.
2. Build a Cranelift function signature from params: &[AbiParamKind] and returns: AbiReturnKind (Ptr, I64, Void, Never, …).
3. Store the FuncId in the JIT module’s func_ids map so lowering can emit direct calls.

Missing symbols surface as JitError::MissingFunction at finalize time rather than as undefined behavior at runtime.

ABI bump workflow (maintainers)

1. Increment BESKID_RUNTIME_ABI_VERSION in beskid_abi/src/version.rs.
2. Update RUNTIME_EXPORT_SYMBOLS and BUILTIN_SPECS together with runtime #[unsafe(no_mangle)] implementations.
3. Refresh platform-spec articles and compiler/crates/beskid_tests / beskid_e2e_tests fixtures that pin version or symbol lists.
4. Publish runtime and compiler artifacts in lockstep; mixed versions are unsupported for production (ABI-004).

Related topics

• Design model — compatibility diagram and actors
• Builtins and symbols — per-symbol contracts