Interop.Contracts — Conformance and versioning

Platform spec article

Interop.Contracts — Conformance and versioning

Back to Interop.Contracts ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (3)

1. 0001-hub-authority Feature hub owns normative contract Accepted

   Abstract boundary vocabulary authority.

   Context

   C and Rust profiles previously duplicated primitive definitions.

   Decision

   This feature hub must own the language-agnostic Interop.Contracts vocabulary. Profile features must bind these primitives, not redefine them.

   Consequences

   Articles under C/Rust ABI cite ownership, call shapes, and conformance from here.

   Verification anchors

   /platform-spec/language-meta/interop/interop-contracts/

   Open full ADR page

2. 0002-profiles-bind-primitives Profiles instantiate abstract primitives Accepted

   C ABI and Rust ABI profiles map Interop.Contracts.

   Context

   Authors need one abstract model with two concrete ABI bindings.

   Decision

   Interop.Contracts does not prescribe a single calling convention. C ABI profile and Rust ABI profile must bind symbols, layouts, linking, and unwind rules to these primitives.

   Consequences

   Syntax for Extern contracts remains under FFI and extern; profiles add ABI tables.

   Verification anchors

   /platform-spec/language-meta/interop/interop-contracts/ and profile hubs.

   Open full ADR page

3. 0003-conformance-envelope Conformance and versioning envelope Accepted

   Forward compatibility rules for hosts claiming Interop.Contracts.

   Context

   Hosts and compilers need a shared compatibility story at boundaries.

   Decision

   This feature must specify symbol identity, type-shape classes, call-shape classes, ownership obligations, error/unwind semantics, and a conformance envelope (versioning and forward compatibility) for compatibility claims.

   Consequences

   ABI contract tests and BESKID_RUNTIME_ABI_VERSION align to the envelope.

   Verification anchors

   compiler/crates/beskid_tests/src/abi/contracts.rs; conformance and versioning.

   Open full ADR page

Articles

• Interop.Contracts — Callback call shapes Function-pointer parameters and host registration tables for foreign re-entry (v0.3). article Standard Reviewed Wed May 20
• Interop.Contracts — Conformance and versioning ABI version gates, forward compatibility, and how artifacts claim Interop.Contracts conformance. article Standard Reviewed Fri May 01
• Interop.Contracts — Core primitives Symbol identity, type-shape classes, call-shape classes, and boundary invariants shared by all interop profiles. article Standard Reviewed Fri May 01
• Interop.Contracts — Error and unwind semantics Divergence, traps, and cross-boundary panic policy for FFI (v0.3). article Standard Reviewed Wed May 20
• Interop.Contracts — Language-agnostic mapping rules How Beskid declarations map to abstract call shapes and foreign symbols before any C- or Rust-specific lowering. article Standard Reviewed Fri May 01
• Interop.Contracts — Ownership at the boundary Borrow, transfer, and opaque-handle rules for parameters on foreign call shapes (v0.3). article Standard Reviewed Wed May 20

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 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
  Interop.Contracts

  Parent feature hub

• Feature
  Rust ABI profile

  Runtime export stability

Runtime ABI version (embedding)

The platform publishes a monotonic runtime ABI version constant for the Rust runtime export surface (BESKID_RUNTIME_ABI_VERSION). An artifact must not load against a runtime that reports an incompatible version when linking builtins.

Implementation reference: compiler/crates/beskid_abi/src/version.rs and compiler/crates/beskid_tests/src/abi/contracts.rs.

User FFI (import layouts, interop views, export tables) is versioned separately — see User FFI layout band below. Bumping user FFI layouts must not require bumping BESKID_RUNTIME_ABI_VERSION unless a runtime export symbol or builtin signature changes.

User FFI layout band (v0.3)

The platform maintains a user FFI layout band for:

• Interop view record layouts (CStringView, CBuffer, CArrayView).
• Export/callback registration table header layout.
• Optional future repr(C) rules (v0.3.1).

Toolchains should record the band in build metadata (for example manifest or artifact stamp) so linkers and hosts reject incompatible combinations. The reference constant name is reserved as BESKID_USER_FFI_LAYOUT_BAND (implementation may trail spec).

Band	Standard content
v0.3.0	Interop views, link-time import, export + callback registration
v0.3.1	CLayout records with primitive fields only
v0.3.2+	Proposed: nested FFI structs, foreign-thread entry

Forward compatibility

Interop.Contracts distinguishes:

• Normative contracts — behavior and layouts the platform commits to for a given ABI version band.
• Reserved extensions — symbol names or dispatch slots documented as internal or experimental; user code must not depend on them unless a feature explicitly promotes them to normative status.

When adding symbols or shapes, the platform should extend tables in beskid_abi with documentation in the Rust ABI profile before declaring user-visible stability.

Profile conformance

A toolchain build conforms to Interop.Contracts if:

1. Every emitted foreign call can be traced to an abstract call shape and symbol identity defined here or in a normative profile article.
2. Runtime exports match the allowlisted symbol set for the declared ABI version.
3. Diagnostics reject unsupported combinations (for example extern imports when the engine feature that resolves them is disabled).