Interop.Contracts — Language-agnostic mapping rules

Platform spec article

Interop.Contracts — Language-agnostic mapping rules

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

Declaration to contract

Beskid surfaces foreign entrypoints through contract declarations annotated for interop (see FFI and extern). At the Interop.Contracts layer, each contract method contributes:

• A logical symbol derived from the contract’s extern metadata, optional per-method Symbol override, or the method’s foreign name when no override is present.
• A call shape derived from Beskid parameter and result types using the type-shape rules on the parent hub’s core primitives article.

The compiler must reject declarations that cannot be lowered to any supported profile’s call shape without undefined behavior.

Multiple profiles

The same abstract call shape may admit more than one profile lowering in the future. Interop.Contracts defines the shared normalization step; C ABI profile and Rust ABI profile document which shapes each profile accepts in the current toolchain.

Builtin vs user foreign boundary

Calls to runtime builtins (allocation, syscalls, internal dispatch helpers) use the same abstract machinery but are not user-authored Extern contracts. They are governed by the runtime ABI and syscall ownership documents under /execution/runtime/; those surfaces must remain consistent with the symbol tables in beskid_abi.