@demlik/tea 0.12.0 → 0.14.0

package/dist/idempotency/adapter.d.ts

@@ -1,62 +0,0 @@
-import { IdempotencyStore } from './index.js';
-
-/**
- * @demlik/tea/idempotency/adapter — the verb seam over the pure idempotency ops.
- *
- * The functions in `./index` (`seen` / `recall` / `remember` / `evictExpired`
- * / `initStore`) are the BLESSED transitions, but their names and the
- * `IdempotencyStore<V>` shape they read/return are the STORE's vocabulary. A
- * consumer that owns an `IdempotencyStore<V>` slice (`idempotent-intake`,
- * `poller`) used to import those functions by name and call them directly, so
- * a change to the op surface — or to `IdempotencyStore`'s fields — cascaded to
- * every call site.
- *
- * `IdempotencyMemory<V>` is the insulating interface: five VERBS (`isSeen` /
- * `recall` / `remember` / `evict` / `init`) consumers depend on instead of the
- * raw functions. The verbs keep the ops' pure contract — no I/O, no `Date.now`
- * (the clock is injected as `now`) — so a consumer folding the adapter through
- * its reducer stays inside invariant 2 (pure transitions). `isSeen` renames the
- * blessed `seen` predicate (a noun-y `seen` reads ambiguously as a slice field;
- * the verb form states the question it answers), and `evict` is the verb form
- * of `evictExpired`.
- *
- * `idempotencyMemory<V>()` is the canonical implementation, a thin binding of
- * the blessed ops. Because the verbs are the only surface consumers touch, an
- * `IdempotencyStore` shape change is absorbed HERE rather than at the consumer
- * call sites.
- *
- * INTERNAL seam (no public-API port): consumers import the adapter from this
- * subpath the same way they imported the ops. The ops remain exported from
- * `./index` for any call site that genuinely wants a function directly.
- */
-
-/**
- * The verb interface over an `IdempotencyStore<V>`. Each verb mirrors a blessed
- * op's pure contract but speaks the consumer's dedupe vocabulary, so the
- * consumer never names a store function or reaches into an `IdempotencyStore`
- * field it did not put there.
- */
-interface IdempotencyMemory<V> {
-    /** Create an empty store, optionally bounded by `capacity` and/or `ttlMs`. */
-    init(opts?: {
-        capacity?: number;
-        ttlMs?: number;
-    }): IdempotencyStore<V>;
-    /** True iff `key` is present AND not expired at `now`. Read-only. */
-    isSeen(store: IdempotencyStore<V>, key: string, now: number): boolean;
-    /** The cached value for `key` if present and unexpired at `now`. Read-only. */
-    recall(store: IdempotencyStore<V>, key: string, now: number): V | undefined;
-    /** Record `key → value` at `now`, enforcing the store's bounds. Returns a new store. */
-    remember(store: IdempotencyStore<V>, key: string, value: V, now: number): IdempotencyStore<V>;
-    /** Drop every entry expired at `now`. Returns a new store. */
-    evict(store: IdempotencyStore<V>, now: number): IdempotencyStore<V>;
-}
-/**
- * The canonical `IdempotencyMemory<V>`, binding each verb to its blessed op.
- * Pure and stateless — call once at module scope in a consumer and fold its
- * verbs through the reducer. An `IdempotencyStore` shape change is absorbed by
- * re-binding a verb here, not at the consumers.
- */
-declare function idempotencyMemory<V>(): IdempotencyMemory<V>;
-
-export { type IdempotencyMemory, idempotencyMemory };

package/dist/idempotency/adapter.js

@@ -1,4 +0,0 @@
-export { idempotencyMemory } from '../chunk-BYQUGDD3.js';
-import '../chunk-K575PT4S.js';
-//# sourceMappingURL=adapter.js.map
-//# sourceMappingURL=adapter.js.map

package/dist/idempotency/adapter.js.map

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

package/dist/idempotent-intake/index.d.ts

@@ -1,187 +0,0 @@
-import { IdempotencyStore } from '../idempotency/index.js';
-import { C as Cmd } from '../core-Bjc0bS8j.js';
-import { QueueItem } from '../work-queue/index.js';
-import '../runtime-types-Bxc637bp.js';
-import 'better-result';
-
-/**
- * @demlik/tea/idempotent-intake — receive-once intake for webhooks / queue
- * messages: dedupe by key, enqueue the new ones, replay the cached result to
- * the duplicates. The "process this payload exactly once even though it
- * arrives N times" knob.
- *
- * **The recipe.** This is a Level-2 composition — it owns no primitive
- * queue/cache logic of its own, it *splices two L1 bricks into one Model slice*
- * and DELEGATES every transition to their VERB SEAMS — `IdempotencyMemory`
- * (`../idempotency/adapter`) and `QueueAdapter` (`../work-queue/adapter`) —
- * so the store ops and the `QueueItem` / `IdempotencyStore` shapes stay
- * insulated behind verbs the intake calls:
- *
- *   - `../idempotency/adapter` — the dedupe-by-key + last-result cache. The
- *     `seen` half of the slice is its `IdempotencyStore`, keyed by
- *     `keyOf(payload)`. A key is recorded once `receive` calls `memory.remember`;
- *     `complete` calls `memory.remember` again to swap its cached value from
- *     `pending` to the finished `result`. The cache write is the brick's, never
- *     re-rolled here.
- *   - `../work-queue/adapter` — the pending-work list. The `queue` half of the
- *     slice is its `QueueItem<P>[]`. Every status flip routes through the
- *     adapter verbs: `receive` enqueues via `queue.enqueue`, `claimNext` stamps
- *     the `running` claim via `queue.patch`, `boot` re-arms a dead worker's
- *     claim via `queue.patch`. Intake owns only the SELECTION (which item,
- *     gated on the done-cache reconcile below) — the array transition is the
- *     brick's. The consumer drains it (claim → process → `complete`) at its own
- *     pace.
- *
- * Both bricks are pure-state + pure-ops, host- and clock-agnostic by
- * construction, so the combined slice inherits TEA's two non-negotiables:
- *
- *   - **Durable** — the slice is a plain serializable value (a record-backed
- *     idempotency store + an array of queue items, no `Map`, no closures), so
- *     it survives a Durable-Object eviction / reload and rehydrates whole.
- *   - **Replayable** — every verb is a pure `(state, …) => [state, Cmd[]]`
- *     transition; no `Date.now()`, no `Math.random()`, no I/O inside a verb.
- *     `at` (the clock) and `id` (the queue-item id) are *injected* at the call
- *     site, so `trace-replay` reconstructs each transition exactly.
- *
- * **The decision lives in a Cmd, not in a return shape.** `receive` cannot
- * "return" what it decided (the knob contract pins the shape to
- * `[State, Cmd[]]`), so the decision is *reified as a Cmd* the runtime
- * performs:
- *
- *   - first sighting of a key  → mark it `pending`, enqueue the payload, emit
- *     `IntakeProcess` (go run the work).
- *   - a key already `pending`  → drop silently (the original is in flight);
- *     emit nothing.
- *   - a key already `done`     → emit `IntakeReplay` carrying the cached
- *     result so the duplicate caller gets the SAME response the first one
- *     produced, with zero re-execution of the side effect.
- *
- * **Two crash-safety guarantees the verbs enforce (and the unit specs alone
- * missed — see the wired-machine test):**
- *
- *   - *A slow worker is never double-enqueued.* The TTL clock starts at
- *     `complete`, not at `receive`: a `pending` entry NEVER ages out, so a
- *     duplicate of an in-flight key is always dropped no matter how long the
- *     worker takes. Only a `done` entry expires (see `liveEntry`).
- *   - *A complete-then-crash never re-runs.* `boot` and `claimNext` reconcile
- *     the queue against the done cache: a queue item whose key already resolved
- *     to `done` in `seen` is skipped (never reset to pending, never claimed),
- *     so a worker that finished and cached its result before the DO evicted is
- *     not re-executed on resume.
- *
- * Typical wiring (the combinator form — splice ~3 hooks into a host machine):
- *
- *   const intake = createIntake<StripeEvent, ChargeResult>({
- *     keyOf: (e) => e.id,          // Stripe's idempotency key
- *     ttlMs: 24 * 60 * 60 * 1000,  // a replayed webhook 24h after it COMPLETED is re-run
- *   });
- *
- *   // in `init`:
- *   intake: intake.init(),
- *   // in `update`, on the inbound-webhook Msg:
- *   const [next, cmds] = intake.receive(state.intake, payload, at, id);
- *   // …route `IntakeProcess` to your worker, `IntakeReplay` to the responder.
- *   // on the worker's done Msg:
- *   const [next, _] = intake.complete(state.intake, key, result, at);
- *   // once, after boot (DO reload), before resuming the drain:
- *   const [next, _] = intake.boot(state.intake);
- *
- * Escape hatch: reach the raw L1 ops via `@demlik/tea/idempotency` and
- * `@demlik/tea/work-queue` and thread them by hand.
- */
-
-/**
- * A cached intake entry: either a key whose work is still in flight
- * (`pending`) or one whose work has finished and whose `result` is held for
- * replay to later duplicates (`done`). Discriminated on `phase` — `pending`
- * carries no payload, `done` carries the result `R`.
- *
- * Lives inside the `seen` half of the slice (`IdempotencyStore<IntakeEntry<R>>`).
- * It is the dedupe ledger's *value*; the ledger's *key* is `keyOf(payload)`.
- */
-type IntakeEntry<R> = {
-    readonly phase: "pending";
-} | {
-    readonly phase: "done";
-    readonly result: R;
-};
-/**
- * The intake knob's config — `keyOf` derives the idempotency key from a
- * payload, `ttlMs` (optional) ages a *completed* cached key out so a webhook
- * replayed long after the work finished is treated as new and re-processed.
- *
- * **The TTL clock starts at `complete`, not at `receive`.** A `pending` entry
- * (work still in flight) NEVER ages out, no matter how slow the worker is —
- * ageing a pending key would let the duplicate re-enqueue the in-flight
- * payload and double-process it. Only a `done` entry expires, measured from
- * the `at` passed to `complete` (the moment the result was cached). Inside the
- * window a duplicate replays the cached result; at/after the window it is
- * re-accepted and re-processed.
- *
- * Omit `ttlMs` for a cache whose `done` entries never expire by age (keys live
- * forever — fine for a bounded universe of ids, unbounded growth otherwise).
- *
- * The TTL is owned HERE, not delegated to the composed `IdempotencyStore`: the
- * store's uniform per-entry TTL cannot tell `pending` from `done`, so intake
- * keeps the store TTL-free and applies the phase-aware rule itself (see
- * `liveEntry`).
- */
-interface IntakeConfig<P> {
-    /** Derive the idempotency key from a payload. Must be pure + deterministic. */
-    readonly keyOf: (payload: P) => string;
-    /**
-     * Age a *completed* key out after this many ms, measured from the `at`
-     * passed to `complete`. Pending keys never age out.
-     */
-    readonly ttlMs?: number;
-}
-/**
- * The Model slice this knob owns. `seen` is the dedupe + last-result cache
- * (the `../idempotency` brick); `queue` is the pending-work list (the
- * `../work-queue` brick). Both are plain serializable values — the whole slice
- * round-trips through `JSON` so it survives eviction and replays exactly.
- */
-interface IntakeState<P, R> {
-    readonly seen: IdempotencyStore<IntakeEntry<R>>;
-    readonly queue: readonly QueueItem<P>[];
-}
-/** A genuinely-new payload was accepted and enqueued — go run the work. */
-interface IntakeProcessCmd<P> extends Cmd<"intake:process"> {
-    /** The dedupe key the payload was filed under. */
-    readonly key: string;
-    /** The enqueued queue-item id (the same `id` passed to `receive`). */
-    readonly itemId: string;
-    /** The original payload, for the worker to process. */
-    readonly payload: P;
-}
-/**
- * A duplicate of an already-completed key arrived — replay the cached result
- * to the caller instead of re-running the side effect.
- */
-interface IntakeReplayCmd<R> extends Cmd<"intake:replay"> {
-    /** The dedupe key whose cached result is being replayed. */
-    readonly key: string;
-    /** The result the ORIGINAL request produced, recalled from the cache. */
-    readonly result: R;
-}
-/** The Cmd union the intake verbs emit. */
-type IntakeCmd<P, R> = IntakeProcessCmd<P> | IntakeReplayCmd<R>;
-/**
- * Build an idempotent-intake knob from `config`. Returns the uniform L2
- * contract — `init()` + the verbs (`receive`, `complete`, `boot`, `claimNext`).
- * No `subs` / `handlers`: intake owns no timers and does no I/O of its own (the
- * composed bricks are pure-ops; the worker that runs `IntakeProcess` and the
- * responder that runs `IntakeReplay` live in the host's interpret map).
- */
-declare function createIntake<P, R>(config: IntakeConfig<P>): {
-    init: () => IntakeState<P, R>;
-    receive: (state: IntakeState<P, R>, payload: P, at: number, id: string) => readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]];
-    complete: (state: IntakeState<P, R>, key: string, result: R, at: number) => readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]];
-    boot: (state: IntakeState<P, R>) => readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]];
-    claimNext: (state: IntakeState<P, R>, at: number) => {
-        readonly state: IntakeState<P, R>;
-        readonly claimed: QueueItem<P>;
-    } | null;
-};
-
-export { type IntakeCmd, type IntakeConfig, type IntakeEntry, type IntakeProcessCmd, type IntakeReplayCmd, type IntakeState, createIntake };

package/dist/idempotent-intake/index.js

@@ -1,7 +0,0 @@
-export { createIntake } from '../chunk-ZVJZ72HY.js';
-import '../chunk-BYQUGDD3.js';
-import '../chunk-K575PT4S.js';
-import '../chunk-MU6MCIAC.js';
-import '../chunk-FV3Z5MBE.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/idempotent-intake/index.js.map

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

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

@@ -1,310 +0,0 @@
-import { C as Cmd } from '../core-Bjc0bS8j.js';
-import { RunCmd, SucceedMsg, FailMsg, ResilientState } from '../resilient-call/index.js';
-import { RetryPolicy } from '../retry-backoff/index.js';
-import { DeadlineExceeded, DeadlineSub } from '../deadline/index.js';
-export { deadlineSub, subscribeDeadline } from '../deadline/index.js';
-import '../cache/index.js';
-import '../types-D7u9DkH7.js';
-import '../circuit-breaker/index.js';
-import '../protocol-B5YmJr0d.js';
-import '../rate-limit/index.js';
-
-/**
- * @packageDocumentation
- * @demlik/tea/llm-call — `resilient-call` + structured-output parse + a typed
- * failure variant, around a purpose-discriminated LLM invocation.
- *
- * This is the ~60-line `call_llm` handler from the audit-agent seed
- * (`interpret.ts` / `effects.ts`) collapsed into the uniform L2 knob: a config
- * object, the resilient-call slice it inherits, and one interpret handler that
- * assembles messages, binds the structured-output schema for the call's
- * `purpose`, invokes the model (retry composed from `../resilient-call`, NOT
- * reinvented), parses the output, and RETURNS the enriched resilient settle Msg
- * (`resilient_ok` / `resilient_err`) so it re-enters the host reducer and drives
- * the inherited succeed/fail → backoff → onTimer loop.
- *
- * ## What it adds over `../resilient-call`
- *
- *   - **Two DI ports** (the seed's two seams):
- *       1. `model: (modelId) => LLM` — the model factory. Tests pass a fake so
- *          the handler runs end-to-end without touching a real provider; the
- *          production worker wires `createChatModel(env, …)`.
- *       2. `loadMessages: Loader` — the SDK / message loader. The seed lazy-
- *          imports `@langchain/core/messages` (a top-level `import type` blows
- *          up the workers test runner); the loader keeps that import lazy and
- *          stubbable. It produces the `BaseMessage[]` for a given call.
- *   - **Structured-output parse** — each `purpose` maps to a `Schema` in
- *     `config.schemas`. The handler binds `model.withStructuredOutput(schema)`
- *     so the invoke resolves to a typed object; a `Schema.parse` that throws
- *     becomes a `resilient_err` carrying an `LlmErr` (a parse failure is a
- *     failure, not a stall — "errors are data"). `withStructuredOutput` is the
- *     seed's brain-only path; the fake model in tests returns the typed object
- *     directly.
- *   - **A typed failure variant** — every failure (model throw, timeout-via-
- *     retry-exhaustion, schema parse) is surfaced as the `LlmErr` carried on the
- *     enriched `resilient_err` settle Msg, tagged with the `purpose` so the
- *     consumer's reducer routes per-stage. The seed dispatched
- *     `llm_failed{purpose}`; the consumer rebuilds that shape in its reducer arm
- *     from `m.error: LlmErr`.
- *
- * ## Inheriting resilient-call by composition (not reinvention)
- *
- * The retry / backoff lives in `../resilient-call`: `createLlmCall` builds a
- * `createResilientCall` knob over the model-invoke port and DELEGATES `init`,
- * `attempt`, `succeed`, `fail`, `onTimer`, `subs` to it verbatim — the slice is
- * literally resilient-call's slice (the spec's "retry lives here"). There is no
- * second backoff implementation here. The handler runs the invoke through the
- * resilient-call handler so a transient model failure backs off exactly as a
- * resilient HTTP call would; the `purpose`-branch + structured parse wrap the
- * port the resilient handler drives.
- *
- * ## The two non-negotiables (canon, inherited)
- *
- *   - **Durable** — the slice is resilient-call's plain-data slice (a Model
- *     field). Input carried on the `resilient_run` Cmd is the plain
- *     `LlmCall` request (purpose + modelId + payload) — no closures.
- *   - **Replayable** — every transition is a resilient-call verb; the handler
- *     is the only impurity, and the one clock read is `Date.now()` at the
- *     effect boundary (inside the handler), exactly as the seed stamped its
- *     `llm_responded` / `llm_failed` Msgs.
- *
- * ## Typical wiring
- *
- *   const llm = createLlmCall<MyPurpose, MyOutputs>({
- *     model: (id) => createChatModel(env, id),
- *     schemas: { plan: planSchema, report: reportSchema },
- *     retry: defaultRetryPolicy,
- *     loadMessages: defaultMessagesLoader,
- *   });
- *
- *   // in the machine:
- *   init: () => [{ resilience: llm.init() }, []],
- *   update: {
- *     call_llm:  (s, m) => lift(s, llm.attempt(s.resilience, m.input, m.at)),
- *     // `resilient_ok` / `resilient_err` RE-ENTER from `handlers` (the settle
- *     // Msg the interpret handler returns). Run the inherited verb FIRST so the
- *     // succeed/fail → backoff → onTimer loop advances, THEN fold the enriched
- *     // payload (`m.result: LlmOk` / `m.error: LlmErr`) into the host's own
- *     // state — the enrichment lives in the reducer arm, not the handler.
- *     resilient_ok:  (s, m) => {
- *       const [slice, cmds] = llm.succeed(s.resilience, m.key, m);
- *       return [{ ...s, resilience: slice, output: m.result.output }, cmds];
- *     },
- *     resilient_err: (s, m) => {
- *       const [slice, cmds] = llm.fail(s.resilience, m.key, m);
- *       return [{ ...s, resilience: slice, failure: m.error }, cmds];
- *     },
- *     deadline_exceeded: (s, m) => lift(s, llm.onTimer(s.resilience, m)),
- *   },
- *   subscriptions: (s) => llm.subs(s.resilience),
- *   subscribe: { deadline: subscribeDeadline },
- *   interpret: llm.handlers(),
- */
-
-/**
- * The minimal structured-output schema contract: `parse(unknown) => T`, the
- * zod-style call the handler uses to validate the model's output before it
- * settles `resilient_ok`. A throwing `parse` (the zod contract on invalid
- * input) propagates out of `invokeOne` and is caught by the resilient handler,
- * which settles `resilient_err` (enriched to `LlmErr`) — a parse failure is a
- * failure, never a silent pass. Structural so a real `z.ZodType<T>` satisfies
- * it without an import.
- */
-interface Schema<T> {
-    /** Validate + narrow `value` to `T`, or throw on mismatch (the zod contract). */
-    parse(value: unknown): T;
-}
-/**
- * The minimal chat-model contract every model the handler talks to must
- * satisfy — the seed's `InjectableChatModel`, trimmed to the one operation
- * llm-call drives for brain-only stages:
- *
- *   `withStructuredOutput(schema)` → a runnable whose `invoke(messages)`
- *   resolves to a typed object matching `schema`.
- *
- * `BaseChatModel` from `@langchain/core` is the runtime type; this surface
- * names only what llm-call calls so a test fake can ignore the rest. Generic
- * over the message shape `Msg` so a consumer's loader and model agree on it
- * without llm-call inspecting messages.
- */
-interface Llm<Msg> {
-    withStructuredOutput<T>(schema: Schema<T>): {
-        invoke(messages: readonly Msg[]): Promise<T>;
-    };
-}
-/**
- * Build the `Msg[]` the handler hands to the bound model for a given call. The
- * SDK / message-assembly seam — the seed's `buildBaseMessages` + the lazy
- * `loadMessages` loader rolled into one injected port. Async because the seed
- * lazy-imports the SDK (a top-level `import type` of the langchain messages
- * package explodes the workers test runner). Receives the full `LlmCall` so it
- * can branch on `purpose` exactly as the seed's `buildBaseMessages` did.
- */
-type MessageLoader<P extends string, Msg> = (call: LlmCall<P>) => Promise<readonly Msg[]>;
-/**
- * The model factory — the first DI port. `(modelId) => Llm`. Tests pass a fake
- * builder; production wires `createChatModel(env, getModelConfig(id))`. `null`
- * means "the host's default model" (the seed's `string | null`).
- */
-type ModelFactory<Msg> = (modelId: string | null) => Llm<Msg>;
-/**
- * The llm-call knob. `model` and `schemas` are the load-bearing pair — the
- * model factory DI port and the per-purpose structured-output targets; the
- * rest is optional, exactly the resilient-call "omit a brick → omit its gate"
- * story for `retry`:
- *
- *   - `model`        — DI port 1: the model factory.
- *   - `schemas`      — one `Schema` per `Purpose`. The handler binds
- *                      `schemas[call.purpose]` as the structured-output target.
- *   - `retry`        — backoff policy, composed straight into `../resilient-
- *                      call`. Omit it and a model failure is terminal (no
- *                      backoff), exactly as resilient-call with no retry brick.
- *   - `loadMessages` — DI port 2: the SDK / message loader. Omit it and the
- *                      handler invokes the bound model with `[]` (a degenerate
- *                      but valid call) — provide it to assemble real messages.
- *
- * `P` is the purpose union (e.g. `"plan" | "report"`); `O` maps each purpose to
- * its parsed output type; `Msg` is the model's message shape (threaded through
- * the loader + model so llm-call never inspects a message).
- */
-interface LlmCallConfig<P extends string, O extends Record<P, unknown>, Msg = unknown> {
-    /** DI port 1 — the model factory. `(modelId) => Llm`. */
-    readonly model: ModelFactory<Msg>;
-    /** One structured-output schema per purpose; the parse target the handler binds. */
-    readonly schemas: {
-        readonly [K in P]: Schema<O[K]>;
-    };
-    /** Backoff policy, composed into `../resilient-call`. Omit → no backoff. */
-    readonly retry?: RetryPolicy;
-    /** DI port 2 — the SDK / message loader. Omit → the handler invokes with `[]`. */
-    readonly loadMessages?: MessageLoader<P, Msg>;
-}
-/**
- * One LLM call request — the resilient-call `input` for this knob, carried on
- * the `resilient_run` Cmd as plain data (no closures, invariant 3). Mirrors the
- * seed's purpose-discriminated `CallLlmCmd`: a `purpose` selecting the schema +
- * prompt assembly, the `model` id, and the opaque per-purpose `payload` the
- * loader consumes.
- *
- * `key` defaults to `purpose` when the consumer calls `attempt(s, purpose, …)`,
- * so one in-flight call per purpose is tracked under the resilient-call slice —
- * the common single-call-per-stage shape. A consumer that fans out many calls
- * of one purpose passes a distinct `key`.
- */
-interface LlmCall<P extends string> {
-    /** The stage / schema selector — drives both `schemas[purpose]` and message assembly. */
-    readonly purpose: P;
-    /** The model id to invoke; `null` = the host's default model. */
-    readonly model: string | null;
-    /** The per-purpose prompt payload the `MessageLoader` consumes. Opaque to the knob. */
-    readonly payload: unknown;
-}
-/** The parsed, typed success carried on the `resilient_ok` settle Msg, tagged with its purpose. */
-interface LlmOk<P extends string, O extends Record<P, unknown>> {
-    readonly key: string;
-    readonly purpose: P;
-    readonly output: O[P];
-}
-/** The typed failure variant — every failure path surfaces this, tagged by purpose. */
-interface LlmErr<P extends string> {
-    readonly key: string;
-    readonly purpose: P;
-    /** A human-readable cause (model throw, retry-exhaustion, or schema parse). */
-    readonly reason: string;
-    /** The original error, carried untouched for the consumer to inspect. */
-    readonly error: unknown;
-}
-/**
- * The settle Msgs llm-call's handler RETURNS from `interpret` so the substrate
- * enqueues them as follow-up Msgs (re-entry) into the host reducer — exactly as
- * `../resilient-call` does. They are the resilient-call settle Msgs with the
- * payloads ENRICHED to llm-call's typed variants: `result` is the parsed,
- * purpose-tagged `LlmOk`; `error` is the typed `LlmErr` (purpose + reason +
- * raw). The host wires `resilient_ok` → `succeed` and `resilient_err` → `fail`
- * reducer arms (the doc-comment wiring), and folds the enriched payload into its
- * own state there — llm-call never forces a Msg vocabulary on the host, and the
- * settle Msg drives the inherited succeed/fail → backoff → onTimer loop instead
- * of bypassing it.
- */
-type LlmSucceedMsg<P extends string, O extends Record<P, unknown>> = SucceedMsg<LlmOk<P, O>>;
-type LlmFailMsg<P extends string> = Omit<FailMsg, "error"> & {
-    readonly error: LlmErr<P>;
-};
-/** The retry / deadline timer Msg — `DeadlineExceeded`, inherited from resilient-call. */
-type LlmTimerMsg = DeadlineExceeded;
-/**
- * The ports the LEGACY detached `handlers(ports)` form takes. Two outbound Msg
- * builders the handler hands the typed Ok / Err; the consumer returns its own
- * Msg (or `undefined`). KEPT only for `../agent`, which still inherits the
- * detached shape; that path does NOT drive the retry loop (it dispatches the
- * consumer's Msg directly and never re-enters the resilient settle Msg). New
- * consumers use the no-arg `handlers()` form, which RETURNS the settle Msg for
- * re-entry and drives the inherited succeed/fail → backoff → onTimer loop.
- * `../agent` carries the same retry-loop gap and is fixed separately.
- *
- * The builders return `M | undefined` — `undefined` is the "dispatch nothing"
- * sentinel the detached form checks (`!== undefined`), spelled as `undefined`
- * rather than `void` so the union is unambiguous (a `void` member of a union is
- * confusing and reads as "may return anything").
- */
-interface LlmCallPorts<P extends string, O extends Record<P, unknown>, M> {
-    /** Build the Msg dispatched on a parsed success. Return `undefined` to dispatch nothing. */
-    readonly onOk: (ok: LlmOk<P, O>) => M | undefined;
-    /** Build the Msg dispatched on any failure (throw / retry-exhausted / parse). */
-    readonly onErr: (err: LlmErr<P>) => M | undefined;
-}
-/**
- * The effect Cmd the knob emits: run the LLM call for `key` with `input`. The
- * `input` is the plain `LlmCall` request — the handler reads `purpose` /
- * `model` / `payload` off it (invariant 3: Cmds are data).
- *
- * It is `../resilient-call`'s `RunCmd` specialized to the `LlmCall` input — NOT a
- * re-declared shape — so the resilient verbs' return tuples (`[State, RunCmd[]]`)
- * are this exact type and thread through `attempt` / `succeed` / `fail` /
- * `onTimer` with no cast.
- */
-type LlmRunCmd<P extends string> = RunCmd<LlmCall<P>>;
-/**
- * Build an llm-call knob from `config`. `rng` is injected for the inherited
- * retry jitter (pass a fixed `() => 0.5` in tests to pin backoff; defaults to
- * `Math.random`, read only at the resilient-call verb boundary).
- *
- * Returns the uniform L2 knob contract. The slice + verbs (`init`, `attempt`,
- * `succeed`, `fail`, `onTimer`, `subs`) are DELEGATED to a `../resilient-call`
- * knob built over the structured-output model-invoke port — no second backoff
- * here. `handlers` is the one new piece: the purpose-branching, schema-parsing
- * wrapper that returns the enriched resilient settle Msg for re-entry.
- *
- * `P` is the purpose union, `O` the purpose→output map, `Msg` the model's
- * message shape.
- */
-declare function createLlmCall<P extends string, O extends Record<P, unknown>, Msg = unknown>(config: LlmCallConfig<P, O, Msg>, rng?: () => number): {
-    init: () => ResilientState<LlmCall<P>, LlmOk<P, O>>;
-    attempt: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>, input: LlmCall<P>, at: number, key?: string) => readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly LlmRunCmd<P>[]];
-    succeed: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>, key: string, msg: LlmSucceedMsg<P, O>) => readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly LlmRunCmd<P>[]];
-    fail: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>, key: string, msg: LlmFailMsg<P>) => readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly LlmRunCmd<P>[]];
-    onTimer: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>, msg: LlmTimerMsg) => readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly LlmRunCmd<P>[]];
-    subs: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>) => readonly DeadlineSub[];
-    handlers: {
-        (): {
-            resilient_run: (cmd: LlmRunCmd<P>) => Promise<LlmSucceedMsg<P, O> | LlmFailMsg<P>>;
-        };
-        <M>(ports: LlmCallPorts<P, O, M>): {
-            resilient_run: (cmd: LlmRunCmd<P>, ctx: {
-                waitUntil(p: Promise<unknown>): void;
-                dispatch(msg: M): unknown;
-            }) => void;
-        };
-    };
-    invokeOne: (input: LlmCall<P>) => Promise<LlmOk<P, O>>;
-};
-/**
- * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the
- * slice lives at `state.resilience` — the same convenience `../resilient-call`
- * ships, re-typed for the llm-call slice so consumers wire one import. Pure.
- */
-declare function liftLlmCall<S extends {
-    resilience: ResilientState<LlmCall<P>, LlmOk<P, O>>;
-}, P extends string, O extends Record<P, unknown>, C extends Cmd>(state: S, result: readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly C[]]): readonly [S, readonly C[]];
-
-export { DeadlineExceeded, DeadlineSub, type Llm, type LlmCall, type LlmCallConfig, type LlmCallPorts, type LlmErr, type LlmFailMsg, type LlmOk, type LlmRunCmd, type LlmSucceedMsg, type LlmTimerMsg, type MessageLoader, type ModelFactory, ResilientState, type Schema, createLlmCall, liftLlmCall };

package/dist/llm-call/index.js

@@ -1,16 +0,0 @@
-export { createLlmCall, liftLlmCall } from '../chunk-ND3DH6KM.js';
-import '../chunk-EUF7XOEE.js';
-import '../chunk-JELSZN25.js';
-export { deadlineSub, subscribeDeadline } from '../chunk-JGVL3WPL.js';
-import '../chunk-Q2UM7BXU.js';
-import '../chunk-S2EGRPCM.js';
-import '../chunk-UF4MZSLT.js';
-import '../chunk-7SVIRMC6.js';
-import '../chunk-3JU6657S.js';
-import '../chunk-2YFLOCWX.js';
-import '../chunk-ZJ5AOYBH.js';
-import '../chunk-G5E74IJB.js';
-import '../chunk-5EHLEUTL.js';
-import '../chunk-B5VXOFMZ.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

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

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