@demlik/tea 0.12.0 → 0.14.0

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

@@ -1,4 +1,5 @@
-import { C as Cmd, S as Sub, M as Machine } from '../core-Bjc0bS8j.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-CTzMJ82M.js';
+import 'zod';
 
 /**
  * Sanitize a discriminant string into a Mermaid-safe node identifier.

package/dist/machine-viz/index.js

@@ -1,7 +1,14 @@
-import { safeId, safeLabel } from '../chunk-UOC2PL46.js';
-export { safeId, safeLabel } from '../chunk-UOC2PL46.js';
-import '../chunk-5EHLEUTL.js';
-import { formOf } from '../chunk-B5VXOFMZ.js';
+import { formOf } from '../chunk-RQULHGYH.js';
+
+// src/machine-viz/mermaid-id.ts
+function safeId(raw) {
+  const cleaned = raw.replace(/[^A-Za-z0-9_]/g, "_");
+  if (cleaned === "") return "_empty";
+  return /^[0-9]/.test(cleaned) ? `s_${cleaned}` : cleaned;
+}
+function safeLabel(raw) {
+  return raw.replace(/["\n\r;:]/g, " ").trim();
+}
 
 // src/machine-viz/index.ts
 function toMermaid(machine, opts = {}) {
@@ -124,6 +131,6 @@ function emitSubscriptions(machine, lines, stateSamples) {
   }
 }
 
-export { toMermaid };
+export { safeId, safeLabel, toMermaid };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"sources":["../../src/machine-viz/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\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 are SHARED with `chart`'s `chartMermaid` — one copy, in a\n// dependency-free module, re-exported here because both drawings are public\n// and a consumer post-processing either one 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[*]` 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"]}

package/dist/mem/index.d.ts

@@ -1,6 +1,7 @@
-import { S as Store } from '../runtime-types-Bxc637bp.js';
+import { S as Store, F as FencedStore } from '../runtime-types-LWDoi943.js';
 import 'better-result';
-import '../core-Bjc0bS8j.js';
+import '../core-CTzMJ82M.js';
+import 'zod';
 
 /**
  * @packageDocumentation
@@ -32,6 +33,17 @@ import '../core-Bjc0bS8j.js';
  * may pass an explicit `parse` to override.
  */
 
+/** Options for {@link memoryStore}. */
+interface MemoryStoreOptions {
+    /**
+     * Refuse a second live writer (#143). With `{ fenced: true }` the returned
+     * store is a `FencedStore<S>` whose version is an in-process counter — honest
+     * for this adapter, since the cell it guards is in this process too. Two
+     * `run`s handed the SAME `memoryStore` are the case it catches, and it is the
+     * cheapest way to exercise the fenced path in a test.
+     */
+    readonly fenced?: true;
+}
 /**
  * Build an in-memory `Store<S>`.
  *
@@ -44,5 +56,9 @@ import '../core-Bjc0bS8j.js';
  *   the test wants to reject seeded shapes that don't match `S`.
  */
 declare function memoryStore<S>(initial?: S | null, parse?: (raw: unknown) => S | null): Store<S>;
+declare function memoryStore<S>(initial: S | null | undefined, parse: ((raw: unknown) => S | null) | undefined, options: MemoryStoreOptions & {
+    readonly fenced: true;
+}): FencedStore<S>;
+declare function memoryStore<S>(initial?: S | null, parse?: (raw: unknown) => S | null, options?: MemoryStoreOptions): Store<S> | FencedStore<S>;
 
-export { memoryStore };
+export { type MemoryStoreOptions, memoryStore };

package/dist/mem/index.js

@@ -1,17 +1,37 @@
+import { StoreConflictError } from '../chunk-RQULHGYH.js';
+
 // src/mem/index.ts
-function memoryStore(initial, parse = (raw) => raw) {
+function memoryStore(initial, parse = (raw) => raw, options = {}) {
   let cell = initial ?? null;
-  return {
+  let version = 0;
+  const base = {
     async load() {
       return cell;
     },
     async save(state) {
       cell = state;
+      version += 1;
     },
     migrate(raw) {
       return parse(raw);
     }
   };
+  if (options.fenced !== true) return base;
+  return {
+    ...base,
+    fenced: true,
+    async loadFenced() {
+      return { raw: cell, version };
+    },
+    async saveFenced(state, expectedVersion) {
+      if (version !== expectedVersion) {
+        throw new StoreConflictError(expectedVersion, version);
+      }
+      cell = state;
+      version += 1;
+      return version;
+    }
+  };
 }
 
 export { memoryStore };

package/dist/mem/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/mem/index.ts"],"names":[],"mappings":";AA2CO,SAAS,WAAA,CACd,OAAA,EACA,KAAA,GAAoC,CAAC,QAAQ,GAAA,EACnC;AAGV,EAAA,IAAI,OAAiB,OAAA,IAAW,IAAA;AAEhC,EAAA,OAAO;AAAA,IACL,MAAM,IAAA,GAAyB;AAC7B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA;AAAA,IACA,MAAM,KAAK,KAAA,EAAyB;AAClC,MAAA,IAAA,GAAO,KAAA;AAAA,IACT,CAAA;AAAA,IACA,QAAQ,GAAA,EAAwB;AAC9B,MAAA,OAAO,MAAM,GAAG,CAAA;AAAA,IAClB;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 { Store } from \"../index\";\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 = (raw) => raw as S | null,\n): Store<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\n  return {\n    async load(): Promise<unknown> {\n      return cell;\n    },\n    async save(state: S): Promise<void> {\n      cell = state;\n    },\n    migrate(raw: unknown): S | null {\n      return parse(raw);\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,7 +1,84 @@
 import WebSocket from 'ws';
-import { S as Store } from '../runtime-types-Bxc637bp.js';
-import { S as Sub, b as SubId } from '../core-Bjc0bS8j.js';
+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';
+
+/**
+ * @packageDocumentation
+ * internal/journal — an append-only, ordered record log for `@demlik/tea`.
+ * Internal since #49 — not published on any subpath; `fileJournal` on
+ * `@demlik/tea/node` is the one public route.
+ *
+ * The log a "durable, replayable state machine" replays from. tea already ships
+ * the log's neighbours — `fileStore`/`memoryStore` (`Store<S>`: snapshot with
+ * whole-load / whole-save), `recorder` (JSONL debug traces), `durable-effects`
+ * (`foldLedger` over an owed-effect ledger) — but not the log itself, so every
+ * consumer hand-rolled it. This is that log, domain-blind: a `Journal<R>` over
+ * an opaque record `R`, with no pipeline/ledger vocabulary of its own.
+ *
+ * Three operations carry the contract:
+ *   - `append(stream, record)` — durable before it returns, assigning a
+ *     per-stream total-order `seq` (1, 2, 3, …). Concurrent appenders to one
+ *     stream converge on one order; the lock's only job is an honest order key.
+ *   - `list(stream)` — every entry of a stream in `seq` order.
+ *   - `changes(listener)` — a subscription over appends made through this
+ *     instance after subscribing.
+ *
+ * `withLock(stream, fx)` runs `fx` with exclusive access to a stream, so a
+ * read-decide-append sequence is atomic against other writers. It is
+ * re-entrant for the same stream: an `append` inside `fx` does not deadlock on
+ * the lock `fx` already holds.
+ *
+ * The substrate is a `JournalBackend<R>` — how a stream is read, how one record
+ * is appended durably, and how a stream is locked across processes.
+ * `makeJournal` wires the domain-blind orchestration (per-stream serialisation,
+ * `seq` assignment, `changes` fan-out) over any backend. `memoryJournal` is the
+ * in-process backend that mirrors `memoryStore` for tests; the Node file
+ * backend (`fileJournal`) homes in `@demlik/tea/node` beside `fileStore`.
+ *
+ * Interface shape follows Effect `unstable/eventlog` `EventJournal`
+ * (`entries`/`write`/`changes`/`withLock`) as prior art, not a dependency.
+ */
+/** A per-stream total-order key. Starts at 1 and increments by one per append. */
+type Seq = number;
+/** One appended record, tagged with its stream and its per-stream `seq`. */
+interface JournalEntry<R> {
+    readonly stream: string;
+    readonly seq: Seq;
+    readonly record: R;
+}
+/**
+ * An append-only, ordered record log over an opaque record `R`.
+ *
+ * Domain-blind: it knows nothing of what a record means. Ordering, durability
+ * and the honest order key are its whole contract.
+ */
+interface Journal<R> {
+    /**
+     * Append `record` to `stream`, durable before the promise resolves, and
+     * resolve with the `seq` it was assigned — the next integer in the stream's
+     * total order.
+     */
+    append(stream: string, record: R): Promise<{
+        seq: Seq;
+    }>;
+    /** Every entry of `stream`, in `seq` order. Empty for an unwritten stream. */
+    list(stream: string): Promise<ReadonlyArray<JournalEntry<R>>>;
+    /**
+     * Subscribe to appends made through this instance after this call. Returns an
+     * unsubscribe. Cross-process appends are not delivered — a cross-process
+     * subscription is a polling concern this log leaves to its consumer.
+     */
+    changes(listener: (entry: JournalEntry<R>) => void): () => void;
+    /**
+     * Run `fx` with exclusive access to `stream` — the in-process mutex against
+     * other callers here, the backend lock against other processes. Re-entrant
+     * for the same stream, so an `append` (or nested `withLock`) inside `fx` runs
+     * under the lock this call already holds rather than deadlocking on it.
+     */
+    withLock<A>(stream: string, fx: () => Promise<A>): Promise<A>;
+}
 
 /**
  * @packageDocumentation
@@ -43,7 +120,9 @@ import 'better-result';
  */
 
 /**
- * `Store<S>` backed by a JSON file at `path`.
+ * Persist a machine's state to a JSON file — pass the `path` and a `parse` that
+ * validates what comes back, get a `Store<S>` you hand to `run` so the next run
+ * resumes where this one stopped.
  *
  * `parse` is REQUIRED because the file is a real serialization boundary — the
  * bytes that come back through `JSON.parse` are structurally `unknown`, and the
@@ -51,8 +130,55 @@ import 'better-result';
  * Returning `null` from `parse` means "no usable persisted state" — the
  * substrate boots `init` with `loaded = null`. `parse` must NOT throw per the
  * `Store<S>.migrate` contract.
+ *
+ * Pass `{ fenced: true }` to get a `FencedStore<S>` instead — see
+ * {@link FileStoreOptions}.
  */
 declare function fileStore<S>(path: string, parse: (raw: unknown) => S | null): Store<S>;
+declare function fileStore<S>(path: string, parse: (raw: unknown) => S | null, options: FileStoreOptions & {
+    readonly fenced: true;
+}): FencedStore<S>;
+declare function fileStore<S>(path: string, parse: (raw: unknown) => S | null, options?: FileStoreOptions): Store<S> | FencedStore<S>;
+/** Options for {@link fileStore}. */
+interface FileStoreOptions {
+    /**
+     * Refuse a second live writer (#143). With `{ fenced: true }` the returned
+     * store is a `FencedStore<S>`: it carries a version stamp beside the state
+     * file, and `run` compare-and-swaps against it on every save. A process that
+     * boots reads the current version and takes the fence; the older live writer
+     * that started from the same version is refused with a `StoreConflictError`
+     * at its next save. Omit it and the store is exactly as it was — the last
+     * writer wins, and single-writer is the caller's precondition to keep.
+     */
+    readonly fenced?: true;
+}
+/**
+ * The Node file substrate for the journal (`src/internal/journal/`), beside
+ * `fileStore`. A
+ * stream is one JSONL file under `dir` (`<encoded-stream>.jsonl`), one
+ * `{"seq":n,"record":…}` object per line — readable and greppable on disk, no
+ * SQLite. `parse` is REQUIRED for the same reason `fileStore` requires it: the
+ * bytes read back through `JSON.parse` are structurally `unknown`, and the
+ * caller who owns `R` is the only party that can validate a record's shape.
+ *
+ * `append` rewrites the whole stream file via a pid-scoped temp + `rename`,
+ * exactly as `fileStore.save` does — a reader sees the old file or the new one,
+ * never a torn line, and the write survives a crash mid-append. The append is
+ * O(n) in the stream's length; a durable record log a machine replays is read
+ * whole anyway, so the atomic-rewrite guarantee is worth the cost.
+ *
+ * The ordering key is taken under a `wx` lock file (`<file>.lock`) holding the
+ * writer's PID: a second writer racing the same stream blocks on the lock, so
+ * `seq` is a single total order across processes. A crashed writer's lock is
+ * stolen once its PID proves dead (`process.kill(pid, 0)` → `ESRCH`), so a
+ * crash never wedges the stream. This is the lock phoenix spike #6673 proved:
+ * its only job is an honest order key, not the win.
+ *
+ * `changes` fires for appends made through THIS instance; a cross-process
+ * append lands on disk but is not broadcast here (that is a polling concern the
+ * log leaves to its consumer, and the remote-journal work downstream).
+ */
+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
@@ -133,4 +259,4 @@ declare function nodeSubscribe<M, Ctx extends NodeSubscribeCtx>(): {
     node_signal: (sub: NodeSignalSub<M>, ctx: Ctx, dispatch: (msg: M) => void) => () => void;
 };
 
-export { type AssertNodeSubIsSub, type NodeSignalSub, type NodeSub, type NodeSubscribeCtx, type NodeTimerSub, type NodeWsRegistry, type NodeWsSub, fileStore, nodeSubscribe, sendToWebSocket };
+export { type AssertNodeSubIsSub, type FileStoreOptions, type NodeSignalSub, type NodeSub, type NodeSubscribeCtx, type NodeTimerSub, type NodeWsRegistry, type NodeWsSub, fileJournal, fileStore, nodeSubscribe, sendToWebSocket };

package/dist/node/index.js

@@ -1,10 +1,68 @@
-import { dispatchIfPresent } from '../chunk-ZJ5AOYBH.js';
-import { mkdir, writeFile, rename, readFile } from 'fs/promises';
-import { dirname } from 'path';
-import WebSocket from 'ws';
+import { StoreConflictError, dispatchIfPresent } from '../chunk-RQULHGYH.js';
+import { mkdir, writeFile, rename, unlink, open, readFile } from 'fs/promises';
+import { createRequire } from 'module';
+import { dirname, join } from 'path';
+import { AsyncLocalStorage } from 'async_hooks';
 
-function fileStore(path, parse) {
+var AsyncLock = class {
+  tail = Promise.resolve();
+  run(fx) {
+    const result = this.tail.then(fx, fx);
+    this.tail = result.then(
+      () => void 0,
+      () => void 0
+    );
+    return result;
+  }
+};
+function makeJournal(backend) {
+  const mutexes = /* @__PURE__ */ new Map();
+  const heldStreams = new AsyncLocalStorage();
+  const listeners = /* @__PURE__ */ new Set();
+  const mutexFor = (stream) => {
+    let mutex = mutexes.get(stream);
+    if (!mutex) {
+      mutex = new AsyncLock();
+      mutexes.set(stream, mutex);
+    }
+    return mutex;
+  };
+  const exclusive = (stream, fx) => {
+    const held = heldStreams.getStore();
+    if (held?.has(stream)) return fx();
+    return mutexFor(stream).run(
+      () => backend.lock(stream, () => {
+        const nested = new Set(held).add(stream);
+        return heldStreams.run(nested, fx);
+      })
+    );
+  };
   return {
+    append(stream, record) {
+      return exclusive(stream, async () => {
+        const entry = await backend.append(stream, record);
+        for (const listener of listeners) listener(entry);
+        return { seq: entry.seq };
+      });
+    },
+    list(stream) {
+      return Promise.resolve(backend.read(stream));
+    },
+    changes(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    withLock(stream, fx) {
+      return exclusive(stream, fx);
+    }
+  };
+}
+
+// src/node/index.ts
+function fileStore(path, parse, options = {}) {
+  const base = {
     async load() {
       let raw;
       try {
@@ -25,10 +83,164 @@ function fileStore(path, parse) {
       return parse(raw);
     }
   };
+  return options.fenced === true ? fenceFileStore(base, path) : base;
+}
+function fenceFileStore(base, path) {
+  const fencePath = `${path}.fence`;
+  const lockPath = `${path}.fence.lock`;
+  async function readVersion() {
+    let raw;
+    try {
+      raw = await readFile(fencePath, "utf8");
+    } catch (err) {
+      if (err.code === "ENOENT") return 0;
+      throw err;
+    }
+    const version = Number.parseInt(raw.trim(), 10);
+    if (!Number.isSafeInteger(version) || version < 0) {
+      throw new Error(
+        `fileStore: version stamp at "${fencePath}" is not an integer: ${raw}`
+      );
+    }
+    return version;
+  }
+  return {
+    ...base,
+    fenced: true,
+    async loadFenced() {
+      const version = await readVersion();
+      return { raw: await base.load(), version };
+    },
+    async saveFenced(state, expectedVersion) {
+      await mkdir(dirname(path), { recursive: true });
+      await acquireFileLock(dirname(path), lockPath);
+      try {
+        const actual = await readVersion();
+        if (actual !== expectedVersion) {
+          throw new StoreConflictError(expectedVersion, actual);
+        }
+        const next = expectedVersion + 1;
+        await base.save(state);
+        const tmp = `${fencePath}.${process.pid}.tmp`;
+        await writeFile(tmp, String(next), "utf8");
+        await rename(tmp, fencePath);
+        return next;
+      } finally {
+        await unlink(lockPath).catch(() => {
+        });
+      }
+    }
+  };
+}
+var LOCK_SPIN_MS = 10;
+function fileJournal(dir, parse) {
+  const streamPath = (stream) => join(dir, `${encodeURIComponent(stream)}.jsonl`);
+  const readEntries = async (stream) => {
+    const path = streamPath(stream);
+    let raw;
+    try {
+      raw = await readFile(path, "utf8");
+    } catch (err) {
+      if (err.code === "ENOENT") return [];
+      throw err;
+    }
+    return raw.split("\n").filter((line) => line.length > 0).map((line) => {
+      const row = JSON.parse(line);
+      return { stream, seq: row.seq, record: parse(row.record) };
+    });
+  };
+  return makeJournal({
+    read: readEntries,
+    async append(stream, record) {
+      const entries = await readEntries(stream);
+      const entry = {
+        stream,
+        seq: entries.length + 1,
+        record
+      };
+      const path = streamPath(stream);
+      const lines = [...entries, entry].map((e) => JSON.stringify({ seq: e.seq, record: e.record })).join("\n");
+      await mkdir(dir, { recursive: true });
+      const tmp = `${path}.${process.pid}.tmp`;
+      await writeFile(tmp, `${lines}
+`, "utf8");
+      await rename(tmp, path);
+      return entry;
+    },
+    async lock(stream, fx) {
+      const lockPath = `${streamPath(stream)}.lock`;
+      await acquireFileLock(dir, lockPath);
+      try {
+        return await fx();
+      } finally {
+        await unlink(lockPath).catch(() => {
+        });
+      }
+    }
+  });
+}
+async function acquireFileLock(dir, lockPath) {
+  await mkdir(dir, { recursive: true });
+  for (; ; ) {
+    try {
+      const handle = await open(lockPath, "wx");
+      try {
+        await handle.writeFile(String(process.pid));
+      } finally {
+        await handle.close();
+      }
+      return;
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      if (await stealIfStale(lockPath)) continue;
+      await new Promise((resolve) => setTimeout(resolve, LOCK_SPIN_MS));
+    }
+  }
+}
+async function stealIfStale(lockPath) {
+  let holder;
+  try {
+    holder = await readFile(lockPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return true;
+    throw err;
+  }
+  const pid = Number(holder.trim());
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (isProcessAlive(pid)) return false;
+  await unlink(lockPath).catch(() => {
+  });
+  return true;
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+var cachedWs;
+function loadWebSocket() {
+  if (cachedWs) return cachedWs;
+  let mod;
+  try {
+    mod = createRequire(import.meta.url)("ws");
+  } catch (cause) {
+    throw new Error(
+      'The `node_ws` Sub needs the optional peer dependency "ws". Install it: `npm install ws`.',
+      { cause }
+    );
+  }
+  const ctor = mod.default ?? mod;
+  cachedWs = ctor;
+  return cachedWs;
 }
+var WS_OPEN = 1;
+var WS_CLOSED = 3;
 function sendToWebSocket(ctx, id, data) {
   const socket = ctx.wsRegistry.get(id);
-  if (!socket || socket.readyState !== WebSocket.OPEN) return false;
+  if (!socket || socket.readyState !== WS_OPEN) return false;
   try {
     socket.send(data);
     return true;
@@ -39,7 +251,7 @@ function sendToWebSocket(ctx, id, data) {
 function nodeSubscribe() {
   return {
     node_ws: (sub, ctx, dispatch) => {
-      const socket = new WebSocket(sub.url);
+      const socket = new (loadWebSocket())(sub.url);
       ctx.wsRegistry.set(sub.id, socket);
       socket.on("open", () => {
         if (sub.onOpen) dispatch(sub.onOpen());
@@ -58,9 +270,9 @@ function nodeSubscribe() {
         socket.removeAllListeners();
         socket.on("error", () => {
         });
-        if (socket.readyState === WebSocket.OPEN) {
+        if (socket.readyState === WS_OPEN) {
           socket.close(1e3, "tea-node sub cleanup");
-        } else if (socket.readyState !== WebSocket.CLOSED) {
+        } else if (socket.readyState !== WS_CLOSED) {
           socket.terminate();
         }
       };
@@ -83,6 +295,6 @@ function nodeSubscribe() {
   };
 }
 
-export { fileStore, nodeSubscribe, sendToWebSocket };
+export { fileJournal, fileStore, nodeSubscribe, sendToWebSocket };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map