Runtime-backed corelib surfaces

Platform spec feature

Runtime-backed corelib surfaces

Back to Stability and API shape ◎ Open 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

• Area
  Stability and API shape

  Parent area

• Area
  Runtime

  Runtime exports implement parts of the corelib API surface

• Area
  ABI and host boundary

  Corelib/runtime coupling relies on stable ABI symbol contracts

What this feature specifies

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

• Corelib docs in compiler/corelib/beskid_corelib/docs/ and site/website/src/legacy-bridge/corelib/System/
• Console package: compiler/corelib/packages/console/
• Stream split: System.Input, System.Output, System.Error in compiler/corelib/packages/runtime/src/System/
• Runtime builtins in compiler/crates/beskid_runtime/src/builtins/mod.rs
• ABI builtin specs in compiler/crates/beskid_abi/src/builtins.rs
• Corelib ABI tests in compiler/crates/beskid_tests/src/abi/contracts.rs

Decisions

No open decisions. Closed choices are normative ADRs under adr/ (D-CORE-STAB-0001 … D-CORE-STAB-0004); use the reader ADRs tab for expandable detail.

Articles

• Split System I/O modulesstdin/stdout/stderr are separate runtime-backed modules.
• Contracts and edge casesStability guarantees for runtime-backed corelib APIs.
• Design modelCorelib APIs implemented by runtime builtins and ABI-stable syscall surfaces.
• ExamplesExamples of runtime-backed corelib surfaces.
• FAQ and troubleshootingFAQ for runtime-backed corelib surfaces.
• Flow and algorithmCall path from Beskid corelib methods to runtime builtins.
• Verification and traceabilityVerification for runtime-backed corelib surfaces.