@xmachines/docs 1.0.0-beta.9 → 2.0.0-alpha.1

package/guides/signals.md

@@ -0,0 +1,166 @@
+# Understanding TC39 Signals in XMachines
+
+TC39 Signals are the reactive substrate connecting actors to the outside world in XMachines. This page explains what they are, why XMachines uses them instead of observables or callbacks, and how the three Signal primitives map to distinct roles in the architecture.
+
+After reading this, you will understand why infrastructure never reads state directly from an actor — and what it does instead.
+
+---
+
+## What problem Signals solve
+
+When a state machine transitions, several things may need to react: the URL bar might update, a router might navigate, a renderer might swap views. The naive approach is to let each of those consumers call `actor.getSnapshot()` whenever they feel like it — or to have the actor call back into each consumer via callbacks.
+
+Both approaches break down:
+
+- **Polling** (`getSnapshot()` on a timer or event) is racy: consumers can observe inconsistent intermediate states during a transition sequence.
+- **Callbacks** create direct dependencies between the actor and infrastructure, violating the architectural invariant that business logic must not depend on runtime APIs.
+
+TC39 Signals solve this with a **push–pull model**:
+
+- The actor **pushes** state changes into signals synchronously on every transition.
+- Consumers **pull** computed values lazily from signals — only when they actually need the value.
+- Changes propagate **atomically**, so no consumer ever sees a half-updated state.
+
+This model is sometimes called _glitch-free reactivity_: intermediate invalid states never escape to the environment.
+
+---
+
+## The three Signal primitives
+
+XMachines uses three primitives from the [TC39 Signals proposal](https://github.com/tc39/proposal-signals), accessed via [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md):
+
+### `Signal.State` — writable values
+
+`Signal.State<T>` holds a single mutable value. Only the actor (or code it explicitly delegates to) writes to it. Everything else reads from it.
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+
+const count = new Signal.State(0);
+
+count.set(1); // write
+count.get(); // read → 1
+```
+
+In XMachines, `actor.state` is a `Signal.State<Snapshot>`. The actor updates it on every XState transition. Infrastructure reads it — never writes it.
+
+### `Signal.Computed` — derived values
+
+`Signal.Computed<T>` derives a value from one or more other signals. It recomputes only when its dependencies change — and only when something reads it (lazy evaluation).
+
+```typescript
+const route = new Signal.Computed(() => {
+	const snapshot = actor.state.get();
+	return snapshot.getMeta()?.route ?? null;
+});
+```
+
+In XMachines, `actor.currentRoute` is a `Signal.Computed<string | null>`. Router adapters read it to know which URL to push — they do not compute the route themselves. Route derivation stays in the actor where the business logic lives.
+
+### `Signal.subtle.Watcher` — reactive observation
+
+`Signal.subtle.Watcher` is the low-level primitive for reacting to signal changes. When a watched signal's value changes, the watcher's `notify` callback fires synchronously. You then schedule the actual work with `queueMicrotask` to avoid re-entrant signal reads.
+
+```typescript
+const watcher = new Signal.subtle.Watcher(() => {
+	queueMicrotask(() => {
+		const pending = watcher.getPending();
+		for (const signal of pending) {
+			signal.get(); // re-read to flush
+		}
+		watcher.watch(...pending); // re-arm for next change
+	});
+});
+
+watcher.watch(actor.currentRoute);
+actor.currentRoute.get(); // initial read required to arm the watcher
+```
+
+Watcher notifications are **one-shot**: if you do not call `watch()` again after draining pending signals, you will miss subsequent changes.
+
+Router bridges and renderers use `Signal.subtle.Watcher` internally. For most application code, the [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) helper covers the common case.
+
+---
+
+## [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) — the safe helper
+
+[`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) exports [`watchSignal(signal, onValue)`](../api/@xmachines/play-signals/functions/watchSignal.md) as a lifecycle-safe wrapper around the raw watcher pattern. It returns a cleanup function:
+
+```typescript
+import { watchSignal } from "@xmachines/play-signals";
+
+const stop = watchSignal(actor.currentRoute, (route) => {
+	console.log("Route is now:", route);
+});
+
+// Later — stops observing and prevents use-after-free
+stop();
+```
+
+[`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) handles three subtle correctness concerns for you:
+
+| Concern                | What happens without it                            | How [`watchSignal`](../api/@xmachines/play-signals/functions/watchSignal.md) handles it |
+| ---------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| **Use-after-free**     | Callback fires after component unmounts            | `disposed` flag checked before invoking callback                                        |
+| **Coalescing**         | Rapid synchronous changes cause multiple callbacks | `needsEnqueue` guard — only one microtask queued per synchronous burst                  |
+| **Idempotent cleanup** | Calling the cleanup twice throws                   | Safe to call multiple times                                                             |
+
+Use [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) in framework adapters and application code. Use the raw `Signal.subtle.Watcher` only when building infrastructure that needs to watch multiple signals independently.
+
+---
+
+## Why not observables (RxJS) or event emitters?
+
+The XMachines architecture chose TC39 Signals over observable libraries and event emitters for three reasons:
+
+**1. Standardization.** Signals are a Stage 1 TC39 proposal. They are not tied to any library, bundler, or framework. Isolating the polyfill behind [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) means the entire ecosystem can migrate to native signals when the proposal lands, with a single package update.
+
+**2. Synchronous atomic propagation.** RxJS streams are asynchronous by default. Event emitters fire immediately but serially — a listener registered halfway through a sequence can see inconsistent state. Signals propagate atomically: all computeds update before any watcher fires.
+
+**3. Pull-based evaluation.** Observables push values to every subscriber immediately. Signals are lazy: `Signal.Computed` does not recompute until something reads it. An adapter that is not currently mounted does not pay the cost of computing derived values.
+
+---
+
+## The five Signal invariants in XMachines
+
+The Play RFC defines five invariants that govern how signals are used:
+
+| Invariant                          | What it means in practice                                                                                   |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **INV-01: Actor Authority**        | Only actor code writes to `actor.state`. Never write to it from infrastructure.                             |
+| **INV-04: Passive Infrastructure** | Routers and renderers read signals and forward events. They never decide state transitions.                 |
+| **INV-05: Signal-Only Reactivity** | Cross-boundary communication uses signals. Infrastructure does not poll `getSnapshot()`.                    |
+| **INV-03: No Direct Queries**      | Infrastructure reads from signals, not from snapshot methods, outside of actor code.                        |
+| **INV-02: Strict Separation**      | Business logic (`machine` definition) never imports browser APIs, routing libraries, or framework packages. |
+
+---
+
+## Cleanup is mandatory
+
+Signals do not clean themselves up when they go out of scope. Every watcher you create must be explicitly disposed when the consuming component or adapter unmounts.
+
+- Framework lifecycle hooks (`useEffect` cleanup in React, `onUnmounted` in Vue, `onCleanup` in Solid) must call `unwatch()` or the cleanup returned by [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md).
+- Router bridge `disconnect()` methods must unwatch all signal subscriptions.
+- If you use the raw `Signal.subtle.Watcher` API, pair every `watch()` call with `unwatch()` in teardown.
+
+Failing to clean up watchers causes memory leaks and stale callbacks firing after the consumer is gone.
+
+---
+
+## Summary
+
+| Primitive                                                                  | Role in XMachines                              | Who uses it                        |
+| -------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------- |
+| `Signal.State`                                                             | Actor output: writable snapshot and view state | Actor writes; infrastructure reads |
+| `Signal.Computed`                                                          | Lazy derivations: routes, view specs           | Actor defines; adapters read       |
+| `Signal.subtle.Watcher`                                                    | Low-level reactive observation                 | Framework adapters, router bridges |
+| [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) | Lifecycle-safe single-signal subscription      | Application code, adapter code     |
+
+## See also
+
+- [Understanding the Actor Model](actor-model.md) — why the actor owns all signal writes
+- [Understanding State Machines](state-machines.md) — how state nodes produce the metadata that signals derive
+- [Getting Started](getting-started.md) — hands-on walkthrough using signals to observe an actor
+- [@xmachines/play-signals](../api/@xmachines/play-signals/README.md) — API reference
+- [Play RFC](../rfc/play.md) — architectural specification
+- [TC39 Signals proposal](https://github.com/tc39/proposal-signals) — upstream proposal

package/guides/state-machines.md

@@ -0,0 +1,300 @@
+# Understanding State Machines in XMachines
+
+XMachines uses XState v6 as its state machine engine. This page explains what finite state machines are, how XMachines extends them with routing and view metadata, and why this design eliminates an entire category of bugs common in traditional frontend architecture.
+
+After reading this, you will understand what a machine definition actually encodes — and why state machines are a better unit of business logic than component-level state or ad-hoc if/else trees.
+
+---
+
+## What a finite state machine is
+
+A finite state machine (FSM) is a model of computation with three properties:
+
+1. **It is always in exactly one state** from a finite set of possible states.
+2. **It transitions between states only in response to events**.
+3. **The same event in different states can produce different outcomes** (or no transition at all).
+
+These three properties, taken together, make behavior _deterministic and exhaustive_. You cannot end up in an unlisted state. You cannot receive an event that produces an unspecified outcome — unhandled events are simply ignored.
+
+In traditional component-level state (e.g., boolean flags, `useState` combinations), you typically end up managing _n_ booleans for _n_ conditions. With _n_ booleans, you have 2^n possible combinations — and only a handful of them are actually valid. State machines force you to enumerate only the valid states.
+
+**Example:** A login flow with two booleans (`isLoading`, `isError`) has four combinations: `{false,false}`, `{true,false}`, `{false,true}`, `{true,true}`. The last one — loading and error simultaneously — is impossible in practice, but the code has no way to rule it out. A state machine with states `idle | loading | success | error` makes the impossible unrepresentable.
+
+---
+
+## How XMachines uses XState v6
+
+XMachines wraps XState v6 via [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md). You define machines using XState's `setup().createMachine()` API:
+
+```typescript
+import { setup, types } from "xstate";
+import { emptyEventSchema } from "@xmachines/play-xstate";
+
+const authSetup = setup({
+	schemas: {
+		context: types<{ username: string | null }>(),
+		events: {
+			"auth.login": types<{ username: string }>(),
+			"auth.logout": emptyEventSchema,
+		},
+	},
+});
+
+const authMachine = authSetup.createMachine({
+	id: "auth",
+	initial: "unauthenticated",
+	context: { username: null },
+	states: {
+		unauthenticated: {
+			on: {
+				"auth.login": ({ event }) => ({
+					target: "authenticated",
+					context: { username: event.username },
+				}),
+			},
+		},
+		authenticated: {
+			on: {
+				"auth.logout": () => ({
+					target: "unauthenticated",
+					context: { username: null },
+				}),
+			},
+		},
+	},
+});
+```
+
+Key patterns:
+
+- **Always use `setup({ schemas })`** before `createMachine`. The `types<T>()` helper declares type-only schemas so TypeScript can check that your events, context fields, and transitions are consistent throughout the machine. The `events` schema is a map from event type to payload shape — the payload excludes the `type` field itself.
+- **Transitions are plain functions** that return `{ target, context }`. Context updates are shallow patches returned from the transition function — there is no separate `assign` action.
+- **Event names use lowercase dot-separated namespaces**: `"auth.login"`, `"play.route"`, `"form.submit"`. This convention makes the event log readable and avoids collisions.
+
+---
+
+## State node metadata: routing and views
+
+XMachines extends XState's `meta` field on each state node. This is where routing intent and view structure live:
+
+```typescript
+import { typedSpec } from "@xmachines/play-actor";
+
+const appMachine = setup({/* ... */}).createMachine({
+	id: "app",
+	initial: "home",
+	states: {
+		home: {
+			meta: {
+				route: "/",
+				view: typedSpec({
+					root: "root",
+					elements: {
+						root: { type: "HomePage", props: { title: "Welcome" }, children: [] },
+					},
+				}),
+			},
+		},
+		login: {
+			meta: {
+				route: "/login",
+				view: typedSpec({
+					root: "root",
+					elements: {
+						root: { type: "LoginPage", props: { title: "Sign in" }, children: [] },
+					},
+				}),
+			},
+		},
+		dashboard: {
+			meta: {
+				route: "/dashboard",
+				view: typedSpec({
+					root: "root",
+					elements: {
+						root: { type: "DashboardPage", props: { title: "Overview" }, children: [] },
+					},
+				}),
+			},
+		},
+	},
+});
+```
+
+`meta.route` is a string path. When the machine enters a state, `actor.currentRoute` (a `Signal.Computed`) derives this path and emits it. The router bridge reads it and updates the URL.
+
+`meta.view` is a [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) — a `@xmachines/json-render-core` spec object describing what to render. Use `typedSpec<TContext>(...)` from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) to validate `contextProps` entries at compile time. When the machine enters a state, `actor.currentView` is updated with this spec. The renderer reads it and projects it through framework components.
+
+**The machine is the single source of truth for both routing and views.** There is no separate route configuration file. There is no switch statement in a component deciding what to render based on the URL. The state machine encodes all of that.
+
+---
+
+## [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) — automatic route event wiring
+
+For routing to work, the machine must respond to `play.route` events (sent by router bridges when the user navigates). Writing these transitions by hand is mechanical:
+
+```typescript
+// Without formatPlayRouteTransitions — verbose and repetitive
+states: {
+  home: {
+    on: {
+      "play.route": [
+        ({ event }) => (event.to === "#login" ? { target: "login" } : undefined),
+        ({ event }) => (event.to === "#dashboard" ? { target: "dashboard" } : undefined),
+      ],
+    },
+    meta: { route: "/" },
+  },
+  // ... repeated for every state
+}
+```
+
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) wires this up automatically from the `id` and `meta.route` fields you already have — each routed state gets a native XState v6 `route: {}` config (for `xstate.route` interop and graph tooling), and one root `play.route` forwarder navigates those targets in a single atomic transition, patching `params`/`query` into context:
+
+```typescript
+import { createRoutedMachine, emptyEventSchema } from "@xmachines/play-xstate";
+
+const appSetup = setup({/* ... */});
+
+const appMachine = createRoutedMachine(appSetup)({
+	id: "app",
+	initial: "home",
+	states: {
+		home: { id: "home", meta: { route: "/" } },
+		login: { id: "login", meta: { route: "/login" } },
+		dashboard: { id: "dashboard", meta: { route: "/dashboard" } },
+	},
+});
+```
+
+`createRoutedMachine` has the same signature as the setup's own `createMachine`, so the config keeps full contextual typing. (The underlying transform, [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md), can also be called directly on a config before `createMachine`.) The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
+
+```typescript
+schemas: {
+  context: types<{
+    params: Record<string, string>;
+    query:  Record<string, string>;
+    // ... other context fields
+  }>(),
+  events: {
+    "play.route": playRouteEventSchema, // exported by @xmachines/play-xstate
+    // ... other event schemas
+  },
+  meta: playMetaSchema, // exported by @xmachines/play-xstate — types meta.route / meta.view
+}
+```
+
+---
+
+## Guards — the actor's authority
+
+Guards are the mechanism by which the actor controls whether a transition occurs. They are pure functions of transition arguments (`{ context, event, ... }`) that return a boolean. Named guards declared in `setup({ guards })` are passed to every transition function via `args.guards`:
+
+```typescript
+const authSetup = setup({
+	guards: {
+		isAuthenticated: ({ context }) => context.isAuthenticated,
+		isAdmin: ({ context }) => context.role === "admin",
+	},
+});
+```
+
+A transition function evaluates its guard condition and returns early to reject the transition:
+
+```typescript
+on: {
+	"admin.open": (args) => {
+		if (!args.guards.isAdmin(args)) return;
+		return { target: "adminPanel" };
+	},
+},
+```
+
+When the guard fails, the transition function returns `undefined`, the transition does not occur — the machine stays in its current state and the `play.route` event is discarded. The router bridge then sees that `actor.currentRoute` has not changed and corrects the URL back to the current valid route.
+
+This is the **Actor Authority** invariant in practice: the machine decides, infrastructure adjusts.
+
+XMachines provides guard combinators in [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) for composing complex conditions. Each combinator returns a plain predicate — call it inside a transition function with the transition arguments:
+
+| Function                                                                                            | What it does                            |
+| --------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| [`composeGuards(...guards)`](../api/@xmachines/play-xstate/functions/composeGuards.md)              | AND — all guards must pass              |
+| [`composeGuardsOr(...guards)`](../api/@xmachines/play-xstate/functions/composeGuardsOr.md)          | OR — any guard must pass                |
+| [`negateGuard(guard)`](../api/@xmachines/play-xstate/functions/negateGuard.md)                      | NOT — inverts the guard result          |
+| [`hasContext(key)`](../api/@xmachines/play-xstate/functions/hasContext.md)                          | Checks that a context field is non-null |
+| [`contextFieldMatches(key, value)`](../api/@xmachines/play-xstate/functions/contextFieldMatches.md) | Checks a context field against a value  |
+| [`eventMatches(type)`](../api/@xmachines/play-xstate/functions/eventMatches.md)                     | Checks the event type                   |
+
+---
+
+## Context — persistent state across transitions
+
+Context is the machine's persistent data store. It survives transitions and is updated by the shallow patches transition functions return:
+
+```typescript
+// Context is defined in setup({ schemas })
+schemas: {
+  context: types<{
+    isAuthenticated: boolean;
+    username: string | null;
+    loginAttempts: number;
+  }>(),
+},
+
+// Transitions update context by returning a patch
+on: {
+  "login.failure": ({ context }) => ({
+    context: { loginAttempts: context.loginAttempts + 1 },
+  }),
+},
+```
+
+Context is accessed in guards, transition functions, and when computing routes or views. It is not directly observable from outside the actor via signals — only the derived signals (`state`, `currentRoute`, `currentView`) are public. If you need to expose a context field reactively, add a `Signal.Computed` to the actor that derives from `actor.state`.
+
+---
+
+## Snapshots and restoration
+
+A snapshot is a point-in-time serialisation of the machine's current state and context. XState produces snapshots in a JSON-compatible format:
+
+```typescript
+const snapshot = actor.getSnapshot();
+// snapshot.value → current state node name, e.g. "dashboard"
+// snapshot.context → current context object
+
+// Stop and serialize
+actor.stop();
+const saved = JSON.stringify(snapshot);
+
+// Restore
+const restored = JSON.parse(saved);
+const actor = createPlayer(undefined, { snapshot: restored });
+actor.start();
+// Actor resumes from where it left off
+```
+
+[`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) accepts an optional `restore` argument for this purpose. Restoration is useful for server-side rendering (hydrate with the server's snapshot), session persistence (resume after page reload), and testing (start from a known mid-flow state).
+
+---
+
+## What state machines replace
+
+| Traditional pattern                                   | State machine equivalent                     | Why the machine version is better                           |
+| ----------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------- |
+| Boolean flags (`isLoading`, `isError`)                | Explicit states (`idle \| loading \| error`) | Impossible state combinations are unrepresentable           |
+| Switch on URL path in component                       | `meta.route` on state nodes                  | Routing intent lives with the state that owns it            |
+| `if (user.role === "admin")` scattered in components  | Guards on transitions                        | Auth logic is co-located with the transitions it governs    |
+| `useEffect` on route changes to decide what to render | `meta.view` on state nodes                   | View structure is declared alongside the state that owns it |
+| Shared mutable state across components                | Context + signals                            | Mutations are explicit, traceable, and test-covered         |
+
+---
+
+## See also
+
+- [Understanding the Actor Model](actor-model.md) — how the machine definition becomes a live actor
+- [Understanding TC39 Signals](signals.md) — how the actor's state is observed by infrastructure
+- [Getting Started](getting-started.md) — step-by-step walkthrough building your first machine and actor
+- [Routing Patterns](../examples/routing-patterns.md) — worked examples of `meta.route` and guards
+- [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — full API reference for [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md), guard combinators
+- [XState documentation](https://stately.ai/docs/xstate) — upstream state machine library documentation
+- [Play RFC](../rfc/play.md) — complete architectural specification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "1.0.0-beta.9",
+  "version": "2.0.0-alpha.1",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -15,13 +15,15 @@
   "author": "Mikael Karon <mikael@karon.se>",
   "repository": {
     "type": "git",
-    "url": "https://gitlab.com/xmachin-es/xmachines-js.git",
+    "url": "git+ssh://git@gitlab.com/xmachin-es/xmachines-js.git",
     "directory": "packages/docs"
   },
   "files": [
     "api",
+    "contributing",
     "examples",
     "guides",
+    "rfc",
     "index.js",
     "index.d.ts"
   ],
@@ -32,8 +34,10 @@
       "import": "./index.js"
     },
     "./api/*": "./api/*",
+    "./contributing/*": "./contributing/*",
     "./examples/*": "./examples/*",
-    "./guides/*": "./guides/*"
+    "./guides/*": "./guides/*",
+    "./rfc/*": "./rfc/*"
   },
   "publishConfig": {
     "access": "public"
@@ -43,12 +47,19 @@
     "lint:fix": "oxlint --fix .",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
-    "typedoc": "typedoc"
+    "typedoc": "typedoc",
+    "test": "vitest run",
+    "clean": "rm -rf coverage node_modules/.vite*"
   },
   "devDependencies": {
-    "@xmachines/shared": "^1.0.0-beta.9",
-    "typedoc": "^0.28.17",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@types/node": "^26.1.1",
+    "@xmachines/shared": "2.0.0-alpha.1",
+    "oxfmt": "^0.58.0",
+    "oxlint": "^1.73.0",
+    "typedoc": "^0.28.19",
     "typedoc-plugin-llms-txt": "^0.1.2",
-    "typedoc-plugin-markdown": "^4.11.0"
+    "typedoc-plugin-markdown": "^4.11.0",
+    "vitest": "^4.1.10"
   }
 }

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.