@demlik/tea 0.1.2 → 0.3.0

package/dist/chunk-VLGARN6H.js

@@ -1,202 +0,0 @@
-import { createRaftNode } from './chunk-6RGBKODV.js';
-
-// src/raft/sim.ts
-function clusterConfigs(n, over) {
-  const ids = Array.from({ length: n }, (_, i) => `n${i}`);
-  return ids.map((self) => ({
-    self,
-    peers: ids.filter((id) => id !== self),
-    electionTimeout: over?.electionTimeout ?? { minMs: 150, maxMs: 300 },
-    heartbeatMs: over?.heartbeatMs ?? 50
-  }));
-}
-function fixedRng(index, count) {
-  const value = count > 0 ? index / count : 0;
-  return () => value;
-}
-function cmdToInbound(sender, cmd) {
-  switch (cmd.type) {
-    case "raft:send_request_vote": {
-      const msg = {
-        _tag: "request_vote_request",
-        term: cmd.term,
-        candidateId: cmd.candidateId,
-        lastLogIndex: cmd.lastLogIndex,
-        lastLogTerm: cmd.lastLogTerm
-      };
-      return msg;
-    }
-    case "raft:send_request_vote_reply": {
-      const msg = {
-        _tag: "request_vote_reply",
-        term: cmd.term,
-        from: sender,
-        voteGranted: cmd.voteGranted
-      };
-      return msg;
-    }
-    case "raft:send_append_entries": {
-      const msg = {
-        _tag: "append_entries_request",
-        term: cmd.term,
-        leaderId: cmd.leaderId,
-        prevLogIndex: cmd.prevLogIndex,
-        prevLogTerm: cmd.prevLogTerm,
-        entries: cmd.entries,
-        leaderCommit: cmd.leaderCommit
-      };
-      return msg;
-    }
-    case "raft:send_append_entries_reply": {
-      const msg = {
-        _tag: "append_entries_reply",
-        term: cmd.term,
-        from: sender,
-        success: cmd.success,
-        matchIndex: cmd.matchIndex
-      };
-      return msg;
-    }
-  }
-}
-function applyInbound(node, state, msg, at) {
-  switch (msg._tag) {
-    case "election_timeout_fired":
-      return node.onElectionTimeout(state, at);
-    case "heartbeat_fired":
-      return node.onHeartbeat(state, at);
-    case "request_vote_request":
-      return node.onRequestVote(state, msg);
-    case "request_vote_reply":
-      return node.onRequestVoteReply(state, msg);
-    case "append_entries_request":
-      return node.onAppendEntries(state, msg);
-    case "append_entries_reply":
-      return node.onAppendEntriesReply(state, msg);
-    case "client_command":
-      return node.onClientCommand(state, msg);
-  }
-}
-function park(world, actor, emitted) {
-  for (const cmd of emitted) {
-    world.pending.push({ from: actor, cmd });
-  }
-}
-function deliverOne(world, index) {
-  if (world.pending.length === 0) {
-    world.clock += 1;
-    return null;
-  }
-  world.clock += 1;
-  const at = world.clock;
-  const i = (index % world.pending.length + world.pending.length) % world.pending.length;
-  const [inFlight] = world.pending.splice(i, 1);
-  if (!inFlight) return null;
-  const target = inFlight.cmd.to;
-  if (world.down.has(target) || world.down.has(inFlight.from)) {
-    return inFlight;
-  }
-  const node = world.handles.get(target);
-  const state = world.states[target];
-  if (node && state) {
-    const inbound = cmdToInbound(inFlight.from, inFlight.cmd);
-    const [next, cmds] = applyInbound(node, state, inbound, at);
-    world.states[target] = next;
-    park(world, target, cmds);
-  }
-  return inFlight;
-}
-function deliveredOf(inFlight) {
-  return { from: inFlight.from, to: inFlight.cmd.to, kind: inFlight.cmd.type };
-}
-function applyEvent(world, event, steps) {
-  if (event.kind === "partition") {
-    world.clock += 1;
-    world.down = new Set(event.down);
-    steps.push({
-      event,
-      pending: world.pending.length,
-      states: snapshot(world.states)
-    });
-    return;
-  }
-  if (event.kind === "settle") {
-    const bound = Math.max(0, event.bound);
-    for (let n = 0; n < bound && world.pending.length > 0; n++) {
-      const inFlight = deliverOne(world, 0);
-      steps.push({
-        event: { kind: "deliver", index: 0 },
-        pending: world.pending.length,
-        states: snapshot(world.states),
-        // Each drained delivery is its OWN step, so record that step's own
-        // delivered message (not "the last of the settle"). The pool was
-        // non-empty (loop guard), so `inFlight` is never null here.
-        ...inFlight ? { delivered: deliveredOf(inFlight) } : {}
-      });
-    }
-    return;
-  }
-  let delivered = null;
-  if (event.kind === "deliver") {
-    delivered = deliverOne(world, event.index);
-  } else {
-    world.clock += 1;
-    const at = world.clock;
-    const actor = event.node;
-    const node = world.handles.get(actor);
-    const state = world.states[actor];
-    if (node && state) {
-      const inbound = event.kind === "timer" ? event.timer === "election" ? { _tag: "election_timeout_fired", at } : { _tag: "heartbeat_fired", at } : { _tag: "client_command", command: event.command };
-      const [next, cmds] = applyInbound(node, state, inbound, at);
-      world.states[actor] = next;
-      park(world, actor, cmds);
-    }
-  }
-  steps.push({
-    event,
-    pending: world.pending.length,
-    states: snapshot(world.states),
-    // Additive read-off: present only when a `deliver` actually consumed a
-    // message. Absent (key omitted) for timer/client and empty-pool delivers,
-    // so the step is structurally identical to a pre-#144 trace.
-    ...delivered ? { delivered: deliveredOf(delivered) } : {}
-  });
-}
-function snapshot(states) {
-  return { ...states };
-}
-function runSchedule(configs, schedule) {
-  const handles = /* @__PURE__ */ new Map();
-  const states = {};
-  configs.forEach((config, i) => {
-    const node = createRaftNode(config, fixedRng(i, configs.length));
-    handles.set(config.self, node);
-    states[config.self] = node.init();
-  });
-  const world = {
-    handles,
-    states,
-    pending: [],
-    clock: 0,
-    down: /* @__PURE__ */ new Set()
-  };
-  const steps = [];
-  for (const event of schedule) {
-    applyEvent(world, event, steps);
-  }
-  return {
-    nodes: configs.map((c) => c.self),
-    steps,
-    final: snapshot(world.states)
-  };
-}
-function replaySchedule(configs, schedule) {
-  return runSchedule(configs, schedule);
-}
-function clusterStatesEqual(a, b) {
-  return JSON.stringify(a) === JSON.stringify(b);
-}
-
-export { clusterConfigs, clusterStatesEqual, replaySchedule, runSchedule };
-//# sourceMappingURL=chunk-VLGARN6H.js.map
-//# sourceMappingURL=chunk-VLGARN6H.js.map

package/dist/chunk-VLGARN6H.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/raft/sim.ts"],"names":[],"mappings":"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","file":"chunk-VLGARN6H.js","sourcesContent":["/**\n * @demlik/tea/raft — a deterministic, in-memory multi-node Raft simulation\n * driver. Slice #121 (the safety-property half) of the consensus epic (#117):\n * the headline payoff is consensus verified by **deterministic replay**, not by\n * flaky wall-clock timing.\n *\n * This module owns NO wall clock, NO real timers, and NO networking. Time and\n * message ordering are entirely the *schedule* — a finite list of {@link SimEvent}s\n * the caller (a fast-check generator or an explicit fixture) hands the driver.\n * The driver folds the schedule one event at a time over a cluster of pure\n * {@link createRaftNode}s, routing every emitted `Cmd` into a pending-message\n * pool and recording the full `(event → resulting cluster states)` trace.\n *\n * Because the underlying reducer is pure (no ambient clock — `at` rides on the\n * Msg; no ambient RNG — `rng` injected once per node), the same schedule re-run\n * yields **byte-identical** cluster state. That replay identity is the property\n * the safety suite (`safety.test.ts`) leans on: a violated invariant shrinks to\n * a *replayable schedule*, not an irreproducible timing fluke (errors are data).\n *\n * ## The schedule model\n *\n * The cluster is N nodes plus a pending-message pool. Each {@link SimEvent} is\n * one of two moves:\n *\n *   - `{ kind: \"timer\", node, timer }` — fire node's election OR heartbeat timer.\n *     Drives an `onElectionTimeout` / `onHeartbeat` verb on that node. The\n *     firing `at` is the driver's monotonic logical clock (one tick per event),\n *     so no verb reads a real clock.\n *   - `{ kind: \"deliver\", index }` — deliver the in-flight message at `index` in\n *     the pending pool to its target node, as the matching inbound `RaftMsg`.\n *     An out-of-range `index` is taken modulo the pool size (so a fast-check\n *     integer always names *some* deliverable message when the pool is\n *     non-empty); a `deliver` against an empty pool is a no-op event (recorded,\n *     advances the clock, changes nothing) — the schedule stays total.\n *\n * Delivering a message removes it from the pool and feeds it to the target's\n * verb; any Cmds that verb emits are appended to the pool (each Cmd carries its\n * own `to`, so routing is just a lookup). This is the in-memory transport: a\n * `SendRequestVote{to}` delivered becomes a `RequestVoteRequest` on `to`; the\n * `SendRequestVoteReply{to}` it emits becomes a `RequestVoteReply` on the\n * original candidate; and so on around the RPC pairs.\n *\n * ## Record / replay\n *\n * {@link runSchedule} returns a {@link SimTrace}: the ordered list of steps, each\n * the event applied and the resulting per-node {@link RaftState} snapshot, plus\n * the final cluster. {@link replaySchedule} re-runs the identical schedule from a\n * fresh cluster; {@link clusterStatesEqual} compares two cluster snapshots\n * structurally. The safety suite asserts `runSchedule(s)` and\n * `replaySchedule(s)` agree byte-for-byte.\n *\n * NOT a substrate primitive and NOT shipped in the node's public verb surface:\n * it depends only on `./index` (the pure node) read-only, and lives beside the\n * node as a test/replay harness.\n */\n\nimport {\n  type AppendEntriesReply,\n  type AppendEntriesRequest,\n  createRaftNode,\n  type LogEntry,\n  type NodeId,\n  type RaftCmd,\n  type RaftConfig,\n  type RaftMsg,\n  type RaftNode,\n  type RaftState,\n  type RequestVoteReply,\n  type RequestVoteRequest,\n} from \"./index\";\n\n// ===========================================================================\n// Schedule — the controllable, wall-clock-free event stream\n// ===========================================================================\n\n/** Which of a node's two timers a `timer` event fires. */\nexport type TimerKind = \"election\" | \"heartbeat\";\n\n/**\n * One move in a schedule. The whole simulation is a fold of these — there is no\n * other source of time or ordering. `_tag`-style `kind` discriminant matches the\n * engine's tagged-union convention.\n */\nexport type SimEvent =\n  | {\n      /** Fire a node's timer (drives `onElectionTimeout` / `onHeartbeat`). */\n      readonly kind: \"timer\";\n      /** The node whose timer fires. */\n      readonly node: NodeId;\n      /** Which timer. */\n      readonly timer: TimerKind;\n    }\n  | {\n      /**\n       * Deliver an in-flight message from the pending pool to its target. The\n       * index is taken modulo the pool size, so any integer names a deliverable\n       * message when the pool is non-empty; a deliver against an empty pool is a\n       * recorded no-op (the clock still advances).\n       */\n      readonly kind: \"deliver\";\n      /** Which pending message to deliver (modulo pool size). */\n      readonly index: number;\n    }\n  | {\n      /**\n       * A client submits a command to a node (Figure 2 §5.3). On the leader it\n       * appends + replicates; on a non-leader it is a no-op. This is how the\n       * replicated log grows in a simulation.\n       */\n      readonly kind: \"client\";\n      /** The node the client contacts. */\n      readonly node: NodeId;\n      /** The opaque command to submit. */\n      readonly command: number;\n    }\n  | {\n      /**\n       * Drain the pending pool to quiescence: deliver messages FIFO (each new\n       * Cmd a delivery emits is appended and itself delivered) until the pool is\n       * empty or `bound` deliveries have run. This is the \"let the network\n       * settle\" move — it lets a started election or a submitted client command\n       * run its RPC round(s) to completion, which is what actually produces\n       * leaders and committed entries. Without it, a purely-random `deliver`\n       * index almost never threads the exact sequence an election + replication\n       * needs (measured: 0 commits in 2000 random schedules vs. 529 with settle),\n       * so the safety properties would pass *vacuously* over empty logs.\n       *\n       * The `bound` caps the drain so a pathological re-emit loop cannot diverge;\n       * every step is still recorded (one trace step per delivery), so a settle\n       * is a deterministic, replayable macro — not a black box.\n       */\n      readonly kind: \"settle\";\n      /** Max deliveries to run (the drain is FIFO; stops early when empty). */\n      readonly bound: number;\n    }\n  | {\n      /**\n       * Set the cluster's *partitioned* node set (a network fault, NOT a state\n       * change). A node in `down` is isolated: the transport DROPS every message\n       * to OR from it (both directions, as a real partition does) while its\n       * timers still fire — so a crashed/partitioned leader stops being able to\n       * heartbeat and the surviving majority elects a new leader. This is the\n       * \"kill the leader\" / \"heal the partition\" move the failover demo needs.\n       *\n       * It names the WHOLE down-set absolutely (not a toggle): `{ down: [n0] }`\n       * isolates n0; a later `{ down: [] }` heals every partition. Recorded as\n       * one step (clock advances, no message moves), so it replays deterministically.\n       */\n      readonly kind: \"partition\";\n      /** The nodes that are currently isolated (drop all their traffic). */\n      readonly down: readonly NodeId[];\n    };\n\n/** A whole schedule: the finite event stream the driver folds. */\nexport type Schedule = readonly SimEvent[];\n\n// ===========================================================================\n// In-flight messages — emitted Cmds parked in the pending pool\n// ===========================================================================\n\n/**\n * A Cmd a node emitted, parked until a `deliver` event routes it. We keep the\n * raw {@link RaftCmd} (it already carries `to`) plus the sender, so a delivery\n * can build the correct inbound {@link RaftMsg} on the target. Commands over a\n * numeric payload (the simulation's `C = number`).\n */\nexport interface InFlight {\n  /** The node that emitted this Cmd (the inbound Msg's `from` / sender). */\n  readonly from: NodeId;\n  /** The emitted Cmd, addressed to `cmd.to`. */\n  readonly cmd: RaftCmd<number>;\n}\n\n// ===========================================================================\n// Cluster + trace\n// ===========================================================================\n\n/** A snapshot of every node's state, keyed by id. */\nexport type ClusterStates = Readonly<Record<NodeId, RaftState<number>>>;\n\n/**\n * A read-off of the message a `deliver` step actually pulled off the pending\n * pool — sender, target, and the {@link RaftCmd} discriminant (`cmd.type`). This\n * is a pure projection of what the fold *already did* (the InFlight that\n * {@link deliverOne} consumed), recorded so a renderer can draw the RPC flow.\n * It is NOT a new input and changes NO simulation behavior. Recorded even when\n * the packet is dropped by a partition (the RPC was still attempted), so the\n * arrow shows the intent while the greyed node shows the drop.\n */\nexport interface DeliveredMessage {\n  /** The node that emitted the delivered Cmd (the inbound Msg's sender). */\n  readonly from: NodeId;\n  /** The node the Cmd was addressed to (`cmd.to`). */\n  readonly to: NodeId;\n  /** The delivered Cmd's discriminant (`RaftCmd[\"type\"]`). */\n  readonly kind: RaftCmd<number>[\"type\"];\n}\n\n/** One recorded step: the event applied and the cluster state it produced. */\nexport interface SimStep {\n  /** The event applied at this step. */\n  readonly event: SimEvent;\n  /** The pending-pool size AFTER applying the event. */\n  readonly pending: number;\n  /** Every node's state after the event. */\n  readonly states: ClusterStates;\n  /**\n   * On a `deliver` step (incl. each delivery a `settle` drains), the message\n   * that was actually pulled off the pool. ABSENT on every other step kind and\n   * on a `deliver` against an empty pool — additive + backward-compatible, so a\n   * trace recorded before this field still folds and renders identically (field\n   * absent ⇒ no arrow). Purely a read-off of {@link deliverOne}'s work.\n   */\n  readonly delivered?: DeliveredMessage;\n}\n\n/**\n * The full record of a run: the per-node configs, the ordered steps, and the\n * final cluster. Replaying the same schedule reproduces this byte-for-byte.\n */\nexport interface SimTrace {\n  /** The cluster's node ids, in config order. */\n  readonly nodes: readonly NodeId[];\n  /** One step per event in the schedule (in order). */\n  readonly steps: readonly SimStep[];\n  /** The final per-node states (== `steps.at(-1)?.states` when non-empty). */\n  readonly final: ClusterStates;\n}\n\n// ===========================================================================\n// Building the cluster\n// ===========================================================================\n\n/**\n * Build N node configs sharing one election-timeout window + heartbeat. Each\n * node's `peers` is every OTHER id. Ids are `n0..n{N-1}`.\n */\nexport function clusterConfigs(\n  n: number,\n  over?: Partial<Omit<RaftConfig, \"self\" | \"peers\">>,\n): readonly RaftConfig[] {\n  const ids = Array.from({ length: n }, (_, i) => `n${i}`);\n  return ids.map((self) => ({\n    self,\n    peers: ids.filter((id) => id !== self),\n    electionTimeout: over?.electionTimeout ?? { minMs: 150, maxMs: 300 },\n    heartbeatMs: over?.heartbeatMs ?? 50,\n  }));\n}\n\n/**\n * A fixed-jitter rng for a node, derived from its index so that distinct nodes\n * draw *distinct but deterministic* election timeouts (the real-cluster effect\n * that breaks split votes), while a replay with the same configs reproduces them\n * exactly. Pure function of the index — no ambient randomness.\n */\nfunction fixedRng(index: number, count: number): () => number {\n  // Spread the [0,1) jitter evenly across the cluster: node i draws i/count.\n  const value = count > 0 ? index / count : 0;\n  return () => value;\n}\n\n// ===========================================================================\n// The driver\n// ===========================================================================\n\n/**\n * The mutable bag the fold threads. Kept local to {@link runSchedule}; never\n * escapes. `clock` is the monotonic logical clock — incremented once per event\n * and used as the `at` for timer firings, so the reducer never reads a real\n * clock and a replay reproduces every `at`.\n */\ninterface SimWorld {\n  readonly handles: ReadonlyMap<NodeId, RaftNode<number>>;\n  states: Record<NodeId, RaftState<number>>;\n  pending: InFlight[];\n  clock: number;\n  /**\n   * The currently-partitioned nodes (a `partition` event sets this absolutely).\n   * The transport drops any in-flight message to OR from a down node — its\n   * timers still fire, but its RPCs never land and it never hears the cluster.\n   */\n  down: Set<NodeId>;\n}\n\n/**\n * Translate one emitted {@link RaftCmd} into the inbound {@link RaftMsg} the\n * target node should receive. Pure mapping over the RPC pairs (Figure 2 wire\n * shapes); `sender` becomes the Msg's `from` / candidateId / leaderId as\n * appropriate. The target is always `cmd.to`.\n */\nfunction cmdToInbound(sender: NodeId, cmd: RaftCmd<number>): RaftMsg<number> {\n  switch (cmd.type) {\n    case \"raft:send_request_vote\": {\n      const msg: RequestVoteRequest = {\n        _tag: \"request_vote_request\",\n        term: cmd.term,\n        candidateId: cmd.candidateId,\n        lastLogIndex: cmd.lastLogIndex,\n        lastLogTerm: cmd.lastLogTerm,\n      };\n      return msg;\n    }\n    case \"raft:send_request_vote_reply\": {\n      const msg: RequestVoteReply = {\n        _tag: \"request_vote_reply\",\n        term: cmd.term,\n        from: sender,\n        voteGranted: cmd.voteGranted,\n      };\n      return msg;\n    }\n    case \"raft:send_append_entries\": {\n      const msg: AppendEntriesRequest<number> = {\n        _tag: \"append_entries_request\",\n        term: cmd.term,\n        leaderId: cmd.leaderId,\n        prevLogIndex: cmd.prevLogIndex,\n        prevLogTerm: cmd.prevLogTerm,\n        entries: cmd.entries,\n        leaderCommit: cmd.leaderCommit,\n      };\n      return msg;\n    }\n    case \"raft:send_append_entries_reply\": {\n      const msg: AppendEntriesReply = {\n        _tag: \"append_entries_reply\",\n        term: cmd.term,\n        from: sender,\n        success: cmd.success,\n        matchIndex: cmd.matchIndex,\n      };\n      return msg;\n    }\n  }\n}\n\n/** Run one node verb for the inbound Msg, returning `[next, cmds]`. */\nfunction applyInbound(\n  node: RaftNode<number>,\n  state: RaftState<number>,\n  msg: RaftMsg<number>,\n  at: number,\n) {\n  switch (msg._tag) {\n    case \"election_timeout_fired\":\n      return node.onElectionTimeout(state, at);\n    case \"heartbeat_fired\":\n      return node.onHeartbeat(state, at);\n    case \"request_vote_request\":\n      return node.onRequestVote(state, msg);\n    case \"request_vote_reply\":\n      return node.onRequestVoteReply(state, msg);\n    case \"append_entries_request\":\n      return node.onAppendEntries(state, msg);\n    case \"append_entries_reply\":\n      return node.onAppendEntriesReply(state, msg);\n    case \"client_command\":\n      return node.onClientCommand(state, msg);\n  }\n}\n\n/** Park the Cmds an acting node emitted into the pending pool (FIFO append). */\nfunction park(\n  world: SimWorld,\n  actor: NodeId,\n  emitted: readonly RaftCmd<number>[],\n): void {\n  for (const cmd of emitted) {\n    world.pending.push({ from: actor, cmd });\n  }\n}\n\n/**\n * Deliver the pending message at `index` (modulo the pool size) to its target,\n * parking whatever it emits. Advances the clock and returns the {@link InFlight}\n * it consumed from the pool (so a caller can record what was delivered),\n * or `null` when the pool was empty (a recorded no-op). A single atomic unit of\n * simulated work — one trace step.\n *\n * The return value is a PURE read-off of work the function already does (the\n * splice was always there); returning it instead of a `boolean` adds no\n * behavior — every existing call-site path (apply, partition-drop, empty-pool)\n * is byte-for-byte unchanged.\n */\nfunction deliverOne(world: SimWorld, index: number): InFlight | null {\n  if (world.pending.length === 0) {\n    world.clock += 1;\n    return null;\n  }\n  world.clock += 1;\n  const at = world.clock;\n  const i =\n    ((index % world.pending.length) + world.pending.length) %\n    world.pending.length;\n  const [inFlight] = world.pending.splice(i, 1);\n  if (!inFlight) return null;\n  const target = inFlight.cmd.to;\n  // Partition: a message to OR from an isolated node is dropped — consumed from\n  // the pool (so a `settle` still terminates) but never applied (the packet was\n  // lost on the wire). Both directions, as a real partition severs.\n  if (world.down.has(target) || world.down.has(inFlight.from)) {\n    return inFlight;\n  }\n  const node = world.handles.get(target);\n  const state = world.states[target];\n  if (node && state) {\n    const inbound = cmdToInbound(inFlight.from, inFlight.cmd);\n    const [next, cmds] = applyInbound(node, state, inbound, at);\n    world.states[target] = next;\n    park(world, target, cmds);\n  }\n  return inFlight;\n}\n\n/** Project a consumed {@link InFlight} into the additive {@link DeliveredMessage} read-off. */\nfunction deliveredOf(inFlight: InFlight): DeliveredMessage {\n  return { from: inFlight.from, to: inFlight.cmd.to, kind: inFlight.cmd.type };\n}\n\n/**\n * Apply one {@link SimEvent} to the world, pushing one trace step PER unit of\n * work onto `steps`. A `timer` / `client` / `deliver` produces exactly one step;\n * a `settle` produces one step per drained delivery (so the macro stays a\n * transparent, replayable sequence — not a black box). Mutates the world's\n * `states` / `pending` / `clock` in place (the local fold bag).\n */\nfunction applyEvent(world: SimWorld, event: SimEvent, steps: SimStep[]): void {\n  if (event.kind === \"partition\") {\n    // A pure network-fault move: replace the down-set, advance the clock, record\n    // a step. No message moves and no node state changes — the effect surfaces\n    // later when `deliverOne` drops traffic to/from a down node.\n    world.clock += 1;\n    world.down = new Set(event.down);\n    steps.push({\n      event,\n      pending: world.pending.length,\n      states: snapshot(world.states),\n    });\n    return;\n  }\n\n  if (event.kind === \"settle\") {\n    // Drain FIFO (index 0) until empty or the bound is hit. Each delivery is its\n    // own recorded step, tagged as the deliver-index-0 it actually is.\n    const bound = Math.max(0, event.bound);\n    for (let n = 0; n < bound && world.pending.length > 0; n++) {\n      const inFlight = deliverOne(world, 0);\n      steps.push({\n        event: { kind: \"deliver\", index: 0 },\n        pending: world.pending.length,\n        states: snapshot(world.states),\n        // Each drained delivery is its OWN step, so record that step's own\n        // delivered message (not \"the last of the settle\"). The pool was\n        // non-empty (loop guard), so `inFlight` is never null here.\n        ...(inFlight ? { delivered: deliveredOf(inFlight) } : {}),\n      });\n    }\n    return;\n  }\n\n  // The message a top-level `deliver` consumed (null on an empty-pool no-op);\n  // read off below into the step's additive `delivered` field. `undefined` for\n  // every non-deliver event kind.\n  let delivered: InFlight | null = null;\n  if (event.kind === \"deliver\") {\n    delivered = deliverOne(world, event.index);\n  } else {\n    // timer / client: drive the acting node's verb directly.\n    world.clock += 1;\n    const at = world.clock;\n    const actor = event.node;\n    const node = world.handles.get(actor);\n    const state = world.states[actor];\n    if (node && state) {\n      const inbound: RaftMsg<number> =\n        event.kind === \"timer\"\n          ? event.timer === \"election\"\n            ? { _tag: \"election_timeout_fired\", at }\n            : { _tag: \"heartbeat_fired\", at }\n          : { _tag: \"client_command\", command: event.command };\n      const [next, cmds] = applyInbound(node, state, inbound, at);\n      world.states[actor] = next;\n      park(world, actor, cmds);\n    }\n  }\n\n  steps.push({\n    event,\n    pending: world.pending.length,\n    states: snapshot(world.states),\n    // Additive read-off: present only when a `deliver` actually consumed a\n    // message. Absent (key omitted) for timer/client and empty-pool delivers,\n    // so the step is structurally identical to a pre-#144 trace.\n    ...(delivered ? { delivered: deliveredOf(delivered) } : {}),\n  });\n}\n\n/** Deep-freeze-free structural copy of a cluster snapshot (states are already immutable values). */\nfunction snapshot(states: Record<NodeId, RaftState<number>>): ClusterStates {\n  return { ...states };\n}\n\n/**\n * Run a schedule against a fresh N-node cluster, recording the full trace. Pure\n * given `(configs, schedule)`: no clock, no RNG, no IO — the only \"time\" is the\n * driver's logical clock, advanced one tick per event. Each node gets a\n * fixed-jitter rng derived from its index (distinct but deterministic timeouts).\n */\nexport function runSchedule(\n  configs: readonly RaftConfig[],\n  schedule: Schedule,\n): SimTrace {\n  const handles = new Map<NodeId, RaftNode<number>>();\n  const states: Record<NodeId, RaftState<number>> = {};\n  configs.forEach((config, i) => {\n    const node = createRaftNode<number>(config, fixedRng(i, configs.length));\n    handles.set(config.self, node);\n    states[config.self] = node.init();\n  });\n\n  const world: SimWorld = {\n    handles,\n    states,\n    pending: [],\n    clock: 0,\n    down: new Set(),\n  };\n  const steps: SimStep[] = [];\n\n  for (const event of schedule) {\n    applyEvent(world, event, steps);\n  }\n\n  return {\n    nodes: configs.map((c) => c.self),\n    steps,\n    final: snapshot(world.states),\n  };\n}\n\n/**\n * Replay a schedule from a fresh cluster. Identical to {@link runSchedule} (it\n * IS `runSchedule`) — exposed under a name that documents intent at the call\n * site: a replay is meant to reproduce a prior run's trace byte-for-byte.\n */\nexport function replaySchedule(\n  configs: readonly RaftConfig[],\n  schedule: Schedule,\n): SimTrace {\n  return runSchedule(configs, schedule);\n}\n\n// ===========================================================================\n// Comparison helpers (for the determinism property + counterexample reports)\n// ===========================================================================\n\n/**\n * Structural equality of two cluster snapshots. Used by the determinism\n * property: a run and its replay must produce identical per-node state for every\n * node. (Tests use vitest `toEqual` for the same comparison; this is the\n * dependency-free version the driver can expose for ad-hoc checks.)\n */\nexport function clusterStatesEqual(\n  a: ClusterStates,\n  b: ClusterStates,\n): boolean {\n  return JSON.stringify(a) === JSON.stringify(b);\n}\n\n// ===========================================================================\n// Re-exports the safety suite reads (so it imports the harness, not ./index)\n// ===========================================================================\n\nexport type { LogEntry, NodeId, RaftConfig, RaftState };\n"]}

package/dist/raft/demo.d.ts

@@ -1,105 +0,0 @@
-import { NodeId, RaftState, RaftConfig } from './index.js';
-import { SimTrace, Schedule } from './sim.js';
-import '../deadline/index.js';
-import '../core-BoB6t7dB.js';
-import '../types-B-8bcAp8.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

@@ -1,172 +0,0 @@
-import { clusterConfigs, runSchedule, replaySchedule } from '../chunk-VLGARN6H.js';
-import '../chunk-6RGBKODV.js';
-import '../chunk-K7Q23EQ4.js';
-import '../chunk-2YFLOCWX.js';
-import '../chunk-MMH7CW5K.js';
-import '../chunk-QLA76GIT.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

@@ -1 +0,0 @@
-{"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"]}