toolnexus 0.25.0 → 0.27.0

package/README.md

@@ -136,6 +136,41 @@ const out = await gate(c, state, questions, [
   filter, content and model batteries into `hooks`. A `beforeLLM` hook may return `{ model }` to
   send another model for that turn only.
 
+### Backends, images, cache and helpers
+
+Every default below is a **proposed default, owner to confirm**
+(`openspec/changes/add-classifier-backends`).
+
+```ts
+import { createClassifier, judge, MemoryCache, validateDecision, thresholdBand, chunkQuestions } from "toolnexus"
+
+const c = createClassifier({ backend: "openrouter", cache: new MemoryCache(3_600_000, 1000) })
+const d = await c.state({ note: "listing", photo: { type: "image", mimeType: "image/png", data: b64 } })
+  .evaluate(judge.noul("red", "Is the object in `photo` red?"))         // fails closed on an invalid reply
+const rs = await c.states("a", "b").evaluate(judge.noul("q", "…"))      // [{ decision } | { error }], in order
+```
+
+- `backend`: `typesafe` (default) · `openrouter` (`typesafe/jev-1.14`) · `cloudflare` (`/ai/run`
+  envelope; `${CLOUDFLARE_ACCOUNT_ID}` in the URL expands at call time, errors name it unexpanded)
+  · `vercel` · `custom` (requires `baseUrl` and `supports`). The table is data:
+  `CLASSIFIER_BACKENDS`; `supports: { images }` overrides it per classifier.
+- Images (style `systemone` only): image parts in the state are lifted into `assets` (cloudflare:
+  data URLs). PNG/JPEG, 280–1568 px a side, ≤ 16 MiB each and 32 MiB per request — never resized.
+  A backend without image support throws `ClassifierUnsupported` before any request. A state with
+  no content part is sent byte-identically to before. JS has no distinct part type, so **any**
+  object shaped like a `ContentPart` (`{type:"text",text}`, `{type:"image",mimeType,…}`) inside a
+  systemone state is treated as a part.
+- `cache: { get(key), set(key, value) }` (sync or async, string values) — off when absent; only
+  valid replies are stored; keys follow the served model. A hit sets `decision.cached` and the
+  `classifier.evaluate` event's `cached`. Every such event also carries `questions` and
+  `questionsHash`.
+- Helpers: `validateDecision(questions, decision)` → `Error | undefined`; `thresholdBand(answer,
+  thresholds?)` with `DEFAULT_THRESHOLDS` 0.8 / 0.2 / 0.6 (inclusive; `Bands` stays the `ask`/`gate`
+  default); `chunkQuestions(questions, size)`.
+- Open union: `judge.raw(name, type, instructions, criteria?)` / `raw(...)`; an answer of an
+  unmodelled type decodes to `{ type, value }` (`decision.raw(key)`).
+- `style: "llm"` is **deprecated** — it still works unchanged, with no runtime warning.
+
 ## Media generation
 
 Generate images, video and speech (plus transcription, voice cloning and talking-head video)

package/dist/acp.d.ts

@@ -48,15 +48,23 @@ export interface ACPOptions {
 /** One warm ACP connection: one child process, one session, alive across many
  *  turns. `.generate` has exactly the shape {@link InProcessOptions.generate}
  *  wants, so it plugs straight into {@link createInProcessClient}. */
+/** Per-call options for {@link ACPClient.generate} / {@link ACPClient.generateStream}. */
+export interface ACPGenerateOptions {
+    /** Cancels the turn: when it aborts mid-turn the `session/cancel` notification is sent,
+     *  the turn's reply is awaited (bounded by `requestTimeoutMs`, default 30s) so the next
+     *  turn never lands on a busy session, and the call rejects with an `AbortError`. The
+     *  process and session stay warm. */
+    signal?: AbortSignal;
+}
 export interface ACPClient {
-    generate: (request: InProcessRequest) => Promise<InProcessResponse>;
+    generate: (request: InProcessRequest, opts?: ACPGenerateOptions) => Promise<InProcessResponse>;
     /** {@link generate}, streaming: `emit` fires as each `session/update` arrives —
      *  agent_message_chunk → `text`, agent_thought_chunk → `thought` (via "acp"),
      *  tool_call → `tool_call` and a completed/failed tool_call_update → `tool_result`
      *  (both via "acp": the agent's own tools, reported, never executed by the loop).
      *  Shaped for {@link InProcessOptions.generateStream}. The returned content is the
      *  message text only. */
-    generateStream: (request: InProcessRequest, emit: (event: StreamEvent) => void) => Promise<InProcessResponse>;
+    generateStream: (request: InProcessRequest, emit: (event: StreamEvent) => void, opts?: ACPGenerateOptions) => Promise<InProcessResponse>;
     /** Terminates the agent's process group. Idempotent — a second call is a no-op. */
     close: () => Promise<void>;
     /** The agent's raw `initialize` result. */

package/dist/acp.js

@@ -298,7 +298,9 @@ export async function loadACP(opts) {
     // each generate() call attaches after whatever is already queued, and the
     // queue itself never rejects (a failed turn does not poison later ones).
     let turnQueue = Promise.resolve();
-    async function promptOnce(request, emit) {
+    async function promptOnce(request, emit, signal) {
+        if (signal?.aborted)
+            throw acpAbortError();
         const text = renderPrompt(request);
         const id = `c-${++nextId}`;
         let content = "";
@@ -361,8 +363,30 @@ export async function loadACP(opts) {
         const timeout = new Promise((_, reject) => {
             timer = setTimeout(() => reject(new Error(`toolnexus: ACP turn timed out after ${permissionTimeoutMs}ms`)), permissionTimeoutMs);
         });
+        let onAbort;
+        const cancelled = new Promise((resolve) => {
+            if (!signal)
+                return;
+            onAbort = () => resolve("cancelled");
+            signal.addEventListener("abort", onAbort, { once: true });
+        });
         try {
-            const msg = await Promise.race([replyPromise, timeout]);
+            const msg = await Promise.race([replyPromise, timeout, cancelled]);
+            if (msg === "cancelled") {
+                // ACP: session/cancel is a notification (no id); the agent then ends the turn with
+                // stopReason "cancelled". Wait (bounded) for that reply so the session is idle again.
+                write({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } });
+                const waitMs = opts.requestTimeoutMs && opts.requestTimeoutMs > 0 ? opts.requestTimeoutMs : 30000;
+                let wait;
+                await Promise.race([
+                    replyPromise,
+                    new Promise((r) => {
+                        wait = setTimeout(r, waitMs);
+                    }),
+                ]);
+                clearTimeout(wait);
+                throw acpAbortError();
+            }
             if (msg.error && msg.error.code === 0)
                 throw new Error(msg.error.message);
             if (msg.error)
@@ -371,14 +395,16 @@ export async function loadACP(opts) {
         }
         finally {
             clearTimeout(timer);
+            if (onAbort)
+                signal.removeEventListener("abort", onAbort);
             pending.delete(id);
             updateSink = null;
         }
     }
-    const generateStream = (request, emit) => {
+    const generateStream = (request, emit, callOpts) => {
         if (closed)
             return Promise.reject(new Error("toolnexus: ACP client is closed"));
-        const turn = turnQueue.then(() => promptOnce(request, emit));
+        const turn = turnQueue.then(() => promptOnce(request, emit, callOpts?.signal));
         turnQueue = turn.then(() => undefined, () => undefined);
         return turn;
     };
@@ -400,13 +426,18 @@ export async function loadACP(opts) {
         if (t === "late")
             await Promise.race([childGone, new Promise((r) => setTimeout(r, 1000).unref())]);
     }
-    const generate = (request) => generateStream(request);
+    const generate = (request, callOpts) => generateStream(request, undefined, callOpts);
     const client = { generate, generateStream, close, initializeResult };
     // Non-enumerable, undocumented — internal test hook only, so the public
     // ACPClient surface stays exactly {generate, generateStream, close}.
     Object.defineProperty(client, "_pid", { value: child.pid, enumerable: false });
     return client;
 }
+function acpAbortError() {
+    const e = new Error("toolnexus: ACP turn cancelled");
+    e.name = "AbortError";
+    return e;
+}
 /** Signals the child's whole process group (POSIX), else the child itself. Never throws. */
 function killGroup(pid, signal) {
     if (process.platform !== "win32") {

package/dist/classifier.d.ts

@@ -1,14 +1,3 @@
-/**
- * Classifier (SPEC.md §8B) — the contract for a JUDGMENT, as `Tool` is the contract for an
- * ACTION. A System One model takes a state plus pre-declared, typed questions and returns
- * calibrated answers with no free text. It has no messages, no tool calling and no streaming,
- * so it never enters the §8 client loop.
- *
- * A classifier INTERPRETS; it never AUTHORISES. Schema validity is not correctness: a decision
- * can be confidently wrong, and "cannot hallucinate" means only that the returned value is in
- * the declared schema. Numeric limits, permission checks and allowlists stay in code. Nothing
- * here is a security control.
- */
 import type { Client } from "./client.js";
 import { type ErrorInfo, type ErrorTier, type MetricEvent } from "./client.js";
 /** The System One endpoint base. */
@@ -24,15 +13,57 @@ export declare const DEFAULT_BATCH_CONCURRENCY = 16;
 /**
  * A named BACKEND: `baseUrl`, `model` and `apiKeyEnv` are only jointly valid, so they travel as
  * a UNIT (ADR 0027 D1). `jev-latest` is TypeSafe's spelling; the gateway spells the same model
- * `typesafe/jev-1.13`, and mixing the two is issue #91.
+ * `typesafe/jev-1.14`, and mixing the two is issue #91. `custom` is a self-hosted System One
+ * endpoint and requires `baseUrl` + `supports` (SPEC §8B "Backends, images, cache and validation").
  */
-export type ClassifierBackend = "typesafe" | "openrouter";
-/** The two servable pairings, as configurations rather than six independently-choosable cells. */
-export declare const CLASSIFIER_BACKENDS: Readonly<Record<ClassifierBackend, {
+export type ClassifierBackend = "typesafe" | "openrouter" | "cloudflare" | "vercel" | "custom";
+/** What a backend+model can take. DATA: a fail-fast for what the table says, never a claim about
+ * the vendor. Override per classifier with `ClassifierOptions.supports`. */
+export interface ClassifierSupports {
+    images: boolean;
+}
+/** One row of the backend table. */
+export interface ClassifierBackendPreset {
+    /** `""` on `custom`, which requires `baseUrl`. May carry `${NAME}`, expanded at call time. */
     baseUrl: string;
     model: string;
     apiKeyEnv: string;
-}>>;
+    /** `systemone`: POST {baseUrl}/systemone. `cloudflare`: POST {baseUrl}, `/ai/run` envelope. */
+    wire: "systemone" | "cloudflare";
+    /** Send `TypeSafe-Danger-Zone-Images: true` when a request carries images. */
+    imagesHeader: boolean;
+    /** The default support for a model on this backend; absent on `custom`. */
+    supports?: (model: string) => ClassifierSupports;
+}
+/** TypeSafe's required opt-in header for image ("danger zone") input. */
+export declare const CLASSIFIER_IMAGES_HEADER = "TypeSafe-Danger-Zone-Images";
+/** Image limits (docs.typesafe.ai/images): checked client-side, never resized. */
+export declare const CLASSIFIER_IMAGE_MIN_SIDE = 280;
+export declare const CLASSIFIER_IMAGE_MAX_SIDE = 1568;
+export declare const CLASSIFIER_IMAGE_MAX_BYTES: number;
+export declare const CLASSIFIER_REQUEST_IMAGE_BYTES: number;
+/**
+ * The backend table (PROPOSED defaults, owner to confirm — design.md PD-1..PD-4). Vercel and
+ * Cloudflare-Jev images stay false until a live probe proves them.
+ */
+export declare const CLASSIFIER_BACKENDS: Readonly<Record<ClassifierBackend, Readonly<ClassifierBackendPreset>>>;
+/**
+ * The env var whose key may be sent to `baseUrl` (already `${NAME}`-expanded): the backend's own
+ * variable, and only when `baseUrl` is that backend's own host over https (OpenRouter also its
+ * subdomains). `""` when none may — `custom` has no preset key at all. A key is never sent to a
+ * host the caller did not name (#155, SPEC §8B).
+ */
+export declare function classifierKeyEnv(backend: ClassifierBackend, baseUrl: string): string;
+/**
+ * Raised BEFORE any network call when the backend table says the backend cannot take what the
+ * request carries. Message, exact: `classifier: <backend> (<model>) does not support <feature>`.
+ */
+export declare class ClassifierUnsupported extends Error {
+    readonly backend: string;
+    readonly model: string;
+    readonly feature: string;
+    constructor(backend: string, model: string, feature: string);
+}
 /** Client-side cap on a choice's named options (§8B). */
 export declare const MAX_CHOICE_OPTIONS = 255;
 /** Bounds of a score rubric (§8B). */
@@ -83,8 +114,25 @@ export interface ScoreQuestion {
     instructions: string;
     criteria: string[];
 }
-/** The closed set of question types, discriminated by `type`. */
+/** The modelled question types, discriminated by `type`. */
 export type Question = NoulQuestion | ChoiceQuestion | ScoreQuestion;
+/**
+ * The OPEN end of the question union (§8B): a System One type the library does not model (e.g.
+ * Jev 1.14 `box`), sent as written with no client-side limits. `type` must be non-empty.
+ */
+export interface RawQuestion {
+    type: string;
+    instructions: string;
+    /** Sent verbatim when present, absent otherwise. */
+    criteria?: unknown;
+}
+/** Every question `evaluate` accepts: the modelled three plus a raw one. */
+export type AnyQuestion = Question | RawQuestion;
+/** True when `q` is a raw question (its type is not noul/choice/score). Not a type guard: every
+ * modelled question is structurally a `RawQuestion` too. */
+export declare function isRawQuestion(q: AnyQuestion): boolean;
+/** A raw question, sent as written. */
+export declare function raw(type: string, instructions: string, criteria?: unknown): RawQuestion;
 /** A noul question. Pass `criteria` only when you mean it — absent ≠ empty on the wire. */
 export declare function noul(instructions: string, criteria?: NoulCriteria): NoulQuestion;
 /** A choice question. Every description must say what picking that option would MEAN. */
@@ -98,7 +146,7 @@ export declare function score(instructions: string, criteria: string[]): ScoreQu
  */
 export declare function choiceOver(instructions: string, items: Record<string, string>): ChoiceQuestion;
 /** The wire form of one question — the object itself, minus an absent `criteria`. */
-export declare function questionWire(q: Question): Record<string, unknown>;
+export declare function questionWire(question: AnyQuestion): Record<string, unknown>;
 /**
  * Canonical JSON: object keys sorted recursively in CODE-UNIT (ASCII) order, arrays NEVER
  * reordered, compact separators, and `<>&'"` plus non-ASCII transmitted raw.
@@ -120,7 +168,7 @@ export declare function canonicalJson(value: unknown): string;
  * ways across our own seven runtimes). Do not re-widen this: a caller who needs their state
  * pinned canonicalises it themselves before handing it over.
  */
-export declare function canonicalRequest(model: string, questions: Record<string, Question>): string;
+export declare function canonicalRequest(model: string, questions: Record<string, AnyQuestion>): string;
 /** The probability that a statement holds. NO confidence: the number is the answer. */
 export interface NoulAnswer {
     type: "noul";
@@ -155,6 +203,18 @@ export interface ScoreAnswer {
  * `Answer` (the suspension resolution) — same idea, different seam.
  */
 export type DecisionAnswer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+/**
+ * An answer of a type the library does not model (the open union, §8B). It may appear in
+ * `Decision.answers` at runtime (read it with `decision.raw(key)` or `isRawAnswer`); `value` is the
+ * whole answer object as decoded, `type` included. It is kept out of `DecisionAnswer` so existing
+ * `switch (a.type)` narrowing keeps compiling.
+ */
+export interface RawAnswer {
+    type: string;
+    value: Record<string, unknown>;
+}
+/** True when an answer is a raw (unmodelled-type) answer. */
+export declare function isRawAnswer(a: unknown): a is RawAnswer;
 /** The wire's usage block. `cost` is absent on some backends. */
 export interface ClassifierUsage {
     inputTokens: number;
@@ -178,6 +238,8 @@ export declare class Decision {
      * BACKEND DOES NOT TRANSFER TO ANOTHER.
      */
     readonly calibrated: boolean;
+    /** True when the decision came from `ClassifierOptions.cache` and no request was sent. */
+    readonly cached: boolean;
     constructor(
     /** What actually answered, which may be more specific than the model that was asked for. */
     model: string, answers: Record<string, DecisionAnswer>, usage: ClassifierUsage, 
@@ -186,7 +248,11 @@ export declare class Decision {
      * unless it derived them from provider token probabilities. A THRESHOLD TUNED AGAINST ONE
      * BACKEND DOES NOT TRANSFER TO ANOTHER.
      */
-    calibrated: boolean);
+    calibrated: boolean, 
+    /** True when the decision came from `ClassifierOptions.cache` and no request was sent. */
+    cached?: boolean);
+    /** Typed read of a raw (unmodelled-type) answer. Throws on an absent key or a modelled type. */
+    raw(key: string): RawAnswer;
     /** Typed read. Throws (never returns undefined) on a wrong-type or absent key. */
     noul(key: string): NoulAnswer;
     choice(key: string): ChoiceAnswer;
@@ -210,7 +276,12 @@ export declare function nearUniform(probabilities: Record<string, number>): bool
  * `nearUniform` is derived. A malformed answer is an error, never a repaired one (ADR 0020).
  */
 export declare function decodeDecision(raw: unknown, fallbackModel: string): Decision;
-/** `"systemone" | "llm" | "custom" | "static"` — the same slot as the client's `style`. */
+/**
+ * `"systemone" | "llm" | "custom" | "static"` — the same slot as the client's `style`.
+ *
+ * `"llm"` is DEPRECATED (ADR 0038 D3: System One is the single product wire). It keeps working
+ * byte-identically, as an alias, for at least one minor release; there is no runtime warning.
+ */
 export type ClassifierStyle = "systemone" | "llm" | "custom" | "static";
 /**
  * One entry of the `static` corpus. It is keyed on the canonical request AND the state: several
@@ -220,12 +291,12 @@ export type ClassifierStyle = "systemone" | "llm" | "custom" | "static";
  */
 export interface RecordedDecision {
     state: unknown;
-    questions: Record<string, Question>;
+    questions: Record<string, AnyQuestion>;
     /** The recorded backend response body, verbatim. */
     response: unknown;
 }
 /** The host's own backend (`style: "custom"`). Every wire option is ignored. */
-export type EvaluateFn = (state: unknown, questions: Record<string, Question>, signal?: AbortSignal) => Promise<Decision> | Decision;
+export type EvaluateFn = (state: unknown, questions: Record<string, AnyQuestion>, signal?: AbortSignal) => Promise<Decision> | Decision;
 /**
  * Mirrors §8 `ClientOptions` field-for-field wherever a field makes sense, so a host that has
  * configured one has configured the other.
@@ -233,7 +304,7 @@ export type EvaluateFn = (state: unknown, questions: Record<string, Question>, s
 export interface ClassifierOptions {
     /** Default `"systemone"`. */
     style?: ClassifierStyle;
-    /** A named `baseUrl` + `model` + `apiKeyEnv` pairing (`"typesafe"` | `"openrouter"`), set as a
+    /** A named backend row (`"typesafe"` | `"openrouter"` | `"cloudflare"` | `"vercel"` | `"custom"`), set as a
      * UNIT. Default `"typesafe"`. The three individual options still win where given, for a
      * self-hosted origin — but a known-bad mixture is refused at construction, not 700 ms later
      * as an "Unknown model" 400. */
@@ -277,12 +348,34 @@ export interface ClassifierOptions {
     /** Emits `classifier.evaluate` events into the SAME §8 sink, and carries the
      * degenerate-criteria warning as `classifier.warning`. */
     onMetric?: (ev: MetricEvent) => void;
-    /** `style: "llm"` only — the §8 Client to emulate over. */
+    /** `style: "llm"` only — the §8 Client to emulate over.
+     * @deprecated `style: "llm"` is deprecated (System One is the single wire); it still works. */
     client?: Client;
     /** `style: "custom"` only — the host's own function. */
     evaluate?: EvaluateFn;
     /** `style: "static"` only — the recorded corpus. */
     decisions?: RecordedDecision[];
+    /** Overrides the backend table's support row for this classifier. Required with `backend: "custom"`. */
+    supports?: ClassifierSupports;
+    /** Opt-in answer cache (§8B). Absent ⇒ no caching. Consulted by style `systemone` only; only
+     * replies that pass `validateDecision` are stored. Methods may return values or Promises. */
+    cache?: ClassifierCache;
+}
+/** An injected answer cache. Values are opaque strings: the served model under a model key, the
+ * System One reply body under a decision key. */
+export interface ClassifierCache {
+    get(key: string): string | undefined | null | Promise<string | undefined | null>;
+    set(key: string, value: string): void | Promise<void>;
+}
+/** One state's outcome from `states(...).evaluate`: exactly one of `decision` / `error` is set. */
+export interface BatchResult {
+    decision?: Decision;
+    error?: Error;
+}
+/** A named question (`judge.noul(...)` etc. build these). */
+export interface NamedClassifierQuestion {
+    name: string;
+    question: AnyQuestion;
 }
 /** The whole seam: one verb. */
 export declare class Classifier {
@@ -291,7 +384,13 @@ export declare class Classifier {
     private readonly baseUrl;
     private readonly model;
     private readonly apiKeyEnv;
+    /** The caller NAMED apiKeyEnv: sent wherever baseUrl points. Otherwise the preset's own key,
+     * and only to its own host (classifierKeyEnv, #155). */
+    private readonly explicitKeyEnv;
     private readonly timeoutMs;
+    private readonly backend;
+    private readonly preset;
+    private readonly supports;
     private readonly corpus;
     /** The once-per-question-key set for the degenerate warning, so a per-turn judge does not
      * flood the sink. */
@@ -301,14 +400,33 @@ export declare class Classifier {
      * The whole contract: a state plus typed questions in, a Decision out. Questions are
      * INDEPENDENT — one answer is never context for another.
      */
-    evaluate(state: unknown, questions: Record<string, Question>, signal?: AbortSignal): Promise<Decision>;
+    evaluate(state: unknown, questions: Record<string, AnyQuestion>, signal?: AbortSignal): Promise<Decision>;
+    /**
+     * Binds one state (a VALUE, not a session: nothing is sent until `evaluate`). Its `evaluate`
+     * runs the same path as `evaluate` PLUS fail-closed validation (`validateDecision`).
+     */
+    state(value: unknown, opts?: {
+        signal?: AbortSignal;
+    }): {
+        evaluate(...questions: NamedClassifierQuestion[]): Promise<Decision>;
+    };
+    /**
+     * Binds a batch of states. Its `evaluate` runs `state(v).evaluate` per state, at most 16 in
+     * flight, and returns one `{decision | error}` per state IN ORDER. One state's failure never
+     * fails the batch; only a question-set error (duplicate name) throws, before any request.
+     */
+    states(...values: unknown[]): {
+        evaluate(...questions: NamedClassifierQuestion[]): Promise<BatchResult[]>;
+    };
+    /** The one path. `validate` = fail closed on `validateDecision` (the value builders). */
+    private run;
     /**
      * The same questions over many states (SPEC §8B "Batch"). Each state goes through
      * `evaluate`, at most `concurrency` (default 16) in flight; decisions come back in STATE
      * order. Fails closed: the first failing state's index is named and no decisions return.
      * No states is an error and sends nothing.
      */
-    evaluateBatch(states: readonly unknown[], questions: Record<string, Question>, opts?: {
+    evaluateBatch(states: readonly unknown[], questions: Record<string, AnyQuestion>, opts?: {
         signal?: AbortSignal;
         concurrency?: number;
     }): Promise<Decision[]>;
@@ -319,15 +437,18 @@ export declare class Classifier {
      */
     private reportDegenerate;
     /**
-     * Assembles the request: the canonical model + questions, plus state VERBATIM as the host
-     * supplied it, then the §8 Gap 1 pipeline in §8 order (base → requestParams merge →
-     * bodyTransform → marshal).
+     * Assembles the request for the backend's wire: the canonical model + questions, plus the state
+     * (VERBATIM unless it carried content parts) and, on systemone, `assets`; then the §8 Gap 1
+     * pipeline in §8 order (base → requestParams merge → bodyTransform → marshal).
      */
     private body;
     /** Identifies a recorded decision by the canonical request AND the state. */
     private staticKey;
     private evaluateStatic;
-    private evaluateSystemOne;
+    /** Lift images, apply the support table and the limits — all before any request. */
+    private prepare;
+    /** The systemone style on every backend: lift, check, cache, post, decode. */
+    private evaluateWire;
     /**
      * The one POST, with the §8 retry budget, reusing the client's `ErrorInfo`/`ErrorTier`
      * classifier and the `Retry-After` delay-seconds rule verbatim.
@@ -369,3 +490,50 @@ export declare function degenerateCriteria(criteria: Record<string, string>): st
  * with, or `""` when the pairing is fine.
  */
 export declare function backendMismatch(baseUrl: string, model: string): string;
+/** §8B model key: which model an endpoint + requested model (alias) served last. */
+export declare function classifierModelCacheKey(endpoint: string, model: string): string;
+/** §8B decision key, on the SERVED model. No assets ⇒ the `assets` member is omitted. */
+export declare function classifierDecisionCacheKey(endpoint: string, servedModel: string, state: unknown, assets: Record<string, unknown> | undefined, questions: Record<string, AnyQuestion>): string;
+/** The canonical JSON a decision key hashes (exported for conformance tests). */
+export declare function classifierDecisionCacheKeyBytes(endpoint: string, servedModel: string, state: unknown, assets: Record<string, unknown> | undefined, questions: Record<string, AnyQuestion>): string;
+/**
+ * In-process TTL cache with a size cap (oldest-inserted out first). `ttlMs` 0 = no expiry; `max`
+ * 0 = unbounded. toolnexus persists nothing itself: implement `ClassifierCache` to persist.
+ */
+export declare class MemoryCache implements ClassifierCache {
+    readonly ttlMs: number;
+    readonly max: number;
+    private readonly now;
+    private readonly m;
+    constructor(ttlMs?: number, max?: number, now?: () => number);
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+    get size(): number;
+}
+/**
+ * V1: fail closed on a reply that does not answer exactly the questions asked, within their
+ * schema. First failure wins, in the §8B order. Returns the error, or undefined when valid.
+ */
+export declare function validateDecision(questions: Record<string, AnyQuestion>, decision: {
+    answers: Record<string, unknown>;
+}): Error | undefined;
+/** jevx's INCLUSIVE cut-points (T1). They sit alongside `Bands` (exclusive), which stays the
+ * default of `ask` / `gate`. */
+export interface Thresholds {
+    yes: number;
+    no: number;
+    minConfidence: number;
+}
+/** 0.8 / 0.2 / 0.6 (jevx's builtin profile). */
+export declare const DEFAULT_THRESHOLDS: Readonly<Thresholds>;
+/**
+ * The band of one answer under `Thresholds`: noul `p >= yes` ⇒ yes, `p <= no` ⇒ no, else
+ * uncertain; choice/score `confidence >= minConfidence` ⇒ yes, else uncertain. No near-uniform
+ * demotion (that is `Bands`' rule). A raw answer is uncertain.
+ */
+export declare function thresholdBand(answer: DecisionAnswer | RawAnswer, t?: Thresholds): "yes" | "no" | "uncertain";
+/**
+ * Split a question set into chunks of `size`, keys in ASCII order. A helper, not automatic:
+ * joint calibration across a split is unproven, so the host decides to split and merges.
+ */
+export declare function chunkQuestions<Q extends AnyQuestion>(questions: Record<string, Q>, size: number): Record<string, Q>[];