Design model

Platform spec article

Design model

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

• Feature
  C ABI profile

  Link-time user libraries

Purpose

Separate who declares foreign calls, who validates signatures, and who resolves addresses at link or run time. User Extern libraries and runtime builtins follow different policy tracks.

Primary actors

Actor	Role
Front-end / analysis	Parses Extern contracts, emits diagnostics for disallowed types (compiler/crates/beskid_analysis).
Codegen	Lowers approved calls to Cranelift call targets—either runtime builtins or imported extern symbols.
Engine (beskid_engine)	Optional extern_dlopen path: dlopen / dlsym with caches (legacy v0.1; Proposed for new work—prefer link-time C ABI profile).
Runtime builtins	interop_dispatch_unit, interop_dispatch_ptr, interop_dispatch_usize bridge language/runtime interop layouts (beskid_runtime::interop).

Dispatch layers

flowchart TB
  src[Beskid Extern contract]
  ty[Type + ABI validation]
  link[Link-time symbol]
  dyn[Optional dlopen path]
  rt[Runtime interop_dispatch_*]
  src --> ty
  ty --> link
  ty --> dyn
  ty --> rt

Link-time (Standard v0.3): User libraries resolve when producing AOT/JIT artifacts; addresses are fixed before execution.

Dynamic (legacy): Engine loads Library + Symbol strings from Extern(Abi:"C", Library:"…") metadata when extern_dlopen is enabled.

Runtime dispatch: Compiler-generated thunks call interop_dispatch_* for tagged interop values; layout offsets are stable per ABI version (ABI versioning).

Policy boundaries

• Lowering must not embed OS-specific syscall behavior for user externs; syscalls remain in Panic, IO, and syscalls.
• Allowed Cranelift scalar kinds for engine-validated externs: pointer-width integer, i64, i32, i8, f64 (legacy Extern policy v0.1).
• High-level Beskid types in extern signatures must be rejected before codegen.

Related topics

• Flow and algorithm
• Interop.Contracts