@xmachines/docs 1.0.0-beta.18 → 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.

package/api/@xmachines/play-router/functions/crawlMachine.md

@@ -1,92 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / crawlMachine
-
-# Function: crawlMachine()
-
-```ts
-function crawlMachine(machine): StateVisit[];
-```
-
-Defined in: [crawl-machine.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/crawl-machine.ts#L74)
-
-Crawl state machine graph using breadth-first traversal
-
-Visits all state nodes in the machine, including deeply nested states, and returns
-complete list of visits with path and parent information. This enables systematic
-discovery of all states for route extraction and tree building.
-
-**Architectural Context:** Implements **Actor Authority (INV-01)** by extracting
-routing information from the state machine definition rather than external configuration.
-The BFS traversal ensures all nested states are discovered, enabling the Actor to
-define the complete navigation structure through its machine definition.
-
-## Parameters
-
-| Parameter | Type                                                                      | Description                      |
-| --------- | ------------------------------------------------------------------------- | -------------------------------- |
-| `machine` | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine to crawl |
-
-## Returns
-
-[`StateVisit`](../interfaces/StateVisit.md)[]
-
-Array of state visits in breadth-first order
-
-## Examples
-
-Basic machine crawl
-
-```typescript
-import { createMachine } from "xstate";
-import { crawlMachine } from "@xmachines/play-router";
-
-const machine = createMachine({
-	initial: "home",
-	states: {
-		home: {},
-		dashboard: {
-			initial: "overview",
-			states: {
-				overview: {},
-				settings: {},
-			},
-		},
-	},
-});
-
-const visits = crawlMachine(machine);
-// Returns visits for: root, home, dashboard, dashboard.overview, dashboard.settings
-console.log(visits.map((v) => v.path.join(".")));
-// ['', 'home', 'dashboard', 'dashboard.overview', 'dashboard.settings']
-```
-
-Extract state paths and parents
-
-```typescript
-import { crawlMachine } from "@xmachines/play-router";
-
-const visits = crawlMachine(machine);
-visits.forEach((visit) => {
-	console.log({
-		path: visit.path.join(".") || "root",
-		hasParent: !!visit.parent,
-		hasChildren: Object.keys(visit.node.states).length > 0,
-	});
-});
-```
-
-## See
-
-- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
-- [extractRoute](extractRoute.md) for extracting route from individual states
-- [extractMachineRoutes](extractMachineRoutes.md) for complete route extraction
-- [StateVisit](../interfaces/StateVisit.md) for visit structure
-
-## Remarks
-
-**BFS Traversal:** Breadth-first search ensures systematic discovery of all states
-at each nesting level before descending deeper. This produces a predictable ordering
-useful for route tree construction and debugging.
-
-**Path Format:** Paths use array notation (`['dashboard', 'settings']`) which can be
-joined with dots for state IDs (`'dashboard.settings'`) matching XState's hierarchical
-state naming convention.

package/api/@xmachines/play-router/functions/extractRoute.md

@@ -1,45 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / extractRoute
-
-# Function: extractRoute()
-
-```ts
-function extractRoute(node, path, stateMap): RouteInfo | null;
-```
-
-Defined in: [extract-route.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/extract-route.ts#L26)
-
-Extract route information from state node with validation
-
-States with meta.route are "routable" - they can receive play.route events
-(when machine is wrapped with formatPlayRouteTransitions).
-
-## Parameters
-
-| Parameter  | Type                                                                                                                                                                                                                           | Description                                       |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
-| `node`     | [`StateNode`](https://www.jsdocs.io/package/xstate#StateNode)                                                                                                                                                                  | XState StateNode to extract route from            |
-| `path`     | `string`[]                                                                                                                                                                                                                     | State path segments from root                     |
-| `stateMap` | `Map`\<`string`, [`StateNode`](https://www.jsdocs.io/package/xstate#StateNode)\<[`MachineContext`](https://www.jsdocs.io/package/xstate#MachineContext), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\>\> | Map of all state IDs to StateNodes for validation |
-
-## Returns
-
-[`RouteInfo`](../interfaces/RouteInfo.md) \| `null`
-
-RouteInfo if state has meta.route, null otherwise
-
-## Throws
-
-If route path is malformed (missing leading /)
-
-## Throws
-
-If route references non-existent state
-
-## Example
-
-```typescript
-const node = {
-	id: "dashboard",
-	meta: { route: "/dashboard" },
-};
-```

package/api/@xmachines/play-router/interfaces/StateVisit.md

@@ -1,15 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / StateVisit
-
-# Interface: StateVisit
-
-Defined in: [types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L28)
-
-Represents a visit to a state node during graph crawling
-
-## Properties
-
-| Property                              | Type                                                                                                                                                                                                                     | Description                                                    | Defined in                                                                                                            |
-| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-node"></a> `node`     | [`StateNode`](https://www.jsdocs.io/package/xstate#StateNode)                                                                                                                                                            | The state node being visited                                   | [types.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L30) |
-| <a id="property-parent"></a> `parent` | \| [`StateNode`](https://www.jsdocs.io/package/xstate#StateNode)\<[`MachineContext`](https://www.jsdocs.io/package/xstate#MachineContext), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> \| `null` | Parent state node (null for root)                              | [types.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L34) |
-| <a id="property-path"></a> `path`     | `string`[]                                                                                                                                                                                                               | Path from root to this state (e.g., ['dashboard', 'overview']) | [types.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L32) |

package/api/@xmachines/play-tanstack-react-router/variables/extractMachineRoutes.md

@@ -1,64 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / extractMachineRoutes
-
-# Variable: extractMachineRoutes
-
-```ts
-const extractMachineRoutes: (machine) => RouteTree;
-```
-
-Defined in: play-router/dist/extract-routes.d.ts:40
-
-Extract complete route tree from state machine graph
-
-Crawls machine starting from root, visits all state nodes (including nested
-and parallel), extracts meta.route metadata, validates route references,
-and builds hierarchical tree.
-
-## Parameters
-
-| Parameter | Type                                                                      | Description             |
-| --------- | ------------------------------------------------------------------------- | ----------------------- |
-| `machine` | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine |
-
-## Returns
-
-[`RouteTree`](../../play-router/interfaces/RouteTree.md)
-
-Route tree with root, byStateId map, and byPath map
-
-## Throws
-
-If route references non-existent state
-
-## Throws
-
-If route path is malformed (doesn't start with /)
-
-## Throws
-
-If parallel states define conflicting routes
-
-## Example
-
-```typescript
-import { createMachine } from "xstate";
-import { extractMachineRoutes } from "@xmachines/play-router";
-
-const machine = createMachine({
-	initial: "home",
-	states: {
-		home: { id: "home", meta: { route: "/" } },
-		dashboard: {
-			id: "dashboard",
-			meta: { route: "/dashboard" },
-			initial: "overview",
-			states: {
-				overview: { id: "overview", meta: { route: "/overview" } },
-			},
-		},
-	},
-});
-
-const tree = extractMachineRoutes(machine);
-console.log(tree.byPath.get("/dashboard/overview"));
-```

package/api/@xmachines/play-xstate/functions/stateMatches.md

@@ -1,25 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / stateMatches
-
-# Function: stateMatches()
-
-```ts
-function stateMatches<TContext>(stateValue): Guard<TContext, PlayEvent>;
-```
-
-Defined in: [packages/play-xstate/src/guards/helpers.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-xstate/src/guards/helpers.ts#L75)
-
-## Type Parameters
-
-| Type Parameter | Default type                    |
-| -------------- | ------------------------------- |
-| `TContext`     | `Record`\<`string`, `unknown`\> |
-
-## Parameters
-
-| Parameter    | Type     |
-| ------------ | -------- |
-| `stateValue` | `string` |
-
-## Returns
-
-[`Guard`](../type-aliases/Guard.md)\<`TContext`, [`PlayEvent`](../../play/type-aliases/PlayEvent.md)\>