Interop.Contracts — Core primitives

Platform spec article

Interop.Contracts — Core primitives

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

Symbol identity

A foreign symbol is identified for interop purposes by a logical name (the string used at link or load time) together with optional library or module metadata, depending on the profile. Profiles define whether names are decorated, mangled, or exported verbatim.

Type-shape classes

Values that may cross a boundary are classified into type-shape classes so that each profile can map them to concrete machine types:

• Scalar — fixed-width integers and enumerations mapped to a profile’s integer rules.
• Opaque handle — an address-sized token with no Beskid-defined layout on the foreign side beyond “passed by value or by pointer per profile”.
• Buffer — length-associated byte or element ranges; ownership (borrow vs transfer) is a separate contract field.
• String-like — bounded UTF-8 or implementation-defined encoding; must align with runtime string ABI where shared with the Beskid runtime (BeskidStr-class layouts in implementation).
• Never — no return across the boundary (divergence); profiles map this to platform unwind or trap semantics.

Profiles may forbid certain shapes at the boundary even if they exist in Beskid source.

Call-shape classes

A call shape describes parameters and return as a flat list of type-shapes plus calling convention metadata. Interop.Contracts requires that every lowering to a foreign call be expressible as a call shape; profiles attach concrete ABIs (for example System V on a tier-1 host).

Boundary invariants

Regardless of profile, these invariants apply unless a profile explicitly documents a narrower guarantee:

1. No silent re-entrancy — foreign code must not assume Beskid runtime locks unless the profile documents re-entrancy classes.
2. Panic isolation — which side may catch or translate panics is profile-defined; the abstract contract requires the mapping to be explicit.
3. ABI version gate — runtimes and artifacts declare a compatible runtime ABI version; mismatches are hard errors at load or link time (see implementation anchors on the parent hub).

For C-oriented user libraries, see C ABI profile. For the embedding Rust runtime surface, see Rust ABI profile.