@xmachines/docs 1.0.0-beta.9 → 1.1.0

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.

package/api/@xmachines/play-actor/interfaces/ViewMetadata.md

@@ -1,17 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor](../README.md) / ViewMetadata
-
-# Interface: ViewMetadata
-
-Defined in: [packages/play-actor/src/abstract-actor.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L87)
-
-View metadata for rendering
-
-Describes the component to be rendered and the props to pass to it.
-Used by PlayRenderer to dynamically render UI based on actor state.
-
-## Properties
-
-| Property                                    | Type                            | Description                                      | Defined in                                                                                                                                                                               |
-| ------------------------------------------- | ------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-component"></a> `component` | `string`                        | Name of the component to render from the catalog | [packages/play-actor/src/abstract-actor.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L89) |
-| <a id="property-props"></a> `props`         | `Record`\<`string`, `unknown`\> | Props to pass to the component                   | [packages/play-actor/src/abstract-actor.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L91) |

package/api/@xmachines/play-catalog/README.md

@@ -1,331 +0,0 @@
-[Documentation](../../README.md) / @xmachines/play-catalog
-
-# @xmachines/play-catalog
-
-**Framework-agnostic UI schema with Zod validation for XMachines Play Architecture**
-
-Type-safe catalog defining component contracts without framework dependencies.
-
-## Overview
-
-`@xmachines/play-catalog` provides `defineCatalog()` and `defineComponents()` for creating type-safe component catalogs with Zod schema validation. It enables business logic to define component props declaratively while maintaining zero framework dependencies — components can be React, Vue, Svelte, or any other framework.
-
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
-
-- **Strict Separation (INV-02):** Business logic has zero framework imports
-- Catalog validates prop types at state entry (build-time + runtime)
-
-## Installation
-
-```bash
-npm install zod@^4.3.6
-npm install @xmachines/play-catalog
-```
-
-## Current Exports
-
-- `defineCatalog`
-- `defineComponents`
-- types: `Catalog`, `InferComponentProps`
-
-**Peer dependencies:**
-
-- `zod` ^4.3.6 — Schema validation (you control the version)
-
-## Quick Start
-
-```typescript
-import { z } from "zod";
-import { defineCatalog } from "@xmachines/play-catalog";
-import type { InferComponentProps } from "@xmachines/play-catalog";
-
-// 1. Define catalog with Zod schemas (business logic layer)
-const catalog = defineCatalog({
-	LoginForm: z.object({
-		error: z.string().optional(),
-	}),
-	Dashboard: z.object({
-		userId: z.string(),
-		username: z.string(),
-		stats: z.object({
-			logins: z.number(),
-			lastLogin: z.date(),
-		}),
-	}),
-});
-
-// 2. TypeScript infers prop types from schemas
-type DashboardProps = InferComponentProps<typeof catalog, "Dashboard">;
-// => { userId: string; username: string; stats: { logins: number; lastLogin: Date } }
-
-// 3. Use in state machine meta.view
-const machine = setup({...}).createMachine({
-	states: {
-		dashboard: {
-			meta: {
-				route: "/dashboard",
-				view: {
-					component: "Dashboard", // Type-checked against catalog
-					props: {
-						userId: "user123",
-						username: "Alice",
-						stats: {
-							logins: 42,
-							lastLogin: new Date(),
-						},
-					},
-				},
-			},
-		},
-	},
-});
-```
-
-## API Reference
-
-### defineCatalog()
-
-Create type-safe component catalog from Zod schemas:
-
-```typescript
-const catalog = defineCatalog({
-	ComponentName: z.object({
-		/* props schema */
-	}),
-});
-```
-
-**Parameters:**
-
-- `schemas: Record<string, ZodObject>` - Map of component names to Zod schemas
-
-**Returns:** Frozen catalog object (immutable in development)
-
-**Example:**
-
-```typescript
-const catalog = defineCatalog({
-	UserProfile: z.object({
-		userId: z.string(),
-		avatar: z.string().url().optional(),
-		bio: z.string().max(500).optional(),
-	}),
-	SettingsForm: z.object({
-		theme: z.enum(["light", "dark"]),
-		notifications: z.boolean(),
-	}),
-});
-```
-
-### InferComponentProps<Catalog, Component>
-
-Utility type extracting prop types from catalog:
-
-```typescript
-type Props = InferComponentProps<typeof catalog, "ComponentName">;
-```
-
-**Example:**
-
-```typescript
-const catalog = defineCatalog({
-	Dashboard: z.object({
-		userId: z.string(),
-		data: z.array(z.number()),
-	}),
-});
-
-type DashboardProps = InferComponentProps<typeof catalog, "Dashboard">;
-// => { userId: string; data: number[] }
-
-// Use in component definition
-function Dashboard(props: DashboardProps) {
-	// props.userId is string
-	// props.data is number[]
-}
-```
-
-### defineComponents()
-
-Validate React component implementations match catalog (compile-time):
-
-```typescript
-const components = defineComponents(catalog, {
-	ComponentName: ComponentImplementation,
-});
-```
-
-**Compile-time validation:**
-
-- Component names must exist in catalog
-- Component prop types must match schema-inferred types
-
-**Example:**
-
-```typescript
-import { defineComponents } from "@xmachines/play-catalog";
-
-const catalog = defineCatalog({
-	LoginForm: z.object({ error: z.string().optional() }),
-	Dashboard: z.object({ userId: z.string() }),
-});
-
-const components = defineComponents(catalog, {
-	LoginForm: ({ error }) => {
-		// error is string | undefined (inferred from schema)
-		return <form>{error && <p>{error}</p>}</form>;
-	},
-	Dashboard: ({ userId }) => {
-		// userId is string (inferred from schema)
-		return <div>User: {userId}</div>;
-	},
-	// @ts-expect-error - "InvalidComponent" not in catalog
-	InvalidComponent: () => <div />,
-});
-```
-
-## Examples
-
-### Progressive Validation
-
-```typescript
-import { z } from "zod";
-import { defineCatalog } from "@xmachines/play-catalog";
-
-// Start simple
-const catalog = defineCatalog({
-	UserCard: z.object({
-		name: z.string(),
-	}),
-});
-
-// Add validation rules
-const enhancedCatalog = defineCatalog({
-	UserCard: z.object({
-		name: z.string().min(1).max(100),
-		email: z.string().email(),
-		age: z.number().int().positive().max(150),
-	}),
-});
-
-// Complex nested schemas
-const advancedCatalog = defineCatalog({
-	UserCard: z.object({
-		name: z.string().min(1),
-		email: z.string().email(),
-		profile: z.object({
-			avatar: z.string().url().optional(),
-			bio: z.string().max(500).optional(),
-			links: z.array(z.string().url()).max(5).optional(),
-		}),
-		preferences: z.object({
-			theme: z.enum(["light", "dark", "auto"]),
-			language: z.string().length(2), // ISO 639-1
-		}),
-	}),
-});
-```
-
-### Machine Integration
-
-```typescript
-import { setup } from "xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
-import { z } from "zod";
-
-const catalog = defineCatalog({
-	LoginForm: z.object({ error: z.string().optional() }),
-	Dashboard: z.object({
-		userId: z.string(),
-		notifications: z.number(),
-	}),
-});
-
-const machine = setup({
-	types: {
-		context: {} as { userId: string; errorMsg: string | null },
-	},
-}).createMachine({
-	initial: "login",
-	context: { userId: "", errorMsg: null },
-	states: {
-		login: {
-			meta: {
-				view: {
-					component: "LoginForm", // Type-checked against catalog
-					props: (context) => ({
-						error: context.errorMsg ?? undefined,
-					}),
-				},
-			},
-			on: {
-				"auth.login": {
-					target: "dashboard",
-					actions: assign({ userId: ({ event }) => event.userId }),
-				},
-			},
-		},
-		dashboard: {
-			meta: {
-				view: {
-					component: "Dashboard",
-					props: (context) => ({
-						userId: context.userId,
-						notifications: 5, // Hardcoded for example
-					}),
-				},
-			},
-		},
-	},
-});
-```
-
-## Architecture
-
-This package enforces **Strict Separation (INV-02)**:
-
-1. **Zero Framework Dependencies:**
-    - Catalog definition has no React/Vue/Svelte imports
-    - Business logic stays framework-agnostic
-    - Same catalog works with any renderer
-
-2. **Validation at State Entry:**
-    - Zod validates props when actor enters state
-    - Invalid props trigger validation error (catchable)
-    - Build-time + runtime safety
-
-3. **Compile-Time Type Safety:**
-    - TypeScript infers prop types from Zod schemas
-    - Component implementations type-checked at compile time
-    - Refactoring propagates through catalog and components
-
-**Benefits:**
-
-- Swap React for Vue without changing business logic
-- Test catalog validation without framework overhead
-- Framework updates don't affect business logic
-
-## Related Packages
-
-- **[@xmachines/play-xstate](../play-xstate/README.md)** - XState adapter using catalogs
-- **[@xmachines/play-react](../play-react/README.md)** - React renderer consuming catalogs
-- **[@xmachines/play](../play/README.md)** - Protocol types
-
-## License
-
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
-
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
-
-## Type Aliases
-
-- [Catalog](type-aliases/Catalog.md)
-- [ComponentsFor](type-aliases/ComponentsFor.md)
-- [InferComponentProps](type-aliases/InferComponentProps.md)
-- [NoExtraKeys](type-aliases/NoExtraKeys.md)
-
-## Functions
-
-- [defineCatalog](functions/defineCatalog.md)
-- [defineComponents](functions/defineComponents.md)