toolnexus 0.25.0 → 0.27.0

package/dist/classifier.js

@@ -1,5 +1,18 @@
+/**
+ * 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 { createHash } from "node:crypto";
 import { redactErrorBody, capErrorBody } from "./client.js";
 import { retryAfterMs, isRetryableStatus } from "./retry.js";
+import { isContentPart } from "./content.js";
 // ---------------------------------------------------------------- constants
 /** The System One endpoint base. */
 export const DEFAULT_CLASSIFIER_BASE_URL = "https://api.typesafe.ai/v1";
@@ -11,11 +24,99 @@ export const DEFAULT_CLASSIFIER_API_KEY_ENV = "TYPESAFE_API_KEY";
 export const DEFAULT_CLASSIFIER_TIMEOUT_MS = 10_000;
 /** `evaluateBatch`: at most this many states in flight by default. */
 export const DEFAULT_BATCH_CONCURRENCY = 16;
-/** The two servable pairings, as configurations rather than six independently-choosable cells. */
-export const CLASSIFIER_BACKENDS = {
-    typesafe: { baseUrl: DEFAULT_CLASSIFIER_BASE_URL, model: DEFAULT_CLASSIFIER_MODEL, apiKeyEnv: DEFAULT_CLASSIFIER_API_KEY_ENV },
-    openrouter: { baseUrl: "https://openrouter.ai/api/v1", model: "typesafe/jev-1.13", apiKeyEnv: "OPENROUTER_API_KEY" },
-};
+/** TypeSafe's required opt-in header for image ("danger zone") input. */
+export const CLASSIFIER_IMAGES_HEADER = "TypeSafe-Danger-Zone-Images";
+/** Image limits (docs.typesafe.ai/images): checked client-side, never resized. */
+export const CLASSIFIER_IMAGE_MIN_SIDE = 280;
+export const CLASSIFIER_IMAGE_MAX_SIDE = 1568;
+export const CLASSIFIER_IMAGE_MAX_BYTES = 16 * 1024 * 1024;
+export const CLASSIFIER_REQUEST_IMAGE_BYTES = 32 * 1024 * 1024;
+/**
+ * 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 const CLASSIFIER_BACKENDS = Object.freeze({
+    typesafe: {
+        baseUrl: DEFAULT_CLASSIFIER_BASE_URL,
+        model: DEFAULT_CLASSIFIER_MODEL,
+        apiKeyEnv: DEFAULT_CLASSIFIER_API_KEY_ENV,
+        wire: "systemone",
+        imagesHeader: true,
+        supports: () => ({ images: true }),
+    },
+    openrouter: {
+        baseUrl: "https://openrouter.ai/api/v1",
+        model: "typesafe/jev-1.14",
+        apiKeyEnv: "OPENROUTER_API_KEY",
+        wire: "systemone",
+        imagesHeader: true,
+        supports: () => ({ images: true }),
+    },
+    cloudflare: {
+        baseUrl: "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/ai/run",
+        model: "typesafe/jev",
+        apiKeyEnv: "CLOUDFLARE_JEV_API_KEY",
+        wire: "cloudflare",
+        imagesHeader: false,
+        supports: (model) => ({ images: model.includes("clef") }),
+    },
+    vercel: {
+        baseUrl: "https://ai-gateway.vercel.sh/typesafe/v1",
+        model: "typesafe-ai/jev",
+        apiKeyEnv: "AI_GATEWAY_API_KEY",
+        wire: "systemone",
+        imagesHeader: true,
+        supports: () => ({ images: false }),
+    },
+    custom: {
+        baseUrl: "",
+        model: DEFAULT_CLASSIFIER_MODEL,
+        apiKeyEnv: "",
+        wire: "systemone",
+        imagesHeader: true,
+    },
+});
+/**
+ * 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 function classifierKeyEnv(backend, baseUrl) {
+    const p = Object.prototype.hasOwnProperty.call(CLASSIFIER_BACKENDS, backend) ? CLASSIFIER_BACKENDS[backend] : undefined;
+    if (!p || !p.apiKeyEnv || !p.baseUrl)
+        return "";
+    const hostOf = (u) => {
+        try {
+            const url = new URL(u);
+            return url.protocol === "https:" ? url.hostname.toLowerCase() : "";
+        }
+        catch {
+            return "";
+        }
+    };
+    const h = hostOf(baseUrl);
+    const own = hostOf(p.baseUrl);
+    if (!h || !own)
+        return "";
+    return h === own || (backend === "openrouter" && h.endsWith(".openrouter.ai")) ? p.apiKeyEnv : "";
+}
+/**
+ * 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 class ClassifierUnsupported extends Error {
+    backend;
+    model;
+    feature;
+    constructor(backend, model, feature) {
+        super(`classifier: ${backend} (${model}) does not support ${feature}`);
+        this.backend = backend;
+        this.model = model;
+        this.feature = feature;
+        this.name = "ClassifierUnsupported";
+    }
+}
 /** Client-side cap on a choice's named options (§8B). */
 export const MAX_CHOICE_OPTIONS = 255;
 /** Bounds of a score rubric (§8B). */
@@ -26,6 +127,16 @@ export const MAX_SCORE_LEVELS = 10;
  * port; `examples/judge/near-uniform.json` pins both sides at 0.0499 / 0.0501.
  */
 export const NEAR_UNIFORM_TOLERANCE = 0.05;
+const MODELLED_TYPES = new Set(["noul", "choice", "score"]);
+/** 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 function isRawQuestion(q) {
+    return !MODELLED_TYPES.has(q?.type);
+}
+/** A raw question, sent as written. */
+export function raw(type, instructions, criteria) {
+    return criteria === undefined ? { type, instructions } : { type, instructions, criteria };
+}
 /** A noul question. Pass `criteria` only when you mean it — absent ≠ empty on the wire. */
 export function noul(instructions, criteria) {
     return criteria === undefined ? { type: "noul", instructions } : { type: "noul", instructions, criteria };
@@ -47,7 +158,14 @@ export function choiceOver(instructions, items) {
     return choice(instructions, items);
 }
 /** The wire form of one question — the object itself, minus an absent `criteria`. */
-export function questionWire(q) {
+export function questionWire(question) {
+    if (isRawQuestion(question)) {
+        const r = question;
+        return r.criteria === undefined
+            ? { type: r.type, instructions: r.instructions }
+            : { type: r.type, instructions: r.instructions, criteria: r.criteria };
+    }
+    const q = question;
     switch (q.type) {
         case "noul":
             return q.criteria === undefined
@@ -60,7 +178,13 @@ export function questionWire(q) {
     }
 }
 /** Client-side limits, enforced BEFORE the request. The error names the key and the limit. */
-function validateQuestion(key, q) {
+function validateQuestion(key, question) {
+    const q = question;
+    if (isRawQuestion(question)) {
+        if (!question?.type)
+            throw new Error(`classifier: question "${key}": a raw question needs a type`);
+        return;
+    }
     if (q.type === "choice") {
         const n = Object.keys(q.criteria ?? {}).length;
         if (n < 1 || n > MAX_CHOICE_OPTIONS) {
@@ -119,6 +243,10 @@ export function canonicalRequest(model, questions) {
     }
     return canonicalJson({ model, questions: qs });
 }
+/** True when an answer is a raw (unmodelled-type) answer. */
+export function isRawAnswer(a) {
+    return !!a && typeof a === "object" && !MODELLED_TYPES.has(a.type) && "value" in a;
+}
 /** The legend in LEVEL order, which the map itself loses ("2" sorts before "10" as a level). */
 export function levels(answer) {
     return Object.keys(answer.legend)
@@ -134,6 +262,7 @@ export class Decision {
     answers;
     usage;
     calibrated;
+    cached;
     constructor(
     /** What actually answered, which may be more specific than the model that was asked for. */
     model, answers, usage, 
@@ -142,11 +271,23 @@ export class Decision {
      * unless it derived them from provider token probabilities. A THRESHOLD TUNED AGAINST ONE
      * BACKEND DOES NOT TRANSFER TO ANOTHER.
      */
-    calibrated) {
+    calibrated, 
+    /** True when the decision came from `ClassifierOptions.cache` and no request was sent. */
+    cached = false) {
         this.model = model;
         this.answers = answers;
         this.usage = usage;
         this.calibrated = calibrated;
+        this.cached = cached;
+    }
+    /** Typed read of a raw (unmodelled-type) answer. Throws on an absent key or a modelled type. */
+    raw(key) {
+        const a = this.answers[key];
+        if (a === undefined)
+            throw new Error(`classifier: no answer "${key}" in this decision`);
+        if (!isRawAnswer(a))
+            throw new Error(`classifier: answer "${key}" is a ${a.type} answer, not raw`);
+        return a;
     }
     /** Typed read. Throws (never returns undefined) on a wrong-type or absent key. */
     noul(key) {
@@ -223,7 +364,10 @@ export function decodeDecision(raw, fallbackModel) {
                 };
                 break;
             default:
-                throw new Error(`classifier: answer "${key}": unknown type ${JSON.stringify(a.type)}`);
+                // The union is OPEN (§8B): an unmodelled type (e.g. Jev 1.14 "box") decodes to a raw
+                // answer instead of failing the whole decision.
+                ;
+                answers[key] = { type: String(a.type ?? ""), value: { ...a } };
         }
     }
     const usage = {
@@ -261,7 +405,13 @@ export class Classifier {
     baseUrl;
     model;
     apiKeyEnv;
+    /** The caller NAMED apiKeyEnv: sent wherever baseUrl points. Otherwise the preset's own key,
+     * and only to its own host (classifierKeyEnv, #155). */
+    explicitKeyEnv;
     timeoutMs;
+    backend;
+    preset;
+    supports;
     corpus = new Map();
     /** The once-per-question-key set for the degenerate warning, so a per-turn judge does not
      * flood the sink. */
@@ -269,14 +419,24 @@ export class Classifier {
     constructor(opts) {
         this.opts = opts;
         this.style = opts.style ?? "systemone";
-        const preset = CLASSIFIER_BACKENDS[opts.backend ?? "typesafe"];
-        this.baseUrl = opts.baseUrl ?? preset.baseUrl;
+        this.backend = opts.backend ?? "typesafe";
+        if (!Object.prototype.hasOwnProperty.call(CLASSIFIER_BACKENDS, this.backend)) {
+            throw new Error(`classifier: unknown backend "${this.backend}" (want "typesafe", "openrouter", "cloudflare", "vercel" or "custom")`);
+        }
+        const preset = CLASSIFIER_BACKENDS[this.backend];
+        this.preset = preset;
+        if (this.backend === "custom" && this.style === "systemone" && (!opts.baseUrl || !opts.supports)) {
+            throw new Error('classifier: backend "custom" requires baseUrl and supports');
+        }
+        this.baseUrl = opts.baseUrl || preset.baseUrl;
         this.model = opts.model ?? preset.model;
         this.apiKeyEnv = opts.apiKeyEnv ?? preset.apiKeyEnv;
+        this.explicitKeyEnv = opts.apiKeyEnv !== undefined;
         const mismatch = backendMismatch(this.baseUrl, this.model);
         if (mismatch)
             throw new Error(mismatch);
         this.timeoutMs = opts.timeoutMs ?? DEFAULT_CLASSIFIER_TIMEOUT_MS;
+        this.supports = opts.supports ? { ...opts.supports } : (preset.supports?.(this.model) ?? { images: false });
         switch (this.style) {
             case "systemone":
                 break;
@@ -309,11 +469,60 @@ export class Classifier {
      * INDEPENDENT — one answer is never context for another.
      */
     async evaluate(state, questions, signal) {
+        return this.run(state, questions, signal, false);
+    }
+    /**
+     * 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, opts = {}) {
+        return {
+            evaluate: async (...qs) => this.run(value, namedQuestions(qs), opts.signal, true),
+        };
+    }
+    /**
+     * 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) {
+        return {
+            evaluate: async (...qs) => {
+                const questions = namedQuestions(qs);
+                const out = new Array(values.length);
+                let next = 0;
+                const worker = async () => {
+                    while (next < values.length) {
+                        const i = next++;
+                        try {
+                            out[i] = { decision: await this.run(values[i], questions, undefined, true) };
+                        }
+                        catch (e) {
+                            out[i] = { error: e instanceof Error ? e : new Error(String(e)) };
+                        }
+                    }
+                };
+                await Promise.all(Array.from({ length: Math.min(DEFAULT_BATCH_CONCURRENCY, values.length) }, worker));
+                return out;
+            },
+        };
+    }
+    /** The one path. `validate` = fail closed on `validateDecision` (the value builders). */
+    async run(state, questions, signal, validate) {
         const start = Date.now();
         const keys = Object.keys(questions ?? {}).sort();
+        // L1: count + hash of the canonical request on every evaluate event ("" when unencodable).
+        let qHash = "";
+        try {
+            qHash = sha256Hex(canonicalRequest(this.model, questions ?? {}));
+        }
+        catch {
+            qHash = "";
+        }
+        const l1 = { questions: keys.length, questionsHash: qHash };
         if (keys.length === 0) {
             const err = new Error("classifier: no questions to evaluate");
-            this.emitError(start, err);
+            this.emitError(start, err, l1);
             throw err;
         }
         try {
@@ -328,7 +537,7 @@ export class Classifier {
             }
         }
         catch (e) {
-            this.emitError(start, e);
+            this.emitError(start, e, l1);
             throw e;
         }
         // Detection, never repair (ADR 0020/0021): the request goes out BYTE-UNCHANGED and the
@@ -347,11 +556,16 @@ export class Classifier {
                     decision = await this.evaluateLLM(state, questions, signal);
                     break;
                 default:
-                    decision = await this.evaluateSystemOne(state, questions, signal);
+                    decision = await this.evaluateWire(state, questions, signal, validate);
+            }
+            if (validate && this.style !== "systemone") {
+                const verr = validateDecision(questions, decision);
+                if (verr)
+                    throw verr;
             }
         }
         catch (e) {
-            this.emitError(start, e);
+            this.emitError(start, e, l1);
             throw e;
         }
         this.emit({
@@ -361,6 +575,8 @@ export class Classifier {
             ms: Date.now() - start,
             promptTokens: decision.usage.inputTokens,
             completionTokens: decision.usage.outputTokens,
+            ...l1,
+            cached: decision.cached === true,
         });
         return decision;
     }
@@ -421,15 +637,26 @@ export class Classifier {
     }
     // ---------------------------------------------------------------- backends
     /**
-     * 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).
      */
-    body(state, questions) {
+    body(p, questions) {
         const qs = {};
         for (const [key, q] of Object.entries(questions))
             qs[key] = questionWire(q);
-        let body = { model: this.model, questions: qs, state };
+        let body;
+        if (this.preset.wire === "cloudflare") {
+            const input = { questions: qs, state: p.state };
+            if (p.images.length > 0)
+                input.images = p.images.map((im) => `data:image/${im.format};base64,${im.data}`);
+            body = { model: this.model, input };
+        }
+        else {
+            body = { model: this.model, questions: qs, state: p.state };
+            if (p.assets)
+                body.assets = p.assets;
+        }
         // A requestParams key WINS on collision.
         if (this.opts.requestParams)
             body = { ...body, ...this.opts.requestParams };
@@ -447,8 +674,44 @@ export class Classifier {
             throw new Error("classifier: static: no recorded decision for this request+state");
         return decodeDecision(raw, this.model);
     }
-    async evaluateSystemOne(state, questions, signal) {
-        const text = await this.post(this.body(state, questions), signal);
+    /** Lift images, apply the support table and the limits — all before any request. */
+    prepare(state) {
+        const { state: sent, images } = liftImages(state);
+        if (images.length > 0 && !this.supports.images)
+            throw new ClassifierUnsupported(this.backend, this.model, "images");
+        checkImages(images);
+        let assets;
+        if (images.length > 0) {
+            assets = {};
+            for (const im of images)
+                assets[im.ref] = { type: "image", format: im.format, data_base64: im.data };
+        }
+        return { state: sent, images, assets };
+    }
+    /** The systemone style on every backend: lift, check, cache, post, decode. */
+    async evaluateWire(state, questions, signal, validate) {
+        const p = this.prepare(state);
+        const cache = this.opts.cache;
+        let modelKey = "";
+        if (cache) {
+            modelKey = classifierModelCacheKey(this.baseUrl, this.model);
+            const served = await cache.get(modelKey);
+            if (typeof served === "string") {
+                const hit = await cache.get(classifierDecisionCacheKey(this.baseUrl, served, p.state, p.assets, questions));
+                if (typeof hit === "string") {
+                    try {
+                        const d = decodeDecision(JSON.parse(hit), served);
+                        if (!validateDecision(questions, d))
+                            return new Decision(d.model, d.answers, d.usage, d.calibrated, true);
+                    }
+                    catch {
+                        // a corrupt entry is a miss
+                    }
+                }
+            }
+        }
+        const extra = p.images.length > 0 && this.preset.imagesHeader ? { [CLASSIFIER_IMAGES_HEADER]: "true" } : {};
+        let text = await this.post(this.body(p, questions), signal, extra);
         let parsed;
         try {
             parsed = JSON.parse(text);
@@ -456,7 +719,20 @@ export class Classifier {
         catch (e) {
             throw new Error(`classifier: response was not JSON: ${e.message}`);
         }
-        return decodeDecision(parsed, this.model);
+        if (this.preset.wire === "cloudflare") {
+            parsed = unwrapCloudflare(parsed);
+            text = canonicalJson(parsed);
+        }
+        const d = decodeDecision(parsed, this.model);
+        const verr = validateDecision(questions, d);
+        if (validate && verr)
+            throw verr;
+        if (cache && !verr) {
+            const served = d.model || this.model;
+            await cache.set(modelKey, served);
+            await cache.set(classifierDecisionCacheKey(this.baseUrl, served, p.state, p.assets, questions), text);
+        }
+        return d;
     }
     /**
      * The one POST, with the §8 retry budget, reusing the client's `ErrorInfo`/`ErrorTier`
@@ -467,8 +743,13 @@ export class Classifier {
      * is never echoed back (a gateway happily reflects a bad Authorization header into its own
      * 401 text).
      */
-    async post(payload, signal) {
-        const endpoint = this.baseUrl.replace(/\/+$/, "") + "/systemone";
+    async post(payload, signal, extraHeaders = {}) {
+        // `endpoint` is what errors name: the CONFIGURED base, ${ENV} unexpanded, so an account id in
+        // a templated URL never reaches an error. `url` is what is dialled, expanded at call time.
+        let endpoint = this.baseUrl.replace(/\/+$/, "");
+        if (this.preset.wire !== "cloudflare")
+            endpoint += "/systemone";
+        const url = endpoint.includes("${") ? expandEnv(endpoint) : endpoint;
         const retries = this.opts.retries ?? 2;
         const base = this.opts.retryBaseMs ?? 500;
         const classify = this.opts.onError ?? ((info) => (info.retryable ? "retry" : "fail"));
@@ -491,9 +772,9 @@ export class Classifier {
             let res;
             let thrown;
             try {
-                res = await doFetch(endpoint, {
+                res = await doFetch(url, {
                     method: "POST",
-                    headers: this.requestHeaders(),
+                    headers: this.requestHeaders(extraHeaders, url),
                     body: payload,
                     signal: timer.signal,
                 });
@@ -516,7 +797,7 @@ export class Classifier {
                 lastErr = new Error(`classifier: POST ${endpoint}: HTTP ${res.status}${cause(res.status, text)}`);
             }
             else {
-                lastErr = new Error(`classifier: POST ${endpoint}: ${errText(thrown)}`);
+                lastErr = new Error(`classifier: POST ${endpoint}: ${errText(thrown).split(url).join(endpoint)}`);
             }
             const retryable = res ? res.status === 408 || isRetryableStatus(res.status, this.opts.retryableStatuses) : true;
             if (attempt >= retries)
@@ -529,11 +810,15 @@ export class Classifier {
         }
     }
     /** Credential and `${ENV_VAR}` headers resolve AT CALL TIME. Never logged, never returned. */
-    requestHeaders() {
+    requestHeaders(extra, url) {
         const headers = { "Content-Type": "application/json" };
-        const key = process.env[this.apiKeyEnv];
+        const keyEnv = this.explicitKeyEnv ? this.apiKeyEnv : classifierKeyEnv(this.backend, url);
+        const key = keyEnv ? process.env[keyEnv] : undefined;
         if (key)
             headers["Authorization"] = `Bearer ${key}`;
+        // The image opt-in header goes BEFORE host headers, which win.
+        for (const [k, v] of Object.entries(extra))
+            headers[k] = v;
         for (const [k, v] of Object.entries(this.opts.headers ?? {}))
             headers[k] = expandEnv(v);
         return headers;
@@ -577,7 +862,7 @@ export class Classifier {
     emit(ev) {
         this.opts.onMetric?.(ev);
     }
-    emitError(start, e) {
+    emitError(start, e, l1) {
         this.emit({
             event: "classifier.evaluate",
             model: this.model,
@@ -586,6 +871,8 @@ export class Classifier {
             promptTokens: 0,
             completionTokens: 0,
             error: errText(e),
+            ...l1,
+            cached: false,
         });
     }
 }
@@ -669,3 +956,324 @@ function sleep(ms) {
         setTimeout(resolve, ms);
     });
 }
+// ---------------------------------------------------------------- backends, images, cache, validation
+// SPEC.md §8B "Backends, images, cache and validation" (change add-classifier-backends, ADR 0038).
+// Every default here is a PROPOSED default, owner to confirm (design.md PD-1..PD-15).
+/** Ordered named questions -> the questions map. A duplicate name is an error naming it. */
+function namedQuestions(qs) {
+    const out = {};
+    for (const { name, question } of qs) {
+        if (Object.prototype.hasOwnProperty.call(out, name))
+            throw new Error(`duplicate question name ${JSON.stringify(name)}`);
+        out[name] = question;
+    }
+    return out;
+}
+function sha256Hex(s) {
+    return createHash("sha256").update(s, "utf8").digest("hex");
+}
+function containsPart(v) {
+    if (Array.isArray(v))
+        return v.some(containsPart);
+    if (v !== null && typeof v === "object") {
+        if (isContentPart(v))
+            return true;
+        return Object.values(v).some(containsPart);
+    }
+    return false;
+}
+/**
+ * The §8B lifting walk. A state with no content part is returned VERBATIM (the same value), so a
+ * text-only state is byte-identical to before. Otherwise depth-first, object keys in ASCII order,
+ * arrays in order: an image part with inline data becomes a reference (its key when unused, else
+ * the smallest unused `image<n>`), a text part becomes its text, any other part is an error.
+ */
+function liftImages(state) {
+    if (!containsPart(state))
+        return { state, images: [] };
+    const used = new Set();
+    const images = [];
+    const nextRef = () => {
+        for (let n = 1;; n++)
+            if (!used.has(`image${n}`))
+                return `image${n}`;
+    };
+    const walk = (v, key) => {
+        if (Array.isArray(v))
+            return v.map((e) => walk(e, ""));
+        if (v === null || typeof v !== "object")
+            return v;
+        if (isContentPart(v)) {
+            const part = v;
+            if (part.type === "text")
+                return part.text;
+            if (part.type === "image") {
+                if (!part.data)
+                    throw new Error("classifier: state: an image part needs inline data (a URL image cannot be sent)");
+                const ref = key === "" || used.has(key) ? nextRef() : key;
+                used.add(ref);
+                images.push({ ref, format: part.mimeType, data: part.data });
+                return ref;
+            }
+            throw new Error(`classifier: state: ${part.type} parts are not supported`);
+        }
+        const obj = v;
+        const out = {};
+        for (const k of Object.keys(obj).sort())
+            out[k] = walk(obj[k], k);
+        return out;
+    };
+    return { state: walk(state, ""), images };
+}
+const IMAGE_FORMATS = { "image/png": "png", "image/jpeg": "jpeg", "image/jpg": "jpeg" };
+/** Format, per-image and per-request limits, in collection order; normalises `format`. */
+function checkImages(images) {
+    let total = 0;
+    for (const im of images) {
+        const format = IMAGE_FORMATS[im.format];
+        if (!format)
+            throw new Error(`classifier: image "${im.ref}": type "${im.format}" is not supported (PNG or JPEG only)`);
+        im.format = format;
+        if (im.data.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(im.data)) {
+            throw new Error(`classifier: image "${im.ref}": data is not base64`);
+        }
+        const raw = Buffer.from(im.data, "base64");
+        if (raw.length > CLASSIFIER_IMAGE_MAX_BYTES) {
+            throw new Error(`classifier: image "${im.ref}": ${raw.length} bytes, over 16 MiB`);
+        }
+        const size = imageSize(format, raw);
+        if (!size)
+            throw new Error(`classifier: image "${im.ref}": not a readable ${format.toUpperCase()}`);
+        const [w, h] = size;
+        const ok = (n) => n >= CLASSIFIER_IMAGE_MIN_SIDE && n <= CLASSIFIER_IMAGE_MAX_SIDE;
+        if (!ok(w) || !ok(h)) {
+            throw new Error(`classifier: image "${im.ref}": ${w}x${h}; each side must be ${CLASSIFIER_IMAGE_MIN_SIDE}..${CLASSIFIER_IMAGE_MAX_SIDE} px`);
+        }
+        total += raw.length;
+    }
+    if (total > CLASSIFIER_REQUEST_IMAGE_BYTES) {
+        throw new Error(`classifier: image "${images[images.length - 1].ref}": request images total ${total} bytes, over 32 MiB`);
+    }
+}
+/** Width/height from a PNG IHDR or the first JPEG SOF marker; undefined when unreadable. */
+function imageSize(format, b) {
+    const be16 = (i) => (b[i] << 8) | b[i + 1];
+    const be32 = (i) => ((b[i] << 24) >>> 0) + (b[i + 1] << 16) + (b[i + 2] << 8) + b[i + 3];
+    if (format === "png") {
+        const sig = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+        if (b.length < 24 || sig.some((x, i) => b[i] !== x))
+            return undefined;
+        if (String.fromCharCode(b[12], b[13], b[14], b[15]) !== "IHDR")
+            return undefined;
+        return [be32(16), be32(20)];
+    }
+    if (b.length < 4 || b[0] !== 0xff || b[1] !== 0xd8)
+        return undefined;
+    let i = 2;
+    while (i + 3 < b.length) {
+        if (b[i] !== 0xff)
+            return undefined;
+        const m = b[i + 1];
+        if (m === 0xff) {
+            i++;
+            continue;
+        }
+        if (m >= 0xc0 && m <= 0xcf && m !== 0xc4 && m !== 0xc8 && m !== 0xcc) {
+            if (i + 8 >= b.length)
+                return undefined;
+            return [be16(i + 7), be16(i + 5)];
+        }
+        i += 2 + be16(i + 2);
+    }
+    return undefined;
+}
+/**
+ * `: <code> <message>` from errors[0] of a failed envelope (SPEC §8B), through the same redaction
+ * and cap as cause(). Cloudflare reports a missing balance, a bad model id and a malformed
+ * request alike as HTTP 200 + success:false, so this is the only thing that tells them apart.
+ * `""` when there is nothing to show.
+ */
+function cloudflareCause(env) {
+    const errs = env !== null && typeof env === "object" ? env.errors : undefined;
+    const e0 = Array.isArray(errs) ? errs[0] : undefined;
+    if (e0 === null || typeof e0 !== "object")
+        return "";
+    const parts = [];
+    if ((typeof e0.code === "number" || typeof e0.code === "string") && String(e0.code) !== "")
+        parts.push(String(e0.code));
+    if (typeof e0.message === "string" && e0.message !== "")
+        parts.push(e0.message);
+    const s = capErrorBody(redactErrorBody(parts.join(" ")));
+    return s ? ": " + s : "";
+}
+/** The System One reply inside a Cloudflare `/ai/run` envelope. Only errors[0] is ever echoed. */
+function unwrapCloudflare(env) {
+    if (env === null || typeof env !== "object" || Array.isArray(env) || env.success !== true) {
+        throw new Error("classifier: cloudflare: envelope not successful" + cloudflareCause(env));
+    }
+    let result = env.result;
+    if (result !== null && typeof result === "object" && !Array.isArray(result) && typeof result.state === "string") {
+        if (result.state !== "Completed")
+            throw new Error(`classifier: cloudflare: run state "${result.state}"`);
+        result = result.result;
+    }
+    return result;
+}
+/** §8B model key: which model an endpoint + requested model (alias) served last. */
+export function classifierModelCacheKey(endpoint, model) {
+    return sha256Hex(canonicalJson({ endpoint, kind: "model", model }));
+}
+/** §8B decision key, on the SERVED model. No assets ⇒ the `assets` member is omitted. */
+export function classifierDecisionCacheKey(endpoint, servedModel, state, assets, questions) {
+    return sha256Hex(classifierDecisionCacheKeyBytes(endpoint, servedModel, state, assets, questions));
+}
+/** The canonical JSON a decision key hashes (exported for conformance tests). */
+export function classifierDecisionCacheKeyBytes(endpoint, servedModel, state, assets, questions) {
+    const qs = {};
+    for (const [k, q] of Object.entries(questions))
+        qs[k] = questionWire(q);
+    const m = { endpoint, kind: "decision", model: servedModel, questions: qs, state };
+    if (assets && Object.keys(assets).length > 0)
+        m.assets = assets;
+    return canonicalJson(m);
+}
+/**
+ * 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 class MemoryCache {
+    ttlMs;
+    max;
+    now;
+    m = new Map();
+    constructor(ttlMs = 0, max = 0, now = Date.now) {
+        this.ttlMs = ttlMs;
+        this.max = max;
+        this.now = now;
+    }
+    get(key) {
+        const e = this.m.get(key);
+        if (!e)
+            return undefined;
+        if (this.ttlMs > 0 && this.now() - e.at > this.ttlMs) {
+            this.m.delete(key);
+            return undefined;
+        }
+        return e.v;
+    }
+    set(key, value) {
+        this.m.delete(key); // a re-set is a fresh insertion
+        this.m.set(key, { v: value, at: this.now() });
+        if (this.max > 0)
+            while (this.m.size > this.max)
+                this.m.delete(this.m.keys().next().value);
+    }
+    get size() {
+        return this.m.size;
+    }
+}
+/**
+ * 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 function validateDecision(questions, decision) {
+    const bad = (msg) => new Error(`classifier: invalid decision: ${msg}`);
+    const answers = decision.answers ?? {};
+    const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+    const qKeys = Object.keys(questions).sort();
+    for (const k of qKeys)
+        if (!has(answers, k))
+            return bad(`no answer "${k}"`);
+    const extra = Object.keys(answers)
+        .filter((k) => !has(questions, k))
+        .sort();
+    if (extra.length > 0)
+        return bad(`unexpected answer "${extra[0]}"`);
+    const in01 = (p) => typeof p === "number" && !Number.isNaN(p) && p >= 0 && p <= 1;
+    const dist = (k, probs, offered) => {
+        let sum = 0;
+        const pk = Object.keys(probs ?? {}).sort();
+        for (const o of pk) {
+            if (!offered(o))
+                return bad(`answer "${k}": probability for "${o}", which was not offered`);
+            if (!in01(probs[o]))
+                return bad(`answer "${k}": probability ${probs[o]} outside [0,1]`);
+            sum += probs[o];
+        }
+        if (pk.length > 0 && Math.abs(sum - 1) > 0.02)
+            return bad(`answer "${k}": probabilities sum to ${sum.toFixed(4)}`);
+        return undefined;
+    };
+    for (const k of qKeys) {
+        const raw = questions[k];
+        const q = raw;
+        const a = answers[k];
+        const qType = raw.type;
+        const aType = a?.type;
+        if (aType !== qType)
+            return bad(`answer "${k}" is a ${aType} answer, not ${qType}`);
+        if (isRawQuestion(raw))
+            continue;
+        if (q.type === "noul") {
+            if (!in01(a.noul))
+                return bad(`answer "${k}": noul ${a.noul} outside [0,1]`);
+        }
+        else if (q.type === "choice") {
+            const offered = (o) => has(q.criteria ?? {}, o);
+            if (!offered(a.choice))
+                return bad(`answer "${k}": choice "${a.choice}" was not offered`);
+            const err = dist(k, a.probabilities, offered);
+            if (err)
+                return err;
+            if (!in01(a.confidence))
+                return bad(`answer "${k}": confidence ${a.confidence} outside [0,1]`);
+        }
+        else {
+            const n = (q.criteria ?? []).length;
+            if (typeof a.score !== "number" || Number.isNaN(a.score) || a.score < 0 || a.score > n - 1) {
+                return bad(`answer "${k}": score ${a.score} outside [0,${n - 1}]`);
+            }
+            const offered = (o) => Array.from({ length: n }, (_, i) => String(i)).includes(o);
+            const err = dist(k, a.probabilities, offered);
+            if (err)
+                return err;
+            if (!in01(a.confidence))
+                return bad(`answer "${k}": confidence ${a.confidence} outside [0,1]`);
+        }
+    }
+    return undefined;
+}
+/** 0.8 / 0.2 / 0.6 (jevx's builtin profile). */
+export const DEFAULT_THRESHOLDS = Object.freeze({ yes: 0.8, no: 0.2, minConfidence: 0.6 });
+/**
+ * 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 function thresholdBand(answer, t = DEFAULT_THRESHOLDS) {
+    const a = answer;
+    if (a.type === "noul") {
+        if (a.noul >= t.yes)
+            return "yes";
+        if (a.noul <= t.no)
+            return "no";
+    }
+    else if ((a.type === "choice" || a.type === "score") && a.confidence >= t.minConfidence) {
+        return "yes";
+    }
+    return "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 function chunkQuestions(questions, size) {
+    if (!(size >= 1))
+        throw new Error(`classifier: chunk size must be at least 1, got ${size}`);
+    const keys = Object.keys(questions).sort();
+    const out = [];
+    for (let i = 0; i < keys.length; i += size) {
+        out.push(Object.fromEntries(keys.slice(i, i + size).map((k) => [k, questions[k]])));
+    }
+    return out;
+}