Export and callbacks

Platform spec feature

Export and callbacks

Back to Interop ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (4)

1. 0001-hub-authority Feature hub owns normative contract Accepted

   Beskid-to-foreign export authority.

   Context

   Export/callback rules were scattered between runtime and language-meta drafts.

   Decision

   This feature hub must own normative MUST/SHOULD for Beskid export and callback registration (user interop).

   Consequences

   Distinct from runtime builtin exports on Rust ABI profile.

   Verification anchors

   /platform-spec/language-meta/interop/export-and-callbacks/

   Open full ADR page

2. 0002-distinct-from-runtime-builtins User export distinct from runtime builtins Accepted

   Export symbols are generated; builtins stay beskid_abi.

   Context

   Plugin authors confused generated exports with frozen JIT builtin tables.

   Decision

   User export symbols are generated from Beskid compilation units. Frozen runtime builtin exports remain on beskid_abi / Rust ABI profile — export-only work must not change BESKID_RUNTIME_ABI_VERSION.

   Consequences

   Codegen plans export metadata beside ExternImport; trampolines use runtime TLS hooks.

   Verification anchors

   /platform-spec/language-meta/interop/export-and-callbacks/ implementation anchors.

   Open full ADR page

3. 0003-export-pub-functions-v03 Export on pub functions v0.3 Accepted

   Contract vtables as Standard export remain out of scope.

   Context

   Embedding hosts need a minimal stable export surface before full vtable stories.

   Decision

   v0.3 Standard must support [Export] on pub functions with FFI-permitted types. Exporting arbitrary contract vtables as Standard is out of scope for v0.3.

   Consequences

   Callback registration table protocol is Standard; foreign-thread entry without host contract is Proposed v0.3.2+.

   Verification anchors

   export attribute; callback registration.

   Open full ADR page

4. 0004-spec-standard-impl-may-trail Standard spec implementation may trail Accepted

   Normative text can lead reference compiler export support.

   Context

   v0.3 is spec-first for interop; codegen for export is still landing.

   Decision

   This feature is Standard in v0.3 specification. Reference compiler support may trail; verification article records gaps until codegen lands.

   Consequences

   Contributors implement against ADRs without downgrading spec status to Proposed.

   Verification anchors

   verification and traceability.

   Open full ADR page

Articles

• Callback registration Host registration table protocol for Beskid exports invoked from foreign code (v0.3). article Standard Reviewed Sat May 23
• Export attribute Normative Export metadata for pub functions exposed to foreign hosts (v0.3). article Standard Reviewed Wed May 20
• Export and callbacks — Verification and traceability Conformance fixtures for Export and callback registration (v0.3). article Standard Reviewed Sat May 23

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)

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  Interop

  Parent area

• Feature
  FFI and extern

  Import direction

• Feature
  Interop.Contracts

  Callback call shapes

• Feature
  C ABI profile

  Export lowering and linking

• Feature
  Rust ABI profile

  Distinct from runtime builtin exports

What this feature specifies

Export and callbacks defines how Beskid code exposes entrypoints to foreign hosts (plugins, embedders, C drivers) and how function-pointer callbacks are registered for re-entry.

This is user interop, not the frozen runtime builtin table on the Rust ABI profile. Export symbols are generated from Beskid compilation units; runtime builtins remain beskid_abi exports.

v0.3 scope

In scope	Out of scope
[Export] on pub functions with FFI-permitted types	Exporting arbitrary contract vtables as Standard
Callback registration table protocol	Foreign-thread entry without host contract (Proposed v0.3.2+)
Trampolines for GC-safe re-entry	Changing BESKID_RUNTIME_ABI_VERSION for export-only features

Spec is Standard in v0.3; reference compiler support for export lowering, callback registration, and link-time extern resolution is landed on Linux tier-1 (see verification).

Implementation anchors

• Export metadata in compiler/crates/beskid_codegen/src/lowering/expressions/export.rs and compiler/crates/beskid_codegen/src/lowering/context.rs (CodegenArtifact::exports)
• AOT export table and linker export policy: compiler/crates/beskid_aot/src/export_table.rs
• Callback registration and GC-safe trampolines: compiler/crates/beskid_runtime/src/builtins/callback.rs (beskid_register_callbacks, BESKID_USER_FFI_LAYOUT_BAND in compiler/crates/beskid_abi/src/symbols.rs)
• Optional extension of interop_dispatch_* for typed host callbacks (reserved; not user Extern)

Decisions

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

Articles

• Feature hub owns normative contractBeskid-to-foreign export authority.
• Callback registrationHost registration table protocol for Beskid exports invoked from foreign code (v0.3).
• Export attributeNormative Export metadata for pub functions exposed to foreign hosts (v0.3).
• Export and callbacks — Verification and traceabilityConformance fixtures for Export and callback registration (v0.3).