Extern dispatch and policy

Platform spec feature

Extern dispatch and policy

Back to ABI and host boundary ◎ Open 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

• Area
  ABI and host boundary

  Parent area

• Area
  Interop

  Extern syntax and semantics feed this runtime dispatch contract

• Feature
  Interop.Contracts

  Abstract symbol and call-shape vocabulary

• Feature
  C ABI profile

  User extern libraries and linking policy

• Feature
  FFI and extern

  Language-level Extern placement

• Area
  Runtime

  Runtime builtins execute approved dispatch targets

What this feature specifies

Extern dispatch and policy defines one operational contract that a newcomer can follow end-to-end: first the model, then execution flow, then strict guarantees, concrete examples, and verification guidance.

Implementation anchors

• Extern parsing and diagnostics in compiler/crates/beskid_analysis/src/beskid.pest and compiler/crates/beskid_analysis/src/analysis/diagnostic_kinds.rs
• ABI builtins definitions in compiler/crates/beskid_abi/src/builtins.rs
• Runtime builtin dispatch in compiler/crates/beskid_runtime/src/builtins/mod.rs
• Panic/syscall bridging in compiler/crates/beskid_runtime/src/builtins/panic_io.rs

Decisions

No open decisions. Closed choices are normative ADRs under adr/ (D-EXEC-ABI-0005, D-EXEC-ABI-0006); use the reader ADRs tab for expandable detail.

Articles

• Link-time extern is the Standard pathUser foreign libraries resolve at link time; dlopen remains legacy.
• Contracts and edge casesMUST rules for extern validation, dynamic linking policy, and interop dispatch layout.
• Design modelExtern resolution layers, runtime dispatch builtins, and host policy boundaries.
• ExamplesDeclaring Extern contracts, dynamic getpid smoke, and interop dispatch usage patterns.
• FAQ and troubleshootingExtern linking failures, dlopen policy, and interop dispatch debugging.
• Flow and algorithmExtern validation, link registration, optional dlopen resolution, and interop dispatch calls.
• Verification and traceabilityEngine extern tests, analysis diagnostics, and interop layout traceability.