Contract import syntax

Platform spec article

Contract import syntax

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
  Language-agnostic mapping

  Symbol and call-shape normalization

Import contracts

Foreign surface area is declared with contract blocks. Importing methods use signatures that end with ; (no Beskid body), consistent with contract grammar in compiler/crates/beskid_analysis/src/beskid.pest.

Each import method contributes:

1. One logical foreign symbol (method name or Symbol override).
2. One abstract call shape after Interop.Contracts normalization.
3. One ExternImport row at codegen (symbol, abi, library).

Calling imported methods

Beskid code calls foreign entrypoints through the contract type, for example Libc.getpid(). Type checking treats the call as contract dispatch lowered through the C ABI profile.

Implementing contracts in Beskid

Beskid types may implement non-extern contracts in normal source. Extern contracts are import-only in v0.3: methods must not have Beskid bodies on the same contract.

Documentation

/// documentation on the contract and its methods should describe:

• Threading and re-entrancy expectations at the foreign side.
• Ownership of each parameter (borrow vs transfer).
• Error representation (return codes vs out-parameters).

Use @arg only on callable parameters (methods), not on contract-level metadata fields.

Relationship to corelib

Platform packages (for example console and threading) should group foreign entrypoints into small Extern contracts per library (libc, libpthread) rather than scattering raw integer pointer parameters across unrelated APIs.