Verification and traceability

Platform spec article

Verification and traceability

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

Source-of-truth crates

Path	What it pins
compiler/crates/beskid_abi/src/version.rs	BESKID_RUNTIME_ABI_VERSION
compiler/crates/beskid_abi/src/symbols.rs	RUNTIME_EXPORT_SYMBOLS, SYM_* constants
compiler/crates/beskid_abi/src/builtins.rs	BUILTIN_SPECS signatures
compiler/crates/beskid_runtime/src/builtins/version.rs	beskid_runtime_abi_version() export
compiler/crates/beskid_engine/src/jit_module.rs	Builtin pointer registration for JIT

Integration tests

Harness	Coverage
compiler/crates/beskid_tests/src/runtime/jit.rs	JIT compiles and runs lowered programs against in-process runtime
compiler/crates/beskid_e2e_tests/src/tests/runtime_cases.rs	End-to-end runtime builtins including panic/IO paths
compiler/crates/beskid_engine (feature extern_dlopen)	Dynamic extern resolution when enabled; see Extern dispatch

Traceability matrix

Requirement	Verification
ABI-001	Review RUNTIME_EXPORT_SYMBOLS vs beskid_runtime pub use list on every ABI-touching PR
ABI-002	declare_builtin_imports uses BUILTIN_SPECS exclusively (beskid_codegen)
ABI-003	Host/version gate tests in JIT and CLI startup (add when missing)
ABI-006	Same beskid_abi path dependency in beskid_engine, beskid_codegen, and beskid_runtime workspace Cargo.toml

CI expectations

Compiler workspace CI must run runtime JIT tests on Linux x86_64 agents. ABI-breaking PRs must include spec updates under this feature and a version constant bump when ABI-004 applies.

Related topics

• Contracts and edge cases — requirement IDs
• Builtins and symbols verification