@demlik/tea 0.13.0 → 0.15.0

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

@@ -1 +0,0 @@
-{"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 { without } from \"../pure/core\";\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  // 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 `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 = clearAuthKey(s, key);\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 [{ ...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 `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    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  // === 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

@@ -1,101 +0,0 @@
-import { R as Runtime, C as CtxArg } from '../runtime-types-CNLmhWif.js';
-import { C as Cmd, S as Sub, M as Machine } from '../core-Co0LWkIA.js';
-import 'better-result';
-import 'zod';
-
-/**
- * @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

@@ -1,76 +0,0 @@
-import { run } from '../chunk-ZSUUOEPL.js';
-import '../chunk-OOYD44JI.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;
-  }
-  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

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

package/dist/batch-window/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/batch-window/index.ts"],"names":[],"mappings":";;;;;;;AA2IO,SAAS,eAAA,GAAqC;AACnD,EAAA,OAAO,EAAE,MAAA,EAAQ,EAAC,EAAG,UAAU,IAAA,EAAK;AACtC;AAqBO,SAAS,kBAAA,CACd,IACA,IAAA,EACoB;AACpB,EAAA,OAAO,gBAAA,CAAiB,IAAI,IAAI,CAAA;AAClC;AAkEO,SAAS,OAAA,CACd,MAAA,EACA,KAAA,EACA,IAAA,EACA,EAAA,EACyC;AACzC,EAAA,MAAM,MAAA,GAAS,CAAC,GAAG,KAAA,CAAM,QAAQ,IAAI,CAAA;AAGrC,EAAA,MAAM,QAAA,GAAW,MAAM,QAAA,IAAY,EAAA;AAInC,EAAA,IAAI,OAAO,MAAA,IAAU,IAAA,CAAK,IAAI,CAAA,EAAG,MAAA,CAAO,QAAQ,CAAA,EAAG;AACjD,IAAA,OAAO,CAAC,iBAAmB,EAAG,CAAC,OAAO,KAAA,CAAM,MAAM,CAAC,CAAC,CAAA;AAAA,EACtD;AAEA,EAAA,OAAO,CAAC,EAAE,MAAA,EAAQ,QAAA,EAAS,EAAG,EAAE,CAAA;AAClC;AAuBO,SAAS,QAAA,CACd,MAAA,EACA,KAAA,EACA,GAAA,EACyC;AAGzC,EAAA,IAAI,KAAA,CAAM,OAAO,MAAA,KAAW,CAAA,SAAU,CAAC,KAAA,EAAO,EAAE,CAAA;AAChD,EAAA,OAAO,CAAC,iBAAmB,EAAG,CAAC,OAAO,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAC,CAAA;AAC5D;AAqBO,SAAS,OAAA,CACd,MAAA,EACA,KAAA,EACA,EAAA,GAAK,cAAA,EACsB;AAK3B,EAAA,IAAI,KAAA,CAAM,QAAA,KAAa,IAAA,EAAM,OAAO,EAAC;AACrC,EAAA,OAAO,CAAC,WAAA,CAAY,EAAA,EAAI,MAAM,QAAA,GAAW,MAAA,CAAO,KAAK,CAAC,CAAA;AACxD;AAQO,IAAM,oBAAA,GAIT;AAYG,SAAS,kBACd,MAAA,EACuB;AACvB,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,MAAM,eAAA,EAAmB;AAAA,IAC/B,GAAA,EAAK,CAAC,KAAA,EAAO,IAAA,EAAM,OAAO,OAAA,CAAQ,MAAA,EAAQ,KAAA,EAAO,IAAA,EAAM,EAAE,CAAA;AAAA,IACzD,UAAU,CAAC,KAAA,EAAO,OAAO,QAAA,CAAS,MAAA,EAAQ,KAAS,CAAA;AAAA,IACnD,MAAM,CAAC,KAAA,EAAO,OAAO,OAAA,CAAQ,MAAA,EAAQ,OAAO,EAAE,CAAA;AAAA,IAC9C,QAAA,EAAU,OAAO,EAAE,QAAA,EAAU,oBAAA,EAAqB;AAAA,GACpD;AACF","file":"index.js","sourcesContent":["/**\n * @demlik/tea/batch-window — coalesce a stream of items into size- or\n * time-bounded BATCHES, then flush each batch as a single Cmd.\n *\n * What this module actually DELEGATES to, vs. what it merely RE-EXPORTS:\n *\n *   - `../deadline` — REAL delegation (the only one). The window timer IS a\n *     `deadline` Sub: `subsFor` returns `deadlineSub` keyed on the window's\n *     identity, the subscribe cell is `subscribeDeadline` verbatim, and the\n *     expiry Msg is `deadlineExceeded`. Nothing about the timer is redrawn here.\n *     \"Fire at an absolute instant, even across a rehydrate\" is exactly\n *     `deadline`'s absolute-target lifecycle: a late subscribe (post-`Store`\n *     rehydrate) recomputes the remaining delay from the current clock and still\n *     fires at the correct moment.\n *   - `../work-queue` — TYPE re-export only, NOT a sink this module calls. A\n *     flush emits a Cmd; the CONSUMER's interpret handler is what enqueues onto a\n *     `createQueue(store)`. This module never touches queue status — it has no\n *     queue state and no status flip to delegate. It re-exports `EnqueueInput<I>`\n *     purely so the consumer's flush Cmd and queue agree on the item shape; any\n *     actual status flip belongs in the consumer and is delegated to\n *     `../work-queue/ops` there, not here.\n *   - `../debounce` — VALUE/TYPE re-export only, NOT wired into `update`. A\n *     bursty source (keystrokes, scroll, websocket frames) can be `debounce`d at\n *     the host BEFORE it ever becomes an `add` Msg, so the batch window only sees\n *     settled items. `debounce` is a sink transformer OUTSIDE `update`;\n *     batch-window is the durable, replayable half inside it. Re-exported for\n *     one-import ergonomics — this module does not call it.\n *\n * Why this is a knob and not hand-wired logic: the managed state (the buffer +\n * the window-open instant) lives in the Model, so it survives DO eviction /\n * reload (durable) and every transition is still a Msg through `update`\n * (replayable). A closure holding a `setTimeout` and a mutable array would break\n * both — banned. `add` / `onWindow` are PURE: time arrives as an `at`\n * parameter, never `Date.now()`; they return NEW slice values, never mutate.\n *\n * Typical wiring (combinator form):\n *\n *   const bw = createBatchWindow<LogLine, Msg>({\n *     maxItems: 100,\n *     maxMs: 5_000,\n *     flush: (items) => ({ type: \"FlushBatch\", items }),\n *   });\n *\n *   // Model:        { batch: BatchWindow<LogLine>, ... }\n *   // init:         (loaded) => [loaded ?? { batch: bw.init(), ... }, []]\n *   // update cells:\n *   //   LogArrived:   (s, m) => mapBatch(s, bw.add(s.batch, m.line, m.at))\n *   //   WindowFired:  (s, m) => mapBatch(s, bw.onWindow(s.batch, m.atMs))\n *   // subscriptions: (s) => bw.subs(s.batch)\n *   // subscribe:     { ...bw.handlers() }\n *\n * where `mapBatch(s, [batch, cmds]) => [{ ...s, batch }, cmds]` lifts the slice\n * transition into the consumer's Model. The `FlushBatch` Cmd's interpret handler\n * is the consumer's — it is where the batch meets I/O (an `enqueue`, a network\n * POST, an R2 write).\n *\n * NOT exported from the package root — reached via the `@demlik/tea/batch-window`\n * subpath, same one-shape-per-package rule as `deadline`, `cache`, and\n * `work-queue`.\n */\n\nimport type { Cmd } from \"../index\";\n\n// `../debounce` re-export (value + type) for one-import ergonomics — see file\n// header. This module does NOT call debounce; a consumer that wants to debounce\n// a bursty source BEFORE it becomes an `add` Msg reaches it from the same import\n// as the batch window.\nexport { type Debounced, debounce } from \"../debounce\";\n\nimport {\n  type DeadlineExceeded,\n  type DeadlineSub,\n  deadlineExceeded,\n  deadlineSub,\n  subscribeDeadline,\n} from \"../deadline\";\nimport type { SubscribeHandler } from \"../subs/types\";\n\n// `../work-queue` TYPE re-export only (see file header). This module emits a\n// flush Cmd; the CONSUMER's interpret handler enqueues onto a\n// `createQueue(store)`. Re-export the caller-facing enqueue payload type so the\n// consumer's flush Cmd and queue agree on the item shape.\nexport type { EnqueueInput } from \"../work-queue\";\n\n/**\n * Configuration for a batch window — the knob. Pure config, no mutable state\n * (the `BatchWindow<I>` slice carries that). One config object is shared across\n * every window of one logical stream (often a module-scope const).\n *\n * `flush` is a pure Cmd CONSTRUCTOR, not a closure-with-state: it maps the\n * buffered items to the single Cmd the runtime performs when a window closes.\n * Keeping it a `(items) => Cmd` (not a `(items) => void`) is what keeps the\n * trigger replayable — the flush is a Cmd in the transition's output, never a\n * side effect inside the verb.\n */\nexport interface BatchWindowConfig<I, C extends Cmd> {\n  /**\n   * Size trigger. A batch flushes the instant its buffer reaches `maxItems`,\n   * WITHOUT waiting for the time window — the classic \"send as soon as the\n   * page is full\" cutoff. Must be `>= 1`; a config of `maxItems: 0` would flush\n   * an empty batch on every `add`, which is never useful, so callers treat `1`\n   * as the floor (the verb still behaves: with `maxItems <= 1` every item\n   * flushes on arrival, a degenerate but legal \"no batching\" window).\n   */\n  readonly maxItems: number;\n  /**\n   * Time trigger, in milliseconds. A batch flushes no later than `openedAt +\n   * maxMs` — `openedAt` being the `at` of the item that opened the window. This\n   * is the latency ceiling: an item never waits longer than `maxMs` to ship,\n   * even if the buffer never reaches `maxItems`.\n   */\n  readonly maxMs: number;\n  /**\n   * Map a flushed batch to the single Cmd the runtime performs. Called with the\n   * buffered items in arrival order; the returned Cmd is what `add` / `onWindow`\n   * emit when a window closes. PURE constructor — no I/O, no clock; the I/O\n   * happens later in the consumer's interpret handler for the returned Cmd.\n   */\n  readonly flush: (items: readonly I[]) => C;\n}\n\n/**\n * The Model slice a batch window owns. `buffer` is the items accumulated for the\n * current open window; `openedAt` is the `at` of the item that OPENED it (the\n * anchor the time trigger measures against), or `null` when the window is\n * closed (buffer empty). The pair is the single source of truth for \"is a\n * window open, and when must it flush by?\" — both plain data so the whole slice\n * is trivially JSON-serializable into a consumer's `Store<S>`.\n *\n * Invariant the verbs preserve: `buffer.length === 0` IFF `openedAt === null`.\n * A non-empty buffer always has an `openedAt`; an empty buffer never does. The\n * window timer Sub keys its arm/disarm off exactly this invariant.\n */\nexport interface BatchWindow<I> {\n  readonly buffer: readonly I[];\n  readonly openedAt: number | null;\n}\n\n/** The starting slice: closed window, empty buffer. */\nexport function initBatchWindow<I>(): BatchWindow<I> {\n  return { buffer: [], openedAt: null };\n}\n\n/**\n * The Sub a batch window's open timer produces: it IS `../deadline`'s\n * `DeadlineSub`, not a re-tagged copy. `atMs` is the absolute flush-by instant\n * (`openedAt + maxMs`). Aliasing the deadline type (rather than redeclaring an\n * identical shape) is what lets `subsFor` return `deadlineSub(...)` with no\n * cast — the value's static type already satisfies this name. Consumers running\n * several windows route each one by the Sub's `id`, not by a distinct type.\n */\nexport type BatchWindowSub = DeadlineSub;\n\n/** The Msg a closed-by-time window dispatches. Alias of `deadline`'s Msg. */\nexport type BatchWindowExpired = DeadlineExceeded;\n\n/**\n * Construct the window-expired Msg for the window identified by `id`, flushing\n * by `atMs`. Re-exported alias of `deadlineExceeded` so the subscribe cell and\n * the consumer's reducer share one constructor rather than two literals that\n * can drift. The consumer handles it in a reducer cell by calling `onWindow`.\n */\nexport function batchWindowExpired(\n  id: string,\n  atMs: number,\n): BatchWindowExpired {\n  return deadlineExceeded(id, atMs);\n}\n\n/**\n * The bound knob returned by `createBatchWindow`. `init` + the two pure verbs +\n * `subs` + `handlers`, all closing over one `BatchWindowConfig`. The verbs\n * return `readonly [BatchWindow<I>, readonly C[]]`: the next slice and the Cmds\n * to emit (one `flush` Cmd when a window closes, none otherwise).\n */\nexport interface BatchWindowKnob<I, C extends Cmd> {\n  /** The starting slice — `initBatchWindow()`. */\n  init(): BatchWindow<I>;\n  /**\n   * Buffer `item` (arrival-stamped `at`), flushing immediately if that brings\n   * the buffer to `maxItems`. See `addItem`.\n   */\n  add(\n    state: BatchWindow<I>,\n    item: I,\n    at: number,\n  ): readonly [BatchWindow<I>, readonly C[]];\n  /**\n   * Flush whatever is buffered because the time window closed. See `onWindow`.\n   */\n  onWindow(\n    state: BatchWindow<I>,\n    at: number,\n  ): readonly [BatchWindow<I>, readonly C[]];\n  /**\n   * The window timer Sub, armed only while a window is open. See `subsFor`.\n   * `id` keys the deadline so several windows on one machine route distinctly.\n   */\n  subs(state: BatchWindow<I>, id?: string): readonly BatchWindowSub[];\n  /**\n   * The `subscribe` cells this knob splices into `machine.subscribe`. One cell,\n   * keyed `\"deadline\"`, delegating to `../deadline`'s subscribe handler. Spread\n   * into the consumer's subscribe map: `subscribe: { ...bw.handlers() }`.\n   */\n  handlers(): {\n    deadline: SubscribeHandler<BatchWindowSub, BatchWindowExpired, unknown>;\n  };\n}\n\n/**\n * Buffer `item` and decide whether the size trigger fires. PURE.\n *\n * - Empty (closed) window → `item` OPENS it: `openedAt` becomes `at`, buffer\n *   becomes `[item]`. This is the anchor the time window measures against.\n * - Open window → `item` appends; `openedAt` is left untouched (the window's\n *   latency clock keeps running from the FIRST item, not this one).\n *\n * After buffering, if the buffer has reached `maxItems` the window flushes\n * immediately: emit `config.flush(buffer)` and RESET to the closed slice. The\n * size trigger pre-empts the time trigger — a full page ships now, the window\n * Sub for the (now closed) window disarms on the next reconcile because `subs`\n * returns `[]` for an empty buffer.\n *\n * `maxItems <= 1` is the degenerate \"no batching\" case: every item flushes on\n * arrival (buffer reaches 1 immediately). Legal and useful as a feature flag to\n * disable batching without restructuring the wiring.\n *\n * @param config the knob (maxItems / flush constructor)\n * @param state  the current slice\n * @param item   the item to buffer\n * @param at     the arrival instant (epoch ms) — the caller stamps it; the verb\n *               never reads the clock\n */\nexport function addItem<I, C extends Cmd>(\n  config: BatchWindowConfig<I, C>,\n  state: BatchWindow<I>,\n  item: I,\n  at: number,\n): readonly [BatchWindow<I>, readonly C[]] {\n  const buffer = [...state.buffer, item];\n  // A closed window opens at THIS item's `at`; an already-open window keeps its\n  // original `openedAt` (the latency clock runs from the first item).\n  const openedAt = state.openedAt ?? at;\n\n  // Size trigger: a full page ships now, regardless of the time window. The\n  // floor of 1 means `maxItems <= 1` flushes every item on arrival.\n  if (buffer.length >= Math.max(1, config.maxItems)) {\n    return [initBatchWindow<I>(), [config.flush(buffer)]];\n  }\n\n  return [{ buffer, openedAt }, []];\n}\n\n/**\n * Flush the open window because its time bound was reached. PURE.\n *\n * - Open window (buffer non-empty) → emit `config.flush(buffer)` and RESET to\n *   the closed slice.\n * - Closed window (buffer empty) → no-op: return the same slice and no Cmds.\n *   This guards the race where the size trigger already flushed and reset the\n *   window before the time Sub's Msg lands — a stale `onWindow` after a\n *   size-flush must NOT emit an empty batch.\n *\n * `at` is accepted for symmetry with `add` and so the consumer's reducer cell\n * has a uniform `(state, at)` shape; the verb doesn't need it for the flush\n * decision (the buffer's emptiness is the whole signal), but taking it keeps a\n * future \"flush only if the window is genuinely past `openedAt + maxMs`\"\n * tightening a non-breaking change.\n *\n * @param config the knob (flush constructor)\n * @param state  the current slice\n * @param at     the firing instant (epoch ms) — the caller stamps it; the verb\n *               never reads the clock\n */\nexport function onWindow<I, C extends Cmd>(\n  config: BatchWindowConfig<I, C>,\n  state: BatchWindow<I>,\n  _at: number,\n): readonly [BatchWindow<I>, readonly C[]] {\n  // Empty buffer = the size trigger already flushed (or nothing arrived). A\n  // stale timer Msg must not ship an empty batch — return the slice untouched.\n  if (state.buffer.length === 0) return [state, []];\n  return [initBatchWindow<I>(), [config.flush(state.buffer)]];\n}\n\n/**\n * The window timer Sub, derived from the slice. PURE.\n *\n * Returns the single `deadline` Sub targeting `openedAt + maxMs` while a window\n * is open (buffer non-empty), or `[]` while it is closed. The substrate's\n * reconcile pass arms the timer when the array gains the Sub and disarms it\n * (clearing the pending `setTimeout`) when the array loses it — so a size-flush\n * that empties the buffer auto-cancels the now-irrelevant time trigger on the\n * next transition.\n *\n * `id` defaults to `\"batch-window\"`; pass a distinct id per window when a\n * machine runs several so the dispatched `BatchWindowExpired` Msg (and its\n * reconcile identity) routes to the right one.\n *\n * @param config the knob (maxMs)\n * @param state  the current slice\n * @param id     stable identity for this window's timer (default\n *               `\"batch-window\"`)\n */\nexport function subsFor<I, C extends Cmd>(\n  config: BatchWindowConfig<I, C>,\n  state: BatchWindow<I>,\n  id = \"batch-window\",\n): readonly BatchWindowSub[] {\n  // Closed window → no timer. The invariant (empty buffer IFF openedAt null)\n  // means either check suffices; we read `openedAt` so the `atMs` arithmetic\n  // below is non-null without a `!`. `deadlineSub` already returns a\n  // `DeadlineSub`, which IS `BatchWindowSub` — no cast.\n  if (state.openedAt === null) return [];\n  return [deadlineSub(id, state.openedAt + config.maxMs)];\n}\n\n/**\n * The `subscribe[\"deadline\"]` cell for a batch window's timer — the exact\n * `../deadline` handler. Arms a one-shot timer for `max(0, atMs - now)` and\n * dispatches `batchWindowExpired(...)`; returns a cleanup that clears it. The\n * consumer assigns it via the knob's `handlers()`.\n */\nexport const subscribeBatchWindow: SubscribeHandler<\n  BatchWindowSub,\n  BatchWindowExpired,\n  unknown\n> = subscribeDeadline;\n\n/**\n * Build a batch window knob from a config. Combinator form (the default L2\n * ergonomic): hand it the config, splice the ~4 returned hooks into your\n * machine. The pure verbs (`add` / `onWindow`) close over the config so the\n * consumer's reducer cells stay a uniform `(state, ...args)` shape; `subs` /\n * `handlers` pre-wire the window timer.\n *\n * @typeParam I the item type buffered into each batch\n * @typeParam C the Cmd type `config.flush` returns\n */\nexport function createBatchWindow<I, C extends Cmd>(\n  config: BatchWindowConfig<I, C>,\n): BatchWindowKnob<I, C> {\n  return {\n    init: () => initBatchWindow<I>(),\n    add: (state, item, at) => addItem(config, state, item, at),\n    onWindow: (state, at) => onWindow(config, state, at),\n    subs: (state, id) => subsFor(config, state, id),\n    handlers: () => ({ deadline: subscribeBatchWindow }),\n  };\n}\n"]}

package/dist/cache/index.d.ts

@@ -1,152 +0,0 @@
-import { S as Sub } from '../core-Co0LWkIA.js';
-import { S as SubscribeHandler } from '../types-XS_miRnB.js';
-import 'zod';
-
-/**
- * @demlik/tea/cache — a TTL cache as pure state, PLUS a periodic eviction Sub.
- *
- * Same pure-state-ops shape as `@demlik/tea/idempotency` and
- * `@demlik/tea/work-queue`: a state type plus pure transition functions. Host-
- * agnostic by construction — no `Date.now()`, no timers, no I/O inside the ops.
- * The caller injects the clock (`nowMs`) and folds the result through its own
- * reducer, keeping the store inside TEA's invariant 2 (transitions are pure:
- * same inputs → same outputs) so a consumer can exercise it with `replay`
- * without a fake clock.
- *
- * Every op returns a NEW cache value and never mutates its input (invariant 1 —
- * state is a value, not a place). `get` / `has` are read-shaped; `set` /
- * `remove` / `evictExpired` return a new cache.
- *
- * **Distinct from `/idempotency`.** Both are TTL-bounded key maps, but they
- * answer different questions and so carry different shapes:
- *
- *   - `/idempotency` is DEDUPE-focused — "have I already processed this key?"
- *     TTL is a single store-level policy (`ttlMs`), each entry stores the
- *     `atMs` it was remembered at, and expiry is derived (`now - atMs >=
- *     ttlMs`). It carries an `order` ledger + `capacity` because the use case
- *     (webhook receivers, retried messages) needs bounded LRU eviction.
- *   - `/cache` is RETRIEVAL-focused — "what is the value for this key right
- *     now?" TTL is set PER ENTRY at write time: `set(key, value, nowMs,
- *     ttlMs)` bakes the absolute `expiresAtMs = nowMs + ttlMs` into the entry.
- *     Different keys can carry different lifetimes (a hot key cached for 1s, a
- *     cold one for 1h) — the dimension idempotency's single store-level
- *     `ttlMs` cannot express. No `order`, no `capacity`: a cache bounds itself
- *     by TTL + periodic eviction, not by LRU count.
- *
- * The eviction Sub is the "eviction is a Msg" half: a `setInterval`-shaped Sub
- * (composed directly on `@demlik/tea/subs`' `fromInterval`) that periodically
- * dispatches a `cache_evict` Msg the consumer's reducer handles by calling
- * `evictExpired`. Time still never enters the reducer — the Sub fires the Msg,
- * the reducer reads `nowMs` off the Msg (the consumer stamps it at the Sub
- * boundary), and `evictExpired` does the pure drop.
- *
- * NOT exported from the package root — reached via the `@demlik/tea/cache`
- * subpath, same one-shape-per-package rule as `work-queue`, `idempotency`, and
- * `rate-limit`.
- */
-
-/**
- * A cached entry: the `value` and the absolute clock reading `expiresAtMs` it
- * expires at. Unlike `/idempotency`'s entry (which stores `atMs` and derives
- * expiry from a store-level `ttlMs`), the expiry instant is baked in at write
- * time — so per-entry TTLs are a first-class capability. Both fields are plain
- * data so the whole cache is trivially JSON-serializable into a consumer's
- * `Store<S>`.
- */
-interface CacheEntry<V> {
-    readonly value: V;
-    readonly expiresAtMs: number;
-}
-/**
- * The cache: a map of `key → entry`. No `order` ledger and no `capacity` (cf.
- * `/idempotency`) — a TTL cache bounds itself by expiry + periodic eviction,
- * not by LRU count. Each entry carries its own `expiresAtMs`, so the cache
- * needs no store-level TTL policy field.
- */
-interface TtlCache<V> {
-    readonly entries: Readonly<Record<string, CacheEntry<V>>>;
-}
-/** Create an empty cache. */
-declare function initCache<V>(): TtlCache<V>;
-/**
- * The cached `value` for `key` iff present AND unexpired at `nowMs`, else
- * `undefined`. An expired entry reads as absent even though it is physically
- * still in `entries` until the next `evictExpired` (or an overwriting `set`)
- * drops it. PURE — reads only, never mutates.
- */
-declare function get<V>(cache: TtlCache<V>, key: string, nowMs: number): V | undefined;
-/**
- * True iff `key` is present AND unexpired at `nowMs`. The boolean sibling of
- * `get` for callers that only need presence, not the value. PURE.
- */
-declare function has<V>(cache: TtlCache<V>, key: string, nowMs: number): boolean;
-/**
- * Write `key → value` with an absolute expiry of `nowMs + ttlMs`. Re-`set`ting
- * an existing key overwrites both the value and the expiry — the TTL clock
- * restarts from the new `nowMs`. PURE — returns a new cache; the input is
- * untouched (a fresh shallow copy of `entries`).
- */
-declare function set<V>(cache: TtlCache<V>, key: string, value: V, nowMs: number, ttlMs: number): TtlCache<V>;
-/**
- * Drop `key` regardless of expiry. PURE — returns a new cache; the input is
- * untouched. Removing an absent key returns an equivalent cache (the shallow
- * copy still happens, but no entry is dropped).
- */
-declare function remove<V>(cache: TtlCache<V>, key: string): TtlCache<V>;
-/**
- * Physically drop every entry expired at `nowMs` (`nowMs >= expiresAtMs`).
- * Returns a NEW cache with the survivors. This is the pure work the eviction
- * Sub's `cache_evict` Msg triggers — `get` / `has` already treat expired
- * entries as absent, so eviction is purely a memory-reclaim pass, not a
- * correctness one. PURE — the input cache is never mutated.
- */
-declare function evictExpired<V>(cache: TtlCache<V>, nowMs: number): TtlCache<V>;
-/**
- * The Msg the eviction Sub dispatches each tick. `id` is the Sub's own id so a
- * consumer with multiple caches can route the tick to the matching cache. The
- * reducer reads `Date.now()`-free time by stamping `nowMs` itself at the Sub
- * boundary if needed; the canonical reducer cell is
- * `cache_evict: (s) => [{ ...s, cache: evictExpired(s.cache, nowMs) }, []]`.
- */
-interface CacheEvictMsg {
-    readonly type: "cache_evict";
-    readonly id: string;
-}
-/** Construct a `cache_evict` Msg for the cache identified by `id`. */
-declare function cacheEvictMsg(id: string): CacheEvictMsg;
-/**
- * The Sub shape the eviction factory installs: a `setInterval`-shaped Sub
- * carrying its tick period (`intervalMs`) per the substrate's
- * reconcile-by-id-with-data-on-the-Sub contract. `type: "cache"` is the
- * lowercase source-noun Sub convention (canon §2.5 / naming-style).
- */
-type CacheEvictionSub = Sub<"cache"> & {
-    readonly intervalMs: number;
-};
-/**
- * Declare an eviction Sub for the cache identified by `id`, ticking every
- * `everyMs`. Drop the result into `subscriptions(state)`:
- *
- *   subscriptions: (s) => [cacheEvictionSub("session-cache", 30_000)]
- *
- * Same id ⇒ same running interval across transitions (no reconcile churn);
- * changing `everyMs` alone will NOT re-arm the timer (the substrate leaves a
- * same-id Sub running) — change the `id` too if the period must change. This
- * mirrors `fromInterval`'s data-on-the-Sub tradeoff exactly.
- */
-declare function cacheEvictionSub(id: string, everyMs: number): CacheEvictionSub;
-/**
- * The `subscribe` cell for the eviction Sub. Assign it to
- * `machine.subscribe.cache`:
- *
- *   subscribe: { cache: cacheEvictionSubscribe }
- *
- * Composed directly on `fromInterval` — it owns the `setInterval` /
- * `clearInterval` lifecycle; this cell only pins the Msg the tick dispatches
- * (`cacheEvictMsg(sub.id)`). The cleanup `fromInterval` returns stops the
- * interval when the Sub is reconciled out (the cache's state exits the phase
- * that declared it).
- */
-declare const cacheEvictionSubscribe: SubscribeHandler<CacheEvictionSub, CacheEvictMsg, unknown>;
-
-export { type CacheEntry, type CacheEvictMsg, type CacheEvictionSub, type TtlCache, cacheEvictMsg, cacheEvictionSub, cacheEvictionSubscribe, evictExpired, get, has, initCache, remove, set };

package/dist/cache/index.js

@@ -1,8 +0,0 @@
-export { cacheEvictMsg, cacheEvictionSub, cacheEvictionSubscribe, evictExpired, get, has, initCache, remove, set } from '../chunk-RH5EFRVJ.js';
-import '../chunk-VYFAZN3F.js';
-import '../chunk-2YFLOCWX.js';
-import '../chunk-ZJ5AOYBH.js';
-import '../chunk-ZSUUOEPL.js';
-import '../chunk-OOYD44JI.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map