Contracts and edge cases

Platform spec article

Contracts and edge cases

Back to Extern dispatch and policy ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0005-link-time-extern-standard Link-time extern is the Standard path Accepted

   User foreign libraries resolve at link time; dlopen remains legacy.

   Context

   Early engine prototypes resolved Extern(Library:…) via dlopen/dlsym. That complicates reproducible AOT artifacts and blurs security review of loaded code.

   Decision

   Track	Status
   Link-time	Standard for v0.3 — addresses fixed before execution via C ABI profile
   Dynamic extern_dlopen	Proposed / legacy — engine feature only; not required for reference CLI
   Validation	High-level Beskid types in extern signatures must be rejected before codegen
   Syscalls	User externs must not embed OS syscall sequences — see Panic, IO, and syscalls

   Consequences

   New platform work documents link-time flows first. Dynamic resolution stays gated behind extern_dlopen in beskid_engine.

   Verification anchors

   compiler/crates/beskid_analysis extern validation; beskid_engine link paths.

   Open full ADR page

2. 0006-interop-dispatch-builtins Runtime interop_dispatch builtins for tagged values Accepted

   Compiler thunks call stable dispatch entrypoints for language/runtime interop layouts.

   Context

   Tagged interop values need runtime-known layout offsets. Per-site custom trampolines would fork ABI stability.

   Decision

   Builtin family	Role
   interop_dispatch_unit	Unit-tagged dispatch
   interop_dispatch_ptr	Pointer payloads
   interop_dispatch_usize	Scalar bridge
   Layout stability	Offsets are versioned with ABI versioning
   Implementation	beskid_runtime::interop exports registered in BUILTIN_SPECS

   Lowering must route approved tagged calls through these builtins rather than ad-hoc host calls.

   Consequences

   Interop layout changes require ABI bump or additive symbol policy per D-EXEC-ABI-0002.

   Verification anchors

   compiler/crates/beskid_runtime/src/interop/; interop lowering tests.

   Open full ADR page

Articles

• Contracts and edge cases MUST rules for extern validation, dynamic linking policy, and interop dispatch layout. article Standard Reviewed Fri May 22
• Design model Extern resolution layers, runtime dispatch builtins, and host policy boundaries. article Standard Reviewed Fri May 22
• Examples Declaring Extern contracts, dynamic getpid smoke, and interop dispatch usage patterns. article Standard Reviewed Fri May 22
• FAQ and troubleshooting Extern linking failures, dlopen policy, and interop dispatch debugging. article Standard Reviewed Fri May 22
• Flow and algorithm Extern validation, link registration, optional dlopen resolution, and interop dispatch calls. article Standard Reviewed Fri May 22
• Verification and traceability Engine extern tests, analysis diagnostics, and interop layout traceability. 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
  Extern dispatch and policy

  Parent feature hub

Normative requirements

ID	Requirement
EXT-001	If dynamic extern resolution is disabled, compilation must fail when the artifact references extern symbols, listing each unresolved import.
EXT-002	Engine-validated extern signatures must use only approved scalar Cranelift kinds; all other types must be rejected.
EXT-003	Dynamic loading on Linux must use RTLD_LOCAL | RTLD_NOW; error paths must surface dlerror() text.
EXT-004	(library, symbol) resolution must be cached for process lifetime without double dlopen of the same library path.
EXT-005	interop_dispatch_* builtins must follow layouts documented in beskid_runtime interop_layout.rs for the active ABI version.
EXT-006	User-facing docs must not expose internal __interop_* mangling; stable names are interop_dispatch_* only.

Edge cases

Case	Behavior
Missing shared library	Compile/link failure with library path in diagnostic when dynamic path enabled
Missing symbol	dlsym failure with symbol + library name
Extern in artifact, feature off	Fail fast (EXT-001); no silent stub addresses
Mixed link-time + dynamic in one workspace	Each artifact follows its manifest/link profile; engine caches are per-process
Non-Linux host with extern_dlopen	Unsupported; compilation or tests should skip with explicit platform guard

SHOULD guidance

• New packages should use link-time C ABI profile rather than extern_dlopen.
• Panic from foreign code should be treated as process-fatal; Beskid does not translate C aborts into Option.

Related topics

• FFI and extern
• Panic, IO, and syscalls