Interop.Contracts — Callback call shapes

Platform spec article

Interop.Contracts — Callback call shapes

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
  Export and callbacks

  Registration protocol and export surface

Callback type-shape

A callback is a function pointer plus optional userdata (i64 opaque address in v0.3.0) passed to foreign code. The pointed-to function must use Export or a trampoline symbol documented in callback registration.

Allowed callback signatures use the same primitive and interop-view types as import methods.

Re-entrancy

When foreign code invokes a Beskid export or registered callback:

1. The runtime must enter a documented runtime scope (TLS heap/root/session).
2. Allocation on the Beskid side must follow normal GC rules.
3. Panics must map to trap/abort across the boundary in v0.3 Standard unless a profile documents C-unwind for a specific runtime entrypoint.

Foreign threads invoking Beskid without a host contract are Proposed (v0.3.2+).

Import side: function-pointer parameters

Extern contract methods may declare parameters whose type is a function type with Export ABI in v0.3.0 when the parameter list uses only permitted FFI types. The compiler must verify that the referenced export exists or will be generated.

Tables vs single callbacks

Hosts may register multiple callbacks through a versioned registration table (see export feature). Interop.Contracts only requires that each slot normalize to a flat call shape and stable symbol or trampoline identity.