Design model

Platform spec article

Design model

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

• Area
  Runtime

  Host exports implement builtins

• Area
  ABI and host boundary

  Stable builtin symbol contracts

Purpose

Some corelib modules are thin Beskid facades over runtime builtins and OS syscalls (syscall_read, syscall_write in beskid_runtime). Higher-level console and ANSI behavior lives in corelib_console (compiler/corelib/packages/console), not monolithic IO.bd.

Layering

flowchart TB
  App[User code]
  Corelib[System.* / corelib_console]
  Codegen[beskid_codegen calls]
  RT[beskid_runtime builtins]
  OS[Host syscalls]
  App --> Corelib --> Codegen --> RT --> OS

Layer	Examples
Beskid surface	System.Input, System.Output, System.Error under packages/runtime/src/System/
Console package	ANSI and terminal helpers in packages/console
Runtime module	alloc, fiber, channel, gc, panic_io in beskid_runtime/src/builtins/mod.rs
ABI catalog	beskid_abi/src/builtins.rs pins symbol names and signatures for AOT/JIT

Stability contract

Runtime-backed surfaces must keep ABI version alignment (beskid_runtime_abi_version, BESKID_RUNTIME_ABI_VERSION in AOT requests). Breaking builtin shapes requires coordinated bumps across:

• beskid_abi specs
• beskid_runtime implementations
• corelib Beskid declarations and docs under compiler/corelib/beskid_corelib/docs/

Language semantics (fiber scheduling, GC barriers) remain in language-meta and execution domains; this feature documents which corelib entry points are native.

Documentation sources

Trudoc-compatible prose lives beside Beskid sources in compiler/corelib/. Public site mirrors may appear under site/website/src/legacy-bridge/corelib/System/ for browsing.

Implementation anchors

• Streams: compiler/corelib/packages/runtime/src/System/
• Console: compiler/corelib/packages/console/
• Runtime: compiler/crates/beskid_runtime/src/builtins/
• ABI: compiler/crates/beskid_abi/src/builtins.rs
• Tests: compiler/crates/beskid_tests/src/abi/contracts.rs