Contracts and edge cases

Platform spec article

Contracts and edge cases

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

• Area
  ABI and host boundary

  Normative ABI versioning

Contracts

• ABI version lockstep — Host, runtime, and AOT artifacts must agree on beskid_runtime_abi_version for a given toolchain release.
• No duplicate syscall paths — Console/ANSI must not bypass System.* stream contracts for primitive read/write.
• Panic across unwind — Builtin entry points use extern "C-unwind"; Beskid panics map through panic_io without corrupting GC state.
• Documented nullability — Beskid wrappers must mirror ABI nullability for handles passed into GC-aware builtins.

Edge cases

Case	Behavior
Missing runtime on link	AOT/JIT link fails at build time, not lazy runtime dlopen
Platform without ANSI	Console package degrades per terminal capability probes
Embedded hosts without stderr	System.Error may alias output; documented per execution profile
Metrics feature gate	beskid_runtime metrics builtins compile only with metrics feature

Non-runtime corelib

Pure Beskid modules in foundation and similar packages are out of scope here—they follow standard IL lowering without builtin tables.