Flow and algorithm

Platform spec article

Flow and algorithm

Back to Runtime-backed corelib surfaces ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (4)

1. 0001-split-system-io-modules Split System I/O modules Accepted

   stdin/stdout/stderr are separate runtime-backed modules.

   Context

   Monolithic IO.bd hid syscall direction and descriptor typing.

   Decision

   Rule	Detail
   Surface	System.Input, System.Output, System.Error under packages/runtime
   Non-goal	Monolithic IO.bd for standard streams

   Consequences

   Syscall descriptors stay typed per stream.

   Verification anchors

   packages/runtime/src/System/; stream contract tests.

   Open full ADR page

2. 0002-console-package-separate-shard Console package is a separate shard Accepted

   ANSI and terminal helpers live in corelib_console.

   Context

   Higher console work must not bloat runtime syscall modules.

   Decision

   Rule	Detail
   Package	compiler/corelib/packages/console (corelib_console)
   Runtime	Streams stay in runtime package

   Consequences

   Terminal features document against console package anchors.

   Verification anchors

   packages/console; pckg workspace publish.

   Open full ADR page

3. 0003-abi-version-lockstep ABI version lockstep for builtins Accepted

   Runtime-backed surfaces require coordinated ABI bumps.

   Context

   Builtin shape changes break AOT/JIT link without version alignment.

   Decision

   Rule	Detail
   Version	beskid_runtime_abi_version / BESKID_RUNTIME_ABI_VERSION must match
   Change	Requires beskid_abi, runtime, and corelib updates together

   Consequences

   Link failures surface at build time, not lazy dlopen.

   Verification anchors

   beskid_abi/src/builtins.rs; abi/contracts.rs.

   Open full ADR page

4. 0004-pure-beskid-out-of-scope Pure Beskid modules out of scope Accepted

   Foundation-style modules without builtins follow normal lowering.

   Context

   Not every corelib module is runtime-backed.

   Decision

   Rule	Detail
   In scope	Builtin/syscall facades documented here
   Out of scope	Pure Beskid foundation modules

   Consequences

   This feature does not duplicate language-meta semantics for pure libraries.

   Verification anchors

   foundation package compile tests.

   Open full ADR page

Articles

• Contracts and edge cases Stability guarantees for runtime-backed corelib APIs. article Standard
• Design model Corelib APIs implemented by runtime builtins and ABI-stable syscall surfaces. article Standard
• Examples Examples of runtime-backed corelib surfaces. article Standard
• FAQ and troubleshooting FAQ for runtime-backed corelib surfaces. article Standard
• Flow and algorithm Call path from Beskid corelib methods to runtime builtins. article Standard
• Verification and traceability Verification for runtime-backed corelib surfaces. article Standard

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
  Runtime-backed corelib surfaces

  Parent feature hub

Call lowering flow

sequenceDiagram
  participant Src as Beskid method
  participant CG as codegen
  participant RT as beskid_runtime
  participant OS as host OS
  Src->>CG: resolve builtin id
  CG->>RT: extern C-unwind call
  RT->>OS: syscall_read/write (I/O)
  RT-->>Src: managed return / GC handles

1. Semantic resolution binds call to a known runtime builtin or inlined fast path.
2. Codegen emits ABI-stable symbol reference from beskid_abi tables.
3. JIT (beskid_engine) or AOT (beskid_aot) links runtime object providing the symbol.
4. Builtin implementation enforces GC safepoints, panic translation, and I/O error mapping.

I/O split algorithm

• System.Input — read paths funnel through syscall_read helpers in panic_io module.
• System.Output / System.Error — write paths use syscall_write with distinct handles where the host distinguishes stderr.
• Console package — layers formatting/ANSI on top without redefining syscall contracts.

Fiber and GC interaction

Fiber builtins (fiber_spawn, fiber_yield, …) and GC builtins (gc_collect, write barriers) share the same registration hub (hub module). Corelib wrappers must not reimplement scheduler logic in Beskid-only code paths for normative behavior.

Verification flow

ABI contract tests compare declared signatures against runtime exports before release tags ship.

Tests

compiler/crates/beskid_tests/src/abi/contracts.rs is the primary gate; extend when adding builtin surfaces.