@demlik/tea 0.1.0 → 0.1.2

package/dist/raft/sim.d.ts

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

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

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

package/dist/raft/timeline.d.ts

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

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

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

package/dist/rate-limit/index.js

@@ -1,45 +1,3 @@
-// src/rate-limit/index.ts
-function initBucket(capacity, refillPerSec, nowMs) {
-  return {
-    tokens: capacity,
-    capacity,
-    refillPerSec,
-    lastRefillMs: nowMs
-  };
-}
-function refill(bucket, nowMs) {
-  const elapsedSec = Math.max(0, nowMs - bucket.lastRefillMs) / 1e3;
-  const replenished = bucket.tokens + elapsedSec * bucket.refillPerSec;
-  return {
-    ...bucket,
-    tokens: Math.min(bucket.capacity, replenished),
-    lastRefillMs: nowMs
-  };
-}
-function tryConsume(bucket, nowMs, n = 1) {
-  const refilled = refill(bucket, nowMs);
-  if (refilled.tokens >= n) {
-    return [{ ...refilled, tokens: refilled.tokens - n }, true];
-  }
-  return [refilled, false];
-}
-function initWindow(windowMs, limit) {
-  return { hits: [], windowMs, limit };
-}
-function record(window, nowMs) {
-  const cutoff = nowMs - window.windowMs;
-  const pruned = window.hits.filter((t) => t > cutoff);
-  if (pruned.length < window.limit) {
-    return [{ ...window, hits: [...pruned, nowMs] }, true];
-  }
-  return [{ ...window, hits: pruned }, false];
-}
-function remaining(window, nowMs) {
-  const cutoff = nowMs - window.windowMs;
-  const live = window.hits.filter((t) => t > cutoff).length;
-  return Math.max(0, window.limit - live);
-}
-
-export { initBucket, initWindow, record, refill, remaining, tryConsume };
+export { initBucket, initWindow, record, refill, remaining, tryConsume } from '../chunk-2YOE5PIS.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/rate-limit/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/rate-limit/index.ts"],"names":[],"mappings":";AAsDO,SAAS,UAAA,CAAW,QAAA,EAAkB,YAAA,EAAsB,KAAA,EAA4B;AAC7F,EAAA,OAAO;AAAA,IACL,MAAA,EAAQ,QAAA;AAAA,IACR,QAAA;AAAA,IACA,YAAA;AAAA,IACA,YAAA,EAAc;AAAA,GAChB;AACF;AAcO,SAAS,MAAA,CAAO,QAAqB,KAAA,EAA4B;AACtE,EAAA,MAAM,aAAa,IAAA,CAAK,GAAA,CAAI,GAAG,KAAA,GAAQ,MAAA,CAAO,YAAY,CAAA,GAAI,GAAA;AAC9D,EAAA,MAAM,WAAA,GAAc,MAAA,CAAO,MAAA,GAAS,UAAA,GAAa,MAAA,CAAO,YAAA;AACxD,EAAA,OAAO;AAAA,IACL,GAAG,MAAA;AAAA,IACH,MAAA,EAAQ,IAAA,CAAK,GAAA,CAAI,MAAA,CAAO,UAAU,WAAW,CAAA;AAAA,IAC7C,YAAA,EAAc;AAAA,GAChB;AACF;AAeO,SAAS,UAAA,CACd,MAAA,EACA,KAAA,EACA,CAAA,GAAI,CAAA,EAC6B;AACjC,EAAA,MAAM,QAAA,GAAW,MAAA,CAAO,MAAA,EAAQ,KAAK,CAAA;AACrC,EAAA,IAAI,QAAA,CAAS,UAAU,CAAA,EAAG;AACxB,IAAA,OAAO,CAAC,EAAE,GAAG,QAAA,EAAU,QAAQ,QAAA,CAAS,MAAA,GAAS,CAAA,EAAE,EAAG,IAAI,CAAA;AAAA,EAC5D;AACA,EAAA,OAAO,CAAC,UAAU,KAAK,CAAA;AACzB;AAqBO,SAAS,UAAA,CAAW,UAAkB,KAAA,EAA8B;AACzE,EAAA,OAAO,EAAE,IAAA,EAAM,EAAC,EAAG,UAAU,KAAA,EAAM;AACrC;AAgBO,SAAS,MAAA,CAAO,QAAuB,KAAA,EAAkD;AAC9F,EAAA,MAAM,MAAA,GAAS,QAAQ,MAAA,CAAO,QAAA;AAC9B,EAAA,MAAM,SAAS,MAAA,CAAO,IAAA,CAAK,OAAO,CAAC,CAAA,KAAM,IAAI,MAAM,CAAA;AACnD,EAAA,IAAI,MAAA,CAAO,MAAA,GAAS,MAAA,CAAO,KAAA,EAAO;AAChC,IAAA,OAAO,CAAC,EAAE,GAAG,MAAA,EAAQ,IAAA,EAAM,CAAC,GAAG,MAAA,EAAQ,KAAK,CAAA,EAAE,EAAG,IAAI,CAAA;AAAA,EACvD;AACA,EAAA,OAAO,CAAC,EAAE,GAAG,QAAQ,IAAA,EAAM,MAAA,IAAU,KAAK,CAAA;AAC5C;AAQO,SAAS,SAAA,CAAU,QAAuB,KAAA,EAAuB;AACtE,EAAA,MAAM,MAAA,GAAS,QAAQ,MAAA,CAAO,QAAA;AAC9B,EAAA,MAAM,IAAA,GAAO,OAAO,IAAA,CAAK,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,GAAI,MAAM,CAAA,CAAE,MAAA;AACnD,EAAA,OAAO,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,MAAA,CAAO,QAAQ,IAAI,CAAA;AACxC","file":"index.js","sourcesContent":["/**\n * @demlik/tea/rate-limit — two rate limiters as pure state + ops.\n *\n * Same shape as `@demlik/tea/work-queue`'s `ops.ts`: a state type plus pure\n * transition functions. Host-agnostic by construction — no `Date.now()`, no\n * timers, no I/O. The caller injects the clock (`nowMs`) and wires the result\n * into its own reducer / interpret. This keeps the limiters inside TEA's\n * invariant 2 (transitions are pure: same inputs → same outputs, no `Date.now`)\n * so a consumer can fold them through `update` and exercise them with `replay`\n * / the pbt fold without a fake 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). The `tryConsume` / `record` ops return a\n * `[next, ok]` tuple so the caller branches on the decision while threading the\n * advanced state forward; `refill` / `remaining` are read-shaped helpers.\n *\n * Two complementary algorithms, picked by the cost the caller wants to pay:\n *\n *   - **Token bucket** — O(1) state (four numbers), smooths bursts against a\n *     steady refill rate. Allows a burst up to `capacity`, then throttles to\n *     `refillPerSec`. Cheapest; the default choice.\n *   - **Sliding window log** — O(limit) state (one timestamp per in-window\n *     hit), exact \"no more than `limit` events per `windowMs`\". Pay the memory\n *     for precise window edges when a token bucket's continuous refill would\n *     let through too many at a boundary.\n *\n * NOT exported from the package root — reached via the `@demlik/tea/rate-limit`\n * subpath, same one-shape-per-package rule as `work-queue` and `do`.\n */\n\n// ===========================================================================\n// Token bucket\n// ===========================================================================\n\n/**\n * A token bucket: `tokens` of `capacity` available now, replenished at\n * `refillPerSec` tokens per second. `lastRefillMs` is the clock reading at\n * which `tokens` was last computed — `refill` advances it. All four fields are\n * plain numbers so the whole bucket is trivially JSON-serializable into a\n * consumer's `Store<S>`.\n */\nexport interface TokenBucket {\n  readonly tokens: number;\n  readonly capacity: number;\n  readonly refillPerSec: number;\n  readonly lastRefillMs: number;\n}\n\n/**\n * Create a full bucket. Starts at `capacity` tokens (the conventional \"a fresh\n * limiter lets the first burst through\" behavior) and stamps `lastRefillMs`\n * with the caller's clock so the first `refill` measures elapsed time from\n * boot, not from epoch 0.\n */\nexport function initBucket(capacity: number, refillPerSec: number, nowMs: number): TokenBucket {\n  return {\n    tokens: capacity,\n    capacity,\n    refillPerSec,\n    lastRefillMs: nowMs,\n  };\n}\n\n/**\n * Add the tokens accrued since `lastRefillMs`, clamped to `capacity`, and\n * advance `lastRefillMs` to `nowMs`. PURE — returns a new bucket; the input is\n * untouched.\n *\n * A `nowMs` at or before `lastRefillMs` (clock not advanced, or skewed\n * backwards) adds a non-positive amount; `Math.max(0, …)` floors the elapsed\n * term so a backwards clock can never *remove* tokens. `lastRefillMs` still\n * advances to `nowMs` so the bucket tracks the latest reading the caller\n * presented — the next forward step measures from there, not from a stale\n * future timestamp.\n */\nexport function refill(bucket: TokenBucket, nowMs: number): TokenBucket {\n  const elapsedSec = Math.max(0, nowMs - bucket.lastRefillMs) / 1000;\n  const replenished = bucket.tokens + elapsedSec * bucket.refillPerSec;\n  return {\n    ...bucket,\n    tokens: Math.min(bucket.capacity, replenished),\n    lastRefillMs: nowMs,\n  };\n}\n\n/**\n * Refill against `nowMs`, then attempt to take `n` tokens (default 1).\n *\n * On success returns `[next, true]` with `n` subtracted; on failure returns\n * `[refilled, false]` — the refilled bucket (so the caller keeps the advanced\n * clock + accrued tokens) with no tokens spent. Branch on the boolean, thread\n * the bucket forward regardless:\n *\n *   const [b1, ok] = tryConsume(bucket, nowMs);\n *   return ok ? [{ ...state, bucket: b1 }, [doWork]] : [{ ...state, bucket: b1 }, []];\n *\n * PURE — input bucket is never mutated.\n */\nexport function tryConsume(\n  bucket: TokenBucket,\n  nowMs: number,\n  n = 1,\n): readonly [TokenBucket, boolean] {\n  const refilled = refill(bucket, nowMs);\n  if (refilled.tokens >= n) {\n    return [{ ...refilled, tokens: refilled.tokens - n }, true];\n  }\n  return [refilled, false];\n}\n\n// ===========================================================================\n// Sliding window log\n// ===========================================================================\n\n/**\n * A sliding-window log: the timestamps of every hit still inside the trailing\n * `windowMs`, capped at `limit` events per window. `hits` is `readonly` and\n * kept oldest-first (pruning slices the stale prefix off the front, recording\n * appends to the back), so the array is its own sorted index. Exact at the\n * window edge — unlike a token bucket's continuous refill, a hit leaves the\n * count the instant it ages past `windowMs`.\n */\nexport interface SlidingWindow {\n  readonly hits: readonly number[];\n  readonly windowMs: number;\n  readonly limit: number;\n}\n\n/** Create an empty window. No hits recorded yet. */\nexport function initWindow(windowMs: number, limit: number): SlidingWindow {\n  return { hits: [], windowMs, limit };\n}\n\n/**\n * Prune hits older than `nowMs - windowMs`, then record `nowMs` if there is\n * room. Returns `[next, true]` with the hit appended when `hits.length < limit`\n * after pruning, else `[pruned, false]` — the pruned window (capacity recovers\n * as old hits age out) with nothing appended.\n *\n * The cutoff is half-open: a hit exactly `windowMs` old is pruned (`<= cutoff`\n * drops it), so a hit recorded at `t` no longer counts at `t + windowMs`. That\n * makes the window's capacity fully recover `windowMs` after the last hit, the\n * behavior tests pin.\n *\n * PURE — input window is never mutated; `hits` is rebuilt by `filter` +\n * spread.\n */\nexport function record(window: SlidingWindow, nowMs: number): readonly [SlidingWindow, boolean] {\n  const cutoff = nowMs - window.windowMs;\n  const pruned = window.hits.filter((t) => t > cutoff);\n  if (pruned.length < window.limit) {\n    return [{ ...window, hits: [...pruned, nowMs] }, true];\n  }\n  return [{ ...window, hits: pruned }, false];\n}\n\n/**\n * How many more hits `record` would accept at `nowMs` without blocking —\n * `limit` minus the live (post-prune) hit count, floored at 0. Read-only: it\n * prunes a local copy to answer but returns no new window. Use it to render a\n * \"N requests remaining\" affordance without committing a hit.\n */\nexport function remaining(window: SlidingWindow, nowMs: number): number {\n  const cutoff = nowMs - window.windowMs;\n  const live = window.hits.filter((t) => t > cutoff).length;\n  return Math.max(0, window.limit - live);\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/react/index.d.ts

@@ -1,4 +1,5 @@
-import { Store, Cmd, Sub, Machine, Runtime } from '../index.js';
+import { Store, Runtime } from '../index.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-BoB6t7dB.js';
 
 /**
  * @demlik/tea/react — React host adapter for `@demlik/tea`.

package/dist/react/index.js

@@ -1,30 +1,53 @@
-import { run } from '../chunk-CMG2KMWX.js';
-import { useMemo, useSyncExternalStore, useEffect } from 'react';
+import { run } from '../chunk-MMH7CW5K.js';
+import '../chunk-QLA76GIT.js';
+import { useMemo, useRef, useReducer, useSyncExternalStore, useEffect } from 'react';
 
 function useMachine(machine, opts) {
   const ctx = opts.ctx;
   const store = opts.store;
-  const runtime = useMemo(() => run(machine, { ctx, store }), [machine, ctx, store]);
-  const preliminaryState = useMemo(() => machine.init(null, ctx)[0], [machine, ctx]);
-  const getSnapshot = () => {
-    try {
-      return runtime.getState();
-    } catch {
-      return preliminaryState;
-    }
-  };
-  const state = useSyncExternalStore(runtime.subscribe, getSnapshot, getSnapshot);
-  useEffect(
-    () => () => {
-      runtime.stop().catch(() => {
-      });
-    },
-    [runtime]
+  const booting = useMemo(
+    () => run(machine, { ctx, store }),
+    [machine, ctx, store]
   );
-  return [state, runtime.dispatch];
+  const readyRef = useRef(null);
+  const [, markBooted] = useReducer((tick) => tick + 1, 0);
+  const preliminaryState = useMemo(
+    () => machine.init(null, ctx)[0],
+    [machine, ctx]
+  );
+  const getSnapshot = () => readyRef.current !== null ? readyRef.current.getState() : preliminaryState;
+  const state = useSyncExternalStore(
+    booting.subscribe,
+    getSnapshot,
+    getSnapshot
+  );
+  useEffect(() => {
+    let live = true;
+    booting.ready.then(
+      (r) => {
+        if (live) {
+          readyRef.current = r;
+          markBooted();
+        }
+      },
+      () => {
+      }
+    );
+    return () => {
+      live = false;
+      readyRef.current = null;
+      booting.stop().catch(() => {
+      });
+    };
+  }, [booting]);
+  return [state, booting.dispatch];
 }
 function useRuntime(runtime) {
-  const state = useSyncExternalStore(runtime.subscribe, runtime.getState, runtime.getState);
+  const state = useSyncExternalStore(
+    runtime.subscribe,
+    runtime.getState,
+    runtime.getState
+  );
   return [state, runtime.dispatch];
 }
 

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/react/index.ts"],"names":[],"mappings":";;;AAuDO,SAAS,UAAA,CACd,SACA,IAAA,EACgC;AAMhC,EAAA,MAAM,MAAM,IAAA,CAAK,GAAA;AACjB,EAAA,MAAM,QAAQ,IAAA,CAAK,KAAA;AACnB,EAAA,MAAM,OAAA,GAAU,OAAA,CAAuB,MAAM,GAAA,CAAI,SAAS,EAAE,GAAA,EAAK,KAAA,EAAO,CAAA,EAAG,CAAC,OAAA,EAAS,GAAA,EAAK,KAAK,CAAC,CAAA;AAahG,EAAA,MAAM,gBAAA,GAAmB,OAAA,CAAW,MAAM,OAAA,CAAQ,IAAA,CAAK,IAAA,EAAM,GAAG,CAAA,CAAE,CAAC,CAAA,EAAG,CAAC,OAAA,EAAS,GAAG,CAAC,CAAA;AAMpF,EAAA,MAAM,cAAc,MAAS;AAC3B,IAAA,IAAI;AACF,MAAA,OAAO,QAAQ,QAAA,EAAS;AAAA,IAC1B,CAAA,CAAA,MAAQ;AACN,MAAA,OAAO,gBAAA;AAAA,IACT;AAAA,EACF,CAAA;AAEA,EAAA,MAAM,KAAA,GAAQ,oBAAA,CAAqB,OAAA,CAAQ,SAAA,EAAW,aAAa,WAAW,CAAA;AAC9E,EAAA,SAAA;AAAA,IACE,MAAM,MAAM;AAIV,MAAA,OAAA,CAAQ,IAAA,EAAK,CAAE,KAAA,CAAM,MAAM;AAAA,MAAC,CAAC,CAAA;AAAA,IAC/B,CAAA;AAAA,IACA,CAAC,OAAO;AAAA,GACV;AACA,EAAA,OAAO,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAA;AACjC;AAeO,SAAS,WACd,OAAA,EACgC;AAChC,EAAA,MAAM,QAAQ,oBAAA,CAAqB,OAAA,CAAQ,WAAW,OAAA,CAAQ,QAAA,EAAU,QAAQ,QAAQ,CAAA;AACxF,EAAA,OAAO,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAA;AACjC","file":"index.js","sourcesContent":["/**\n * @demlik/tea/react — React host adapter for `@demlik/tea`.\n *\n * The thinnest possible adapter that makes a tea machine consumable from a\n * React component. Three rules (PRD §\"React adapter\"):\n *\n *   1. The runtime is the source of truth, NOT React state. We subscribe via\n *      `useSyncExternalStore(runtime.subscribe, runtime.getState,\n *      runtime.getState)`. React renders are driven by runtime state changes;\n *      React never owns the state.\n *   2. The runtime is memoized per component-mount, not per render. The deps\n *      array is `[machine, opts.ctx, opts.store]` — IDENTITY, not value. See\n *      `README.md` for the ctx-identity footgun + fix.\n *   3. Concurrent React is the design target. `useSyncExternalStore` is the\n *      React-blessed primitive for tearing-free external state.\n *\n * Client-only in v1 — components that call `useMachine` MUST be `\"use client\"`.\n * Server Components consume data via Relay/RSC as today; tea machines own\n * client-side stateful flows. No RSC streaming, no server-side state\n * hydration. Crossing this boundary is a v2 concern.\n */\n\n\"use client\";\n\nimport { type Cmd, type Machine, type Runtime, run, type Store, type Sub } from \"../index\";\nimport { useEffect, useMemo, useSyncExternalStore } from \"react\";\n\n/**\n * Options passed to `useMachine`. The shape is intentionally minimal — `ctx`\n * is required (every machine has one), `store` is optional (omit it for\n * volatile-state machines).\n *\n * **Identity matters.** The runtime is memoized on `[machine, opts.ctx,\n * opts.store]`. A new `ctx` reference rebuilds the runtime. Always `useMemo`\n * (or otherwise stabilize) the ctx at the call site. See README.\n */\nexport interface UseMachineOpts<S, Ctx> {\n  ctx: Ctx;\n  store?: Store<S>;\n}\n\n/**\n * Build and own a `Runtime<S, M>` for the lifetime of the component mount.\n *\n * - Builds via `useMemo(() => run(machine, opts), [machine, opts.ctx,\n *   opts.store])` — runtime is recreated when ANY of the three identities\n *   change.\n * - Subscribes via `useSyncExternalStore(runtime.subscribe, runtime.getState,\n *   runtime.getState)` — tearing-free under React 18 concurrent rendering.\n * - On unmount (or any dep change), `useEffect` cleanup calls\n *   `runtime.stop()` — drains the queue, runs every active sub cleanup,\n *   flushes state.\n *\n * Returns `[state, dispatch]` shaped like `useReducer`.\n */\nexport function useMachine<S, M extends { type: string }, C extends Cmd, U extends Sub, Ctx>(\n  machine: Machine<S, M, C, U, Ctx>,\n  opts: UseMachineOpts<S, Ctx>,\n): [S, (msg: M) => Promise<void>] {\n  // Deps are literal: machine identity, ctx identity, store identity. NOT\n  // `[opts]` (would rebuild every render — callers pass fresh objects).\n  // We pass explicit fields to `run()` so the closure captures only the\n  // deps in the array — keeps biome's `useExhaustiveDependencies` happy\n  // without lying about what the memo actually depends on.\n  const ctx = opts.ctx;\n  const store = opts.store;\n  const runtime = useMemo<Runtime<S, M>>(() => run(machine, { ctx, store }), [machine, ctx, store]);\n\n  // Preliminary state computed sync from `machine.init(null, ctx)`. This is\n  // the snapshot React sees BEFORE the runtime finishes booting (matters\n  // only when `opts.store` is present — without a store, the substrate\n  // already sets state synchronously inside `run()`). Once the runtime\n  // boots, `runtime.getState()` returns the real (possibly loaded) state.\n  //\n  // We deliberately recompute on each render but cache by `[machine,\n  // opts.ctx]` — `init` is pure by convention, so cost is negligible. The\n  // cached snapshot is also identity-stable across rerenders when the deps\n  // don't change, which `useSyncExternalStore` rewards (no spurious\n  // re-renders).\n  const preliminaryState = useMemo<S>(() => machine.init(null, ctx)[0], [machine, ctx]);\n\n  // `getSnapshot` reads the runtime if it has booted, else falls back to\n  // the preliminary state. The runtime's `getState` throws pre-boot when a\n  // store is configured — we catch that and substitute the preliminary\n  // value.\n  const getSnapshot = (): S => {\n    try {\n      return runtime.getState();\n    } catch {\n      return preliminaryState;\n    }\n  };\n\n  const state = useSyncExternalStore(runtime.subscribe, getSnapshot, getSnapshot);\n  useEffect(\n    () => () => {\n      // Fire-and-forget — `stop()` is async but `useEffect` cleanup is sync.\n      // The runtime swallows in-flight rejections internally, so this never\n      // rejects in practice; we still attach `.catch` for safety.\n      runtime.stop().catch(() => {});\n    },\n    [runtime],\n  );\n  return [state, runtime.dispatch];\n}\n\n/**\n * Lower-level escape hatch: consume an externally-built `Runtime<S, M>`.\n *\n * Use this when the runtime is owned by something OTHER than the component —\n * a parent component, a test harness, a singleton. **The component does NOT\n * call `runtime.stop()` on unmount** — the caller owns the lifecycle.\n *\n * Primary use case in this repo: component tests. Build a runtime with\n * `@demlik/tea/mem` and pre-seed it via `replay`, then mount the component with\n * `useRuntime(testRuntime)` to render in any phase.\n *\n * Returns `[state, dispatch]` — same shape as `useMachine`.\n */\nexport function useRuntime<S, M extends { type: string }>(\n  runtime: Runtime<S, M>,\n): [S, (msg: M) => Promise<void>] {\n  const state = useSyncExternalStore(runtime.subscribe, runtime.getState, runtime.getState);\n  return [state, runtime.dispatch];\n}\n"]}
+{"version":3,"sources":["../../src/react/index.ts"],"names":[],"mappings":";;;;AAqEO,SAAS,UAAA,CAOd,SACA,IAAA,EACgC;AAMhC,EAAA,MAAM,MAAM,IAAA,CAAK,GAAA;AACjB,EAAA,MAAM,QAAQ,IAAA,CAAK,KAAA;AAMnB,EAAA,MAAM,OAAA,GAAU,OAAA;AAAA,IACd,MAAM,GAAA,CAAI,OAAA,EAAS,EAAE,GAAA,EAAK,OAAO,CAAA;AAAA,IACjC,CAAC,OAAA,EAAS,GAAA,EAAK,KAAK;AAAA,GACtB;AAeA,EAAA,MAAM,QAAA,GAAW,OAA6B,IAAI,CAAA;AAClD,EAAA,MAAM,GAAG,UAAU,CAAA,GAAI,WAAW,CAAC,IAAA,KAAiB,IAAA,GAAO,CAAA,EAAG,CAAC,CAAA;AAa/D,EAAA,MAAM,gBAAA,GAAmB,OAAA;AAAA,IACvB,MAAM,OAAA,CAAQ,IAAA,CAAK,IAAA,EAAM,GAAG,EAAE,CAAC,CAAA;AAAA,IAC/B,CAAC,SAAS,GAAG;AAAA,GACf;AAMA,EAAA,MAAM,WAAA,GAAc,MAClB,QAAA,CAAS,OAAA,KAAY,OAAO,QAAA,CAAS,OAAA,CAAQ,UAAS,GAAI,gBAAA;AAE5D,EAAA,MAAM,KAAA,GAAQ,oBAAA;AAAA,IACZ,OAAA,CAAQ,SAAA;AAAA,IACR,WAAA;AAAA,IACA;AAAA,GACF;AAEA,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,IAAA,GAAO,IAAA;AAMX,IAAA,OAAA,CAAQ,KAAA,CAAM,IAAA;AAAA,MACZ,CAAC,CAAA,KAAM;AACL,QAAA,IAAI,IAAA,EAAM;AACR,UAAA,QAAA,CAAS,OAAA,GAAU,CAAA;AACnB,UAAA,UAAA,EAAW;AAAA,QACb;AAAA,MACF,CAAA;AAAA,MACA,MAAM;AAAA,MAAC;AAAA,KACT;AACA,IAAA,OAAO,MAAM;AACX,MAAA,IAAA,GAAO,KAAA;AACP,MAAA,QAAA,CAAS,OAAA,GAAU,IAAA;AAInB,MAAA,OAAA,CAAQ,IAAA,EAAK,CAAE,KAAA,CAAM,MAAM;AAAA,MAAC,CAAC,CAAA;AAAA,IAC/B,CAAA;AAAA,EACF,CAAA,EAAG,CAAC,OAAO,CAAC,CAAA;AAEZ,EAAA,OAAO,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAA;AACjC;AAeO,SAAS,WACd,OAAA,EACgC;AAChC,EAAA,MAAM,KAAA,GAAQ,oBAAA;AAAA,IACZ,OAAA,CAAQ,SAAA;AAAA,IACR,OAAA,CAAQ,QAAA;AAAA,IACR,OAAA,CAAQ;AAAA,GACV;AACA,EAAA,OAAO,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAA;AACjC","file":"index.js","sourcesContent":["/**\n * @demlik/tea/react — React host adapter for `@demlik/tea`.\n *\n * The thinnest possible adapter that makes a tea machine consumable from a\n * React component. Three rules (PRD §\"React adapter\"):\n *\n *   1. The runtime is the source of truth, NOT React state. We subscribe via\n *      `useSyncExternalStore(runtime.subscribe, runtime.getState,\n *      runtime.getState)`. React renders are driven by runtime state changes;\n *      React never owns the state.\n *   2. The runtime is memoized per component-mount, not per render. The deps\n *      array is `[machine, opts.ctx, opts.store]` — IDENTITY, not value. See\n *      `README.md` for the ctx-identity footgun + fix.\n *   3. Concurrent React is the design target. `useSyncExternalStore` is the\n *      React-blessed primitive for tearing-free external state.\n *\n * Client-only in v1 — components that call `useMachine` MUST be `\"use client\"`.\n * Server Components consume data via Relay/RSC as today; tea machines own\n * client-side stateful flows. No RSC streaming, no server-side state\n * hydration. Crossing this boundary is a v2 concern.\n */\n\n\"use client\";\n\nimport {\n  useEffect,\n  useMemo,\n  useReducer,\n  useRef,\n  useSyncExternalStore,\n} from \"react\";\nimport {\n  type BootingRuntime,\n  type Cmd,\n  type Machine,\n  type Runtime,\n  run,\n  type Store,\n  type Sub,\n} from \"../index\";\n\n/**\n * Options passed to `useMachine`. The shape is intentionally minimal — `ctx`\n * is required (every machine has one), `store` is optional (omit it for\n * volatile-state machines).\n *\n * **Identity matters.** The runtime is memoized on `[machine, opts.ctx,\n * opts.store]`. A new `ctx` reference rebuilds the runtime. Always `useMemo`\n * (or otherwise stabilize) the ctx at the call site. See README.\n */\nexport interface UseMachineOpts<S, Ctx> {\n  ctx: Ctx;\n  store?: Store<S>;\n}\n\n/**\n * Build and own a `Runtime<S, M>` for the lifetime of the component mount.\n *\n * - Builds via `useMemo(() => run(machine, opts), [machine, opts.ctx,\n *   opts.store])` — runtime is recreated when ANY of the three identities\n *   change.\n * - Subscribes via `useSyncExternalStore(runtime.subscribe, runtime.getState,\n *   runtime.getState)` — tearing-free under React 18 concurrent rendering.\n * - On unmount (or any dep change), `useEffect` cleanup calls\n *   `runtime.stop()` — drains the queue, runs every active sub cleanup,\n *   flushes state.\n *\n * Returns `[state, dispatch]` shaped like `useReducer`.\n */\nexport function useMachine<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  opts: UseMachineOpts<S, Ctx>,\n): [S, (msg: M) => Promise<void>] {\n  // Deps are literal: machine identity, ctx identity, store identity. NOT\n  // `[opts]` (would rebuild every render — callers pass fresh objects).\n  // We pass explicit fields to `run()` so the closure captures only the\n  // deps in the array — keeps biome's `useExhaustiveDependencies` happy\n  // without lying about what the memo actually depends on.\n  const ctx = opts.ctx;\n  const store = opts.store;\n  // `run()` returns a `BootingRuntime<S, M>` SYNCHRONOUSLY (issue #45) — exactly\n  // what `useMemo` needs. We never `await` here: awaiting would force an async\n  // memo, a null first-commit state, and a resolved-flag dance. Instead we hold\n  // the booting handle and capture the booted `Runtime` (the only thing with a\n  // total `getState`) once `ready` resolves.\n  const booting = useMemo<BootingRuntime<S, M>>(\n    () => run(machine, { ctx, store }),\n    [machine, ctx, store],\n  );\n\n  // Captures the booted `Runtime` once `ready` resolves. Until then it is\n  // `null` and `getSnapshot` serves `preliminaryState`. Reset whenever the\n  // booting handle identity changes (a new machine/ctx/store mount).\n  //\n  // The boot race the paired `bootedTick` bump exists for: the substrate's\n  // boot fanout fires BEFORE `ready` resolves (fireListeners runs inside the\n  // boot step; `ready` chains off the boot promise), so at notification time\n  // this ref is still null and `getSnapshot` returns the same\n  // `preliminaryState` reference — React sees an unchanged snapshot and\n  // skips the re-render. Nothing re-notifies after the ref is set, so a\n  // store-backed mount would stay stuck on the preliminary state until the\n  // next unrelated transition. Bumping a reducer when we capture the booted\n  // runtime forces the render that swaps preliminary → real state.\n  const readyRef = useRef<Runtime<S, M> | null>(null);\n  const [, markBooted] = useReducer((tick: number) => tick + 1, 0);\n\n  // Preliminary state computed sync from `machine.init(null, ctx)`. This is\n  // the snapshot React sees BEFORE the runtime finishes booting (matters\n  // only when `opts.store` is present — without a store, the substrate\n  // already sets state synchronously inside `run()`, so the boot fanout that\n  // captures `readyRef` lands on the same microtask as the first commit).\n  //\n  // We deliberately recompute on each render but cache by `[machine,\n  // opts.ctx]` — `init` is pure by convention, so cost is negligible. The\n  // cached snapshot is also identity-stable across rerenders when the deps\n  // don't change, which `useSyncExternalStore` rewards (no spurious\n  // re-renders).\n  const preliminaryState = useMemo<S>(\n    () => machine.init(null, ctx)[0],\n    [machine, ctx],\n  );\n\n  // `getSnapshot` reads the booted runtime if `ready` has resolved (the ref is\n  // populated), else falls back to the preliminary state. No try/catch dance\n  // anymore — pre-boot there is simply no booted `Runtime` to read from, so\n  // the fallback is structural, not exception-driven.\n  const getSnapshot = (): S =>\n    readyRef.current !== null ? readyRef.current.getState() : preliminaryState;\n\n  const state = useSyncExternalStore(\n    booting.subscribe,\n    getSnapshot,\n    getSnapshot,\n  );\n\n  useEffect(() => {\n    let live = true;\n    // Capture the booted runtime when `ready` resolves, then force the\n    // render that swaps preliminary → real state (see the boot-race note on\n    // `readyRef` — the boot fanout fires too early to do it for us). Boot\n    // rejections are swallowed: a failed boot surfaces on every `dispatch`,\n    // which is where the consumer handles it.\n    booting.ready.then(\n      (r) => {\n        if (live) {\n          readyRef.current = r;\n          markBooted();\n        }\n      },\n      () => {},\n    );\n    return () => {\n      live = false;\n      readyRef.current = null;\n      // Fire-and-forget — `stop()` is async but `useEffect` cleanup is sync.\n      // The runtime swallows in-flight rejections internally, so this never\n      // rejects in practice; we still attach `.catch` for safety.\n      booting.stop().catch(() => {});\n    };\n  }, [booting]);\n\n  return [state, booting.dispatch];\n}\n\n/**\n * Lower-level escape hatch: consume an externally-built `Runtime<S, M>`.\n *\n * Use this when the runtime is owned by something OTHER than the component —\n * a parent component, a test harness, a singleton. **The component does NOT\n * call `runtime.stop()` on unmount** — the caller owns the lifecycle.\n *\n * Primary use case in this repo: component tests. Build a runtime with\n * `@demlik/tea/mem` and pre-seed it via `replay`, then mount the component with\n * `useRuntime(testRuntime)` to render in any phase.\n *\n * Returns `[state, dispatch]` — same shape as `useMachine`.\n */\nexport function useRuntime<S, M extends { type: string }>(\n  runtime: Runtime<S, M>,\n): [S, (msg: M) => Promise<void>] {\n  const state = useSyncExternalStore(\n    runtime.subscribe,\n    runtime.getState,\n    runtime.getState,\n  );\n  return [state, runtime.dispatch];\n}\n"]}