@xmachines/docs 1.0.0-beta.19 → 1.0.0-beta.20

package/rfc/streams.md

@@ -0,0 +1,168 @@
+# RFC: Streams
+
+**Status:** Draft  
+**Version:** 1  
+**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](node.md)).
+
+---
+
+## 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
+
+1. Web Streams are the only core abstraction
+2. Everything is a stream or transform
+3. Framing does not change semantics
+4. Durability is implemented as transforms
+5. Ordering is preserved
+6. 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.