Interop.Contracts

Platform spec feature

Interop.Contracts

Back to Interop ◎ Open 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

• Area
  Interop

  Parent area

• Feature
  C ABI profile

  C/System V binding of these primitives

• Feature
  Rust ABI profile

  Rust runtime embedding binding

• Feature
  FFI and extern

  Beskid language surface for extern contracts

• Domain
  Language meta

  Parent domain hub

What this feature specifies

Interop.Contracts is the normative, language-agnostic vocabulary for describing how Beskid values and control flow cross a foreign boundary. It does not prescribe a single calling convention; C ABI profile and Rust ABI profile bind these primitives to concrete ABIs and linking models.

This feature specifies: symbol identity, type-shape classes, call-shape classes, ownership and lifetime obligations at the boundary, error and unwind semantics, and a conformance envelope (versioning and forward compatibility) that host runtimes and compilers must honor when claiming compatibility.

Implementation anchors

• Runtime export names and builtin dispatch tables: compiler/crates/beskid_abi/src/symbols.rs, compiler/crates/beskid_abi/src/builtins.rs
• Stable FFI layouts for standard runtime types: compiler/crates/beskid_abi/src/types.rs
• Runtime ABI version constant: compiler/crates/beskid_abi/src/version.rs
• JIT symbol registration and extern import validation: compiler/crates/beskid_engine/src/jit_module.rs, compiler/crates/beskid_engine/src/engine.rs
• Extern import collection and Cranelift calls: compiler/crates/beskid_codegen/src/lowering/lowerable.rs, compiler/crates/beskid_codegen/src/lowering/expressions/call_expression.rs
• ABI contract tests: compiler/crates/beskid_tests/src/abi/contracts.rs

Relationship to language syntax

User-visible [Extern(...)] contract declarations are specified under FFI and extern. That chapter must remain consistent with the abstract contracts here; profile pages add ABI-specific rules.

Decisions

No open decisions. Closed choices are normative ADRs under adr/ (D-LMETA-IC-0001 … D-LMETA-IC-0003); use the reader ADRs tab for detail.

Articles

• Feature hub owns normative contractAbstract boundary vocabulary authority.
• Interop.Contracts — Callback call shapesFunction-pointer parameters and host registration tables for foreign re-entry (v0.3).
• Interop.Contracts — Conformance and versioningABI version gates, forward compatibility, and how artifacts claim Interop.Contracts conformance.
• Interop.Contracts — Core primitivesSymbol identity, type-shape classes, call-shape classes, and boundary invariants shared by all interop profiles.
• Interop.Contracts — Error and unwind semanticsDivergence, traps, and cross-boundary panic policy for FFI (v0.3).
• Interop.Contracts — Language-agnostic mapping rulesHow Beskid declarations map to abstract call shapes and foreign symbols before any C- or Rust-specific lowering.
• Interop.Contracts — Ownership at the boundaryBorrow, transfer, and opaque-handle rules for parameters on foreign call shapes (v0.3).