@demlik/tea 0.12.0 → 0.14.0

package/dist/chunk-SUST46KO.js

@@ -1,53 +0,0 @@
-import { typeOf, indexPath, unionKeys, keyPath } from './chunk-EWJP3YYP.js';
-import { replay } from './chunk-5EHLEUTL.js';
-
-// src/trace-replay/index.ts
-function replayTrace(machine, trace, ctx) {
-  const result = replay(machine, {
-    msgs: trace.msgs,
-    ctx,
-    loaded: trace.loaded
-  });
-  const actual = result.state;
-  const expected = trace.finalState;
-  const divergence = firstDivergence(expected, actual, "state");
-  if (divergence === null) {
-    return { matches: true, expected, actual };
-  }
-  return { matches: false, expected, actual, divergence };
-}
-function deepEqual(a, b) {
-  return firstDivergence(a, b, "state") === null;
-}
-function firstDivergence(expected, actual, path) {
-  if (Object.is(expected, actual)) return null;
-  const te = typeOf(expected);
-  const ta = typeOf(actual);
-  if (te !== ta) return { path, expected, actual };
-  if (te === "array") {
-    const ae = expected;
-    const aa = actual;
-    if (ae.length !== aa.length) {
-      return { path, expected, actual };
-    }
-    for (let i = 0; i < ae.length; i++) {
-      const d = firstDivergence(ae[i], aa[i], indexPath(path, i));
-      if (d !== null) return d;
-    }
-    return null;
-  }
-  if (te === "object") {
-    const oe = expected;
-    const oa = actual;
-    for (const key of unionKeys(oe, oa)) {
-      const d = firstDivergence(oe[key], oa[key], keyPath(path, key));
-      if (d !== null) return d;
-    }
-    return null;
-  }
-  return { path, expected, actual };
-}
-
-export { deepEqual, replayTrace };
-//# sourceMappingURL=chunk-SUST46KO.js.map
-//# sourceMappingURL=chunk-SUST46KO.js.map

package/dist/chunk-SUST46KO.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/trace-replay/index.ts"],"names":[],"mappings":";;;;AAqEO,SAAS,WAAA,CAOd,OAAA,EACA,KAAA,EACA,GAAA,EACiB;AACjB,EAAA,MAAM,MAAA,GAAS,OAAO,OAAA,EAAS;AAAA,IAC7B,MAAM,KAAA,CAAM,IAAA;AAAA,IACZ,GAAA;AAAA,IACA,QAAQ,KAAA,CAAM;AAAA,GACf,CAAA;AACD,EAAA,MAAM,SAAS,MAAA,CAAO,KAAA;AACtB,EAAA,MAAM,WAAW,KAAA,CAAM,UAAA;AAEvB,EAAA,MAAM,UAAA,GAAa,eAAA,CAAgB,QAAA,EAAU,MAAA,EAAQ,OAAO,CAAA;AAC5D,EAAA,IAAI,eAAe,IAAA,EAAM;AACvB,IAAA,OAAO,EAAE,OAAA,EAAS,IAAA,EAAM,QAAA,EAAU,MAAA,EAAO;AAAA,EAC3C;AACA,EAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,QAAA,EAAU,QAAQ,UAAA,EAAW;AACxD;AAcO,SAAS,SAAA,CAAU,GAAY,CAAA,EAAqB;AACzD,EAAA,OAAO,eAAA,CAAgB,CAAA,EAAG,CAAA,EAAG,OAAO,CAAA,KAAM,IAAA;AAC5C;AA2BA,SAAS,eAAA,CACP,QAAA,EACA,MAAA,EACA,IAAA,EACY;AAIZ,EAAA,IAAI,MAAA,CAAO,EAAA,CAAG,QAAA,EAAU,MAAM,GAAG,OAAO,IAAA;AAExC,EAAA,MAAM,EAAA,GAAK,OAAO,QAAQ,CAAA;AAC1B,EAAA,MAAM,EAAA,GAAK,OAAO,MAAM,CAAA;AAGxB,EAAA,IAAI,OAAO,EAAA,EAAI,OAAO,EAAE,IAAA,EAAM,UAAU,MAAA,EAAO;AAE/C,EAAA,IAAI,OAAO,OAAA,EAAS;AAClB,IAAA,MAAM,EAAA,GAAK,QAAA;AACX,IAAA,MAAM,EAAA,GAAK,MAAA;AACX,IAAA,IAAI,EAAA,CAAG,MAAA,KAAW,EAAA,CAAG,MAAA,EAAQ;AAG3B,MAAA,OAAO,EAAE,IAAA,EAAM,QAAA,EAAU,MAAA,EAAO;AAAA,IAClC;AACA,IAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,EAAA,CAAG,QAAQ,CAAA,EAAA,EAAK;AAClC,MAAA,MAAM,CAAA,GAAI,eAAA,CAAgB,EAAA,CAAG,CAAC,CAAA,EAAG,EAAA,CAAG,CAAC,CAAA,EAAG,SAAA,CAAU,IAAA,EAAM,CAAC,CAAC,CAAA;AAC1D,MAAA,IAAI,CAAA,KAAM,MAAM,OAAO,CAAA;AAAA,IACzB;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,IAAI,OAAO,QAAA,EAAU;AACnB,IAAA,MAAM,EAAA,GAAK,QAAA;AACX,IAAA,MAAM,EAAA,GAAK,MAAA;AAIX,IAAA,KAAA,MAAW,GAAA,IAAO,SAAA,CAAU,EAAA,EAAI,EAAE,CAAA,EAAG;AACnC,MAAA,MAAM,CAAA,GAAI,eAAA,CAAgB,EAAA,CAAG,GAAG,CAAA,EAAG,EAAA,CAAG,GAAG,CAAA,EAAG,OAAA,CAAQ,IAAA,EAAM,GAAG,CAAC,CAAA;AAC9D,MAAA,IAAI,CAAA,KAAM,MAAM,OAAO,CAAA;AAAA,IACzB;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AAIA,EAAA,OAAO,EAAE,IAAA,EAAM,QAAA,EAAU,MAAA,EAAO;AAClC","file":"chunk-SUST46KO.js","sourcesContent":["// ---------------------------------------------------------------------------\n// trace-replay — replay a recorded Trace against a machine and diff the state.\n//\n// This is the back half of the record/replay feature. `../recorder` captures\n// a run (`loaded` + `msgs` + `finalState`); this module feeds that input\n// through the core `replay(machine, { msgs, ctx, loaded })` fold and asks:\n//\n//     does the current reducer still produce the SAME final state for this\n//     recorded input?\n//\n// Equal ⇒ the reducer is behavior-compatible with the recording. Diverged ⇒\n// the reducer changed for that input, and the divergence path\n// (`state.queue[2].status`) points at exactly the cell that drifted. This is\n// the regression / production-repro tool: record a prod incident, replay it\n// against the fixed reducer locally, confirm the fix changes the state at the\n// path you expected — or catch an unintended drift before it ships.\n//\n// Standalone by design. It imports ONLY the `Trace` type from `../recorder`\n// and the `replay` engine from `../index`. The deep-equal + first-divergence\n// path finder is self-contained (no external diff lib) — a richer pretty-diff\n// lands in `../devtools` later; trace-replay stays dependency-free so it can\n// run anywhere a machine runs (CI, a Worker, a Node script).\n// ---------------------------------------------------------------------------\n\nimport { type Cmd, type Machine, replay, type Sub } from \"../index\";\nimport type { Trace } from \"../recorder\";\nimport { indexPath, keyPath, typeOf, unionKeys } from \"./state-walk\";\n\n/**\n * The outcome of {@link replayTrace}.\n *\n * @typeParam S - the machine's State type.\n */\nexport interface ReplayResult<S> {\n  /** `true` iff the recomputed final state deep-equals the trace's `finalState`. */\n  matches: boolean;\n  /** The trace's recorded `finalState` — what the run originally produced. */\n  expected: S;\n  /** The state the current reducer produced for the same input. */\n  actual: S;\n  /**\n   * Present iff `matches` is `false`. The FIRST point of divergence found by\n   * a deterministic pre-order walk:\n   *   - `path`     — a dotted/indexed access path from the state root, e.g.\n   *                  `state.queue[2].status` or `state` for a root-level\n   *                  scalar mismatch.\n   *   - `expected` — the recorded value at that path.\n   *   - `actual`   — the recomputed value at that path.\n   */\n  divergence?: { path: string; expected: unknown; actual: unknown };\n}\n\n/**\n * Replay a recorded {@link Trace} against `machine` and diff the recomputed\n * final state against the recorded one.\n *\n * Runs the core pure fold `replay(machine, { msgs: trace.msgs, ctx,\n * loaded: trace.loaded })` — init + update only, never `interpret`, never a\n * `Store`, never a live subscription (see `replay` in ../index). The `ctx` is\n * supplied fresh by the caller: the trace is the INPUT (loaded + msgs); ctx is\n * the ENVIRONMENT the reducer runs against now.\n *\n * @param machine - the machine to replay against. Mutating its reducer (the\n *                  whole point of a regression check) is what makes a recorded\n *                  trace diverge.\n * @param trace   - a Trace from `../recorder` (live `dump()` or a re-hydrated\n *                  `parseJSONL(...)`).\n * @param ctx     - the runtime ctx, supplied fresh at replay time.\n */\nexport function replayTrace<\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  trace: Trace<S, M>,\n  ctx: Ctx,\n): ReplayResult<S> {\n  const result = replay(machine, {\n    msgs: trace.msgs,\n    ctx,\n    loaded: trace.loaded,\n  });\n  const actual = result.state;\n  const expected = trace.finalState;\n\n  const divergence = firstDivergence(expected, actual, \"state\");\n  if (divergence === null) {\n    return { matches: true, expected, actual };\n  }\n  return { matches: false, expected, actual, divergence };\n}\n\n/**\n * Order-insensitive structural deep-equality — the comparator the\n * record/replay lane owns, exposed so consumers (e.g. `@demlik/tea/parity`'s\n * `parityEqual`) reuse it rather than adding a fourth deep-compare. It is one\n * of three structural walkers in the package, divergent on purpose:\n * this `deepEqual` returns a boolean verdict (order-insensitive, for\n * replay/parity equality), `devtools`'s `diffState` returns a change list (for\n * a human-readable diff view), and `testing`'s `__deepEqual` is the assertion\n * helpers' internal compare — same shape, three jobs, not one to collapse.\n * `true` iff `a` and `b` are structurally equal under {@link firstDivergence}'s\n * walk (object keys compared order-insensitively, arrays index-by-index).\n */\nexport function deepEqual(a: unknown, b: unknown): boolean {\n  return firstDivergence(a, b, \"state\") === null;\n}\n\n// === deep-equal + first-divergence path finder ===\n//\n// One walk does both jobs: it returns the FIRST point where `expected` and\n// `actual` differ (as a path + the two values), or `null` when they are\n// deeply equal. \"First\" is defined by a deterministic pre-order traversal:\n// the node itself, then its children in a stable key order (array index\n// order; object keys sorted so the result does not depend on insertion\n// order — two states with the same data but different key order are equal,\n// and the reported path for a real mismatch is reproducible run-to-run).\n//\n// The path grammar (`typeOf`, `indexPath`/`keyPath` segments, `unionKeys`\n// order) is shared with devtools' `diffState` via `./state-walk`, so the two\n// walkers print the SAME path for the same cell by construction. Only the leaf\n// policy differs, on purpose: first-hit here, collect-all there.\n//\n// Scope: TEA state is plain JSON-shaped data (the substrate's __DEV__ guards\n// reject closures in Cmds, and states are conventionally serializable). So\n// the walk handles: primitives, null/undefined, arrays, and plain objects.\n// It treats other object kinds (Date, Map, Set, class instances) by reference\n// identity + a structural fallback via Object.entries — sufficient for the\n// JSON-shaped states this tool targets; a richer differ lives in ../devtools.\n\n/** A divergence record, or `null` when the two values are deeply equal. */\ntype Divergence = { path: string; expected: unknown; actual: unknown } | null;\n\nfunction firstDivergence(\n  expected: unknown,\n  actual: unknown,\n  path: string,\n): Divergence {\n  // Identity / primitive fast path. Handles same-reference, and equal\n  // primitives. `Object.is` so NaN === NaN and +0 ≠ -0 (matches structural\n  // equality intent better than ===).\n  if (Object.is(expected, actual)) return null;\n\n  const te = typeOf(expected);\n  const ta = typeOf(actual);\n  // Different kinds at this node (e.g. object vs array, number vs string,\n  // present vs null) — this node IS the divergence.\n  if (te !== ta) return { path, expected, actual };\n\n  if (te === \"array\") {\n    const ae = expected as unknown[];\n    const aa = actual as unknown[];\n    if (ae.length !== aa.length) {\n      // Length mismatch reported at the array node itself — the shape differs,\n      // which is more informative than an arbitrary element index.\n      return { path, expected, actual };\n    }\n    for (let i = 0; i < ae.length; i++) {\n      const d = firstDivergence(ae[i], aa[i], indexPath(path, i));\n      if (d !== null) return d;\n    }\n    return null;\n  }\n\n  if (te === \"object\") {\n    const oe = expected as Record<string, unknown>;\n    const oa = actual as Record<string, unknown>;\n    // Sorted union of keys for deterministic traversal. A key present in one\n    // but absent in the other diverges at that child path (its value is\n    // `undefined` on the missing side).\n    for (const key of unionKeys(oe, oa)) {\n      const d = firstDivergence(oe[key], oa[key], keyPath(path, key));\n      if (d !== null) return d;\n    }\n    return null;\n  }\n\n  // Primitives (string/number/boolean/bigint/symbol/function) that failed the\n  // Object.is fast path, or null/undefined that differ — this node diverges.\n  return { path, expected, actual };\n}\n"]}

package/dist/chunk-TP5UPGLY.js

@@ -1,61 +0,0 @@
-import { MsgType } from './chunk-JELSZN25.js';
-import { tryInterpret } from './chunk-5EHLEUTL.js';
-
-// src/token-refresh/index.ts
-function initTokenRefresh() {
-  return { token: null, stale: false };
-}
-function refreshTokenCmd() {
-  return { type: "refresh_token" };
-}
-function tokenRefreshedMsg(token) {
-  return { type: MsgType.TokenRefreshed, token };
-}
-function tokenRefreshFailedMsg(error) {
-  return { type: MsgType.TokenRefreshFailed, error };
-}
-function createTokenRefresh(config = {}) {
-  const skewMs = config.skewMs !== void 0 && config.skewMs > 0 ? config.skewMs : 0;
-  function needsRefresh(state, at) {
-    if (state.token === null) return true;
-    if (state.stale) return true;
-    if (!Number.isFinite(state.token.expiresAt)) return true;
-    return at >= state.token.expiresAt - skewMs;
-  }
-  function on401(state) {
-    if (state.stale) return state;
-    return { ...state, stale: true };
-  }
-  function refreshed(state, token) {
-    const normalized = Object.is(token.expiresAt, -0) ? { ...token, expiresAt: 0 } : token;
-    return { ...state, token: normalized, stale: false };
-  }
-  function ensureFresh(state, at) {
-    if (needsRefresh(state, at)) {
-      return [state, [refreshTokenCmd()]];
-    }
-    return [state, []];
-  }
-  function handlers(ports) {
-    return {
-      refresh_token: tryInterpret(
-        () => ports.refresh(),
-        (token) => tokenRefreshedMsg(token),
-        (error) => tokenRefreshFailedMsg(error)
-      )
-    };
-  }
-  return {
-    /** The slice initializer — spread into the consumer's `init`. */
-    init: initTokenRefresh,
-    needsRefresh,
-    on401,
-    refreshed,
-    ensureFresh,
-    handlers
-  };
-}
-
-export { createTokenRefresh, initTokenRefresh, refreshTokenCmd, tokenRefreshFailedMsg, tokenRefreshedMsg };
-//# sourceMappingURL=chunk-TP5UPGLY.js.map
-//# sourceMappingURL=chunk-TP5UPGLY.js.map

package/dist/chunk-TP5UPGLY.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/token-refresh/index.ts"],"names":[],"mappings":";;;;AAkJO,SAAS,gBAAA,GAA+B;AAC7C,EAAA,OAAO,EAAE,KAAA,EAAO,IAAA,EAAM,KAAA,EAAO,KAAA,EAAM;AACrC;AAYO,SAAS,eAAA,GAAmC;AACjD,EAAA,OAAO,EAAE,MAAM,eAAA,EAAgB;AACjC;AAaO,SAAS,kBAAkB,KAAA,EAAiC;AACjE,EAAA,OAAO,EAAE,IAAA,EAAM,OAAA,CAAQ,cAAA,EAAgB,KAAA,EAAM;AAC/C;AAgBO,SAAS,sBAAsB,KAAA,EAAuC;AAC3E,EAAA,OAAO,EAAE,IAAA,EAAM,OAAA,CAAQ,kBAAA,EAAoB,KAAA,EAAM;AACnD;AA0BO,SAAS,kBAAA,CAAmB,MAAA,GAA6B,EAAC,EAAG;AAIlE,EAAA,MAAM,MAAA,GACJ,OAAO,MAAA,KAAW,MAAA,IAAa,OAAO,MAAA,GAAS,CAAA,GAAI,OAAO,MAAA,GAAS,CAAA;AAsBrE,EAAA,SAAS,YAAA,CAAa,OAAmB,EAAA,EAAqB;AAC5D,IAAA,IAAI,KAAA,CAAM,KAAA,KAAU,IAAA,EAAM,OAAO,IAAA;AACjC,IAAA,IAAI,KAAA,CAAM,OAAO,OAAO,IAAA;AAKxB,IAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,MAAM,KAAA,CAAM,SAAS,GAAG,OAAO,IAAA;AACpD,IAAA,OAAO,EAAA,IAAM,KAAA,CAAM,KAAA,CAAM,SAAA,GAAY,MAAA;AAAA,EACvC;AAcA,EAAA,SAAS,MAAM,KAAA,EAA+B;AAC5C,IAAA,IAAI,KAAA,CAAM,OAAO,OAAO,KAAA;AACxB,IAAA,OAAO,EAAE,GAAG,KAAA,EAAO,KAAA,EAAO,IAAA,EAAK;AAAA,EACjC;AAmBA,EAAA,SAAS,SAAA,CAAU,OAAmB,KAAA,EAA0B;AAC9D,IAAA,MAAM,UAAA,GAAoB,MAAA,CAAO,EAAA,CAAG,KAAA,CAAM,SAAA,EAAW,EAAE,CAAA,GACnD,EAAE,GAAG,KAAA,EAAO,SAAA,EAAW,CAAA,EAAE,GACzB,KAAA;AACJ,IAAA,OAAO,EAAE,GAAG,KAAA,EAAO,KAAA,EAAO,UAAA,EAAY,OAAO,KAAA,EAAM;AAAA,EACrD;AAgBA,EAAA,SAAS,WAAA,CACP,OACA,EAAA,EACuC;AACvC,IAAA,IAAI,YAAA,CAAa,KAAA,EAAO,EAAE,CAAA,EAAG;AAC3B,MAAA,OAAO,CAAC,KAAA,EAAO,CAAC,eAAA,EAAiB,CAAC,CAAA;AAAA,IACpC;AACA,IAAA,OAAO,CAAC,KAAA,EAAO,EAAE,CAAA;AAAA,EACnB;AAgBA,EAAA,SAAS,SACP,KAAA,EACsD;AACtD,IAAA,OAAO;AAAA,MACL,aAAA,EAAe,YAAA;AAAA,QAMb,MAAM,MAAM,OAAA,EAAQ;AAAA,QACpB,CAAC,KAAA,KAAU,iBAAA,CAAkB,KAAK,CAAA;AAAA,QAClC,CAAC,KAAA,KAAU,qBAAA,CAAsB,KAAK;AAAA;AACxC,KACF;AAAA,EACF;AAEA,EAAA,OAAO;AAAA;AAAA,IAEL,IAAA,EAAM,gBAAA;AAAA,IACN,YAAA;AAAA,IACA,KAAA;AAAA,IACA,SAAA;AAAA,IACA,WAAA;AAAA,IACA;AAAA,GACF;AACF","file":"chunk-TP5UPGLY.js","sourcesContent":["/**\n * @demlik/tea/token-refresh — a credential's lifecycle as pure state + verbs,\n * with the actual token fetch deferred to a single injected port.\n *\n * This is the L1 brick `authed-call` (#10 in the composition specs) stacks on:\n * a token slice `{ token, stale }` plus pure transitions that decide *when* a\n * credential must be re-minted, and one `handlers(ports)` splice that performs\n * the re-mint. It follows the uniform knob contract every composition wears —\n * `createTokenRefresh(config) → { init, <verbs>, handlers }` — so a consumer\n * spreads ~3 hooks into their machine instead of hand-wiring the refresh dance.\n *\n * It is a LEAF module in the same mold as `@demlik/tea/retry-backoff`: it\n * depends only on the core (`../index`), never on a sibling brick. The two\n * non-negotiables of every knob hold here by construction:\n *\n *   - **Durable** — the token slice is plain JSON-serializable data, so it\n *     survives a Durable Object eviction / page reload. A rehydrated machine\n *     resumes knowing exactly which token it holds and whether it is stale.\n *   - **Replayable** — every transition is a pure verb returning\n *     `readonly [State, Cmd[]]`. No verb reads the wall clock or performs I/O,\n *     so `replay` reconstructs the slice exactly. Time enters ONLY as an `at`\n *     parameter the caller stamps; the network fetch enters ONLY at the\n *     `handlers` boundary. This keeps the substrate's purity invariants intact\n *     (invariant 2: pure transitions; invariant 4: I/O is an effect, not a\n *     reducer body).\n *\n * ## The staleness model — two independent reasons to refresh\n *\n * A token becomes unusable for two unrelated reasons, and the slice tracks both\n * without conflating them:\n *\n *   1. **Expiry** — the token has a known `expiresAt` (epoch ms). It is \"near\n *      expiry\" once `at >= expiresAt - skewMs`. The `skewMs` skew refreshes\n *      *ahead* of the hard deadline so an in-flight call never races a token\n *      that expires mid-request. This is the proactive, time-driven reason and\n *      is computed purely from the injected `at` — no clock in the verb.\n *\n *   2. **Server rejection (401)** — the server rejected a request the client\n *      believed was still valid (clock skew, a server-side revocation, an early\n *      rotation). `on401` flips a `stale` flag regardless of `expiresAt`. This\n *      is the reactive reason: the client's belief about validity was wrong, so\n *      the next `needsRefresh` returns true even though the clock says the\n *      token is fine.\n *\n * `needsRefresh` is the union of the two (plus \"no token at all\"). One source\n * of truth for \"should I fetch a fresh credential before the next call?\", read\n * by the consumer's reducer at the call boundary.\n *\n * Typical wiring (inside a consumer machine):\n *\n *   const tr = createTokenRefresh({ skewMs: 30_000 });\n *\n *   // in init:\n *   init: (loaded) => [loaded ?? { auth: tr.init() }, Cmd.none],\n *\n *   // in a reducer cell that is about to make an authed call:\n *   before_call: (s, msg) => {\n *     const [auth, cmds] = tr.ensureFresh(s.auth, msg.at);\n *     return [{ ...s, auth }, cmds]; // emits a refresh Cmd iff a refresh is due\n *   },\n *\n *   // on a 401 from a guarded call:\n *   got_401: (s) => [{ ...s, auth: tr.on401(s.auth) }, []],\n *\n *   // when the refresh port resolves:\n *   token_refreshed: (s, msg) => [{ ...s, auth: tr.refreshed(s.auth, msg.token) }, []],\n *\n *   // splice the I/O:\n *   interpret: { ...tr.handlers({ refresh: () => mySdk.mintToken() }) },\n *\n * NOT a substrate primitive: from `../index` it reuses only the `Cmd` /\n * `Interpret` types and the `tryInterpret` Railway helper (a runtime function,\n * not a type) that every effectful brick uses — and no sibling brick. It is a\n * leaf utility consumers reach via the `@demlik/tea/token-refresh` subpath.\n */\n\nimport { type Cmd, type Interpret, tryInterpret } from \"../index\";\nimport { MsgType } from \"../protocol\";\n\n/**\n * A minted credential: the opaque `value` to send on the wire, and the absolute\n * `expiresAt` (epoch milliseconds — the `Date.now()` scale) the issuer stamped\n * it with. Both fields are plain data so a `Token` is trivially serializable\n * into a consumer's `Store<S>`.\n *\n * `value` is `string` because that is the universal shape of a bearer token /\n * API key / session cookie on the wire. A consumer whose refresh port yields a\n * richer object can JSON-encode it into `value`, or keep this module's slice as\n * the \"is it fresh?\" gate and hold the richer object elsewhere in their Model.\n */\nexport interface Token {\n  /** The opaque credential to present on each request (bearer token, API key). */\n  readonly value: string;\n  /** Absolute expiry instant, epoch milliseconds. The `Date.now()` scale. */\n  readonly expiresAt: number;\n}\n\n/**\n * Pure configuration — the knob's only field. Carries no mutable state;\n * `TokenState` does. One config is shared across all the refreshes of one\n * logical credential (often a module-scope const).\n */\nexport interface TokenRefreshConfig {\n  /**\n   * Refresh-ahead skew, in milliseconds. A token is treated as needing a\n   * refresh once `at >= expiresAt - skewMs`, i.e. `skewMs` BEFORE its hard\n   * expiry. This buys headroom so a call that starts just under the wire never\n   * races a token that lapses mid-flight, and absorbs small client/server clock\n   * disagreement. `0` means \"refresh exactly at expiry\"; a negative value is\n   * clamped to `0` (a skew that pushes the trigger past expiry is meaningless).\n   *\n   * @default 0\n   */\n  readonly skewMs?: number;\n}\n\n/**\n * The token slice this knob owns — the Model field a consumer spreads in via\n * `init()`. A two-field record rather than a phase union because the two\n * dimensions are orthogonal: a token can be present-and-fresh, present-but-stale\n * (a 401 came back), absent, or absent-and-stale (cleared after a failed\n * refresh). Every combination is meaningful, so neither field implies the\n * other's value and a discriminated union would only manufacture impossible\n * arms.\n *\n *   - `token` — the currently held credential, or `null` when none has been\n *     minted yet (fresh boot) or the last refresh failed.\n *   - `stale` — set by `on401` when the server rejected a request the client\n *     believed valid. Forces the next `needsRefresh` to true regardless of\n *     `expiresAt`; cleared by `refreshed` once a new credential lands.\n *\n * Both fields `readonly` so the whole slice threads safely through a pure\n * reducer and serializes into a `Store<S>`.\n */\nexport interface TokenState {\n  /** The held credential, or `null` if none is available (boot / failed refresh). */\n  readonly token: Token | null;\n  /** Whether a 401 has marked the held token unusable ahead of its `expiresAt`. */\n  readonly stale: boolean;\n}\n\n/**\n * The starting slice: no token held, not stale. The first `needsRefresh` after\n * this returns `true` (no token), so a consumer's first guarded call mints a\n * credential before going out.\n */\nexport function initTokenRefresh(): TokenState {\n  return { token: null, stale: false };\n}\n\n/**\n * The Cmd this knob emits to ask the runtime to mint a fresh token. Plain data\n * (no closure — invariant 1) carrying nothing: the refresh port takes no input,\n * and the slice the result installs is read off the follow-up Msg, not this\n * Cmd. The consumer unions this into their machine's Cmd type and lets\n * `handlers` interpret it.\n */\nexport interface RefreshTokenCmd extends Cmd<\"refresh_token\"> {}\n\n/** Construct a `refresh_token` Cmd. */\nexport function refreshTokenCmd(): RefreshTokenCmd {\n  return { type: \"refresh_token\" };\n}\n\n/**\n * The Msg the refresh port dispatches on success — carries the freshly minted\n * `Token`. The consumer unions this into their Msg type and handles it by\n * folding `refreshed(state, msg.token)` into the slice.\n */\nexport interface TokenRefreshedMsg {\n  readonly type: typeof MsgType.TokenRefreshed;\n  readonly token: Token;\n}\n\n/** Construct a `token_refreshed` Msg carrying the new token. */\nexport function tokenRefreshedMsg(token: Token): TokenRefreshedMsg {\n  return { type: MsgType.TokenRefreshed, token };\n}\n\n/**\n * The Msg the refresh port dispatches on failure — carries the rejection so the\n * consumer's reducer can decide whether to back off, surface an error, or give\n * up (errors are data: it is dispatched, never swallowed). The slice itself is\n * left untouched by a failed refresh — the held token (if any) stays held and\n * stale stays set, so the consumer can retry; clearing it is the consumer's\n * policy, expressed in their reducer.\n */\nexport interface TokenRefreshFailedMsg {\n  readonly type: typeof MsgType.TokenRefreshFailed;\n  readonly error: unknown;\n}\n\n/** Construct a `token_refresh_failed` Msg carrying the rejection. */\nexport function tokenRefreshFailedMsg(error: unknown): TokenRefreshFailedMsg {\n  return { type: MsgType.TokenRefreshFailed, error };\n}\n\n/** The two Msgs the refresh port can produce. Union for a consumer's Msg type. */\nexport type TokenRefreshMsg = TokenRefreshedMsg | TokenRefreshFailedMsg;\n\n/** The ports this knob's `handlers` splice needs — the single refresh DI seam. */\nexport interface TokenRefreshPorts {\n  /**\n   * Mint a fresh credential. Called ONLY from the `refresh_token` interpret\n   * handler — never from a verb — so the network I/O and any clock the issuer\n   * reads stay at the effect boundary. May reject; the rejection is routed to\n   * `token_refresh_failed` (errors are data), never thrown into the runtime.\n   */\n  readonly refresh: () => Promise<Token>;\n}\n\n/**\n * The knob: hand it a config, get back the slice initializer, the pure verbs,\n * and the `handlers` splice. Mirrors every L2 composition's uniform contract so\n * the call sites read identically across bricks.\n *\n * @example\n *   const tr = createTokenRefresh({ skewMs: 30_000 });\n *   const s0 = tr.init();\n *   const [s1, cmds] = tr.ensureFresh(s0, Date.now()); // cmds = [refreshTokenCmd()]\n */\nexport function createTokenRefresh(config: TokenRefreshConfig = {}) {\n  // Clamp once at construction: a negative skew would push the refresh trigger\n  // PAST expiry, which inverts the knob's intent (\"refresh ahead\"). NaN (a\n  // miswired config) collapses to 0 so `needsRefresh`'s comparison stays total.\n  const skewMs =\n    config.skewMs !== undefined && config.skewMs > 0 ? config.skewMs : 0;\n\n  /**\n   * Whether the held token must be refreshed before the next guarded call, at\n   * the injected instant `at` (epoch ms). PURE — reads only, no clock, no\n   * mutation. True iff ANY of:\n   *\n   *   - no token is held (`token === null`) — nothing to present;\n   *   - the token was marked `stale` by a 401 — the server disagrees with the\n   *     client's belief that it is valid;\n   *   - the token's `expiresAt` is not a finite number (`NaN` / `±Infinity`) —\n   *     a miswired issuer or a corrupted slice; we cannot reason about when it\n   *     lapses, so we fail SAFE toward minting a fresh one rather than letting\n   *     `at >= NaN` (always `false`) or `at >= Infinity` (always `false`) mask\n   *     a broken expiry as \"fresh forever\";\n   *   - the token is at or past its skewed expiry (`at >= expiresAt - skewMs`)\n   *     — the proactive refresh-ahead window has opened.\n   *\n   * The expiry cutoff is half-open (`>=`), matching the window edges in\n   * `rate-limit` / `cache` / `circuit-breaker`: a token minted to expire at `t`\n   * with zero skew is considered due at exactly `t`.\n   */\n  function needsRefresh(state: TokenState, at: number): boolean {\n    if (state.token === null) return true;\n    if (state.stale) return true;\n    // Non-finite expiry (NaN/±Infinity) can never be compared into a \"due\"\n    // verdict — `at >= NaN` and `at >= Infinity` are both `false`, which would\n    // pin a broken token as fresh forever. Fail safe: treat it as needing a\n    // refresh so the next call mints a credential with a real deadline.\n    if (!Number.isFinite(state.token.expiresAt)) return true;\n    return at >= state.token.expiresAt - skewMs;\n  }\n\n  /**\n   * Mark the held token unusable because a request the client believed valid\n   * came back 401. PURE — returns a new slice; the input is never mutated.\n   * Sets `stale` regardless of `expiresAt`, so the next `needsRefresh` returns\n   * true even when the clock still says the token is fine. The token VALUE is\n   * kept (not nulled) — it is the consumer's last-known credential until a\n   * refresh replaces it, and keeping it lets observability show what was\n   * rejected.\n   *\n   * Idempotent: a second 401 on an already-stale slice returns the same shape.\n   * A 401 with no token held is a no-op (already needs a refresh).\n   */\n  function on401(state: TokenState): TokenState {\n    if (state.stale) return state;\n    return { ...state, stale: true };\n  }\n\n  /**\n   * Install a freshly minted `token`, clearing `stale`. PURE — returns a new\n   * slice; the input is never mutated. This is the fold for the\n   * `token_refreshed` Msg: after it, `needsRefresh(state, at)` is false for any\n   * `at` below the new skewed expiry, and the stale flag is gone (the new\n   * credential supersedes whatever the 401 rejected).\n   *\n   * This is the slice's WRITE boundary for a credential, so it is where the\n   * durability invariant is paid for: it normalizes a negative-zero `expiresAt`\n   * to `+0` before the value enters the slice. `-0` is the one finite double\n   * JSON cannot round-trip — `JSON.stringify(-0)` is `\"0\"`, which parses back as\n   * `+0`, so a slice carrying `-0` would diverge from its persisted form across\n   * a Durable Object eviction / page reload (invariant: the boundary parses, the\n   * core trusts). `-0` and `+0` denote the same epoch-ms instant, so collapsing\n   * them loses no information and makes the un-round-trippable state\n   * unrepresentable in the slice by construction.\n   */\n  function refreshed(state: TokenState, token: Token): TokenState {\n    const normalized: Token = Object.is(token.expiresAt, -0)\n      ? { ...token, expiresAt: 0 }\n      : token;\n    return { ...state, token: normalized, stale: false };\n  }\n\n  /**\n   * The verb a consumer calls at the call boundary: \"make sure I have a fresh\n   * credential before the next request.\" PURE — returns `[next, cmds]`. When a\n   * refresh is due (`needsRefresh(state, at)`), emits a single `refresh_token`\n   * Cmd; otherwise emits none. The slice is returned UNCHANGED in both branches\n   * — the refresh itself is async and lands later via `refreshed`, so there is\n   * no in-flight phase to record here. (A consumer that wants single-flight —\n   * \"don't fire a second refresh while one is pending\" — layers that in their\n   * own reducer, e.g. by tracking a pending flag; this brick stays minimal and\n   * lets the consumer own that policy.)\n   *\n   * The `at` is the caller's stamped clock reading (epoch ms), never read here —\n   * keeping the verb pure and `replay`-able.\n   */\n  function ensureFresh(\n    state: TokenState,\n    at: number,\n  ): readonly [TokenState, readonly Cmd[]] {\n    if (needsRefresh(state, at)) {\n      return [state, [refreshTokenCmd()]];\n    }\n    return [state, []];\n  }\n\n  /**\n   * The interpret splice: wraps the injected `refresh` port and routes its\n   * Ok/Err to `token_refreshed` / `token_refresh_failed` Msgs via the core's\n   * `tryInterpret` Railway helper. Spread the result into a consumer's\n   * `interpret` map:\n   *\n   *   interpret: { ...other, ...tr.handlers({ refresh: () => sdk.mintToken() }) }\n   *\n   * The port is the ONLY place the network (and any clock the issuer reads) is\n   * touched — every verb above stays pure. `tryInterpret` guarantees the\n   * handler never rejects: a port rejection becomes a `token_refresh_failed`\n   * Msg (errors are data), so the runtime's dispatch loop is never poisoned by\n   * an unhandled rejection.\n   */\n  function handlers(\n    ports: TokenRefreshPorts,\n  ): Interpret<TokenRefreshMsg, RefreshTokenCmd, unknown> {\n    return {\n      refresh_token: tryInterpret<\n        RefreshTokenCmd,\n        Token,\n        TokenRefreshMsg,\n        unknown\n      >(\n        () => ports.refresh(),\n        (token) => tokenRefreshedMsg(token),\n        (error) => tokenRefreshFailedMsg(error),\n      ),\n    };\n  }\n\n  return {\n    /** The slice initializer — spread into the consumer's `init`. */\n    init: initTokenRefresh,\n    needsRefresh,\n    on401,\n    refreshed,\n    ensureFresh,\n    handlers,\n  };\n}\n\n/** The shape `createTokenRefresh` returns — useful for typing a held knob. */\nexport type TokenRefresh = ReturnType<typeof createTokenRefresh>;\n"]}

package/dist/chunk-UF4MZSLT.js

@@ -1,53 +0,0 @@
-// 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 };
-//# sourceMappingURL=chunk-UF4MZSLT.js.map
-//# sourceMappingURL=chunk-UF4MZSLT.js.map

package/dist/chunk-UF4MZSLT.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/circuit-breaker/index.ts"],"names":[],"mappings":";AAyHO,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":"chunk-UF4MZSLT.js","sourcesContent":["/**\n * @packageDocumentation\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"]}

package/dist/chunk-UOC2PL46.js

@@ -1,13 +0,0 @@
-// src/machine-viz/mermaid-id.ts
-function safeId(raw) {
-  const cleaned = raw.replace(/[^A-Za-z0-9_]/g, "_");
-  if (cleaned === "") return "_empty";
-  return /^[0-9]/.test(cleaned) ? `s_${cleaned}` : cleaned;
-}
-function safeLabel(raw) {
-  return raw.replace(/["\n\r;:]/g, " ").trim();
-}
-
-export { safeId, safeLabel };
-//# sourceMappingURL=chunk-UOC2PL46.js.map
-//# sourceMappingURL=chunk-UOC2PL46.js.map

package/dist/chunk-UOC2PL46.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/machine-viz/mermaid-id.ts"],"names":[],"mappings":";AAsBO,SAAS,OAAO,GAAA,EAAqB;AAC1C,EAAA,MAAM,OAAA,GAAU,GAAA,CAAI,OAAA,CAAQ,gBAAA,EAAkB,GAAG,CAAA;AACjD,EAAA,IAAI,OAAA,KAAY,IAAI,OAAO,QAAA;AAC3B,EAAA,OAAO,SAAS,IAAA,CAAK,OAAO,CAAA,GAAI,CAAA,EAAA,EAAK,OAAO,CAAA,CAAA,GAAK,OAAA;AACnD;AAQO,SAAS,UAAU,GAAA,EAAqB;AAC7C,EAAA,OAAO,GAAA,CAAI,OAAA,CAAQ,YAAA,EAAc,GAAG,EAAE,IAAA,EAAK;AAC7C","file":"chunk-UOC2PL46.js","sourcesContent":["// ═══════════════════════════════════════════════════════════════════════════\n// MERMAID SANITIZING — the two functions every drawing in this package shares.\n//\n// Mermaid state ids must be identifier-safe, and a transition label must not\n// contain the characters that terminate it. Both `machine-viz`'s `toMermaid`\n// (which draws a COMPILED machine) and `chart`'s `chartMermaid` (which draws\n// the CHART) need exactly this, and a state name like `human:cp-approval` —\n// real, from `src/chart/__fixtures__/lane.ts` — breaks the diagram in both.\n//\n// So it lives here, in a module with NO imports: `machine-viz/index.ts` pulls\n// in the whole substrate (`formOf` from `../index`), and `chart/compile.ts`\n// must not acquire that dependency merely to sanitize a string.\n// ═══════════════════════════════════════════════════════════════════════════\n\n/**\n * Sanitize a discriminant string into a Mermaid-safe node identifier.\n *\n * Any run of non-identifier characters becomes `_`; a leading digit is\n * prefixed so the id is always a valid Mermaid token; the empty string gets a\n * stable placeholder. Deterministic and idempotent — `safeId(safeId(x))` is\n * `safeId(x)`, so a diagram may sanitize the same name at several sites.\n */\nexport function safeId(raw: string): string {\n  const cleaned = raw.replace(/[^A-Za-z0-9_]/g, \"_\");\n  if (cleaned === \"\") return \"_empty\";\n  return /^[0-9]/.test(cleaned) ? `s_${cleaned}` : cleaned;\n}\n\n/**\n * Sanitize text used as a Mermaid edge/transition label (the part after `:`).\n *\n * Strips the characters that terminate or confuse a label: newlines, the `:`\n * that separates label from target, and Mermaid's `\"`/`;` delimiters.\n */\nexport function safeLabel(raw: string): string {\n  return raw.replace(/[\"\\n\\r;:]/g, \" \").trim();\n}\n"]}

package/dist/chunk-WLGO64WC.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/monitored-run/index.ts"],"names":[],"mappings":"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","file":"chunk-WLGO64WC.js","sourcesContent":["/**\n * @demlik/tea/monitored-run — a long-running operation that is BOTH staged and\n * watched: an ordered stage pipeline whose POSITION survives eviction, wrapped\n * by a no-progress safety deadline and (optionally) a periodic durable\n * checkpoint.\n *\n * This is the merge of two field-guide concerns the audit-agent machine\n * hand-wired together (`seed/audit-agent-machine`): the OUTER pipeline position\n * (`RunStage` — planning → testing → summarizing → reporting, replayed on cold\n * wake by re-emitting the one outstanding effect) and the no-progress safety\n * alarm (`subs.ts`, keyed on `progressSeq` so every progress event retires the\n * old alarm and arms a fresh one). `monitored-run` lifts both into one config-\n * driven knob with the uniform L2 contract `resilient-call` established:\n * `init()`, the verbs (`start` / `advance` / `progress` / `onDeadline` /\n * `boot`), `subs(state)`, and `handlers(ports)`.\n *\n *   - It is **staged, optionally**. Omit `stages` and the run is single-shot:\n *     `start` enters `running`, `advance` finishes it to `done`. Provide\n *     `stages` and it becomes an ordered pipeline — each `advance` retires the\n *     current stage and claims the next, finishing to `done` only when the last\n *     stage is retired. The pipeline POSITION lives in the Model (a\n *     `work-queue` of stage items), so an eviction mid-pipeline resumes at the\n *     same stage via `boot` — the audit machine's \"pipeline position survives\n *     eviction\" property, generalized.\n *   - It is **watched**. While `running`, a no-progress deadline is armed at\n *     `lastProgressAt + deadlineMs` and keyed on `progressSeq`. Every\n *     `progress` / `advance` bumps the seq, so the substrate retires the old\n *     alarm and arms a new one — a self-rearming watchdog. If the alarm fires\n *     (`onDeadline`) the run goes `failed` with a deadline reason. Omit\n *     `deadlineMs` → no watchdog (the `stale` phase is never reachable).\n *   - It **checkpoints, optionally**. Provide `snapshotEvery` and every\n *     progress unit is accounted to a `../snapshot` slice; once the cadence is\n *     reached a checkpoint Cmd is emitted (interpreted by the spliced snapshot\n *     `handlers`), so a crashed run restarts from the last durable checkpoint\n *     rather than from zero. Omit it → no checkpointing.\n *\n * ## Why the run lifecycle is INLINE (run-tracker not extracted)\n *\n * The phase union (`idle` / `running` / `stale` / `done` / `failed`, a\n * discriminated union carrying only each phase's own data) and its bookkeeping\n * (`runId`, `startedAt`, `lastProgressAt`, `progressSeq`) live directly on this\n * slice rather than behind a `run-tracker` sub-knob.\n * Extraction earns its keep when two independent axes vary; here the lifecycle\n * has exactly one anchoring axis (this run), so a separate module would be a\n * premature seam. The two genuinely independent axes — the safety DEADLINE and\n * the periodic SNAPSHOT — ARE extracted (`../deadline`, `../snapshot`), and the\n * stage list is a `../work-queue` slice (`QueueItem<Stage>[]`) whose every\n * status flip is DELEGATED to the blessed `../work-queue/ops` (`enqueueOp` /\n * `claimNextOp` / `markDoneOp`) — never re-rolled here. The lifecycle is the\n * glue between them.\n *\n * ## The two non-negotiables (canon)\n *\n *   - **Durable** — the slice is plain data (the stage queue is a\n *     JSON-serializable `QueueItem<Stage>[]`, the snapshot slice is plain\n *     numbers), so it survives DO eviction / reload.\n *   - **Replayable** — every transition is a pure verb returning new state +\n *     Cmds; nothing here reads the clock or RNG. Time arrives as an `at` / `atMs`\n *     parameter; the only clock read is `Date.now()` inside the snapshot\n *     `handlers` port (the effect boundary), exactly as `../snapshot` stamps it.\n *\n * ## Typical wiring\n *\n *   const run = createMonitoredRun<MyStage, MyState>({\n *     stages: [\"plan\", \"test\", \"report\"],\n *     deadlineMs: 10 * 60_000,\n *     snapshotEvery: 25,\n *   });\n *\n *   init: (loaded) => loaded ? [loaded, []] : [{ run: run.init() }, []],\n *   update: {\n *     begin:    (s, m) => lift(s, run.start(s.run, m.runId, m.at)),\n *     advance:  (s, m) => lift(s, run.advance(s.run, checkpoint(s), m.result, m.at)),\n *     progress: (s, m) => lift(s, run.progress(s.run, checkpoint(s), m.at)),\n *     run_deadline: (s, m) => lift(s, run.onDeadline(s.run, m)),\n *     boot:     (s, m) => lift(s, run.boot(s.run, m.at)),\n *   },\n *   subscriptions: (s) => run.subs(s.run),\n *   subscribe: { deadline: subscribeDeadline },\n *   interpret: run.handlers({ store: r2 }),\n */\n\nimport {\n  type DeadlineExceeded,\n  type DeadlineSub,\n  deadlineSub,\n  subscribeDeadline,\n} from \"../deadline\";\nimport type { Cmd, Interpret } from \"../index\";\nimport {\n  createSnapshot,\n  type SnapshotFailedMsg,\n  type SnapshotLoadCmd,\n  type SnapshotLoadedMsg,\n  type SnapshotLoadFailedMsg,\n  type SnapshotSavedMsg,\n  type SnapshotState,\n  type SnapshotStore,\n  type SnapshotWriteCmd,\n} from \"../snapshot\";\nimport type { QueueItem } from \"../work-queue\";\nimport { queueAdapter } from \"../work-queue/adapter\";\n\n// ===========================================================================\n// Config — the knob. Every field optional; omit a field → omit its gate.\n// ===========================================================================\n\n/**\n * The monitored-run knob. EVERY field is optional:\n *   - omit `stages`       → single-shot run (no pipeline; one `advance` finishes).\n *   - omit `deadlineMs`   → no no-progress watchdog (the run is never auto-failed).\n *   - omit `snapshotEvery`→ no periodic checkpoint (no `snapshot_write` Cmds).\n *\n * An empty config `{}` is a valid single-shot, unwatched, uncheckpointed run.\n *\n * `Stage` is the consumer's stage identifier — any JSON-serializable value\n * (a string id, a `{ kind, ... }` record). It rides through the stage queue\n * unchanged so the consumer's reducer can branch on the current stage to emit\n * that stage's outstanding effect (the audit machine's `outstandingEffect`).\n */\nexport interface MonitoredRunConfig<Stage> {\n  /**\n   * The ordered stages of the pipeline. Position survives eviction (lives in\n   * the Model's stage queue). Omit for a single-shot run. An empty array is\n   * treated as single-shot too — there is nothing to pipeline through.\n   */\n  readonly stages?: readonly Stage[];\n  /**\n   * No-progress watchdog budget, in ms. The safety deadline is armed at\n   * `lastProgressAt + deadlineMs` and re-armed on every progress event. Omit\n   * for no watchdog.\n   */\n  readonly deadlineMs?: number;\n  /**\n   * Checkpoint cadence — write a durable snapshot once this many progress\n   * units have accumulated. Threaded straight into `../snapshot`'s `every`.\n   * Omit for no checkpointing.\n   */\n  readonly snapshotEvery?: number;\n  /**\n   * Store key the rolling checkpoint is written under. Forwarded to\n   * `../snapshot`'s `key`; defaults to that module's `@@snapshot`. Ignored\n   * when `snapshotEvery` is omitted.\n   */\n  readonly snapshotKey?: string;\n}\n\n// ===========================================================================\n// Slice — the Model field this knob owns. Run lifecycle INLINE + composed bricks.\n// ===========================================================================\n\n/**\n * Why a run terminated as `failed`. Discriminated so each reason carries only\n * its own data (pattern 11):\n *   - `deadline`  — the no-progress watchdog fired (`onDeadline`).\n *   - `stage`     — the consumer reported a stage failure via `advance(..., fail)`.\n *\n * `stale` is a SEPARATE phase (not a fail reason): a run is `stale` only by an\n * explicit consumer signal that progress has wedged WITHOUT the deadline having\n * fired — a soft, recoverable observation. The deadline firing is a hard\n * terminal (`failed { reason: \"deadline\" }`).\n *\n * The `stage` variant carries the FAILING STAGE VALUE (the `Stage` itself), not\n * a positional index: done stages leave the queue (`markDoneOp` filters them),\n * so a residual index drifts as the pipeline advances. The stage value is the\n * stable, meaningful identifier — `undefined` for a single-shot run (no stage).\n */\nexport type RunFailure<Stage> =\n  | { readonly reason: \"deadline\"; readonly at: number }\n  | {\n      readonly reason: \"stage\";\n      readonly stage: Stage | undefined;\n      readonly error: unknown;\n    };\n\n/**\n * The run bookkeeping every phase carries in common, split out so each arm of\n * the `MonitoredRunState` discriminated union names only the data it ADDS\n * (`runId` on started phases, `failure` on `failed`) — the same discipline the\n * sibling `PaginatorState` uses for its shared `seen` / `pages` counters. Plain\n * data end to end so the whole slice survives DO eviction / reload:\n *\n *   - `stepStates`     — the stage pipeline as a `work-queue` of stage items.\n *                        Empty for a single-shot run. The ONE `running` item is\n *                        the current stage; `done` items are retired stages\n *                        (they leave the queue via `markDoneOp`, so the queue\n *                        shrinks as the pipeline advances and is empty at\n *                        `done`). POSITION survives eviction because this list\n *                        is durable.\n *   - `startedAt`      — `at` of `start`. Observability; never compared in a verb.\n *   - `lastProgressAt` — `at` of the most recent progress event; the watchdog\n *                        base. Re-armed by `progress` / `advance`.\n *   - `progressSeq`    — monotonic progress counter; keys the safety alarm Sub\n *                        id so every bump retires the old alarm and arms a new\n *                        one (the audit subs' `safety:{progressSeq}` discipline).\n *   - `snapshot`       — the `../snapshot` slice (cadence counter + durable\n *                        watermark). Always present (uniform shape); the gate\n *                        is simply never driven when `snapshotEvery` is omitted.\n */\ninterface RunCore<Stage> {\n  readonly stepStates: readonly QueueItem<Stage>[];\n  readonly startedAt: number;\n  readonly lastProgressAt: number;\n  readonly progressSeq: number;\n  readonly snapshot: SnapshotState;\n}\n\n/**\n * The slice — a discriminated union on `phase` so each phase carries ONLY its\n * own data and impossible combinations are unrepresentable (pattern 11), the\n * same idiom the sibling `CircuitState` / `PaginatorState` / `RunFailure` follow:\n *\n *   - `idle`    — created but never started. Carries no `runId` (identity is\n *                 host-minted at `start`) and no `failure`: \"not started\" is its\n *                 OWN phase, not a `running` run wearing an empty-string `runId`\n *                 sentinel. `start` is the only transition out, so no verb has to\n *                 guard \"has this actually started?\" — `phase === \"idle\"` says it.\n *   - `running` — the run is live. Carries the host-minted `runId` and the\n *                 `RunCore` pipeline position + watchdog bookkeeping.\n *   - `stale`   — a soft \"no progress observed\" mark the consumer can set and\n *                 clear; still resumable (a `progress` clears it back to\n *                 `running`). Distinct from a fired deadline, which is terminal.\n *   - `done`    — every stage retired (or the single-shot `advance` landed).\n *   - `failed`  — terminal failure; the typed `failure` reason rides ONLY this\n *                 arm, so it is present iff `phase === \"failed\"` BY CONSTRUCTION —\n *                 there is no nullable side field to keep in sync.\n *\n * `runId` is the host-minted run identity, stamped at `start` (the machine never\n * mints — see the audit seed's \"run identity is host-minted\"). It rides every\n * started phase, but not `idle`.\n */\nexport type MonitoredRunState<Stage> =\n  | (RunCore<Stage> & { readonly phase: \"idle\" })\n  | (RunCore<Stage> & { readonly phase: \"running\"; readonly runId: string })\n  | (RunCore<Stage> & { readonly phase: \"stale\"; readonly runId: string })\n  | (RunCore<Stage> & { readonly phase: \"done\"; readonly runId: string })\n  | (RunCore<Stage> & {\n      readonly phase: \"failed\";\n      readonly runId: string;\n      readonly failure: RunFailure<Stage>;\n    });\n\n/**\n * The live (still-timed) phases — `running` or `stale`. The verbs narrow to this\n * before touching the watchdog bookkeeping (`runId` / `progressSeq`), so a\n * settled (`done` / `failed`) or never-started (`idle`) slice can never be bumped\n * — the narrow replaces the old `runId === \"\"` born-live guard.\n */\ntype LiveRun<Stage> = Extract<\n  MonitoredRunState<Stage>,\n  { readonly phase: \"running\" | \"stale\" }\n>;\n\n/**\n * The outcome a consumer reports to `advance`: the current stage either\n * succeeded (retire it, claim the next) or failed (terminate the run). Plain\n * data — the consumer parses its stage result at its own boundary and hands a\n * settled outcome here.\n */\nexport type StageResult =\n  | { readonly kind: \"ok\" }\n  | { readonly kind: \"fail\"; readonly error: unknown };\n\n// ===========================================================================\n// Cmd + Msg — re-exported from the composed bricks so consumers wire one import.\n// ===========================================================================\n\n/** The checkpoint-write Cmd, generic over the consumer's checkpoint value `V`. */\nexport type MonitoredRunCmd<V> = SnapshotWriteCmd<V>;\n\n/** The deadline Msg the safety alarm dispatches when the watchdog fires. */\nexport type MonitoredRunTimerMsg = DeadlineExceeded;\n\n/** Ports the consumer supplies to `handlers` — just the checkpoint store. */\nexport interface MonitoredRunPorts<V> {\n  /** Where periodic checkpoints are written (R2 / KV / DO sub-key / Map). */\n  readonly store: SnapshotStore<V>;\n}\n\n// ===========================================================================\n// Sub-id family. The safety alarm is keyed on `progressSeq` so a progress\n// event retires the old alarm and arms a new one (single-shot, re-armed by id\n// bump — the audit subs discipline).\n// ===========================================================================\n\nfunction safetyTimerId(runId: string, progressSeq: number): string {\n  return `monitored:safety:${runId}:${progressSeq}`;\n}\n\n// ===========================================================================\n// The knob factory.\n// ===========================================================================\n\n/**\n * Build a monitored-run knob from `config`. `Stage` is the consumer's stage\n * identifier type; `V` is the consumer's checkpoint value type (what\n * `snapshotEvery` checkpoints). Returns the uniform L2 knob contract.\n *\n * No `rng` parameter: unlike `resilient-call`, nothing here jitters — the only\n * external inputs are time (an `at` / `atMs` parameter) and the consumer's\n * stage outcomes. The clock is read only inside the snapshot `handlers` port.\n */\nexport function createMonitoredRun<Stage, V = unknown>(\n  config: MonitoredRunConfig<Stage> = {},\n) {\n  const stages = config.stages ?? [];\n  const isPipeline = stages.length > 0;\n\n  // The stage-queue seam, bound once. Every stage status flip delegates to the\n  // `QueueAdapter` verbs (`wq.enqueue` / `wq.claim` / `wq.markDone`), so the\n  // `QueueItem<Stage>` shape stays insulated behind them.\n  const wq = queueAdapter<Stage>();\n\n  // The snapshot sub-knob is built only when `snapshotEvery` is configured;\n  // absence is `null` so the progress gate short-circuits to \"no checkpoint\".\n  // When present, the slice still carries a default SnapshotState so the shape\n  // is uniform across configs — the gate simply never records into it.\n  const snap =\n    config.snapshotEvery !== undefined\n      ? createSnapshot<V>({\n          every: config.snapshotEvery,\n          ...(config.snapshotKey !== undefined\n            ? { key: config.snapshotKey }\n            : {}),\n        })\n      : null;\n\n  // The snapshot knob to actually drive: `snap` when configured, else a single\n  // inert default (`every: 1`) bound ONCE here. Its `record` is never invoked\n  // (the progress gate short-circuits when `snap` is null), so the cadence value\n  // is immaterial — one shared stateless knob of pure functions stands in for\n  // the disabled-checkpoint case across init/boot/handlers.\n  const activeSnap = snap ?? createSnapshot<V>({ every: 1 });\n\n  /** The starting slice for a never-started run: the `idle` phase, no `runId`. */\n  function init(): MonitoredRunState<Stage> {\n    return {\n      phase: \"idle\",\n      stepStates: [],\n      startedAt: 0,\n      lastProgressAt: 0,\n      progressSeq: 0,\n      // A default snapshot slice even without the brick → uniform shape. When\n      // `snap` is null the inert `activeSnap` default supplies the slice; its\n      // `record` is never called, so the cadence value is immaterial.\n      snapshot: activeSnap.init(),\n    };\n  }\n\n  /**\n   * Seed the stage queue from the configured stages: every stage enqueued\n   * `pending`, then the first claimed `running`. `at` stamps the claim. PURE —\n   * the work-queue ops are pure array transforms; ids are positional (`stage:i`)\n   * so they are deterministic and replayable (no `crypto`, no `Math.random`).\n   */\n  function seedStages(at: number): readonly QueueItem<Stage>[] {\n    let queue: readonly QueueItem<Stage>[] = [];\n    stages.forEach((stage, i) => {\n      queue = wq.enqueue(queue, stage, at, `stage:${i}`).next;\n    });\n    // Claim the first stage as the running position. A non-empty pipeline always\n    // has a pending head here, so the claim succeeds.\n    const claimed = wq.claim(queue, at);\n    return claimed ? claimed.next : queue;\n  }\n\n  /** The current (running) stage item, or `undefined` for a single-shot run. */\n  function currentStage(\n    s: MonitoredRunState<Stage>,\n  ): QueueItem<Stage> | undefined {\n    return s.stepStates.find((i) => i.status === \"running\");\n  }\n\n  // === Verb: start =========================================================\n\n  /**\n   * Start (or restart) the run for `runId` at time `at`. Seeds the stage queue\n   * (if a pipeline) and enters `running` with the watchdog clock primed. Stamps\n   * `runId` from the host — the machine never mints (invariant: identity is\n   * host-minted, parsed at the boundary). PURE.\n   */\n  function start(\n    s: MonitoredRunState<Stage>,\n    runId: string,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    // Build the `running` arm explicitly rather than spreading `...s`: a restart\n    // from `failed` must NOT carry the old `failure` field forward (the `running`\n    // arm has none), and a start from `idle` has no `runId` to preserve. Only the\n    // snapshot slice threads through.\n    const next: MonitoredRunState<Stage> = {\n      phase: \"running\",\n      runId,\n      stepStates: isPipeline ? seedStages(at) : [],\n      startedAt: at,\n      lastProgressAt: at,\n      progressSeq: 0,\n      snapshot: s.snapshot,\n    };\n    return [next, []];\n  }\n\n  /**\n   * Bump the watchdog clock: set `lastProgressAt`/`progressSeq` so the safety\n   * alarm Sub id changes and the substrate re-arms a fresh deadline. Shared by\n   * `progress` and `advance`. PURE.\n   */\n  function bumpProgress(s: LiveRun<Stage>, at: number): LiveRun<Stage> {\n    return { ...s, lastProgressAt: at, progressSeq: s.progressSeq + 1 };\n  }\n\n  /**\n   * Account one progress unit to the snapshot slice (when the brick is\n   * configured), returning the new slice + any checkpoint Cmd. `payload` is the\n   * consumer's checkpoint value to persist. PURE — `snap.record` is pure, the\n   * write is realized only when the runtime performs the emitted Cmd.\n   */\n  function recordSnapshot(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (snap === null) return [s, []];\n    const [snapshot, cmds] = snap.record(s.snapshot, payload, at);\n    // `snap.record` only ever emits `SnapshotWriteCmd<V>` (its sole Cmd), but\n    // its signature widens to `readonly Cmd[]`. Narrow back to this knob's\n    // precise Cmd union so a consumer's host Cmd type can stay exact.\n    return [{ ...s, snapshot }, cmds as readonly MonitoredRunCmd<V>[]];\n  }\n\n  // === Verb: progress ======================================================\n\n  /**\n   * Record forward progress: bump the watchdog (re-arming the safety alarm),\n   * clear any `stale` mark back to `running`, and account a snapshot unit\n   * (emitting a checkpoint Cmd on a cadence hit). A no-op unless the run is live\n   * (`running` / `stale`) — a late progress event on a settled (`done` /\n   * `failed`) or never-started (`idle`) run is ignored. PURE.\n   */\n  function progress(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    const bumped: MonitoredRunState<Stage> = {\n      ...bumpProgress(s, at),\n      phase: \"running\",\n    };\n    return recordSnapshot(bumped, payload, at);\n  }\n\n  // === Verb: markStale =====================================================\n\n  /**\n   * Mark the run `stale` — a soft \"no progress observed\" signal the consumer\n   * raises WITHOUT the deadline having fired (e.g. an upstream heartbeat gap).\n   * Recoverable: the next `progress` flips it back to `running`. A no-op unless\n   * the run is currently `running` (a settled run cannot go stale). Does NOT\n   * touch `progressSeq` — going stale is not progress, so the armed deadline\n   * keeps counting toward the hard terminal. PURE.\n   */\n  function markStale(\n    s: MonitoredRunState<Stage>,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\") return [s, []];\n    return [{ ...s, phase: \"stale\" }, []];\n  }\n\n  // === Verb: advance =======================================================\n\n  /**\n   * Advance the pipeline on a stage outcome:\n   *\n   *   - `result.kind === \"fail\"` → terminate `failed { reason: \"stage\" }`,\n   *     carrying the failing stage index + error. No further stages run.\n   *   - `result.kind === \"ok\"`:\n   *       - single-shot run → finish to `done` (and force a final checkpoint\n   *         when checkpointing, so the last durable snapshot is the terminal\n   *         state).\n   *       - pipeline → retire the current stage (`markDoneOp`) and claim the\n   *         next (`claimNextOp`). If none remain, finish to `done`. The new\n   *         position survives eviction.\n   *\n   * An advance is itself a progress event, so it bumps the watchdog (re-arming\n   * the alarm at the new stage) and accounts a snapshot unit. A no-op on a\n   * settled (`done` / `failed`) or never-started (`idle`) run. PURE — `at` is the\n   * only clock, ids are positional.\n   */\n  function advance(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    result: StageResult,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n\n    // Stage failure → hard terminal. Carry the failing stage VALUE (stable),\n    // `undefined` for a single-shot run with no stage.\n    if (result.kind === \"fail\") {\n      const failed: MonitoredRunState<Stage> = {\n        ...s,\n        phase: \"failed\",\n        failure: {\n          reason: \"stage\",\n          stage: currentStage(s)?.input,\n          error: result.error,\n        },\n      };\n      return [failed, []];\n    }\n\n    // Success: bump the watchdog first (an advance is progress), then move the\n    // pipeline position.\n    const bumped = bumpProgress(s, at);\n\n    // Single-shot: one advance finishes the run.\n    if (!isPipeline) {\n      const done: MonitoredRunState<Stage> = { ...bumped, phase: \"done\" };\n      // Force a terminal checkpoint so the last durable snapshot is `done`,\n      // not whatever the cadence happened to land on.\n      return finishWithSnapshot(done, payload, at);\n    }\n\n    // Pipeline: retire the running stage, claim the next.\n    const current = currentStage(s);\n    const afterDone =\n      current !== undefined\n        ? wq.markDone(s.stepStates, current.id).next\n        : s.stepStates;\n    const claimed = wq.claim(afterDone, at);\n\n    if (claimed === null) {\n      // No more stages — the pipeline is complete.\n      const done: MonitoredRunState<Stage> = {\n        ...bumped,\n        phase: \"done\",\n        stepStates: afterDone,\n      };\n      return finishWithSnapshot(done, payload, at);\n    }\n\n    // Advance to the next stage — POSITION now points at the claimed item.\n    const moved: MonitoredRunState<Stage> = {\n      ...bumped,\n      stepStates: claimed.next,\n    };\n    return recordSnapshot(moved, payload, at);\n  }\n\n  /**\n   * Finish helper: force a terminal checkpoint when checkpointing is enabled\n   * (so the durable snapshot is the terminal state), else just settle. Shared\n   * by single-shot finish and pipeline completion. PURE.\n   */\n  function finishWithSnapshot(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (snap === null) return [s, []];\n    const [snapshot, cmds] = snap.force(s.snapshot, payload, at);\n    // Same narrowing as `recordSnapshot`: `snap.force` emits only the write Cmd.\n    return [{ ...s, snapshot }, cmds as readonly MonitoredRunCmd<V>[]];\n  }\n\n  // === Verb: onDeadline ====================================================\n\n  /**\n   * The safety alarm fired. Two outcomes by Sub-id match:\n   *\n   *   - the alarm matches the CURRENT `progressSeq` (no progress since it was\n   *     armed) → the run is wedged → terminate `failed { reason: \"deadline\" }`.\n   *   - the alarm matches an OLDER seq → a stale fire racing a progress event\n   *     that already re-armed the alarm → no-op (the substrate retired this id;\n   *     tolerate a fire still in flight defensively).\n   *\n   * A no-op on a settled run (its alarm was reconciled away; tolerate a stale\n   * fire) and on a NEVER-STARTED (`idle`) run (`subs` armed nothing for it, so\n   * any alarm reaching it is a rogue fire that must not un-start it). PURE —\n   * `msg.atMs` stamps the failure.\n   */\n  function onDeadline(\n    s: MonitoredRunState<Stage>,\n    msg: MonitoredRunTimerMsg,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    // Only a live (`running` / `stale`) run is watched. A settled (`done` /\n    // `failed`) run's alarm was reconciled away, and a never-started (`idle`) run\n    // — which has no host-minted `runId` and armed nothing — must not be\n    // un-started by a born-live/rogue fire. The phase narrow IS the guard the old\n    // `runId === \"\"` sentinel stood in for.\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    // Only the alarm armed against the current progressSeq is live. A bumped\n    // seq means progress re-armed it; an older fire is stale.\n    if (msg.id !== safetyTimerId(s.runId, s.progressSeq)) return [s, []];\n    const failed: MonitoredRunState<Stage> = {\n      ...s,\n      phase: \"failed\",\n      failure: { reason: \"deadline\", at: msg.atMs },\n    };\n    return [failed, []];\n  }\n\n  // === Verb: boot ==========================================================\n\n  /**\n   * Resume after a reload (cold wake). Re-seeds the watchdog clock to `at` so\n   * the safety alarm re-arms from NOW (the pre-crash `lastProgressAt` would\n   * immediately fire a deadline that already elapsed during downtime — a cold\n   * wake is not a no-progress wedge). Bumps `progressSeq` so the alarm gets a\n   * fresh id, and resets the snapshot cadence counter (un-checkpointed\n   * pre-crash progress is moot — recovery resumes from the last durable\n   * checkpoint). The pipeline POSITION (`stepStates`) is preserved untouched —\n   * that is the whole point of staging: resume at the same stage.\n   *\n   * A no-op on a settled (`done` / `failed`) or never-started (`idle`) run. Emits\n   * NO Cmd — re-emitting the current stage's outstanding effect is the CONSUMER's\n   * job (it knows the per-stage Cmd), the audit machine's `outstandingEffect(stage)`\n   * pattern. PURE.\n   */\n  function boot(\n    s: MonitoredRunState<Stage>,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    // `snap.boot` returns the reducer-cell shape `[SnapshotState, Cmd[]]`\n    // (uniform across every sibling knob); a boot emits no Cmd, so take only the\n    // slice. Assigning the tuple itself would put an ARRAY where a SnapshotState\n    // belongs — a type error AND a non-round-trippable slice.\n    const [bootedSnapshot] = activeSnap.boot(s.snapshot);\n    const reseeded: MonitoredRunState<Stage> = {\n      ...s,\n      phase: \"running\",\n      lastProgressAt: at,\n      progressSeq: s.progressSeq + 1,\n      snapshot: bootedSnapshot,\n      // Any stage left `running` mid-flight stays the running position; the\n      // queue is already correct (a single in-flight stage). resetRunningOp is\n      // NOT applied — unlike a work pool, a monitored run has exactly one\n      // in-flight stage and resuming it (not re-queuing it) is the correct\n      // cold-wake behavior.\n    };\n    return [reseeded, []];\n  }\n\n  // === Subs ================================================================\n\n  /**\n   * Pre-wired subscriptions: the no-progress safety deadline, armed only while\n   * the run is live (`running` / `stale`) AND a `deadlineMs` is configured. The\n   * Sub id is keyed on `progressSeq`, so every progress event retires the old\n   * alarm and the substrate arms a fresh one at the new `lastProgressAt +\n   * deadlineMs` — a self-rearming watchdog with no manual `clearTimeout`. A\n   * settled run desires no subs. Wire `subscribe: { deadline: subscribeDeadline }`.\n   *\n   * A NEVER-STARTED slice (`init()`) is its OWN `idle` phase, not a `running` run\n   * with an empty `runId`. The `phase !== \"running\" && phase !== \"stale\"` narrow\n   * therefore excludes it structurally — no separate `runId === \"\"` sentinel gate\n   * is needed. Were `idle` armed, it would fire a deadline at `0 + deadlineMs`\n   * (already in the past) and auto-fail a run that never began — the \"born live\"\n   * defect. `start` is the only transition out of `idle`, so the watchdog exists\n   * exactly once a real run is in flight.\n   */\n  function subs(s: MonitoredRunState<Stage>): readonly DeadlineSub[] {\n    if (config.deadlineMs === undefined) return [];\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [];\n    return [\n      deadlineSub(\n        safetyTimerId(s.runId, s.progressSeq),\n        s.lastProgressAt + config.deadlineMs,\n      ),\n    ];\n  }\n\n  // === Handlers ============================================================\n\n  /**\n   * Pre-wired interpret handler for the checkpoint write. Delegates wholesale to\n   * `../snapshot`'s `handlers` (which performs the `put` and routes Ok →\n   * `snapshot_saved` / Err → `snapshot_failed` via Railway — the write never\n   * rejects into the runtime). When checkpointing is disabled (`snapshotEvery`\n   * omitted), no `snapshot_write` Cmd is ever emitted, so the returned map is an\n   * inert no-op handler — kept for a uniform `handlers(ports)` call shape.\n   *\n   * Fold the `snapshot_saved` Msg back through this knob's `confirmSnapshot`\n   * verb to advance the durable watermark.\n   */\n  function handlers(\n    ports: MonitoredRunPorts<V>,\n  ): Interpret<\n    | SnapshotSavedMsg\n    | SnapshotFailedMsg\n    | SnapshotLoadedMsg<V>\n    | SnapshotLoadFailedMsg,\n    SnapshotWriteCmd<V> | SnapshotLoadCmd,\n    unknown\n  > {\n    return activeSnap.handlers({ store: ports.store });\n  }\n\n  /**\n   * Fold a confirmed checkpoint write into the slice — advances the snapshot\n   * watermark (forward-only). A no-op pass-through when checkpointing is\n   * disabled. PURE. Fold the `snapshot_saved` Msg here.\n   */\n  function confirmSnapshot(\n    s: MonitoredRunState<Stage>,\n    msg: SnapshotSavedMsg,\n  ): MonitoredRunState<Stage> {\n    if (snap === null) return s;\n    // `snap.confirm` returns the reducer-cell shape `[SnapshotState, Cmd[]]`\n    // (an ack emits nothing). Take only the slice — folding the whole tuple into\n    // `snapshot` would store an ARRAY where a SnapshotState belongs (a type error\n    // and a non-round-trippable slice).\n    const [confirmed] = snap.confirm(s.snapshot, msg);\n    return { ...s, snapshot: confirmed };\n  }\n\n  return {\n    init,\n    start,\n    progress,\n    markStale,\n    advance,\n    onDeadline,\n    boot,\n    confirmSnapshot,\n    subs,\n    handlers,\n  };\n}\n\n/**\n * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the\n * slice lives at `state.run`. Convenience for the common single-slice host;\n * hosts with a differently-named field spread by hand. PURE — a thin record\n * rebuild, no clock / RNG.\n */\nexport function liftRun<\n  S extends { run: MonitoredRunState<Stage> },\n  Stage,\n  C extends Cmd,\n>(\n  state: S,\n  [slice, cmds]: readonly [MonitoredRunState<Stage>, readonly C[]],\n): readonly [S, readonly C[]] {\n  return [{ ...state, run: slice }, cmds];\n}\n\n/**\n * Re-export the deadline Sub primitives so consumers (and tests) wire one\n * import: `subscribeDeadline` is the `subscribe` cell, `deadlineSub` builds the\n * Sub literal this knob's `subs` emits.\n */\nexport { subscribeDeadline, deadlineSub };\nexport type {\n  DeadlineSub,\n  DeadlineExceeded,\n  SnapshotSavedMsg,\n  SnapshotWriteCmd,\n};\n"]}

package/dist/chunk-WRAA7GVZ.js

@@ -1,209 +0,0 @@
-import { typeOf, indexPath, unionKeys, keyPath } from './chunk-EWJP3YYP.js';
-import { jsx, jsxs } from 'react/jsx-runtime';
-import { useRef, useEffect, useState, useCallback } from 'react';
-
-function MsgLog({ history, className }) {
-  return /* @__PURE__ */ jsx("div", { className: `tea-dt-log${className ? ` ${className}` : ""}`, children: history.map((r, i) => /* @__PURE__ */ jsxs(
-    "div",
-    {
-      className: `tea-dt-row tea-dt-${r.kind ?? "msg"}`,
-      children: [
-        /* @__PURE__ */ jsx("span", { className: "tea-dt-t", children: r.ts }),
-        /* @__PURE__ */ jsx("span", { className: "tea-dt-m", children: r.text })
-      ]
-    },
-    `${r.ts}-${i}`
-  )) });
-}
-
-// src/devtools/state-diff.ts
-function diffState(expected, actual) {
-  const out = [];
-  walk(expected, actual, "state", out);
-  return out;
-}
-function walk(expected, actual, path, out) {
-  if (Object.is(expected, actual)) return;
-  const te = typeOf(expected);
-  const ta = typeOf(actual);
-  if (te === "undefined") {
-    out.push({ path, kind: "added", expected, actual });
-    return;
-  }
-  if (ta === "undefined") {
-    out.push({ path, kind: "removed", expected, actual });
-    return;
-  }
-  if (te !== ta) {
-    out.push({ path, kind: "changed", expected, actual });
-    return;
-  }
-  if (te === "array") {
-    const ae = expected;
-    const aa = actual;
-    const len = Math.max(ae.length, aa.length);
-    for (let i = 0; i < len; i++) {
-      walk(ae[i], aa[i], indexPath(path, i), out);
-    }
-    return;
-  }
-  if (te === "object") {
-    const oe = expected;
-    const oa = actual;
-    for (const key of unionKeys(oe, oa)) {
-      walk(oe[key], oa[key], keyPath(path, key), out);
-    }
-    return;
-  }
-  out.push({ path, kind: "changed", expected, actual });
-}
-function fmtValue(v) {
-  if (v === void 0) return "undefined";
-  if (typeof v === "number" && Number.isNaN(v)) return "NaN";
-  if (typeof v === "bigint") return `${v}n`;
-  if (typeof v === "string") return JSON.stringify(v);
-  if (typeof v === "function" || typeof v === "symbol") return String(v);
-  try {
-    return JSON.stringify(v) ?? String(v);
-  } catch {
-    return String(v);
-  }
-}
-function formatDiff(changes) {
-  return changes.map(formatChange).join("\n");
-}
-function formatChange(c) {
-  switch (c.kind) {
-    case "changed":
-      return `~ ${c.path}: ${fmtValue(c.expected)} \u2192 ${fmtValue(c.actual)}`;
-    case "removed":
-      return `- ${c.path}: ${fmtValue(c.expected)}`;
-    case "added":
-      return `+ ${c.path}: ${fmtValue(c.actual)}`;
-  }
-}
-function changeRow(c) {
-  switch (c.kind) {
-    case "changed":
-      return /* @__PURE__ */ jsxs("div", { className: "tea-dt-diff-row tea-dt-diff-changed", children: [
-        /* @__PURE__ */ jsx("span", { className: "tea-dt-diff-mark", children: "~" }),
-        /* @__PURE__ */ jsx("span", { className: "tea-dt-diff-path", children: c.path }),
-        /* @__PURE__ */ jsx("span", { className: "tea-dt-diff-old", children: fmtValue(c.expected) }),
-        /* @__PURE__ */ jsx("span", { className: "tea-dt-diff-arrow", children: "\u2192" }),
-        /* @__PURE__ */ jsx("span", { className: "tea-dt-diff-new", children: fmtValue(c.actual) })
-      ] }, c.path);
-    case "removed":
-      return /* @__PURE__ */ jsxs("div", { className: "tea-dt-diff-row tea-dt-diff-removed", children: [
-        /* @__PURE__ */ jsx("span", { className: "tea-dt-diff-mark", children: "-" }),
-        /* @__PURE__ */ jsx("span", { className: "tea-dt-diff-path", children: c.path }),
-        /* @__PURE__ */ jsx("span", { className: "tea-dt-diff-old", children: fmtValue(c.expected) })
-      ] }, c.path);
-    case "added":
-      return /* @__PURE__ */ jsxs("div", { className: "tea-dt-diff-row tea-dt-diff-added", children: [
-        /* @__PURE__ */ jsx("span", { className: "tea-dt-diff-mark", children: "+" }),
-        /* @__PURE__ */ jsx("span", { className: "tea-dt-diff-path", children: c.path }),
-        /* @__PURE__ */ jsx("span", { className: "tea-dt-diff-new", children: fmtValue(c.actual) })
-      ] }, c.path);
-  }
-}
-function StateDiff({ expected, actual, className }) {
-  const changes = diffState(expected, actual);
-  return /* @__PURE__ */ jsx(
-    "div",
-    {
-      className: `tea-dt-diff${className ? ` ${className}` : ""}`,
-      title: changes.length === 0 ? "no changes" : formatDiff(changes),
-      children: changes.length === 0 ? /* @__PURE__ */ jsx("div", { className: "tea-dt-diff-empty", children: "no changes" }) : changes.map(changeRow)
-    }
-  );
-}
-function escapeHtml(s) {
-  return s.replace(
-    /[&<>"]/g,
-    (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]
-  );
-}
-function fmtJson(obj, indent = 0) {
-  if (obj === null) return '<span class="tea-dt-b">null</span>';
-  if (typeof obj === "number") return `<span class="tea-dt-n">${obj}</span>`;
-  if (typeof obj === "boolean") return `<span class="tea-dt-b">${obj}</span>`;
-  if (typeof obj === "string")
-    return `<span class="tea-dt-s">"${escapeHtml(obj)}"</span>`;
-  if (Array.isArray(obj)) {
-    if (obj.length === 0) return '<span class="tea-dt-br">[]</span>';
-    return '<span class="tea-dt-br">[</span>' + obj.map((v) => fmtJson(v, indent + 1)).join('<span class="tea-dt-br">, </span>') + '<span class="tea-dt-br">]</span>';
-  }
-  if (typeof obj === "object") {
-    const keys = Object.keys(obj);
-    if (keys.length === 0) return '<span class="tea-dt-br">{}</span>';
-    const pad = "&nbsp;&nbsp;".repeat(indent + 1);
-    const lines = keys.map((k, i) => {
-      const v = obj[k];
-      const comma = i < keys.length - 1 ? '<span class="tea-dt-br">,</span>' : "";
-      return `${pad}<span class="tea-dt-k">${escapeHtml(k)}</span><span class="tea-dt-br">:</span> ${fmtJson(v, indent + 1)}${comma}`;
-    });
-    return [
-      '<span class="tea-dt-br">{</span>',
-      ...lines,
-      `${"&nbsp;&nbsp;".repeat(indent)}<span class="tea-dt-br">}</span>`
-    ].join("<br/>");
-  }
-  return escapeHtml(String(obj));
-}
-function StateInspector({
-  state,
-  flashKey,
-  className
-}) {
-  const boxRef = useRef(null);
-  useEffect(() => {
-    if (flashKey === void 0 || !boxRef.current) return;
-    boxRef.current.classList.remove("tea-dt-flash");
-    void boxRef.current.offsetWidth;
-    boxRef.current.classList.add("tea-dt-flash");
-  }, [flashKey]);
-  return /* @__PURE__ */ jsx(
-    "div",
-    {
-      ref: boxRef,
-      className: `tea-dt-state${className ? ` ${className}` : ""}`,
-      children: /* @__PURE__ */ jsx(
-        "div",
-        {
-          className: "tea-dt-json",
-          dangerouslySetInnerHTML: { __html: fmtJson(state) }
-        }
-      )
-    }
-  );
-}
-function nowTs() {
-  return (/* @__PURE__ */ new Date()).toLocaleTimeString("en-GB", { hour12: false }).slice(3);
-}
-function useMsgHistory(dispatch, opts = {}) {
-  const max = opts.max ?? 60;
-  const now = opts.now ?? nowTs;
-  const derive = opts.derive ?? ((msg) => {
-    const tag = msg && typeof msg === "object" && "type" in msg ? String(msg.type) : String(msg);
-    return { ts: now(), kind: "msg", text: tag };
-  });
-  const [history, setHistory] = useState([]);
-  const dispatchRef = useRef(dispatch);
-  dispatchRef.current = dispatch;
-  const deriveRef = useRef(derive);
-  deriveRef.current = derive;
-  const wrapped = useCallback(
-    (msg) => {
-      const entry = deriveRef.current(msg);
-      setHistory((prev) => [entry, ...prev].slice(0, max));
-      void dispatchRef.current(msg);
-    },
-    [max]
-  );
-  const clear = useCallback(() => setHistory([]), []);
-  return [history, wrapped, clear];
-}
-
-export { MsgLog, StateDiff, StateInspector, diffState, formatDiff, useMsgHistory };
-//# sourceMappingURL=chunk-WRAA7GVZ.js.map
-//# sourceMappingURL=chunk-WRAA7GVZ.js.map