lib-stdio

lib-stdio provides caller-buffered, lossless ordered streams and explicit standard input, output, and error endpoint roles for native EriX programs.

EriX is a clean-room, capability-based microkernel operating system written entirely in Rust.

See:

• docs for system architecture and the technical manual
• lib-ipc for stream wire bodies
• lib-tty for PTY control semantics

Purpose of This Repository

This repository standardizes native byte-stream behavior without hiding transport, allocation, or authority. Callers provide retention storage, response storage, endpoint slots, and operation scheduling.

The maintained responsibilities are:

• define exact stdin-reader, stdout-writer, and stderr-writer roles
• retain ordered bytes in a caller-provided circular buffer
• separate typed owner metadata from exact deployment byte regions when a service manages many streams
• report partial writes and receiver-sized reads with absolute offsets
• preview retained owner bytes without advancing progress so downstream lossless capacity can be reserved before source consumption
• apply backpressure without dropping data or inventing retry ceilings
• expose EOF, orderly half-close, cancellation, peer failure, and cleanup state
• erase retained bytes on cancellation and peer failure
• adapt validated lib-ipc stream bodies to the semantic state machine
• validate correlated client replies and forward-only shared-reader and shared-writer cursor resynchronization without performing transport
• validate complete and incremental UTF-8 without replacement or truncation

Clean-Room Policy

EriX follows a strict clean-room philosophy:

• No external source code may be copied.
• No external Rust crates are allowed.
• No code generation tools that embed third-party code.
• All code must be authored within the project.

Violations will result in rejection of the contribution.

License

All EriX repositories are licensed under the ISC License.

Development Model

The crate is no_std, forbids unsafe code, and denies missing public documentation. A StreamBuffer uses the complete caller-provided slice as a ring. Capacity controls only current backpressure; total stream progress is an independent u64 offset and has no private logical-size limit.

Stream endpoints are explicitly delegated capabilities. EndpointSlot records where a caller expects one, but the numeric slot is not proof of authority. Messages never carry capabilities, and this crate never discovers or invokes an endpoint.

Status

Implemented:

• lossless circular buffering with wraparound
• partial writes, receiver-sized reads, offsets, backpressure, and EOF
• repeatable non-consuming owner preview over the exact retained prefix
• orderly producer/consumer close, cancellation, and peer-failure state
• terminal-state byte erasure and visible cleanup status
• stream wire request/response adapters
• detached StreamState records bound to the identity and length of their exact caller-owned byte regions
• allocation-free reader/writer cursors with immutable prepared calls, correlation checks, partial progress, orderly half-close, and forward-only shared-alias resynchronization for sequential readers and concurrent writers
• range-local EOF handling that keeps a seekable read-write endpoint live while preserving the stronger closed-producer EOF rule in StreamBuffer
• byte and incremental UTF-8 helpers
• standard stream role and slot validation

Governance Principles

lib-stdio governs stream semantics, not endpoint ownership or scheduling.

• No byte is silently dropped, replaced, reordered, or duplicated.
• Progress offsets make accepted retries unambiguous.
• Client cursors move only after a correlated reply proves canonical progress; a stale shared writer may move forward to the owner's cursor but never regress or imply that its unaccepted offer was committed.
• Terminal cleanup state remains visible until the owning service destroys it.
• Caller storage and transport envelopes determine capacity.
• Git dependencies use full 40-character commit rev pins. Integration source revisions and CI caches preserve those identities, with no branch-head or synthetic-commit substitution.

Library Boundaries

• The crate holds no endpoint, allocator, filesystem, process, console, or discovery authority.
• It performs no syscall, allocation, polling, or logging.
• PTY modes, session identity, and trusted UI belong to lib-tty and ttyd.

Contact

Development occurs in the EriX organization. Decisions and rationale are recorded in issues and design documents.

Maintainers can be reached at admin@erikinkinen.fi.