@demlik/tea 0.1.0 → 0.1.1

package/dist/raft/demo.d.ts

@@ -0,0 +1,105 @@
+import { NodeId, RaftState, RaftConfig } from './index.js';
+import { SimTrace, Schedule } from './sim.js';
+import '../deadline/index.js';
+import '../core-CymXZCeY.js';
+import '../types-N9LZbdnr.js';
+
+/**
+ * @demlik/tea/raft — a runnable, deterministic multi-node Raft demo (#123,
+ * stories 7+8 of epic #117). The live demo the docs reference: it boots a
+ * 3-node cluster and drives the full consensus arc through {@link runSchedule}
+ * — elect a leader, replicate + commit a client command to a majority, KILL the
+ * leader (a network partition), watch the surviving majority elect a NEW leader,
+ * and show the committed log converged across the survivors.
+ *
+ * It is a thin, readable composition over the existing simulation harness
+ * (`./sim`): every phase is just a slice of one fixed {@link Schedule}, so the
+ * whole run is pure, replayable, and byte-identical on re-run (the determinism
+ * the safety suite already enforces — here turned into a watchable narrative).
+ * It owns NO clock, NO RNG, NO IO beyond an optional narration printer.
+ *
+ * Two entry points:
+ *   - {@link runDemo} — fold the scripted schedule, return a structured
+ *     {@link DemoResult} (the phases, the per-phase cluster summary, the final
+ *     trace). Pure: it asserts nothing and prints nothing — the test and the
+ *     CLI both read its result.
+ *   - {@link narrateDemo} — render a {@link DemoResult} as readable lines (the
+ *     `pnpm demo:raft` output). Pure string-building; the runner does the IO.
+ *
+ * Run it:  `pnpm --filter @demlik/tea demo:raft`
+ * (see `src/raft/README.md`).
+ */
+
+/** A compact, JSON-friendly read of one node's state (what the demo reports). */
+interface NodeSummary {
+    /** The node's id. */
+    readonly id: NodeId;
+    /** Its role this snapshot: follower / candidate / leader. */
+    readonly role: RaftState["role"]["_tag"];
+    /** Its current term. */
+    readonly term: number;
+    /** Its commit index (entries at or below this are committed). */
+    readonly commitIndex: number;
+    /** The COMMITTED commands, in log order (entries `1..commitIndex`). */
+    readonly committed: readonly number[];
+}
+/** Read one node's committed commands (the prefix of its log up to commitIndex). */
+declare function committedCommands(state: RaftState<number>): readonly number[];
+/** A snapshot of one phase's outcome: its headline + the cluster after it ran. */
+interface PhaseOutcome {
+    /** The phase headline. */
+    readonly title: string;
+    /** The phase's one-line note. */
+    readonly note: string;
+    /** The single leader after this phase, or `null`. */
+    readonly leader: NodeId | null;
+    /** Every node's summary after this phase. */
+    readonly cluster: readonly NodeSummary[];
+}
+/** The structured outcome of a full demo run — pure data, asserts nothing. */
+interface DemoResult {
+    /** The cluster node ids, in config order. */
+    readonly nodes: readonly NodeId[];
+    /** The nodes partitioned off by the end of the run (the killed leader). */
+    readonly partitioned: readonly NodeId[];
+    /** The leader elected in phase 1 (before the kill). */
+    readonly firstLeader: NodeId | null;
+    /** The leader elected in phase 4 (after the kill) — a DIFFERENT node. */
+    readonly secondLeader: NodeId | null;
+    /** The commands committed across the SURVIVING majority by the end. */
+    readonly convergedLog: readonly number[];
+    /** Per-phase outcomes, in order. */
+    readonly phases: readonly PhaseOutcome[];
+    /** The full underlying simulation trace (for replay / deep inspection). */
+    readonly trace: SimTrace;
+}
+/** The demo cluster: 3 nodes, default election-timeout window + heartbeat. */
+declare function demoCluster(): readonly RaftConfig[];
+/** The full scripted schedule (every phase's events concatenated, in order). */
+declare function demoSchedule(): Schedule;
+/**
+ * The nodes that survive the partition (everyone NOT in the down-set). The demo
+ * checks convergence over THESE — the partitioned leader is, by construction,
+ * stuck at its pre-kill log.
+ */
+declare function survivors(nodes: readonly NodeId[], partitioned: readonly NodeId[]): readonly NodeId[];
+/**
+ * Run the scripted demo against a fresh 3-node cluster and return a structured
+ * {@link DemoResult}. Pure: folds {@link demoSchedule} through {@link runSchedule},
+ * then reads the cluster at each phase boundary. Deterministic — the same
+ * schedule yields a byte-identical trace, so {@link runDemo}() === runDemo().
+ */
+declare function runDemo(): DemoResult;
+/**
+ * Render a {@link DemoResult} as a readable, deterministic narrative — the
+ * `pnpm demo:raft` output. Pure: returns the lines; the runner prints them.
+ */
+declare function narrateDemo(result: DemoResult): string;
+/**
+ * Re-run the demo's schedule from a fresh cluster and report whether the trace
+ * is byte-identical to the original run (the determinism contract). Used by the
+ * test and surfaced in the CLI footer.
+ */
+declare function demoIsReproducible(result: DemoResult): boolean;
+
+export { type DemoResult, type NodeSummary, type PhaseOutcome, committedCommands, demoCluster, demoIsReproducible, demoSchedule, narrateDemo, runDemo, survivors };

package/dist/raft/demo.js

@@ -0,0 +1,172 @@
+import { clusterConfigs, runSchedule, replaySchedule } from '../chunk-7VEG4KHB.js';
+import '../chunk-XRXKH7KA.js';
+import '../chunk-QGZW4W3E.js';
+import '../chunk-2YFLOCWX.js';
+import '../chunk-2WZHS4P2.js';
+import '../chunk-BNJYE4AU.js';
+
+// src/raft/demo.ts
+var N0 = "n0";
+var N1 = "n1";
+var FIRST_COMMAND = 42;
+var SECOND_COMMAND = 77;
+var PHASES = [
+  {
+    title: "1. Elect a leader",
+    note: "n0 times out, runs an election, and wins a majority (term 1).",
+    events: [
+      { kind: "timer", node: N0, timer: "election" },
+      { kind: "settle", bound: 30 }
+    ]
+  },
+  {
+    title: "2. Replicate + commit a command",
+    note: `client sends ${FIRST_COMMAND} to the leader; it replicates to a majority, commits, and the next heartbeat carries the commit to the followers.`,
+    events: [
+      { kind: "client", node: N0, command: FIRST_COMMAND },
+      { kind: "settle", bound: 30 },
+      // The leader's commitIndex advances on the success replies, but followers
+      // only learn it on the NEXT AppendEntries (Figure 2 `leaderCommit`). One
+      // heartbeat round propagates the commit so the cluster converges.
+      { kind: "timer", node: N0, timer: "heartbeat" },
+      { kind: "settle", bound: 30 }
+    ]
+  },
+  {
+    title: "3. Kill the leader",
+    note: "partition isolates n0 \u2014 the transport drops all traffic to/from it.",
+    events: [{ kind: "partition", down: [N0] }]
+  },
+  {
+    title: "4. A new leader is elected",
+    note: "a surviving follower (n1) times out and wins the surviving majority {n1,n2} in a higher term.",
+    events: [
+      { kind: "timer", node: N1, timer: "election" },
+      { kind: "settle", bound: 30 }
+    ]
+  },
+  {
+    title: "5. Replicate on the new leader \u2192 logs converged",
+    note: `client sends ${SECOND_COMMAND} to the new leader; it commits on the surviving majority, and a heartbeat converges the survivors' committed logs.`,
+    events: [
+      { kind: "client", node: N1, command: SECOND_COMMAND },
+      { kind: "settle", bound: 30 },
+      // Same as phase 2: a heartbeat round carries the new commitIndex to the
+      // surviving follower (n2) so every survivor's committed log converges.
+      { kind: "timer", node: N1, timer: "heartbeat" },
+      { kind: "settle", bound: 30 }
+    ]
+  }
+];
+function committedCommands(state) {
+  return state.log.slice(0, state.commitIndex).map((e) => e.command);
+}
+function summarizeNode(id, states) {
+  const state = states[id];
+  if (!state) {
+    return { id, role: "follower", term: 0, commitIndex: 0, committed: [] };
+  }
+  return {
+    id,
+    role: state.role._tag,
+    term: state.currentTerm,
+    commitIndex: state.commitIndex,
+    committed: committedCommands(state)
+  };
+}
+function summarizeCluster(nodes, states) {
+  return nodes.map((id) => summarizeNode(id, states));
+}
+function leaderOf(nodes, states) {
+  const leaders = nodes.filter((id) => states[id]?.role._tag === "leader");
+  if (leaders.length === 0) return null;
+  const topTerm = Math.max(
+    ...leaders.map((id) => states[id]?.currentTerm ?? 0)
+  );
+  const top = leaders.filter((id) => states[id]?.currentTerm === topTerm);
+  return top.length === 1 ? top[0] ?? null : null;
+}
+function demoCluster() {
+  return clusterConfigs(3);
+}
+function demoSchedule() {
+  return PHASES.flatMap((phase) => phase.events);
+}
+function survivors(nodes, partitioned) {
+  const down = new Set(partitioned);
+  return nodes.filter((id) => !down.has(id));
+}
+function runDemo() {
+  const configs = demoCluster();
+  const nodes = configs.map((c) => c.self);
+  const schedule = demoSchedule();
+  const trace = runSchedule(configs, schedule);
+  const phases = [];
+  for (let i = 0; i < PHASES.length; i++) {
+    const phase = PHASES[i];
+    if (!phase) continue;
+    const prefix = PHASES.slice(0, i + 1).flatMap((p) => p.events);
+    const states = runSchedule(configs, prefix).final;
+    phases.push({
+      title: phase.title,
+      note: phase.note,
+      leader: leaderOf(nodes, states),
+      cluster: summarizeCluster(nodes, states)
+    });
+  }
+  const partitioned = [N0];
+  const firstLeader = phases[1]?.leader ?? null;
+  const secondLeader = phases.at(-1)?.leader ?? null;
+  const leaderState = secondLeader ? trace.final[secondLeader] : void 0;
+  const convergedLog = leaderState ? committedCommands(leaderState) : [];
+  return {
+    nodes,
+    partitioned,
+    firstLeader,
+    secondLeader,
+    convergedLog,
+    phases,
+    trace
+  };
+}
+function nodeLine(n) {
+  const role = n.role.padEnd(9);
+  return `    ${n.id}  ${role} term=${n.term} commit=${n.commitIndex} committed=[${n.committed.join(",")}]`;
+}
+function narrateDemo(result) {
+  const lines = [];
+  lines.push("=".repeat(72));
+  lines.push("  @demlik/tea/raft \u2014 multi-node consensus demo (deterministic)");
+  lines.push(`  cluster: ${result.nodes.join(", ")}  (majority = 2 of 3)`);
+  lines.push("=".repeat(72));
+  for (const phase of result.phases) {
+    lines.push("");
+    lines.push(phase.title);
+    lines.push(`  ${phase.note}`);
+    lines.push(`  leader: ${phase.leader ?? "(none \u2014 election in progress)"}`);
+    for (const node of phase.cluster) {
+      lines.push(nodeLine(node));
+    }
+  }
+  lines.push("");
+  lines.push("-".repeat(72));
+  lines.push("  Summary");
+  lines.push(`  first leader (pre-kill):  ${result.firstLeader ?? "none"}`);
+  lines.push(`  killed (partitioned):     ${result.partitioned.join(", ")}`);
+  lines.push(`  new leader (post-kill):   ${result.secondLeader ?? "none"}`);
+  lines.push(`  converged committed log:  [${result.convergedLog.join(", ")}]`);
+  const failedOver = result.firstLeader !== null && result.secondLeader !== null && result.firstLeader !== result.secondLeader;
+  lines.push(
+    `  failover: ${failedOver ? "OK \u2014 a NEW leader took over and the log converged" : "NOT observed"}`
+  );
+  lines.push("-".repeat(72));
+  return lines.join("\n");
+}
+function demoIsReproducible(result) {
+  const replay = replaySchedule(demoCluster(), demoSchedule());
+  return JSON.stringify(replay.final) === JSON.stringify(result.trace.final) && JSON.stringify(replay.steps) === JSON.stringify(result.trace.steps);
+}
+
+export { committedCommands, demoCluster, demoIsReproducible, demoSchedule, narrateDemo, runDemo, survivors };
+//# sourceMappingURL=demo.js.map
+//# sourceMappingURL=demo.js.map

package/dist/raft/demo.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/raft/demo.ts"],"names":[],"mappings":"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","file":"demo.js","sourcesContent":["/**\n * @demlik/tea/raft — a runnable, deterministic multi-node Raft demo (#123,\n * stories 7+8 of epic #117). The live demo the docs reference: it boots a\n * 3-node cluster and drives the full consensus arc through {@link runSchedule}\n * — elect a leader, replicate + commit a client command to a majority, KILL the\n * leader (a network partition), watch the surviving majority elect a NEW leader,\n * and show the committed log converged across the survivors.\n *\n * It is a thin, readable composition over the existing simulation harness\n * (`./sim`): every phase is just a slice of one fixed {@link Schedule}, so the\n * whole run is pure, replayable, and byte-identical on re-run (the determinism\n * the safety suite already enforces — here turned into a watchable narrative).\n * It owns NO clock, NO RNG, NO IO beyond an optional narration printer.\n *\n * Two entry points:\n *   - {@link runDemo} — fold the scripted schedule, return a structured\n *     {@link DemoResult} (the phases, the per-phase cluster summary, the final\n *     trace). Pure: it asserts nothing and prints nothing — the test and the\n *     CLI both read its result.\n *   - {@link narrateDemo} — render a {@link DemoResult} as readable lines (the\n *     `pnpm demo:raft` output). Pure string-building; the runner does the IO.\n *\n * Run it:  `pnpm --filter @demlik/tea demo:raft`\n * (see `src/raft/README.md`).\n */\n\nimport type { NodeId, RaftState } from \"./index\";\nimport {\n  type ClusterStates,\n  clusterConfigs,\n  type RaftConfig,\n  replaySchedule,\n  runSchedule,\n  type Schedule,\n  type SimTrace,\n} from \"./sim\";\n\n// ===========================================================================\n// The scripted scenario — one fixed schedule, sliced into named phases\n// ===========================================================================\n\n// The demo cluster is the 3 default nodes n0/n1/n2 (see {@link clusterConfigs}).\n// Only the two nodes the script names explicitly need constants; the rest of the\n// cluster is addressed via `nodes`.\nconst N0 = \"n0\";\nconst N1 = \"n1\";\n\n/** The two client commands the demo replicates (opaque numeric payloads). */\nconst FIRST_COMMAND = 42;\nconst SECOND_COMMAND = 77;\n\n/**\n * One phase of the demo: a human-readable headline plus the slice of the\n * schedule that drives it. Concatenating every phase's `events` in order yields\n * the full {@link Schedule} {@link runDemo} folds — so the phase boundaries are\n * exactly the trace-step boundaries, and narration lines up with the trace.\n */\ninterface DemoPhase {\n  /** What this phase demonstrates (printed as the section headline). */\n  readonly title: string;\n  /** A one-line plain-language description of the move. */\n  readonly note: string;\n  /** The schedule events this phase contributes (in order). */\n  readonly events: Schedule;\n}\n\n/**\n * The scripted arc. Each phase is a deterministic macro over the harness:\n *\n *   1. n0's election timer fires; `settle` drains the RequestVote round → n0\n *      wins a majority (n0+n1, or n0+n2) and becomes leader of term 1, then its\n *      first heartbeat round drains.\n *   2. A client command hits the leader; `settle` runs the AppendEntries\n *      replication + success replies → the entry commits on a majority.\n *   3. `partition` isolates n0 (the leader): the transport now drops every\n *      message to/from n0. n0 can no longer heartbeat the cluster.\n *   4. A surviving follower (n1) times out and starts an election; `settle`\n *      drains it across the survivors {n1,n2} (a majority of 3) → n1 becomes\n *      leader of a HIGHER term.\n *   5. A client command hits the NEW leader; `settle` replicates it → it commits\n *      on the surviving majority. The survivors' committed logs have converged.\n *\n * The `bound`s are generous caps (the FIFO drain stops early when the pool is\n * empty); they only guard against a pathological re-emit loop.\n */\nconst PHASES: readonly DemoPhase[] = [\n  {\n    title: \"1. Elect a leader\",\n    note: \"n0 times out, runs an election, and wins a majority (term 1).\",\n    events: [\n      { kind: \"timer\", node: N0, timer: \"election\" },\n      { kind: \"settle\", bound: 30 },\n    ],\n  },\n  {\n    title: \"2. Replicate + commit a command\",\n    note: `client sends ${FIRST_COMMAND} to the leader; it replicates to a majority, commits, and the next heartbeat carries the commit to the followers.`,\n    events: [\n      { kind: \"client\", node: N0, command: FIRST_COMMAND },\n      { kind: \"settle\", bound: 30 },\n      // The leader's commitIndex advances on the success replies, but followers\n      // only learn it on the NEXT AppendEntries (Figure 2 `leaderCommit`). One\n      // heartbeat round propagates the commit so the cluster converges.\n      { kind: \"timer\", node: N0, timer: \"heartbeat\" },\n      { kind: \"settle\", bound: 30 },\n    ],\n  },\n  {\n    title: \"3. Kill the leader\",\n    note: \"partition isolates n0 — the transport drops all traffic to/from it.\",\n    events: [{ kind: \"partition\", down: [N0] }],\n  },\n  {\n    title: \"4. A new leader is elected\",\n    note: \"a surviving follower (n1) times out and wins the surviving majority {n1,n2} in a higher term.\",\n    events: [\n      { kind: \"timer\", node: N1, timer: \"election\" },\n      { kind: \"settle\", bound: 30 },\n    ],\n  },\n  {\n    title: \"5. Replicate on the new leader → logs converged\",\n    note: `client sends ${SECOND_COMMAND} to the new leader; it commits on the surviving majority, and a heartbeat converges the survivors' committed logs.`,\n    events: [\n      { kind: \"client\", node: N1, command: SECOND_COMMAND },\n      { kind: \"settle\", bound: 30 },\n      // Same as phase 2: a heartbeat round carries the new commitIndex to the\n      // surviving follower (n2) so every survivor's committed log converges.\n      { kind: \"timer\", node: N1, timer: \"heartbeat\" },\n      { kind: \"settle\", bound: 30 },\n    ],\n  },\n] as const;\n\n// ===========================================================================\n// Cluster-state reading — the demo's view of \"who leads / what committed\"\n// ===========================================================================\n\n/** A compact, JSON-friendly read of one node's state (what the demo reports). */\nexport interface NodeSummary {\n  /** The node's id. */\n  readonly id: NodeId;\n  /** Its role this snapshot: follower / candidate / leader. */\n  readonly role: RaftState[\"role\"][\"_tag\"];\n  /** Its current term. */\n  readonly term: number;\n  /** Its commit index (entries at or below this are committed). */\n  readonly commitIndex: number;\n  /** The COMMITTED commands, in log order (entries `1..commitIndex`). */\n  readonly committed: readonly number[];\n}\n\n/** Read one node's committed commands (the prefix of its log up to commitIndex). */\nexport function committedCommands(state: RaftState<number>): readonly number[] {\n  return state.log.slice(0, state.commitIndex).map((e) => e.command);\n}\n\n/** Summarize one node from a cluster snapshot. */\nfunction summarizeNode(id: NodeId, states: ClusterStates): NodeSummary {\n  const state = states[id];\n  if (!state) {\n    return { id, role: \"follower\", term: 0, commitIndex: 0, committed: [] };\n  }\n  return {\n    id,\n    role: state.role._tag,\n    term: state.currentTerm,\n    commitIndex: state.commitIndex,\n    committed: committedCommands(state),\n  };\n}\n\n/** Summarize every node in a cluster snapshot, in the given order. */\nfunction summarizeCluster(\n  nodes: readonly NodeId[],\n  states: ClusterStates,\n): readonly NodeSummary[] {\n  return nodes.map((id) => summarizeNode(id, states));\n}\n\n/**\n * The cluster's *current* leader in a snapshot: the leader of the HIGHEST term,\n * or `null` if no node leads (mid-election) or two nodes tie for the top term (a\n * genuine split). A partitioned OLD leader keeps believing it leads — it cannot\n * learn it was deposed while its traffic is dropped — but it sits at a strictly\n * LOWER term than whoever the surviving majority elected, so the highest-term\n * leader is the legitimate one. (Election Safety guarantees ≤1 leader per term,\n * so a single top-term leader is unambiguous.)\n */\nfunction leaderOf(\n  nodes: readonly NodeId[],\n  states: ClusterStates,\n): NodeId | null {\n  const leaders = nodes.filter((id) => states[id]?.role._tag === \"leader\");\n  if (leaders.length === 0) return null;\n  const topTerm = Math.max(\n    ...leaders.map((id) => states[id]?.currentTerm ?? 0),\n  );\n  const top = leaders.filter((id) => states[id]?.currentTerm === topTerm);\n  return top.length === 1 ? (top[0] ?? null) : null;\n}\n\n// ===========================================================================\n// The demo result — what runDemo returns (the test + the CLI both read this)\n// ===========================================================================\n\n/** A snapshot of one phase's outcome: its headline + the cluster after it ran. */\nexport interface PhaseOutcome {\n  /** The phase headline. */\n  readonly title: string;\n  /** The phase's one-line note. */\n  readonly note: string;\n  /** The single leader after this phase, or `null`. */\n  readonly leader: NodeId | null;\n  /** Every node's summary after this phase. */\n  readonly cluster: readonly NodeSummary[];\n}\n\n/** The structured outcome of a full demo run — pure data, asserts nothing. */\nexport interface DemoResult {\n  /** The cluster node ids, in config order. */\n  readonly nodes: readonly NodeId[];\n  /** The nodes partitioned off by the end of the run (the killed leader). */\n  readonly partitioned: readonly NodeId[];\n  /** The leader elected in phase 1 (before the kill). */\n  readonly firstLeader: NodeId | null;\n  /** The leader elected in phase 4 (after the kill) — a DIFFERENT node. */\n  readonly secondLeader: NodeId | null;\n  /** The commands committed across the SURVIVING majority by the end. */\n  readonly convergedLog: readonly number[];\n  /** Per-phase outcomes, in order. */\n  readonly phases: readonly PhaseOutcome[];\n  /** The full underlying simulation trace (for replay / deep inspection). */\n  readonly trace: SimTrace;\n}\n\n// ===========================================================================\n// Running the demo\n// ===========================================================================\n\n/** The demo cluster: 3 nodes, default election-timeout window + heartbeat. */\nexport function demoCluster(): readonly RaftConfig[] {\n  return clusterConfigs(3);\n}\n\n/** The full scripted schedule (every phase's events concatenated, in order). */\nexport function demoSchedule(): Schedule {\n  return PHASES.flatMap((phase) => phase.events);\n}\n\n/**\n * The nodes that survive the partition (everyone NOT in the down-set). The demo\n * checks convergence over THESE — the partitioned leader is, by construction,\n * stuck at its pre-kill log.\n */\nexport function survivors(\n  nodes: readonly NodeId[],\n  partitioned: readonly NodeId[],\n): readonly NodeId[] {\n  const down = new Set(partitioned);\n  return nodes.filter((id) => !down.has(id));\n}\n\n/**\n * Run the scripted demo against a fresh 3-node cluster and return a structured\n * {@link DemoResult}. Pure: folds {@link demoSchedule} through {@link runSchedule},\n * then reads the cluster at each phase boundary. Deterministic — the same\n * schedule yields a byte-identical trace, so {@link runDemo}() === runDemo().\n */\nexport function runDemo(): DemoResult {\n  const configs = demoCluster();\n  const nodes = configs.map((c) => c.self);\n  const schedule = demoSchedule();\n  const trace = runSchedule(configs, schedule);\n\n  // Walk the trace one phase at a time: each phase consumes as many trace steps\n  // as it contributed events — except `settle`, which expands to one step per\n  // drained delivery. So we slice by counting steps until the phase's last\n  // non-settle event is consumed. Simpler + robust: re-fold each cumulative\n  // prefix of phases and read the resulting cluster (the schedule is tiny).\n  const phases: PhaseOutcome[] = [];\n  for (let i = 0; i < PHASES.length; i++) {\n    const phase = PHASES[i];\n    if (!phase) continue;\n    const prefix = PHASES.slice(0, i + 1).flatMap((p) => p.events);\n    const states = runSchedule(configs, prefix).final;\n    phases.push({\n      title: phase.title,\n      note: phase.note,\n      leader: leaderOf(nodes, states),\n      cluster: summarizeCluster(nodes, states),\n    });\n  }\n\n  const partitioned: readonly NodeId[] = [N0];\n  const firstLeader = phases[1]?.leader ?? null;\n  const secondLeader = phases.at(-1)?.leader ?? null;\n\n  // Converged log = the committed commands the surviving majority agree on. We\n  // read the new leader's committed prefix; the test asserts every survivor\n  // matches it once the final settle drains.\n  const leaderState = secondLeader ? trace.final[secondLeader] : undefined;\n  const convergedLog = leaderState ? committedCommands(leaderState) : [];\n\n  return {\n    nodes,\n    partitioned,\n    firstLeader,\n    secondLeader,\n    convergedLog,\n    phases,\n    trace,\n  };\n}\n\n// ===========================================================================\n// Narration — render a DemoResult as readable lines (the CLI output)\n// ===========================================================================\n\n/** One node's summary as a compact line, e.g. `n0 leader  term=2 commit=2 [42,77]`. */\nfunction nodeLine(n: NodeSummary): string {\n  const role = n.role.padEnd(9);\n  return `    ${n.id}  ${role} term=${n.term} commit=${n.commitIndex} committed=[${n.committed.join(\",\")}]`;\n}\n\n/**\n * Render a {@link DemoResult} as a readable, deterministic narrative — the\n * `pnpm demo:raft` output. Pure: returns the lines; the runner prints them.\n */\nexport function narrateDemo(result: DemoResult): string {\n  const lines: string[] = [];\n  lines.push(\"=\".repeat(72));\n  lines.push(\"  @demlik/tea/raft — multi-node consensus demo (deterministic)\");\n  lines.push(`  cluster: ${result.nodes.join(\", \")}  (majority = 2 of 3)`);\n  lines.push(\"=\".repeat(72));\n\n  for (const phase of result.phases) {\n    lines.push(\"\");\n    lines.push(phase.title);\n    lines.push(`  ${phase.note}`);\n    lines.push(`  leader: ${phase.leader ?? \"(none — election in progress)\"}`);\n    for (const node of phase.cluster) {\n      lines.push(nodeLine(node));\n    }\n  }\n\n  lines.push(\"\");\n  lines.push(\"-\".repeat(72));\n  lines.push(\"  Summary\");\n  lines.push(`  first leader (pre-kill):  ${result.firstLeader ?? \"none\"}`);\n  lines.push(`  killed (partitioned):     ${result.partitioned.join(\", \")}`);\n  lines.push(`  new leader (post-kill):   ${result.secondLeader ?? \"none\"}`);\n  lines.push(`  converged committed log:  [${result.convergedLog.join(\", \")}]`);\n  const failedOver =\n    result.firstLeader !== null &&\n    result.secondLeader !== null &&\n    result.firstLeader !== result.secondLeader;\n  lines.push(\n    `  failover: ${failedOver ? \"OK — a NEW leader took over and the log converged\" : \"NOT observed\"}`,\n  );\n  lines.push(\"-\".repeat(72));\n  return lines.join(\"\\n\");\n}\n\n// ===========================================================================\n// Replay helper — prove the demo is byte-identically reproducible\n// ===========================================================================\n\n/**\n * Re-run the demo's schedule from a fresh cluster and report whether the trace\n * is byte-identical to the original run (the determinism contract). Used by the\n * test and surfaced in the CLI footer.\n */\nexport function demoIsReproducible(result: DemoResult): boolean {\n  const replay = replaySchedule(demoCluster(), demoSchedule());\n  return (\n    JSON.stringify(replay.final) === JSON.stringify(result.trace.final) &&\n    JSON.stringify(replay.steps) === JSON.stringify(result.trace.steps)\n  );\n}\n"]}