@demlik/tea 0.14.0 → 0.16.0

package/dist/machine-viz/index.d.ts

@@ -1,5 +1,5 @@
-import { C as Cmd, S as Sub, M as Machine } from '../core-CTzMJ82M.js';
-import 'zod';
+import { C as Cmd, S as Sub, M as Machine } from '../core-BbgtiXdg.js';
+import '@standard-schema/spec';
 
 /**
  * Sanitize a discriminant string into a Mermaid-safe node identifier.
@@ -38,10 +38,10 @@ declare function safeLabel(raw: string): string;
  *
  * What we MUST NOT do (these are the effectful paths, off-limits here):
  *   - call `interpret[*]` handlers (perform I/O)
- *   - call `subscribe[*]` handlers (install listeners)
+ *   - call `subscribe[*]` runners (install listeners)
  *   - call `run` / the runtime
- * We MAY call `init`, `update[*]` cells, and `subscriptions(state)` — all pure
- * by the invariants (same set `replay` is allowed to touch).
+ * We MAY call `init`, `update[*]` cells, and each `subs` entry's `deps(state)`
+ * — all pure by the invariants (same set `replay` is allowed to touch).
  */
 
 /**

package/dist/machine-viz/index.js

@@ -1,4 +1,5 @@
-import { formOf } from '../chunk-RQULHGYH.js';
+import '../chunk-GOX2CYIM.js';
+import { formOf, subEntriesOf, desiredSub } from '../chunk-CH5KTOEZ.js';
 
 // src/machine-viz/mermaid-id.ts
 function safeId(raw) {
@@ -116,14 +117,17 @@ function resolveEdge(row, stateType, msgType, ctx) {
   }
 }
 function emitSubscriptions(machine, lines, stateSamples) {
-  if (machine.subscriptions === void 0) return;
+  const entries = subEntriesOf(machine);
+  if (entries.length === 0) return;
   const stateTypes = Object.keys(stateSamples);
   if (stateTypes.length === 0) return;
   for (const st of stateTypes) {
     const sample = stateSamples[st];
     if (sample === void 0) continue;
-    const subs = machine.subscriptions(sample);
-    const subTypes = subs.map((s) => s.type);
+    const subTypes = entries.flatMap((entry) => {
+      const sub = desiredSub(entry, sample);
+      return sub === null ? [] : [sub.type];
+    });
     const body = subTypes.length === 0 ? "(no active subs)" : `subs: ${subTypes.map(safeLabel).join(", ")}`;
     lines.push(`  note left of ${safeId(st)}`);
     lines.push(`    ${body}`);

package/dist/machine-viz/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/machine-viz/mermaid-id.ts","../../src/machine-viz/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// ═══════════════════════════════════════════════════════════════════════════\n// MERMAID SANITIZING — the two functions every drawing in this package shares.\n//\n// Mermaid state ids must be identifier-safe, and a transition label must not\n// contain the characters that terminate it. A state name like\n// `human:cp-approval` breaks the diagram on both counts.\n//\n// So it lives here, in a module with NO imports, rather than inside\n// `machine-viz/index.ts` — that one pulls in the whole substrate (`formOf`\n// from `../index`), and a future drawing must not acquire that dependency\n// merely to sanitize a string.\n// ═══════════════════════════════════════════════════════════════════════════\n\n/**\n * Sanitize a discriminant string into a Mermaid-safe node identifier.\n *\n * Any run of non-identifier characters becomes `_`; a leading digit is\n * prefixed so the id is always a valid Mermaid token; the empty string gets a\n * stable placeholder. Deterministic and idempotent — `safeId(safeId(x))` is\n * `safeId(x)`, so a diagram may sanitize the same name at several sites.\n */\nexport function safeId(raw: string): string {\n  const cleaned = raw.replace(/[^A-Za-z0-9_]/g, \"_\");\n  if (cleaned === \"\") return \"_empty\";\n  return /^[0-9]/.test(cleaned) ? `s_${cleaned}` : cleaned;\n}\n\n/**\n * Sanitize text used as a Mermaid edge/transition label (the part after `:`).\n *\n * Strips the characters that terminate or confuse a label: newlines, the `:`\n * that separates label from target, and Mermaid's `\"`/`;` delimiters.\n */\nexport function safeLabel(raw: string): string {\n  return raw.replace(/[\"\\n\\r;:]/g, \" \").trim();\n}\n","/**\n * @demlik/tea/machine-viz — turn a `Machine` into a Mermaid diagram string.\n *\n * PURE. No deps, no AST parsing, no file I/O. The function reads only the\n * `Machine` value it is handed plus optional sample states/msgs/ctx.\n *\n * The trick: TEA update cells are PURE (invariant 2 — they return\n * `[nextState, cmds]` as data, no effects). So we can SAFELY EXECUTE a cell to\n * discover its target state — exactly what `replay` does. That gives us REAL\n * edges (`red --> green : go`) without parsing source. When no sample is\n * provided for a `(state, msg)` pair we cannot resolve the target, so we fall\n * back to a STRUCTURAL self-edge annotated with `?` — visually distinct from a\n * resolved edge and documented in the diagram's legend.\n *\n * Form detection is `formOf(machine)` — the same reader `run`/`replay` use,\n * honoring the authoritative `__form` tag `defineMachine` stamps (falling back\n * to the structural heuristic for machines built without it; #275).\n *\n * What we MUST NOT do (these are the effectful paths, off-limits here):\n *   - call `interpret[*]` handlers (perform I/O)\n *   - call `subscribe[*]` handlers (install listeners)\n *   - call `run` / the runtime\n * We MAY call `init`, `update[*]` cells, and `subscriptions(state)` — all pure\n * by the invariants (same set `replay` is allowed to touch).\n */\n\nimport type { Cmd, Machine, Sub } from \"../index\";\nimport { formOf } from \"../index\";\nimport { safeId, safeLabel } from \"./mermaid-id\";\n\n// The sanitizers live in a dependency-free module and are re-exported here,\n// because a consumer post-processing this drawing needs the same escaping.\nexport { safeId, safeLabel } from \"./mermaid-id\";\n\n// === Public options ===\n\n/**\n * Options controlling diagram emission.\n *\n * `samples` is the lever that turns STRUCTURAL edges into RESOLVED edges. For a\n * Transitions machine, providing a sample state for `stateType` AND a sample\n * msg for `msgType` lets us execute `update[stateType][msgType](state, msg)` and\n * read the real target `next.type`. Sample maps are keyed by the discriminant\n * string (`state.type` / `msg.type`).\n *\n * `samples.ctx` is the argument to `init(null, ctx)` — provide it to draw the\n * `[*] -->` initial-state edge. Omitted ⇒ no init edge (annotated as such),\n * because `init`'s signature requires a ctx and we will not invent one.\n */\nexport interface MachineVizOptions<S, M> {\n  samples?: {\n    /** Sample state per `state.type` — unlocks RESOLVED edges + sub annotations. */\n    states?: Partial<Record<string, S>>;\n    /** Sample msg per `msg.type` — unlocks RESOLVED edges. */\n    msgs?: Partial<Record<string, M>>;\n    /** Ctx for `init(null, ctx)` — unlocks the `[*] -->` initial-state edge. */\n    ctx?: unknown;\n  };\n  /** Mermaid layout direction. Default `\"TB\"` (top-to-bottom). */\n  direction?: \"TB\" | \"LR\";\n  /** Optional diagram title, emitted as a Mermaid front-matter `title:` block. */\n  title?: string;\n}\n\n// === Edge model ===\n\ntype Edge =\n  // Resolved: we executed the cell with samples and read the real target.\n  | { kind: \"resolved\"; from: string; to: string; msg: string }\n  // Structural: no samples for the pair → target unknown, drawn as a self-loop.\n  | { kind: \"structural\"; from: string; msg: string };\n\n// === toMermaid ===\n\n/**\n * Render a `Machine` as a Mermaid `stateDiagram-v2` string.\n *\n * - **Transitions form** (`update` is a record-of-records): nodes are the\n *   `state.type` keys; each `(stateType × msgType)` cell becomes an edge. With\n *   samples for both, the edge is RESOLVED by executing the (pure) cell. Without\n *   samples it is STRUCTURAL — a `from --> from : msg?` self-loop (the `?`\n *   suffix marks \"target unresolved\"). A legend note documents the distinction.\n *   The `[*] -->` init edge is drawn only when `samples.ctx` is provided.\n *\n * - **Reducer form** (`update` values are functions): there is no static phase\n *   graph (state is not a discriminated union over phases). We emit a single\n *   node listing the handled `msg.type`s and an honest note saying so. No edges\n *   are invented.\n *\n * Output is deterministic for the same input (keys iterated in insertion order,\n * no clocks, no randomness).\n */\nexport function toMermaid<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  // `NoInfer` pins S/M to the `machine` argument so sample object literals in\n  // `opts` are CHECKED against the machine's State/Msg unions rather than\n  // driving inference (which would widen `{ type: \"open\" }` to `{ type: string }`\n  // and collide with the machine's discriminated union).\n  opts: MachineVizOptions<NoInfer<S>, NoInfer<M>> = {},\n): string {\n  const direction = opts.direction ?? \"TB\";\n  const stateSamples = opts.samples?.states ?? {};\n  const msgSamples = opts.samples?.msgs ?? {};\n  const hasCtx = opts.samples !== undefined && \"ctx\" in opts.samples;\n\n  const mode = formOf(machine);\n  const lines: string[] = [];\n\n  // Front matter — Mermaid reads a YAML `title:` block before the diagram.\n  if (opts.title !== undefined) {\n    lines.push(\"---\", `title: ${opts.title}`, \"---\");\n  }\n  lines.push(\"stateDiagram-v2\");\n  lines.push(`  direction ${direction}`);\n\n  if (mode === \"reducer\") {\n    emitReducer(machine, lines);\n  } else {\n    emitTransitions(machine, lines, {\n      stateSamples,\n      msgSamples,\n      hasCtx,\n      ctx: opts.samples?.ctx,\n    });\n  }\n\n  // Subscriptions annotation — pure call to `subscriptions(sampleState)` per\n  // sampled state. Skipped entirely when no state samples are provided (we\n  // refuse to invent a state to feed it).\n  emitSubscriptions(machine, lines, stateSamples);\n\n  return lines.join(\"\\n\");\n}\n\n// === Reducer-form emission ===\n\n/**\n * Reducer form has no phase graph. Emit one node listing the handled msg types\n * plus an honest note. The msg set is the `update` record's keys (the Reducer\n * mapped type guarantees one cell per Msg variant).\n */\nfunction emitReducer(machine: { update: unknown }, lines: string[]): void {\n  const msgTypes = Object.keys(machine.update as object);\n  lines.push(\"  state ReducerMachine {\");\n  if (msgTypes.length === 0) {\n    lines.push(\"    [*] --> NoMsgs\");\n    lines.push('    NoMsgs : \"(no msg variants — M is never)\"');\n  } else {\n    for (const m of msgTypes) {\n      lines.push(`    ${safeId(m)} : ${safeLabel(m)}`);\n    }\n  }\n  lines.push(\"  }\");\n  // The note IS the design honesty: no edges, because reducer-form state is not\n  // a discriminated union over phases — there is no static target to draw.\n  lines.push(\"  note right of ReducerMachine\");\n  lines.push(\"    Reducer-form machine: flat dispatch keyed by msg.type.\");\n  lines.push(\n    \"    No phase graph — state is not a discriminated union over phases.\",\n  );\n  lines.push(`    Handled msg types: ${msgTypes.length}`);\n  lines.push(\"  end note\");\n}\n\n// === Transitions-form emission ===\n\ninterface TransitionsCtx<S, M> {\n  stateSamples: Partial<Record<string, S>>;\n  msgSamples: Partial<Record<string, M>>;\n  hasCtx: boolean;\n  ctx: unknown;\n}\n\n/**\n * Transitions form: walk the `update[stateType][msgType]` table. Execute the\n * (pure) cell when both samples exist → RESOLVED edge; otherwise → STRUCTURAL\n * self-loop. Draw the `[*] -->` init edge only when a ctx sample is given.\n */\nfunction emitTransitions<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  lines: string[],\n  ctx: TransitionsCtx<S, M>,\n): void {\n  type CellFn = (state: S, msg: M) => readonly [S, readonly C[]];\n  type Table = Record<string, Record<string, CellFn>>;\n  const table = machine.update as unknown as Table;\n  const stateTypes = Object.keys(table);\n\n  // Declare every node up front so even unreachable phases render.\n  for (const st of stateTypes) {\n    lines.push(`  ${safeId(st)}`);\n  }\n\n  // Init edge — only resolvable with a ctx sample. `init(null, ctx)` is pure\n  // (invariant 2: fresh-boot branch returns a starting state). Read `next.type`.\n  if (ctx.hasCtx) {\n    const [initState] = machine.init(null, ctx.ctx as Ctx);\n    const initType = (initState as unknown as { type: string }).type;\n    lines.push(`  [*] --> ${safeId(initType)}`);\n  } else {\n    lines.push(\n      \"  %% init edge omitted: no samples.ctx provided to run init(null, ctx)\",\n    );\n  }\n\n  let anyStructural = false;\n  for (const st of stateTypes) {\n    const row = table[st];\n    if (row === undefined) continue;\n    const msgTypes = Object.keys(row);\n    for (const mt of msgTypes) {\n      const edge = resolveEdge(row, st, mt, ctx);\n      if (edge.kind === \"resolved\") {\n        lines.push(\n          `  ${safeId(edge.from)} --> ${safeId(edge.to)} : ${safeLabel(edge.msg)}`,\n        );\n      } else {\n        anyStructural = true;\n        // Structural self-loop with a `?` suffix — target unresolved. Visually\n        // distinct from a resolved edge (self-loop + trailing `?`).\n        lines.push(\n          `  ${safeId(edge.from)} --> ${safeId(edge.from)} : ${safeLabel(edge.msg)}?`,\n        );\n      }\n    }\n  }\n\n  // Legend — document the resolved-vs-structural distinction in the output.\n  lines.push(`  note right of ${safeId(stateTypes[0] ?? \"_empty\")}`);\n  lines.push(\"    Transitions-form machine.\");\n  lines.push(\"    Edge a --> b : msg = RESOLVED (cell executed with samples).\");\n  if (anyStructural) {\n    lines.push(\n      \"    Self-loop a --> a : msg? = STRUCTURAL (no sample; target unresolved).\",\n    );\n  }\n  lines.push(\"  end note\");\n}\n\n/**\n * Resolve a single `(stateType, msgType)` cell into an Edge. With both a sample\n * state and a sample msg, EXECUTE the pure cell to read the real target. Any\n * missing sample → structural. A thrown cell (e.g. a sample shaped wrong for\n * the cell) degrades to structural rather than crashing the whole diagram —\n * the diagram is a best-effort visualization, not a correctness gate.\n */\nfunction resolveEdge<S, M extends { type: string }, C extends Cmd>(\n  row: Record<string, (state: S, msg: M) => readonly [S, readonly C[]]>,\n  stateType: string,\n  msgType: string,\n  ctx: {\n    stateSamples: Partial<Record<string, S>>;\n    msgSamples: Partial<Record<string, M>>;\n  },\n): Edge {\n  const sampleState = ctx.stateSamples[stateType];\n  const sampleMsg = ctx.msgSamples[msgType];\n  const cell = row[msgType];\n  if (\n    sampleState === undefined ||\n    sampleMsg === undefined ||\n    cell === undefined\n  ) {\n    return { kind: \"structural\", from: stateType, msg: msgType };\n  }\n  try {\n    const [next] = cell(sampleState, sampleMsg);\n    const to = (next as unknown as { type: string }).type;\n    return { kind: \"resolved\", from: stateType, to, msg: msgType };\n  } catch {\n    // Mismatched sample → cannot resolve. Fall back to structural.\n    return { kind: \"structural\", from: stateType, msg: msgType };\n  }\n}\n\n// === Subscriptions annotation ===\n\n/**\n * For each sampled state, call the (pure) `subscriptions(state)` description\n * function and annotate which Sub types are active in that state as a Mermaid\n * note. We call `subscriptions` (the description) but NEVER `subscribe[*]` (the\n * effectful installer) — same boundary `replay` honors. Skipped when no state\n * samples are provided or the machine declares no `subscriptions`.\n */\nfunction emitSubscriptions<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  lines: string[],\n  stateSamples: Partial<Record<string, S>>,\n): void {\n  if (machine.subscriptions === undefined) return;\n  const stateTypes = Object.keys(stateSamples);\n  if (stateTypes.length === 0) return;\n\n  for (const st of stateTypes) {\n    const sample = stateSamples[st];\n    if (sample === undefined) continue;\n    const subs = machine.subscriptions(sample);\n    const subTypes = subs.map((s) => s.type);\n    const body =\n      subTypes.length === 0\n        ? \"(no active subs)\"\n        : `subs: ${subTypes.map(safeLabel).join(\", \")}`;\n    lines.push(`  note left of ${safeId(st)}`);\n    lines.push(`    ${body}`);\n    lines.push(\"  end note\");\n  }\n}\n"]}
+{"version":3,"sources":["../../src/machine-viz/mermaid-id.ts","../../src/machine-viz/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// ═══════════════════════════════════════════════════════════════════════════\n// MERMAID SANITIZING — the two functions every drawing in this package shares.\n//\n// Mermaid state ids must be identifier-safe, and a transition label must not\n// contain the characters that terminate it. A state name like\n// `human:cp-approval` breaks the diagram on both counts.\n//\n// So it lives here, in a module with NO imports, rather than inside\n// `machine-viz/index.ts` — that one pulls in the whole substrate (`formOf`\n// from `../index`), and a future drawing must not acquire that dependency\n// merely to sanitize a string.\n// ═══════════════════════════════════════════════════════════════════════════\n\n/**\n * Sanitize a discriminant string into a Mermaid-safe node identifier.\n *\n * Any run of non-identifier characters becomes `_`; a leading digit is\n * prefixed so the id is always a valid Mermaid token; the empty string gets a\n * stable placeholder. Deterministic and idempotent — `safeId(safeId(x))` is\n * `safeId(x)`, so a diagram may sanitize the same name at several sites.\n */\nexport function safeId(raw: string): string {\n  const cleaned = raw.replace(/[^A-Za-z0-9_]/g, \"_\");\n  if (cleaned === \"\") return \"_empty\";\n  return /^[0-9]/.test(cleaned) ? `s_${cleaned}` : cleaned;\n}\n\n/**\n * Sanitize text used as a Mermaid edge/transition label (the part after `:`).\n *\n * Strips the characters that terminate or confuse a label: newlines, the `:`\n * that separates label from target, and Mermaid's `\"`/`;` delimiters.\n */\nexport function safeLabel(raw: string): string {\n  return raw.replace(/[\"\\n\\r;:]/g, \" \").trim();\n}\n","/**\n * @demlik/tea/machine-viz — turn a `Machine` into a Mermaid diagram string.\n *\n * PURE. No deps, no AST parsing, no file I/O. The function reads only the\n * `Machine` value it is handed plus optional sample states/msgs/ctx.\n *\n * The trick: TEA update cells are PURE (invariant 2 — they return\n * `[nextState, cmds]` as data, no effects). So we can SAFELY EXECUTE a cell to\n * discover its target state — exactly what `replay` does. That gives us REAL\n * edges (`red --> green : go`) without parsing source. When no sample is\n * provided for a `(state, msg)` pair we cannot resolve the target, so we fall\n * back to a STRUCTURAL self-edge annotated with `?` — visually distinct from a\n * resolved edge and documented in the diagram's legend.\n *\n * Form detection is `formOf(machine)` — the same reader `run`/`replay` use,\n * honoring the authoritative `__form` tag `defineMachine` stamps (falling back\n * to the structural heuristic for machines built without it; #275).\n *\n * What we MUST NOT do (these are the effectful paths, off-limits here):\n *   - call `interpret[*]` handlers (perform I/O)\n *   - call `subscribe[*]` runners (install listeners)\n *   - call `run` / the runtime\n * We MAY call `init`, `update[*]` cells, and each `subs` entry's `deps(state)`\n * — all pure by the invariants (same set `replay` is allowed to touch).\n */\n\nimport type { Cmd, Machine, Sub } from \"../index\";\nimport { formOf } from \"../index\";\nimport { desiredSub, subEntriesOf } from \"../pure/core\";\nimport { safeId, safeLabel } from \"./mermaid-id\";\n\n// The sanitizers live in a dependency-free module and are re-exported here,\n// because a consumer post-processing this drawing needs the same escaping.\nexport { safeId, safeLabel } from \"./mermaid-id\";\n\n// === Public options ===\n\n/**\n * Options controlling diagram emission.\n *\n * `samples` is the lever that turns STRUCTURAL edges into RESOLVED edges. For a\n * Transitions machine, providing a sample state for `stateType` AND a sample\n * msg for `msgType` lets us execute `update[stateType][msgType](state, msg)` and\n * read the real target `next.type`. Sample maps are keyed by the discriminant\n * string (`state.type` / `msg.type`).\n *\n * `samples.ctx` is the argument to `init(null, ctx)` — provide it to draw the\n * `[*] -->` initial-state edge. Omitted ⇒ no init edge (annotated as such),\n * because `init`'s signature requires a ctx and we will not invent one.\n */\nexport interface MachineVizOptions<S, M> {\n  samples?: {\n    /** Sample state per `state.type` — unlocks RESOLVED edges + sub annotations. */\n    states?: Partial<Record<string, S>>;\n    /** Sample msg per `msg.type` — unlocks RESOLVED edges. */\n    msgs?: Partial<Record<string, M>>;\n    /** Ctx for `init(null, ctx)` — unlocks the `[*] -->` initial-state edge. */\n    ctx?: unknown;\n  };\n  /** Mermaid layout direction. Default `\"TB\"` (top-to-bottom). */\n  direction?: \"TB\" | \"LR\";\n  /** Optional diagram title, emitted as a Mermaid front-matter `title:` block. */\n  title?: string;\n}\n\n// === Edge model ===\n\ntype Edge =\n  // Resolved: we executed the cell with samples and read the real target.\n  | { kind: \"resolved\"; from: string; to: string; msg: string }\n  // Structural: no samples for the pair → target unknown, drawn as a self-loop.\n  | { kind: \"structural\"; from: string; msg: string };\n\n// === toMermaid ===\n\n/**\n * Render a `Machine` as a Mermaid `stateDiagram-v2` string.\n *\n * - **Transitions form** (`update` is a record-of-records): nodes are the\n *   `state.type` keys; each `(stateType × msgType)` cell becomes an edge. With\n *   samples for both, the edge is RESOLVED by executing the (pure) cell. Without\n *   samples it is STRUCTURAL — a `from --> from : msg?` self-loop (the `?`\n *   suffix marks \"target unresolved\"). A legend note documents the distinction.\n *   The `[*] -->` init edge is drawn only when `samples.ctx` is provided.\n *\n * - **Reducer form** (`update` values are functions): there is no static phase\n *   graph (state is not a discriminated union over phases). We emit a single\n *   node listing the handled `msg.type`s and an honest note saying so. No edges\n *   are invented.\n *\n * Output is deterministic for the same input (keys iterated in insertion order,\n * no clocks, no randomness).\n */\nexport function toMermaid<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  // `NoInfer` pins S/M to the `machine` argument so sample object literals in\n  // `opts` are CHECKED against the machine's State/Msg unions rather than\n  // driving inference (which would widen `{ type: \"open\" }` to `{ type: string }`\n  // and collide with the machine's discriminated union).\n  opts: MachineVizOptions<NoInfer<S>, NoInfer<M>> = {},\n): string {\n  const direction = opts.direction ?? \"TB\";\n  const stateSamples = opts.samples?.states ?? {};\n  const msgSamples = opts.samples?.msgs ?? {};\n  const hasCtx = opts.samples !== undefined && \"ctx\" in opts.samples;\n\n  const mode = formOf(machine);\n  const lines: string[] = [];\n\n  // Front matter — Mermaid reads a YAML `title:` block before the diagram.\n  if (opts.title !== undefined) {\n    lines.push(\"---\", `title: ${opts.title}`, \"---\");\n  }\n  lines.push(\"stateDiagram-v2\");\n  lines.push(`  direction ${direction}`);\n\n  if (mode === \"reducer\") {\n    emitReducer(machine, lines);\n  } else {\n    emitTransitions(machine, lines, {\n      stateSamples,\n      msgSamples,\n      hasCtx,\n      ctx: opts.samples?.ctx,\n    });\n  }\n\n  // Subscriptions annotation — pure call to each `subs` entry's `deps` per\n  // sampled state. Skipped entirely when no state samples are provided (we\n  // refuse to invent a state to feed it).\n  emitSubscriptions(machine, lines, stateSamples);\n\n  return lines.join(\"\\n\");\n}\n\n// === Reducer-form emission ===\n\n/**\n * Reducer form has no phase graph. Emit one node listing the handled msg types\n * plus an honest note. The msg set is the `update` record's keys (the Reducer\n * mapped type guarantees one cell per Msg variant).\n */\nfunction emitReducer(machine: { update: unknown }, lines: string[]): void {\n  const msgTypes = Object.keys(machine.update as object);\n  lines.push(\"  state ReducerMachine {\");\n  if (msgTypes.length === 0) {\n    lines.push(\"    [*] --> NoMsgs\");\n    lines.push('    NoMsgs : \"(no msg variants — M is never)\"');\n  } else {\n    for (const m of msgTypes) {\n      lines.push(`    ${safeId(m)} : ${safeLabel(m)}`);\n    }\n  }\n  lines.push(\"  }\");\n  // The note IS the design honesty: no edges, because reducer-form state is not\n  // a discriminated union over phases — there is no static target to draw.\n  lines.push(\"  note right of ReducerMachine\");\n  lines.push(\"    Reducer-form machine: flat dispatch keyed by msg.type.\");\n  lines.push(\n    \"    No phase graph — state is not a discriminated union over phases.\",\n  );\n  lines.push(`    Handled msg types: ${msgTypes.length}`);\n  lines.push(\"  end note\");\n}\n\n// === Transitions-form emission ===\n\ninterface TransitionsCtx<S, M> {\n  stateSamples: Partial<Record<string, S>>;\n  msgSamples: Partial<Record<string, M>>;\n  hasCtx: boolean;\n  ctx: unknown;\n}\n\n/**\n * Transitions form: walk the `update[stateType][msgType]` table. Execute the\n * (pure) cell when both samples exist → RESOLVED edge; otherwise → STRUCTURAL\n * self-loop. Draw the `[*] -->` init edge only when a ctx sample is given.\n */\nfunction emitTransitions<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  lines: string[],\n  ctx: TransitionsCtx<S, M>,\n): void {\n  type CellFn = (state: S, msg: M) => readonly [S, readonly C[]];\n  type Table = Record<string, Record<string, CellFn>>;\n  const table = machine.update as unknown as Table;\n  const stateTypes = Object.keys(table);\n\n  // Declare every node up front so even unreachable phases render.\n  for (const st of stateTypes) {\n    lines.push(`  ${safeId(st)}`);\n  }\n\n  // Init edge — only resolvable with a ctx sample. `init(null, ctx)` is pure\n  // (invariant 2: fresh-boot branch returns a starting state). Read `next.type`.\n  if (ctx.hasCtx) {\n    const [initState] = machine.init(null, ctx.ctx as Ctx);\n    const initType = (initState as unknown as { type: string }).type;\n    lines.push(`  [*] --> ${safeId(initType)}`);\n  } else {\n    lines.push(\n      \"  %% init edge omitted: no samples.ctx provided to run init(null, ctx)\",\n    );\n  }\n\n  let anyStructural = false;\n  for (const st of stateTypes) {\n    const row = table[st];\n    if (row === undefined) continue;\n    const msgTypes = Object.keys(row);\n    for (const mt of msgTypes) {\n      const edge = resolveEdge(row, st, mt, ctx);\n      if (edge.kind === \"resolved\") {\n        lines.push(\n          `  ${safeId(edge.from)} --> ${safeId(edge.to)} : ${safeLabel(edge.msg)}`,\n        );\n      } else {\n        anyStructural = true;\n        // Structural self-loop with a `?` suffix — target unresolved. Visually\n        // distinct from a resolved edge (self-loop + trailing `?`).\n        lines.push(\n          `  ${safeId(edge.from)} --> ${safeId(edge.from)} : ${safeLabel(edge.msg)}?`,\n        );\n      }\n    }\n  }\n\n  // Legend — document the resolved-vs-structural distinction in the output.\n  lines.push(`  note right of ${safeId(stateTypes[0] ?? \"_empty\")}`);\n  lines.push(\"    Transitions-form machine.\");\n  lines.push(\"    Edge a --> b : msg = RESOLVED (cell executed with samples).\");\n  if (anyStructural) {\n    lines.push(\n      \"    Self-loop a --> a : msg? = STRUCTURAL (no sample; target unresolved).\",\n    );\n  }\n  lines.push(\"  end note\");\n}\n\n/**\n * Resolve a single `(stateType, msgType)` cell into an Edge. With both a sample\n * state and a sample msg, EXECUTE the pure cell to read the real target. Any\n * missing sample → structural. A thrown cell (e.g. a sample shaped wrong for\n * the cell) degrades to structural rather than crashing the whole diagram —\n * the diagram is a best-effort visualization, not a correctness gate.\n */\nfunction resolveEdge<S, M extends { type: string }, C extends Cmd>(\n  row: Record<string, (state: S, msg: M) => readonly [S, readonly C[]]>,\n  stateType: string,\n  msgType: string,\n  ctx: {\n    stateSamples: Partial<Record<string, S>>;\n    msgSamples: Partial<Record<string, M>>;\n  },\n): Edge {\n  const sampleState = ctx.stateSamples[stateType];\n  const sampleMsg = ctx.msgSamples[msgType];\n  const cell = row[msgType];\n  if (\n    sampleState === undefined ||\n    sampleMsg === undefined ||\n    cell === undefined\n  ) {\n    return { kind: \"structural\", from: stateType, msg: msgType };\n  }\n  try {\n    const [next] = cell(sampleState, sampleMsg);\n    const to = (next as unknown as { type: string }).type;\n    return { kind: \"resolved\", from: stateType, to, msg: msgType };\n  } catch {\n    // Mismatched sample → cannot resolve. Fall back to structural.\n    return { kind: \"structural\", from: stateType, msg: msgType };\n  }\n}\n\n// === Subscriptions annotation ===\n\n/**\n * For each sampled state, read which `subs` entries are on there (their pure\n * `deps`) and annotate those Sub types as a Mermaid note. We read `deps` (the\n * description) but NEVER a `subscribe[*]` runner (the effectful installer) —\n * same boundary `replay` honors. Skipped when no state samples are provided or\n * the machine declares no `subs`.\n */\nfunction emitSubscriptions<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  lines: string[],\n  stateSamples: Partial<Record<string, S>>,\n): void {\n  const entries = subEntriesOf<S>(machine);\n  if (entries.length === 0) return;\n  const stateTypes = Object.keys(stateSamples);\n  if (stateTypes.length === 0) return;\n\n  for (const st of stateTypes) {\n    const sample = stateSamples[st];\n    if (sample === undefined) continue;\n    const subTypes = entries.flatMap((entry) => {\n      const sub = desiredSub(entry, sample);\n      return sub === null ? [] : [sub.type];\n    });\n    const body =\n      subTypes.length === 0\n        ? \"(no active subs)\"\n        : `subs: ${subTypes.map(safeLabel).join(\", \")}`;\n    lines.push(`  note left of ${safeId(st)}`);\n    lines.push(`    ${body}`);\n    lines.push(\"  end note\");\n  }\n}\n"]}

package/dist/mem/index.d.ts

@@ -1,7 +1,6 @@
-import { S as Store, F as FencedStore } from '../runtime-types-LWDoi943.js';
-import 'better-result';
-import '../core-CTzMJ82M.js';
-import 'zod';
+import { S as Store, F as FencedStore } from '../runtime-types-CiVpC0HN.js';
+import '../core-BbgtiXdg.js';
+import '@standard-schema/spec';
 
 /**
  * @packageDocumentation

package/dist/mem/index.js

@@ -1,4 +1,5 @@
-import { StoreConflictError } from '../chunk-RQULHGYH.js';
+import '../chunk-GOX2CYIM.js';
+import { StoreConflictError } from '../chunk-CH5KTOEZ.js';
 
 // src/mem/index.ts
 function memoryStore(initial, parse = (raw) => raw, options = {}) {

package/dist/mem/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/mem/index.ts"],"names":[],"mappings":";;;AAsEO,SAAS,WAAA,CACd,SACA,KAAA,GAAoC,CAAC,QAAQ,GAAA,EAC7C,OAAA,GAA8B,EAAC,EACJ;AAG3B,EAAA,IAAI,OAAiB,OAAA,IAAW,IAAA;AAGhC,EAAA,IAAI,OAAA,GAAU,CAAA;AAEd,EAAA,MAAM,IAAA,GAAiB;AAAA,IACrB,MAAM,IAAA,GAAyB;AAC7B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA;AAAA,IACA,MAAM,KAAK,KAAA,EAAyB;AAClC,MAAA,IAAA,GAAO,KAAA;AACP,MAAA,OAAA,IAAW,CAAA;AAAA,IACb,CAAA;AAAA,IACA,QAAQ,GAAA,EAAwB;AAC9B,MAAA,OAAO,MAAM,GAAG,CAAA;AAAA,IAClB;AAAA,GACF;AACA,EAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,IAAA,EAAM,OAAO,IAAA;AAEpC,EAAA,OAAO;AAAA,IACL,GAAG,IAAA;AAAA,IACH,MAAA,EAAQ,IAAA;AAAA,IACR,MAAM,UAAA,GAAyD;AAC7D,MAAA,OAAO,EAAE,GAAA,EAAK,IAAA,EAAM,OAAA,EAAQ;AAAA,IAC9B,CAAA;AAAA,IACA,MAAM,UAAA,CAAW,KAAA,EAAU,eAAA,EAA0C;AAInE,MAAA,IAAI,YAAY,eAAA,EAAiB;AAC/B,QAAA,MAAM,IAAI,kBAAA,CAAmB,eAAA,EAAiB,OAAO,CAAA;AAAA,MACvD;AACA,MAAA,IAAA,GAAO,KAAA;AACP,MAAA,OAAA,IAAW,CAAA;AACX,MAAA,OAAO,OAAA;AAAA,IACT;AAAA,GACF;AACF","file":"index.js","sourcesContent":["/**\n * @packageDocumentation\n * @demlik/tea/mem — in-memory `Store<S>` adapter for `@demlik/tea`.\n *\n * The standard test adapter — used everywhere a Worker or DO would be\n * overkill. Mirrors the source-only convention from `packages/widget-engine`\n * and `packages/tea` (no build step).\n *\n * Reference semantics, NOT deep-clone semantics:\n *   - `save(state)` stores the reference; subsequent mutations to that\n *     reference by the caller are observable through later `load()` calls.\n *   - `load()` returns the stored reference; mutations made through it are\n *     observable on the next `load()`.\n *\n * This matches what a real KV/DO `get()` would NOT do (those serialize +\n * deserialize), but it also matches what an in-memory cache obviously does.\n * Adding a deep clone here would lie about the boundary and impose a JSON\n * round-trip on every test. Tests that need fresh copies should clone at the\n * call site.\n *\n * Boundary parse (invariant 8): `Store<S>` requires `migrate(raw)`. For\n * `memoryStore` we ship a permissive identity-default — `(raw) => raw as\n * S | null` — because this adapter is a degenerate same-process boundary:\n * there is no serialization, the reference we read is structurally the\n * reference we wrote. The `as` cast here is the documented exception to the\n * invariant-8 no-`as` rule, scoped to the parameter default. Callers that\n * want strict parsing (e.g. a test that hand-seeds the cell from outside)\n * may pass an explicit `parse` to override.\n */\n\nimport type { FencedStore, Store } from \"../index\";\nimport { StoreConflictError } from \"../index\";\n\n/** Options for {@link memoryStore}. */\nexport interface MemoryStoreOptions {\n  /**\n   * Refuse a second live writer (#143). With `{ fenced: true }` the returned\n   * store is a `FencedStore<S>` whose version is an in-process counter — honest\n   * for this adapter, since the cell it guards is in this process too. Two\n   * `run`s handed the SAME `memoryStore` are the case it catches, and it is the\n   * cheapest way to exercise the fenced path in a test.\n   */\n  readonly fenced?: true;\n}\n\n/**\n * Build an in-memory `Store<S>`.\n *\n * @param initial - optional seed value. `undefined` and explicit `null` both\n *   mean \"no seed\"; `load()` resolves with `null` until the first `save()`.\n *   A concrete `S` seed is returned by `load()` until overwritten.\n * @param parse - optional boundary parse for the `Store<S>.migrate` contract.\n *   Defaults to identity (`(raw) => raw as S | null`) — honest for this\n *   adapter's degenerate same-process boundary. Pass an explicit parser when\n *   the test wants to reject seeded shapes that don't match `S`.\n */\nexport function memoryStore<S>(\n  initial?: S | null,\n  parse?: (raw: unknown) => S | null,\n): Store<S>;\nexport function memoryStore<S>(\n  initial: S | null | undefined,\n  parse: ((raw: unknown) => S | null) | undefined,\n  options: MemoryStoreOptions & { readonly fenced: true },\n): FencedStore<S>;\nexport function memoryStore<S>(\n  initial?: S | null,\n  parse?: (raw: unknown) => S | null,\n  options?: MemoryStoreOptions,\n): Store<S> | FencedStore<S>;\nexport function memoryStore<S>(\n  initial?: S | null,\n  parse: (raw: unknown) => S | null = (raw) => raw as S | null,\n  options: MemoryStoreOptions = {},\n): Store<S> | FencedStore<S> {\n  // Single internal cell — `undefined` and `null` collapse to one\n  // representation so the load site is branchless.\n  let cell: S | null = initial ?? null;\n  // The version the cell was last written at. A never-written cell reads `0`,\n  // matching `fileStore`'s absent stamp.\n  let version = 0;\n\n  const base: Store<S> = {\n    async load(): Promise<unknown> {\n      return cell;\n    },\n    async save(state: S): Promise<void> {\n      cell = state;\n      version += 1;\n    },\n    migrate(raw: unknown): S | null {\n      return parse(raw);\n    },\n  };\n  if (options.fenced !== true) return base;\n\n  return {\n    ...base,\n    fenced: true,\n    async loadFenced(): Promise<{ raw: unknown; version: number }> {\n      return { raw: cell, version };\n    },\n    async saveFenced(state: S, expectedVersion: number): Promise<number> {\n      // No lock: the whole store is one process's memory, and this body has no\n      // await before the compare, so nothing can interleave between the check\n      // and the write.\n      if (version !== expectedVersion) {\n        throw new StoreConflictError(expectedVersion, version);\n      }\n      cell = state;\n      version += 1;\n      return version;\n    },\n  };\n}\n"]}
+{"version":3,"sources":["../../src/mem/index.ts"],"names":[],"mappings":";;;;AAsEO,SAAS,WAAA,CACd,SACA,KAAA,GAAoC,CAAC,QAAQ,GAAA,EAC7C,OAAA,GAA8B,EAAC,EACJ;AAG3B,EAAA,IAAI,OAAiB,OAAA,IAAW,IAAA;AAGhC,EAAA,IAAI,OAAA,GAAU,CAAA;AAEd,EAAA,MAAM,IAAA,GAAiB;AAAA,IACrB,MAAM,IAAA,GAAyB;AAC7B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA;AAAA,IACA,MAAM,KAAK,KAAA,EAAyB;AAClC,MAAA,IAAA,GAAO,KAAA;AACP,MAAA,OAAA,IAAW,CAAA;AAAA,IACb,CAAA;AAAA,IACA,QAAQ,GAAA,EAAwB;AAC9B,MAAA,OAAO,MAAM,GAAG,CAAA;AAAA,IAClB;AAAA,GACF;AACA,EAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,IAAA,EAAM,OAAO,IAAA;AAEpC,EAAA,OAAO;AAAA,IACL,GAAG,IAAA;AAAA,IACH,MAAA,EAAQ,IAAA;AAAA,IACR,MAAM,UAAA,GAAyD;AAC7D,MAAA,OAAO,EAAE,GAAA,EAAK,IAAA,EAAM,OAAA,EAAQ;AAAA,IAC9B,CAAA;AAAA,IACA,MAAM,UAAA,CAAW,KAAA,EAAU,eAAA,EAA0C;AAInE,MAAA,IAAI,YAAY,eAAA,EAAiB;AAC/B,QAAA,MAAM,IAAI,kBAAA,CAAmB,eAAA,EAAiB,OAAO,CAAA;AAAA,MACvD;AACA,MAAA,IAAA,GAAO,KAAA;AACP,MAAA,OAAA,IAAW,CAAA;AACX,MAAA,OAAO,OAAA;AAAA,IACT;AAAA,GACF;AACF","file":"index.js","sourcesContent":["/**\n * @packageDocumentation\n * @demlik/tea/mem — in-memory `Store<S>` adapter for `@demlik/tea`.\n *\n * The standard test adapter — used everywhere a Worker or DO would be\n * overkill. Mirrors the source-only convention from `packages/widget-engine`\n * and `packages/tea` (no build step).\n *\n * Reference semantics, NOT deep-clone semantics:\n *   - `save(state)` stores the reference; subsequent mutations to that\n *     reference by the caller are observable through later `load()` calls.\n *   - `load()` returns the stored reference; mutations made through it are\n *     observable on the next `load()`.\n *\n * This matches what a real KV/DO `get()` would NOT do (those serialize +\n * deserialize), but it also matches what an in-memory cache obviously does.\n * Adding a deep clone here would lie about the boundary and impose a JSON\n * round-trip on every test. Tests that need fresh copies should clone at the\n * call site.\n *\n * Boundary parse (invariant 8): `Store<S>` requires `migrate(raw)`. For\n * `memoryStore` we ship a permissive identity-default — `(raw) => raw as\n * S | null` — because this adapter is a degenerate same-process boundary:\n * there is no serialization, the reference we read is structurally the\n * reference we wrote. The `as` cast here is the documented exception to the\n * invariant-8 no-`as` rule, scoped to the parameter default. Callers that\n * want strict parsing (e.g. a test that hand-seeds the cell from outside)\n * may pass an explicit `parse` to override.\n */\n\nimport type { FencedStore, Store } from \"../index\";\nimport { StoreConflictError } from \"../index\";\n\n/** Options for {@link memoryStore}. */\nexport interface MemoryStoreOptions {\n  /**\n   * Refuse a second live writer (#143). With `{ fenced: true }` the returned\n   * store is a `FencedStore<S>` whose version is an in-process counter — honest\n   * for this adapter, since the cell it guards is in this process too. Two\n   * `run`s handed the SAME `memoryStore` are the case it catches, and it is the\n   * cheapest way to exercise the fenced path in a test.\n   */\n  readonly fenced?: true;\n}\n\n/**\n * Build an in-memory `Store<S>`.\n *\n * @param initial - optional seed value. `undefined` and explicit `null` both\n *   mean \"no seed\"; `load()` resolves with `null` until the first `save()`.\n *   A concrete `S` seed is returned by `load()` until overwritten.\n * @param parse - optional boundary parse for the `Store<S>.migrate` contract.\n *   Defaults to identity (`(raw) => raw as S | null`) — honest for this\n *   adapter's degenerate same-process boundary. Pass an explicit parser when\n *   the test wants to reject seeded shapes that don't match `S`.\n */\nexport function memoryStore<S>(\n  initial?: S | null,\n  parse?: (raw: unknown) => S | null,\n): Store<S>;\nexport function memoryStore<S>(\n  initial: S | null | undefined,\n  parse: ((raw: unknown) => S | null) | undefined,\n  options: MemoryStoreOptions & { readonly fenced: true },\n): FencedStore<S>;\nexport function memoryStore<S>(\n  initial?: S | null,\n  parse?: (raw: unknown) => S | null,\n  options?: MemoryStoreOptions,\n): Store<S> | FencedStore<S>;\nexport function memoryStore<S>(\n  initial?: S | null,\n  parse: (raw: unknown) => S | null = (raw) => raw as S | null,\n  options: MemoryStoreOptions = {},\n): Store<S> | FencedStore<S> {\n  // Single internal cell — `undefined` and `null` collapse to one\n  // representation so the load site is branchless.\n  let cell: S | null = initial ?? null;\n  // The version the cell was last written at. A never-written cell reads `0`,\n  // matching `fileStore`'s absent stamp.\n  let version = 0;\n\n  const base: Store<S> = {\n    async load(): Promise<unknown> {\n      return cell;\n    },\n    async save(state: S): Promise<void> {\n      cell = state;\n      version += 1;\n    },\n    migrate(raw: unknown): S | null {\n      return parse(raw);\n    },\n  };\n  if (options.fenced !== true) return base;\n\n  return {\n    ...base,\n    fenced: true,\n    async loadFenced(): Promise<{ raw: unknown; version: number }> {\n      return { raw: cell, version };\n    },\n    async saveFenced(state: S, expectedVersion: number): Promise<number> {\n      // No lock: the whole store is one process's memory, and this body has no\n      // await before the compare, so nothing can interleave between the check\n      // and the write.\n      if (version !== expectedVersion) {\n        throw new StoreConflictError(expectedVersion, version);\n      }\n      cell = state;\n      version += 1;\n      return version;\n    },\n  };\n}\n"]}

package/dist/node/index.d.ts

@@ -1,8 +1,7 @@
 import WebSocket from 'ws';
-import { S as Store, F as FencedStore } from '../runtime-types-LWDoi943.js';
-import { S as Sub, c as SubId } from '../core-CTzMJ82M.js';
-import 'better-result';
-import 'zod';
+import { S as Store, F as FencedStore } from '../runtime-types-CiVpC0HN.js';
+import { S as Sub, h as Dispose } from '../core-BbgtiXdg.js';
+import '@standard-schema/spec';
 
 /**
  * @packageDocumentation
@@ -94,29 +93,33 @@ interface Journal<R> {
  *      Use for resumable scripts / local repro of prod machines. Ephemeral
  *      CLIs can skip persistence with `memoryStore` from `@demlik/tea/mem`.
  *
- *   2. `nodeSubscribe<M, Ctx>()` — handler registry for the three node-native
- *      Sub types this package owns:
- *        - `node_ws`     — opens a `ws` WebSocket; routes open/message/close/
- *                          error into Msgs. Registers the live socket in
- *                          `ctx.wsRegistry` so a Cmd handler can write to it
- *                          (see `sendToWebSocket`). Cleanup closes the socket
- *                          for ANY non-CLOSED state.
- *        - `node_timer`  — setTimeout / setInterval; cleanup clears it.
- *        - `node_signal` — a process signal (SIGINT/SIGTERM/…) → Msg; cleanup
- *                          detaches the listener.
+ *   2. `nodeSubscribe<M, Ctx>({ ws })` — the runners for the three node-native
+ *      Sub types this package owns, handed to `run` as its `subscribe`:
+ *        - `node_ws`     — deps `{ key, url }`. Opens a `ws` WebSocket; routes
+ *                          open/message/close/error into Msgs through the `ws`
+ *                          handlers. Registers the live socket in
+ *                          `ctx.wsRegistry` under `key` so a Cmd handler can
+ *                          write to it (see `sendToWebSocket`). Cleanup closes
+ *                          the socket for ANY non-CLOSED state.
+ *        - `node_timer`  — deps `{ delayMs, msg, repeat? }`. setTimeout /
+ *                          setInterval; cleanup clears it.
+ *        - `node_signal` — deps `{ signal, msg }`. A process signal
+ *                          (SIGINT/SIGTERM/…) → Msg; cleanup detaches the
+ *                          listener.
  *
  * Unlike tea-do — whose `alarm()` / `webSocketMessage()` are DO lifecycle
  * methods the handler can't observe from the outside, hence its registries —
- * a node process is continuously alive: each handler holds its resource in
- * closure and the returned cleanup closes it. The substrate's subscription
- * reconciler runs that cleanup the instant `subscriptions(state)` stops listing
- * the Sub — end-then-start choreography for free (Rule 9, [invariant 4]).
- * A lifecycle-bound resource (a socket, a timer) becomes impossible to leak
- * from a reducer cell, because no reducer cell owns its teardown.
+ * a node process is continuously alive: each runner holds its resource in
+ * closure and the returned cleanup closes it. The engine runs that cleanup the
+ * instant the Sub's `deps` go null, and a changed `deps` value stops the old
+ * runner before starting the new one — end-then-start choreography for free
+ * (Rule 9, [invariant 4]). A lifecycle-bound resource (a socket, a timer)
+ * becomes impossible to leak from a reducer cell, because no reducer cell owns
+ * its teardown.
  *
- * `ctx.wsRegistry` is the one shared surface: `node_ws` populates it; a Cmd
- * interpreter reads it to write to the open socket. Same shape as tea-do's
- * `wsRegistry`.
+ * `ctx.wsRegistry` is the one shared surface: `node_ws` populates it, keyed by
+ * the Sub's `deps.key`; a Cmd interpreter reads it to write to the open
+ * socket. Same shape as tea-do's `wsRegistry`.
  */
 
 /**
@@ -180,83 +183,121 @@ interface FileStoreOptions {
  */
 declare function fileJournal<R>(dir: string, parse: (raw: unknown) => R): Journal<R>;
 /**
- * A node WebSocket sub. The substrate diffs subs by `id`; the same `id` across
- * transitions = the same socket (kept open). Emit a DIFFERENT `id` to force a
- * reconnect.
+ * The `deps` of a `node_ws` Sub: which socket (`key`) and where it connects
+ * (`url`). Both are plain data, so the engine derives the Sub's id from them —
+ * the same `{ key, url }` across transitions is the same socket (kept open),
+ * and a changed one closes it and opens a fresh one.
  *
- * Only `onMessage` returns `M | null` (null drops the frame) because inbound
- * frames are the boundary that needs a parse-and-maybe-discard seam. `onOpen`/
- * `onClose`/`onError` always dispatch — a spurious one is dropped in the reducer
- * (the cell ignores it), not here.
+ * `key` is the author's name for the socket: the Cmd side addresses it through
+ * {@link sendToWebSocket} by that key, since the derived Sub id is not
+ * something a Cmd handler can know. It must be unique among the machine's live
+ * `node_ws` Subs.
  */
-type NodeWsSub<M> = {
-    id: SubId;
-    type: "node_ws";
-    url: string;
-    onMessage: (data: string) => M | null;
-    onOpen?: () => M;
-    onClose?: (code: number, reason: string) => M;
-    onError?: (message: string) => M;
+type NodeWsDeps = {
+    readonly key: string;
+    readonly url: string;
 };
 /**
- * A node timer sub. One-shot `setTimeout` by default; `repeat: true` →
- * `setInterval`. Cleanup clears the timer — a timer keyed to a phase is
- * cancelled the moment the machine leaves that phase.
+ * A node WebSocket sub. Its callbacks are not data, so they live on the runner
+ * side — {@link NodeWsHandlers}, handed to {@link nodeSubscribe}.
+ */
+type NodeWsSub = Sub<"node_ws", NodeWsDeps>;
+/**
+ * The `deps` of a `node_timer` Sub. One-shot `setTimeout` by default;
+ * `repeat: true` → `setInterval`.
  */
-type NodeTimerSub<M> = {
-    id: SubId;
-    type: "node_timer";
-    delayMs: number;
-    msg: M;
-    repeat?: boolean;
+type NodeTimerDeps<M> = {
+    readonly delayMs: number;
+    readonly msg: M;
+    readonly repeat?: boolean;
 };
 /**
- * A process-signal sub: `signal` (SIGINT/SIGTERM/…) → `msg`. Cleanup detaches
- * the listener. Lets graceful shutdown be a real machine transition rather than
- * an out-of-band `process.on` that the reducer can't see.
+ * A node timer sub. Cleanup clears the timer — a timer keyed to a phase is
+ * cancelled the moment the machine leaves that phase, and a changed
+ * `delayMs` / `msg` / `repeat` is a new id, so the timer restarts. For a plain
+ * one-shot, the engine's built-in `timer` Sub needs no runner at all.
  */
-type NodeSignalSub<M> = {
-    id: SubId;
-    type: "node_signal";
-    signal: NodeJS.Signals;
-    msg: M;
+type NodeTimerSub<M> = Sub<"node_timer", NodeTimerDeps<M>>;
+/** The `deps` of a `node_signal` Sub: `signal` (SIGINT/SIGTERM/…) → `msg`. */
+type NodeSignalDeps<M> = {
+    readonly signal: NodeJS.Signals;
+    readonly msg: M;
 };
-type NodeSub<M> = NodeWsSub<M> | NodeTimerSub<M> | NodeSignalSub<M>;
-type AssertNodeSubIsSub<T extends Sub = NodeSub<unknown>> = T;
-type NodeWsRegistry = Map<SubId, WebSocket>;
 /**
- * The Ctx fields the node Subs depend on. A consumer's Ctx must extend this so
- * `node_ws` can register the live socket and Cmd handlers can reach it.
+ * A process-signal sub. Cleanup detaches the listener. Lets graceful shutdown
+ * be a real machine transition rather than an out-of-band `process.on` that the
+ * reducer can't see.
+ */
+type NodeSignalSub<M> = Sub<"node_signal", NodeSignalDeps<M>>;
+type NodeSub<M> = NodeWsSub | NodeTimerSub<M> | NodeSignalSub<M>;
+/** The live `node_ws` sockets, keyed by each Sub's `deps.key`. */
+type NodeWsRegistry = Map<string, WebSocket>;
+/**
+ * The Ctx fields the `node_ws` runner depends on. A consumer's Ctx must extend
+ * this so the runner can register the live socket and Cmd handlers can reach
+ * it.
  *
  * Deliberately NOT parameterized by Msg: the registry holds raw `WebSocket`s,
- * and each Sub variant carries its own Msg-typed callbacks. Trip-wire: if a
- * future node Sub holds a Msg-typed callback on ctx, this becomes
- * `NodeSubscribeCtx<M>`.
+ * and the Msg-typed callbacks live in the {@link NodeWsHandlers} handed to
+ * `nodeSubscribe`. Trip-wire: if a future node Sub holds a Msg-typed callback
+ * on ctx, this becomes `NodeSubscribeCtx<M>`.
  */
 interface NodeSubscribeCtx {
     wsRegistry: NodeWsRegistry;
 }
 /**
- * Write a frame to a registered `node_ws` socket. No-op (returns `false`) when
- * the socket is absent, not OPEN, or `send()` throws. The Cmd-side companion to
- * the `node_ws` Sub: the Sub owns the socket's lifetime; this writes to it.
+ * Write a frame to the `node_ws` socket whose `deps.key` is `key`. No-op
+ * (returns `false`) when the socket is absent, not OPEN, or `send()` throws.
+ * The Cmd-side companion to the `node_ws` Sub: the Sub owns the socket's
+ * lifetime; this writes to it.
  *
  * The contract is a boolean no-op, never a throw: the socket can transition out
  * of OPEN between the `readyState` check and `send()` (or `ws` can throw on an
  * errored underlying connection), and a Cmd interpreter must not crash on that.
  */
-declare function sendToWebSocket(ctx: NodeSubscribeCtx, id: SubId, data: string): boolean;
+declare function sendToWebSocket(ctx: NodeSubscribeCtx, key: string, data: string): boolean;
 /**
- * Build the `subscribe` handlers for `node_ws`, `node_timer`, and
- * `node_signal`. Matches `Machine#subscribe`'s
- * `[K in U["type"]]: (sub, ctx, dispatch) => () => void` contract for the
- * `NodeSub<M>` variants. Generic `Ctx` must extend `NodeSubscribeCtx` so the
- * `node_ws` handler can register its socket.
+ * What a `node_ws` socket's events become. Functions cannot be `deps`, so they
+ * live here, on the runner side; each receives the running Sub so one handler
+ * table can branch on `sub.deps` (its `key` or `url`) when a machine runs more
+ * than one socket.
+ *
+ * Only `onMessage` returns `M | null` (null drops the frame) because inbound
+ * frames are the boundary that needs a parse-and-maybe-discard seam. `onOpen`/
+ * `onClose`/`onError` always dispatch — a spurious one is dropped in the reducer
+ * (the cell ignores it), not here. An omitted one dispatches nothing.
  */
-declare function nodeSubscribe<M, Ctx extends NodeSubscribeCtx>(): {
-    node_ws: (sub: NodeWsSub<M>, ctx: Ctx, dispatch: (msg: M) => void) => () => void;
-    node_timer: (sub: NodeTimerSub<M>, ctx: Ctx, dispatch: (msg: M) => void) => () => void;
-    node_signal: (sub: NodeSignalSub<M>, ctx: Ctx, dispatch: (msg: M) => void) => () => void;
-};
+interface NodeWsHandlers<M> {
+    onMessage(data: string, sub: NodeWsSub): M | null;
+    onOpen?(sub: NodeWsSub): M;
+    onClose?(code: number, reason: string, sub: NodeWsSub): M;
+    onError?(message: string, sub: NodeWsSub): M;
+}
+/** The options of {@link nodeSubscribe}: the `node_ws` handlers, when used. */
+interface NodeSubscribeOpts<M> {
+    readonly ws: NodeWsHandlers<M>;
+}
+/** The `node_timer` + `node_signal` runners — what every `nodeSubscribe` returns. */
+interface NodeSubscribeBase<M> {
+    node_timer: (sub: NodeTimerSub<M>, ctx: unknown, dispatch: (msg: M) => void) => Dispose;
+    node_signal: (sub: NodeSignalSub<M>, ctx: unknown, dispatch: (msg: M) => void) => Dispose;
+}
+/** The full runner table, with `node_ws` — `nodeSubscribe({ ws })`. */
+interface NodeSubscribeWithWs<M, Ctx extends NodeSubscribeCtx> extends NodeSubscribeBase<M> {
+    node_ws: (sub: NodeWsSub, ctx: Ctx, dispatch: (msg: M) => void) => Dispose;
+}
+/**
+ * Build the `subscribe` runners for the node Sub types, to hand to `run`:
+ * `run(machine, { subscribe: nodeSubscribe<M, Ctx>({ ws: { onMessage } }), ctx })`.
+ *
+ * `node_timer` and `node_signal` read everything off `sub.deps`, so they need
+ * no options. `node_ws` needs its {@link NodeWsHandlers}; called without them,
+ * the table has no `node_ws` runner, so a machine that declares `NodeWsSub`
+ * fails to typecheck at `run` rather than opening a socket nobody listens to.
+ * `Ctx` must extend {@link NodeSubscribeCtx} so the `node_ws` runner can
+ * register its socket.
+ */
+declare function nodeSubscribe<M>(): NodeSubscribeBase<M>;
+declare function nodeSubscribe<M, Ctx extends NodeSubscribeCtx>(opts: NodeSubscribeOpts<M>): NodeSubscribeWithWs<M, Ctx>;
 
-export { type AssertNodeSubIsSub, type FileStoreOptions, type NodeSignalSub, type NodeSub, type NodeSubscribeCtx, type NodeTimerSub, type NodeWsRegistry, type NodeWsSub, fileJournal, fileStore, nodeSubscribe, sendToWebSocket };
+export { type FileStoreOptions, type NodeSignalDeps, type NodeSignalSub, type NodeSub, type NodeSubscribeBase, type NodeSubscribeCtx, type NodeSubscribeOpts, type NodeSubscribeWithWs, type NodeTimerDeps, type NodeTimerSub, type NodeWsDeps, type NodeWsHandlers, type NodeWsRegistry, type NodeWsSub, fileJournal, fileStore, nodeSubscribe, sendToWebSocket };

package/dist/node/index.js

@@ -1,4 +1,5 @@
-import { StoreConflictError, dispatchIfPresent } from '../chunk-RQULHGYH.js';
+import { dispatchIfPresent } from '../chunk-GOX2CYIM.js';
+import { StoreConflictError } from '../chunk-CH5KTOEZ.js';
 import { mkdir, writeFile, rename, unlink, open, readFile } from 'fs/promises';
 import { createRequire } from 'module';
 import { dirname, join } from 'path';
@@ -238,8 +239,8 @@ function loadWebSocket() {
 }
 var WS_OPEN = 1;
 var WS_CLOSED = 3;
-function sendToWebSocket(ctx, id, data) {
-  const socket = ctx.wsRegistry.get(id);
+function sendToWebSocket(ctx, key, data) {
+  const socket = ctx.wsRegistry.get(key);
   if (!socket || socket.readyState !== WS_OPEN) return false;
   try {
     socket.send(data);
@@ -248,51 +249,64 @@ function sendToWebSocket(ctx, id, data) {
     return false;
   }
 }
-function nodeSubscribe() {
-  return {
-    node_ws: (sub, ctx, dispatch) => {
-      const socket = new (loadWebSocket())(sub.url);
-      ctx.wsRegistry.set(sub.id, socket);
-      socket.on("open", () => {
-        if (sub.onOpen) dispatch(sub.onOpen());
-      });
-      socket.on("message", (data) => {
-        dispatchIfPresent(dispatch, sub.onMessage(data.toString()));
-      });
-      socket.on("close", (code, reason) => {
-        if (sub.onClose) dispatch(sub.onClose(code, reason.toString()));
-      });
-      socket.on("error", (err) => {
-        if (sub.onError) dispatch(sub.onError(err.message));
-      });
-      return () => {
-        ctx.wsRegistry.delete(sub.id);
-        socket.removeAllListeners();
-        socket.on("error", () => {
-        });
-        if (socket.readyState === WS_OPEN) {
-          socket.close(1e3, "tea-node sub cleanup");
-        } else if (socket.readyState !== WS_CLOSED) {
-          socket.terminate();
-        }
-      };
-    },
+function nodeSubscribe(opts) {
+  const base = {
     node_timer: (sub, _ctx, dispatch) => {
-      if (sub.repeat) {
-        const handle2 = setInterval(() => dispatch(sub.msg), sub.delayMs);
+      const { delayMs, msg, repeat } = sub.deps;
+      if (repeat) {
+        const handle2 = setInterval(() => dispatch(msg), delayMs);
         return () => clearInterval(handle2);
       }
-      const handle = setTimeout(() => dispatch(sub.msg), sub.delayMs);
+      const handle = setTimeout(() => dispatch(msg), delayMs);
       return () => clearTimeout(handle);
     },
     node_signal: (sub, _ctx, dispatch) => {
-      const handler = () => dispatch(sub.msg);
-      process.on(sub.signal, handler);
+      const { signal, msg } = sub.deps;
+      const handler = () => dispatch(msg);
+      process.on(signal, handler);
       return () => {
-        process.off(sub.signal, handler);
+        process.off(signal, handler);
       };
     }
   };
+  if (opts === void 0) return base;
+  return { ...base, node_ws: nodeWsRunner(opts.ws) };
+}
+function nodeWsRunner(handlers) {
+  return (sub, ctx, dispatch) => {
+    const { key, url } = sub.deps;
+    if (ctx.wsRegistry.has(key)) {
+      throw new Error(
+        `node_ws: a live socket is already registered under key "${key}" \u2014 each running node_ws Sub needs its own \`deps.key\`.`
+      );
+    }
+    const socket = new (loadWebSocket())(url);
+    ctx.wsRegistry.set(key, socket);
+    socket.on("open", () => {
+      if (handlers.onOpen) dispatch(handlers.onOpen(sub));
+    });
+    socket.on("message", (data) => {
+      dispatchIfPresent(dispatch, handlers.onMessage(data.toString(), sub));
+    });
+    socket.on("close", (code, reason) => {
+      if (handlers.onClose)
+        dispatch(handlers.onClose(code, reason.toString(), sub));
+    });
+    socket.on("error", (err) => {
+      if (handlers.onError) dispatch(handlers.onError(err.message, sub));
+    });
+    return () => {
+      ctx.wsRegistry.delete(key);
+      socket.removeAllListeners();
+      socket.on("error", () => {
+      });
+      if (socket.readyState === WS_OPEN) {
+        socket.close(1e3, "tea-node sub cleanup");
+      } else if (socket.readyState !== WS_CLOSED) {
+        socket.terminate();
+      }
+    };
+  };
 }
 
 export { fileJournal, fileStore, nodeSubscribe, sendToWebSocket };