@demlik/tea 0.1.2 → 0.3.0

package/dist/raft/sim.d.ts

@@ -1,222 +0,0 @@
-import { NodeId, RaftCmd, RaftState, RaftConfig } from './index.js';
-export { LogEntry } from './index.js';
-import '../deadline/index.js';
-import '../core-BoB6t7dB.js';
-import '../types-B-8bcAp8.js';
-
-/**
- * @demlik/tea/raft — a deterministic, in-memory multi-node Raft simulation
- * driver. Slice #121 (the safety-property half) of the consensus epic (#117):
- * the headline payoff is consensus verified by **deterministic replay**, not by
- * flaky wall-clock timing.
- *
- * This module owns NO wall clock, NO real timers, and NO networking. Time and
- * message ordering are entirely the *schedule* — a finite list of {@link SimEvent}s
- * the caller (a fast-check generator or an explicit fixture) hands the driver.
- * The driver folds the schedule one event at a time over a cluster of pure
- * {@link createRaftNode}s, routing every emitted `Cmd` into a pending-message
- * pool and recording the full `(event → resulting cluster states)` trace.
- *
- * Because the underlying reducer is pure (no ambient clock — `at` rides on the
- * Msg; no ambient RNG — `rng` injected once per node), the same schedule re-run
- * yields **byte-identical** cluster state. That replay identity is the property
- * the safety suite (`safety.test.ts`) leans on: a violated invariant shrinks to
- * a *replayable schedule*, not an irreproducible timing fluke (errors are data).
- *
- * ## The schedule model
- *
- * The cluster is N nodes plus a pending-message pool. Each {@link SimEvent} is
- * one of two moves:
- *
- *   - `{ kind: "timer", node, timer }` — fire node's election OR heartbeat timer.
- *     Drives an `onElectionTimeout` / `onHeartbeat` verb on that node. The
- *     firing `at` is the driver's monotonic logical clock (one tick per event),
- *     so no verb reads a real clock.
- *   - `{ kind: "deliver", index }` — deliver the in-flight message at `index` in
- *     the pending pool to its target node, as the matching inbound `RaftMsg`.
- *     An out-of-range `index` is taken modulo the pool size (so a fast-check
- *     integer always names *some* deliverable message when the pool is
- *     non-empty); a `deliver` against an empty pool is a no-op event (recorded,
- *     advances the clock, changes nothing) — the schedule stays total.
- *
- * Delivering a message removes it from the pool and feeds it to the target's
- * verb; any Cmds that verb emits are appended to the pool (each Cmd carries its
- * own `to`, so routing is just a lookup). This is the in-memory transport: a
- * `SendRequestVote{to}` delivered becomes a `RequestVoteRequest` on `to`; the
- * `SendRequestVoteReply{to}` it emits becomes a `RequestVoteReply` on the
- * original candidate; and so on around the RPC pairs.
- *
- * ## Record / replay
- *
- * {@link runSchedule} returns a {@link SimTrace}: the ordered list of steps, each
- * the event applied and the resulting per-node {@link RaftState} snapshot, plus
- * the final cluster. {@link replaySchedule} re-runs the identical schedule from a
- * fresh cluster; {@link clusterStatesEqual} compares two cluster snapshots
- * structurally. The safety suite asserts `runSchedule(s)` and
- * `replaySchedule(s)` agree byte-for-byte.
- *
- * NOT a substrate primitive and NOT shipped in the node's public verb surface:
- * it depends only on `./index` (the pure node) read-only, and lives beside the
- * node as a test/replay harness.
- */
-
-/** Which of a node's two timers a `timer` event fires. */
-type TimerKind = "election" | "heartbeat";
-/**
- * One move in a schedule. The whole simulation is a fold of these — there is no
- * other source of time or ordering. `_tag`-style `kind` discriminant matches the
- * engine's tagged-union convention.
- */
-type SimEvent = {
-    /** Fire a node's timer (drives `onElectionTimeout` / `onHeartbeat`). */
-    readonly kind: "timer";
-    /** The node whose timer fires. */
-    readonly node: NodeId;
-    /** Which timer. */
-    readonly timer: TimerKind;
-} | {
-    /**
-     * Deliver an in-flight message from the pending pool to its target. The
-     * index is taken modulo the pool size, so any integer names a deliverable
-     * message when the pool is non-empty; a deliver against an empty pool is a
-     * recorded no-op (the clock still advances).
-     */
-    readonly kind: "deliver";
-    /** Which pending message to deliver (modulo pool size). */
-    readonly index: number;
-} | {
-    /**
-     * A client submits a command to a node (Figure 2 §5.3). On the leader it
-     * appends + replicates; on a non-leader it is a no-op. This is how the
-     * replicated log grows in a simulation.
-     */
-    readonly kind: "client";
-    /** The node the client contacts. */
-    readonly node: NodeId;
-    /** The opaque command to submit. */
-    readonly command: number;
-} | {
-    /**
-     * Drain the pending pool to quiescence: deliver messages FIFO (each new
-     * Cmd a delivery emits is appended and itself delivered) until the pool is
-     * empty or `bound` deliveries have run. This is the "let the network
-     * settle" move — it lets a started election or a submitted client command
-     * run its RPC round(s) to completion, which is what actually produces
-     * leaders and committed entries. Without it, a purely-random `deliver`
-     * index almost never threads the exact sequence an election + replication
-     * needs (measured: 0 commits in 2000 random schedules vs. 529 with settle),
-     * so the safety properties would pass *vacuously* over empty logs.
-     *
-     * The `bound` caps the drain so a pathological re-emit loop cannot diverge;
-     * every step is still recorded (one trace step per delivery), so a settle
-     * is a deterministic, replayable macro — not a black box.
-     */
-    readonly kind: "settle";
-    /** Max deliveries to run (the drain is FIFO; stops early when empty). */
-    readonly bound: number;
-} | {
-    /**
-     * Set the cluster's *partitioned* node set (a network fault, NOT a state
-     * change). A node in `down` is isolated: the transport DROPS every message
-     * to OR from it (both directions, as a real partition does) while its
-     * timers still fire — so a crashed/partitioned leader stops being able to
-     * heartbeat and the surviving majority elects a new leader. This is the
-     * "kill the leader" / "heal the partition" move the failover demo needs.
-     *
-     * It names the WHOLE down-set absolutely (not a toggle): `{ down: [n0] }`
-     * isolates n0; a later `{ down: [] }` heals every partition. Recorded as
-     * one step (clock advances, no message moves), so it replays deterministically.
-     */
-    readonly kind: "partition";
-    /** The nodes that are currently isolated (drop all their traffic). */
-    readonly down: readonly NodeId[];
-};
-/** A whole schedule: the finite event stream the driver folds. */
-type Schedule = readonly SimEvent[];
-/**
- * A Cmd a node emitted, parked until a `deliver` event routes it. We keep the
- * raw {@link RaftCmd} (it already carries `to`) plus the sender, so a delivery
- * can build the correct inbound {@link RaftMsg} on the target. Commands over a
- * numeric payload (the simulation's `C = number`).
- */
-interface InFlight {
-    /** The node that emitted this Cmd (the inbound Msg's `from` / sender). */
-    readonly from: NodeId;
-    /** The emitted Cmd, addressed to `cmd.to`. */
-    readonly cmd: RaftCmd<number>;
-}
-/** A snapshot of every node's state, keyed by id. */
-type ClusterStates = Readonly<Record<NodeId, RaftState<number>>>;
-/**
- * A read-off of the message a `deliver` step actually pulled off the pending
- * pool — sender, target, and the {@link RaftCmd} discriminant (`cmd.type`). This
- * is a pure projection of what the fold *already did* (the InFlight that
- * {@link deliverOne} consumed), recorded so a renderer can draw the RPC flow.
- * It is NOT a new input and changes NO simulation behavior. Recorded even when
- * the packet is dropped by a partition (the RPC was still attempted), so the
- * arrow shows the intent while the greyed node shows the drop.
- */
-interface DeliveredMessage {
-    /** The node that emitted the delivered Cmd (the inbound Msg's sender). */
-    readonly from: NodeId;
-    /** The node the Cmd was addressed to (`cmd.to`). */
-    readonly to: NodeId;
-    /** The delivered Cmd's discriminant (`RaftCmd["type"]`). */
-    readonly kind: RaftCmd<number>["type"];
-}
-/** One recorded step: the event applied and the cluster state it produced. */
-interface SimStep {
-    /** The event applied at this step. */
-    readonly event: SimEvent;
-    /** The pending-pool size AFTER applying the event. */
-    readonly pending: number;
-    /** Every node's state after the event. */
-    readonly states: ClusterStates;
-    /**
-     * On a `deliver` step (incl. each delivery a `settle` drains), the message
-     * that was actually pulled off the pool. ABSENT on every other step kind and
-     * on a `deliver` against an empty pool — additive + backward-compatible, so a
-     * trace recorded before this field still folds and renders identically (field
-     * absent ⇒ no arrow). Purely a read-off of {@link deliverOne}'s work.
-     */
-    readonly delivered?: DeliveredMessage;
-}
-/**
- * The full record of a run: the per-node configs, the ordered steps, and the
- * final cluster. Replaying the same schedule reproduces this byte-for-byte.
- */
-interface SimTrace {
-    /** The cluster's node ids, in config order. */
-    readonly nodes: readonly NodeId[];
-    /** One step per event in the schedule (in order). */
-    readonly steps: readonly SimStep[];
-    /** The final per-node states (== `steps.at(-1)?.states` when non-empty). */
-    readonly final: ClusterStates;
-}
-/**
- * Build N node configs sharing one election-timeout window + heartbeat. Each
- * node's `peers` is every OTHER id. Ids are `n0..n{N-1}`.
- */
-declare function clusterConfigs(n: number, over?: Partial<Omit<RaftConfig, "self" | "peers">>): readonly RaftConfig[];
-/**
- * Run a schedule against a fresh N-node cluster, recording the full trace. Pure
- * given `(configs, schedule)`: no clock, no RNG, no IO — the only "time" is the
- * driver's logical clock, advanced one tick per event. Each node gets a
- * fixed-jitter rng derived from its index (distinct but deterministic timeouts).
- */
-declare function runSchedule(configs: readonly RaftConfig[], schedule: Schedule): SimTrace;
-/**
- * Replay a schedule from a fresh cluster. Identical to {@link runSchedule} (it
- * IS `runSchedule`) — exposed under a name that documents intent at the call
- * site: a replay is meant to reproduce a prior run's trace byte-for-byte.
- */
-declare function replaySchedule(configs: readonly RaftConfig[], schedule: Schedule): SimTrace;
-/**
- * Structural equality of two cluster snapshots. Used by the determinism
- * property: a run and its replay must produce identical per-node state for every
- * node. (Tests use vitest `toEqual` for the same comparison; this is the
- * dependency-free version the driver can expose for ad-hoc checks.)
- */
-declare function clusterStatesEqual(a: ClusterStates, b: ClusterStates): boolean;
-
-export { type ClusterStates, type DeliveredMessage, type InFlight, NodeId, RaftConfig, RaftState, type Schedule, type SimEvent, type SimStep, type SimTrace, type TimerKind, clusterConfigs, clusterStatesEqual, replaySchedule, runSchedule };

package/dist/raft/sim.js

@@ -1,8 +0,0 @@
-export { clusterConfigs, clusterStatesEqual, replaySchedule, runSchedule } from '../chunk-VLGARN6H.js';
-import '../chunk-6RGBKODV.js';
-import '../chunk-K7Q23EQ4.js';
-import '../chunk-2YFLOCWX.js';
-import '../chunk-MMH7CW5K.js';
-import '../chunk-QLA76GIT.js';
-//# sourceMappingURL=sim.js.map
-//# sourceMappingURL=sim.js.map

package/dist/raft/sim.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"sim.js"}

package/dist/raft/timeline.d.ts

@@ -1,46 +0,0 @@
-import { SimTrace } from './sim.js';
-import './index.js';
-import '../deadline/index.js';
-import '../core-BoB6t7dB.js';
-import '../types-B-8bcAp8.js';
-
-/**
- * @demlik/tea/raft — an ASCII step-timeline renderer for a {@link SimTrace}.
- *
- * PURE. `renderTimeline(trace)` folds a recorded trace into a deterministic,
- * paced-friendly string: a header, then one block per step — the {@link SimEvent}
- * that drove it, followed by one row per node (role · term · commit · committed
- * log), with the current leader marked and partitioned nodes flagged.
- *
- * It is a *projection of the trace*, not an instrumentation of the engine: the
- * trace already carries every node's full {@link RaftState} at every step
- * (`step.states`), so this reads that data and never touches the reducer. The
- * same renderer works for ANY trace `runSchedule` produces — the canned
- * {@link runDemo} failover, or an author's own schedule.
- *
- * Plain ASCII + a little box-drawing, no ANSI — so it renders identically in a
- * terminal, a captured asciinema cast, and a golden test assertion (the
- * deterministic-output property the rest of the raft module leans on).
- *
- * The partition set is not on `SimStep` (it lives in the sim's internal world),
- * so the renderer RECONSTRUCTS it by folding the `partition` events as it walks
- * the steps — a `{ kind: "partition", down }` sets the down-set absolutely,
- * `{ down: [] }` heals (exactly the harness's own semantics).
- */
-
-/** Options for {@link renderTimeline}. */
-interface TimelineOptions {
-    /**
-     * Drop the header banner (the `@demlik/tea/raft …` title + the column key).
-     * Default `false` — the banner is shown. A cast that frames its own title
-     * passes `true`.
-     */
-    readonly noHeader?: boolean;
-}
-/**
- * Render a whole {@link SimTrace} as an ASCII step timeline. PURE +
- * deterministic — the same trace renders byte-identically every time.
- */
-declare function renderTimeline(trace: SimTrace, opts?: TimelineOptions): string;
-
-export { type TimelineOptions, renderTimeline };

package/dist/raft/timeline.js

@@ -1,62 +0,0 @@
-// src/raft/timeline.ts
-function committedCommands(state) {
-  return state.log.slice(0, state.commitIndex).map((entry) => entry.command);
-}
-function summarizeEvent(event) {
-  switch (event.kind) {
-    case "timer":
-      return `timer    \xB7 ${event.node} ${event.timer}`;
-    case "deliver":
-      return `deliver  \xB7 in-flight msg #${event.index}`;
-    case "client":
-      return `client   \xB7 ${event.node} \u27F5 cmd ${event.command}`;
-    case "settle":
-      return `settle   \xB7 drain the network (\u2264 ${event.bound})`;
-    case "partition":
-      return event.down.length === 0 ? "partition \xB7 HEAL \u2014 every node reachable" : `partition \xB7 DOWN [${[...event.down].join(", ")}] (traffic dropped)`;
-  }
-}
-function pad(s, width) {
-  return s.length >= width ? s : s + " ".repeat(width - s.length);
-}
-function renderNodeRow(id, state, down) {
-  const isLeader = state.role._tag === "leader";
-  const isDown = down.has(id);
-  const marker = isDown ? "\u2573" : isLeader ? "\u25B8" : " ";
-  const committed = committedCommands(state);
-  const logSize = state.log.length;
-  const logCell = `[${committed.join(", ")}]${logSize > committed.length ? ` (+${logSize - committed.length} uncommitted)` : ""}`;
-  return `  ${marker} ${pad(id, 4)} ${pad(state.role._tag, 10)} term ${pad(String(state.currentTerm), 3)} commit ${pad(String(state.commitIndex), 3)} log ${logCell}${isDown ? "   (down)" : ""}`;
-}
-function renderStep(index, event, states, nodes, down) {
-  const header = `step ${pad(String(index), 3)}\u2502 ${summarizeEvent(event)}`;
-  const rows = nodes.map((id) => {
-    const state = states[id];
-    return state === void 0 ? `  \xB7 ${pad(id, 4)} (absent)` : renderNodeRow(id, state, down);
-  });
-  return [header, ...rows].join("\n");
-}
-function renderTimeline(trace, opts = {}) {
-  const blocks = [];
-  if (!opts.noHeader) {
-    const majority = Math.floor(trace.nodes.length / 2) + 1;
-    blocks.push(
-      "\u2550".repeat(64),
-      ` @demlik/tea/raft \u2014 consensus timeline  (${trace.nodes.length} nodes, majority ${majority})`,
-      ` \u25B8 leader   \u2573 partitioned   \xB7  log = [committed]`,
-      "\u2550".repeat(64)
-    );
-  }
-  let down = /* @__PURE__ */ new Set();
-  trace.steps.forEach((step, i) => {
-    if (step.event.kind === "partition") {
-      down = new Set(step.event.down);
-    }
-    blocks.push(renderStep(i + 1, step.event, step.states, trace.nodes, down));
-  });
-  return blocks.join("\n\n");
-}
-
-export { renderTimeline };
-//# sourceMappingURL=timeline.js.map
-//# sourceMappingURL=timeline.js.map

package/dist/raft/timeline.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/raft/timeline.ts"],"names":[],"mappings":"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","file":"timeline.js","sourcesContent":["/**\n * @demlik/tea/raft — an ASCII step-timeline renderer for a {@link SimTrace}.\n *\n * PURE. `renderTimeline(trace)` folds a recorded trace into a deterministic,\n * paced-friendly string: a header, then one block per step — the {@link SimEvent}\n * that drove it, followed by one row per node (role · term · commit · committed\n * log), with the current leader marked and partitioned nodes flagged.\n *\n * It is a *projection of the trace*, not an instrumentation of the engine: the\n * trace already carries every node's full {@link RaftState} at every step\n * (`step.states`), so this reads that data and never touches the reducer. The\n * same renderer works for ANY trace `runSchedule` produces — the canned\n * {@link runDemo} failover, or an author's own schedule.\n *\n * Plain ASCII + a little box-drawing, no ANSI — so it renders identically in a\n * terminal, a captured asciinema cast, and a golden test assertion (the\n * deterministic-output property the rest of the raft module leans on).\n *\n * The partition set is not on `SimStep` (it lives in the sim's internal world),\n * so the renderer RECONSTRUCTS it by folding the `partition` events as it walks\n * the steps — a `{ kind: \"partition\", down }` sets the down-set absolutely,\n * `{ down: [] }` heals (exactly the harness's own semantics).\n */\n\nimport type { NodeId, RaftState } from \"./index\";\nimport type { ClusterStates, SimEvent, SimTrace } from \"./sim\";\n\n/** Options for {@link renderTimeline}. */\nexport interface TimelineOptions {\n  /**\n   * Drop the header banner (the `@demlik/tea/raft …` title + the column key).\n   * Default `false` — the banner is shown. A cast that frames its own title\n   * passes `true`.\n   */\n  readonly noHeader?: boolean;\n}\n\n/** The committed commands of a node — `log[0 .. commitIndex)`, in order. */\nfunction committedCommands(state: RaftState<number>): number[] {\n  return state.log.slice(0, state.commitIndex).map((entry) => entry.command);\n}\n\n/** One-line summary of the move a step applied. */\nfunction summarizeEvent(event: SimEvent): string {\n  switch (event.kind) {\n    case \"timer\":\n      return `timer    · ${event.node} ${event.timer}`;\n    case \"deliver\":\n      return `deliver  · in-flight msg #${event.index}`;\n    case \"client\":\n      return `client   · ${event.node} ⟵ cmd ${event.command}`;\n    case \"settle\":\n      return `settle   · drain the network (≤ ${event.bound})`;\n    case \"partition\":\n      return event.down.length === 0\n        ? \"partition · HEAL — every node reachable\"\n        : `partition · DOWN [${[...event.down].join(\", \")}] (traffic dropped)`;\n  }\n}\n\n/** Pad `s` to `width` with trailing spaces (left-aligned column). */\nfunction pad(s: string, width: number): string {\n  return s.length >= width ? s : s + \" \".repeat(width - s.length);\n}\n\n/**\n * Render one node's row. The leader of the cluster is marked with `▸`; a\n * partitioned (down) node is dimmed with `╳` and a `(down)` tag — it keeps\n * showing its last-known state because, isolated, it cannot learn otherwise.\n */\nfunction renderNodeRow(\n  id: NodeId,\n  state: RaftState<number>,\n  down: ReadonlySet<NodeId>,\n): string {\n  const isLeader = state.role._tag === \"leader\";\n  const isDown = down.has(id);\n  const marker = isDown ? \"╳\" : isLeader ? \"▸\" : \" \";\n  const committed = committedCommands(state);\n  const logSize = state.log.length;\n  // committed/total so a row shows replication progress (committed ≤ total).\n  const logCell = `[${committed.join(\", \")}]${\n    logSize > committed.length\n      ? ` (+${logSize - committed.length} uncommitted)`\n      : \"\"\n  }`;\n  return (\n    `  ${marker} ${pad(id, 4)} ${pad(state.role._tag, 10)} ` +\n    `term ${pad(String(state.currentTerm), 3)} ` +\n    `commit ${pad(String(state.commitIndex), 3)} ` +\n    `log ${logCell}${isDown ? \"   (down)\" : \"\"}`\n  );\n}\n\n/** Render one step block: the event header + every node's row. */\nfunction renderStep(\n  index: number,\n  event: SimEvent,\n  states: ClusterStates,\n  nodes: readonly NodeId[],\n  down: ReadonlySet<NodeId>,\n): string {\n  const header = `step ${pad(String(index), 3)}│ ${summarizeEvent(event)}`;\n  const rows = nodes.map((id) => {\n    const state = states[id];\n    return state === undefined\n      ? `  · ${pad(id, 4)} (absent)`\n      : renderNodeRow(id, state, down);\n  });\n  return [header, ...rows].join(\"\\n\");\n}\n\n/**\n * Render a whole {@link SimTrace} as an ASCII step timeline. PURE +\n * deterministic — the same trace renders byte-identically every time.\n */\nexport function renderTimeline(\n  trace: SimTrace,\n  opts: TimelineOptions = {},\n): string {\n  const blocks: string[] = [];\n  if (!opts.noHeader) {\n    const majority = Math.floor(trace.nodes.length / 2) + 1;\n    blocks.push(\n      \"═\".repeat(64),\n      ` @demlik/tea/raft — consensus timeline` +\n        `  (${trace.nodes.length} nodes, majority ${majority})`,\n      ` ▸ leader   ╳ partitioned   ·  log = [committed]`,\n      \"═\".repeat(64),\n    );\n  }\n  // Fold the partition set as we walk — a `partition` event sets it absolutely.\n  let down: ReadonlySet<NodeId> = new Set();\n  trace.steps.forEach((step, i) => {\n    if (step.event.kind === \"partition\") {\n      down = new Set(step.event.down);\n    }\n    blocks.push(renderStep(i + 1, step.event, step.states, trace.nodes, down));\n  });\n  return blocks.join(\"\\n\\n\");\n}\n"]}