FAQ and troubleshooting

Platform spec article

FAQ and troubleshooting

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

FAQ

When must we bump BESKID_RUNTIME_ABI_VERSION?

When an existing generated call pattern would observe different layout, symbol names, or Cranelift signatures at link time. Purely additive exports that no shipped compiler emits may stay on the same version (ABI-005).

Does the VSIX bundle its own runtime?

The extension ships a platform-matched beskid CLI/LSP stack; that stack must be built against the same beskid_abi revision as the embedded compiler. Mismatch manifests as JIT MissingFunction or version gate failures—reinstall matching artifacts rather than mixing arbitrary release channels.

Are interop_dispatch_* symbols part of the versioned surface?

Yes. They appear in RUNTIME_EXPORT_SYMBOLS and BUILTIN_SPECS. Tag/payload layout changes require an ABI bump and coordinated engine/runtime updates (Builtins and symbols).

Can JIT use a newer runtime than the compiler?

Only when beskid_runtime_abi_version() is still equal to the compiler’s expected constant and no removed symbols are referenced. Otherwise rebuild the compiler; unsupported mixing is intentional (ABI-004).

Troubleshooting

Symptom	Likely cause	Fix
missing function 'alloc' at JIT finalize	Runtime library not linked or stripped exports	Ensure beskid_runtime built with default features; verify RUNTIME_EXPORT_SYMBOLS
Segfault on first builtin call	Wrong function pointer type registered	Check BUILTIN_SPECS vs runtime extern "C-unwind" signature
Works in debug CLI, fails in VSIX	Stale extension runtime	Rebuild Open VSX matrix with matching beskid_abi
AOT binary crashes, JIT OK	Old runtime .so bundled in deploy	Re-link AOT with current beskid_runtime

Related topics

• Flow and algorithm
• Runtime feature flags — optional arrays_backing without ABI version bumps