Rust ABI profile — Boundary and stability

Platform spec article

Rust ABI profile — Boundary and stability

Back to Rust ABI profile ◎ 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

   Runtime embedding exports defer to this hub.

   Context

   Rust runtime exports were documented beside user C extern rules.

   Decision

   This feature hub must own normative MUST/SHOULD for Rust-hosted runtime interop distinct from user C ABI profile libraries.

   Consequences

   Builtin table and ABI version policy stay here; user Extern stays on C profile.

   Verification anchors

   /platform-spec/language-meta/interop/rust-abi-profile/

   Open full ADR page

2. 0002-runtime-c-exports-rust-internal Runtime exposes C-compatible entrypoints Accepted

   Rust-specific choices stay inside the runtime crate boundary.

   Context

   JIT/AOT loaders need stable C symbol names while implementation remains Rust.

   Decision

   The Beskid runtime must expose stable C-compatible entrypoints to loaders. Rust-specific implementation choices must remain inside the runtime crate boundary.

   Consequences

   beskid_abi symbols and unwind bridges document the outward face only.

   Verification anchors

   compiler/crates/beskid_abi; compiler/crates/beskid_runtime.

   Open full ADR page

3. 0003-user-extern-not-rust-crates User Extern not arbitrary Rust crates Accepted

   User foreign code uses C ABI profile until a future spec promotes Rust-native interop.

   Context

   Linking arbitrary rlib targets as user Extern would imply unstable Rust ABI across toolchains.

   Decision

   This profile is not a promise that arbitrary Rust crates can be user Extern targets without shims. User-authored foreign code on the supported path must remain C ABI profile until a future specification promotes additional Rust-native interop.

   Consequences

   Embedding docs steer authors to C contracts + shims for Rust libraries.

   Verification anchors

   /platform-spec/language-meta/interop/rust-abi-profile/ and FFI and extern.

   Open full ADR page

Articles

• Rust ABI profile — Boundary and stability What is stable at the Rust runtime ↔ generated code boundary versus implementation-private Rust types. article Standard Reviewed Fri May 01
• Rust ABI profile — Shims and compatibility strategy How future Rust-native interop would layer on top of C ABI exports without breaking the stable runtime contract. article Proposed Reviewed Fri May 01

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 2 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
  Rust ABI profile

  Parent feature hub

• Feature
  Interop.Contracts

  Shared conformance vocabulary

Stable surface

The normative stable surface for loaders and generated code is the set of exported symbols and their documented C-compatible signatures published through beskid_abi and realized in beskid_runtime. Conformance tests lock this set for a given runtime ABI version (see compiler/crates/beskid_tests/src/abi/contracts.rs).

Implementation-private Rust

Rust types, modules, and internal helpers inside beskid_runtime that are not part of the exported symbol contract may change across compiler releases without a major ABI version bump, provided tests and documented runtime behavior remain compatible.

Unwind and panics

Runtime entrypoints may use extern "C-unwind" (or equivalent) where platform policy requires interoperable unwinding with generated code. The exact mapping is profile-defined and must stay consistent with panic and IO documentation under /execution/runtime/.