FFI and extern — Verification and traceability

Platform spec article

FFI and extern — Verification and traceability

Back to FFI and extern ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (5)

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

   Author-facing extern import rules live on this hub.

   Context

   v0.3 interop split author syntax from execution lowering; articles must not fork MUST tables.

   Decision

   This feature hub must own normative MUST/SHOULD contract text for foreign import. Sibling articles must not redefine hub requirements.

   Consequences

   Execution and tooling specs link here for Extern placement and attribute shape.

   Verification anchors

   /platform-spec/language-meta/interop/ffi-and-extern/; compiler/crates/beskid_analysis contract validation.

   Open full ADR page

2. 0002-extern-contract-level-only Extern on contract declarations only Accepted

   Extern on non-contract declarations is E1510.

   Context

   Bulk C-style surfaces need stable contract blocks; module-level extern was exploratory.

   Decision

   Extern must apply only to contract declarations in v0.3 Standard. The reference compiler must reject Extern on non-contract declarations (E1510).

   Consequences

   Codegen collects ExternImport from contract metadata; mod-level extern remains non-Standard.

   Verification anchors

   compiler/crates/beskid_analysis/src/types/context/context.rs; extern attribute schema.

   Open full ADR page

3. 0003-mod-level-extern-deferred Mod-level Extern not Standard v0.3 Accepted

   Bulk import uses contract blocks with method signatures.

   Context

   Header-style Extern on mod was considered for v0.3 but increases parser and ABI ambiguity.

   Decision

   Extern on mod is not part of v0.3 Standard. Authors must use contract blocks with method signatures ending in ;.

   Consequences

   Future promotion requires a dedicated ADR and profile conformance tests.

   Verification anchors

   /platform-spec/language-meta/interop/ffi-and-extern/ v0.3 scope section.

   Open full ADR page

4. 0004-user-cabi-vs-runtime-rustabi User C ABI separate from runtime Rust exports Accepted

   Tier-1 user libraries use C profile; runtime builtins stay on Rust ABI.

   Context

   Mixing user Extern symbols with BESKID_RUNTIME_ABI_VERSION exports caused namespace and stability risk.

   Decision

   Plane	Rule
   User libraries	C ABI profile + link-time binding
   Runtime embedding	Rust ABI profile / frozen builtin table
   Separation	User Extern must not mutate runtime builtin symbol namespace

   Consequences

   JIT registration and engine policy keep tables disjoint; see profile boundary map on hub.

   Verification anchors

   compiler/crates/beskid_abi; Rust ABI profile; C ABI profile.

   Open full ADR page

5. 0005-repr-c-deferred-v031 repr C records deferred to v0.3.1 Accepted

   CLayout primitive structs are Proposed not v0.3.0 Standard.

   Context

   Arbitrary Beskid record repr(C) needs layout rules beyond interop views.

   Decision

   repr(C) on arbitrary Beskid types is out of scope for v0.3.0 Standard; CLayout primitive structs land in v0.3.1 (Proposed) per C layout types.

   Consequences

   v0.3.0 Standard ships interop view types and link-time import first.

   Verification anchors

   C ABI profile.

   Open full ADR page

Articles

• Contract import syntax How extern contracts declare foreign imports and map to symbols and call shapes. article Standard Reviewed Wed May 20
• Extern attribute schema Normative Extern and per-method interop attributes for contract imports (v0.3). article Standard Reviewed Wed May 20
• FFI and extern — Verification and traceability Conformance strategy for v0.3 FFI spec (fixtures, diagnostics, ignored runtime tests). 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 · 7 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

• Feature
  FFI and extern

  Parent feature hub

• Feature
  Extern import extraction contract

  Compiler lowering contract

Spec-first conformance

v0.3 FFI is normative in platform-spec before the reference compiler fully implements link-time binding, interop views, and export/callback registration.

Toolchains conform to this feature when:

1. Parse and analysis fixtures accept valid v0.3 extern/export syntax and emit expected diagnostics for invalid forms.
2. Codegen extraction tests record stable ExternImport / export metadata from fixtures (where implemented).
3. Runtime e2e tests for link-time foreign calls may be marked #[ignore] with reason v0.3 FFI impl until the engine/CLI path lands.

Traceability matrix

Contract clause	Verification anchor
Extern on contract only	beskid_tests analysis E1510
Abi:"C" + Library	beskid_tests extern validation pipeline
Interop view types	Type fixtures + lowering signature scan (validate_ffi_signature)
Link-time libraries	Manifest contract tests + future CLI import tests
Export / callbacks	Dedicated fixtures under export-and-callbacks hub

Runtime ABI separation

Tests for RUNTIME_EXPORT_SYMBOLS and BESKID_RUNTIME_ABI_VERSION remain under beskid_tests/src/abi/contracts.rs. User FFI layout versioning must not bump the runtime ABI version unless a runtime export symbol changes.

Maintainer rule

Any behavior change in this area must update platform-spec text and add or adjust tests in the same change so the specification stays executable.