Contracts and edge cases

Platform spec article

Contracts and edge cases

Back to Builtins and symbols ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0003-builtin-specs-sole-clif-source BUILTIN_SPECS is sole Cranelift import source Accepted

   Codegen must not invent alternate calling conventions for runtime builtins.

   Context

   Hand-written Cranelift calls bypass the shared ABI catalog and desynchronize JIT, AOT, and runtime extern "C-unwind" implementations.

   Decision

   Rule	Detail
   Catalog	BUILTIN_SPECS in beskid_abi::builtins is the sole source of Cranelift import signatures (ABI-002)
   Codegen	declare_builtin_imports builds FuncIds only from specs
   Diverging builtins	AbiReturnKind::Never for panic so unreachable blocks are correct
   Parity	Symbol strings in specs must match RUNTIME_EXPORT_SYMBOLS entries (ABI-001)

   Consequences

   New builtins require spec, BUILTIN_SPECS, symbols.rs, and beskid_runtime::builtins in one change set.

   Verification anchors

   compiler/crates/beskid_codegen; compiler/crates/beskid_abi/src/builtins.rs.

   Open full ADR page

2. 0004-runtime-c-unwind-exports Runtime builtins use C-unwind exports Accepted

   no_mangle extern C-unwind symbols implement the stable host surface.

   Context

   Generated code calls runtime entrypoints across JIT relink and AOT link. Rust panics across the boundary must use the platform unwind ABI expected by Cranelift call sites.

   Decision

   Rule	Detail
   Export attribute	Implementations use #[unsafe(no_mangle)] pub extern "C-unwind" in beskid_runtime::builtins
   Registry	RUNTIME_EXPORT_SYMBOLS lists every export the linker/JIT registers
   Layout types	BeskidStr { ptr, len } and BeskidArray { ptr, len, cap } are normative payload headers
   Families	Allocation, GC, fibers, channels, interop dispatch, IO, and panic share one catalog

   Consequences

   Host tooling resolves imports by symbol name + BUILTIN_SPECS signature, not Rust mangling.

   Verification anchors

   compiler/crates/beskid_runtime/src/builtins/mod.rs; compiler/crates/beskid_runtime/src/lib.rs re-exports.

   Open full ADR page

Articles

• Contracts and edge cases MUST rules for builtin signatures, return kinds, and export name stability. article Standard Reviewed Fri May 22
• Design model BuiltinFnSpec catalog, runtime export symbols, and codegen import boundaries. article Standard Reviewed Fri May 22
• Examples Reading BUILTIN_SPECS, mapping symbols to runtime modules, and typical call patterns. article Standard Reviewed Fri May 22
• FAQ and troubleshooting Builtin symbol drift, signature mismatches, and codegen/runtime debugging. article Standard Reviewed Fri May 22
• Flow and algorithm From lowering call sites through BUILTIN_SPECS to runtime C exports. article Standard Reviewed Fri May 22
• Verification and traceability Crate paths and tests that pin builtin specs to runtime exports. article Standard Reviewed Fri May 22

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
  Builtins and symbols

  Parent feature hub

Normative requirements

ID	Requirement
BLT-001	Every BUILTIN_SPECS entry must have exactly one #[unsafe(no_mangle)] export in beskid_runtime with the same symbol string.
BLT-002	RUNTIME_EXPORT_SYMBOLS must be a superset of all builtin symbols plus beskid_runtime_abi_version.
BLT-003	panic and panic_str must use AbiReturnKind::Never; callers must not expect return values.
BLT-004	Pointer parameters must refer to GC-tracked or ABI-documented structs (BeskidStr, headers); null unless the specific builtin documents otherwise.
BLT-005	Fiber join builtins must distinguish status-only (fiber_join_status) vs value (fiber_join_value) per symbol names in symbols.rs.
BLT-006	Channel receive must expose status vs value as separate symbols (channel_receive_status, channel_receive_value) to avoid ambiguous CLIF signatures.

Signature table (selected)

Symbol	Params	Returns
alloc	ptr, ptr (size, type desc)	ptr
str_new	ptr, ptr (data, len)	ptr
syscall_write	i64, ptr (fd, BeskidStr)	i64
gc_write_barrier	ptr, ptr	void
fiber_spawn	(see builtins.rs)	i64 fiber id
interop_dispatch_ptr	ptr	ptr

Full table: compiler/crates/beskid_abi/src/builtins.rs.

Edge cases

Case	Rule
array_new without arrays_backing	Header allocated; ptr field null; array_len still reports logical length
Null BeskidStr in syscall_write	Returns error sentinel (-1) per IO runtime
Test helpers test_bytes_*	Only for compiler tests; not a stable user API
Metrics exports	Gated by metrics feature; not in baseline RUNTIME_EXPORT_SYMBOLS unless enabled at build

Related topics

• Panic, IO, and syscalls
• Channels and synchronization