RFC: Streams (v1)
Status: Draft
Version: v1
Scope: Stream primitives, transforms, framing, durability
Non-goals: Execution semantics, protocols, storage backends
1. Purpose
This RFC defines the stream abstraction used throughout XMachines.
Streams are the only integration boundary between:
- runtimes
- transports
- durability backends
- adapters (REST, MCP, Git, server, browser)
Everything that moves data in XMachines moves through streams.
2. Canonical Stream Type
2.1 Web Streams (authoritative)
All streams in XMachines are defined using WHATWG Web Streams:
ReadableStream<T>WritableStream<T>TransformStream<I, O>
This applies uniformly to:
- browsers
- Node.js
- servers
- workers
No other stream type is part of the core contract.
2.2 Node.js interop (non-core)
Node classic streams (stream.Readable, stream.Writable) are not part of the
contract.
Interop with Node streams is handled by explicit Node adapter packages (see Node RFC).
3. Stream Roles
Streams appear in four distinct roles:
| Role | Type | Meaning |
|---|---|---|
| Input | WritableStream | accepts events |
| Output | ReadableStream | emits outputs |
| Error | ReadableStream | emits errors |
| Snapshot | ReadableStream | emits materialized state |
Roles are never overloaded.
4. Transforms
A transform is a TransformStream that:
- preserves ordering
- preserves backpressure
- does not buffer unbounded data
Transforms are the only mechanism for:
- framing (NDJSON, SSE)
- durability
- filtering
- projection
- multiplexing
5. Framing Transforms
5.1 NDJSON
- newline-delimited JSON
- one logical record per chunk
- ordering preserved
- used for logs and bulk streaming
5.2 SSE
- text-based framing
- browser-friendly
- transform-only
- no protocol semantics
5.3 JSON (single value)
- non-streaming
- used for snapshots and acknowledgements
6. Durability Transforms
Durability is implemented as stream transforms.
Examples:
- Git-backed transforms
- Valkey-backed transforms
- filesystem-backed transforms
Rules:
- append-only
- ordering preserved
- replayable
- never implicit
7. Replay & Projection
Replay is reading from a durable stream and piping it into another stream.
Projection is transforming a stream into another representation without changing semantics.
8. Backpressure & Cancellation
- Backpressure MUST be respected
- Cancellation MUST propagate across transforms
- Closing a stream signals upstream cancellation
9. Invariants
- Web Streams are the only core abstraction
- Everything is a stream or transform
- Framing does not change semantics
- Durability is implemented as transforms
- Ordering is preserved
- Replay is deterministic
10. Lock statement
Streams are the universal integration boundary in XMachines.
All execution, transport, durability, and projection is expressed as streams and transforms.
This is Streams v1.