Breaking ABI changes require version bump

Platform spec ADR

Breaking ABI changes require version bump

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

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

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.