@demlik/tea 0.13.0 → 0.15.0

package/dist/index.js

@@ -1,4 +1,3 @@
-export { DispatchDiscardedError, DisposeTimeoutNotice, IdentityDropNotice, PortNameCollisionError, QuiescenceTimeoutError, RuntimeDiscardNotice, RuntimeDiscardedError, SubIdCollisionError, __resetPortRegistry, absurd, asReducer, defineMachine, definePort, historyTracker, noop, replay, run, schemaMigrate, settle, tryApplyCell, tryFoldMsgs, tryInterpret, wrapDetached } from './chunk-ZSUUOEPL.js';
-export { Cmd, NoCellError, acceptsOf, applyCell, applyCellChecked, describeMachine, detectUpdateForm, foldMsgs, foldUpdates, formOf, msgKeysOf, structuralHash, subId } from './chunk-OOYD44JI.js';
+export { Cmd, DispatchDiscardedError, DisposeTimeoutNotice, DriveFailedError, DriveStalledError, IdentityDropNotice, NO_ACK, NoCellError, PortNameCollisionError, ProvideFailedError, ProviderCycleError, QuiescenceTimeoutError, RuntimeDiscardNotice, RuntimeDiscardedError, StoreConflictError, SubIdCollisionError, UnknownProviderError, __resetPortRegistry, absurd, acceptedTypes, acceptsOf, ack, applyCell, applyCellChecked, asReducer, combineManagedResources, defineListener, defineMachine, defineManagedResource, definePort, dep, describeMachine, detectUpdateForm, driveToDone, foldMsgs, foldUpdates, formOf, fromBroadcastChannel, fromEventSource, fromEventTarget, fromInterval, fromPort, fromReconnectingWebSocket, fromTimeout, fromTransport, fromWebSocket, historyTracker, initAck, isFencedStore, isProvided, layer, liftSlice, msgKeysOf, nextSeq, noop, partitionByAck, provide, readInOrder, reconcile, replay, run, schemaMigrate, settle, structuralHash, subId, tagSeq, tryApplyCell, tryFoldMsgs, tryInterpret, value, wrapDetached } from './chunk-66PY5WYF.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/jev/index.d.ts

@@ -0,0 +1,646 @@
+import { b as CmdDef, C as Cmd } from '../core-DnzqWy6u.js';
+import { RetryPolicy } from '../retry-backoff/index.js';
+import { R as RunCmd, F as FailMsg, S as SucceedMsg, a as ResilientState } from '../index-CA_7I5g9.js';
+export { m as mountResilientCall } from '../index-CA_7I5g9.js';
+import { a as DeadlineSub, D as DeadlineExceeded, T as TtlCache, C as CacheEvictionSub, c as CacheEvictMsg } from '../index-HSYgG2Yt.js';
+export { b as deadlineSub, s as subscribeDeadline } from '../index-HSYgG2Yt.js';
+import { S as SubscribeHandler } from '../types-BseNPIhr.js';
+import { B as BatchWindow, a as BatchWindowSub, b as BatchWindowExpired } from '../index-C2DwkjlP.js';
+import { F as FanOutState } from '../index-CuNO9m8i.js';
+import 'zod';
+import '../index-CSyMYDAB.js';
+import '../runtime-types-CMF13BBh.js';
+import 'better-result';
+
+/**
+ * @packageDocumentation
+ * internal/jev/protocol — the wire contract of TypeSafe **Jev** (System One)
+ * as types plus two pure functions, and nothing that performs I/O. Internal
+ * since #216 — not published on any subpath; the `ask` child that opens the
+ * socket imports it from here.
+ *
+ * The contract is transcribed from `https://docs.typesafe.ai/api`, re-verified
+ * 2026-09-21: `POST https://api.typesafe.ai/v1/systemone`, `Authorization:
+ * Bearer <API_KEY>`, request `{ state, model, questions }`, response
+ * `{ model, answers, usage }`. Where this module and that page disagree, the
+ * page is right and this module is a bug.
+ *
+ * ## What this module is for
+ *
+ * A Jev call is a map of questions you name, and an answer comes back under
+ * each name. That is a shape TypeScript can hold onto, and the whole point of
+ * typing it here is that a **choice** question's `criteria` keys ARE its
+ * answer's `choice` domain — write the rubric once and the narrowing is free
+ * at the call site:
+ *
+ * ```ts
+ * const qs = jevQuestions({
+ *   category: {
+ *     type: "choice",
+ *     instructions: "Which budget line is this?",
+ *     criteria: { groceries: "Supermarkets", dining: "Restaurants" },
+ *   },
+ * });
+ * // parsed.answers.category.choice : "groceries" | "dining"
+ * ```
+ *
+ * `jevQuestions` is an identity function with a `const` type parameter; it
+ * exists so the literal keys survive inference without every call site
+ * spelling `as const`. `JevAnswers<Q>` is the mapped type that turns such a
+ * questions map into its answers map.
+ *
+ * ## Why parsing is a pure function returning data
+ *
+ * `parseAnswers` never throws — a response that disagrees with the questions
+ * that produced it is a recoverable failure with an obvious next move (retry,
+ * re-prompt, give up on this one item), so it is DATA: a closed `JevErr`
+ * union of `{ _tag }` values that survives a JSON round-trip into Model
+ * (ADR 0011). The type-level guarantee above is a *claim about the wire*, and
+ * `parseAnswers` is the one place that claim is checked against a body the
+ * network actually produced. Every `unknown` reaches a `JevErr`; nothing
+ * reaches a `throw`.
+ *
+ * The check itself is a `zod` schema DERIVED from the questions map, so the
+ * typed value is what `safeParse` returns rather than something asserted after
+ * a hand-walk. Both halves of a choice question's claim are structural in that
+ * schema: `choice` is a `z.enum` over the criteria keys, and `probabilities`
+ * is a strict `z.object` whose shape IS those keys — so a distribution missing
+ * one or carrying an extra fails the schema rather than a separate arm a later
+ * reader has to remember. A partial distribution typed `Record<K, number>` is
+ * the representable-invalid state this module exists to refuse, and it arrives
+ * through this gate or not at all. The envelope is checked by the same schema:
+ * `model` is a string and `usage` carries two finite numbers.
+ *
+ * `safeParse`, never `parse`: a zod failure is turned into a `JevErr` value by
+ * mapping its first issue's path onto the arm that names it.
+ *
+ * ## Why status classification lives here and not in `ask`
+ *
+ * "429 and 529 back off, everything else non-2xx is terminal" is a fact about
+ * the protocol, published in the same reference page as the body shapes, and
+ * `ask` re-deriving it is how the retry policy and the wire contract drift
+ * apart. `classifyStatus` is the single reading.
+ *
+ * ## Bounds the API enforces and this module does not
+ *
+ * A Choice takes at most 255 options and a Score takes at most 10 levels.
+ * `JevScoreQuestion` encodes the *lower* bound — a Score with fewer than two
+ * levels does not compile — because a two-element minimum is a tuple, which
+ * costs nothing. The upper bounds are not encoded: spelling them as a union
+ * of nine tuple arities (or 255 of them) buys a compile error in place of a
+ * `422`, at the price of unreadable diagnostics on every ordinary Score. They
+ * are the API's `422`, which `classifyStatus` already calls terminal.
+ */
+/**
+ * What every `instructions` and every criterion description accepts.
+ *
+ * The reference page allows a string, an object, or an array in all three
+ * slots: a long question carrying data it refers to is written as an object
+ * with the question in one field and the data in the others. Typing it as
+ * `string` alone would reject the documented structured form.
+ */
+type JevText = string | Readonly<Record<string, unknown>> | readonly unknown[];
+/** The three question types, as the `type` discriminant spells them. */
+type JevQuestionType = "choice" | "score" | "noul";
+/**
+ * A choice question's rubric: option key → description, or `null` where an
+ * option needs no extra detail. The keys are the answer's `choice` domain.
+ */
+type JevChoiceCriteria = Readonly<Record<string, JevText | null>>;
+/** Pick one option from a set you define. */
+interface JevChoiceQuestion<C extends JevChoiceCriteria = JevChoiceCriteria> {
+    readonly type: "choice";
+    readonly instructions: JevText;
+    readonly criteria: C;
+}
+/**
+ * A score question's rubric: an ORDERED list of level descriptions, at least
+ * two of them. The API accepts up to ten.
+ */
+type JevScoreCriteria = readonly [JevText, JevText, ...JevText[]];
+/** Rate the state along an ordered rubric. */
+interface JevScoreQuestion {
+    readonly type: "score";
+    readonly instructions: JevText;
+    readonly criteria: JevScoreCriteria;
+}
+/** A yes/no question. `criteria` is optional; both arms are required when it is present. */
+interface JevNoulQuestion {
+    readonly type: "noul";
+    readonly instructions: JevText;
+    readonly criteria?: {
+        readonly true: JevText;
+        readonly false: JevText;
+    };
+}
+/** One typed question. */
+type JevQuestion = JevChoiceQuestion | JevScoreQuestion | JevNoulQuestion;
+/** The `questions` map: an id you choose → the question asked under it. */
+type JevQuestionMap = Readonly<Record<string, JevQuestion>>;
+/**
+ * Identity, with the literal keys kept.
+ *
+ * The `const` type parameter is the whole function: it preserves each choice
+ * question's `criteria` keys as literals, so `JevAnswers<typeof qs>` can name
+ * them. Without it the inferred type is `Record<string, string>` and the
+ * narrowing this module exists for is gone before `parseAnswers` is reached.
+ */
+declare const jevQuestions: <const Q extends JevQuestionMap>(questions: Q) => Q;
+/** The evaluation endpoint. */
+declare const JEV_ENDPOINT: "https://api.typesafe.ai/v1/systemone";
+/** The content to evaluate: text, or structured data. */
+type JevState = string | Readonly<Record<string, unknown>> | readonly unknown[];
+/** The request body of `POST /v1/systemone`. */
+interface JevRequest<Q extends JevQuestionMap = JevQuestionMap> {
+    readonly state: JevState;
+    readonly model: string;
+    readonly questions: Q;
+}
+/** The yes/no answer, on a scale from 0 (no) to 1 (yes). */
+interface JevNoulAnswer {
+    readonly type: "noul";
+    readonly noul: number;
+}
+/**
+ * The chosen option and the full distribution over the options.
+ *
+ * `K` is the choice question's own criteria keys, which is why `choice` is a
+ * union rather than a `string` and `probabilities` is total over the options.
+ */
+interface JevChoiceAnswer<K extends string = string> {
+    readonly type: "choice";
+    readonly choice: K;
+    readonly probabilities: Readonly<Record<K, number>>;
+    readonly confidence: number;
+}
+/**
+ * The probability-weighted value across the levels — it can land BETWEEN
+ * levels, which is why `score` is a `number` and not an index. `legend` and
+ * `probabilities` are keyed by the level index as a string.
+ */
+interface JevScoreAnswer {
+    readonly type: "score";
+    readonly score: number;
+    readonly legend: Readonly<Record<string, string>>;
+    readonly probabilities: Readonly<Record<string, number>>;
+    readonly confidence: number;
+}
+/** One typed answer. */
+type JevAnswer = JevChoiceAnswer | JevScoreAnswer | JevNoulAnswer;
+/** The answer a given question type yields, with the choice union carried through. */
+type JevAnswerFor<Q> = Q extends {
+    readonly type: "choice";
+    readonly criteria: infer C;
+} ? JevChoiceAnswer<Extract<keyof C, string>> : Q extends {
+    readonly type: "score";
+} ? JevScoreAnswer : Q extends {
+    readonly type: "noul";
+} ? JevNoulAnswer : never;
+/** A questions map turned into its answers map, id for id. */
+type JevAnswers<Q extends JevQuestionMap> = {
+    readonly [K in keyof Q]: JevAnswerFor<Q[K]>;
+};
+/** Token usage for the request. */
+interface JevUsage {
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+}
+/** The response body of `POST /v1/systemone`. */
+interface JevResponse<Q extends JevQuestionMap = JevQuestionMap> {
+    readonly model: string;
+    readonly answers: JevAnswers<Q>;
+    readonly usage: JevUsage;
+}
+/**
+ * Every way a response can fail to be the answers to the questions asked.
+ *
+ * Closed, `{ _tag }`-discriminated, JSON-round-trippable: a consumer folds one
+ * of these into Model and routes on `_tag` (ADR 0011). `path` and `id` say
+ * WHERE, so a failure names the question it is about rather than the whole
+ * call.
+ */
+type JevErr = 
+/** The envelope is not a Jev response at all — not an object, or `model` /
+ *  `answers` / `usage` missing or of the wrong shape. */
+{
+    readonly _tag: "malformed_body";
+    readonly reason: string;
+}
+/** A question id in the request has no answer under it in the response. */
+ | {
+    readonly _tag: "missing_answer";
+    readonly id: string;
+}
+/** An answer arrived, but its `type` is not its question's. */
+ | {
+    readonly _tag: "answer_type_mismatch";
+    readonly id: string;
+    readonly expected: JevQuestionType;
+    readonly received: string;
+}
+/** A choice answer picked something that is not one of its criteria keys. */
+ | {
+    readonly _tag: "off_criteria_choice";
+    readonly id: string;
+    readonly choice: string;
+    readonly options: readonly string[];
+}
+/** A choice answer's `probabilities` keys are not exactly its question's
+ *  criteria keys. `JevChoiceAnswer<K>` types that map as TOTAL over `K`, so
+ *  a partial or off-criteria one is the representable-invalid state this
+ *  module exists to refuse. `missing` and `extra` say which way it failed. */
+ | {
+    readonly _tag: "off_criteria_probabilities";
+    readonly id: string;
+    readonly missing: readonly string[];
+    readonly extra: readonly string[];
+    readonly options: readonly string[];
+}
+/** The answer's `type` is right and its payload is not — a missing
+ *  `confidence`, a `probabilities` that is not a number map, and so on. */
+ | {
+    readonly _tag: "malformed_answer";
+    readonly id: string;
+    readonly reason: string;
+};
+/**
+ * Is `value` a {@link JevErr}?
+ *
+ * The discriminant is the `_tag` VALUE against the closed set above, never the
+ * bare presence of the key. A `JevAnswers` map is keyed by the caller's own
+ * question ids, so a caller may legally name a question `_tag` — and then
+ * `"_tag" in answers` is `true`. The value under it is an ANSWER, which is
+ * always an object and never one of these string literals, so reading the
+ * value is the one test a caller's id space cannot reach.
+ */
+declare function isJevErr(value: object): value is JevErr;
+/** What `parseAnswers` returns: typed answers, or one `JevErr`. Never a throw. */
+type JevParse<Q extends JevQuestionMap> = {
+    readonly ok: true;
+    readonly answers: JevAnswers<Q>;
+    readonly model: string;
+    readonly usage: JevUsage;
+} | {
+    readonly ok: false;
+    readonly error: JevErr;
+};
+/**
+ * Turn an `unknown` response body into the typed answers for `questions`, or
+ * into one `JevErr`. Pure, total, and never throwing on any input.
+ *
+ * The schema is question-driven: every id the request asked about must be
+ * answered, each answer is checked against ITS question's type and — for a
+ * choice — against that question's own criteria keys, both as the `choice`
+ * picked and as the exact key set of `probabilities`. An answer under an id
+ * nobody asked about is dropped rather than refused.
+ */
+declare const parseAnswers: <Q extends JevQuestionMap>(questions: Q, body: unknown) => JevParse<Q>;
+/**
+ * What a caller does next with an HTTP status.
+ *
+ * `retry` means back off and send it again; `terminal` means this request will
+ * never succeed as written. `ok` is the 2xx arm — naming it keeps the function
+ * total, so `ask` switches on three cases instead of testing 2xx itself and
+ * then asking here.
+ */
+type JevHttpStatus = "ok" | "retry" | "terminal";
+/**
+ * Classify one HTTP status, per the reference page's error table.
+ *
+ * 429 (rate limited) and 529 (overloaded) are the two the page tells you to
+ * back off on. 401 (bad key) and 422 (the body failed validation) will fail
+ * identically forever. Every other non-2xx is terminal by default: an
+ * unrecognized failure is not evidence that retrying helps, and a retry loop
+ * over one is the expensive way to find that out.
+ */
+declare const classifyStatus: (status: number) => JevHttpStatus;
+
+/**
+ * The injected HTTP caller — the one seam that touches the network.
+ *
+ * It returns the status and the undecoded body rather than throwing on a
+ * non-2xx, because WHICH non-2xx it is decides whether the call backs off, and
+ * a thrown adapter error has already lost that. `signal` is optional so a
+ * `fetch` adapter can be cancelled; resilient-call issues no signal today, and
+ * the slot exists so an adapter's own shape does not have to change when it
+ * does.
+ *
+ * A `fetch` adapter and a scripted test fake satisfy this identically, which is
+ * the whole reason the key lives in the adapter's closure and never in config.
+ */
+type JevPort<Q extends JevQuestionMap = JevQuestionMap> = (request: JevRequest<Q>, signal?: AbortSignal) => Promise<{
+    readonly status: number;
+    readonly body: unknown;
+}>;
+/**
+ * The pure decider that answers when the network cannot.
+ *
+ * Called on exactly two paths: `port` is absent (the no-key case), and the
+ * resilient retry budget is spent. It must be a pure function of the request —
+ * the exhaustion path runs it inside the `fail` VERB, which replay re-runs, so
+ * a clock read or an I/O call here would make the machine unreplayable.
+ * Returning a {@link JevErr} is how a fallback says "I have no answer for
+ * this one"; the call then settles as that error.
+ */
+type JevFallback<Q extends JevQuestionMap> = (request: JevRequest<Q>) => JevAnswers<Q> | JevErr;
+/**
+ * Every way an ask can fail, as DATA.
+ *
+ * A superset of the protocol child's {@link JevErr}: a parse failure is
+ * reported with the protocol's own tag untouched, and the three tags below are
+ * the ones only a caller can observe. `{_tag}`-discriminated and
+ * JSON-round-trippable like the rest (ADR 0011), because it is carried on the
+ * settle Msg and stored in the slice's `failed` phase.
+ *
+ * `http_retry` and `port_threw` are the TRANSIENT pair — {@link isTransientJevAskErr}
+ * is the single reading, and `fail` backs off on exactly those two.
+ */
+type JevAskErr = JevErr
+/** 429 / 529 — the statuses `classifyStatus` says to back off on. */
+ | {
+    readonly _tag: "http_retry";
+    readonly status: number;
+}
+/** 401 / 422 / any other non-2xx — this request fails identically forever. */
+ | {
+    readonly _tag: "http_terminal";
+    readonly status: number;
+}
+/** The port itself rejected (a socket error, a DNS failure) — transient. */
+ | {
+    readonly _tag: "port_threw";
+    readonly reason: string;
+}
+/** No `port` and no `fallback`: the knob was configured with no way to answer. */
+ | {
+    readonly _tag: "no_answer_path";
+};
+/**
+ * Does this failure deserve another attempt?
+ *
+ * The one place the transient/terminal split is read. A rate limit and a dropped
+ * socket are the two failures a second attempt can clear; a 401, a 422 and every
+ * parse failure will reproduce exactly, so retrying one spends a real HTTP call
+ * to learn nothing.
+ */
+declare function isTransientJevAskErr(error: JevAskErr): boolean;
+/**
+ * The carrier that gets a {@link JevAskErr} out of the port and through
+ * resilient-call's throw seam intact.
+ *
+ * resilient-call routes a rejected port to a failure Msg carrying the raw
+ * thrown value, so throwing is the only way the handler can say "this attempt
+ * failed" — and a bare `Error` would arrive with its classification already
+ * lost. The typed payload rides on `jev`; the slice never stores this object
+ * (the verbs store `jev` itself), so nothing un-serializable reaches Model.
+ */
+declare class JevAskFailure extends Error {
+    readonly jev: JevAskErr;
+    constructor(jev: JevAskErr);
+}
+/** The model the door asks for when config names none. */
+declare const DEFAULT_JEV_MODEL = "jev-latest";
+/**
+ * The jev-ask knob. `questions` is the load-bearing one: it is both the map
+ * sent on every request and the type that makes the answers narrow at the call
+ * site, so it belongs to the knob rather than to a call.
+ */
+interface JevAskConfig<Q extends JevQuestionMap> {
+    /** The question map every request carries; its keys type the answers. */
+    readonly questions: Q;
+    /** DI port — the HTTP caller. Absent = the no-key case; `fallback` answers instead. */
+    readonly port?: JevPort<Q>;
+    /** The pure decider for the no-port and budget-spent paths. Absent → those settle as an error. */
+    readonly fallback?: JevFallback<Q>;
+    /** Backoff policy, composed into `../../resilience/resilient-call`. Omit → no backoff. */
+    readonly retry?: RetryPolicy;
+    /** The model id asked for. Defaults to {@link DEFAULT_JEV_MODEL}. */
+    readonly model?: string;
+}
+/**
+ * The settled answer carried on `resilient_ok`.
+ *
+ * `source` is not decoration: a fallback answer and a model answer are both
+ * valid answers with identical shape, and a host that routes on confidence — or
+ * bills on usage — has to be able to tell them apart. A fallback's `usage` is
+ * zero because nothing was spent.
+ */
+interface JevOk<Q extends JevQuestionMap> {
+    /** The typed answers, one per question id. */
+    readonly answers: JevAnswers<Q>;
+    /** The model that answered, as the response reported it (or the requested one, for a fallback). */
+    readonly model: string;
+    /** Tokens spent. Zero on the fallback path. */
+    readonly usage: JevUsage;
+    /** Which path produced this answer. */
+    readonly source: "port" | "fallback";
+}
+/**
+ * The one effect this knob emits: run the ask for `key` with the plain-data
+ * {@link JevRequest} (ADR 0014 — a Cmd is DECLARED, so its input, ok and err
+ * channels are types on the constructor rather than a convention). It is
+ * resilient-call's `runCmdDef` specialized to this door's input and result, the
+ * same way `../../idempotency/idempotent-intake` mints its defs per knob: `Q` is
+ * a type parameter, so the def is a factory and not a module constant.
+ */
+declare function jevAskCmdDef<Q extends JevQuestionMap>(): CmdDef<"resilient_run", {
+    readonly key: string;
+    readonly input: JevRequest<Q>;
+}, JevOk<Q>, {
+    readonly [detail: string]: unknown;
+    readonly _tag: "deadline_exceeded";
+} | {
+    readonly [detail: string]: unknown;
+    readonly _tag: "port_rejected";
+}, unknown>;
+/** The Cmd the verbs emit — `resilient_run` carrying the request. */
+type JevAskCmd<Q extends JevQuestionMap> = RunCmd<JevRequest<Q>>;
+/** The success settle Msg — resilient-call's, with `result` narrowed to {@link JevOk}. */
+type JevSucceedMsg<Q extends JevQuestionMap> = SucceedMsg<JevOk<Q>>;
+/** The failure settle Msg — resilient-call's, with `error` narrowed to {@link JevAskErr}. */
+type JevFailMsg = Omit<FailMsg, "error"> & {
+    readonly error: JevAskErr;
+};
+/** The retry / deadline timer Msg — `DeadlineExceeded`, inherited. */
+type JevTimerMsg = DeadlineExceeded;
+/**
+ * Build a jev-ask knob from `config`. `rng` is injected for the inherited retry
+ * jitter (pass a fixed `() => 0` in tests to pin backoff; defaults to
+ * `Math.random`, read only at resilient-call's verb boundary).
+ *
+ * The slice and five of the six verbs are resilient-call's, forwarded. `fail` is
+ * the one composed verb — it reads the {@link JevAskErr} the handler typed and
+ * routes on it (see its docblock); it reimplements no backoff. `handlers` is the
+ * new piece: the port call, the status classification, the parse, and the
+ * enriched settle Msg.
+ */
+declare function createJevAsk<Q extends JevQuestionMap>(config: JevAskConfig<Q>, rng?: () => number): {
+    name: "resilient";
+    init: () => ResilientState<JevRequest<Q>, JevOk<Q>>;
+    attempt: (s: ResilientState<JevRequest<Q>, JevOk<Q>>, key: string, content: JevState, at: number) => readonly [ResilientState<JevRequest<Q>, JevOk<Q>>, readonly JevAskCmd<Q>[]];
+    succeed: (s: ResilientState<JevRequest<Q>, JevOk<Q>>, key: string, msg: JevSucceedMsg<Q>) => readonly [ResilientState<JevRequest<Q>, JevOk<Q>>, readonly JevAskCmd<Q>[]];
+    fail: (s: ResilientState<JevRequest<Q>, JevOk<Q>>, key: string, msg: JevFailMsg) => readonly [ResilientState<JevRequest<Q>, JevOk<Q>>, readonly JevAskCmd<Q>[]];
+    onTimer: (s: ResilientState<JevRequest<Q>, JevOk<Q>>, msg: JevTimerMsg) => readonly [ResilientState<JevRequest<Q>, JevOk<Q>>, readonly JevAskCmd<Q>[]];
+    subs: (s: ResilientState<JevRequest<Q>, JevOk<Q>>) => readonly DeadlineSub[];
+    handlers: () => {
+        resilient_run: (cmd: JevAskCmd<Q>) => Promise<JevSucceedMsg<Q> | JevFailMsg>;
+    };
+    ask: (request: JevRequest<Q>, signal?: AbortSignal) => Promise<JevOk<Q>>;
+};
+/**
+ * The Cmd type a host machine declares in `types.cmd` when it splices a
+ * {@link createJevAsk} knob in — {@link JevAskCmd} under the name a `types`
+ * block reads well with. It is stated here so a host writes `cmd: {} as
+ * JevCmd<Questions>` rather than deriving it from the knob's shape, which is
+ * what `ReturnType<Ask["attempt"]>[1][number]` used to be doing at every call
+ * site: a spelling of the same type that breaks the moment `attempt`'s tuple
+ * changes, and that reads as machinery rather than as a name.
+ */
+type JevCmd<Q extends JevQuestionMap> = JevAskCmd<Q>;
+/**
+ * The Sub type a host machine declares in `types.sub` — the deadline Sub
+ * `subs` emits, inherited from resilient-call. Named here for the same reason
+ * as {@link JevCmd}: a host names the type, it does not re-derive it.
+ */
+type JevSub = DeadlineSub;
+/**
+ * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the slice
+ * lives at `state.resilience` — resilient-call's convenience, re-typed for this
+ * door's slice so a consumer wires one import. Pure.
+ *
+ * The record rebuild is `liftSlice` from the root door (#231), the same helper
+ * `liftResilience` is expressed over — this stays as the named, pre-keyed
+ * convenience for this door, unchanged in name, signature and subpath.
+ */
+declare function liftJevAsk<S extends {
+    resilience: ResilientState<JevRequest<Q>, JevOk<Q>>;
+}, Q extends JevQuestionMap, C extends Cmd>(state: S, result: readonly [ResilientState<JevRequest<Q>, JevOk<Q>>, readonly C[]]): readonly [S, readonly C[]];
+
+/**
+ * The rubric every item is classified against: option key → description, or
+ * `null` where an option needs no extra detail. `C` is the option union, and it
+ * is what makes an answer's `choice` narrow at the call site.
+ */
+type ClassifyCriteria<C extends string> = Readonly<Record<C, JevText | null>>;
+/** The one `choice` question an item is asked. */
+type ItemQuestion<C extends string> = JevChoiceQuestion<ClassifyCriteria<C>>;
+/**
+ * The `questions` map of one batch: one {@link ItemQuestion} per item, keyed by
+ * `keyOf(item)`. This IS Jev's native batch form — the questions map is the
+ * fan-out over items, so nothing here wraps the items in an envelope of its own.
+ */
+type ItemQuestions<C extends string> = Readonly<Record<string, ItemQuestion<C>>>;
+/** The answer one item's question yields. */
+type ItemAnswer<C extends string> = JevAnswerFor<ItemQuestion<C>>;
+/**
+ * One flushed batch, as plain data: the items and the id fan-out addresses it
+ * by. `id` is a pure function of the batch's item keys (they are joined with a
+ * separator no sanitized key contains), which is what lets a settle Msg — whose
+ * `key` is that id — find its batch again after a rehydrate.
+ */
+interface Batch<I> {
+    readonly id: string;
+    readonly items: readonly I[];
+}
+/** The Cmd a flushed batch becomes — `../ask`'s, carrying the native request. */
+type ClassifyBatchCmd<C extends string> = JevAskCmd<ItemQuestions<C>>;
+/** The success settle Msg — `../ask`'s, with the batch's answers. */
+type ClassifyBatchOkMsg<C extends string> = JevSucceedMsg<ItemQuestions<C>>;
+/** The failure settle Msg — `../ask`'s, with the typed {@link JevAskErr}. */
+type ClassifyBatchErrMsg = JevFailMsg;
+/** The default page size — the one the grill settled on for Jev. */
+declare const DEFAULT_CLASSIFY_MAX_ITEMS = 25;
+/** The knob. Every field is a policy this module refuses to invent. */
+interface ClassifyBatchConfig<I, C extends string> {
+    /**
+     * The cache key and the question id of an item — e.g. a sanitized merchant
+     * string, so two transactions at the same shop share one answer. PURE.
+     */
+    readonly keyOf: (item: I) => string;
+    /** The rubric every item is classified against. Its keys are the answer domain. */
+    readonly criteria: ClassifyCriteria<C>;
+    /**
+     * The `instructions` for one item's question. Defaults to a template naming
+     * the item's key, which is what tells the model WHICH element of the request
+     * `state` the question is about.
+     */
+    readonly instructions?: (key: string, item: I) => JevText;
+    /** Size trigger, forwarded to the batch window. Defaults to {@link DEFAULT_CLASSIFY_MAX_ITEMS}. */
+    readonly maxItems?: number;
+    /** Latency ceiling in ms, forwarded to the batch window. */
+    readonly maxMs: number;
+    /** Max batches in flight, forwarded to fan-out. */
+    readonly concurrency: number;
+    /** How long a settled answer stays cached, forwarded to the TTL cache. */
+    readonly ttlMs: number;
+    /** Eviction tick for the TTL cache. Omit and no eviction Sub is declared. */
+    readonly evictEveryMs?: number;
+    /** The model asked for. Forwarded to `../ask`'s default when omitted. */
+    readonly model?: string;
+    /** DI port — the HTTP caller. Forwarded to `../ask`; absent is the no-key case. */
+    readonly port?: JevPort<ItemQuestions<C>>;
+    /** The pure decider for the no-port path. Forwarded to `../ask`. */
+    readonly fallback?: JevFallback<ItemQuestions<C>>;
+}
+/**
+ * The slice: the three batteries' own slices, plus the one fact none of them
+ * holds — which keys a failed batch left unanswered. All plain data.
+ */
+interface ClassifyBatchState<I, C extends string> {
+    /** The open batch window — `../../flow/batch-window`'s slice. */
+    readonly window: BatchWindow<I>;
+    /** The in-flight batches — `../../flow/fan-out`'s slice. */
+    readonly fanOut: FanOutState<Batch<I>, JevOk<ItemQuestions<C>>>;
+    /** The answers, keyed by `keyOf` — `../../resilience/cache`'s slice. */
+    readonly cache: TtlCache<ItemAnswer<C>>;
+    /** Keys whose batch settled `resilient_err`, with the error that settled it. */
+    readonly failed: Readonly<Record<string, JevAskErr>>;
+}
+/** What {@link ClassifyBatchKnob.answerFor} reports about one key. */
+type KeyAnswer<C extends string> = 
+/** Answered and unexpired: the host applies its own confidence rule to this. */
+{
+    readonly status: "answered";
+    readonly answer: ItemAnswer<C>;
+}
+/** The batch carrying this key settled `resilient_err`. Nothing was cached. */
+ | {
+    readonly status: "failed";
+    readonly error: JevAskErr;
+}
+/** Buffered in the open window, or in a batch that has not settled. */
+ | {
+    readonly status: "pending";
+}
+/** Never seen, or cached and now expired. */
+ | {
+    readonly status: "absent";
+};
+/**
+ * Build a classify-batch knob from `config`.
+ *
+ * The verbs are pure and the whole composition is the four batteries'; the only
+ * thing this factory adds is the native-batch request shape and the bookkeeping
+ * that keeps one key out of two batches at once.
+ */
+declare function createClassifyBatch<I, C extends string>(config: ClassifyBatchConfig<I, C>): {
+    init: () => ClassifyBatchState<I, C>;
+    add: (state: ClassifyBatchState<I, C>, item: I, at: number) => readonly [ClassifyBatchState<I, C>, readonly ClassifyBatchCmd<C>[]];
+    onWindow: (state: ClassifyBatchState<I, C>, at: number) => readonly [ClassifyBatchState<I, C>, readonly ClassifyBatchCmd<C>[]];
+    onBatchOk: (state: ClassifyBatchState<I, C>, msg: ClassifyBatchOkMsg<C>) => readonly [ClassifyBatchState<I, C>, readonly ClassifyBatchCmd<C>[]];
+    onBatchErr: (state: ClassifyBatchState<I, C>, msg: ClassifyBatchErrMsg) => readonly [ClassifyBatchState<I, C>, readonly ClassifyBatchCmd<C>[]];
+    onEvict: (state: ClassifyBatchState<I, C>, at: number) => readonly [ClassifyBatchState<I, C>, readonly ClassifyBatchCmd<C>[]];
+    answerFor: (state: ClassifyBatchState<I, C>, key: string, at: number) => KeyAnswer<C>;
+    subs: (state: ClassifyBatchState<I, C>, id?: string) => readonly (BatchWindowSub | CacheEvictionSub)[];
+    subscribers: () => {
+        deadline: SubscribeHandler<BatchWindowSub, BatchWindowExpired, unknown>;
+        cache: SubscribeHandler<CacheEvictionSub, CacheEvictMsg, unknown>;
+    };
+    handlers: () => {
+        resilient_run: (cmd: ClassifyBatchCmd<C>) => Promise<ClassifyBatchOkMsg<C> | ClassifyBatchErrMsg>;
+    };
+};
+/** The bound knob {@link createClassifyBatch} returns. */
+type ClassifyBatchKnob<I, C extends string> = ReturnType<typeof createClassifyBatch<I, C>>;
+
+export { type Batch, type ClassifyBatchCmd, type ClassifyBatchConfig, type ClassifyBatchErrMsg, type ClassifyBatchKnob, type ClassifyBatchOkMsg, type ClassifyBatchState, type ClassifyCriteria, DEFAULT_CLASSIFY_MAX_ITEMS, DEFAULT_JEV_MODEL, DeadlineExceeded, DeadlineSub, type ItemAnswer, type ItemQuestion, type ItemQuestions, JEV_ENDPOINT, type JevAnswer, type JevAnswerFor, type JevAnswers, type JevAskCmd, type JevAskConfig, type JevAskErr, JevAskFailure, type JevChoiceAnswer, type JevChoiceCriteria, type JevChoiceQuestion, type JevCmd, type JevErr, type JevFailMsg, type JevFallback, type JevHttpStatus, type JevNoulAnswer, type JevNoulQuestion, type JevOk, type JevParse, type JevPort, type JevQuestion, type JevQuestionMap, type JevQuestionType, type JevRequest, type JevResponse, type JevScoreAnswer, type JevScoreCriteria, type JevScoreQuestion, type JevState, type JevSub, type JevSucceedMsg, type JevText, type JevTimerMsg, type JevUsage, type KeyAnswer, ResilientState, classifyStatus, createClassifyBatch, createJevAsk, isJevErr, isTransientJevAskErr, jevAskCmdDef, jevQuestions, liftJevAsk, parseAnswers };