lib-tty

lib-tty defines allocation-free PTY lifecycle, terminal mode, ordinary event, and trusted-control contracts for native EriX programs and services.

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 terminal wire bodies
• lib-stdio for ordered byte-stream semantics

Purpose of This Repository

This repository separates PTY state and control from the byte streams carried by PTY endpoints. Callers provide event storage, name endpoint roles explicitly, and preserve the authenticated route used for trusted control.

The maintained responsibilities are:

• validate terminal modes and cell or pixel dimensions
• model master and slave lifecycle with monotonic state generations
• enforce role-specific mode, resize, close, and hangup transitions
• define the exact master-to-slave input and slave-to-master output roles
• retain ordinary or trusted events in caller-provided lossless queues
• expose explicit queue backpressure and replay-resistant cursors
• adapt ordinary PTY state and events to exact receipt-free lib-ipc terminal bodies with canonical signal identities and consecutive cursors
• correlate trusted-control responses with request, session, and cursor identity
• keep trusted-control types structurally separate from ordinary PTY events

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. PtyPair owns semantic state but no capability; the service that holds authenticated master or slave endpoints supplies the requesting role.

EventQueue uses the complete caller-provided slice as bounded retention. A full queue returns the event unchanged, allowing the producer to apply backpressure without data loss. Queue capacity is deployment policy, not a private protocol limit.

Status

Implemented:

• validated interactive and raw terminal modes
• master/slave role-specific mode and resize operations
• endpoint close, terminal hangup, and monotonic state snapshots
• lossless caller-buffered event queues with exact cursors
• ordinary PTY wire event and state adapters
• exact resize, mode-change, hangup, and interrupt wire values using the shared signal catalog rather than host-native codes or duplicated state payloads
• direction-specific PTY input and output stream roles
• trusted session-control response correlation
• structural separation of ordinary and trusted event paths

Governance Principles

lib-tty governs PTY semantics, not endpoint ownership, display routing, input policy, or process scheduling.

• A role value is accepted only from a caller that already authenticated its endpoint route.
• Ordinary bytes and events cannot produce a trusted-control value.
• Ordinary event values are descriptive only: they convey canonical signals, state generations, or hangup reasons and cannot select a process or job.
• Trusted decisions remain tied to a nonzero authenticated session, exact request, and monotonic cursor.
• Full caller storage causes explicit backpressure, never silent event loss.
• 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, VFS, input, display, process, or discovery authority.
• It performs no syscall, allocation, polling, or logging.
• Stream bytes belong to lib-stdio; endpoint and trusted-route ownership belong to ttyd and its service peers.

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.