@demlik/tea 0.1.0 → 0.1.1

package/dist/token-refresh/index.d.ts

@@ -0,0 +1,215 @@
+import { C as Cmd, I as Interpret } from '../core-CymXZCeY.js';
+import { M as MsgType } from '../protocol-B5YmJr0d.js';
+
+/**
+ * @demlik/tea/token-refresh — a credential's lifecycle as pure state + verbs,
+ * with the actual token fetch deferred to a single injected port.
+ *
+ * This is the L1 brick `authed-call` (#10 in the composition specs) stacks on:
+ * a token slice `{ token, stale }` plus pure transitions that decide *when* a
+ * credential must be re-minted, and one `handlers(ports)` splice that performs
+ * the re-mint. It follows the uniform knob contract every composition wears —
+ * `createTokenRefresh(config) → { init, <verbs>, handlers }` — so a consumer
+ * spreads ~3 hooks into their machine instead of hand-wiring the refresh dance.
+ *
+ * It is a LEAF module in the same mold as `@demlik/tea/retry-backoff`: it
+ * depends only on the core (`../index`), never on a sibling brick. The two
+ * non-negotiables of every knob hold here by construction:
+ *
+ *   - **Durable** — the token slice is plain JSON-serializable data, so it
+ *     survives a Durable Object eviction / page reload. A rehydrated machine
+ *     resumes knowing exactly which token it holds and whether it is stale.
+ *   - **Replayable** — every transition is a pure verb returning
+ *     `readonly [State, Cmd[]]`. No verb reads the wall clock or performs I/O,
+ *     so `replay` reconstructs the slice exactly. Time enters ONLY as an `at`
+ *     parameter the caller stamps; the network fetch enters ONLY at the
+ *     `handlers` boundary. This keeps the substrate's purity invariants intact
+ *     (invariant 2: pure transitions; invariant 4: I/O is an effect, not a
+ *     reducer body).
+ *
+ * ## The staleness model — two independent reasons to refresh
+ *
+ * A token becomes unusable for two unrelated reasons, and the slice tracks both
+ * without conflating them:
+ *
+ *   1. **Expiry** — the token has a known `expiresAt` (epoch ms). It is "near
+ *      expiry" once `at >= expiresAt - skewMs`. The `skewMs` skew refreshes
+ *      *ahead* of the hard deadline so an in-flight call never races a token
+ *      that expires mid-request. This is the proactive, time-driven reason and
+ *      is computed purely from the injected `at` — no clock in the verb.
+ *
+ *   2. **Server rejection (401)** — the server rejected a request the client
+ *      believed was still valid (clock skew, a server-side revocation, an early
+ *      rotation). `on401` flips a `stale` flag regardless of `expiresAt`. This
+ *      is the reactive reason: the client's belief about validity was wrong, so
+ *      the next `needsRefresh` returns true even though the clock says the
+ *      token is fine.
+ *
+ * `needsRefresh` is the union of the two (plus "no token at all"). One source
+ * of truth for "should I fetch a fresh credential before the next call?", read
+ * by the consumer's reducer at the call boundary.
+ *
+ * Typical wiring (inside a consumer machine):
+ *
+ *   const tr = createTokenRefresh({ skewMs: 30_000 });
+ *
+ *   // in init:
+ *   init: (loaded) => [loaded ?? { auth: tr.init() }, Cmd.none],
+ *
+ *   // in a reducer cell that is about to make an authed call:
+ *   before_call: (s, msg) => {
+ *     const [auth, cmds] = tr.ensureFresh(s.auth, msg.at);
+ *     return [{ ...s, auth }, cmds]; // emits a refresh Cmd iff a refresh is due
+ *   },
+ *
+ *   // on a 401 from a guarded call:
+ *   got_401: (s) => [{ ...s, auth: tr.on401(s.auth) }, []],
+ *
+ *   // when the refresh port resolves:
+ *   token_refreshed: (s, msg) => [{ ...s, auth: tr.refreshed(s.auth, msg.token) }, []],
+ *
+ *   // splice the I/O:
+ *   interpret: { ...tr.handlers({ refresh: () => mySdk.mintToken() }) },
+ *
+ * NOT a substrate primitive: from `../index` it reuses only the `Cmd` /
+ * `Interpret` types and the `tryInterpret` Railway helper (a runtime function,
+ * not a type) that every effectful brick uses — and no sibling brick. It is a
+ * leaf utility consumers reach via the `@demlik/tea/token-refresh` subpath.
+ */
+
+/**
+ * A minted credential: the opaque `value` to send on the wire, and the absolute
+ * `expiresAt` (epoch milliseconds — the `Date.now()` scale) the issuer stamped
+ * it with. Both fields are plain data so a `Token` is trivially serializable
+ * into a consumer's `Store<S>`.
+ *
+ * `value` is `string` because that is the universal shape of a bearer token /
+ * API key / session cookie on the wire. A consumer whose refresh port yields a
+ * richer object can JSON-encode it into `value`, or keep this module's slice as
+ * the "is it fresh?" gate and hold the richer object elsewhere in their Model.
+ */
+interface Token {
+    /** The opaque credential to present on each request (bearer token, API key). */
+    readonly value: string;
+    /** Absolute expiry instant, epoch milliseconds. The `Date.now()` scale. */
+    readonly expiresAt: number;
+}
+/**
+ * Pure configuration — the knob's only field. Carries no mutable state;
+ * `TokenState` does. One config is shared across all the refreshes of one
+ * logical credential (often a module-scope const).
+ */
+interface TokenRefreshConfig {
+    /**
+     * Refresh-ahead skew, in milliseconds. A token is treated as needing a
+     * refresh once `at >= expiresAt - skewMs`, i.e. `skewMs` BEFORE its hard
+     * expiry. This buys headroom so a call that starts just under the wire never
+     * races a token that lapses mid-flight, and absorbs small client/server clock
+     * disagreement. `0` means "refresh exactly at expiry"; a negative value is
+     * clamped to `0` (a skew that pushes the trigger past expiry is meaningless).
+     *
+     * @default 0
+     */
+    readonly skewMs?: number;
+}
+/**
+ * The token slice this knob owns — the Model field a consumer spreads in via
+ * `init()`. A two-field record rather than a phase union because the two
+ * dimensions are orthogonal: a token can be present-and-fresh, present-but-stale
+ * (a 401 came back), absent, or absent-and-stale (cleared after a failed
+ * refresh). Every combination is meaningful, so neither field implies the
+ * other's value and a discriminated union would only manufacture impossible
+ * arms.
+ *
+ *   - `token` — the currently held credential, or `null` when none has been
+ *     minted yet (fresh boot) or the last refresh failed.
+ *   - `stale` — set by `on401` when the server rejected a request the client
+ *     believed valid. Forces the next `needsRefresh` to true regardless of
+ *     `expiresAt`; cleared by `refreshed` once a new credential lands.
+ *
+ * Both fields `readonly` so the whole slice threads safely through a pure
+ * reducer and serializes into a `Store<S>`.
+ */
+interface TokenState {
+    /** The held credential, or `null` if none is available (boot / failed refresh). */
+    readonly token: Token | null;
+    /** Whether a 401 has marked the held token unusable ahead of its `expiresAt`. */
+    readonly stale: boolean;
+}
+/**
+ * The starting slice: no token held, not stale. The first `needsRefresh` after
+ * this returns `true` (no token), so a consumer's first guarded call mints a
+ * credential before going out.
+ */
+declare function initTokenRefresh(): TokenState;
+/**
+ * The Cmd this knob emits to ask the runtime to mint a fresh token. Plain data
+ * (no closure — invariant 1) carrying nothing: the refresh port takes no input,
+ * and the slice the result installs is read off the follow-up Msg, not this
+ * Cmd. The consumer unions this into their machine's Cmd type and lets
+ * `handlers` interpret it.
+ */
+interface RefreshTokenCmd extends Cmd<"refresh_token"> {
+}
+/** Construct a `refresh_token` Cmd. */
+declare function refreshTokenCmd(): RefreshTokenCmd;
+/**
+ * The Msg the refresh port dispatches on success — carries the freshly minted
+ * `Token`. The consumer unions this into their Msg type and handles it by
+ * folding `refreshed(state, msg.token)` into the slice.
+ */
+interface TokenRefreshedMsg {
+    readonly type: typeof MsgType.TokenRefreshed;
+    readonly token: Token;
+}
+/** Construct a `token_refreshed` Msg carrying the new token. */
+declare function tokenRefreshedMsg(token: Token): TokenRefreshedMsg;
+/**
+ * The Msg the refresh port dispatches on failure — carries the rejection so the
+ * consumer's reducer can decide whether to back off, surface an error, or give
+ * up (errors are data: it is dispatched, never swallowed). The slice itself is
+ * left untouched by a failed refresh — the held token (if any) stays held and
+ * stale stays set, so the consumer can retry; clearing it is the consumer's
+ * policy, expressed in their reducer.
+ */
+interface TokenRefreshFailedMsg {
+    readonly type: typeof MsgType.TokenRefreshFailed;
+    readonly error: unknown;
+}
+/** Construct a `token_refresh_failed` Msg carrying the rejection. */
+declare function tokenRefreshFailedMsg(error: unknown): TokenRefreshFailedMsg;
+/** The two Msgs the refresh port can produce. Union for a consumer's Msg type. */
+type TokenRefreshMsg = TokenRefreshedMsg | TokenRefreshFailedMsg;
+/** The ports this knob's `handlers` splice needs — the single refresh DI seam. */
+interface TokenRefreshPorts {
+    /**
+     * Mint a fresh credential. Called ONLY from the `refresh_token` interpret
+     * handler — never from a verb — so the network I/O and any clock the issuer
+     * reads stay at the effect boundary. May reject; the rejection is routed to
+     * `token_refresh_failed` (errors are data), never thrown into the runtime.
+     */
+    readonly refresh: () => Promise<Token>;
+}
+/**
+ * The knob: hand it a config, get back the slice initializer, the pure verbs,
+ * and the `handlers` splice. Mirrors every L2 composition's uniform contract so
+ * the call sites read identically across bricks.
+ *
+ * @example
+ *   const tr = createTokenRefresh({ skewMs: 30_000 });
+ *   const s0 = tr.init();
+ *   const [s1, cmds] = tr.ensureFresh(s0, Date.now()); // cmds = [refreshTokenCmd()]
+ */
+declare function createTokenRefresh(config?: TokenRefreshConfig): {
+    /** The slice initializer — spread into the consumer's `init`. */
+    init: typeof initTokenRefresh;
+    needsRefresh: (state: TokenState, at: number) => boolean;
+    on401: (state: TokenState) => TokenState;
+    refreshed: (state: TokenState, token: Token) => TokenState;
+    ensureFresh: (state: TokenState, at: number) => readonly [TokenState, readonly Cmd[]];
+    handlers: (ports: TokenRefreshPorts) => Interpret<TokenRefreshMsg, RefreshTokenCmd, unknown>;
+};
+/** The shape `createTokenRefresh` returns — useful for typing a held knob. */
+type TokenRefresh = ReturnType<typeof createTokenRefresh>;
+
+export { type RefreshTokenCmd, type Token, type TokenRefresh, type TokenRefreshConfig, type TokenRefreshFailedMsg, type TokenRefreshMsg, type TokenRefreshPorts, type TokenRefreshedMsg, type TokenState, createTokenRefresh, initTokenRefresh, refreshTokenCmd, tokenRefreshFailedMsg, tokenRefreshedMsg };

package/dist/token-refresh/index.js

@@ -0,0 +1,6 @@
+export { createTokenRefresh, initTokenRefresh, refreshTokenCmd, tokenRefreshFailedMsg, tokenRefreshedMsg } from '../chunk-FH5RUIIL.js';
+import '../chunk-JELSZN25.js';
+import '../chunk-2WZHS4P2.js';
+import '../chunk-BNJYE4AU.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/token-refresh/index.js.map

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

package/dist/trace-replay/index.d.ts

@@ -1,5 +1,6 @@
-import { Cmd, Sub, Machine } from '../index.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-CymXZCeY.js';
 import { Trace } from '../recorder/index.js';
+import '../index.js';
 
 /**
  * The outcome of {@link replayTrace}.
@@ -48,5 +49,13 @@ interface ReplayResult<S> {
 declare function replayTrace<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, trace: Trace<S, M>, ctx: Ctx): ReplayResult<S>;
+/**
+ * Order-insensitive structural deep-equality — the single comparator this
+ * package owns, exposed so consumers (e.g. `@demlik/tea/parity`'s `diff`)
+ * reuse it rather than adding a second deep-compare. `true` iff `a` and `b`
+ * are structurally equal under {@link firstDivergence}'s walk (object keys
+ * compared order-insensitively, arrays index-by-index).
+ */
+declare function deepEqual(a: unknown, b: unknown): boolean;
 
-export { type ReplayResult, replayTrace };
+export { type ReplayResult, deepEqual, replayTrace };

package/dist/trace-replay/index.js

@@ -1,57 +1,5 @@
-import { replay } from '../chunk-CMG2KMWX.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 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], `${path}[${i}]`);
-      if (d !== null) return d;
-    }
-    return null;
-  }
-  if (te === "object") {
-    const oe = expected;
-    const oa = actual;
-    const keys = [.../* @__PURE__ */ new Set([...Object.keys(oe), ...Object.keys(oa)])].sort();
-    for (const key of keys) {
-      const d = firstDivergence(oe[key], oa[key], `${path}.${key}`);
-      if (d !== null) return d;
-    }
-    return null;
-  }
-  return { path, expected, actual };
-}
-function typeOf(v) {
-  if (v === null) return "null";
-  if (v === void 0) return "undefined";
-  if (Array.isArray(v)) return "array";
-  if (typeof v === "object") return "object";
-  return "primitive";
-}
-
-export { replayTrace };
+export { deepEqual, replayTrace } from '../chunk-EDGDR5XX.js';
+import '../chunk-2WZHS4P2.js';
+import '../chunk-BNJYE4AU.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/trace-replay/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/trace-replay/index.ts"],"names":[],"mappings":"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","file":"index.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\";\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// === self-contained 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// 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], `${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    // Union of keys, sorted 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    const keys = [...new Set([...Object.keys(oe), ...Object.keys(oa)])].sort();\n    for (const key of keys) {\n      const d = firstDivergence(oe[key], oa[key], `${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\n/** Coarse type tag used by the divergence walk to decide how to recurse. */\nfunction typeOf(\n  v: unknown,\n): \"null\" | \"undefined\" | \"array\" | \"object\" | \"primitive\" {\n  if (v === null) return \"null\";\n  if (v === undefined) return \"undefined\";\n  if (Array.isArray(v)) return \"array\";\n  if (typeof v === \"object\") return \"object\";\n  return \"primitive\";\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/{types-CwBC5wMn.d.ts → types-N9LZbdnr.d.ts}

@@ -1,4 +1,4 @@
-import { Sub } from './index.js';
+import { S as Sub } from './core-CymXZCeY.js';
 
 type SubscribeHandler<S extends Sub, M, Ctx> = (sub: S, ctx: Ctx, dispatch: (msg: M) => void) => () => void;
 

package/dist/with-deadline/index.d.ts

@@ -0,0 +1,196 @@
+import { S as Sub, C as Cmd, M as Machine } from '../core-CymXZCeY.js';
+
+/**
+ * @demlik/tea/with-deadline — auto-fail a wrapped machine at T+N, re-arm on
+ * progress. A **pure function over machine data**: `withDeadline(base, config)`
+ * takes any `Machine<S, M, C, U, Ctx>` and returns a NEW `Machine` over the
+ * composed Model `{ base, $deadline }`. You `run()` / `replay()` the result
+ * exactly like any other machine — there is no new runtime, no privileged
+ * interception path.
+ *
+ * ## What it does
+ *
+ * The wrapper watches the base Msg stream. While the deadline is `armed`, a
+ * RELATIVE timeout Sub counts down `config.ms`. Every base Msg the
+ * `config.progress` predicate accepts (default: every base Msg) is treated as
+ * activity: the wrapper bumps a numeric `seq`, which CHANGES the timer Sub's id,
+ * so the substrate's reconcile pass retires the old countdown and starts a fresh
+ * one — "re-arm on progress". If `config.ms` elapses with NO accepted progress,
+ * the timeout Sub dispatches `$deadline:exceeded`; the merged `update` folds it
+ * by flipping `phase` to `exceeded`, and from then on `subscriptions` returns no
+ * timer (the machine has auto-failed). The expiry is a slice transition visible
+ * in the Msg log — the auto-fail is never an off-ledger side effect.
+ *
+ * This is an OBSERVE-ONLY wrapper in the same sense as `withTelemetry`: it never
+ * intercepts a base Cmd and never gates a base Msg. `state.base` after wrapping
+ * is BYTE-IDENTICAL to running the base alone, so the shared
+ * `assertWrapperFaithful` gate passes with the deadline bolted on.
+ *
+ * ## The 5 rules it satisfies (from the wrapper-tier contract)
+ *
+ *   1. **Named, serializable slice.** Wrapper state lives at `model.$deadline`,
+ *      a plain `{ phase, seq }` — JSON-serializable, never a closure. There is
+ *      NO absolute timestamp in the slice: the clock is never read in `update`.
+ *   2. **Retag-and-re-emit, never swallow.** The merged `update` runs the base
+ *      reducer, passes its Cmds through UNCHANGED, and APPENDS its own
+ *      `$deadline:rearm` / `$deadline:expire` decision Cmd. No base Cmd ever
+ *      vanishes; nothing is gated.
+ *   3. **Every decision is a Msg/Cmd.** Re-arm is a `$deadline:rearm` Cmd; the
+ *      auto-fail expiry is the `$deadline:exceeded` Msg the Sub delivers, folded
+ *      into the slice and echoed as a `$deadline:expire` Cmd. "Why did this
+ *      fire" is answerable from reducer + log alone.
+ *   4. **Subs merge by id.** `subscriptions = [...base, ...deadlineSubs]`; the
+ *      timeout id is `$deadline:timeout:{seq}`, so a progress bump (seq+1)
+ *      yields a NEW id — the substrate retires the old timer and arms a fresh
+ *      one. When `exceeded`, no deadline sub is returned.
+ *   5. **Clock out of update.** The countdown is a relative-timeout Sub; the
+ *      clock is read at subscribe time inside the Sub (`setTimeout`), NEVER in a
+ *      verb. The slice carries `seq`, not a deadline timestamp.
+ *
+ * ## Typical wiring
+ *
+ *   const guarded = withDeadline(baseMachine, {
+ *     ms: 900_000, // auto-fail after 15 minutes of inactivity
+ *     progress: (msg) => msg.type !== "heartbeat", // heartbeats don't re-arm
+ *   });
+ *   const runtime = run(guarded, { ctx: baseCtx });
+ */
+
+/**
+ * The wrapper's Model slice. `phase` is the lifecycle (`armed` while the
+ * countdown runs, `exceeded` once the deadline fired); `seq` is the monotonic
+ * re-arm counter that keys the timer Sub's id so each accepted progress Msg
+ * retires the old timer and starts a fresh one.
+ *
+ * PURE and SERIALIZABLE: there is deliberately NO absolute timestamp here. A
+ * deadline timestamp would force the merged `update` to read the wall clock to
+ * compute it, which the conformance gate (property 2 — two replays under
+ * distinct ambient clocks) is built to catch. Instead, the timer arms a fresh
+ * full `ms` countdown per generation; no remaining-delay computation and no
+ * clock read occur in the slice or `update` — the only clock is `setTimeout`
+ * inside the Sub.
+ */
+interface DeadlineSlice {
+    /** `armed` while the countdown is live; `exceeded` once the deadline fired. */
+    readonly phase: "armed" | "exceeded";
+    /**
+     * Monotonic re-arm counter. Starts at 0; each accepted progress Msg (while
+     * armed) bumps it by one. Folds into the timer Sub's id, so a bump = a new id
+     * = the substrate retires the old timer and arms a fresh `ms` countdown.
+     */
+    readonly seq: number;
+}
+/**
+ * The composed Model. The base machine's state is nested under `base`; the
+ * wrapper's state lives in the NAMED `$deadline` slice — never hidden in a
+ * closure. Both fields are plain data, so the whole composed Model round-trips
+ * through `JSON.parse(JSON.stringify(...))` iff the base state does.
+ */
+interface DeadlineModel<S> {
+    readonly base: S;
+    readonly $deadline: DeadlineSlice;
+}
+/**
+ * The relative-timeout Sub the wrapper arms while `phase === "armed"`. `delayMs`
+ * is the window `config.ms`; the id is `$deadline:timeout:{seq}`, so each
+ * progress bump produces a distinct id and the reconcile pass churns the timer.
+ * Same `delayMs`-on-the-Sub shape `fromTimeout` consumes.
+ */
+type DeadlineTimeoutSub = Sub<"$deadline:timeout"> & {
+    readonly delayMs: number;
+};
+/**
+ * The Msg the timeout Sub dispatches when `config.ms` elapses with no accepted
+ * progress. `seq` echoes the re-arm generation the timer was armed against, so a
+ * stale timer's Msg (one whose id was already retired) is identifiable; the
+ * merged `update` only honors it when it matches the current slice `seq`.
+ */
+interface DeadlineExceededMsg {
+    readonly type: "$deadline:exceeded";
+    /** The re-arm generation this timer was armed against. */
+    readonly seq: number;
+}
+/**
+ * Construct the deadline-exceeded Msg. Exported so the subscribe cell and tests
+ * share one constructor rather than two literals that can drift.
+ */
+declare function deadlineExceededMsg(seq: number): DeadlineExceededMsg;
+/**
+ * The fire-and-forget decision Cmd the merged `update` appends on every
+ * transition, so the wrapper's choice is visible in the replayed Cmd log
+ * (rule 3) — `rearm` when an accepted progress Msg bumped `seq`, `expire` when
+ * the deadline-exceeded Msg flipped the phase, `idle` otherwise (a non-progress
+ * Msg, or a Msg after the machine already auto-failed). Plain data; its
+ * interpret handler is a no-op (the decision is the Cmd's presence in the log,
+ * not a side effect).
+ */
+type DeadlineDecisionCmd = Cmd<"$deadline:decision"> & {
+    readonly decision: "rearm" | "expire" | "idle";
+    /** The slice `seq` AFTER this transition (the re-arm generation now armed). */
+    readonly seq: number;
+};
+/**
+ * A predicate over a Msg that decides whether it re-arms the deadline.
+ *
+ * The argument is `Readonly<M>` and the result is `boolean`: this is the
+ * STRONGEST purity TS can express here. `Readonly<M>` removes the most common
+ * impurity at compile time — the predicate cannot reassign the Msg's own
+ * fields — and `boolean` pins the return so a side-effecting `(msg) => { … }`
+ * with an implicit `undefined`/`void` return is rejected.
+ *
+ * What the type system CANNOT encode (TS has no effect tracking): observational
+ * purity. A body that reads `Date.now()`, calls `Math.random()`, performs IO,
+ * or closes over and mutates external state still type-checks. Those remain a
+ * CONVENTION enforced by review, not the compiler — the predicate runs inside
+ * the pure merged `update` (invariant 2), so it must be a pure function of the
+ * Msg alone: no clock, no RNG, no IO, no captured mutable state.
+ */
+type ProgressPredicate<M extends {
+    type: string;
+}> = (msg: Readonly<M>) => boolean;
+/**
+ * The deadline knob. `ms` is the inactivity window; `progress` is an OPTIONAL
+ * predicate picking which base Msgs count as activity (default: EVERY base Msg
+ * re-arms). The predicate runs INSIDE the pure merged `update`, so it must be a
+ * pure function of the Msg — see {@link ProgressPredicate} for what the type
+ * enforces vs. what stays a convention.
+ */
+interface DeadlineConfig<M extends {
+    type: string;
+}> {
+    /** The inactivity window in milliseconds. Auto-fail after `ms` with no progress. */
+    readonly ms: number;
+    /**
+     * Predicate picking which base Msgs re-arm the timer. Default: every base Msg
+     * counts as progress. Pure — a function of the Msg alone (see
+     * {@link ProgressPredicate}).
+     */
+    readonly progress?: ProgressPredicate<M>;
+}
+/**
+ * Wrap `base` with an inactivity deadline. Returns a NEW `Machine` over the
+ * composed Model `{ base, $deadline }`, with the base's Msgs/Cmds/Subs extended
+ * by the wrapper's own (`$deadline:exceeded` Msg, `$deadline:decision` Cmd,
+ * `$deadline:timeout` Sub).
+ *
+ * The composed machine:
+ *   - `init` rehydrates the base (honoring the `[loaded, []]` contract) and
+ *     seeds `$deadline: { phase: "armed", seq: 0 }`. Base init Cmds pass
+ *     through unchanged.
+ *   - `update` (Reducer form) runs the base reducer for base Msgs — base Cmds
+ *     pass through UNCHANGED — and on an accepted progress Msg bumps `seq`
+ *     (re-arm). The `$deadline:exceeded` Msg cell flips `phase` to `exceeded`.
+ *     Every transition appends a `$deadline:decision` marker Cmd.
+ *   - `subscriptions` is the base's, plus a `$deadline:timeout` Sub keyed on
+ *     `seq` while `phase === "armed"`.
+ *   - `subscribe` is the base's, plus the `$deadline:timeout` cell.
+ *   - `interpret` is the base's, plus a no-op `$deadline:decision` handler.
+ *
+ * @param base   any `Machine<S, M, C, U, Ctx>`.
+ * @param config the deadline knob (`ms` window + optional `progress` predicate).
+ */
+declare function withDeadline<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(base: Machine<S, M, C, U, Ctx>, config: DeadlineConfig<M>): Machine<DeadlineModel<S>, M | DeadlineExceededMsg, C | DeadlineDecisionCmd, U | DeadlineTimeoutSub, Ctx>;
+
+export { type DeadlineConfig, type DeadlineDecisionCmd, type DeadlineExceededMsg, type DeadlineModel, type DeadlineSlice, type DeadlineTimeoutSub, type ProgressPredicate, deadlineExceededMsg, withDeadline };

package/dist/with-deadline/index.js

@@ -0,0 +1,130 @@
+import { fromTimeout } from '../chunk-2YFLOCWX.js';
+import '../chunk-2WZHS4P2.js';
+import { formOf, subId } from '../chunk-BNJYE4AU.js';
+
+// src/with-deadline/index.ts
+function deadlineExceededMsg(seq) {
+  return { type: "$deadline:exceeded", seq };
+}
+function runBaseUpdate(update, form, state, msg) {
+  if (form === "reducer") {
+    const record = update;
+    return record[msg.type](state, msg);
+  }
+  const table = update;
+  const stateKey = state.type;
+  return table[stateKey][msg.type](state, msg);
+}
+function deadlineMsgKeys(update, form) {
+  const keys = Object.keys(update);
+  const firstKey = keys[0];
+  if (firstKey === void 0) return [];
+  if (form === "reducer") return keys;
+  const firstValue = update[firstKey];
+  return Object.keys(firstValue);
+}
+function withDeadline(base, config) {
+  const windowMs = config.ms;
+  const isProgress = config.progress;
+  const update = {};
+  const baseForm = formOf(base);
+  const baseMsgKeys = deadlineMsgKeys(base.update, baseForm);
+  for (const key of baseMsgKeys) {
+    if (key.startsWith("$deadline:")) {
+      throw new Error(
+        `withDeadline: the base machine declares a reserved "${key}" update cell \u2014 the wrapper owns the "$deadline:" Msg namespace. Rename the base Msg.`
+      );
+    }
+  }
+  for (const key of baseMsgKeys) {
+    update[key] = (state, msg) => {
+      const [nextBase, baseCmds] = runBaseUpdate(
+        base.update,
+        baseForm,
+        state.base,
+        msg
+      );
+      const armed = state.$deadline.phase === "armed";
+      const counts = armed && (isProgress === void 0 || isProgress(msg));
+      const $deadline = counts ? { phase: "armed", seq: state.$deadline.seq + 1 } : state.$deadline;
+      const next = { base: nextBase, $deadline };
+      const decision = {
+        type: "$deadline:decision",
+        decision: counts ? "rearm" : "idle",
+        seq: $deadline.seq
+      };
+      return [next, [...baseCmds, decision]];
+    };
+  }
+  update["$deadline:exceeded"] = (state, msg) => {
+    const m = msg;
+    const fires = state.$deadline.phase === "armed" && m.seq === state.$deadline.seq;
+    const $deadline = fires ? { phase: "exceeded", seq: state.$deadline.seq } : state.$deadline;
+    const next = { base: state.base, $deadline };
+    const decision = {
+      type: "$deadline:decision",
+      decision: fires ? "expire" : "idle",
+      seq: $deadline.seq
+    };
+    return [next, [decision]];
+  };
+  const baseInterpret = base.interpret ?? {};
+  if (Object.hasOwn(baseInterpret, "$deadline:decision")) {
+    throw new Error(
+      'withDeadline: the base machine declares a reserved "$deadline:decision" interpret handler \u2014 the wrapper owns the "$deadline:" Cmd namespace. Rename the base handler.'
+    );
+  }
+  const interpret = {
+    ...baseInterpret,
+    "$deadline:decision": async () => {
+    }
+  };
+  const baseSubscriptions = base.subscriptions;
+  const subscriptions = (state) => {
+    const baseSubs = baseSubscriptions ? baseSubscriptions(state.base) : [];
+    if (state.$deadline.phase !== "armed") return baseSubs;
+    const timeout = {
+      id: subId(`$deadline:timeout:${state.$deadline.seq}`),
+      type: "$deadline:timeout",
+      delayMs: windowMs
+    };
+    return [...baseSubs, timeout];
+  };
+  const baseSubscribe = base.subscribe ?? {};
+  if (Object.hasOwn(baseSubscribe, "$deadline:timeout")) {
+    throw new Error(
+      'withDeadline: the base machine declares a reserved "$deadline:timeout" subscribe handler \u2014 the wrapper owns the "$deadline:" Sub namespace. Rename the base handler.'
+    );
+  }
+  const timeoutCell = fromTimeout(
+    (sub) => {
+      const seq = Number(sub.id.slice(sub.id.lastIndexOf(":") + 1));
+      return deadlineExceededMsg(seq);
+    }
+  );
+  const subscribe = {
+    ...baseSubscribe,
+    "$deadline:timeout": timeoutCell
+  };
+  return {
+    init: (loaded, ctx) => {
+      if (loaded !== null) {
+        return [loaded, []];
+      }
+      const [base0, cmds] = base.init(null, ctx);
+      const model = {
+        base: base0,
+        $deadline: { phase: "armed", seq: 0 }
+      };
+      return [model, cmds];
+    },
+    update,
+    subscriptions,
+    subscribe,
+    interpret
+  };
+}
+
+export { deadlineExceededMsg, withDeadline };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map