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

package/rfc/run.md

@@ -0,0 +1,159 @@
+# RFC: Run
+
+**Status:** Draft  
+**Version:** 1  
+**Scope:** Machine execution, runs, events, ports, snapshots  
+**Non-goals:** Transport protocols, persistence backends
+
+---
+
+## 1. Purpose
+
+This RFC defines what a **run** is and how machines execute in XMachines.
+
+A run is the sole execution unit.
+
+---
+
+## 2. Core Concepts
+
+### 2.1 Machine
+
+A deterministic state transition system.
+
+---
+
+### 2.2 Run
+
+A **run** is a single execution lineage of a machine.
+
+Properties:
+
+- bound to exactly one machine
+- progresses only by events
+- history is immutable
+
+---
+
+### 2.3 Run Identity
+
+- Run IDs are **opaque and hash-like**
+- The algorithm is **Git OID–compatible**
+- With Git enabled: run ID **is** a commit hash
+- Without Git: the same algorithm is used
+
+Run IDs never change and never require migration.
+
+---
+
+## 3. Lifecycle
+
+### 3.1 Creation
+
+- forked from a machine
+- initial state only
+- no applied events
+
+---
+
+### 3.2 Progression
+
+- events are applied sequentially
+- batches are atomic (all-or-nothing)
+
+---
+
+### 3.3 Completion
+
+- completion is machine-defined
+- runs may remain open indefinitely
+
+---
+
+## 4. Ports
+
+All ports are **Web Streams**.
+
+### `in`
+
+WritableStream of events.  
+The only external mutation mechanism.
+
+### `out`
+
+ReadableStream of outputs emitted by the machine.
+
+### `err`
+
+ReadableStream of errors.
+
+### `snapshot`
+
+ReadableStream of snapshots.
+
+Snapshots are:
+
+- produced internally
+- observable externally
+- **never writable or triggerable externally**
+
+---
+
+## 5. Events
+
+- immutable
+- ordered
+- atomic
+- deterministic
+
+---
+
+## 6. Snapshots
+
+Snapshots are materialized state views.
+
+Rules:
+
+- optional
+- derived from events
+- never replace event history
+- represent latest truth
+
+---
+
+## 7. Determinism
+
+Given the same machine and ordered event sequence,
+a run is deterministic.
+
+---
+
+## 8. Concurrency
+
+- single-writer semantics
+- concurrent senders serialize at `in`
+
+---
+
+## 9. Errors
+
+- errors are observable via `err`
+- fatality is machine-defined
+- errors do not mutate history
+
+---
+
+## 10. Invariants
+
+1. Events are the only mutation mechanism
+2. Snapshots are read-only externally
+3. History is immutable
+4. IDs are Git OID–compatible
+
+---
+
+## 11. Lock statement
+
+> A run is the execution of a machine driven solely by ordered events.  
+> All interaction happens through streams.  
+> This is Run.

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.