Interop.Contracts — Ownership at the boundary

Platform spec article

Interop.Contracts — Ownership at the boundary

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
  Memory and GC runtime contract

  Pinning and safepoints during foreign calls

Ownership classes

Every parameter on an abstract call shape has an ownership class:

Class	Meaning
Borrow	Caller retains ownership. Foreign code must not store pointers beyond the call unless the contract documents an exception.
Transfer	Caller relinquishes the obligation described by the interop view (for example heap-allocated buffer freed by callee).
Opaque borrow	Address-sized token with no Beskid layout on the foreign side; lifetime is caller-managed.

Default when no modifier is present: Borrow.

GC-managed values

Beskid string and slice (T[]) values must not cross the user FFI boundary as ordinary GC references in v0.3.0 Standard. Authors must use interop view types (see interop view types).

Passing GC pointers to foreign code without a view is undefined behavior.

Optional GcPin (Proposed) would extend a call with a runtime root for the call duration; until standardized, hosts must reject or lower pinned forms only when explicitly implemented.

Safepoints

Every foreign call is a safepoint for the active collector policy. Foreign code must not be assumed to run with a migrated fiber stack unless documented by the execution runtime.

Complex types (deferred)

Nested records, enums with non-trivial representation, and nested arrays inside FFI structs are out of scope for v0.3.0 Standard. They are specified under C layout types for v0.3.1 after basic FFI is in place.