Flow and algorithm

Platform spec article

Flow and algorithm

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

Purpose

Step-by-step flow from source Extern to executable call target. Actor diagram: design model.

Compile-time validation

1. Parser records Extern ABI string (typically "C") and optional Library for dynamic profiles.
2. Semantic analysis rejects Beskid-only types in extern parameter/return positions.
3. declare_validated_extern_imports (beskid_codegen) maps each extern to a Cranelift signature; invalid shapes become ExternDeclarationError::InvalidSignature.

JIT link without dynamic externs

1. BeskidJitModule::new() registers runtime builtins only.
2. declare_validated_extern_imports declares extern imports; addresses must be supplied by the linker or pre-resolved extras table before execution.
3. remap_testcase_externals rewrites CLIF external names to registered FuncIds during define.

Optional dynamic resolution (extern_dlopen)

When the engine feature is enabled on Linux x86_64:

1. For each distinct (library, symbol) in the artifact, dlopen(RTLD_LOCAL | RTLD_NOW) once per process.
2. dlsym resolves the symbol; failures include dlerror() text in diagnostics.
3. Process-lifetime caches deduplicate libraries and symbols across compilation units.
4. BeskidJitModule::new_with_symbols passes (name, *const u8) pairs into the JIT builder so Cranelift imports bind to resolved addresses.

When the feature is disabled, artifacts containing externs must fail compilation with an explicit list of unresolved symbols (EXT-001).

Runtime interop dispatch path

1. Lowering passes a tagged interop handle (header + discriminant + payload per interop_layout.rs).
2. Generated code calls interop_dispatch_unit, interop_dispatch_ptr, or interop_dispatch_usize depending on return shape.
3. Runtime reads tag at offset +8 and payload at +16 from the object header (v0.2 baseline; ABI-bumped if layout changes).

Related topics

• Contracts and edge cases
• Examples — getpid smoke pattern