@xmachines/docs 7.0.0 → 8.0.0-next.1

package/guides/state-machines.md

@@ -1,6 +1,6 @@
 # State Machines in XMachines
 
-XMachines uses XState v5 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.
+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.
 
@@ -22,17 +22,20 @@ In traditional component-level state (e.g., boolean flags, `useState` combinatio
 
 ---
 
-## How XMachines uses XState v5
+## How XMachines uses XState v6
 
-XMachines wraps XState v5 via [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md). You define machines using XState's `setup().createMachine()` API:
+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 } from "xstate";
+import { setup, types } from "xstate";
 
 const authSetup = setup({
-	types: {
-		context: {} as { username: string | null },
-		events: {} as { type: "auth.login"; username: string } | { type: "auth.logout" },
+	schemas: {
+		context: types<{ username: string | null }>(),
+		events: {
+			"auth.login": types<{ username: string }>(),
+			"auth.logout": types<void>(),
+		},
 	},
 });
 
@@ -43,21 +46,18 @@ const authMachine = authSetup.createMachine({
 	states: {
 		unauthenticated: {
 			on: {
-				"auth.login": {
+				"auth.login": ({ event }) => ({
 					target: "authenticated",
-					actions: authSetup.assign({
-						username: ({ event }) =>
-							event.type === "auth.login" ? event.username : null,
-					}),
-				},
+					context: { username: event.username },
+				}),
 			},
 		},
 		authenticated: {
 			on: {
-				"auth.logout": {
+				"auth.logout": () => ({
 					target: "unauthenticated",
-					actions: authSetup.assign({ username: null }),
-				},
+					context: { username: null },
+				}),
 			},
 		},
 	},
@@ -66,8 +66,8 @@ const authMachine = authSetup.createMachine({
 
 Key patterns:
 
-- **Always use `setup({ types })`** before `createMachine`. The type declarations let TypeScript check that your events, context fields, and actions are consistent throughout the machine.
-- **Use `setup.assign()`**, not the bare `assign` from xstate. This keeps the type checker aware of which context fields the action touches.
+- **Always use `setup({ schemas })`** before `createMachine`. `types<T>()` declares a schema for the type alone. The schemas let TypeScript check that your events, context fields, and transitions are consistent throughout the machine. `events` is a map from the type of each event to its payload.
+- **Return a context patch** from a transition function: `{ context: { username: null } }`. XState 6 merges the patch into the context at the top level, and it has no `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.
 
 ---
@@ -77,10 +77,13 @@ Key patterns:
 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-view";
-import { setup } from "xstate";
+import { typedSpec, type ViewMeta } from "@xmachines/play-view";
+import { setup, types } from "xstate";
 
-const appMachine = setup({/* ... */}).createMachine({
+const appMachine = setup({
+	// XState 6 types the `meta` of each state from this schema.
+	schemas: { meta: types<{ route?: string; view?: ViewMeta }>() },
+}).createMachine({
 	id: "app",
 	initial: "home",
 	states: {
@@ -123,11 +126,11 @@ const appMachine = setup({/* ... */}).createMachine({
 
 `meta.route` is a string path. When the machine enters a state, `actor.currentRoute` (a `ReadonlyAtom`) derives this path and emits it. The router bridge reads it and updates the URL.
 
-`meta.view` is a [`ViewMeta`](../api/@xmachines/play-view/index/interfaces/ViewMeta.md) — a `@xmachines/json-render-core` spec object describing what to render. The actor derives a [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) from it, and that derived spec is what a renderer receives. Use `typedSpec(...)` from [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) to type-check the spec literal at the definition site (XState's `meta` is untyped). When the machine enters a state, `actor.currentView` is updated with the derived spec. The renderer reads it and projects it through framework components.
+`meta.view` is a [`ViewMeta`](../api/@xmachines/play-view/index/interfaces/ViewMeta.md) — a `@xmachines/json-render-core` spec object describing what to render. The actor derives a [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) from it, and that derived spec is what a renderer receives. Use `typedSpec(...)` from [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) to type-check the spec literal at the definition site. XState 6 types `meta` from `schemas.meta` of the machine, and a state cannot declare a `meta` that the schema does not name. When the machine enters a state, `actor.currentView` is updated with the derived spec. The renderer reads it and projects it through framework components.
 
 The machine's whole context is available to every view through the **`/context` projection**: the derived spec's `state` carries `context: <machine context>`. Specs read it with ordinary state expressions — `{ $state: "/context/username" }` in props, `visible` conditions, or `repeat.statePath`. The subtree is **read-only**: context changes only through machine events, and a `$bindState`/`setState` write under `/context` throws. URL data lives at its own paths (`/context/params/…`, `/context/query/…`, written into context by `formatPlayRouteTransitions`), so a URL param can never shadow a machine-owned field. When validating specs with tools like `validateSpec`, validate the **derived** view (`actor.currentView.get()`) — its `state` honestly describes the store contents — not the raw `meta.view`. A context change re-emits the view with the same `viewKey`; providers respond by refreshing `/context` in the live store, not by remounting the UI.
 
-**Give each state its own id, and do not use an array index as an id.** XState does not check that the ids of the states are unique, and a repeated id makes a `#id` target name two states. XMachines keys the route, the view and its store on the id of a state, so two states that share an id share one route entry, one store, and one key. An array index is a whole number from 0 to 2³² − 2 with no leading zero, such as `"42"`. JavaScript lists such a key first in every object that is keyed on ids, so the route of its state loses its place in the branch. [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) writes one warning for each machine that breaks these rules.
+**Give each state its own id, and do not use an array index as an id.** XState 6 throws when two states declare the same explicit id, because a repeated id makes a `#id` target name two states. XMachines keys the route, the view and its store on the id of a state, so two states that share an id share one route entry, one store, and one key. An array index is a whole number from 0 to 2³² − 2 with no leading zero, such as `"42"`. JavaScript lists such a key first in every object that is keyed on ids, so the route of its state loses its place in the branch. [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) writes one warning for each machine that breaks these rules.
 
 **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.
 
@@ -137,7 +140,7 @@ Without outlets, the deepest active state that declares a view wins, and a view
 
 ```typescript
 import { typedSpec, type ViewMeta } from "@xmachines/play-view";
-import { setup } from "xstate";
+import { setup, types } from "xstate";
 
 declare const menuView: ViewMeta, homeView: ViewMeta, searchView: ViewMeta; // your views
 
@@ -154,7 +157,9 @@ const shell = typedSpec({
 	},
 });
 
-const appMachine = setup({/* ... */}).createMachine({
+const appMachine = setup({
+	schemas: { meta: types<{ route?: string; view?: ViewMeta }>() },
+}).createMachine({
 	id: "app",
 	type: "parallel",
 	meta: { view: shell },
@@ -198,7 +203,7 @@ CAUTION: a second routed region moves without its URL. Take a `page` region with
 - A deep link to `/drawer/settings` moves the drawer too, but the actor derives the URL `/` from the `page` region, so the address bar does not keep the path of the drawer.
 - The navigation to `#search` puts the drawer back to `closed`, because the default `handler: "root"` exits and enters every region. `handler: "local"` keeps it.
 
-A URL path has one hierarchy, and it cannot hold the branches of two regions. Keep the other regions unrouted. When the position of such a region must survive a reload or a shared link, write it as a query value of the routed region, for example `/search?drawer=settings`. The generated `play.route` transition assigns the query to `context.query`, the URL carries `context.query`, and your machine moves the region to match the value.
+A URL path has one hierarchy, and it cannot hold the branches of two regions. Keep the other regions unrouted. When the position of such a region must survive a reload or a shared link, write it as a query value of the routed region, for example `/search?drawer=settings`. The generated `play.route` transition writes the query to `context.query`, the URL carries `context.query`, and your machine moves the region to match the value.
 
 ---
 
@@ -211,10 +216,10 @@ For routing to work, the machine must respond to `play.route` events (sent by ro
 states: {
   home: {
     on: {
-      "play.route": [
-        { guard: ({ event }) => event.to === "#login", target: "login" },
-        { guard: ({ event }) => event.to === "#dashboard", target: "dashboard" },
-      ],
+      "play.route": ({ event }) => {
+        if (event.to === "#login") return { target: "login" };
+        if (event.to === "#dashboard") return { target: "dashboard" };
+      },
     },
     meta: { route: "/" },
   },
@@ -226,9 +231,11 @@ states: {
 
 ```typescript
 import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
-import { setup } from "xstate";
+import { setup, types } from "xstate";
 
-const appMachine = setup({/* ... */}).createMachine(
+const appMachine = setup({
+	schemas: { meta: types<{ route?: string }>() },
+}).createMachine(
 	formatPlayRouteTransitions({
 		id: "app",
 		initial: "home",
@@ -241,16 +248,19 @@ const appMachine = setup({/* ... */}).createMachine(
 );
 ```
 
-[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) inspects all state nodes with a `meta.route` and generates the corresponding `play.route` guard transitions. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) inspects all state nodes with a `meta.route` and generates the corresponding `play.route` transitions. Each one is a config object: `matches: { to: "#<id>" }` selects the event, and a `context` mapper returns the patch with the `params` and the `query` of the event. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present), and the event map must declare `play.route`:
 
 ```typescript fragment
-types: {
-  context: {} as {
+schemas: {
+  context: types<{
     params: Record<string, string>;
     query:  Record<string, string>;
     // ... other context fields
+  }>(),
+  events: {
+    "play.route": types<Omit<PlayRouteEvent, "type">>(),
+    // ... other events
   },
-  events: {} as PlayRouteEvent | OtherEvents,
 }
 ```
 
@@ -258,61 +268,67 @@ types: {
 
 ## Guards — the actor's authority
 
-Guards are the mechanism by which the actor controls whether a transition occurs. They are pure functions of `{ context, event }` that return a boolean.
+Guards are the mechanism by which the actor controls whether a transition occurs. In XState 6 the transition function is the guard: it returns nothing to refuse the event. A named guard of `setup()` is a pure predicate, and a transition function calls it through its `guards` argument:
 
 ```typescript
-import { setup } from "xstate";
+import { setup, types } from "xstate";
 
-const authSetup = setup({
-	types: {
-		context: {} as { isAuthenticated: boolean; role: "user" | "admin" },
+const authMachine = setup({
+	schemas: {
+		context: types<{ isAuthenticated: boolean; role: "user" | "admin" }>(),
+		events: { "admin.open": types<void>() },
 	},
 	guards: {
-		isAuthenticated: ({ context }) => context.isAuthenticated,
-		isAdmin: ({ context }) => context.role === "admin",
+		isAdmin: (role: "user" | "admin") => role === "admin",
+	},
+}).createMachine({
+	context: { isAuthenticated: false, role: "user" },
+	initial: "home",
+	states: {
+		home: {
+			on: {
+				"admin.open": ({ context, guards }) =>
+					context.isAuthenticated && guards.isAdmin(context.role)
+						? { target: "admin" }
+						: undefined,
+			},
+		},
+		admin: {},
 	},
 });
 ```
 
-Guards are evaluated by XState before a transition fires. If the guard returns `false`, 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.
+XState evaluates the transition function before a transition fires. If the function returns nothing, 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.
 
-Compose a condition with the combinators of XState:
-
-| Function        | What it does                |
-| --------------- | --------------------------- |
-| `and([g1, g2])` | AND — every guard must pass |
-| `or([g1, g2])`  | OR — one guard must pass    |
-| `not(g)`        | NOT — it inverts the guard  |
-
-Each combinator resolves a guard NAME against the `guards` of `setup()`, so a name that the map does not hold fails to compile.
+XState 6 has no guard combinators. Combine conditions with `&&`, `||` and `!` inside the transition function. A guard name that the `guards` map does not hold fails to compile.
 
 ---
 
 ## Context — persistent state across transitions
 
-Context is the machine's persistent data store. It survives transitions and can be read and updated by actions:
+Context is the machine's persistent data store. It survives transitions. A transition function and an entry or exit function read it, and they change it with a returned patch:
 
 ```typescript fragment
-// Context is defined in setup({ types })
-types: {
-  context: {} as {
+// Context is declared in setup({ schemas })
+schemas: {
+  context: types<{
     isAuthenticated: boolean;
     username: string | null;
     loginAttempts: number;
-  },
+  }>(),
 },
 
-// Actions mutate context via assign
-actions: {
-  recordLoginFailure: assign({
-    loginAttempts: ({ context }) => context.loginAttempts + 1,
+// A transition function changes the context with a patch
+on: {
+  "auth.failed": ({ context }) => ({
+    context: { loginAttempts: context.loginAttempts + 1 },
   }),
 },
 ```
 
-Context is accessed in guards, actions, and when computing routes or views. It is not directly observable from outside the actor via atoms — only the derived atoms (`state`, `currentRoute`, `currentView`) are public. If you need to expose a context field reactively, add a computed atom to the actor that derives from `actor.state`.
+Context is accessed in transition functions, and when computing routes or views. It is not directly observable from outside the actor via atoms — only the derived atoms (`state`, `currentRoute`, `currentView`) are public. If you need to expose a context field reactively, add a computed atom to the actor that derives from `actor.state`.
 
 ---
 
@@ -368,5 +384,5 @@ The factory that [`definePlayer`](../api/@xmachines/play-xstate/index/functions/
 - [Views](views.md) — which state supplies the view, how a layout holds its pages, and when a renderer keeps the UI
 - [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/index/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md), and the routing utilities
-- [XState v5 documentation](https://stately.ai/docs/xstate) — upstream state machine library documentation
+- [XState documentation](https://stately.ai/docs/xstate) — upstream state machine library documentation. The migration guide of XState 6 ships in the `docs` folder of the `xstate` package
 - [Play RFC](../rfc/play.md) — complete architectural specification

package/guides/views.md

@@ -37,10 +37,12 @@ A machine and its specs therefore change never when you change the framework. Yo
 A `meta.view` is a [`ViewMeta`](../api/@xmachines/play-view/index/interfaces/ViewMeta.md). `root` names the first element, and `elements` holds every element by its key:
 
 ```ts
-import { setup } from "xstate";
-import { typedSpec } from "@xmachines/play-view";
+import { setup, types } from "xstate";
+import { typedSpec, type ViewMeta } from "@xmachines/play-view";
 
-const machine = setup({}).createMachine({
+const machine = setup({
+	schemas: { meta: types<{ view?: ViewMeta }>() },
+}).createMachine({
 	id: "app",
 	initial: "home",
 	states: {
@@ -59,7 +61,7 @@ const machine = setup({}).createMachine({
 });
 ```
 
-XState types `meta` as `Record<string, unknown>`, so TypeScript checks nothing that you write there. `typedSpec` of [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) gives the literal the type `ViewMeta` where you write it, and it does nothing at run time. The check of an excess property works on an inline literal only. For a spec in a variable, write `satisfies ViewMeta` at the literal.
+XState 6 types `meta` from `schemas.meta` of the machine, and a state cannot declare a `meta` that the schema does not name. Declare `view?: ViewMeta` there. `typedSpec` of [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) gives the literal the type `ViewMeta` where you write it, and it does nothing at run time. The check of an excess property works on an inline literal only. For a spec in a variable, write `satisfies ViewMeta` at the literal.
 
 A `ViewMeta` is what you WRITE. A [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) is what the actor DERIVES from it, and what a renderer receives. The derivation consumes `outlets`, it adds the machine context, and it stamps `viewKey` and `viewParts`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "7.0.0",
+  "version": "8.0.0-next.1",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",

package/rfc/git.md

@@ -25,10 +25,10 @@ Git is optional.
 
 ## 2. Model
 
-- machines = orphan branches
-- runs = forks
-- events = commits
-- snapshots = commits
+- machines = orphan branches (the definition is `machine.json`)
+- runs = forks (the fork commit adds `run.json`)
+- event batches = commits (one commit per appended batch, as `events.ndjson`)
+- snapshots = commits (`snapshot.json`)
 
 History is append-only.
 
@@ -37,7 +37,15 @@ History is append-only.
 ## 3. Identity
 
 - commit hashes are canonical IDs
-- same algorithm used with or without Git
+- IDs are Git object IDs in the **SHA-1** object format; SHA-256 repositories are
+  out of scope
+- IDs hash the **exact bytes** of each file: JSON is written as
+  `JSON.stringify(value, null, 2)` and a final newline, and `events.ndjson` has one
+  `JSON.stringify(event)` line per event
+- key order is kept: it is part of a machine definition (the order of `states` is
+  XState's document order), so a definition with reordered keys is another machine
+  with another ID
+- same algorithm used with or without Git: the same value gives the same ID
 
 ---
 

package/rfc/play.md

@@ -11,7 +11,7 @@
 
 This RFC defines the **Universal Player Architecture** and its reference implementation. The architecture establishes a design pattern that strictly separates **Business Logic (The Actor)** from **Infrastructure (The Runtime Adapter and View)**.
 
-The reference implementation provides a modular monorepo that satisfies the architectural constraints of **Runtime Agnosticism** and **Logic-Driven Guarding**. It leverages **atoms** to glue a specific **State Engine (XState v5)** to multiple **Runtime Adapters** (TanStack Router, React Router, Vue Router, SolidJS Router) and **View Layers** (React, Vue, SolidJS, Vanilla DOM — all via JSON-Render), while ensuring that **business logic remains the single source of truth** for navigation, state, and UI structure.
+The reference implementation provides a modular monorepo that satisfies the architectural constraints of **Runtime Agnosticism** and **Logic-Driven Guarding**. It leverages **atoms** to glue a specific **State Engine (XState v6)** to multiple **Runtime Adapters** (TanStack Router, React Router, Vue Router, SolidJS Router) and **View Layers** (React, Vue, SolidJS, Vanilla DOM — all via JSON-Render), while ensuring that **business logic remains the single source of truth** for navigation, state, and UI structure.
 
 ---
 
@@ -162,7 +162,6 @@ The base class requires only two abstract members: **reactive state** and **type
 **Design Rationale:** The RFC declared an abstract `AbstractActor` CLASS that extended `Actor` of `xstate`, and it declared both capability interfaces in this package. The implementation made the contract an INTERFACE, `PlayActor`, because the class carried no implementation: both of its members were abstract, and its whole effect was to force the inheritance of XState on every consumer of the contract. [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) names `xstate` nowhere now. The implementation also moved each capability interface to the package that holds its shared machinery: `Routable` is in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md), beside the bridge that reads it, and `Viewable` and `PlaySpec` are in [`@xmachines/play-view`](../api/@xmachines/play-view/README.md), beside the view store lifecycle. A consumer who needs no routing and no view therefore installs neither package, and [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) names the capability packages nowhere. The shape of each interface is unchanged.
 
 ```ts
-import { Actor, type AnyActorLogic, type EventObject } from "xstate";
 import type {
 	AnyAtom,
 	Atom,
@@ -215,16 +214,18 @@ export interface Viewable {
 	readonly currentView: ReadonlyAtom<PlaySpec | null>;
 }
 
-// The Base Protocol — minimal contract
-export abstract class PlayActor<
-	TLogic extends AnyActorLogic,
-	TEvent extends EventObject = EventObject,
-> extends Actor<TLogic> {
+// The Base Protocol — minimal contract. An INTERFACE, which names no state machine
+// library. The RFC declared an abstract class that extended `Actor` of XState.
+export interface ActorEvent {
+	readonly type: string;
+}
+
+export interface PlayActor<TSnapshot = unknown, TEvent extends ActorEvent = ActorEvent> {
 	// Reactive Output (Snapshot)
-	public abstract state: Atom<unknown>;
+	readonly state: Atom<TSnapshot>;
 
 	// Input Channel (typed for specific event shapes)
-	public abstract override send(event: TEvent): void;
+	send(event: TEvent): void;
 }
 ```
 
@@ -238,9 +239,9 @@ export abstract class PlayActor<
 
 #### 5.2.1 `@xmachines/play-xstate`
 
-**Role:** Concrete Logic Adapter (XState v5)
+**Role:** Concrete Logic Adapter (XState v6)
 
-Wraps XState v5 to satisfy the `PlayActor` contract. Provides the primary API for creating actors from state machine definitions.
+Wraps XState v6 to satisfy the `PlayActor` contract. Provides the primary API for creating actors from state machine definitions.
 
 **Primary Exports:**
 
@@ -258,7 +259,7 @@ Wraps XState v5 to satisfy the `PlayActor` contract. Provides the primary API fo
 - Compose the view of a parent state that declares `outlets` with the views of its active substates, so the state tree decides the layout
 - Manage atom lifecycle (create on start, dispose on stop)
 - Support snapshot restore for resumable sessions
-- Provide XState DevTools compatibility
+- Keep the inspection of XState: the `inspect` option of the factory goes to `createActor` without a change
 
 ```ts fragment
 import type { AnyStateMachine, InputFrom } from "xstate";
@@ -278,8 +279,8 @@ const definePlayer = <TMachine extends AnyStateMachine>(
 // PlayerActor carries the core protocol alone. It extends the actor class of XState
 // directly, and `PlayActor` is a contract that it implements.
 class PlayerActor<TMachine extends AnyStateMachine>
-	extends Actor<AnyActorLogic>
-	implements PlayActor<SnapshotFrom<TMachine>, EventFromLogic<TMachine>>
+	extends Actor<TMachine>
+	implements PlayActor<SnapshotFrom<TMachine>, SendableEventFromLogic<TMachine>>
 {
 	public state: Atom<SnapshotFrom<TMachine>>;
 }
@@ -303,7 +304,7 @@ Provides the complete routing infrastructure: route extraction from state machin
 
 **Design Rationale:** The RFC put the whole of the routing in one package. The implementation split it at two boundaries, because a consumer paid for both halves and used one:
 
-- [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md) holds the machine half — `extractMachineRoutes`, `createRouteMap`, `machineToGraph`, and the queries over a route tree. That half alone needs `xstate` and `@statelyai/graph`.
+- [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md) holds the machine half — `extractMachineRoutes`, `createRouteMap`, `machineToGraph`, and the queries over a route tree. That half alone needs `xstate`.
 - [`@xmachines/play-pattern`](../api/@xmachines/play-pattern/README.md) holds the pattern LANGUAGE — one parse of the URLPattern pathname grammar, and the path that `buildPath` writes back from it. A parse is string work, so the package carries no URLPattern API and no polyfill. BOTH directions of the routing read it: the match of [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) reads the parse, and the routing capability of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) reads the same parse to build a URL, so that package installs no matching machinery.
 - [`@xmachines/play-url`](../api/@xmachines/play-url/README.md) holds the URL LAYER — the URLPattern API with its polyfill, a base path, a location splitter, and the params of a framework router. It reads [`@xmachines/play-pattern`](../api/@xmachines/play-pattern/README.md) for the language and re-exports it whole. It knows no machine and no bridge.
 - [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) keeps the route map, the match of a location, `RouterBridgeBase`, the provider lifecycle, and the `Routable` capability. It names no state machine.
@@ -458,13 +459,16 @@ export const catalog = defineCatalog(schema, {
 Defines **Logic**. No framework code. No routing library imports.
 
 ```ts
-import { setup } from "xstate";
+import { setup, types } from "xstate";
 import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
 import { withRouting } from "@xmachines/play-xstate/routing";
 import { withView } from "@xmachines/play-xstate/view";
-import { typedSpec } from "@xmachines/play-view";
+import { typedSpec, type ViewMeta } from "@xmachines/play-view";
 
-export const machine = setup({/* types, guards, actions */}).createMachine({
+export const machine = setup({
+	// the schemas of the context and the events, guards, actions
+	schemas: { meta: types<{ route?: string; view?: ViewMeta }>() },
+}).createMachine({
 	id: "dashboard",
 	initial: "overview",
 	states: {

package/rfc/run.md

@@ -42,9 +42,12 @@ Properties:
 ### 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
+- The algorithm is **Git's object ID**, in the **SHA-1** object format
+- A run ID is the hash of the run's **fork commit**: its parent is the machine's
+  commit, its tree holds `machine.json` and `run.json` (the run's name and input),
+  and its author time is the time of the fork (see [Git](git.md), Identity)
+- With Git enabled: run ID **is** that commit hash
+- Without Git: the same algorithm is used, so the ID is the same
 
 Run IDs never change and never require migration.
 
@@ -152,7 +155,7 @@ a run is deterministic.
 1. Events are the only mutation mechanism
 2. Snapshots are read-only externally
 3. History is immutable
-4. IDs are Git OID–compatible
+4. IDs are Git object IDs (SHA-1)
 
 ---