@demlik/tea 0.16.0 → 0.18.0

package/dist/resilience/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/internal/resilience/token-refresh/index.ts","../../src/internal/resilience/authed-call/index.ts","../../src/internal/resilience/retry-to-success/index.ts"],"names":["deadlines"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * internal/resilience/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 `Cmd.define`d Cmd (`refresh_token`)\n * that asks for the re-mint. You write that Cmd's handler in your engine's\n * style (ADR 0021); the knob ships no I/O.\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 in the\n *     `refresh_token` handler you write. 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 lands (the engine mints `refresh_token_ok`):\n *   refresh_token_ok: (s, msg) => [{ ...s, auth: tr.refreshed(s.auth, msg.value) }, []],\n *\n *   // and where the machine runs, the handler you write for the Cmd:\n *   run(machine, {\n *     interpret: {\n *       refresh_token: async (_cmd, { ok, err }) => {\n *         try { return ok(await mySdk.mintToken()); }\n *         catch (cause) { return err({ _tag: \"token_refresh_failed\", cause }); }\n *       },\n *     },\n *   });\n *\n * NOT a substrate primitive: from `../index` it reuses only `Cmd.define` — and\n * no sibling brick. It is a leaf utility internal to the package\n * (`src/internal/resilience/`, #46).\n */\n\nimport {\n  Cmd,\n  type CmdOf,\n  type SettledErr,\n  type SettledOk,\n  type TaggedError,\n} from \"../../../index\";\nimport { unchecked } from \"../../schema\";\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 takes no input, and\n * the slice the result installs is read off the settled Msg, not this Cmd.\n * List it in the machine's `cmds`; its handler returns `ok(token)` or\n * `err({ _tag: \"token_refresh_failed\", … })`, and the engine mints\n * `refresh_token_ok` / `refresh_token_err`.\n */\nexport const refreshToken = Cmd.define(\"refresh_token\", {\n  input: unchecked<Record<string, never>>(),\n  ok: unchecked<Token>(),\n  err: [\"token_refresh_failed\"],\n});\nexport type RefreshTokenCmd = CmdOf<typeof refreshToken>;\n\n/** Construct a `refresh_token` Cmd. */\nexport function refreshTokenCmd(): RefreshTokenCmd {\n  return refreshToken({});\n}\n\n/**\n * The Msg the engine mints when the `refresh_token` handler returns\n * `ok(token)`: `value` is the freshly minted `Token`. Fold it with\n * `refreshed(state, msg.value)`.\n */\nexport type TokenRefreshedMsg = SettledOk<\n  \"refresh_token\",\n  RefreshTokenCmd,\n  Token\n>;\n\n/**\n * The Msg the engine mints when the handler returns\n * `err({ _tag: \"token_refresh_failed\", … })` — errors are data, never\n * swallowed. The slice is left untouched by a failed refresh: the held token\n * (if any) stays held and stale stays set, so the consumer can retry; clearing\n * it is the consumer's policy, expressed in their reducer.\n */\nexport type TokenRefreshFailedMsg = SettledErr<\n  \"refresh_token\",\n  RefreshTokenCmd,\n  TaggedError<\"token_refresh_failed\">\n>;\n\n/** The two Msgs a refresh can settle with. Union for a consumer's Msg type. */\nexport type TokenRefreshMsg = TokenRefreshedMsg | TokenRefreshFailedMsg;\n\n/**\n * The knob: hand it a config, get back the slice initializer and the pure\n * verbs, plus the `refresh_token` Cmd def (`run`) to list in `cmds`.\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 RefreshTokenCmd[]] {\n    if (needsRefresh(state, at)) {\n      return [state, [refreshTokenCmd()]];\n    }\n    return [state, []];\n  }\n\n  return {\n    /** The `refresh_token` Cmd def — list it in the machine's `cmds`. */\n    run: refreshToken,\n    /** The slice initializer — spread into the consumer's `init`. */\n    init: initTokenRefresh,\n    needsRefresh,\n    on401,\n    refreshed,\n    ensureFresh,\n  };\n}\n\n/** The shape `createTokenRefresh` returns — useful for typing a held knob. */\nexport type TokenRefresh = ReturnType<typeof createTokenRefresh>;\n","/**\n * internal/resilience/authed-call — resilient-call with one extra dimension: a bearer\n * credential that must be minted before a call goes out and re-minted when the\n * server says it is no longer good (a 401). It is composition #10 in the specs:\n * *extends resilient-call; needs the L1 `token-refresh` brick*.\n *\n * The recipe — two existing bricks, stacked, nothing hand-wired:\n *\n *   - `../resilient-call` owns ALL the call resilience: cache → circuit-breaker\n *     → rate-limit → exponential-backoff retry, plus the per-call deadline. This\n *     knob does not re-implement a single line of it. The `attempt` / `succeed`\n *     / `fail` / `onTimer` verbs here are thin delegations that thread the\n *     composed slice's `resilience` field through the resilient-call verb —\n *     `succeed` and `fail` both through its one `settle`. Whatever resilience config a consumer passes flows straight\n *     down — every `ResilientConfig` field is still optional, still \"omit a\n *     brick → omit its gate\".\n *\n *   - `../token-refresh` owns the credential lifecycle: the `{ token, stale }`\n *     slice and the decisions about *when* a token must be refreshed (expiry\n *     skew, or a reactive 401). This knob adds the one verb resilient-call has\n *     no concept of — `on401` — and asks for a fresh token with token-refresh's\n *     `refresh_token` Cmd.\n *\n * So the slice is exactly *resilient-call's slice + token-refresh's slice*:\n *\n *   { resilience: ResilientState<I,R>, auth: TokenState }\n *\n * and the verb set is *resilient-call's four verbs + `on401`*, precisely the\n * spec's \"resilient-call's + `on401(s)` (refresh → retry once)\".\n *\n * ## The 401 dance — \"refresh → retry once\"\n *\n * A 401 is special: it is not a transient failure (backing off and retrying the\n * SAME credential just earns another 401), and it is not a terminal failure (a\n * fresh token usually fixes it). So `on401(s, key, at)` does three things:\n *\n *   1. marks the held token `stale` (via token-refresh's `on401`) and emits a\n *      `refresh_token` Cmd to mint a new one;\n *   2. parks the in-flight call in a per-key `authRetry` budget so that, *once*,\n *      the refresh landing re-issues that call with the new credential;\n *   3. caps that to a SINGLE auth-retry per call. A second 401 on the same call\n *      after we already refreshed and retried does NOT loop — it settles the\n *      call `failed` (errors are data: the failure is recorded, never swallowed\n *      or spun on forever). The budget resets on the next fresh `attempt`.\n *\n * When the refresh resolves, the consumer folds `refreshed` into the auth slice\n * and calls `onRefreshed(s, at)`, which re-attempts every parked call through\n * the resilient gate with the new token in hand.\n *\n * ## The two non-negotiables (canon — inherited from both bricks)\n *\n *   - **Durable** — the slice is `ResilientState` (plain data) + `TokenState`\n *     (plain data) + a plain `Record<string, number>` retry budget. All JSON-\n *     serializable, so it survives a Durable Object eviction / reload.\n *   - **Replayable** — every verb returns `readonly [State, Cmd[]]` and never\n *     reads the wall clock or RNG. Time arrives as an `at` parameter; the RNG\n *     for retry jitter is injected once at `createAuthedCall(config, rng)` and\n *     handed straight to the resilient-call knob. The knob ships no I/O: the\n *     call and the token mint are two `Cmd.define`d Cmds whose handlers you\n *     write (ADR 0021).\n *\n * ## Typical wiring\n *\n *   const ac = createAuthedCall<string, Resp>({\n *     retry: defaultRetryPolicy,\n *     circuit: { threshold: 5, cooldownMs: 30_000 },\n *     deadline: { ms: 5_000 },\n *     skewMs: 30_000,\n *   });\n *\n *   // in the machine:\n *   cmds: [ac.run, ac.refresh],\n *   init: () => [ac.init(), []],\n *   update: {\n *     fetch:   (s, m) => ac.attempt(s, m.key, m.input, m.at),\n *     resilient_run_ok:  (s, m) => ac.succeed(s, m),\n *     resilient_run_err: (s, m) => ac.fail(s, m),\n *     got_401: (s, m) => ac.on401(s, m.key, m.at),\n *     refresh_token_ok: (s, m) => ac.onRefreshed(ac.installToken(s, m.value), m.at),\n *     refresh_token_err: (s) => [s, []],\n *     deadline_exceeded: (s, m) => ac.onTimer(s, m),\n *   },\n *   subs: [{ type: \"timer\", deps: (s) => ac.timer(s) }],\n *\n *   // and where it runs — the two handlers you write:\n *   run(machine, {\n *     interpret: {\n *       resilient_run: async (cmd, { ok, err }) => …,  // the call itself\n *       refresh_token: async (_cmd, { ok, err }) => …, // mint a Token\n *     },\n *   });\n */\n\nimport type { Cmd } from \"../../../index\";\nimport type { MsgType } from \"../../../protocol\";\nimport { without } from \"../../../pure/core\";\nimport type { DeadlineSub } from \"../deadline\";\nimport {\n  createResilientCall,\n  type FailMsg,\n  type ResilientConfig,\n  type ResilientState,\n  type ResilientTimerMsg,\n  type RunCmd,\n  type SucceedMsg,\n} from \"../resilient-call\";\nimport {\n  createTokenRefresh,\n  type RefreshTokenCmd,\n  refreshTokenCmd,\n  type Token,\n  type TokenRefreshConfig,\n  type TokenRefreshMsg,\n  type TokenState,\n} from \"../token-refresh\";\n\n// ===========================================================================\n// Config — the knob. The resilient-call config PLUS token-refresh's skew.\n// ===========================================================================\n\n/**\n * The authed-call knob. It is `ResilientConfig` widened by the token dimension:\n *\n *   - `skewMs` — token-refresh's refresh-ahead skew (optional, defaults to 0).\n *   - every `ResilientConfig` field (`retry` / `circuit` / `rateLimit` /\n *     `cache` / `deadline`) — passed straight through to the resilient-call\n *     knob, each still optional, each still \"omit a brick → omit its gate\".\n *\n * The token mint is not on the config: it is the `refresh_token` Cmd, and its\n * handler is yours.\n */\nexport type AuthedConfig = ResilientConfig & TokenRefreshConfig;\n\n// ===========================================================================\n// Slice — resilient-call's slice + token-refresh's slice + the auth-retry\n// budget. A flat record, every field plain data.\n// ===========================================================================\n\n/**\n * The composed slice. Three plain-data fields, no closures:\n *\n *   - `resilience` — resilient-call's entire slice (circuit, bucket, retry,\n *     cache, calls). Owned and mutated only via resilient-call's verbs.\n *   - `auth` — token-refresh's `{ token, stale }` slice. Owned and mutated only\n *     via token-refresh's verbs.\n *   - `authRetry` — per-key count of auth-retries (401 → refresh → retry) spent\n *     on a call. Caps the dance at one retry per call so a credential the server\n *     keeps rejecting cannot spin forever. A key absent from the record has\n *     spent zero. Cleared when a call settles or a fresh `attempt` starts.\n *\n * `pendingAuthRetry` carries the inputs of calls parked waiting for the refresh\n * to land, keyed so `onRefreshed` can re-issue exactly those calls. Plain data —\n * `input` is the same payload the call was issued with.\n */\nexport interface AuthedState<I, R> {\n  readonly resilience: ResilientState<I, R>;\n  readonly auth: TokenState;\n  readonly authRetry: Readonly<Record<string, number>>;\n  readonly pendingAuthRetry: Readonly<Record<string, I>>;\n}\n\n// ===========================================================================\n// Cmds + Msgs. The union of both bricks' Cmds/Msgs plus a 401 trigger Msg.\n// ===========================================================================\n\n/** The two effects this knob emits: resilient-call's run, token-refresh's mint. */\nexport type AuthedCmd<I> = RunCmd<I> | RefreshTokenCmd;\n\n/**\n * Every Msg the knob's verbs fold. Resilient-call's settle + timer Msgs, token-\n * refresh's refresh-result Msgs, and the 401 trigger the consumer dispatches\n * when a guarded call comes back unauthorized.\n */\nexport type Unauthorized = {\n  readonly type: typeof MsgType.Unauthorized;\n  readonly key: string;\n  readonly at: number;\n};\n\n/**\n * The plain-data error a 401 we cannot fix settles with. A `{_tag, ...}`\n * sentinel — NEVER a `new Error(...)` — so the slice stays JSON-serializable\n * (an Error object round-trips to `{}` under JSON and carries a stack trace,\n * both of which break the slice's durability invariant once it is persisted\n * into a `Store<S>` and reloaded). Mirrors resilient-call's `DeadlineExceededError`\n * sentinel discipline. `key` echoes the call that was rejected so a consumer can\n * attribute the failure.\n */\nexport type UnauthorizedError = {\n  readonly _tag: \"unauthorized\";\n  readonly key: string;\n};\n\n// ===========================================================================\n// The knob factory.\n// ===========================================================================\n\n/**\n * Build an authed-call knob from `config`. `rng` is injected for retry jitter\n * and threaded straight into the underlying resilient-call knob — pass a fixed\n * `() => 0.5` in tests to pin backoff; defaults to `Math.random` (read only at\n * the verb boundary inside resilient-call, never in a brick op).\n *\n * Returns the uniform L2 knob contract, widened by the auth verbs (`on401`,\n * `onRefreshed`, `installToken`). `I` is the port input type, `R` the result.\n */\nexport function createAuthedCall<I, R>(\n  config: AuthedConfig = {},\n  rng: () => number = Math.random,\n) {\n  // Delegate ALL call resilience to the root composition. The resilient config\n  // is exactly `config` minus the two auth-only fields — but since\n  // `ResilientConfig` only reads the brick fields it knows, passing the wider\n  // `config` is harmless. We pass it directly so future resilient bricks flow\n  // through without a re-spread.\n  const rc = createResilientCall<I, R>(config, rng);\n  // Delegate the credential lifecycle to the L1 token brick.\n  const tr = createTokenRefresh({ skewMs: config.skewMs });\n\n  /** The starting slice — both bricks' inits plus empty auth-retry bookkeeping. */\n  function init(): AuthedState<I, R> {\n    return {\n      resilience: rc.init(),\n      auth: tr.init(),\n      authRetry: {},\n      pendingAuthRetry: {},\n    };\n  }\n\n  // Rebuild the host record after a resilient-call verb, preserving the auth\n  // dimension. The single seam where a `[ResilientState, Cmd[]]` becomes a\n  // `[AuthedState, Cmd[]]`.\n  function liftResilient(\n    s: AuthedState<I, R>,\n    [resilience, cmds]: readonly [ResilientState<I, R>, readonly RunCmd<I>[]],\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    return [{ ...s, resilience }, cmds];\n  }\n\n  // Forget a key's auth bookkeeping: the 401 budget (`authRetry`) and any\n  // parked input (`pendingAuthRetry`) that a settled or restarted call must\n  // clear TOGETHER. These two records form a coupled invariant — a call that\n  // settles, restarts, or gives up on its 401 dance drops both — so the joint\n  // clear lives in one place rather than being open-coded at each site.\n  function clearAuthKey(s: AuthedState<I, R>, key: string): AuthedState<I, R> {\n    return {\n      ...s,\n      authRetry: without(s.authRetry, key),\n      pendingAuthRetry: without(s.pendingAuthRetry, key),\n    };\n  }\n\n  // === Verb: attempt =======================================================\n\n  /**\n   * Start (or restart) the call for `key`. Delegates the gate entirely to\n   * resilient-call. A fresh attempt resets this key's auth-retry budget (a new\n   * logical call gets its own single 401 retry) and drops any stale parked\n   * input. PURE — `at` is the only clock.\n   *\n   * Note this knob does NOT proactively refresh on expiry inside `attempt`: the\n   * expiry-driven refresh is the consumer's call-boundary concern (token-refresh\n   * exposes `ensureFresh` for exactly that, re-exported below). `attempt` owns\n   * the *reactive* path — it issues the call, and a 401 coming back triggers the\n   * refresh. Keeping the two seams separate means a consumer who wants only\n   * reactive auth (no proactive refresh) wires nothing extra.\n   */\n  function attempt(\n    s: AuthedState<I, R>,\n    key: string,\n    input: I,\n    at: number,\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    const cleared = clearAuthKey(s, key);\n    return liftResilient(\n      cleared,\n      rc.attempt(cleared.resilience, key, input, at),\n    );\n  }\n\n  // === Verb: succeed =======================================================\n\n  /**\n   * Record a success for `msg.cmd.key`: delegate to resilient-call (closes the\n   * breaker, fills the cache, resets retry) and clear this key's auth-retry\n   * bookkeeping — the call settled, so its 401 budget and any parked input are\n   * forgotten. PURE.\n   */\n  function succeed(\n    s: AuthedState<I, R>,\n    msg: SucceedMsg<R>,\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    const settled = clearAuthKey(s, msg.cmd.key);\n    const { call, cmds } = rc.settle(settled.resilience, msg);\n    return liftResilient(settled, [call, cmds]);\n  }\n\n  // === Verb: fail ==========================================================\n\n  /**\n   * Record a NON-auth failure for `key` (a 5xx, a network drop — anything that\n   * is not a 401). Delegate to resilient-call's `settle`, which trips the breaker\n   * and backs off / settles per the retry policy. The auth dimension is\n   * untouched: a generic failure says nothing about the credential. PURE.\n   *\n   * A 401 is NOT routed here — the consumer dispatches `unauthorized` and the\n   * machine calls `on401` instead. Routing a 401 through `fail` would burn the\n   * resilient retry budget on a credential that a plain re-issue cannot fix.\n   */\n  function fail(\n    s: AuthedState<I, R>,\n    msg: FailMsg,\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    // If the resilient verb settles this call, forget its auth bookkeeping too.\n    const { call: resilience, cmds } = rc.settle(s.resilience, msg);\n    const next = settleAuthIfDone(\n      { ...s, resilience },\n      msg.cmd.key,\n      resilience,\n    );\n    return [next, cmds];\n  }\n\n  // === Verb: on401 =========================================================\n\n  /**\n   * The auth dimension's one verb: the server rejected `key`'s call as\n   * unauthorized. \"Refresh → retry once\":\n   *\n   *   - First 401 on this call → mark the token stale, emit a `refresh_token`\n   *     Cmd, and PARK the call's input so the refresh landing re-issues it. The\n   *     resilient call phase is left as-is (still `running`, or `waiting_retry`\n   *     if a transient failure had already backed it off); the in-flight\n   *     resilient effect is abandoned in favour of the post-refresh re-issue.\n   *   - Second 401 (the budget is already spent) → settle the call `failed`\n   *     with the unauthorized error. No second refresh, no loop. Errors are\n   *     data: the failure is recorded on the resilient slice, visible to the\n   *     consumer.\n   *\n   * A 401 is NOT a downstream-health signal — a credential the server rejected\n   * says nothing about the backend's health. So the terminal path routes through\n   * resilient-call's `settleFailed` (which settles `failed` WITHOUT tripping the\n   * shared breaker or advancing this key's retry counter), never `fail` (which\n   * would punish a healthy target and burn the retry budget on a request that a\n   * plain re-issue cannot fix).\n   *\n   * PURE — `at` is the instant a terminal 401 settles the call at.\n   */\n  function on401(\n    s: AuthedState<I, R>,\n    key: string,\n    at: number,\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    const spent = s.authRetry[key] ?? 0;\n    const call = s.resilience.calls[key];\n    // A 401 can arrive while the call is `running` OR after a transient failure\n    // backed it off to `waiting_retry`; both hold the input needed to re-issue.\n    // Reading only `running` would drop a 401 that races a backoff — the call\n    // would never refresh.\n    const input =\n      call?.phase === \"running\" || call?.phase === \"waiting_retry\"\n        ? call.input\n        : undefined;\n\n    // Budget exhausted (already refreshed + retried once), or nothing to\n    // re-issue: settle the call failed with the unauthorized error. Through\n    // `settleFailed`, NOT `fail` — a 401 is not a breaker / retry signal.\n    if (spent >= 1 || input === undefined) {\n      const error: UnauthorizedError = { _tag: \"unauthorized\", key };\n      const [settled] = rc.settleFailed(s.resilience, key, error, at);\n      return [{ ...clearAuthKey(s, key), resilience: settled }, []];\n    }\n\n    // First 401: mark stale, park the call, ask for a fresh token.\n    return [\n      {\n        ...s,\n        auth: tr.on401(s.auth),\n        authRetry: { ...s.authRetry, [key]: spent + 1 },\n        pendingAuthRetry: { ...s.pendingAuthRetry, [key]: input },\n      },\n      [refreshTokenCmd()],\n    ];\n  }\n\n  // === Verb: installToken ==================================================\n\n  /**\n   * Fold a freshly minted `token` into the auth slice (delegates to token-\n   * refresh's `refreshed`: installs the token, clears `stale`). PURE. Call this\n   * from the `refresh_token_ok` reducer cell, then chain `onRefreshed` to re-fire\n   * the parked calls. Split from `onRefreshed` so a consumer can install a token\n   * without auto-retrying (e.g. a proactive expiry refresh with nothing parked).\n   */\n  function installToken(s: AuthedState<I, R>, token: Token): AuthedState<I, R> {\n    return { ...s, auth: tr.refreshed(s.auth, token) };\n  }\n\n  // === Verb: onRefreshed ===================================================\n\n  /**\n   * Re-issue every call parked by a 401 now that a fresh token has landed. Runs\n   * each parked input back through resilient-call's `attempt` gate (so the\n   * circuit / rate-limit / cache are all re-checked against the new `at`),\n   * clears the parked set, and accumulates the run Cmds. The auth-retry COUNT is\n   * preserved (each re-issued call has already spent one auth-retry, so a second\n   * 401 on it settles failed). PURE — `at` is the gate's clock.\n   *\n   * No parked calls → a no-op that returns the slice unchanged by reference, so\n   * a proactive (expiry) refresh with nothing in flight costs nothing.\n   */\n  function onRefreshed(\n    s: AuthedState<I, R>,\n    at: number,\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    const parked = Object.entries(s.pendingAuthRetry);\n    if (parked.length === 0) return [s, []];\n\n    let resilience = s.resilience;\n    const cmds: AuthedCmd<I>[] = [];\n    for (const [key, input] of parked) {\n      const [next, runCmds] = rc.attempt(resilience, key, input, at);\n      resilience = next;\n      cmds.push(...runCmds);\n    }\n    return [{ ...s, resilience, pendingAuthRetry: {} }, cmds];\n  }\n\n  // === Verb: onTimer =======================================================\n\n  /**\n   * A retry / deadline timer fired — delegate straight to resilient-call. If the\n   * delegated verb settled the call, forget its auth bookkeeping. PURE.\n   */\n  function onTimer(\n    s: AuthedState<I, R>,\n    msg: ResilientTimerMsg | { readonly id: string; readonly atMs: number },\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    const [resilience, cmds] = rc.onTimer(s.resilience, msg);\n    const next = settleAuthIfDone({ ...s, resilience }, undefined, resilience);\n    return [next, cmds];\n  }\n\n  // --- helpers --------------------------------------------------------------\n\n  // After a resilient verb, drop auth bookkeeping for any key the resilient\n  // slice now reports as settled (succeeded / failed). `onlyKey` narrows the\n  // scan to one key when the verb targeted one (fail); `undefined` scans all\n  // (onTimer can settle a deadline on any key).\n  function settleAuthIfDone(\n    s: AuthedState<I, R>,\n    onlyKey: string | undefined,\n    resilience: ResilientState<I, R>,\n  ): AuthedState<I, R> {\n    const keys = onlyKey !== undefined ? [onlyKey] : Object.keys(s.authRetry);\n    let next = s;\n    for (const key of keys) {\n      const phase = resilience.calls[key]?.phase;\n      if (phase === \"succeeded\" || phase === \"failed\") {\n        next = clearAuthKey(next, key);\n      }\n    }\n    return next;\n  }\n\n  // === Timers ==============================================================\n\n  /**\n   * The deadlines this slice waits on — exactly resilient-call's (retry +\n   * deadline timers keyed per call). The auth dimension arms NO timers: a\n   * refresh is a one-shot Cmd, and the parked-call re-issue is driven by the\n   * `refresh_token_ok` Msg, not a timer.\n   */\n  function deadlines(s: AuthedState<I, R>): readonly DeadlineSub[] {\n    return rc.deadlines(s.resilience);\n  }\n\n  /**\n   * The built-in `timer` Sub's deps: resilient-call's `timer` over the\n   * `resilience` field. Declare `{ type: \"timer\", deps: (s) => ac.timer(s) }`.\n   */\n  function timer(s: AuthedState<I, R>) {\n    return rc.timer(s.resilience);\n  }\n\n  return {\n    /** The call's `Cmd.define`d run Cmd — list it in `cmds`. */\n    run: rc.run,\n    /** token-refresh's `refresh_token` Cmd def — list it in `cmds`. */\n    refresh: tr.run,\n    init,\n    attempt,\n    succeed,\n    fail,\n    on401,\n    installToken,\n    onRefreshed,\n    onTimer,\n    /** token-refresh's call-boundary verb, re-exposed for proactive expiry refresh. */\n    needsRefresh: (s: AuthedState<I, R>, at: number) =>\n      tr.needsRefresh(s.auth, at),\n    deadlines,\n    timer,\n  };\n}\n\n/** The shape `createAuthedCall` returns — useful for typing a held knob. */\nexport type AuthedCall<I, R> = ReturnType<typeof createAuthedCall<I, R>>;\n\n/**\n * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the slice\n * lives at `state.authed`. A convenience for the common single-slice host;\n * consumers with a differently-named field spread by hand. Pure — a thin record\n * rebuild, no clock / RNG.\n */\nexport function liftAuthed<\n  S extends { authed: AuthedState<I, R> },\n  I,\n  R,\n  C extends Cmd,\n>(\n  state: S,\n  [slice, cmds]: readonly [AuthedState<I, R>, readonly C[]],\n): readonly [S, readonly C[]] {\n  return [{ ...state, authed: slice }, cmds];\n}\n\n/**\n * Re-export the types a consumer wires into their reducer, so the whole\n * composition imports from one subpath.\n */\nexport type {\n  ResilientState,\n  TokenState,\n  Token,\n  TokenRefreshMsg,\n  SucceedMsg,\n  FailMsg,\n  ResilientTimerMsg,\n  RunCmd,\n};\n","/**\n * internal/resilience/retry-to-success — run a fallible async port through BOUNDED\n * retry + exponential backoff to success-or-terminal-give-up, and hand the\n * caller a `Promise<R>` that resolves on the first success or REJECTS with a\n * checkable {@link RetryExhaustedError} the moment the retry bound is hit.\n *\n * This is the retry-side parallel to `./await-terminal`. `runToTerminal` gives a\n * caller with a one-shot decision *machine* a fire-and-await `Promise<State>`\n * without wiring `observe`; this gives a caller with a one-shot fallible *port*\n * a fire-and-await `Promise<R>` without either hand-folding the\n * `./retry-backoff` primitives (`recordFailure` / `shouldRetry` / `nextDelayMs`)\n * into their own reducer each time, or standing up the full `./resilient-call`\n * verb contract (`init` + `attempt`/`succeed`/`fail`/`onTimer` + `subs` +\n * `handlers`) when they want retry only and none of cache / circuit / rate-limit\n * / deadline.\n *\n * It adds NO new runtime capability and NO new backoff math — the whole retry\n * decision is `./retry-backoff` exactly as `resilient-call`'s `backoff` verb\n * wires it:\n *   - `initRetry()` seeds the per-call attempt counter.\n *   - `recordFailure(retry, error)` folds each thrown failure (attempt++).\n *   - `shouldRetry(retry, policy)` is the terminal-at-`maxAttempts` bound — the\n *     `maxAttempts`-th recorded failure refuses another attempt (attempts\n *     `0 .. maxAttempts-1` run; the port is invoked at most `maxAttempts` times).\n *   - `nextDelayMs(retry, policy, rng)` is the exp+jitter+cap delay before the\n *     next attempt, computed on the incremented state — same call order as\n *     `resilient-call`.\n *\n * Where the clock / RNG live: injected, never read on the module's own behalf,\n * mirroring `retry-backoff`'s purity discipline. `rng` is an {@link Rng} (branded\n * `[0, 1)` via `asRng` at the caller boundary) threaded straight into\n * `nextDelayMs`; the wait itself is a `sleep(ms)` port defaulting to a real\n * `setTimeout`, injectable so a test can drive the backoff schedule\n * deterministically without touching wall-clock timers.\n *\n * Exhaustion is NEVER a silent swallow: at the bound the returned promise\n * rejects with {@link RetryExhaustedError} (carrying the attempt count and the\n * final failure), the retry-side dialect of `await-terminal`'s\n * `TerminalTimeoutError` — a distinct `instanceof`- and `_tag`-checkable\n * rejection.\n *\n * NOT a substrate primitive: it depends on nothing from `../index`, only on the\n * leaf `retry-backoff` utility. Internal to the package\n * (`src/internal/resilience/`, #46), not a published subpath.\n */\n\nimport {\n  defaultRng,\n  initRetry,\n  nextDelayMs,\n  type RetryPolicy,\n  type Rng,\n  recordFailure,\n  shouldRetry,\n} from \"../../../retry-backoff\";\n\n/**\n * Raised when `retryToSuccess` exhausts the retry bound without a success — the\n * `maxAttempts`-th recorded failure refuses another attempt. Follows the tea\n * error dialect (`override readonly name`) and carries a `_tag` discriminant, so\n * a caller can branch on it by `instanceof` or on the tag. It carries the number\n * of attempts made and the final failure (`lastError`) so the terminal give-up\n * is a distinct, checkable rejection — never a silent resolve, and never a\n * swallowed error.\n */\nexport class RetryExhaustedError extends Error {\n  override readonly name = \"RetryExhaustedError\";\n  readonly _tag = \"RetryExhaustedError\" as const;\n  constructor(\n    /** How many times the port was invoked before giving up (= `policy.maxAttempts`). */\n    public readonly attempts: number,\n    /** The failure the final attempt threw — carried, never interpreted. */\n    public readonly lastError: unknown,\n  ) {\n    super(\n      `@demlik/tea: retryToSuccess gave up after ${attempts} attempt(s) — the ` +\n        `bounded retry reached maxAttempts without a success. See .lastError ` +\n        `for the final failure.`,\n    );\n  }\n}\n\n/** Default wait: a real `setTimeout(ms)`, the sole clock read this module makes. */\nconst defaultSleep = (ms: number): Promise<void> =>\n  new Promise((resolve) => setTimeout(resolve, ms));\n\n/** Options for {@link retryToSuccess}. */\nexport interface RetryToSuccessOptions {\n  /**\n   * The `[0, 1)` jitter source threaded into `nextDelayMs`, branded via\n   * `asRng` at construction (a raw `() => number` is rejected by the type).\n   * Injected for deterministic backoff in tests; defaults to `defaultRng`\n   * (`Math.random`), read only at the delay boundary — never inside the loop's\n   * decision.\n   */\n  readonly rng?: Rng;\n  /**\n   * The wait between attempts, given the backoff delay in ms. Injectable so a\n   * test can drive the retry schedule without wall-clock timers (and assert the\n   * exact delays); defaults to a real `setTimeout`. The delay value is always\n   * `./retry-backoff`'s `nextDelayMs` — this port only realizes the wait.\n   */\n  readonly sleep?: (ms: number) => Promise<void>;\n}\n\n/**\n * Fire-and-await bounded retry: invoke the fallible `port`, and on each thrown\n * failure fold it through `./retry-backoff` — record it, and if the policy\n * still permits an attempt, back off `nextDelayMs` and retry; otherwise REJECT\n * with {@link RetryExhaustedError}. Resolves with the port's value on the first\n * success.\n *\n * The port is invoked at most `policy.maxAttempts` times (attempts\n * `0 .. maxAttempts-1`); the `maxAttempts`-th failure is terminal. Every failure\n * is either retried or surfaced on the rejection's `lastError` — none is\n * swallowed.\n *\n * @param port   the fallible work — throws on failure, resolves with `R` on success.\n * @param policy the bounded-retry curve (`baseMs` / `factor` / `capMs` /\n *               `maxAttempts` / `jitter`) from `./retry-backoff`.\n * @param opts   optional injected `rng` (jitter) and `sleep` (the wait) — see\n *               {@link RetryToSuccessOptions}.\n */\nexport async function retryToSuccess<R>(\n  port: () => Promise<R>,\n  policy: RetryPolicy,\n  opts: RetryToSuccessOptions = {},\n): Promise<R> {\n  const rng = opts.rng ?? defaultRng;\n  const sleep = opts.sleep ?? defaultSleep;\n\n  // The retry counter folds over `./retry-backoff` exactly as resilient-call's\n  // `backoff` verb does — no local attempt bookkeeping, no local backoff math.\n  let retry = initRetry();\n  for (;;) {\n    try {\n      return await port();\n    } catch (error) {\n      // Fold the failure first (attempt++), then consult the bound on the\n      // incremented state — same order as resilient-call so the semantics of\n      // `maxAttempts` are identical across both surfaces.\n      retry = recordFailure(retry, error);\n      if (!shouldRetry(retry, policy)) {\n        // Terminal give-up at the bound: reject, never swallow. `retry.attempt`\n        // is the number of failures = the number of port invocations made.\n        throw new RetryExhaustedError(retry.attempt, error);\n      }\n      await sleep(nextDelayMs(retry, policy, rng));\n    }\n  }\n}\n"]}
+{"version":3,"sources":["../../src/internal/resilience/token-refresh/index.ts","../../src/internal/resilience/authed-call/index.ts","../../src/internal/resilience/retry-to-success/index.ts"],"names":["deadlines"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * internal/resilience/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 `Cmd.define`d Cmd (`refresh_token`)\n * that asks for the re-mint. You write that Cmd's handler in your engine's\n * style (ADR 0021); the knob ships no I/O.\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 in the\n *     `refresh_token` handler you write. 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 lands (the engine mints `refresh_token_ok`):\n *   refresh_token_ok: (s, msg) => [{ ...s, auth: tr.refreshed(s.auth, msg.value) }, []],\n *\n *   // and where the machine runs, the handler you write for the Cmd:\n *   run(machine, {\n *     interpret: {\n *       refresh_token: async (_cmd, { ok, err }) => {\n *         try { return ok(await mySdk.mintToken()); }\n *         catch (cause) { return err({ _tag: \"token_refresh_failed\", cause }); }\n *       },\n *     },\n *   });\n *\n * NOT a substrate primitive: from `../index` it reuses only `Cmd.define` — and\n * no sibling brick. It is a leaf utility internal to the package\n * (`src/internal/resilience/`, #46).\n */\n\nimport {\n  Cmd,\n  type CmdOf,\n  type SettledErr,\n  type SettledOk,\n  type TaggedError,\n} from \"../../../index\";\nimport { unchecked } from \"../../schema\";\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 takes no input, and\n * the slice the result installs is read off the settled Msg, not this Cmd.\n * List it in the machine's `cmds`; its handler returns `ok(token)` or\n * `err({ _tag: \"token_refresh_failed\", … })`, and the engine mints\n * `refresh_token_ok` / `refresh_token_err`.\n */\nexport const refreshToken = Cmd.define(\"refresh_token\", {\n  input: unchecked<Record<string, never>>(),\n  ok: unchecked<Token>(),\n  err: [\"token_refresh_failed\"],\n});\nexport type RefreshTokenCmd = CmdOf<typeof refreshToken>;\n\n/** Construct a `refresh_token` Cmd. */\nexport function refreshTokenCmd(): RefreshTokenCmd {\n  return refreshToken({});\n}\n\n/**\n * The Msg the engine mints when the `refresh_token` handler returns\n * `ok(token)`: `value` is the freshly minted `Token`. Fold it with\n * `refreshed(state, msg.value)`.\n */\nexport type TokenRefreshedMsg = SettledOk<\n  \"refresh_token\",\n  RefreshTokenCmd,\n  Token\n>;\n\n/**\n * The Msg the engine mints when the handler returns\n * `err({ _tag: \"token_refresh_failed\", … })` — errors are data, never\n * swallowed. The slice is left untouched by a failed refresh: the held token\n * (if any) stays held and stale stays set, so the consumer can retry; clearing\n * it is the consumer's policy, expressed in their reducer.\n */\nexport type TokenRefreshFailedMsg = SettledErr<\n  \"refresh_token\",\n  RefreshTokenCmd,\n  TaggedError<\"token_refresh_failed\">\n>;\n\n/** The two Msgs a refresh can settle with. Union for a consumer's Msg type. */\nexport type TokenRefreshMsg = TokenRefreshedMsg | TokenRefreshFailedMsg;\n\n/**\n * The knob: hand it a config, get back the slice initializer and the pure\n * verbs, plus the `refresh_token` Cmd def (`run`) to list in `cmds`.\n *\n * @example\n * ```ts\n * import { createTokenRefresh } from \"@demlik/tea/resilience\";\n *\n * const tr = createTokenRefresh({ skewMs: 30_000 });\n * const s0 = tr.init();\n * const [s1, cmds] = tr.ensureFresh(s0, Date.now()); // cmds = [refreshTokenCmd()]\n * ```\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 RefreshTokenCmd[]] {\n    if (needsRefresh(state, at)) {\n      return [state, [refreshTokenCmd()]];\n    }\n    return [state, []];\n  }\n\n  return {\n    /** The `refresh_token` Cmd def — list it in the machine's `cmds`. */\n    run: refreshToken,\n    /** The slice initializer — spread into the consumer's `init`. */\n    init: initTokenRefresh,\n    needsRefresh,\n    on401,\n    refreshed,\n    ensureFresh,\n  };\n}\n\n/** The shape `createTokenRefresh` returns — useful for typing a held knob. */\nexport type TokenRefresh = ReturnType<typeof createTokenRefresh>;\n","/**\n * internal/resilience/authed-call — resilient-call with one extra dimension: a bearer\n * credential that must be minted before a call goes out and re-minted when the\n * server says it is no longer good (a 401). It is composition #10 in the specs:\n * *extends resilient-call; needs the L1 `token-refresh` brick*.\n *\n * The recipe — two existing bricks, stacked, nothing hand-wired:\n *\n *   - `../resilient-call` owns ALL the call resilience: cache → circuit-breaker\n *     → rate-limit → exponential-backoff retry, plus the per-call deadline. This\n *     knob does not re-implement a single line of it. The `attempt` / `succeed`\n *     / `fail` / `onTimer` verbs here are thin delegations that thread the\n *     composed slice's `resilience` field through the resilient-call verb —\n *     `succeed` and `fail` both through its one `settle`. Whatever resilience config a consumer passes flows straight\n *     down — every `ResilientConfig` field is still optional, still \"omit a\n *     brick → omit its gate\".\n *\n *   - `../token-refresh` owns the credential lifecycle: the `{ token, stale }`\n *     slice and the decisions about *when* a token must be refreshed (expiry\n *     skew, or a reactive 401). This knob adds the one verb resilient-call has\n *     no concept of — `on401` — and asks for a fresh token with token-refresh's\n *     `refresh_token` Cmd.\n *\n * So the slice is exactly *resilient-call's slice + token-refresh's slice*:\n *\n *   { resilience: ResilientState<I,R>, auth: TokenState }\n *\n * and the verb set is *resilient-call's four verbs + `on401`*, precisely the\n * spec's \"resilient-call's + `on401(s)` (refresh → retry once)\".\n *\n * ## The 401 dance — \"refresh → retry once\"\n *\n * A 401 is special: it is not a transient failure (backing off and retrying the\n * SAME credential just earns another 401), and it is not a terminal failure (a\n * fresh token usually fixes it). So `on401(s, key, at)` does three things:\n *\n *   1. marks the held token `stale` (via token-refresh's `on401`) and emits a\n *      `refresh_token` Cmd to mint a new one;\n *   2. parks the in-flight call in a per-key `authRetry` budget so that, *once*,\n *      the refresh landing re-issues that call with the new credential;\n *   3. caps that to a SINGLE auth-retry per call. A second 401 on the same call\n *      after we already refreshed and retried does NOT loop — it settles the\n *      call `failed` (errors are data: the failure is recorded, never swallowed\n *      or spun on forever). The budget resets on the next fresh `attempt`.\n *\n * When the refresh resolves, the consumer folds `refreshed` into the auth slice\n * and calls `onRefreshed(s, at)`, which re-attempts every parked call through\n * the resilient gate with the new token in hand.\n *\n * ## The two non-negotiables (canon — inherited from both bricks)\n *\n *   - **Durable** — the slice is `ResilientState` (plain data) + `TokenState`\n *     (plain data) + a plain `Record<string, number>` retry budget. All JSON-\n *     serializable, so it survives a Durable Object eviction / reload.\n *   - **Replayable** — every verb returns `readonly [State, Cmd[]]` and never\n *     reads the wall clock or RNG. Time arrives as an `at` parameter; the RNG\n *     for retry jitter is injected once at `createAuthedCall(config, rng)` and\n *     handed straight to the resilient-call knob. The knob ships no I/O: the\n *     call and the token mint are two `Cmd.define`d Cmds whose handlers you\n *     write (ADR 0021).\n *\n * ## Typical wiring\n *\n *   const ac = createAuthedCall<string, Resp>({\n *     retry: defaultRetryPolicy,\n *     circuit: { threshold: 5, cooldownMs: 30_000 },\n *     deadline: { ms: 5_000 },\n *     skewMs: 30_000,\n *   });\n *\n *   // in the machine:\n *   cmds: [ac.run, ac.refresh],\n *   init: () => [ac.init(), []],\n *   update: {\n *     fetch:   (s, m) => ac.attempt(s, m.key, m.input, m.at),\n *     resilient_run_ok:  (s, m) => ac.succeed(s, m),\n *     resilient_run_err: (s, m) => ac.fail(s, m),\n *     got_401: (s, m) => ac.on401(s, m.key, m.at),\n *     refresh_token_ok: (s, m) => ac.onRefreshed(ac.installToken(s, m.value), m.at),\n *     refresh_token_err: (s) => [s, []],\n *     deadline_exceeded: (s, m) => ac.onTimer(s, m),\n *   },\n *   subs: [{ type: \"timer\", deps: (s) => ac.timer(s) }],\n *\n *   // and where it runs — the two handlers you write:\n *   run(machine, {\n *     interpret: {\n *       resilient_run: async (cmd, { ok, err }) => …,  // the call itself\n *       refresh_token: async (_cmd, { ok, err }) => …, // mint a Token\n *     },\n *   });\n */\n\nimport type { Cmd } from \"../../../index\";\nimport type { MsgType } from \"../../../protocol\";\nimport { without } from \"../../../pure/core\";\nimport type { DeadlineSub } from \"../deadline\";\nimport {\n  createResilientCall,\n  type FailMsg,\n  type ResilientConfig,\n  type ResilientState,\n  type ResilientTimerMsg,\n  type RunCmd,\n  type SucceedMsg,\n} from \"../resilient-call\";\nimport {\n  createTokenRefresh,\n  type RefreshTokenCmd,\n  refreshTokenCmd,\n  type Token,\n  type TokenRefreshConfig,\n  type TokenRefreshMsg,\n  type TokenState,\n} from \"../token-refresh\";\n\n// ===========================================================================\n// Config — the knob. The resilient-call config PLUS token-refresh's skew.\n// ===========================================================================\n\n/**\n * The authed-call knob. It is `ResilientConfig` widened by the token dimension:\n *\n *   - `skewMs` — token-refresh's refresh-ahead skew (optional, defaults to 0).\n *   - every `ResilientConfig` field (`retry` / `circuit` / `rateLimit` /\n *     `cache` / `deadline`) — passed straight through to the resilient-call\n *     knob, each still optional, each still \"omit a brick → omit its gate\".\n *\n * The token mint is not on the config: it is the `refresh_token` Cmd, and its\n * handler is yours.\n */\nexport type AuthedConfig = ResilientConfig & TokenRefreshConfig;\n\n// ===========================================================================\n// Slice — resilient-call's slice + token-refresh's slice + the auth-retry\n// budget. A flat record, every field plain data.\n// ===========================================================================\n\n/**\n * The composed slice. Three plain-data fields, no closures:\n *\n *   - `resilience` — resilient-call's entire slice (circuit, bucket, retry,\n *     cache, calls). Owned and mutated only via resilient-call's verbs.\n *   - `auth` — token-refresh's `{ token, stale }` slice. Owned and mutated only\n *     via token-refresh's verbs.\n *   - `authRetry` — per-key count of auth-retries (401 → refresh → retry) spent\n *     on a call. Caps the dance at one retry per call so a credential the server\n *     keeps rejecting cannot spin forever. A key absent from the record has\n *     spent zero. Cleared when a call settles or a fresh `attempt` starts.\n *\n * `pendingAuthRetry` carries the inputs of calls parked waiting for the refresh\n * to land, keyed so `onRefreshed` can re-issue exactly those calls. Plain data —\n * `input` is the same payload the call was issued with.\n */\nexport interface AuthedState<I, R> {\n  readonly resilience: ResilientState<I, R>;\n  readonly auth: TokenState;\n  readonly authRetry: Readonly<Record<string, number>>;\n  readonly pendingAuthRetry: Readonly<Record<string, I>>;\n}\n\n// ===========================================================================\n// Cmds + Msgs. The union of both bricks' Cmds/Msgs plus a 401 trigger Msg.\n// ===========================================================================\n\n/** The two effects this knob emits: resilient-call's run, token-refresh's mint. */\nexport type AuthedCmd<I> = RunCmd<I> | RefreshTokenCmd;\n\n/**\n * Every Msg the knob's verbs fold. Resilient-call's settle + timer Msgs, token-\n * refresh's refresh-result Msgs, and the 401 trigger the consumer dispatches\n * when a guarded call comes back unauthorized.\n */\nexport type Unauthorized = {\n  readonly type: typeof MsgType.Unauthorized;\n  readonly key: string;\n  readonly at: number;\n};\n\n/**\n * The plain-data error a 401 we cannot fix settles with. A `{_tag, ...}`\n * sentinel — NEVER a `new Error(...)` — so the slice stays JSON-serializable\n * (an Error object round-trips to `{}` under JSON and carries a stack trace,\n * both of which break the slice's durability invariant once it is persisted\n * into a `Store<S>` and reloaded). Mirrors resilient-call's `DeadlineExceededError`\n * sentinel discipline. `key` echoes the call that was rejected so a consumer can\n * attribute the failure.\n */\nexport type UnauthorizedError = {\n  readonly _tag: \"unauthorized\";\n  readonly key: string;\n};\n\n// ===========================================================================\n// The knob factory.\n// ===========================================================================\n\n/**\n * Build an authed-call knob from `config`. `rng` is injected for retry jitter\n * and threaded straight into the underlying resilient-call knob — pass a fixed\n * `() => 0.5` in tests to pin backoff; defaults to `Math.random` (read only at\n * the verb boundary inside resilient-call, never in a brick op).\n *\n * Returns the uniform L2 knob contract, widened by the auth verbs (`on401`,\n * `onRefreshed`, `installToken`). `I` is the port input type, `R` the result.\n */\nexport function createAuthedCall<I, R>(\n  config: AuthedConfig = {},\n  rng: () => number = Math.random,\n) {\n  // Delegate ALL call resilience to the root composition. The resilient config\n  // is exactly `config` minus the two auth-only fields — but since\n  // `ResilientConfig` only reads the brick fields it knows, passing the wider\n  // `config` is harmless. We pass it directly so future resilient bricks flow\n  // through without a re-spread.\n  const rc = createResilientCall<I, R>(config, rng);\n  // Delegate the credential lifecycle to the L1 token brick.\n  const tr = createTokenRefresh({ skewMs: config.skewMs });\n\n  /** The starting slice — both bricks' inits plus empty auth-retry bookkeeping. */\n  function init(): AuthedState<I, R> {\n    return {\n      resilience: rc.init(),\n      auth: tr.init(),\n      authRetry: {},\n      pendingAuthRetry: {},\n    };\n  }\n\n  // Rebuild the host record after a resilient-call verb, preserving the auth\n  // dimension. The single seam where a `[ResilientState, Cmd[]]` becomes a\n  // `[AuthedState, Cmd[]]`.\n  function liftResilient(\n    s: AuthedState<I, R>,\n    [resilience, cmds]: readonly [ResilientState<I, R>, readonly RunCmd<I>[]],\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    return [{ ...s, resilience }, cmds];\n  }\n\n  // Forget a key's auth bookkeeping: the 401 budget (`authRetry`) and any\n  // parked input (`pendingAuthRetry`) that a settled or restarted call must\n  // clear TOGETHER. These two records form a coupled invariant — a call that\n  // settles, restarts, or gives up on its 401 dance drops both — so the joint\n  // clear lives in one place rather than being open-coded at each site.\n  function clearAuthKey(s: AuthedState<I, R>, key: string): AuthedState<I, R> {\n    return {\n      ...s,\n      authRetry: without(s.authRetry, key),\n      pendingAuthRetry: without(s.pendingAuthRetry, key),\n    };\n  }\n\n  // === Verb: attempt =======================================================\n\n  /**\n   * Start (or restart) the call for `key`. Delegates the gate entirely to\n   * resilient-call. A fresh attempt resets this key's auth-retry budget (a new\n   * logical call gets its own single 401 retry) and drops any stale parked\n   * input. PURE — `at` is the only clock.\n   *\n   * Note this knob does NOT proactively refresh on expiry inside `attempt`: the\n   * expiry-driven refresh is the consumer's call-boundary concern (token-refresh\n   * exposes `ensureFresh` for exactly that, re-exported below). `attempt` owns\n   * the *reactive* path — it issues the call, and a 401 coming back triggers the\n   * refresh. Keeping the two seams separate means a consumer who wants only\n   * reactive auth (no proactive refresh) wires nothing extra.\n   */\n  function attempt(\n    s: AuthedState<I, R>,\n    key: string,\n    input: I,\n    at: number,\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    const cleared = clearAuthKey(s, key);\n    return liftResilient(\n      cleared,\n      rc.attempt(cleared.resilience, key, input, at),\n    );\n  }\n\n  // === Verb: succeed =======================================================\n\n  /**\n   * Record a success for `msg.cmd.key`: delegate to resilient-call (closes the\n   * breaker, fills the cache, resets retry) and clear this key's auth-retry\n   * bookkeeping — the call settled, so its 401 budget and any parked input are\n   * forgotten. PURE.\n   */\n  function succeed(\n    s: AuthedState<I, R>,\n    msg: SucceedMsg<R>,\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    const settled = clearAuthKey(s, msg.cmd.key);\n    const { call, cmds } = rc.settle(settled.resilience, msg);\n    return liftResilient(settled, [call, cmds]);\n  }\n\n  // === Verb: fail ==========================================================\n\n  /**\n   * Record a NON-auth failure for `key` (a 5xx, a network drop — anything that\n   * is not a 401). Delegate to resilient-call's `settle`, which trips the breaker\n   * and backs off / settles per the retry policy. The auth dimension is\n   * untouched: a generic failure says nothing about the credential. PURE.\n   *\n   * A 401 is NOT routed here — the consumer dispatches `unauthorized` and the\n   * machine calls `on401` instead. Routing a 401 through `fail` would burn the\n   * resilient retry budget on a credential that a plain re-issue cannot fix.\n   */\n  function fail(\n    s: AuthedState<I, R>,\n    msg: FailMsg,\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    // If the resilient verb settles this call, forget its auth bookkeeping too.\n    const { call: resilience, cmds } = rc.settle(s.resilience, msg);\n    const next = settleAuthIfDone(\n      { ...s, resilience },\n      msg.cmd.key,\n      resilience,\n    );\n    return [next, cmds];\n  }\n\n  // === Verb: on401 =========================================================\n\n  /**\n   * The auth dimension's one verb: the server rejected `key`'s call as\n   * unauthorized. \"Refresh → retry once\":\n   *\n   *   - First 401 on this call → mark the token stale, emit a `refresh_token`\n   *     Cmd, and PARK the call's input so the refresh landing re-issues it. The\n   *     resilient call phase is left as-is (still `running`, or `waiting_retry`\n   *     if a transient failure had already backed it off); the in-flight\n   *     resilient effect is abandoned in favour of the post-refresh re-issue.\n   *   - Second 401 (the budget is already spent) → settle the call `failed`\n   *     with the unauthorized error. No second refresh, no loop. Errors are\n   *     data: the failure is recorded on the resilient slice, visible to the\n   *     consumer.\n   *\n   * A 401 is NOT a downstream-health signal — a credential the server rejected\n   * says nothing about the backend's health. So the terminal path routes through\n   * resilient-call's `settleFailed` (which settles `failed` WITHOUT tripping the\n   * shared breaker or advancing this key's retry counter), never `fail` (which\n   * would punish a healthy target and burn the retry budget on a request that a\n   * plain re-issue cannot fix).\n   *\n   * PURE — `at` is the instant a terminal 401 settles the call at.\n   */\n  function on401(\n    s: AuthedState<I, R>,\n    key: string,\n    at: number,\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    const spent = s.authRetry[key] ?? 0;\n    const call = s.resilience.calls[key];\n    // A 401 can arrive while the call is `running` OR after a transient failure\n    // backed it off to `waiting_retry`; both hold the input needed to re-issue.\n    // Reading only `running` would drop a 401 that races a backoff — the call\n    // would never refresh.\n    const input =\n      call?.phase === \"running\" || call?.phase === \"waiting_retry\"\n        ? call.input\n        : undefined;\n\n    // Budget exhausted (already refreshed + retried once), or nothing to\n    // re-issue: settle the call failed with the unauthorized error. Through\n    // `settleFailed`, NOT `fail` — a 401 is not a breaker / retry signal.\n    if (spent >= 1 || input === undefined) {\n      const error: UnauthorizedError = { _tag: \"unauthorized\", key };\n      const [settled] = rc.settleFailed(s.resilience, key, error, at);\n      return [{ ...clearAuthKey(s, key), resilience: settled }, []];\n    }\n\n    // First 401: mark stale, park the call, ask for a fresh token.\n    return [\n      {\n        ...s,\n        auth: tr.on401(s.auth),\n        authRetry: { ...s.authRetry, [key]: spent + 1 },\n        pendingAuthRetry: { ...s.pendingAuthRetry, [key]: input },\n      },\n      [refreshTokenCmd()],\n    ];\n  }\n\n  // === Verb: installToken ==================================================\n\n  /**\n   * Fold a freshly minted `token` into the auth slice (delegates to token-\n   * refresh's `refreshed`: installs the token, clears `stale`). PURE. Call this\n   * from the `refresh_token_ok` reducer cell, then chain `onRefreshed` to re-fire\n   * the parked calls. Split from `onRefreshed` so a consumer can install a token\n   * without auto-retrying (e.g. a proactive expiry refresh with nothing parked).\n   */\n  function installToken(s: AuthedState<I, R>, token: Token): AuthedState<I, R> {\n    return { ...s, auth: tr.refreshed(s.auth, token) };\n  }\n\n  // === Verb: onRefreshed ===================================================\n\n  /**\n   * Re-issue every call parked by a 401 now that a fresh token has landed. Runs\n   * each parked input back through resilient-call's `attempt` gate (so the\n   * circuit / rate-limit / cache are all re-checked against the new `at`),\n   * clears the parked set, and accumulates the run Cmds. The auth-retry COUNT is\n   * preserved (each re-issued call has already spent one auth-retry, so a second\n   * 401 on it settles failed). PURE — `at` is the gate's clock.\n   *\n   * No parked calls → a no-op that returns the slice unchanged by reference, so\n   * a proactive (expiry) refresh with nothing in flight costs nothing.\n   */\n  function onRefreshed(\n    s: AuthedState<I, R>,\n    at: number,\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    const parked = Object.entries(s.pendingAuthRetry);\n    if (parked.length === 0) return [s, []];\n\n    let resilience = s.resilience;\n    const cmds: AuthedCmd<I>[] = [];\n    for (const [key, input] of parked) {\n      const [next, runCmds] = rc.attempt(resilience, key, input, at);\n      resilience = next;\n      cmds.push(...runCmds);\n    }\n    return [{ ...s, resilience, pendingAuthRetry: {} }, cmds];\n  }\n\n  // === Verb: onTimer =======================================================\n\n  /**\n   * A retry / deadline timer fired — delegate straight to resilient-call. If the\n   * delegated verb settled the call, forget its auth bookkeeping. PURE.\n   */\n  function onTimer(\n    s: AuthedState<I, R>,\n    msg: ResilientTimerMsg | { readonly id: string; readonly atMs: number },\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    const [resilience, cmds] = rc.onTimer(s.resilience, msg);\n    const next = settleAuthIfDone({ ...s, resilience }, undefined, resilience);\n    return [next, cmds];\n  }\n\n  // --- helpers --------------------------------------------------------------\n\n  // After a resilient verb, drop auth bookkeeping for any key the resilient\n  // slice now reports as settled (succeeded / failed). `onlyKey` narrows the\n  // scan to one key when the verb targeted one (fail); `undefined` scans all\n  // (onTimer can settle a deadline on any key).\n  function settleAuthIfDone(\n    s: AuthedState<I, R>,\n    onlyKey: string | undefined,\n    resilience: ResilientState<I, R>,\n  ): AuthedState<I, R> {\n    const keys = onlyKey !== undefined ? [onlyKey] : Object.keys(s.authRetry);\n    let next = s;\n    for (const key of keys) {\n      const phase = resilience.calls[key]?.phase;\n      if (phase === \"succeeded\" || phase === \"failed\") {\n        next = clearAuthKey(next, key);\n      }\n    }\n    return next;\n  }\n\n  // === Timers ==============================================================\n\n  /**\n   * The deadlines this slice waits on — exactly resilient-call's (retry +\n   * deadline timers keyed per call). The auth dimension arms NO timers: a\n   * refresh is a one-shot Cmd, and the parked-call re-issue is driven by the\n   * `refresh_token_ok` Msg, not a timer.\n   */\n  function deadlines(s: AuthedState<I, R>): readonly DeadlineSub[] {\n    return rc.deadlines(s.resilience);\n  }\n\n  /**\n   * The built-in `timer` Sub's deps: resilient-call's `timer` over the\n   * `resilience` field. Declare `{ type: \"timer\", deps: (s) => ac.timer(s) }`.\n   */\n  function timer(s: AuthedState<I, R>) {\n    return rc.timer(s.resilience);\n  }\n\n  return {\n    /** The call's `Cmd.define`d run Cmd — list it in `cmds`. */\n    run: rc.run,\n    /** token-refresh's `refresh_token` Cmd def — list it in `cmds`. */\n    refresh: tr.run,\n    init,\n    attempt,\n    succeed,\n    fail,\n    on401,\n    installToken,\n    onRefreshed,\n    onTimer,\n    /** token-refresh's call-boundary verb, re-exposed for proactive expiry refresh. */\n    needsRefresh: (s: AuthedState<I, R>, at: number) =>\n      tr.needsRefresh(s.auth, at),\n    deadlines,\n    timer,\n  };\n}\n\n/** The shape `createAuthedCall` returns — useful for typing a held knob. */\nexport type AuthedCall<I, R> = ReturnType<typeof createAuthedCall<I, R>>;\n\n/**\n * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the slice\n * lives at `state.authed`. A convenience for the common single-slice host;\n * consumers with a differently-named field spread by hand. Pure — a thin record\n * rebuild, no clock / RNG.\n */\nexport function liftAuthed<\n  S extends { authed: AuthedState<I, R> },\n  I,\n  R,\n  C extends Cmd,\n>(\n  state: S,\n  [slice, cmds]: readonly [AuthedState<I, R>, readonly C[]],\n): readonly [S, readonly C[]] {\n  return [{ ...state, authed: slice }, cmds];\n}\n\n/**\n * Re-export the types a consumer wires into their reducer, so the whole\n * composition imports from one subpath.\n */\nexport type {\n  ResilientState,\n  TokenState,\n  Token,\n  TokenRefreshMsg,\n  SucceedMsg,\n  FailMsg,\n  ResilientTimerMsg,\n  RunCmd,\n};\n","/**\n * internal/resilience/retry-to-success — run a fallible async port through BOUNDED\n * retry + exponential backoff to success-or-terminal-give-up, and hand the\n * caller a `Promise<R>` that resolves on the first success or REJECTS with a\n * checkable {@link RetryExhaustedError} the moment the retry bound is hit.\n *\n * This is the retry-side parallel to `./await-terminal`. `runToTerminal` gives a\n * caller with a one-shot decision *machine* a fire-and-await `Promise<State>`\n * without wiring `observe`; this gives a caller with a one-shot fallible *port*\n * a fire-and-await `Promise<R>` without either hand-folding the\n * `./retry-backoff` primitives (`recordFailure` / `shouldRetry` / `nextDelayMs`)\n * into their own reducer each time, or standing up the full `./resilient-call`\n * verb contract (`init` + `attempt`/`succeed`/`fail`/`onTimer` + `subs` +\n * `handlers`) when they want retry only and none of cache / circuit / rate-limit\n * / deadline.\n *\n * It adds NO new runtime capability and NO new backoff math — the whole retry\n * decision is `./retry-backoff` exactly as `resilient-call`'s `backoff` verb\n * wires it:\n *   - `initRetry()` seeds the per-call attempt counter.\n *   - `recordFailure(retry, error)` folds each thrown failure (attempt++).\n *   - `shouldRetry(retry, policy)` is the terminal-at-`maxAttempts` bound — the\n *     `maxAttempts`-th recorded failure refuses another attempt (attempts\n *     `0 .. maxAttempts-1` run; the port is invoked at most `maxAttempts` times).\n *   - `nextDelayMs(retry, policy, rng)` is the exp+jitter+cap delay before the\n *     next attempt, computed on the incremented state — same call order as\n *     `resilient-call`.\n *\n * Where the clock / RNG live: injected, never read on the module's own behalf,\n * mirroring `retry-backoff`'s purity discipline. `rng` is an {@link Rng} (branded\n * `[0, 1)` via `asRng` at the caller boundary) threaded straight into\n * `nextDelayMs`; the wait itself is a `sleep(ms)` port defaulting to a real\n * `setTimeout`, injectable so a test can drive the backoff schedule\n * deterministically without touching wall-clock timers.\n *\n * Exhaustion is NEVER a silent swallow: at the bound the returned promise\n * rejects with {@link RetryExhaustedError} (carrying the attempt count and the\n * final failure), the retry-side dialect of `await-terminal`'s\n * `TerminalTimeoutError` — a distinct `instanceof`- and `_tag`-checkable\n * rejection.\n *\n * NOT a substrate primitive: it depends on nothing from `../index`, only on the\n * leaf `retry-backoff` utility. Internal to the package\n * (`src/internal/resilience/`, #46), not a published subpath.\n */\n\nimport {\n  defaultRng,\n  initRetry,\n  nextDelayMs,\n  type RetryPolicy,\n  type Rng,\n  recordFailure,\n  shouldRetry,\n} from \"../../../retry-backoff\";\n\n/**\n * Raised when `retryToSuccess` exhausts the retry bound without a success — the\n * `maxAttempts`-th recorded failure refuses another attempt. Follows the tea\n * error dialect (`override readonly name`) and carries a `_tag` discriminant, so\n * a caller can branch on it by `instanceof` or on the tag. It carries the number\n * of attempts made and the final failure (`lastError`) so the terminal give-up\n * is a distinct, checkable rejection — never a silent resolve, and never a\n * swallowed error.\n */\nexport class RetryExhaustedError extends Error {\n  override readonly name = \"RetryExhaustedError\";\n  readonly _tag = \"RetryExhaustedError\" as const;\n  constructor(\n    /** How many times the port was invoked before giving up (= `policy.maxAttempts`). */\n    public readonly attempts: number,\n    /** The failure the final attempt threw — carried, never interpreted. */\n    public readonly lastError: unknown,\n  ) {\n    super(\n      `@demlik/tea: retryToSuccess gave up after ${attempts} attempt(s) — the ` +\n        `bounded retry reached maxAttempts without a success. See .lastError ` +\n        `for the final failure.`,\n    );\n  }\n}\n\n/** Default wait: a real `setTimeout(ms)`, the sole clock read this module makes. */\nconst defaultSleep = (ms: number): Promise<void> =>\n  new Promise((resolve) => setTimeout(resolve, ms));\n\n/** Options for {@link retryToSuccess}. */\nexport interface RetryToSuccessOptions {\n  /**\n   * The `[0, 1)` jitter source threaded into `nextDelayMs`, branded via\n   * `asRng` at construction (a raw `() => number` is rejected by the type).\n   * Injected for deterministic backoff in tests; defaults to `defaultRng`\n   * (`Math.random`), read only at the delay boundary — never inside the loop's\n   * decision.\n   */\n  readonly rng?: Rng;\n  /**\n   * The wait between attempts, given the backoff delay in ms. Injectable so a\n   * test can drive the retry schedule without wall-clock timers (and assert the\n   * exact delays); defaults to a real `setTimeout`. The delay value is always\n   * `./retry-backoff`'s `nextDelayMs` — this port only realizes the wait.\n   */\n  readonly sleep?: (ms: number) => Promise<void>;\n}\n\n/**\n * Fire-and-await bounded retry: invoke the fallible `port`, and on each thrown\n * failure fold it through `./retry-backoff` — record it, and if the policy\n * still permits an attempt, back off `nextDelayMs` and retry; otherwise REJECT\n * with {@link RetryExhaustedError}. Resolves with the port's value on the first\n * success.\n *\n * The port is invoked at most `policy.maxAttempts` times (attempts\n * `0 .. maxAttempts-1`); the `maxAttempts`-th failure is terminal. Every failure\n * is either retried or surfaced on the rejection's `lastError` — none is\n * swallowed.\n *\n * @param port   the fallible work — throws on failure, resolves with `R` on success.\n * @param policy the bounded-retry curve (`baseMs` / `factor` / `capMs` /\n *               `maxAttempts` / `jitter`) from `./retry-backoff`.\n * @param opts   optional injected `rng` (jitter) and `sleep` (the wait) — see\n *               {@link RetryToSuccessOptions}.\n */\nexport async function retryToSuccess<R>(\n  port: () => Promise<R>,\n  policy: RetryPolicy,\n  opts: RetryToSuccessOptions = {},\n): Promise<R> {\n  const rng = opts.rng ?? defaultRng;\n  const sleep = opts.sleep ?? defaultSleep;\n\n  // The retry counter folds over `./retry-backoff` exactly as resilient-call's\n  // `backoff` verb does — no local attempt bookkeeping, no local backoff math.\n  let retry = initRetry();\n  for (;;) {\n    try {\n      return await port();\n    } catch (error) {\n      // Fold the failure first (attempt++), then consult the bound on the\n      // incremented state — same order as resilient-call so the semantics of\n      // `maxAttempts` are identical across both surfaces.\n      retry = recordFailure(retry, error);\n      if (!shouldRetry(retry, policy)) {\n        // Terminal give-up at the bound: reject, never swallow. `retry.attempt`\n        // is the number of failures = the number of port invocations made.\n        throw new RetryExhaustedError(retry.attempt, error);\n      }\n      await sleep(nextDelayMs(retry, policy, rng));\n    }\n  }\n}\n"]}

package/dist/{runtime-types-CiVpC0HN.d.ts → runtime-types-BKg2CGMx.d.ts}

@@ -1,10 +1,10 @@
-import { C as Cmd, S as Sub, M as Machine, R as RunHandlers, P as Port, N as NoCellError, i as Reducer, A as AnyCmdDef, j as Settled, c as CmdOf, k as Transitions, a as BuiltinSub, U as UpdateForm, l as Outcome, I as InterpretDetached, m as PortEmitter } from './core-BbgtiXdg.js';
+import { C as Cmd, c as Sub, M as Machine, R as RunHandlers, P as Port, N as NoCellError, g as Reducer, A as AnyCmdDef, h as Settled, a as CmdOf, i as Transitions, B as BuiltinSub, U as UpdateForm, O as Outcome, j as InterpretDetached, H as HandlerCtx } from './core-Ce9ncpuv.js';
 
 /**
  * @demlik/tea runtime interface surface + pure helpers — the public types,
  * interfaces, and construction/composition helpers the runtime (`./run`)
  * implements against: `Store`, the error-sink and supervision contracts, the
- * engine-neutral `RunHandle` / `BootedRunHandle` every engine's `run` returns,
+ * engine-neutral `RunHandle` / `BootedRunHandle` host adapters are typed on,
  * the Promise engine's `RuntimeRef` / `BootingRuntime` / `Runtime` handle
  * hierarchy that widens it, `definePort`, the
  * identity-typed constructors `defineMachine` / `asReducer`, and the pure tools
@@ -23,11 +23,19 @@ type Branded<T> = T & {
  * site. Strengthens invariant 7 (identity is explicit).
  *
  * @example
+ * ```ts
+ * import { absurd } from "@demlik/tea";
+ *
+ * type Msg = { type: "a" } | { type: "b" };
+ *
+ * function label(msg: Msg): string {
  *   switch (msg.type) {
- *     case "a": return ...;
- *     case "b": return ...;
+ *     case "a": return "A";
+ *     case "b": return "B";
  *     default: return absurd(msg);  // compile error if a "c" is added
  *   }
+ * }
+ * ```
  */
 declare function absurd(x: never): never;
 declare const noop: <S, M, C extends Cmd>(state: S, _msg: M) => readonly [S, readonly C[]];
@@ -76,6 +84,11 @@ declare function __resetPortRegistry(): void;
  * - `"port-emit"` — a `subscribePort` listener threw during a port emission.
  * - `"sub-cleanup"` — a subscription's cleanup threw (reconcile-removal or
  *   `stop()` teardown).
+ * - `"sub"` — a running Sub failed with an error it did not turn into a Msg:
+ *   its runner threw while starting, or (Effect engine) its Stream failed. The
+ *   run stops — on the Effect engine by closing its Scope with the failure. A
+ *   Sub that expects an error maps it to a Msg itself; there is no hook for it
+ *   here.
  * - `"discard"` — work lost to a teardown the host asked for. Two witnesses,
  *   both carrying a `RuntimeDiscardNotice`: `stop()` was called while interpret
  *   handlers were still awaiting (`RuntimeDiscardedError`), and a Msg that
@@ -94,7 +107,7 @@ declare function __resetPortRegistry(): void;
  * consumer sink that throws while handling a `"discard"` report inherits that
  * phase; keying the warn-only path on it would make the sink's own defect vanish.
  */
-type RuntimeErrorPhase = "follow-up" | "interpret" | "stop-save" | "reduce" | "listener" | "observer" | "event" | "boot" | "port-emit" | "sub-cleanup" | "discard" | "identity-drop";
+type RuntimeErrorPhase = "follow-up" | "interpret" | "stop-save" | "reduce" | "listener" | "observer" | "event" | "boot" | "port-emit" | "sub-cleanup" | "sub" | "discard" | "identity-drop";
 /**
  * What the `telemetry` sink passed to `run` receives, once per APPLIED
  * transition. Plain data, so a recorded stream stays durable.
@@ -303,7 +316,50 @@ declare function definePort<T>(name: string): Port<T>;
 interface Store<S> {
     load(): Promise<unknown>;
     save(state: S): Promise<void>;
-    migrate(raw: unknown): S | null;
+    migrate(raw: unknown): Migrated<S>;
+}
+/**
+ * What `Store.migrate` answers: the parsed `S`, `null` when nothing was saved,
+ * or a {@link Refusal} for saved bytes it cannot read.
+ */
+type Migrated<S> = S | null | Refusal;
+/**
+ * `migrate`'s answer for saved bytes it cannot read. Build one with
+ * {@link refuse}. A class, so no plain State object can pass for one.
+ */
+declare class Refusal {
+    readonly reason: string;
+    readonly _tag: "refusal";
+    constructor(reason: string);
+}
+/**
+ * Refuse saved bytes from `Store.migrate`. `run` then fails with a
+ * {@link StoreRefusedError} carrying `reason`, and writes nothing to the store.
+ *
+ * ```ts
+ * migrate: (raw) => {
+ *   if (raw === null) return null; // nothing saved: boot fresh
+ *   return isState(raw) ? raw : refuse("not a saved State");
+ * }
+ * ```
+ */
+declare function refuse(reason: string): Refusal;
+/**
+ * `ready` rejects with this when the saved state could not be restored:
+ * `migrate` returned {@link refuse}, or `load` / `migrate` threw (that throw is
+ * the `cause`). The run never booted and wrote nothing, so the stored bytes are
+ * unchanged.
+ *
+ * A host that wants a "couldn't restore" view catches it and starts its own run
+ * with no store; tea has no placeholder mode.
+ */
+declare class StoreRefusedError extends Error {
+    readonly reason: string;
+    readonly name = "StoreRefusedError";
+    readonly _tag: "store_refused";
+    constructor(reason: string, options?: {
+        readonly cause?: unknown;
+    });
 }
 interface FencedRead {
     /** Raw bytes at the key, the `Store.load` contract unchanged. */
@@ -337,6 +393,24 @@ interface FencedStore<S> extends Store<S> {
      */
     saveFenced(state: S, expectedVersion: number): Promise<number>;
 }
+/**
+ * A `Store<S>` that can remove what it saved — how a host forgets a run.
+ *
+ * The same optional widening as {@link FencedStore} (ADR 0017): `Store<S>` is
+ * unchanged, so every external implementor still compiles. `fileStore`,
+ * `memoryStore` and `doStore` return one, fenced and unfenced alike.
+ *
+ * After `delete()`, `load()` returns what a never-saved store returns, so the
+ * next `run` boots fresh. The store stays dumb about who deletes: an unfenced
+ * `save` after `delete()` simply writes the state again. A fenced store drops
+ * its version with the state, so a run still live on it is refused with a
+ * {@link StoreConflictError} at its next save. Deleting under a live run is the
+ * host's mistake to avoid.
+ */
+interface DeletableStore<S> extends Store<S> {
+    /** Remove the saved state. Idempotent: deleting nothing resolves. */
+    delete(): Promise<void>;
+}
 /** Narrow a `Store<S>` to a {@link FencedStore} — what `run` uses to decide. */
 declare function isFencedStore<S>(store: Store<S>): store is FencedStore<S>;
 /**
@@ -368,11 +442,11 @@ interface Schema<S> {
  * (job 2). `upcast` maps a recognized-but-OLD raw shape forward into the shape
  * the schema validates; it defaults to identity (no version migration yet).
  *
- * Never throws — a shape the schema rejects returns `null`, the substrate's
- * fresh-boot path, per the `Store.migrate` contract. An `upcast` that itself
- * throws on a corrupt blob is caught and collapses to `null` (same posture).
+ * Never throws. Nothing saved (`null` or `undefined`) returns `null`, the
+ * fresh-boot path. Saved bytes the schema rejects, or that make `upcast` throw,
+ * return a {@link refuse}, so `run` fails instead of booting fresh over them.
  */
-declare function schemaMigrate<S>(schema: Schema<S>, upcast?: (raw: unknown) => unknown): (raw: unknown) => S | null;
+declare function schemaMigrate<S>(schema: Schema<S>, upcast?: (raw: unknown) => unknown): (raw: unknown) => Migrated<S>;
 type DispatchSettle = "quiescent" | "once";
 interface RuntimeRef<M extends {
     type: string;
@@ -401,7 +475,7 @@ interface RuntimeRef<M extends {
     dispatchOnce(msg: M): Promise<void>;
 }
 /**
- * What an engine's `run` returns: queue a Msg, listen, wait for boot, stop.
+ * A running machine's handle: queue a Msg, listen, wait for boot, stop.
  * `getState` is not here — there is no State until boot runs, so it lives on
  * the {@link BootedRunHandle} that `ready` resolves to. `E` is the machine's
  * semantic event union (see `on`); `never` when the run projects none.
@@ -454,8 +528,8 @@ type RunOptions<S, M extends {
 /**
  * An engine's `run`, seen from a host adapter: a machine and its
  * {@link RunOptions} in, a {@link RunHandle} out. `useMachine` and
- * `createAgentHost` take one, so they run on whichever engine the caller
- * imported — `run` from `@demlik/tea/promise` fits it as it is.
+ * `createAgentHost` take one — `run` from `@demlik/tea/promise` fits it as it
+ * is.
  */
 type EngineRun<S, M extends {
     type: string;
@@ -683,7 +757,7 @@ declare function replay<S, M extends {
 };
 declare function wrapDetached<C extends Cmd, M extends {
     type: string;
-}, Allowed extends M, Ctx>(handler: InterpretDetached<C, Allowed, Ctx>): (cmd: C, ctx: Ctx & PortEmitter, dispatch?: (msg: M) => void) => Promise<void>;
+}, Allowed extends M, Ctx>(handler: InterpretDetached<C, Allowed, Ctx>): (cmd: C, ctx: HandlerCtx<Ctx>, dispatch?: (msg: M) => void) => Promise<void>;
 /**
  * `applyCell`, with "no handler for this Msg" moved into the return type
  * instead of a throw.
@@ -738,4 +812,4 @@ declare function tryFoldMsgs<S, M extends {
 }, base: S, msgs: readonly M[]): Outcome<S, FoldRefusal<M>>;
 declare function tryInterpret<C extends Cmd, Ok, M, Ctx>(work: (cmd: C, ctx: Ctx) => Promise<Ok>, onOk: (value: Ok, cmd: C) => M, onErr: (error: unknown, cmd: C) => M): (cmd: C, ctx: Ctx) => Promise<M>;
 
-export { replay as A, type BootingRuntime as B, type CtxArg as C, DispatchDiscardedError as D, type EngineRun as E, type FencedStore as F, schemaMigrate as G, tryApplyCell as H, IdentityDropNotice as I, tryFoldMsgs as J, tryInterpret as K, wrapDetached as L, type MachineTypes as M, type OnError as O, PortNameCollisionError as P, QuiescenceTimeoutError as Q, type Runtime as R, type Store as S, type TelemetrySink as T, __resetPortRegistry as _, type Supervision as a, type BootedRunHandle as b, type RunHandle as c, type Branded as d, type DispatchSettle as e, DisposeTimeoutNotice as f, DriveFailedError as g, DriveStalledError as h, type FencedRead as i, type FoldRefusal as j, type RunOptions as k, RuntimeDiscardNotice as l, RuntimeDiscardedError as m, type RuntimeErrorContext as n, type RuntimeErrorPhase as o, type RuntimeRef as p, type Schema as q, StoreConflictError as r, type SupervisionStrategy as s, type TelemetryEvent as t, absurd as u, asReducer as v, defineMachine as w, definePort as x, isFencedStore as y, noop as z };
+export { defineMachine as A, type BootingRuntime as B, type CtxArg as C, type DeletableStore as D, type EngineRun as E, type FencedStore as F, definePort as G, isFencedStore as H, IdentityDropNotice as I, noop as J, refuse as K, replay as L, type Migrated as M, schemaMigrate as N, type OnError as O, PortNameCollisionError as P, QuiescenceTimeoutError as Q, type Runtime as R, type Store as S, type TelemetrySink as T, tryApplyCell as U, tryFoldMsgs as V, tryInterpret as W, wrapDetached as X, __resetPortRegistry as _, type Supervision as a, type BootedRunHandle as b, type RunHandle as c, type Branded as d, DispatchDiscardedError as e, type DispatchSettle as f, DisposeTimeoutNotice as g, DriveFailedError as h, DriveStalledError as i, type FencedRead as j, type FoldRefusal as k, type MachineTypes as l, Refusal as m, type RunOptions as n, RuntimeDiscardNotice as o, RuntimeDiscardedError as p, type RuntimeErrorContext as q, type RuntimeErrorPhase as r, type RuntimeRef as s, type Schema as t, StoreConflictError as u, StoreRefusedError as v, type SupervisionStrategy as w, type TelemetryEvent as x, absurd as y, asReducer as z };

package/dist/testing/effect/index.d.ts

@@ -0,0 +1,65 @@
+import { D as DriveRoundsExceededError, a as DriveNoHandlerError, b as DriveOptions, c as DriveResult } from '../../drive-loop-CsUsW3Wo.js';
+export { d as DEFAULT_MAX_ROUNDS, e as DriveCtxArg, f as DriveTraceEntry, g as driveTraceOf } from '../../drive-loop-CsUsW3Wo.js';
+import { Effect } from 'effect';
+import { C as CellErrors, S as SubscribeOption, E as EffectInterpret, a as EffectSubscribe, I as InterpretServices, b as SubscribeServices } from '../../index-BnsAqn0-.js';
+import { C as Cmd, c as Sub, M as Machine } from '../../core-Ce9ncpuv.js';
+import '../../runtime-types-BKg2CGMx.js';
+import 'effect/Cause';
+import 'effect/Types';
+import '@standard-schema/spec';
+
+/**
+ * The Effect `drive`'s options: the Promise `drive`'s, plus `subscribe` — the
+ * runners the engine's `run` takes, required exactly when `run` requires them.
+ */
+type EffectDriveOptions<U extends Sub, Ctx, B> = DriveOptions<Ctx> & SubscribeOption<U, B>;
+/** The failures a drive ends with: the loop's own, and a hand-written cell's. */
+type EffectDriveError<M, C extends Cmd, I> = DriveRoundsExceededError<M, C> | DriveNoHandlerError<M, C> | CellErrors<C, I>;
+/**
+ * Drive `machine` from `initial` through `msg` against the REAL Effect
+ * `interpret` map — the one a host hands the Effect engine's `run` — and the
+ * Subs the machine wants, feeding every Msg back until the machine goes quiet.
+ * Yields the settled state together with the whole history, `{ state, trace }`.
+ *
+ * The rounds, the trace, `maxRounds` and `clock` are the Promise `drive`'s
+ * (`@demlik/tea/testing/promise`). What is the Effect engine's:
+ *
+ *   - a cell returns an Effect. A `Cmd.define`d Cmd's success mints `_ok` and
+ *     its declared failure `_err`; a hand-written Cmd's success is its
+ *     follow-up — a Msg, a list of them folded in order, or nothing (#324) —
+ *     and its failure fails the drive, typed. A defect dies. A cell takes no
+ *     `dispatch`, so a defined Cmd's handler cannot send its own `_ok` /
+ *     `_err`: the engine's rule holds by construction;
+ *   - the services the cells and runners read are this Effect's requirements,
+ *     so a test provides them the way a host does: `Effect.provide(layer)`;
+ *   - the Subs the machine wants run, through `opts.subscribe` or the engine's
+ *     built-in runner, started and stopped after every fold. Their Msgs are
+ *     folded once no Cmd's follow-up is pending. The drive settles once no Msg
+ *     is pending and no Sub is still running, so hand it a runner whose Stream
+ *     ends — a Sub that never ends keeps it waiting. A Stream that fails with
+ *     an error it did not map to a Msg dies, as it stops the engine's run.
+ *
+ * Interrupting the drive interrupts every cell and Sub still running.
+ *
+ * ```ts
+ * const { state, trace } = await Effect.runPromise(
+ *   drive(machine, initial, { type: "go" }, {
+ *     fetch: (cmd) =>
+ *       Effect.gen(function* () {
+ *         const api = yield* Api;
+ *         return yield* api.get(cmd.id);
+ *       }),
+ *   }).pipe(Effect.provide(ApiTest)),
+ * );
+ * ```
+ *
+ * Fails with {@link DriveRoundsExceededError} when the machine is still
+ * emitting work after `opts.maxRounds` rounds, {@link DriveNoHandlerError}
+ * for a Cmd no cell answers, or a hand-written cell's own failure — each with
+ * the partial trace, readable via `driveTraceOf`.
+ */
+declare function drive<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx, I extends EffectInterpret<M, C> = EffectInterpret<M, C, never>, B extends EffectSubscribe<M, U> = EffectSubscribe<M, U, never>>(machine: Machine<S, M, C, U, Ctx>, initial: S, msg: M, interpret: I, ...[opts]: Record<never, never> extends EffectDriveOptions<U, Ctx, B> ? [opts?: EffectDriveOptions<U, Ctx, B>] : [opts: EffectDriveOptions<U, Ctx, B>]): Effect.Effect<DriveResult<S, M, C>, EffectDriveError<M, C, I>, InterpretServices<I> | SubscribeServices<B>>;
+
+export { DriveNoHandlerError, DriveOptions, DriveResult, DriveRoundsExceededError, type EffectDriveError, type EffectDriveOptions, drive };