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

package/rfc/broker.md

@@ -0,0 +1,100 @@
+# RFC: Broker
+
+**Status:** Draft  
+**Version:** 1  
+**Scope:** Real-time event transport, consumer coordination, run execution bindings  
+**Non-goals:** Persistence formats, execution semantics
+
+---
+
+## 1. Purpose
+
+This RFC defines how **XMachines runs** are driven by streaming broker backends.
+
+Unlike **Git**, which solves for durability and offline distribution, **Broker** solves for:
+
+- **Liveness:** pushing events to machines in real-time
+- **Coordination:** managing concurrency via consumer groups
+- **Transport:** bridging the gap between topics and run streams
+
+---
+
+## 2. Separation of Concerns
+
+This RFC establishes **Broker** as orthogonal to **Git**.
+
+| Feature          | Git (Persistence)              | Broker (Execution)                    |
+| ---------------- | ------------------------------ | ------------------------------------- |
+| Role             | the ledger (storage)           | the pipe (transport)                  |
+| Model            | pull (fetch/clone)             | push (subscribe)                      |
+| Concurrency      | optimistic locking (branching) | pessimistic locking (consumer groups) |
+| Latency          | batch / high latency           | streaming / sub-second                |
+| Primary Artifact | commit (immutable record)      | message (trigger)                     |
+
+A typical setup uses Broker for the **hot path** (real-time execution) and Git for the **cold path** (archival/audit).
+
+---
+
+## 3. Package Model
+
+The Broker implementation follows the adapter pattern:
+
+- **`@xmachines/broker`** — core interfaces for `BrokerConsumer` and `BrokerProducer`
+- **`@xmachines/broker-kafka`** — Kafka adapter
+- **`@xmachines/broker-redpanda`** — Redpanda adapter
+
+---
+
+## 4. Execution Model
+
+The Broker acts as the **drive mechanism** for a run. It does not replace the run; it feeds it.
+
+### Consumer Binding
+
+- The Broker subscribes to a topic
+- It maps the partition key to a specific **run ID**
+- It instantiates the run (if not already running)
+
+### Stream Piping
+
+**Inbound:**  
+The Broker pipes the topic partition into the run's **in stream** (`WritableStream`)
+
+**Outbound:**  
+The Broker pipes the run's **out stream** (`ReadableStream`) back to a result topic or dead-letter queue
+
+### Backpressure
+
+Because XMachines uses **Web Streams**, backpressure propagates automatically.
+
+If the run is slow to process, the Broker stops fetching from the partition.
+
+---
+
+## 5. Concurrency & Ordering
+
+[Run RFC](run.md) mandates that a run is deterministic given an ordered sequence of events.
+
+**Broker RFC** guarantees this via **partition leasing**:
+
+- A specific run ID is pinned to a specific partition
+- The Broker's consumer group protocol ensures only one worker node holds the lease at any time
+
+This provides the **single writer guarantee** required by the run without needing a distributed lock manager.
+
+---
+
+## 6. Invariants
+
+1. Transport agnostic — the run does not know it is being driven by Kafka
+2. Ordering preserved — messages from a partition are delivered in strict order
+3. At-least-once — offsets are committed only after the run has successfully processed the event
+4. Partition alignment — a single run must never span multiple partitions
+
+---
+
+## 7. Lock statement
+
+> The Broker is the active transport binding that drives XMachines runs from real-time streams.  
+> It handles coordination and delivery, delegating logic to the run and persistence to the configured durability backend.  
+> This is Broker.

package/rfc/browser.md

@@ -0,0 +1,44 @@
+# RFC: Browser
+
+**Status:** Draft  
+**Version:** 1  
+**Scope:** Browser-native interoperability  
+**Non-goals:** Execution, persistence, protocols
+
+---
+
+## 1. Purpose
+
+Defines browser-specific adapters using Web Streams.
+
+---
+
+## 2. Package Model
+
+Alias:
+
+- `@xmachines/browser`
+
+Implementations:
+
+- `browser-dom`
+- `browser-ws`
+- `browser-worker`
+
+Only non-isomorphic APIs receive browser packages.
+
+---
+
+## 3. Invariants
+
+1. Web Streams only
+2. Optional dependency
+3. No persistence
+4. No protocol semantics
+
+---
+
+## 4. Lock statement
+
+> Browser interop is explicit and stream-based.  
+> This is Browser.

package/rfc/cli.md

@@ -0,0 +1,118 @@
+# RFC: CLI
+
+**Status:** Draft  
+**Version:** 1  
+**Scope:** Command-line interface architecture, configuration, and implementation resolution  
+**Non-goals:** Execution semantics, protocol definitions, stream behavior
+
+---
+
+## 1. Purpose
+
+This RFC defines the XMachines CLI architecture.
+
+The CLI provides:
+
+- a human-facing interface to XMachines capabilities
+- configuration and defaults for implementation selection
+- an orchestration layer over RFC-defined capabilities
+
+The CLI does not define behavior. It selects and wires implementations.
+
+---
+
+## 2. Design Principles
+
+1. CLI is optional
+2. CLI never defines semantics
+3. CLI resolves implementations explicitly
+4. Configuration is explicit and persistent
+5. Alias packages expose commands, implementation packages implement behavior
+
+---
+
+## 3. Package Structure
+
+- `@xmachines/cli`
+- built using oclif
+- contains command definitions and shared helpers only
+
+---
+
+## 4. Implementation Resolution
+
+Resolution order:
+
+1. explicit CLI flags
+2. persisted configuration
+3. alias-level defaults (if any)
+4. error
+
+Implementation identifiers are stored as fully qualified package names.
+If no scope is provided, default scope is `@xmachines/`.
+
+---
+
+## 5. Configuration Model
+
+- stored via oclif config
+- user-scoped
+- persistent across upgrades
+
+Defaults follow a first-writer-wins strategy.
+
+---
+
+## 6. Install & Uninstall Hooks
+
+Implementation packages MAY:
+
+- suggest themselves as defaults on install
+- respect `if-not-set` or `quiet` strategies
+- avoid auto-reassignment on uninstall
+
+Uninstall MAY support an explicit purge option to remove config entries.
+
+---
+
+## 7. Feature Enablement
+
+Some capabilities expose features (e.g. REST, Git, MCP).
+
+Rules:
+
+- features map to installed packages
+- enablement is explicit
+- disablement requires explicit flags
+
+---
+
+## 8. Scope Boundaries
+
+The CLI:
+
+- wires components
+- launches servers
+- manages configuration
+
+The CLI does NOT:
+
+- define protocol semantics
+- parse stream payloads
+- implement execution logic
+
+---
+
+## 9. Invariants
+
+1. No implicit defaults
+2. Explicit implementation selection
+3. CLI never defines semantics
+
+---
+
+## 10. Lock statement
+
+> The CLI is an orchestration and configuration layer only.  
+> All semantics live in other RFCs.  
+> This is CLI.

package/rfc/git.md

@@ -0,0 +1,61 @@
+# RFC: Git
+
+**Status:** Draft  
+**Version:** 1  
+**Scope:** Durable streams and distribution  
+**Non-goals:** Runtime execution
+
+---
+
+## 1. Purpose
+
+Git is used as:
+
+- durable stream
+- replication mechanism
+- backup format
+
+Git is optional.
+
+---
+
+## 2. Model
+
+- machines = orphan branches
+- runs = forks
+- events = commits
+- snapshots = commits
+
+History is append-only.
+
+---
+
+## 3. Identity
+
+- commit hashes are canonical IDs
+- same algorithm used with or without Git
+
+---
+
+## 4. SmartHTTP
+
+```
+/<repo>.git/**
+```
+
+Standard Git semantics apply.
+
+---
+
+## 5. Invariants
+
+1. No history rewriting
+2. Git is optional
+3. Append-only semantics
+
+---
+
+## 6. Lock statement
+
+> Git is a durable, append-only stream for XMachines.  
+> This is Git.

package/rfc/mcp.md

@@ -0,0 +1,43 @@
+# RFC: MCP
+
+**Status:** Draft  
+**Version:** 1  
+**Scope:** Model Context Protocol integration  
+**Non-goals:** Transport inference, execution semantics
+
+---
+
+## 1. Purpose
+
+MCP exposes machines as **tools** to external agents.
+
+---
+
+## 2. Implementations
+
+Examples:
+
+- `@xmachines/mcp-http`
+- `@xmachines/mcp-tty`
+
+---
+
+## 3. Server Semantics
+
+- MCP server runs machines
+- transport is irrelevant server-side
+- tools map to machine events
+
+---
+
+## 4. Invariants
+
+1. MCP implementation selection is explicit
+2. MCP is bidirectional
+
+---
+
+## 5. Lock statement
+
+> MCP integrates XMachines with external agents using explicit transports.  
+> This is MCP.

package/rfc/node.md

@@ -0,0 +1,36 @@
+# RFC: Node
+
+**Status:** Draft  
+**Version:** 1  
+**Scope:** Node.js-specific interoperability  
+**Non-goals:** Browser APIs, execution semantics
+
+---
+
+## 1. Purpose
+
+Defines Node-only adapters for non-isomorphic APIs.
+
+---
+
+## 2. Packages
+
+- `node-stream`
+- `node-process`
+
+There is no generic `@xmachines/node`.
+
+---
+
+## 3. Invariants
+
+1. Web Streams are canonical
+2. Node adapters are optional
+3. No protocol semantics
+
+---
+
+## 4. Lock statement
+
+> Node interop is provided by focused adapters only.  
+> This is Node.