Lossless, caller-buffered byte streams and explicit standard I/O endpoint roles for native EriX programs.
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Erik Inkinen 036acca574
All checks were successful
CI / markdown (push) Successful in 2s
CI / rust (push) Successful in 29s
ci: Merge explicit provider selection policy
Preserve the exact incoming provider-selection feature and current main runtime. Bind the target workflow to actual main providers while retaining the original source checks and component gates.
2026-11-14 22:07:45 +02:00
.github ci: Merge explicit provider selection policy 2026-11-14 22:07:45 +02:00
docs ci: Retain the current stream provider during source selection 2026-11-14 20:08:23 +02:00
src feat: Resynchronize sequential shared readers 2026-08-21 22:19:46 +03:00
.editorconfig Initial commit 2026-08-05 19:46:38 +02:00
.gitignore Initial commit 2026-08-05 19:46:38 +02:00
.markdownlint-cli2.yaml Initial commit 2026-08-05 19:46:38 +02:00
ARCHITECTURE.md ci: Retain the current stream provider during source selection 2026-11-14 20:08:23 +02:00
Cargo.toml ci: Use checked sources and main dependencies for baseline checks 2026-10-30 11:12:23 +02:00
CODE_OF_CONDUCT.md docs: Synchronize shared contribution and review policies 2026-09-12 06:38:19 +03:00
CONTRIBUTING.md build: Pin dependency and CI helper source commits 2026-09-12 07:32:23 +03:00
LICENSE Initial commit 2026-08-05 19:46:38 +02:00
README.md ci: Retain the current stream provider during source selection 2026-11-14 20:08:23 +02:00
ROADMAP.md ci: Retain the current stream provider during source selection 2026-11-14 20:08:23 +02:00
rustfmt.toml Initial commit 2026-08-05 19:46:38 +02:00
SECURITY.md docs: Synchronize shared contribution and review policies 2026-09-12 06:38:19 +03:00

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.
  • CI retains the exact provider revisions used by the checked source consumer. Source declarations follow the shared dependency protocol.

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.