<SpecSection title="What this feature specifies" id="what-this-feature-specifies">
`Core-backed 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. All modules listed here use the `Core.*` prefix per [D-CORE-NS-0001](/platform-spec/core-library/stability-and-api-shape/corelib-api-shape/adr/0004-single-core-namespace/).
</SpecSection>

<SpecSection title="Implementation anchors" id="implementation-anchors">
- Corelib docs in `compiler/corelib/beskid_corelib/docs/Core/`
- Console package: `compiler/corelib/packages/console/`
- Stream split: `Core.Input`, `Core.Output`, `Core.Error` in `compiler/corelib/packages/foundation/src/Core/`
- 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`
</SpecSection>

## Decisions
<!-- spec:generate:adr-index -->
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.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [Contracts and edge cases](./articles/contracts-and-edge-cases/)
- [Design model](./articles/design-model/)
- [Examples](./articles/examples/)
- [FAQ and troubleshooting](./articles/faq-and-troubleshooting/)
- [Flow and algorithm](./articles/flow-and-algorithm/)
- [Verification and traceability](./articles/verification-and-traceability/)
<!-- /spec:generate:article-index -->

## Context

Monolithic IO.bd hid syscall direction and descriptor typing.

## Decision

| Rule | Detail |
| --- | --- |
| Surface | `Core.Input`, `Core.Output`, `Core.Error` under `packages/foundation/src/Core/` |
| Non-goal | Monolithic `IO.bd` for standard streams |

## Consequences

Syscall descriptors stay typed per stream.

## Verification anchors

`packages/foundation/src/Core/Input/`, `Output/`, `Error/`; stream contract tests.

## 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.

## 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`.

## 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.

## 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 `Core.*` 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 | `Core.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.

## Purpose

Some corelib modules are thin Beskid facades over **language runtime builtins**, **host-owned dispatch handlers**, and **OS syscalls**. ABI v4 makes that layering explicit: language semantics stay in `beskid_runtime`, while filesystem, environment, process, and TTY behavior are supplied by `beskid_host` in the `std` runtime profile.

Higher-level console and ANSI behavior lives in **`corelib_console`** (`compiler/corelib/packages/console`), not monolithic `IO.bd`.

## Layering

```mermaid
flowchart TB
  App[User code]
  Corelib[Core.* / corelib_console]
  Codegen[beskid_codegen injected __* calls]
  Dispatch[beskid_runtime dispatch router]
  Lang[Language-owned runtime handlers]
  Host[beskid_host handlers]
  OS[Host OS]
  App --> Corelib --> Codegen --> Dispatch
  Dispatch --> Lang
  Dispatch --> Host --> OS
```

| Layer | Examples |
| --- | --- |
| **Beskid surface** | `Core.Input`, `Core.Output`, `Core.Error`, `Core.FS`, `Core.Syscall`, `Core.Time`, environment/process facades |
| **Console package** | ANSI and terminal helpers in `packages/console`; terminal-size fallback when host TTY returns `0` |
| **Language runtime module** | `alloc`, `fiber`, `channel`, `gc`, `panic_io`, clocks, strings, bytes in `beskid_runtime` |
| **Host module** | `fs_*`, `env_*`, `process_*`, `tty_winsize` handlers in `beskid_host` |
| **ABI catalog** | `compiler/runtime_manifest.toml` and generated `beskid_abi` tables pin symbol names, dispatch tags, owners, and signatures |

## Runtime profiles

| Profile | Surface behavior |
| --- | --- |
| `std` | Links `beskid_runtime` plus `beskid_host`; host-backed corelib surfaces are registered before user entry. |
| `minimal` | Links `beskid_runtime` only; language-owned surfaces work, while host-backed surfaces trap if called. |

`Runtime.Init` is a no-op stub in ABI v4. The host/link layer owns host registration through `beskid_host_register_all()`.

## 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:

- `compiler/runtime_manifest.toml`
- `beskid_abi` generated specs
- `beskid_runtime` language-owned implementations
- `beskid_host` host-owned 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** and which native owner supplies them.

## Documentation sources

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

## Implementation anchors

- Streams and Core facades: `compiler/corelib/packages/foundation/src/Core/`
- Console: `compiler/corelib/packages/console/`
- Language runtime: `compiler/crates/beskid_runtime/src/builtins/`
- Host runtime: `compiler/crates/beskid_host/`
- ABI manifest: `compiler/runtime_manifest.toml`
- ABI generated tables: `compiler/crates/beskid_abi/src/generated/`
- Tests: `compiler/crates/beskid_tests/src/abi/contracts.rs`

## Stdout write path

Application code calls `Core.Output` helpers → codegen targets `syscall_write` builtin → host writes fd 1. Errors surface as Beskid exceptions per runtime mapping.

## Fiber spawn

`fiber_spawn` builtin allocates fiber control block in runtime, registers GC roots, and schedules on runtime thread pool—corelib exposes typed wrappers only.

## ABI contract test snippet

Tests in `abi/contracts.rs` assert each exported builtin symbol referenced by codegen exists in the linked runtime library for the target triple.

## Separating console concerns

ANSI coloring and terminal size queries belong in **`corelib_console`** package dependencies on `Core.*` streams, keeping syscall surface minimal.

## Link error for missing builtin symbol

Rebuild with matching `beskid` and runtime objects; verify `BESKID_RUNTIME_ABI_VERSION` alignment between CLI and cached AOT artifacts.

## I/O works in JIT but not AOT

Confirm AOT link includes `beskid_runtime` with the same feature set (e.g., platform I/O stubs).

## Should I add syscalls to `IO.bd`?

No—split across `Core.Input` / `Core.Output` / `Core.Error` and keep ANSI in `corelib_console`.

## Where is the authoritative builtin list?

`compiler/crates/beskid_abi/src/builtins.rs` plus re-exports in `beskid_runtime/src/builtins/mod.rs`.

## Doc drift vs implementation

Update Beskid sources and `compiler/corelib/beskid_corelib/docs/` together; run `beskid doc` before publishing packages with API browser content.

## Call lowering flow

```mermaid
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

- **`Core.Input`** — read paths funnel through `syscall_read` helpers in `panic_io` module.
- **`Core.Output` / `Core.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.

## Automated gates

| Gate | Location |
| --- | --- |
| ABI ↔ runtime export parity | `compiler/crates/beskid_tests/src/abi/contracts.rs` |
| AOT ABI version constant | `beskid_aot` + CLI build tests |
| Corelib compile smoke | `beskid_tests/src/projects/corelib/compile.rs` |

## Traceability matrix

| Surface area | Spec article | Code |
| --- | --- | --- |
| Syscall I/O | This feature + console-io-streams | `panic_io`, `System.*` |
| Fibers / GC | execution/runtime features | `fiber`, `gc` modules |
| Console ANSI | terminal-and-console area | `packages/console` |

## Release process

Runtime ABI bumps require: update `beskid_abi`, runtime implementations, ABI tests, platform-spec execution pages, and this feature bundle in one toolchain release.