Design model

Platform spec article

Design model

Back to Console I/O streams ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (3)

1. 0010-split-stream-modules Split stream modules per fd Accepted

   stdin/stdout/stderr use separate System modules.

   Context

   A single Console IO type obscures direction and syscall descriptors.

   Decision

   Rule	Detail
   Modules	System.Input, System.Output, System.Error
   Forbidden	Monolithic console IO type for standard streams

   Consequences

   Each module binds one StandardStream descriptor; cross-stream APIs stay separate.

   Verification anchors

   packages/runtime/src/System/Input.bd, Output.bd, Error.bd.

   Open full ADR page

2. 0011-write-panic-read-result Write panics; read returns Result Accepted

   Syscall write failures panic; reads surface Result.

   Context

   v1 write helpers are infallible at the type level; read paths need explicit error handling.

   Decision

   Rule	Detail
   Write	Write / WriteLine must panic on WriteWith failure
   Read	Read / ReadLine return Result<string, SyscallError>

   Consequences

   Diagnostics for write failures use fixed panic strings; callers cannot catch write errors in Beskid v1.

   Verification anchors

   Corelib stream tests; syscall integration in beskid_runtime.

   Open full ADR page

3. 0012-writeline-unix-lf WriteLine emits Unix LF Accepted

   WriteLine appends a single LF byte sequence.

   Context

   Cross-platform hosts may translate line endings below the Beskid API.

   Decision

   Rule	Detail
   Ending	WriteLine must append \n only
   Windows	Host/platform layer may translate later without API change

   Consequences

   Authors see consistent Beskid source semantics; CRLF is not encoded in corelib strings.

   Verification anchors

   Output.bd / Error.bd tests; platform IO docs.

   Open full ADR page

Articles

• Contracts and edge cases MUST rules for standard stream reads, writes, and error handling. article Standard Reviewed Thu May 21
• Design model Stream module boundaries and syscall descriptor model for standard I/O. article Standard Reviewed Thu May 21
• Examples Standard stream read and write usage patterns. article Standard Reviewed Thu May 21
• Flow and algorithm Read and write algorithms for standard stream helpers. article Standard Reviewed Thu May 21
• Verification and traceability Runtime syscall and corelib anchors for standard stream I/O. article Standard Reviewed Thu May 21

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 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
  Console I/O streams

  Parent feature hub

• Feature
  Panic, IO, and syscalls

  Builtin read/write implementation

Purpose

Define how syscall-backed standard streams are exposed as three Beskid modules (System.Input, System.Output, System.Error) without leaking raw file descriptors or host APIs into user code.

Canonical references

• Feature hub: Console I/O streams
• Runtime syscall surface: Panic, IO, and syscalls
• Normative requirement IDs IO-001–IO-006: contracts and edge cases
• Implementation: compiler/corelib/packages/runtime/src/System/Input.bd, Output.bd, Error.bd, Syscall/

Detailed behavior

Layering

flowchart TB
  app[Application or Console.Format]
  streams[System.Input / Output / Error]
  syscall[System.Syscall ReadWith WriteWith]
  builtin[__syscall_read / __syscall_write]
  app --> streams --> syscall --> builtin

Console I/O streams are thin facades: they select Descriptor::Standard(StandardStream) and translate Beskid string values to UTF-8 byte buffers. Styling, cursor motion, and color live in corelib_console and appear on stdout/stderr only as opaque UTF-8 after ANSI escape model composition.

Descriptor model (normative)

StandardStream	Typical fd	Module	Read	Write
Stdin	0	System.Input	Read, ReadLine → Result	Forbidden
Stdout	1	System.Output	Forbidden	Write, WriteLine
Stderr	2	System.Error	Forbidden	Write, WriteLine

User code must not pass integer fds to ReadWith / WriteWith for these helpers. Arbitrary descriptors, sockets, and pipes are out of scope for v1 stream modules.

Syscall routing rules

• Every read must use Syscall.ReadWith with Descriptor::Standard(Stdin) only (IO-001).
• Every stdout write must use Descriptor::Standard(Stdout); stderr must use Stderr (IO-002).
• WriteLine(text) must perform Write(text) then Write("\n") as LF only—no implicit CRLF in the API (IO-003, decision D-TC-012).
• Write failures must panic with stable messages; read paths must return Result (IO-004, IO-005).
• Stream modules must not parse or validate ANSI sequences (IO-006).

Read vs write asymmetry

Direction	API shape	Rationale
Read	Result<string, SyscallError>	EOF and syscall errors are ordinary control flow
Write	Panic on failure	v1 CLI treats broken stdout as fatal

Relationship to Console facade

Console.FormatLine and control renderers must call System.Output or System.Error after producing a final string. They must not bypass syscall descriptors with host-specific writes. Capability probing runs in Console capabilities, not inside Output.bd.

Verification

• Contract IDs IO-001–IO-006 are enforced by runtime module structure and corelib integration tests that exercise stdin/stdout/stderr through the public API.
• Styled output paths are verified indirectly via console tests that call System.Output after Ansi gating.

Related topics

• Flow and algorithm — step-by-step read/write algorithms
• Examples — ReadLine, WriteLine, and FormatLine usage
• ANSI escape model — escape bytes written through stdout
• Console terminal events — tick loop writes after resize