@demlik/tea 0.1.0 → 0.1.2

package/dist/chunk-VLGARN6H.js

@@ -0,0 +1,202 @@
+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

@@ -0,0 +1 @@
+{"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/circuit-breaker/index.js

@@ -1,53 +1,3 @@
-// src/circuit-breaker/index.ts
-var defaultCircuitPolicy = {
-  failureThreshold: 5,
-  cooldownMs: 3e4,
-  halfOpenMaxProbes: 1
-};
-function initCircuit() {
-  return { phase: "closed", failures: 0 };
-}
-function onSuccess(state, _policy) {
-  switch (state.phase) {
-    case "closed":
-      return state.failures === 0 ? state : { phase: "closed", failures: 0 };
-    case "half_open":
-      return { phase: "closed", failures: 0 };
-    case "open":
-      return state;
-  }
-}
-function onFailure(state, policy, nowMs) {
-  switch (state.phase) {
-    case "closed": {
-      const failures = state.failures + 1;
-      return failures >= policy.failureThreshold ? { phase: "open", openedAtMs: nowMs } : { phase: "closed", failures };
-    }
-    case "half_open":
-      return { phase: "open", openedAtMs: nowMs };
-    case "open":
-      return state;
-  }
-}
-function canPass(state, policy, nowMs) {
-  switch (state.phase) {
-    case "closed":
-      return [state, true];
-    case "open": {
-      const elapsed = nowMs - state.openedAtMs;
-      if (elapsed >= policy.cooldownMs) {
-        return [{ phase: "half_open", probes: 1 }, true];
-      }
-      return [state, false];
-    }
-    case "half_open":
-      if (state.probes < policy.halfOpenMaxProbes) {
-        return [{ phase: "half_open", probes: state.probes + 1 }, true];
-      }
-      return [state, false];
-  }
-}
-
-export { canPass, defaultCircuitPolicy, initCircuit, onFailure, onSuccess };
+export { canPass, defaultCircuitPolicy, initCircuit, onFailure, onSuccess } from '../chunk-SC3FAFZN.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/circuit-breaker/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/circuit-breaker/index.ts"],"names":[],"mappings":";AAwHO,IAAM,oBAAA,GAAsC;AAAA,EACjD,gBAAA,EAAkB,CAAA;AAAA,EAClB,UAAA,EAAY,GAAA;AAAA,EACZ,iBAAA,EAAmB;AACrB;AAoBO,SAAS,WAAA,GAA4B;AAC1C,EAAA,OAAO,EAAE,KAAA,EAAO,QAAA,EAAU,QAAA,EAAU,CAAA,EAAE;AACxC;AAYO,SAAS,SAAA,CACd,OACA,OAAA,EACc;AACd,EAAA,QAAQ,MAAM,KAAA;AAAO,IACnB,KAAK,QAAA;AAGH,MAAA,OAAO,KAAA,CAAM,aAAa,CAAA,GAAI,KAAA,GAAQ,EAAE,KAAA,EAAO,QAAA,EAAU,UAAU,CAAA,EAAE;AAAA,IACvE,KAAK,WAAA;AACH,MAAA,OAAO,EAAE,KAAA,EAAO,QAAA,EAAU,QAAA,EAAU,CAAA,EAAE;AAAA,IACxC,KAAK,MAAA;AACH,MAAA,OAAO,KAAA;AAAA;AAEb;AAgBO,SAAS,SAAA,CACd,KAAA,EACA,MAAA,EACA,KAAA,EACc;AACd,EAAA,QAAQ,MAAM,KAAA;AAAO,IACnB,KAAK,QAAA,EAAU;AACb,MAAA,MAAM,QAAA,GAAW,MAAM,QAAA,GAAW,CAAA;AAGlC,MAAA,OAAO,QAAA,IAAY,MAAA,CAAO,gBAAA,GACtB,EAAE,KAAA,EAAO,MAAA,EAAQ,UAAA,EAAY,KAAA,EAAM,GACnC,EAAE,KAAA,EAAO,QAAA,EAAU,QAAA,EAAS;AAAA,IAClC;AAAA,IACA,KAAK,WAAA;AAEH,MAAA,OAAO,EAAE,KAAA,EAAO,MAAA,EAAQ,UAAA,EAAY,KAAA,EAAM;AAAA,IAC5C,KAAK,MAAA;AACH,MAAA,OAAO,KAAA;AAAA;AAEb;AA0BO,SAAS,OAAA,CACd,KAAA,EACA,MAAA,EACA,KAAA,EACkC;AAClC,EAAA,QAAQ,MAAM,KAAA;AAAO,IACnB,KAAK,QAAA;AACH,MAAA,OAAO,CAAC,OAAO,IAAI,CAAA;AAAA,IACrB,KAAK,MAAA,EAAQ;AACX,MAAA,MAAM,OAAA,GAAU,QAAQ,KAAA,CAAM,UAAA;AAG9B,MAAA,IAAI,OAAA,IAAW,OAAO,UAAA,EAAY;AAChC,QAAA,OAAO,CAAC,EAAE,KAAA,EAAO,aAAa,MAAA,EAAQ,CAAA,IAAK,IAAI,CAAA;AAAA,MACjD;AACA,MAAA,OAAO,CAAC,OAAO,KAAK,CAAA;AAAA,IACtB;AAAA,IACA,KAAK,WAAA;AACH,MAAA,IAAI,KAAA,CAAM,MAAA,GAAS,MAAA,CAAO,iBAAA,EAAmB;AAC3C,QAAA,OAAO,CAAC,EAAE,KAAA,EAAO,WAAA,EAAa,QAAQ,KAAA,CAAM,MAAA,GAAS,CAAA,EAAE,EAAG,IAAI,CAAA;AAAA,MAChE;AACA,MAAA,OAAO,CAAC,OAAO,KAAK,CAAA;AAAA;AAE1B","file":"index.js","sourcesContent":["/**\n * @demlik/tea/circuit-breaker — per-target failure tracking as pure state + ops.\n *\n * Same shape as `@demlik/tea/work-queue`'s `ops.ts`, `@demlik/tea/rate-limit`,\n * and `@demlik/tea/idempotency`: a state type plus pure transition functions.\n * Host-agnostic by construction — no `Date.now()`, no timers, no I/O. The\n * caller injects the clock (`nowMs`) and wires the result into its own reducer\n * / interpret. This keeps the breaker inside TEA's invariant 2 (transitions are\n * pure: same inputs → same outputs, no `Date.now`) so a consumer can fold it\n * through `update` and exercise it with `replay` / the pbt fold without a fake\n * clock.\n *\n * Every op returns a NEW state value and never mutates its input (invariant 1 —\n * state is a value, not a place). `canPass` returns a `[next, allowed]` tuple so\n * the caller branches on the decision while threading the advanced state forward\n * — same convention as `rate-limit`'s `tryConsume` / `record`. `onSuccess` /\n * `onFailure` are the outcome-recording transitions the caller folds in once the\n * guarded call resolves.\n *\n * ## The phase machine\n *\n * A circuit breaker guards a fallible downstream target (an HTTP backend, a DB,\n * a flaky tool call). Instead of hammering a target that is already failing, it\n * trips OPEN after enough failures and fast-fails subsequent calls for a\n * cooldown, then probes with a few trial calls before fully closing again.\n * Three phases, each carrying ONLY its own data so impossible states are\n * unrepresentable (pattern 11):\n *\n *   - **closed** — the healthy steady state. Calls pass through. Carries\n *     `failures`: the count of *consecutive* failures since the last success.\n *     A success resets it to 0; the `failureThreshold`-th failure trips the\n *     breaker OPEN. Only `closed` has a failure counter — `open` and\n *     `half_open` don't, because in those phases the count is irrelevant\n *     (the breaker has already tripped / is already probing).\n *\n *   - **open** — the tripped state. All calls fast-fail (no downstream load).\n *     Carries `openedAtMs`: the clock reading at which the breaker tripped.\n *     `canPass` compares `nowMs - openedAtMs` against `cooldownMs` to decide\n *     when to start probing. Only `open` carries a timestamp — neither other\n *     phase is timing anything.\n *\n *   - **half_open** — the probing state. A limited number of trial calls are\n *     allowed through to test whether the target has recovered. Carries\n *     `probes`: the count of probes admitted so far this probing round.\n *     `canPass` admits while `probes < halfOpenMaxProbes`, then fast-fails the\n *     rest (so a slow target can't be flooded by every queued caller at once).\n *     A probe success closes the breaker; a probe failure re-opens it (and\n *     resets the cooldown clock). Only `half_open` counts in-flight probes.\n *\n * ### Transition table\n *\n * Rows are the current phase; columns are the event. `→` denotes the next\n * phase; `self` means unchanged. `nowMs` is the injected clock.\n *\n * | from \\ event | onSuccess      | onFailure                              | canPass (→ allowed?)                                                                 |\n * | ------------ | -------------- | -------------------------------------- | ------------------------------------------------------------------------------------ |\n * | closed       | closed(0)      | failures+1; trip → open(nowMs) at thr. | self → true (always)                                                                  |\n * | open         | self *(¹)*     | self                                   | elapsed ≥ cooldown → half_open(1), true; else self → false                            |\n * | half_open    | → closed(0)    | → open(nowMs) (probe failed)           | probes < max → half_open(probes+1), true; else self → false                          |\n *\n * *(¹)* `onSuccess` on `open` \"shouldn't happen\": no call was admitted while\n * open, so no success can be reported for one. We leave the state unchanged\n * rather than throw — the breaker is a coordination aid, not a correctness\n * gate, and a spurious success report (e.g. a late-arriving result from before\n * the trip) must not silently un-trip the breaker. `onFailure` on `open` is\n * likewise a no-op: the breaker is already tripped; the `open` clock is anchored\n * at the trip, not bumped by late failures.\n *\n * ### The probe-admission asymmetry\n *\n * Entering `half_open` happens inside `canPass`, not `onSuccess` / `onFailure`,\n * because the cooldown is a *time* condition and only `canPass` reads the clock\n * against `openedAtMs`. The first `canPass` after the cooldown elapses both\n * transitions the phase AND admits the probe (`[half_open(1), true]`) — one\n * caller drives the recovery attempt. Subsequent `canPass` calls in the same\n * round admit up to `halfOpenMaxProbes` total, then fast-fail until a probe\n * resolves and `onSuccess` / `onFailure` moves the phase out of `half_open`.\n *\n * This module is a textbook three-state machine — a clean `/machine-viz` demo.\n *\n * NOT exported from the package root — reached via the\n * `@demlik/tea/circuit-breaker` subpath, same one-shape-per-package rule as\n * `work-queue`, `rate-limit`, and `idempotency`.\n */\n\n/**\n * Circuit-breaker policy — pure configuration, no mutable state. One policy is\n * shared across all the calls guarded by one logical breaker (often a\n * module-scope const). `CircuitState` carries the mutable counts; this carries\n * the thresholds those counts are compared against.\n */\nexport interface CircuitPolicy {\n  /**\n   * Consecutive failures in `closed` that trip the breaker `open`. The\n   * `failureThreshold`-th failure is the one that trips — with a threshold of\n   * 5, the breaker survives 4 failures and opens on the 5th.\n   */\n  readonly failureThreshold: number;\n  /**\n   * How long the breaker stays `open` before `canPass` starts admitting\n   * probes, in milliseconds. Measured from `openedAtMs`; the cutoff is\n   * half-open (`elapsed >= cooldownMs` admits), matching `rate-limit` /\n   * `idempotency` window edges — a breaker opened at `t` first probes at\n   * `t + cooldownMs`.\n   */\n  readonly cooldownMs: number;\n  /**\n   * How many probe calls `half_open` admits before fast-failing the rest of\n   * the round. Caps the load on a recovering target — a single slow probe\n   * can't be joined by every queued caller. The round ends when a probe\n   * resolves: success closes the breaker, failure re-opens it.\n   */\n  readonly halfOpenMaxProbes: number;\n}\n\n/**\n * Sensible defaults: trip after 5 consecutive failures, cool down for 30s,\n * admit a single probe before deciding. Tuned for guarding a network backend;\n * override per call site rather than mutating this shared const.\n */\nexport const defaultCircuitPolicy: CircuitPolicy = {\n  failureThreshold: 5,\n  cooldownMs: 30_000,\n  halfOpenMaxProbes: 1,\n};\n\n/**\n * The breaker's phase. A discriminated union on `phase` so each phase carries\n * ONLY its own data and impossible combinations are unrepresentable (pattern\n * 11): there is no state with both a failure count AND an open timestamp,\n * because such a state is meaningless. `phase` is the discriminant; every field\n * is `readonly` so the whole value is trivially JSON-serializable into a\n * consumer's `Store<S>` and safe to thread through a pure reducer.\n *\n *   - `closed`    carries `failures`   — consecutive failures since last success.\n *   - `open`      carries `openedAtMs` — clock reading when it tripped.\n *   - `half_open` carries `probes`     — probes admitted this round.\n */\nexport type CircuitState =\n  | { readonly phase: \"closed\"; readonly failures: number }\n  | { readonly phase: \"open\"; readonly openedAtMs: number }\n  | { readonly phase: \"half_open\"; readonly probes: number };\n\n/** The starting state: closed with zero recorded failures. */\nexport function initCircuit(): CircuitState {\n  return { phase: \"closed\", failures: 0 };\n}\n\n/**\n * Record a successful guarded call. PURE — returns a new state; the input is\n * never mutated.\n *\n *   - `closed`    → reset `failures` to 0 (a success breaks the consecutive run).\n *   - `half_open` → the probe succeeded; the target has recovered → `closed`.\n *   - `open`      → unchanged. A success \"shouldn't happen\" while open (no call\n *                   was admitted to produce one); a late/spurious success must\n *                   not silently un-trip the breaker. See module header note ¹.\n */\nexport function onSuccess(\n  state: CircuitState,\n  _policy: CircuitPolicy,\n): CircuitState {\n  switch (state.phase) {\n    case \"closed\":\n      // Already closed at 0 → return the same shape (cheap; the consumer's\n      // store only re-persists on a real change if it dedupes).\n      return state.failures === 0 ? state : { phase: \"closed\", failures: 0 };\n    case \"half_open\":\n      return { phase: \"closed\", failures: 0 };\n    case \"open\":\n      return state;\n  }\n}\n\n/**\n * Record a failed guarded call. PURE — returns a new state; the input is never\n * mutated. `nowMs` is the injected clock, stamped onto the `open` phase when the\n * breaker trips so `canPass` can measure the cooldown later.\n *\n *   - `closed`    → `failures + 1`; if that reaches `failureThreshold`, trip to\n *                   `open(nowMs)`. The threshold-th failure is the one that trips.\n *   - `half_open` → the probe failed; the target is still unhealthy →\n *                   `open(nowMs)`, restarting the cooldown clock so a fresh\n *                   cooldown elapses before the next probe round.\n *   - `open`      → unchanged. The breaker is already tripped; the `open` clock\n *                   is anchored at the original trip, not bumped by late\n *                   failures. See module header note ¹.\n */\nexport function onFailure(\n  state: CircuitState,\n  policy: CircuitPolicy,\n  nowMs: number,\n): CircuitState {\n  switch (state.phase) {\n    case \"closed\": {\n      const failures = state.failures + 1;\n      // `>=` not `===`: a threshold of 0 (or any already-exceeded count from a\n      // policy change) trips immediately rather than over-counting forever.\n      return failures >= policy.failureThreshold\n        ? { phase: \"open\", openedAtMs: nowMs }\n        : { phase: \"closed\", failures };\n    }\n    case \"half_open\":\n      // A failed probe re-opens and resets the cooldown clock to nowMs.\n      return { phase: \"open\", openedAtMs: nowMs };\n    case \"open\":\n      return state;\n  }\n}\n\n/**\n * Decide whether a call may pass, advancing the phase as a side effect of the\n * decision. PURE — returns `[next, allowed]`; the input is never mutated.\n * Branch on the boolean, thread the state forward regardless:\n *\n *   const [c1, allowed] = canPass(state.circuit, policy, nowMs);\n *   if (!allowed) return [{ ...state, circuit: c1 }, [fastFailCmd]];\n *   return [{ ...state, circuit: c1 }, [doGuardedCallCmd]];\n *\n *   - `closed`    → `[state, true]` — always passes; failures are recorded by\n *                   `onFailure` once the call resolves, not gated here.\n *   - `open`      → if `nowMs - openedAtMs >= cooldownMs` the cooldown has\n *                   elapsed → enter `half_open` and admit this caller as the\n *                   first probe: `[half_open(1), true]`. Otherwise still cooling\n *                   down → `[state, false]` (fast-fail, no downstream load).\n *   - `half_open` → admit while `probes < halfOpenMaxProbes`, incrementing the\n *                   count: `[half_open(probes+1), true]`. Once the cap is hit →\n *                   `[state, false]` until a probe resolves and `onSuccess` /\n *                   `onFailure` moves the phase out of `half_open`.\n *\n * Entering `half_open` lives here (not in `onSuccess` / `onFailure`) because the\n * cooldown is a time condition and only `canPass` reads `nowMs` against\n * `openedAtMs`. See the module header's probe-admission note.\n */\nexport function canPass(\n  state: CircuitState,\n  policy: CircuitPolicy,\n  nowMs: number,\n): readonly [CircuitState, boolean] {\n  switch (state.phase) {\n    case \"closed\":\n      return [state, true];\n    case \"open\": {\n      const elapsed = nowMs - state.openedAtMs;\n      // Half-open cutoff: elapsed exactly == cooldownMs admits the first probe,\n      // matching the >= edge `rate-limit` / `idempotency` use for their windows.\n      if (elapsed >= policy.cooldownMs) {\n        return [{ phase: \"half_open\", probes: 1 }, true];\n      }\n      return [state, false];\n    }\n    case \"half_open\":\n      if (state.probes < policy.halfOpenMaxProbes) {\n        return [{ phase: \"half_open\", probes: state.probes + 1 }, true];\n      }\n      return [state, false];\n  }\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/core-BoB6t7dB.d.ts

@@ -0,0 +1,188 @@
+type SyncReturn<S, C extends Cmd> = readonly [S, readonly C[]] & {
+    readonly then?: never;
+};
+type UpdateForm = "reducer" | "transitions";
+declare function detectUpdateForm(update: object): UpdateForm;
+declare function formOf(machine: {
+    update: object;
+    __form?: UpdateForm;
+}): UpdateForm;
+declare function applyCell<S, M extends {
+    type: string;
+}, C extends Cmd>(machine: {
+    update: object;
+    __form?: UpdateForm;
+}, state: S, msg: M): readonly [S, readonly C[]];
+declare function msgKeysOf(machine: {
+    update: object;
+    __form?: UpdateForm;
+}): readonly string[];
+type Reducer<S, M extends {
+    type: string;
+}, C extends Cmd> = {
+    [K in M["type"]]: (state: S, msg: Extract<M, {
+        type: K;
+    }>) => SyncReturn<S, C>;
+};
+type Transitions<S extends {
+    type: string;
+}, M extends {
+    type: string;
+}, C extends Cmd> = {
+    [P in S["type"]]: {
+        [K in M["type"]]: (state: Extract<S, {
+            type: P;
+        }>, msg: Extract<M, {
+            type: K;
+        }>) => SyncReturn<S, C>;
+    };
+};
+type Cmd<T extends string = string> = {
+    type: T;
+};
+declare const Cmd: {
+    /**
+     * The empty Cmd array. Typed `readonly never[]` so it's assignable to any
+     * `readonly C[]` for any `C extends Cmd`. Use in `init` returns and
+     * Transitions cells that emit zero effects:
+     *
+     *   init: (loaded) => [loaded ?? initial, Cmd.none],
+     *   tick: (state) => [state, Cmd.none],
+     *
+     * Elm's `Cmd.none` analogue. Cultural signal alongside the runtime help:
+     * `[state, Cmd.none]` reads as intent ("this transition emits nothing"),
+     * `[state, []]` reads as "empty array of what".
+     *
+     * Frozen at runtime so a downstream consumer can't `.push()` into the
+     * shared reference.
+     */
+    readonly none: readonly never[];
+    /**
+     * Flat concat of cmd arrays. Use when a cell composes effects from
+     * multiple conditional sources:
+     *
+     *   return [next, Cmd.batch(
+     *     Cmd.whenDefined(state.queueItemId, (id) => ({ type: "complete", id })),
+     *     Cmd.when(state.windowId !== undefined, { type: "close_window", windowId }),
+     *     [{ type: "detach_debugger", tabId: state.tabId }],
+     *   )];
+     *
+     * `<const C>` keeps inline cmd literals' discriminants narrow (same
+     * rationale as `when` / `whenDefined` above).
+     */
+    readonly batch: <const C extends Cmd>(...arrs: readonly (readonly C[])[]) => readonly C[];
+    /**
+     * Emit `cmd` wrapped in a single-element array iff `cond` is true.
+     * Otherwise return the empty array. Spreads cleanly into the cmds array
+     * returned by a Transitions cell.
+     *
+     * `const C` (TypeScript 5.0+) keeps the inferred `type:` discriminator
+     * literal narrow when called with an object literal — so `Cmd.when(b,
+     * { type: "x", ... })` infers as `{ type: "x", ... }`, not `{ type:
+     * string, ... }`, and stays assignable to a discriminated-union arm
+     * without `as const` at the call site.
+     */
+    readonly when: <const C extends Cmd>(cond: boolean, cmd: C) => readonly C[];
+    /**
+     * If `value` is defined, call `build(value)` and emit the resulting cmd
+     * wrapped in a single-element array. If `value` is `undefined`, return
+     * the empty array. `value` is narrowed to `T` inside `build`.
+     *
+     * `const C` on the return type keeps the callback's object-literal
+     * `type:` field narrow (see `when` above for the full rationale).
+     */
+    readonly whenDefined: <T, const C extends Cmd>(value: T | undefined, build: (value: T) => C) => readonly C[];
+};
+type SubId = string & {
+    readonly __brand: "SubId";
+};
+/**
+ * Construct a `SubId` from a string. Use this everywhere a Sub literal is
+ * built — including ids derived from runtime data (`subId(\`ws:${auditId}\`)`).
+ * The brand is structural, not nominal, so dynamic ids are permitted; the
+ * constructor's job is to make the identity decision explicit at every call
+ * site so the type system can catch accidental raw-string drift.
+ *
+ * Strengthens invariant 7 (identity is explicit).
+ */
+declare function subId(s: string): SubId;
+type Sub<T extends string = string> = {
+    id: SubId;
+    type: T;
+};
+interface Port<T> {
+    readonly __brand: "port";
+    readonly name: string;
+    readonly __t?: T;
+}
+/**
+ * Augmentation injected onto `ctx` inside Cmd handlers. Handlers receive
+ * `ctx & PortEmitter` so they can call `ctx.emit(port, value)` synchronously.
+ * Subscribers registered via `runtime.subscribePort(port, listener)` receive
+ * the value immediately.
+ *
+ * Emitting to a port with no subscribers is a no-op (does not throw).
+ */
+interface PortEmitter {
+    emit<T>(port: Port<T>, value: T): void;
+}
+type NoCtx = Readonly<Record<never, never>>;
+/** Spelled-out alias for `NoCtx`, for sites that prefer the long name. */
+type ContextFree = NoCtx;
+type Interpret<M extends {
+    type: string;
+}, C extends Cmd, Ctx> = {
+    [K in C["type"]]: (cmd: Extract<C, {
+        type: K;
+    }>, ctx: Ctx & PortEmitter) => Promise<M | void>;
+};
+type Subscribe<M extends {
+    type: string;
+}, U extends Sub, Ctx> = {
+    [K in U["type"]]: (sub: Extract<U, {
+        type: K;
+    }>, ctx: Ctx, dispatch: (msg: M) => void) => () => void;
+};
+type Machine<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx> = {
+    /**
+     * Boot the runtime. Called once by `run(...)` with whatever `Store.load()`
+     * returned: `null` on fresh boot, the persisted state on rehydrate.
+     *
+     * **Contract:** when `loaded !== null`, init MUST return `[loaded, []]` —
+     * no Cmds. Init's rehydrate branch is the migration / parse boundary, not
+     * the boot-effect hook. See Invariant 2 in `.patterns/tea/tea-invariants.md`.
+     *
+     * Boot effects routes:
+     *   - Stateless infrastructure → host module top, outside TEA.
+     *   - State-conditional resume → a `boot` Msg the host dispatches once
+     *     after `run(...)` returns.
+     *
+     * Violations are caught at runtime by `replay` (which throws with a
+     * pointer to the alternatives).
+     */
+    init: (loaded: S | null, ctx: Ctx) => readonly [S, readonly C[]];
+    update: Reducer<S, M, C> | ([S] extends [{
+        type: string;
+    }] ? Transitions<S, M, C> : never);
+    subscriptions?: (state: S) => readonly U[];
+    subscribe?: Subscribe<M, U, Ctx>;
+    /**
+     * The update form ("reducer" | "transitions"), stamped non-enumerably by
+     * `defineMachine` at construction (see `UpdateForm` / `formOf`). Optional in
+     * the type so the structural `Machine` annotation form keeps accepting plain
+     * object literals; readers go through `formOf`, which falls back to
+     * `detectUpdateForm` when the tag is absent. Never written by hand.
+     */
+    readonly __form?: UpdateForm;
+} & ([C] extends [Cmd<never>] ? {
+    interpret?: Interpret<M, C, Ctx>;
+} : {
+    interpret: Interpret<M, C, Ctx>;
+});
+declare function foldMsgs<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, base: S, msgs: readonly M[]): S;
+
+export { Cmd as C, type Interpret as I, type Machine as M, type NoCtx as N, type Port as P, type Reducer as R, type Sub as S, type Transitions as T, type UpdateForm as U, type SubId as a, type ContextFree as b, type PortEmitter as c, type Subscribe as d, type SyncReturn as e, applyCell as f, detectUpdateForm as g, foldMsgs as h, formOf as i, msgKeysOf as m, subId as s };

package/dist/deadline/index.d.ts

@@ -1,5 +1,5 @@
-import { Sub } from '../index.js';
-import { S as SubscribeHandler } from '../types-CwBC5wMn.js';
+import { S as Sub } from '../core-BoB6t7dB.js';
+import { S as SubscribeHandler } from '../types-B-8bcAp8.js';
 
 /**
  * @demlik/tea/deadline — a one-shot Sub that fires when an ABSOLUTE wall-clock
@@ -48,7 +48,21 @@ import { S as SubscribeHandler } from '../types-CwBC5wMn.js';
  */
 type DeadlineSub = Sub<"deadline"> & {
     readonly atMs: number;
-};
+} & DeadlineOpts;
+/**
+ * Additive options the `deadlineSub` factory folds onto the Sub literal. This
+ * is the extension seam (invariant 5 — composition by reduction): future fields
+ * — `repeatMs` for a re-arming deadline, `jitterMs` for spread, etc. — land HERE
+ * as optional members, and every existing call site keeps compiling because the
+ * factory's third parameter is optional and the fields are `readonly` optionals
+ * on `DeadlineSub`. Callers are insulated from the concrete `DeadlineSub` shape:
+ * they ask for what they need by name, never positionally, so a shape extension
+ * never rewrites the ~13 `deadlineSub(id, atMs)` call sites.
+ *
+ * Empty today on purpose — the seam exists before the first extension does, so
+ * the first field is a one-line additive change, not a 13-site migration.
+ */
+type DeadlineOpts = {};
 /**
  * The Msg the deadline dispatches when the wall clock crosses `atMs`. Exported
  * as a tagged shape so consumers can union it into their machine's Msg type and
@@ -83,8 +97,13 @@ type DeadlineExceeded = {
  *             deadlines on the same machine.
  * @param atMs Absolute target in epoch milliseconds (e.g. `Date.now() + 900_000`
  *             for a 15-minute guard, or a persisted `expiresAt`).
+ * @param opts Optional additive fields folded onto the Sub literal (see
+ *             {@link DeadlineOpts}). Omit it for the common case; pass it when a
+ *             future field (e.g. `repeatMs`) needs to ride on the deadline. The
+ *             optionality is the future-proofing seam — extending the shape
+ *             never breaks an existing `deadlineSub(id, atMs)` call site.
  */
-declare function deadlineSub(id: string, atMs: number): DeadlineSub;
+declare function deadlineSub(id: string, atMs: number, opts?: DeadlineOpts): DeadlineSub;
 /**
  * The `subscribe["deadline"]` cell. Arms a one-shot timer for the remaining
  * delay `max(0, atMs - Date.now())` and dispatches `deadlineExceeded(...)` when
@@ -110,4 +129,4 @@ declare const subscribeDeadline: SubscribeHandler<DeadlineSub, DeadlineExceeded,
  */
 declare function deadlineExceeded(id: string, atMs: number): DeadlineExceeded;
 
-export { type DeadlineExceeded, type DeadlineSub, deadlineExceeded, deadlineSub, subscribeDeadline };
+export { type DeadlineExceeded, type DeadlineOpts, type DeadlineSub, deadlineExceeded, deadlineSub, subscribeDeadline };

package/dist/deadline/index.js

@@ -1,20 +1,6 @@
-import { fromTimeout } from '../chunk-2YFLOCWX.js';
-import { subId } from '../chunk-CMG2KMWX.js';
-
-// src/deadline/index.ts
-function deadlineSub(id, atMs) {
-  return { id: subId(id), type: "deadline", atMs };
-}
-var subscribeDeadline = (sub, ctx, dispatch) => {
-  const remainingMs = Math.max(0, sub.atMs - Date.now());
-  return fromTimeout(
-    (armed) => deadlineExceeded(armed.id, armed.atMs)
-  )({ ...sub, delayMs: remainingMs }, ctx, dispatch);
-};
-function deadlineExceeded(id, atMs) {
-  return { type: "deadline_exceeded", id, atMs };
-}
-
-export { deadlineExceeded, deadlineSub, subscribeDeadline };
+export { deadlineExceeded, deadlineSub, subscribeDeadline } from '../chunk-K7Q23EQ4.js';
+import '../chunk-2YFLOCWX.js';
+import '../chunk-MMH7CW5K.js';
+import '../chunk-QLA76GIT.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/deadline/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/deadline/index.ts"],"names":[],"mappings":";;;;AAuFO,SAAS,WAAA,CAAY,IAAY,IAAA,EAA2B;AACjE,EAAA,OAAO,EAAE,EAAA,EAAI,KAAA,CAAM,EAAE,CAAA,EAAG,IAAA,EAAM,YAAY,IAAA,EAAK;AACjD;AAmBO,IAAM,iBAAA,GAA8E,CACzF,GAAA,EACA,GAAA,EACA,QAAA,KACG;AAKH,EAAA,MAAM,WAAA,GAAc,KAAK,GAAA,CAAI,CAAA,EAAG,IAAI,IAAA,GAAO,IAAA,CAAK,KAAK,CAAA;AAMrD,EAAA,OAAO,WAAA;AAAA,IAAiE,CAAC,KAAA,KACvE,gBAAA,CAAiB,KAAA,CAAM,EAAA,EAAI,MAAM,IAAI;AAAA,GACvC,CAAE,EAAE,GAAG,GAAA,EAAK,SAAS,WAAA,EAAY,EAAG,KAAK,QAAQ,CAAA;AACnD;AAOO,SAAS,gBAAA,CAAiB,IAAY,IAAA,EAAgC;AAC3E,EAAA,OAAO,EAAE,IAAA,EAAM,mBAAA,EAAqB,EAAA,EAAI,IAAA,EAAK;AAC/C","file":"index.js","sourcesContent":["/**\n * @demlik/tea/deadline — a one-shot Sub that fires when an ABSOLUTE wall-clock\n * deadline is reached.\n *\n * Generalizes the recurring \"auto-fail a machine at T+N\" / \"15-minute stale\n * guard\" pattern: a Sub whose `subscriptions(state)` returns it only while the\n * deadline should be armed, and which dispatches a single `DeadlineExceeded`\n * Msg when the wall clock crosses `atMs`.\n *\n * Difference from `fromTimeout` (relative — \"fire after N ms\"): a deadline is\n * an ABSOLUTE target. The delay is computed at subscribe time as\n * `max(0, atMs - Date.now())`. The consequence that matters: subscribing LATE —\n * e.g. after a `Store` rehydrate that resumes a machine whose deadline was set\n * before the page reloaded — still fires at the correct absolute moment,\n * because the remaining delay is recomputed from the current clock, not stored\n * in the Sub. A deadline already in the past at subscribe time yields delay `0`,\n * so `setTimeout(fn, 0)` fires on the NEXT tick (never synchronously inside the\n * reconcile pass — the substrate must finish wiring all subs before any Msg\n * lands).\n *\n * Composition over reinvention: the timer lifecycle is `fromTimeout`'s, not\n * redrawn here. `deadlineSub` produces the Sub literal carrying `atMs`; the\n * `subscribe` cell (`subscribeDeadline`) translates `atMs` → a relative delay\n * and delegates the `setTimeout` / `clearTimeout` to `fromTimeout`. The clock\n * read (`Date.now()`) lives only in the subscribe handler — never in a reducer\n * (invariant 2) — and is exercised in tests via vitest fake timers, matching\n * the no-injection convention of the `fromTimeout` / `fromInterval` exemplars.\n *\n * Strengthens invariant 4 (external time is a subscription — the deadline is a\n * `Sub` the runtime reconciles, never a `setTimeout` leaked into a reducer) and\n * invariant 7 (identity is explicit — the Sub carries a stable `SubId`, so the\n * reconcile pass leaves it running across transitions instead of churning it).\n */\n\nimport { type Sub, subId } from \"../index\";\nimport { fromTimeout } from \"../subs/from-timeout\";\nimport type { SubscribeHandler } from \"../subs/types\";\n\n/**\n * The Sub variant a deadline produces. `atMs` is the absolute target — epoch\n * milliseconds (the `Date.now()` / `Date.parse(...)` scale), NOT a relative\n * delay. It rides on the Sub so the reconcile pass keys identity by `id`\n * alone: the same `id` across transitions means the same armed timer, even if\n * a later `subscriptions(state)` recomputes the literal.\n *\n * Lowercase `\"deadline\"` discriminant per the Sub naming convention (a source\n * noun that doubles as the SubId family); same shape family as the\n * `TimeoutSubData` the `fromTimeout` factory consumes.\n */\nexport type DeadlineSub = Sub<\"deadline\"> & { readonly atMs: number };\n\n/**\n * The Msg the deadline dispatches when the wall clock crosses `atMs`. Exported\n * as a tagged shape so consumers can union it into their machine's Msg type and\n * handle it in a reducer cell. `id` lets a reducer disambiguate WHICH deadline\n * fired when a machine arms several at once; `atMs` echoes the target the timer\n * was scheduled against (useful for assertions / observability).\n *\n * Snake-shaped `\"deadline_exceeded\"` matches the tagged-Msg style this module's\n * orchestrator requested; the actor-in-name PascalCase convention\n * (`TimerFiredDeadline`) is the consumer's to apply at their own boundary if\n * they prefer — `deadlineExceeded(...)` only fixes the wire shape, not the\n * consumer's local dialect.\n */\nexport type DeadlineExceeded = {\n  readonly type: \"deadline_exceeded\";\n  readonly id: string;\n  readonly atMs: number;\n};\n\n/**\n * Build a deadline Sub literal. Pure data — no clock read, no timer; the timer\n * is armed later by the `subscribe` cell. `id` is branded via `subId(...)` so\n * accidental raw-string drift fails at the type level (invariant 7).\n *\n * Return the result directly from `subscriptions(state)` while the deadline\n * should be armed; drop it (return `[]`, or stop returning this id) to disarm —\n * the reconcile pass calls the cleanup, clearing the pending timer before it\n * fires. That is the \"cancel on state exit\" lifecycle, identical to\n * `fromTimeout`'s.\n *\n * @param id   Stable identity for this deadline. Same `id` across transitions =\n *             same armed timer (no churn). Use distinct ids for distinct\n *             deadlines on the same machine.\n * @param atMs Absolute target in epoch milliseconds (e.g. `Date.now() + 900_000`\n *             for a 15-minute guard, or a persisted `expiresAt`).\n */\nexport function deadlineSub(id: string, atMs: number): DeadlineSub {\n  return { id: subId(id), type: \"deadline\", atMs };\n}\n\n/**\n * The `subscribe[\"deadline\"]` cell. Arms a one-shot timer for the remaining\n * delay `max(0, atMs - Date.now())` and dispatches `deadlineExceeded(...)` when\n * it fires; returns a cleanup that clears the pending timer.\n *\n * Composes on `fromTimeout`: it adapts the absolute `atMs` on the Sub to the\n * relative `delayMs` that `fromTimeout` schedules against, then hands off the\n * `setTimeout` / `clearTimeout` lifecycle wholesale. A past deadline collapses\n * to `delayMs: 0`, so `fromTimeout` fires on the next tick — asynchronously,\n * never inside the reconcile pass.\n *\n * Assign directly to a `Subscribe` cell:\n *\n *   subscribe: {\n *     deadline: subscribeDeadline,\n *   }\n */\nexport const subscribeDeadline: SubscribeHandler<DeadlineSub, DeadlineExceeded, unknown> = (\n  sub,\n  ctx,\n  dispatch,\n) => {\n  // Recompute the remaining delay from the CURRENT clock so a late subscribe\n  // (post-rehydrate) still targets the correct absolute moment. `max(0, …)`\n  // keeps a past deadline at delay 0 → setTimeout(fn, 0) → fires next tick, not\n  // synchronously.\n  const remainingMs = Math.max(0, sub.atMs - Date.now());\n\n  // Delegate the timer lifecycle to fromTimeout: build the relative-delay Sub\n  // shape it consumes (`{ ...sub, delayMs }`) and let it own setTimeout /\n  // clearTimeout. The msgFn closes over the deadline's identity + target so the\n  // dispatched Msg carries both.\n  return fromTimeout<DeadlineSub & { delayMs: number }, DeadlineExceeded>((armed) =>\n    deadlineExceeded(armed.id, armed.atMs),\n  )({ ...sub, delayMs: remainingMs }, ctx, dispatch);\n};\n\n/**\n * Construct the Msg the deadline dispatches. Exported so consumers can build /\n * assert the same shape (and so the subscribe cell and tests share one\n * constructor rather than two literals that can drift).\n */\nexport function deadlineExceeded(id: string, atMs: number): DeadlineExceeded {\n  return { type: \"deadline_exceeded\", id, atMs };\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}