@demlik/tea 0.1.0 → 0.1.2

package/dist/agent/index.js

@@ -0,0 +1,20 @@
+export { COMPACTION_PURPOSE, agentBootMsg, agentEvents, agentTurnSchema, compactionSummarySchema, createAgent, isAgentTurn, isCompactionSummary, liftAgent, mergeInterpret, status } from '../chunk-S3FQN4SL.js';
+import '../chunk-7W4LMPUW.js';
+import '../chunk-PS23H6KQ.js';
+import '../chunk-EHIX7NYZ.js';
+import '../chunk-27N2SPTN.js';
+import '../chunk-JELSZN25.js';
+import '../chunk-UV6UWGEO.js';
+export { deadlineSub, subscribeDeadline } from '../chunk-K7Q23EQ4.js';
+import '../chunk-5VNWZADP.js';
+import '../chunk-2YOE5PIS.js';
+import '../chunk-SC3FAFZN.js';
+import '../chunk-IN33Q4VJ.js';
+import '../chunk-HJO6VNQI.js';
+import '../chunk-TGG26XMK.js';
+import '../chunk-NSDFA6M6.js';
+import '../chunk-2YFLOCWX.js';
+import '../chunk-MMH7CW5K.js';
+import '../chunk-QLA76GIT.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

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

package/dist/authed-call/index.d.ts

@@ -0,0 +1,119 @@
+import { c as PortEmitter, C as Cmd } from '../core-BoB6t7dB.js';
+import { M as MsgType } from '../protocol-B5YmJr0d.js';
+import { ResilientConfig, ResilientState, RunCmd, ResilientPorts, SucceedMsg, FailMsg, ResilientTimerMsg } from '../resilient-call/index.js';
+import { TokenRefreshConfig, Token, TokenState, RefreshTokenCmd, TokenRefreshMsg } from '../token-refresh/index.js';
+import { DeadlineSub } from '../deadline/index.js';
+export { DeadlineExceeded, deadlineSub, subscribeDeadline } from '../deadline/index.js';
+import '../cache/index.js';
+import '../types-B-8bcAp8.js';
+import '../circuit-breaker/index.js';
+import '../rate-limit/index.js';
+import '../retry-backoff/index.js';
+
+/**
+ * The authed-call knob. It is `ResilientConfig` widened by the token dimension:
+ *
+ *   - `refresh` — the ONLY required field: the port that mints a fresh `Token`.
+ *     Identical to token-refresh's `TokenRefreshPorts.refresh`; it is hoisted
+ *     onto the config (not the ports) so the consumer spells the credential
+ *     source once, the same way `rng` is curried onto the factory.
+ *   - `skewMs` — token-refresh's refresh-ahead skew (optional, defaults to 0).
+ *   - every `ResilientConfig` field (`retry` / `circuit` / `rateLimit` /
+ *     `cache` / `deadline`) — passed straight through to the resilient-call
+ *     knob, each still optional, each still "omit a brick → omit its gate".
+ */
+interface AuthedConfig extends ResilientConfig, TokenRefreshConfig {
+    /** Mint a fresh credential. The single DI seam the auth dimension adds. */
+    readonly refresh: () => Promise<Token>;
+}
+/**
+ * The composed slice. Three plain-data fields, no closures:
+ *
+ *   - `resilience` — resilient-call's entire slice (circuit, bucket, retry,
+ *     cache, calls). Owned and mutated only via resilient-call's verbs.
+ *   - `auth` — token-refresh's `{ token, stale }` slice. Owned and mutated only
+ *     via token-refresh's verbs.
+ *   - `authRetry` — per-key count of auth-retries (401 → refresh → retry) spent
+ *     on a call. Caps the dance at one retry per call so a credential the server
+ *     keeps rejecting cannot spin forever. A key absent from the record has
+ *     spent zero. Cleared when a call settles or a fresh `attempt` starts.
+ *
+ * `pendingAuthRetry` carries the inputs of calls parked waiting for the refresh
+ * to land, keyed so `onRefreshed` can re-issue exactly those calls. Plain data —
+ * `input` is the same payload the call was issued with.
+ */
+interface AuthedState<I, R> {
+    readonly resilience: ResilientState<I, R>;
+    readonly auth: TokenState;
+    readonly authRetry: Readonly<Record<string, number>>;
+    readonly pendingAuthRetry: Readonly<Record<string, I>>;
+}
+/** The two effects this knob emits: resilient-call's run, token-refresh's mint. */
+type AuthedCmd<I> = RunCmd<I> | RefreshTokenCmd;
+/**
+ * Every Msg the knob's verbs fold. Resilient-call's settle + timer Msgs, token-
+ * refresh's refresh-result Msgs, and the 401 trigger the consumer dispatches
+ * when a guarded call comes back unauthorized.
+ */
+type Unauthorized = {
+    readonly type: typeof MsgType.Unauthorized;
+    readonly key: string;
+    readonly at: number;
+};
+/**
+ * The plain-data error a 401 we cannot fix settles with. A `{_tag, ...}`
+ * sentinel — NEVER a `new Error(...)` — so the slice stays JSON-serializable
+ * (an Error object round-trips to `{}` under JSON and carries a stack trace,
+ * both of which break the slice's durability invariant once it is persisted
+ * into a `Store<S>` and reloaded). Mirrors resilient-call's `DeadlineExceededError`
+ * sentinel discipline. `key` echoes the call that was rejected so a consumer can
+ * attribute the failure.
+ */
+type UnauthorizedError = {
+    readonly _tag: "unauthorized";
+    readonly key: string;
+};
+/** Ports `handlers` needs — resilient-call's run port AND token-refresh's refresh port. */
+interface AuthedPorts<I, R> extends ResilientPorts<I, R> {
+    /** Mint a fresh credential. Mirrors `AuthedConfig.refresh` for symmetry at the splice site. */
+    readonly refresh: () => Promise<Token>;
+}
+/**
+ * Build an authed-call knob from `config`. `rng` is injected for retry jitter
+ * and threaded straight into the underlying resilient-call knob — pass a fixed
+ * `() => 0.5` in tests to pin backoff; defaults to `Math.random` (read only at
+ * the verb boundary inside resilient-call, never in a brick op).
+ *
+ * Returns the uniform L2 knob contract, widened by the auth verbs (`on401`,
+ * `onRefreshed`, `installToken`). `I` is the port input type, `R` the result.
+ */
+declare function createAuthedCall<I, R>(config: AuthedConfig, rng?: () => number): {
+    init: () => AuthedState<I, R>;
+    attempt: (s: AuthedState<I, R>, key: string, input: I, at: number) => readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]];
+    succeed: (s: AuthedState<I, R>, key: string, msg: SucceedMsg<R>) => readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]];
+    fail: (s: AuthedState<I, R>, key: string, msg: FailMsg) => readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]];
+    on401: (s: AuthedState<I, R>, key: string, at: number) => readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]];
+    installToken: (s: AuthedState<I, R>, token: Token) => AuthedState<I, R>;
+    onRefreshed: (s: AuthedState<I, R>, at: number) => readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]];
+    onTimer: (s: AuthedState<I, R>, msg: ResilientTimerMsg) => readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]];
+    /** token-refresh's call-boundary verb, re-exposed for proactive expiry refresh. */
+    needsRefresh: (s: AuthedState<I, R>, at: number) => boolean;
+    subs: (s: AuthedState<I, R>) => readonly DeadlineSub[];
+    handlers: (ports: AuthedPorts<I, R>) => {
+        refresh_token: (cmd: RefreshTokenCmd, ctx: PortEmitter) => Promise<void | TokenRefreshMsg>;
+        resilient_run: (cmd: RunCmd<I>, ctx: Readonly<Record<never, never>>) => Promise<FailMsg | SucceedMsg<R>>;
+    };
+};
+/** The shape `createAuthedCall` returns — useful for typing a held knob. */
+type AuthedCall<I, R> = ReturnType<typeof createAuthedCall<I, R>>;
+/**
+ * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the slice
+ * lives at `state.authed`. A convenience for the common single-slice host;
+ * consumers with a differently-named field spread by hand. Pure — a thin record
+ * rebuild, no clock / RNG.
+ */
+declare function liftAuthed<S extends {
+    authed: AuthedState<I, R>;
+}, I, R, C extends Cmd>(state: S, [slice, cmds]: readonly [AuthedState<I, R>, readonly C[]]): readonly [S, readonly C[]];
+
+export { type AuthedCall, type AuthedCmd, type AuthedConfig, type AuthedPorts, type AuthedState, DeadlineSub, FailMsg, ResilientState, ResilientTimerMsg, RunCmd, SucceedMsg, Token, TokenRefreshMsg, TokenState, type Unauthorized, type UnauthorizedError, createAuthedCall, liftAuthed };

package/dist/authed-call/index.js

@@ -0,0 +1,148 @@
+import { createTokenRefresh, refreshTokenCmd } from '../chunk-3XJWC7VW.js';
+import { createResilientCall } from '../chunk-27N2SPTN.js';
+import '../chunk-JELSZN25.js';
+export { deadlineSub, subscribeDeadline } from '../chunk-K7Q23EQ4.js';
+import '../chunk-5VNWZADP.js';
+import '../chunk-2YOE5PIS.js';
+import '../chunk-SC3FAFZN.js';
+import '../chunk-IN33Q4VJ.js';
+import '../chunk-NSDFA6M6.js';
+import '../chunk-2YFLOCWX.js';
+import '../chunk-MMH7CW5K.js';
+import '../chunk-QLA76GIT.js';
+
+// src/authed-call/index.ts
+function createAuthedCall(config, rng = Math.random) {
+  const rc = createResilientCall(config, rng);
+  const tr = createTokenRefresh({ skewMs: config.skewMs });
+  function init() {
+    return {
+      resilience: rc.init(),
+      auth: tr.init(),
+      authRetry: {},
+      pendingAuthRetry: {}
+    };
+  }
+  function liftResilient(s, [resilience, cmds]) {
+    return [{ ...s, resilience }, cmds];
+  }
+  function without(rec, key) {
+    const { [key]: _dropped, ...rest } = rec;
+    return rest;
+  }
+  function attempt(s, key, input, at) {
+    const cleared = {
+      ...s,
+      authRetry: without(s.authRetry, key),
+      pendingAuthRetry: without(s.pendingAuthRetry, key)
+    };
+    return liftResilient(
+      cleared,
+      rc.attempt(cleared.resilience, key, input, at)
+    );
+  }
+  function succeed(s, key, msg) {
+    const settled = {
+      ...s,
+      authRetry: without(s.authRetry, key),
+      pendingAuthRetry: without(s.pendingAuthRetry, key)
+    };
+    return liftResilient(settled, rc.succeed(settled.resilience, key, msg));
+  }
+  function fail(s, key, msg) {
+    const [resilience, cmds] = rc.fail(s.resilience, key, msg);
+    const next = settleAuthIfDone({ ...s, resilience }, key, resilience);
+    return [next, cmds];
+  }
+  function on401(s, key, at) {
+    const spent = s.authRetry[key] ?? 0;
+    const call = s.resilience.calls[key];
+    const input = call?.phase === "running" || call?.phase === "waiting_retry" ? call.input : void 0;
+    if (spent >= 1 || input === void 0) {
+      const error = { _tag: "unauthorized", key };
+      const [settled] = rc.settleFailed(s.resilience, key, error);
+      return [
+        {
+          ...s,
+          resilience: settled,
+          authRetry: without(s.authRetry, key),
+          pendingAuthRetry: without(s.pendingAuthRetry, key)
+        },
+        []
+      ];
+    }
+    return [
+      {
+        ...s,
+        auth: tr.on401(s.auth),
+        authRetry: { ...s.authRetry, [key]: spent + 1 },
+        pendingAuthRetry: { ...s.pendingAuthRetry, [key]: input }
+      },
+      [refreshTokenCmd()]
+    ];
+  }
+  function installToken(s, token) {
+    return { ...s, auth: tr.refreshed(s.auth, token) };
+  }
+  function onRefreshed(s, at) {
+    const parked = Object.entries(s.pendingAuthRetry);
+    if (parked.length === 0) return [s, []];
+    let resilience = s.resilience;
+    const cmds = [];
+    for (const [key, input] of parked) {
+      const [next, runCmds] = rc.attempt(resilience, key, input, at);
+      resilience = next;
+      cmds.push(...runCmds);
+    }
+    return [{ ...s, resilience, pendingAuthRetry: {} }, cmds];
+  }
+  function onTimer(s, msg) {
+    const [resilience, cmds] = rc.onTimer(s.resilience, msg);
+    const next = settleAuthIfDone({ ...s, resilience }, void 0, resilience);
+    return [next, cmds];
+  }
+  function settleAuthIfDone(s, onlyKey, resilience) {
+    let authRetry = s.authRetry;
+    let pendingAuthRetry = s.pendingAuthRetry;
+    const keys = onlyKey !== void 0 ? [onlyKey] : Object.keys(authRetry);
+    for (const key of keys) {
+      const phase = resilience.calls[key]?.phase;
+      if (phase === "succeeded" || phase === "failed") {
+        authRetry = without(authRetry, key);
+        pendingAuthRetry = without(pendingAuthRetry, key);
+      }
+    }
+    return { ...s, authRetry, pendingAuthRetry };
+  }
+  function subs(s) {
+    return rc.subs(s.resilience);
+  }
+  function handlers(ports) {
+    const trPorts = { refresh: ports.refresh };
+    return {
+      ...rc.handlers({ run: ports.run }),
+      ...tr.handlers(trPorts)
+    };
+  }
+  return {
+    init,
+    attempt,
+    succeed,
+    fail,
+    on401,
+    installToken,
+    onRefreshed,
+    onTimer,
+    /** token-refresh's call-boundary verb, re-exposed for proactive expiry refresh. */
+    needsRefresh: (s, at) => tr.needsRefresh(s.auth, at),
+    subs,
+    handlers
+  };
+}
+function liftAuthed(state, [slice, cmds]) {
+  return [{ ...state, authed: slice }, cmds];
+}
+
+export { createAuthedCall, liftAuthed };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/authed-call/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/authed-call/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/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 of the\n *     same name. 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 routes the refresh I/O through token-\n *     refresh's `refresh_token` handler.\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 only clock / network reads\n *     live in `handlers` (the effect boundary) — resilient-call's `run` port and\n *     token-refresh's `refresh` port.\n *\n * ## Typical wiring\n *\n *   const ac = createAuthedCall<string, Resp>({\n *     refresh: () => sdk.mintToken(),\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 *   init: () => [ac.init(), []],\n *   update: {\n *     fetch:   (s, m) => ac.attempt(s, m.key, m.input, m.at),\n *     call_ok: (s, m) => ac.succeed(s, m.key, m),\n *     call_err:(s, m) => ac.fail(s, m.key, m),\n *     got_401: (s, m) => ac.on401(s, m.key, m.at),\n *     token_refreshed: (s, m) => ac.onRefreshed(ac.installToken(s, m.token), m.at),\n *     retry_due: (s, m) => ac.onTimer(s, m),\n *   },\n *   subscriptions: (s) => ac.subs(s),\n *   subscribe: { deadline: subscribeDeadline },\n *   interpret: ac.handlers({ run: ctx.call, refresh: () => sdk.mintToken() }),\n */\n\nimport type { Cmd } from \"../index\";\nimport type { MsgType } from \"../protocol\";\nimport {\n  createResilientCall,\n  type DeadlineExceeded,\n  type DeadlineSub,\n  deadlineSub,\n  type FailMsg,\n  type ResilientConfig,\n  type ResilientPorts,\n  type ResilientState,\n  type ResilientTimerMsg,\n  type RunCmd,\n  type SucceedMsg,\n  subscribeDeadline,\n} from \"../resilient-call\";\nimport {\n  createTokenRefresh,\n  type RefreshTokenCmd,\n  refreshTokenCmd,\n  type Token,\n  type TokenRefreshConfig,\n  type TokenRefreshMsg,\n  type TokenRefreshPorts,\n  type TokenState,\n} from \"../token-refresh\";\n\n// ===========================================================================\n// Config — the knob. The resilient-call config PLUS the two token-refresh\n// fields. Every field optional except `refresh` (the credential is the whole\n// point: without a mint port there is nothing to authenticate with).\n// ===========================================================================\n\n/**\n * The authed-call knob. It is `ResilientConfig` widened by the token dimension:\n *\n *   - `refresh` — the ONLY required field: the port that mints a fresh `Token`.\n *     Identical to token-refresh's `TokenRefreshPorts.refresh`; it is hoisted\n *     onto the config (not the ports) so the consumer spells the credential\n *     source once, the same way `rng` is curried onto the factory.\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 */\nexport interface AuthedConfig extends ResilientConfig, TokenRefreshConfig {\n  /** Mint a fresh credential. The single DI seam the auth dimension adds. */\n  readonly refresh: () => Promise<Token>;\n}\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/** Ports `handlers` needs — resilient-call's run port AND token-refresh's refresh port. */\nexport interface AuthedPorts<I, R> extends ResilientPorts<I, R> {\n  /** Mint a fresh credential. Mirrors `AuthedConfig.refresh` for symmetry at the splice site. */\n  readonly refresh: () => Promise<Token>;\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  // Drop a key from a `Record` immutably.\n  function without<V>(\n    rec: Readonly<Record<string, V>>,\n    key: string,\n  ): Readonly<Record<string, V>> {\n    const { [key]: _dropped, ...rest } = rec;\n    return rest;\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: AuthedState<I, R> = {\n      ...s,\n      authRetry: without(s.authRetry, key),\n      pendingAuthRetry: without(s.pendingAuthRetry, key),\n    };\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 `key`: delegate to resilient-call (closes the breaker,\n   * fills the cache, resets retry) and clear this key's auth-retry bookkeeping —\n   * the call settled, so its 401 budget and any parked input are forgotten.\n   * PURE.\n   */\n  function succeed(\n    s: AuthedState<I, R>,\n    key: string,\n    msg: SucceedMsg<R>,\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    const settled: AuthedState<I, R> = {\n      ...s,\n      authRetry: without(s.authRetry, key),\n      pendingAuthRetry: without(s.pendingAuthRetry, key),\n    };\n    return liftResilient(settled, rc.succeed(settled.resilience, key, msg));\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 `fail`, 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    key: string,\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 [resilience, cmds] = rc.fail(s.resilience, key, msg);\n    const next = settleAuthIfDone({ ...s, resilience }, key, resilience);\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 carried for symmetry with the other verbs (the refresh Cmd\n   * itself carries no time; the refresh port stamps its own result Msg).\n   */\n  function on401(\n    s: AuthedState<I, R>,\n    key: string,\n    at: number,\n  ): readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]] {\n    void at; // carried for symmetry; the async refresh's result Msg stamps the clock.\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);\n      return [\n        {\n          ...s,\n          resilience: settled,\n          authRetry: without(s.authRetry, key),\n          pendingAuthRetry: without(s.pendingAuthRetry, key),\n        },\n        [],\n      ];\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 `token_refreshed` 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,\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    let authRetry = s.authRetry;\n    let pendingAuthRetry = s.pendingAuthRetry;\n    const keys = onlyKey !== undefined ? [onlyKey] : Object.keys(authRetry);\n    for (const key of keys) {\n      const phase = resilience.calls[key]?.phase;\n      if (phase === \"succeeded\" || phase === \"failed\") {\n        authRetry = without(authRetry, key);\n        pendingAuthRetry = without(pendingAuthRetry, key);\n      }\n    }\n    return { ...s, authRetry, pendingAuthRetry };\n  }\n\n  // === Subs ================================================================\n\n  /**\n   * Pre-wired subscriptions — exactly resilient-call's (retry + deadline timers\n   * keyed per call). The auth dimension arms NO timers: a refresh is a one-shot\n   * Cmd, not a recurring sub, and the parked-call re-issue is driven by the\n   * `token_refreshed` Msg, not a timer. Wire `subscribe: { deadline:\n   * subscribeDeadline }`.\n   */\n  function subs(s: AuthedState<I, R>): readonly DeadlineSub[] {\n    return rc.subs(s.resilience);\n  }\n\n  // === Handlers ============================================================\n\n  /**\n   * Pre-wired interpret handlers: resilient-call's `resilient_run` (wraps the\n   * `run` port) AND token-refresh's `refresh_token` (wraps the `refresh` port).\n   * Both route Ok/Err through `tryInterpret`, stamping `Date.now()` at the\n   * effect boundary — the only clock reads in the whole module. Assign to the\n   * machine's `interpret`:\n   *\n   *   interpret: ac.handlers({ run: ctx.call, refresh: () => sdk.mintToken() })\n   */\n  function handlers(ports: AuthedPorts<I, R>) {\n    const trPorts: TokenRefreshPorts = { refresh: ports.refresh };\n    return {\n      ...rc.handlers({ run: ports.run }),\n      ...tr.handlers(trPorts),\n    };\n  }\n\n  return {\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    subs,\n    handlers,\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 deadline Sub primitives (this knob's `subs` emits `DeadlineSub`s,\n * inherited from resilient-call) and the token-refresh Msg constructors a\n * consumer wires into their reducer, so the whole composition imports from one\n * subpath.\n */\nexport { subscribeDeadline, deadlineSub };\nexport type {\n  DeadlineSub,\n  DeadlineExceeded,\n  ResilientState,\n  TokenState,\n  Token,\n  TokenRefreshMsg,\n  SucceedMsg,\n  FailMsg,\n  ResilientTimerMsg,\n  RunCmd,\n};\n"]}

package/dist/await-terminal/index.d.ts

@@ -0,0 +1,99 @@
+import { Runtime, CtxArg } from '../index.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-BoB6t7dB.js';
+
+/**
+ * @demlik/tea/await-terminal — run a ONE-SHOT / decision-procedure machine to a
+ * terminal state and hand the caller a `Promise<State>` that resolves the moment
+ * the machine FIRST enters a terminal state.
+ *
+ * This is the ~10 lines both audit suitability probes hand-wired at their
+ * integration seam: a one-shot decision machine (a credibility check, an auth
+ * mint, a validation pass — run to a terminal state, then throw-or-proceed at the
+ * caller boundary) has no built-in "await the terminal", so each consumer re-wires
+ * a promise off `observe` that resolves when the state is terminal. This helper
+ * lifts that boilerplate into `@demlik/tea` once.
+ *
+ * It rides the EXISTING observation surface (`packages/tea/src/index.ts`) and adds
+ * NO new runtime capability:
+ *   - `runtime.getState()` (total on a booted `Runtime`) covers the
+ *     already-terminal-at-attach case — resolve synchronously rather than wait for
+ *     a transition that may never come.
+ *   - `runtime.observe((msg, state) => void): () => void` fires on EVERY transition
+ *     and returns an unsubscribe — the "first terminal transition" signal, detached
+ *     the instant it resolves (no leak, no busy-wait / polling loop).
+ *   - `runtime.stop()` is the teardown the fire-and-await `runToTerminal` owns.
+ *
+ * `isTerminal` is caller-supplied — tea has no built-in terminal-set concept and
+ * this helper does NOT invent one; the caller names their own terminal states.
+ *
+ * The optional `timeoutMs` is a plain caller-boundary timer (not an in-loop
+ * progress deadline — see `../deadline` / `../with-deadline` for that shape): it
+ * clears on resolve and REJECTS with the `instanceof`-checkable
+ * {@link TerminalTimeoutError} if the deadline elapses first, never silently
+ * resolving.
+ */
+
+/**
+ * Raised when `awaitTerminal` / `runToTerminal` is wired with a `timeoutMs` and
+ * the deadline elapses before any terminal state is reached. Follows the tea
+ * error dialect (`override readonly name`) and carries a `_tag` discriminant, so
+ * a caller can branch on it either by `instanceof` or on the tag — the timeout is
+ * a distinct, checkable rejection, never a silent resolve.
+ */
+declare class TerminalTimeoutError extends Error {
+    readonly timeoutMs: number;
+    readonly name = "TerminalTimeoutError";
+    readonly _tag: "TerminalTimeoutError";
+    constructor(timeoutMs: number);
+}
+/** Options shared by `awaitTerminal` and `runToTerminal`. */
+interface AwaitTerminalOptions {
+    /**
+     * Optional bounded deadline in milliseconds. When set, the returned promise
+     * REJECTS with {@link TerminalTimeoutError} if no terminal state is reached
+     * within the window; the timer is cleared on the resolve path so a resolved
+     * await never later rejects or leaves a dangling timer. Omit for an unbounded
+     * await (never rejects for time).
+     */
+    readonly timeoutMs?: number;
+}
+/**
+ * Attach to an ALREADY-RUNNING `Runtime<S, M, E>` and resolve with the terminal
+ * `S` on the first transition for which `isTerminal(state)` is true.
+ *
+ * If the runtime is ALREADY terminal at attach time (`isTerminal(getState())`),
+ * resolves immediately — it never hangs waiting for a transition that will not
+ * come. Otherwise it subscribes via `observe` and detaches that subscription the
+ * instant it resolves (or times out), so there is no observer leak and no
+ * further callbacks fire.
+ *
+ * @param runtime    a booted `Runtime` (from `await run(machine, opts).ready`).
+ * @param isTerminal caller-supplied terminal predicate over the machine's state.
+ * @param opts       optional bounded `timeoutMs` deadline (see {@link AwaitTerminalOptions}).
+ */
+declare function awaitTerminal<S, M extends {
+    type: string;
+}, E extends {
+    type: string;
+} = never>(runtime: Runtime<S, M, E>, isTerminal: (state: S) => boolean, opts?: AwaitTerminalOptions): Promise<S>;
+/**
+ * Fire-and-await convenience: `run()` the machine, dispatch the seed `msgs`, and
+ * resolve with the terminal state — then tear the runtime down (`runtime.stop()`)
+ * on BOTH the resolve and reject paths. Wraps {@link awaitTerminal}.
+ *
+ * The seed carries the machine's `ctx` (conditionally optional, exactly as
+ * `run`'s `ctx` — a pure machine omits it) and the `msgs` to dispatch once
+ * booted. A `timeoutMs` in `opts` bounds the await identically to `awaitTerminal`.
+ *
+ * @param machine    the machine to boot.
+ * @param seed       `{ ctx?, msgs }` — the boot context and the seed messages.
+ * @param isTerminal caller-supplied terminal predicate over the machine's state.
+ * @param opts       optional bounded `timeoutMs` deadline (see {@link AwaitTerminalOptions}).
+ */
+declare function runToTerminal<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, seed: CtxArg<Ctx> & {
+    readonly msgs: readonly M[];
+}, isTerminal: (state: S) => boolean, opts?: AwaitTerminalOptions): Promise<S>;
+
+export { type AwaitTerminalOptions, TerminalTimeoutError, awaitTerminal, runToTerminal };

package/dist/await-terminal/index.js

@@ -0,0 +1,75 @@
+import { run } from '../chunk-MMH7CW5K.js';
+import '../chunk-QLA76GIT.js';
+
+// src/await-terminal/index.ts
+var TerminalTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(
+      `@demlik/tea: awaitTerminal did not reach a terminal state within ${timeoutMs}ms \u2014 no transition satisfied isTerminal before the deadline.`
+    );
+    this.timeoutMs = timeoutMs;
+  }
+  name = "TerminalTimeoutError";
+  _tag = "TerminalTimeoutError";
+};
+function awaitTerminal(runtime, isTerminal, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const current = runtime.getState();
+    if (isTerminal(current)) {
+      resolve(current);
+      return;
+    }
+    let settled = false;
+    let timer;
+    let detach;
+    const cleanup = () => {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      if (detach !== void 0) {
+        detach();
+        detach = void 0;
+      }
+    };
+    detach = runtime.observe((_msg, state) => {
+      if (settled) return;
+      if (isTerminal(state)) {
+        settled = true;
+        cleanup();
+        resolve(state);
+      }
+    });
+    const timeoutMs = opts.timeoutMs;
+    if (timeoutMs !== void 0) {
+      timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(new TerminalTimeoutError(timeoutMs));
+      }, timeoutMs);
+    }
+  });
+}
+async function runToTerminal(machine, seed, isTerminal, opts = {}) {
+  const { msgs, ...ctxArg } = seed;
+  const runtime = await run(
+    machine,
+    ctxArg
+  ).ready;
+  try {
+    const terminal = awaitTerminal(runtime, isTerminal, opts);
+    const seeding = Promise.all(msgs.map((msg) => runtime.dispatch(msg)));
+    const state = await Promise.race([terminal, seeding.then(() => terminal)]);
+    await runtime.stop();
+    return state;
+  } catch (err) {
+    await runtime.stop().catch(() => {
+    });
+    throw err;
+  }
+}
+
+export { TerminalTimeoutError, awaitTerminal, runToTerminal };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/await-terminal/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/await-terminal/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/await-terminal — run a ONE-SHOT / decision-procedure machine to a\n * terminal state and hand the caller a `Promise<State>` that resolves the moment\n * the machine FIRST enters a terminal state.\n *\n * This is the ~10 lines both audit suitability probes hand-wired at their\n * integration seam: a one-shot decision machine (a credibility check, an auth\n * mint, a validation pass — run to a terminal state, then throw-or-proceed at the\n * caller boundary) has no built-in \"await the terminal\", so each consumer re-wires\n * a promise off `observe` that resolves when the state is terminal. This helper\n * lifts that boilerplate into `@demlik/tea` once.\n *\n * It rides the EXISTING observation surface (`packages/tea/src/index.ts`) and adds\n * NO new runtime capability:\n *   - `runtime.getState()` (total on a booted `Runtime`) covers the\n *     already-terminal-at-attach case — resolve synchronously rather than wait for\n *     a transition that may never come.\n *   - `runtime.observe((msg, state) => void): () => void` fires on EVERY transition\n *     and returns an unsubscribe — the \"first terminal transition\" signal, detached\n *     the instant it resolves (no leak, no busy-wait / polling loop).\n *   - `runtime.stop()` is the teardown the fire-and-await `runToTerminal` owns.\n *\n * `isTerminal` is caller-supplied — tea has no built-in terminal-set concept and\n * this helper does NOT invent one; the caller names their own terminal states.\n *\n * The optional `timeoutMs` is a plain caller-boundary timer (not an in-loop\n * progress deadline — see `../deadline` / `../with-deadline` for that shape): it\n * clears on resolve and REJECTS with the `instanceof`-checkable\n * {@link TerminalTimeoutError} if the deadline elapses first, never silently\n * resolving.\n */\n\nimport {\n  type Cmd,\n  type CtxArg,\n  type Machine,\n  type Runtime,\n  run,\n  type Sub,\n} from \"../index\";\n\n/**\n * Raised when `awaitTerminal` / `runToTerminal` is wired with a `timeoutMs` and\n * the deadline elapses before any terminal state is reached. Follows the tea\n * error dialect (`override readonly name`) and carries a `_tag` discriminant, so\n * a caller can branch on it either by `instanceof` or on the tag — the timeout is\n * a distinct, checkable rejection, never a silent resolve.\n */\nexport class TerminalTimeoutError extends Error {\n  override readonly name = \"TerminalTimeoutError\";\n  readonly _tag = \"TerminalTimeoutError\" as const;\n  constructor(public readonly timeoutMs: number) {\n    super(\n      `@demlik/tea: awaitTerminal did not reach a terminal state within ` +\n        `${timeoutMs}ms — no transition satisfied isTerminal before the deadline.`,\n    );\n  }\n}\n\n/** Options shared by `awaitTerminal` and `runToTerminal`. */\nexport interface AwaitTerminalOptions {\n  /**\n   * Optional bounded deadline in milliseconds. When set, the returned promise\n   * REJECTS with {@link TerminalTimeoutError} if no terminal state is reached\n   * within the window; the timer is cleared on the resolve path so a resolved\n   * await never later rejects or leaves a dangling timer. Omit for an unbounded\n   * await (never rejects for time).\n   */\n  readonly timeoutMs?: number;\n}\n\n/**\n * Attach to an ALREADY-RUNNING `Runtime<S, M, E>` and resolve with the terminal\n * `S` on the first transition for which `isTerminal(state)` is true.\n *\n * If the runtime is ALREADY terminal at attach time (`isTerminal(getState())`),\n * resolves immediately — it never hangs waiting for a transition that will not\n * come. Otherwise it subscribes via `observe` and detaches that subscription the\n * instant it resolves (or times out), so there is no observer leak and no\n * further callbacks fire.\n *\n * @param runtime    a booted `Runtime` (from `await run(machine, opts).ready`).\n * @param isTerminal caller-supplied terminal predicate over the machine's state.\n * @param opts       optional bounded `timeoutMs` deadline (see {@link AwaitTerminalOptions}).\n */\nexport function awaitTerminal<\n  S,\n  M extends { type: string },\n  E extends { type: string } = never,\n>(\n  runtime: Runtime<S, M, E>,\n  isTerminal: (state: S) => boolean,\n  opts: AwaitTerminalOptions = {},\n): Promise<S> {\n  return new Promise<S>((resolve, reject) => {\n    // Already-terminal-at-attach: resolve now. Returning here attaches neither an\n    // observer nor a timer, so the immediate case cannot leak either.\n    const current = runtime.getState();\n    if (isTerminal(current)) {\n      resolve(current);\n      return;\n    }\n\n    let settled = false;\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let detach: (() => void) | undefined;\n\n    const cleanup = (): void => {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      if (detach !== undefined) {\n        detach();\n        detach = undefined;\n      }\n    };\n\n    detach = runtime.observe((_msg, state) => {\n      if (settled) return;\n      if (isTerminal(state)) {\n        settled = true;\n        cleanup();\n        resolve(state);\n      }\n    });\n\n    // Narrow into a const so the closure keeps the `number` narrowing (the field\n    // itself is `number | undefined`).\n    const timeoutMs = opts.timeoutMs;\n    if (timeoutMs !== undefined) {\n      timer = setTimeout(() => {\n        if (settled) return;\n        settled = true;\n        cleanup();\n        reject(new TerminalTimeoutError(timeoutMs));\n      }, timeoutMs);\n    }\n  });\n}\n\n/**\n * Fire-and-await convenience: `run()` the machine, dispatch the seed `msgs`, and\n * resolve with the terminal state — then tear the runtime down (`runtime.stop()`)\n * on BOTH the resolve and reject paths. Wraps {@link awaitTerminal}.\n *\n * The seed carries the machine's `ctx` (conditionally optional, exactly as\n * `run`'s `ctx` — a pure machine omits it) and the `msgs` to dispatch once\n * booted. A `timeoutMs` in `opts` bounds the await identically to `awaitTerminal`.\n *\n * @param machine    the machine to boot.\n * @param seed       `{ ctx?, msgs }` — the boot context and the seed messages.\n * @param isTerminal caller-supplied terminal predicate over the machine's state.\n * @param opts       optional bounded `timeoutMs` deadline (see {@link AwaitTerminalOptions}).\n */\nexport async function runToTerminal<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  seed: CtxArg<Ctx> & { readonly msgs: readonly M[] },\n  isTerminal: (state: S) => boolean,\n  opts: AwaitTerminalOptions = {},\n): Promise<S> {\n  // Split the seed messages out from the boot context: `run`'s opts don't carry\n  // `msgs`, so what remains is exactly the conditionally-optional `ctx` arg. The\n  // cast is because `CtxArg<Ctx>` is a deferred generic conditional TS won't\n  // verify against `run`'s all-optional opts (its weak-type check) — the value\n  // is structurally valid; `run` defaults an absent `ctx` to `{}`.\n  const { msgs, ...ctxArg } = seed;\n  const runtime = await run<S, M, C, U, Ctx>(\n    machine,\n    ctxArg as Parameters<typeof run<S, M, C, U, Ctx>>[1],\n  ).ready;\n  try {\n    // Attach the terminal await BEFORE dispatching so a terminal transition that\n    // lands during a seed dispatch is caught (and the immediate-terminal check\n    // inside awaitTerminal covers a machine that boots already terminal).\n    const terminal = awaitTerminal(runtime, isTerminal, opts);\n    // Dispatch runs serially on the runtime's tail; fire all seeds and let a\n    // dispatch failure (a reducer/interpret throw) surface by racing it against\n    // the terminal await rather than floating as an unhandled rejection.\n    const seeding = Promise.all(msgs.map((msg) => runtime.dispatch(msg)));\n    const state = await Promise.race([terminal, seeding.then(() => terminal)]);\n    await runtime.stop();\n    return state;\n  } catch (err) {\n    // Tear down on the reject path too (timeout, dispatch failure) — a rejected\n    // runToTerminal never leaves the runtime running.\n    await runtime.stop().catch(() => {});\n    throw err;\n  }\n}\n"]}