@demlik/tea 0.14.0 → 0.16.0

package/dist/{index-B5BZ-_cT.d.ts → index-Cou86-GX.d.ts}

@@ -1,59 +1,6 @@
-import { a as CmdOf, b as CmdDef, i as CmdValue, C as Cmd } from './core-CTzMJ82M.js';
+import { c as CmdOf, b as CmdDef, g as TaggedError, r as MalformedResult, T as TimerDeps, C as Cmd } from './core-BbgtiXdg.js';
 import { RetryState, AnyRetryPolicy } from './retry-backoff/index.js';
-import { T as TtlCache, D as DeadlineExceeded, a as DeadlineSub } from './index-q0hXFeZ0.js';
-
-/**
- * The closed set of cross-module Msg/Cmd discriminant strings. Declared `as
- * const` so each entry is usable as both a value (construction / reducer keys /
- * switch labels) and, via `typeof MsgType.X`, a literal type (`readonly type:`
- * fields). The single source of truth for issue #60.
- */
-declare const MsgType: {
-    /** The "run the port for `key`" effect Cmd resilient-call emits. */
-    readonly ResilientRun: "resilient_run";
-    /** PRIVATE success settle Msg (read only by `agentEvents`, #47). */
-    readonly ResilientOk: "resilient_ok";
-    /** Failure settle Msg — routed to the `fail` verb (back off via retry). */
-    readonly ResilientErr: "resilient_err";
-    /** Begin a run. */
-    readonly AgentStart: "agent_start";
-    /** PRIVATE tool-fan-out success settle Msg (read only by `agentEvents`, #47). */
-    readonly AgentToolOk: "agent_tool_ok";
-    /** Tool-fan-out failure settle Msg. */
-    readonly AgentToolErr: "agent_tool_err";
-    /**
-     * Re-fire the one outstanding effect on rehydrate (the do↔agent seam). Fired
-     * by `do/host`'s `autoBoot` via the typed `agentBootMsg` constructor, matched
-     * by the agent reducer — see `AgentBootPort` in `../agent`.
-     */
-    readonly AgentBoot: "agent_boot";
-    /**
-     * Stop the run from outside and settle it `cancelled` — what an `AbortSignal`
-     * handed to `driveToDone` / a defined agent's `run` dispatches on abort. A
-     * transition, never a throw: the outcome lands in the Model, so a reload reads
-     * a run that ended rather than one to resume.
-     */
-    readonly AgentCancel: "agent_cancel";
-    /**
-     * The "summarize the oldest N turns" effect Cmd the agent emits when its
-     * `CompactionPolicy` asks to compact before a brain call. A DEDICATED
-     * round-trip (design B1), distinct from the brain call's `resilient_run`, so
-     * compaction is its own honest `Awaiting` state — see `../agent`.
-     */
-    readonly CompactRun: "compact_run";
-    /** Compaction round-trip resolved — carries the summary text the fold-back folds. */
-    readonly CompactOk: "compact_ok";
-    /** Compaction round-trip failed (exhausted retry) — surfaced as data, not a stall. */
-    readonly CompactErr: "compact_err";
-    /** Refresh port resolved — carries the fresh `Token`. */
-    readonly TokenRefreshed: "token_refreshed";
-    /** Refresh port rejected — carries the rejection (errors are data). */
-    readonly TokenRefreshFailed: "token_refresh_failed";
-    /** The 401 the consumer dispatches when a guarded call comes back unauthorized. */
-    readonly Unauthorized: "unauthorized";
-};
-/** The union of every discriminant string in the protocol. */
-type MsgTypeValue = (typeof MsgType)[keyof typeof MsgType];
+import { T as TtlCache, D as DeadlineExceeded, a as DeadlineSub } from './index-Xufl55W8.js';
 
 /**
  * @packageDocumentation
@@ -404,13 +351,47 @@ interface DeadlineConfig {
     /** Budget of in-process time from the moment a call starts, in ms. */
     readonly ms: number;
 }
+/**
+ * The family every unnamed knob speaks: `resilient_run` / `resilient_run_ok` /
+ * `resilient_run_err`. Identical to the `MsgType.Resilient*` literals, which
+ * stay the vocabulary of every knob that passes no name.
+ */
+declare const DEFAULT_RESILIENT_NAME = "resilient";
+type DefaultResilientName = typeof DEFAULT_RESILIENT_NAME;
+/** The run Cmd's `type` for the `N` family. */
+type ResilientRunType<N extends string> = `${N}_run`;
+/** The success settle Msg's `type` for the `N` family — minted by the engine. */
+type ResilientOkType<N extends string> = `${N}_run_ok`;
+/** The failure settle Msg's `type` for the `N` family — minted by the engine. */
+type ResilientErrType<N extends string> = `${N}_run_err`;
 /**
  * The resilience knob. EVERY field is optional: omit a brick and its gate is
  * skipped entirely (the slice still carries a default brick state so the shape
  * stays uniform across configs, but the gate is never consulted). An empty
  * config `{}` is a valid pass-through — a bare effect with no resilience at all.
+ *
+ * `N` is the knob's Msg-name family (see {@link ResilientName}); it is carried on
+ * the config so the run Cmd and the two settle Msgs are named from ONE place.
  */
-interface ResilientConfig {
+interface ResilientConfig<N extends string = DefaultResilientName> {
+    /**
+     * What this knob's Cmd and settle Msgs are called: `<name>_run`, and the
+     * `<name>_run_ok` / `<name>_run_err` the engine mints from the run handler's
+     * outcome. Omit it and the family is `resilient` — `resilient_run` /
+     * `resilient_run_ok` / `resilient_run_err`.
+     *
+     * Name a knob when a machine holds more than one of the resilient family.
+     * Two unnamed knobs meet in ONE `resilient_run_ok` cell whose payload is the union
+     * of both results, and the consumer discriminates by hand on `key` — which the
+     * type checker cannot see. Under distinct names each knob settles into its own
+     * cell, already narrowed to its own payload.
+     *
+     * The name is a value AND a type: the settle Msg types are generic in `N`, and
+     * `N` is not inferable from `I` / `R`, so an opted-in knob spells all three
+     * type arguments — `createResilientCall<In, Out, "jev">({ name: "jev", … })`.
+     * The `name` field is typed at `N`, so the two cannot drift apart.
+     */
+    readonly name?: N;
     /**
      * The backoff brick. Omit and a failure is terminal (no backoff, no timer).
      *
@@ -418,7 +399,7 @@ interface ResilientConfig {
      * wall-clock outage budget (`DurationRetryPolicy`), or explicit
      * `unbounded: true`. A duration bound needs no extra wiring: every path that
      * records a failure already holds the instant it was observed as DATA —
-     * `fail`'s `msg.at` (stamped at the interpret boundary) and `gate`'s `at`
+     * `settle`'s `msg.at` (stamped at the interpret boundary) and `gate`'s `at`
      * (the caller's `attempt` / the retry timer's `atMs`) — so the streak clock
      * is fed from a Msg, never from a `Date.now()` inside a verb (invariant 2).
      */
@@ -461,7 +442,7 @@ interface CallBudget {
  * `phase` so each phase carries only its own data (pattern 11):
  *
  *   - `idle`          — never attempted, or fully settled and forgotten.
- *   - `running`       — the effect Cmd is out; awaiting `succeed` / `fail`.
+ *   - `running`       — the effect Cmd is out; awaiting `settle`.
  *                       Carries the deadline budget ({@link CallBudget}) and the
  *                       last `input` so a retry can re-issue it.
  *   - `waiting_retry` — a transient failure backed off; the retry timer is armed
@@ -517,13 +498,30 @@ interface ResilientState<I, R> {
     readonly retry: Readonly<Record<string, RetryState>>;
     readonly cache: TtlCache<R>;
     readonly calls: Readonly<Record<string, CallPhase<I, R>>>;
+    /**
+     * The instant of the latest clocked transition this slice saw — the `at` of
+     * the last `attempt` / `resume` / `settleFailed`, settled Msg or timer fire.
+     * `timer` counts the soonest deadline down from it, so the built-in `timer`
+     * Sub gets a relative `ms` without anything reading a clock. `0` until the
+     * first clocked transition.
+     */
+    readonly clockMs: number;
 }
 /**
- * The one effect this knob emits: "run the port for `key` with `input`". The
- * consumer's `handlers(ports)` interprets it; it carries no closure — `input`
- * is plain data (invariant 3).
+ * The failures a run handler may return (ADR 0021). `port_rejected` is the
+ * work failing — carry the cause beside the tag (`err({ _tag: "port_rejected",
+ * cause })`); `deadline_exceeded` is a handler that timed the work out itself.
+ * Either one settles as `<name>_run_err` and feeds the retry / breaker. Any
+ * other failure is a contract breach and goes to the error sink.
  */
-declare function runCmdDef<I, R>(): CmdDef<"resilient_run", {
+type RunErr = TaggedError<"port_rejected" | "deadline_exceeded">;
+/**
+ * The one effect this knob emits: "run the work for `key` with `input`". It is
+ * `Cmd.define`d, so the handler you write for it returns an outcome and the
+ * engine mints `<name>_run_ok` / `<name>_run_err` (ADR 0021). It carries no
+ * closure — `input` is plain data (invariant 3).
+ */
+declare function runCmdDef<I, R, N extends string = DefaultResilientName>(name?: N): CmdDef<`${N}_run`, {
     readonly key: string;
     readonly input: I;
 }, R, {
@@ -532,24 +530,109 @@ declare function runCmdDef<I, R>(): CmdDef<"resilient_run", {
 } | {
     readonly [detail: string]: unknown;
     readonly _tag: "port_rejected";
-}, unknown>;
-type RunCmdDef<I, R> = ReturnType<typeof runCmdDef<I, R>>;
-type RunCmd<I> = CmdOf<RunCmdDef<I, unknown>>;
-/** Settle Msgs the `handlers` port dispatches back. `at` is stamped at the boundary. */
-type SucceedMsg<R> = {
-    readonly type: typeof MsgType.ResilientOk;
-    readonly key: string;
-    readonly result: R;
+}>;
+type RunCmdDef<I, R, N extends string = DefaultResilientName> = ReturnType<typeof runCmdDef<I, R, N>>;
+/**
+ * The run Cmd value. `R` is its settle value — `unknown` reads any knob's run
+ * Cmd; the knob's own verbs emit it at their `R`, which is what lets a machine
+ * list `cmds: [rc.run]` and take the verbs' Cmds as its own.
+ */
+type RunCmd<I, N extends string = DefaultResilientName, R = unknown> = CmdOf<RunCmdDef<I, R, N>>;
+/**
+ * The settle Msgs the engine mints from a run handler's outcome:
+ * `<name>_run_ok` carrying the handler's `value`, `<name>_run_err` carrying its
+ * declared `error`. Each carries the run Cmd it settles (`cmd.key` names the
+ * call) and the `at` the engine stamped. Both are generic in the knob's name
+ * family `N`, so two knobs named apart land in two `update` cells whose
+ * payloads are already narrowed.
+ *
+ * They are the `SettledOk` / `SettledErr` pair `Cmd.define` mints, spelled out
+ * so a helper that folds the error into a richer type of its own (llm-call's
+ * `LlmErr`, jev-ask's `JevAskErr`) can hand `settle` its Msg with `E` widened.
+ */
+type SucceedMsg<R, N extends string = DefaultResilientName, I = unknown> = {
+    readonly type: ResilientOkType<N>;
+    readonly cmd: RunCmd<I, N>;
+    readonly value: R;
     readonly at: number;
 };
-type FailMsg = {
-    readonly type: typeof MsgType.ResilientErr;
-    readonly key: string;
+type FailMsg<N extends string = DefaultResilientName, I = unknown, E = RunErr | MalformedResult> = {
+    readonly type: ResilientErrType<N>;
+    readonly cmd: RunCmd<I, N>;
+    readonly error: E;
+    readonly at: number;
+};
+/**
+ * What `settle` reads off a settled Msg: the call's `key` (on `cmd`), the
+ * engine's `at`, and the handler's `value` or `error`. {@link SucceedMsg} and
+ * {@link FailMsg} are both one of these, so an engine-minted Msg passes
+ * straight in; a helper that settles from its own data (a fallback answer, a
+ * compaction summary) builds the record without inventing a whole run Cmd.
+ */
+type SettleMsg<R, N extends string = DefaultResilientName> = {
+    readonly type?: ResilientOkType<N>;
+    readonly cmd: {
+        readonly key: string;
+    };
+    readonly value: R;
+    readonly at: number;
+} | {
+    readonly type?: ResilientErrType<N>;
+    readonly cmd: {
+        readonly key: string;
+    };
     readonly error: unknown;
     readonly at: number;
 };
-/** The retry / deadline timer Msg — `DeadlineExceeded`, keyed by the call `key`. */
-type ResilientTimerMsg = DeadlineExceeded;
+/**
+ * How a settled call ended — the third thing `settle` hands back, and the only
+ * place the port's value can be read from.
+ *
+ *   - `done`     — the port answered; `value` is its result.
+ *   - `failed`   — no retry is left (or no retry brick); `error` is the last
+ *                  failure.
+ *   - `retrying` — backed off; the retry timer is armed and the call is still
+ *                  live.
+ */
+type SettleOutcome<R> = {
+    readonly kind: "done";
+    readonly value: R;
+} | {
+    readonly kind: "failed";
+    readonly error: unknown;
+} | {
+    readonly kind: "retrying";
+};
+/**
+ * What `settle` returns: the settled slice, the Cmds it emitted, and the
+ * {@link SettleOutcome}. One record, so the slice update and the result read
+ * cannot be split apart in a hand-wired `update` cell.
+ */
+interface SettleResult<I, R, N extends string = DefaultResilientName> {
+    readonly call: ResilientState<I, R>;
+    readonly cmds: readonly RunCmd<I, N, R>[];
+    readonly outcome: SettleOutcome<R>;
+}
+/**
+ * The deadline Msg tag this knob's timers dispatch, derived from its name the
+ * same way the settle Msgs are. The DEFAULT family keeps the bare
+ * `"deadline_exceeded"` literal.
+ */
+type ResilientDeadlineType<N extends string = DefaultResilientName> = N extends DefaultResilientName ? "deadline_exceeded" : `${N}_deadline`;
+/**
+ * The name a deadline carries for the `N` family — `undefined` for the
+ * default family (no name at all, so the bare literal is dispatched), the name
+ * itself otherwise. One conditional, so the value and {@link
+ * ResilientDeadlineType} can never disagree about which family is unnamed.
+ */
+type DeadlineNameOf<N extends string = DefaultResilientName> = N extends DefaultResilientName ? undefined : N;
+/**
+ * The retry / deadline timer Msg — a `DeadlineExceeded` whose tag is this
+ * knob's ({@link ResilientDeadlineType}), keyed by the call `key` through the
+ * Sub `id`. Bare `ResilientTimerMsg` is the default family's, so it is the same
+ * `DeadlineExceeded` it has always been.
+ */
+type ResilientTimerMsg<N extends string = DefaultResilientName> = DeadlineExceeded<DeadlineNameOf<N>>;
 /**
  * The plain-data error a deadline-failed call settles with. A `{_tag, ...}`
  * sentinel — NEVER a `new Error(...)` — so the slice stays JSON-serializable
@@ -562,11 +645,6 @@ type DeadlineExceededError = {
     readonly id: string;
     readonly atMs: number;
 };
-/** Ports the consumer supplies to `handlers`. */
-interface ResilientPorts<I, R> {
-    /** The fallible work this knob wraps. Throws on failure → routed to `fail`. */
-    readonly run: (input: I, key: string) => Promise<R>;
-}
 /**
  * Build a resilient-call knob from `config`. `rng` is injected for retry
  * jitter — pass a fixed `() => 0.5` in tests to pin backoff; defaults to
@@ -574,43 +652,46 @@ interface ResilientPorts<I, R> {
  * curried onto the factory rather than threaded through every verb so callers
  * spell the determinism choice once.
  *
- * Returns the uniform L2 knob contract. `I` is the port input type, `R` the
- * port result type. Consumers outside the package reach this through
- * `withResilience` (`../with-resilience`) — see the migration map at the top
- * of this module.
+ * Returns plain functions and the run Cmd def (ADR 0022) — see the module doc
+ * for the wiring. `I` is the work's input type, `R` its result type.
  */
-declare function createResilientCall<I, R>(config: ResilientConfig, rng?: () => number): {
+declare function createResilientCall<I, R, N extends string = DefaultResilientName>(config: ResilientConfig<N>, rng?: () => number): {
+    name: N;
+    /** The `Cmd.define`d run Cmd; list it in the machine's `cmds`. */
+    run: CmdDef<`${N}_run`, {
+        readonly key: string;
+        readonly input: I;
+    }, R, {
+        readonly [detail: string]: unknown;
+        readonly _tag: "deadline_exceeded";
+    } | {
+        readonly [detail: string]: unknown;
+        readonly _tag: "port_rejected";
+    }>;
     init: () => ResilientState<I, R>;
-    attempt: (s: ResilientState<I, R>, key: string, input: I, at: number) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
+    attempt: (s: ResilientState<I, R>, key: string, input: I, at: number) => readonly [ResilientState<I, R>, readonly RunCmd<I, N, R>[]];
     resume: (s: ResilientState<I, R>, at: number) => ResilientState<I, R>;
-    succeed: (s: ResilientState<I, R>, key: string, msg: SucceedMsg<R>) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
-    fail: (s: ResilientState<I, R>, key: string, msg: FailMsg) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
-    settleFailed: (s: ResilientState<I, R>, key: string, error: unknown) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
-    onTimer: (s: ResilientState<I, R>, msg: ResilientTimerMsg) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
-    subs: (s: ResilientState<I, R>) => readonly DeadlineSub[];
-    handlers: (ports: ResilientPorts<I, R>) => {
-        resilient_run: (cmd: CmdValue<"resilient_run", {
-            readonly key: string;
-            readonly input: I;
-        }, {
-            readonly [detail: string]: unknown;
-            readonly _tag: "deadline_exceeded";
-        } | {
-            readonly [detail: string]: unknown;
-            readonly _tag: "port_rejected";
-        }, unknown>, ctx: Readonly<Record<never, never>>) => Promise<FailMsg | SucceedMsg<R>>;
-    };
+    settle: (s: ResilientState<I, R>, msg: SettleMsg<R, N>) => SettleResult<I, R, N>;
+    settleFailed: (s: ResilientState<I, R>, key: string, error: unknown, at: number) => readonly [ResilientState<I, R>, readonly RunCmd<I, N, R>[]];
+    onTimer: (slice: ResilientState<I, R>, msg: {
+        readonly id: string;
+        readonly atMs: number;
+    }) => readonly [ResilientState<I, R>, readonly RunCmd<I, N, R>[]];
+    deadlines: (s: ResilientState<I, R>) => readonly DeadlineSub<DeadlineNameOf<N>>[];
+    timer: (s: ResilientState<I, R>) => TimerDeps<ResilientTimerMsg<N>> | null;
 };
 /**
  * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the
  * slice lives at `state.resilience`. 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. Under `withResilience` the wrapper owns
- * `model.$resilience`, so there is nothing to lift; this is for the embedded
- * slice consumers only.
+ * record rebuild, no clock / RNG.
+ *
+ * The record rebuild itself is `liftSlice` from the root door (#231) — this
+ * stays as the named, pre-keyed convenience for the `state.resilience` field,
+ * unchanged in name, signature and subpath.
  */
 declare function liftResilience<S extends {
     resilience: ResilientState<I, R>;
-}, I, R, C extends Cmd>(state: S, [slice, cmds]: readonly [ResilientState<I, R>, readonly C[]]): readonly [S, readonly C[]];
+}, I, R, C extends Cmd>(state: S, result: readonly [ResilientState<I, R>, readonly C[]]): readonly [S, readonly C[]];
 
-export { runCmdDef as A, tryConsume as B, type CircuitConfig as C, type DeadlineConfig as D, type FailMsg as F, MsgType as M, type RunCmd as R, type SucceedMsg as S, type TokenBucket as T, type ResilientState as a, type MsgTypeValue as b, type RateLimitConfig as c, type ResilientPorts as d, type ResilientConfig as e, type ResilientTimerMsg as f, type CacheConfig as g, type CallBudget as h, type CallPhase as i, type CircuitPolicy as j, type CircuitState as k, type DeadlineExceededError as l, type RunCmdDef as m, type SlidingWindow as n, canPass as o, createResilientCall as p, defaultCircuitPolicy as q, initBucket as r, initCircuit as s, initWindow as t, liftResilience as u, onFailure as v, onSuccess as w, record as x, refill as y, remaining as z };
+export { initBucket as A, initCircuit as B, type CacheConfig as C, DEFAULT_RESILIENT_NAME as D, initWindow as E, type FailMsg as F, liftResilience as G, onFailure as H, onSuccess as I, record as J, refill as K, remaining as L, runCmdDef as M, tryConsume as N, type RunCmd as R, type SucceedMsg as S, type TokenBucket as T, type ResilientState as a, type ResilientTimerMsg as b, type ResilientConfig as c, type CallBudget as d, type CallPhase as e, type CircuitConfig as f, type CircuitPolicy as g, type CircuitState as h, type DeadlineExceededError as i, type DeadlineNameOf as j, type DefaultResilientName as k, type RateLimitConfig as l, type DeadlineConfig as m, type ResilientDeadlineType as n, type ResilientErrType as o, type ResilientOkType as p, type ResilientRunType as q, type RunCmdDef as r, type RunErr as s, type SettleMsg as t, type SettleOutcome as u, type SettleResult as v, type SlidingWindow as w, canPass as x, createResilientCall as y, defaultCircuitPolicy as z };

package/dist/{index-TvRb1KVf.d.ts → index-DU6JpQ8G.d.ts}

@@ -1,4 +1,4 @@
-import { B as BootingRuntime } from './runtime-types-LWDoi943.js';
+import { B as BootingRuntime } from './runtime-types-CiVpC0HN.js';
 
 /**
  * A recorded run, sufficient to reproduce it via `../trace-replay`.