@zanii/blackbox 0.22.0 → 0.23.0

package/dist/analysis/plan-checks.js

@@ -0,0 +1,748 @@
+// Flight-plan checks on arguments and output (spec/findings.md §5a): a portable regular expression
+// (a Pike VM: linear time, the same answer in both SDKs), a JSON path, a JSON Schema subset, and the
+// `tool_args` / `answer` predicates built on them. Mirrors analysis/plan_checks.py.
+import { canonical, isObj } from "../reconcile/shared.js";
+const MAX_PATTERN = 256;
+const MAX_PROGRAM = 1000;
+const MAX_REPEAT = 100;
+/** Text longer than this (in code points) isn't matched (cannot_verify). */
+export const MAX_MATCH_TEXT = 100_000;
+const isDigit = (c) => c >= "0" && c <= "9";
+const isWord = (c) => (c >= "a" && c <= "z") || (c >= "A" && c <= "Z") || isDigit(c) || c === "_";
+const isSpace = (c) => " \t\n\r\f\v".includes(c) && c.length === 1;
+const CLASSES = {
+    d: isDigit,
+    D: (c) => !isDigit(c),
+    w: isWord,
+    W: (c) => !isWord(c),
+    s: isSpace,
+    S: (c) => !isSpace(c),
+};
+const CONTROL = { n: "\n", r: "\r", t: "\t" };
+const SYNTAX = "\\^$.|?*+()[]{}/-";
+const cp = (c) => c.codePointAt(0);
+class PatternError extends Error {
+}
+/** Parses and compiles a pattern, or says why it isn't one (spec/findings.md §5a.1). */
+export function compilePattern(source) {
+    if (typeof source !== "string")
+        return "a pattern must be a string";
+    const s = Array.from(source);
+    if (s.length === 0 || s.length > MAX_PATTERN)
+        return "a pattern must be 1-256 characters";
+    let i = 0;
+    const fail = (why) => {
+        throw new PatternError(why);
+    };
+    const escaped = (inClass) => {
+        const c = s[i++];
+        if (c === undefined)
+            return fail("a pattern can't end with \\");
+        if (CLASSES[c])
+            return CLASSES[c];
+        if (CONTROL[c])
+            return CONTROL[c];
+        if (!inClass && (c === "b" || c === "B"))
+            return c;
+        if (SYNTAX.includes(c))
+            return c;
+        return fail("unsupported escape");
+    };
+    const klass = () => {
+        // after "["
+        let neg = false;
+        if (s[i] === "^") {
+            neg = true;
+            i++;
+        }
+        const tests = [];
+        let first = true;
+        for (;;) {
+            const c = s[i];
+            if (c === undefined)
+                fail("unterminated character class");
+            if (c === "]") {
+                if (first)
+                    fail("empty character class");
+                i++;
+                break;
+            }
+            first = false;
+            if (c === "[")
+                fail("unescaped [ in a character class");
+            let lo;
+            i++;
+            lo = c === "\\" ? escaped(true) : c;
+            if (typeof lo === "string" && s[i] === "-" && s[i + 1] !== undefined && s[i + 1] !== "]") {
+                i++;
+                const d = s[i++];
+                const hi = d === "\\" ? escaped(true) : d === "[" ? fail("unescaped [ in a character class") : d;
+                if (typeof hi !== "string" || cp(hi) < cp(lo))
+                    fail("bad character range");
+                const a = cp(lo);
+                const b = cp(hi);
+                tests.push((x) => cp(x) >= a && cp(x) <= b);
+                continue;
+            }
+            if (typeof lo === "string") {
+                const ch = lo;
+                lo = (x) => x === ch;
+            }
+            tests.push(lo);
+        }
+        return neg ? (x) => !tests.some((t) => t(x)) : (x) => tests.some((t) => t(x));
+    };
+    const count = () => {
+        let n = "";
+        while (s[i] !== undefined && isDigit(s[i]))
+            n += s[i++];
+        if (n.length === 0 || n.length > 3)
+            return null;
+        return Number(n);
+    };
+    const alt = () => {
+        const items = [cat()];
+        while (s[i] === "|") {
+            i++;
+            items.push(cat());
+        }
+        return items.length === 1 ? items[0] : { t: "alt", items };
+    };
+    const cat = () => {
+        const items = [];
+        for (;;) {
+            const c = s[i];
+            if (c === undefined || c === "|" || c === ")")
+                break;
+            let node;
+            i++;
+            if (c === "(") {
+                if (s[i] === "?") {
+                    if (s[i + 1] !== ":")
+                        fail("unsupported group");
+                    i += 2;
+                }
+                node = alt();
+                if (s[i] !== ")")
+                    fail("unbalanced parentheses");
+                i++;
+            }
+            else if (c === "[")
+                node = { t: "char", test: klass() };
+            else if (c === ".")
+                node = { t: "char", test: (x) => x !== "\n" };
+            else if (c === "^")
+                node = { t: "assert", kind: "bol" };
+            else if (c === "$")
+                node = { t: "assert", kind: "eol" };
+            else if (c === "\\") {
+                const e = escaped(false);
+                if (e === "b" || e === "B")
+                    node = { t: "assert", kind: e === "b" ? "word" : "nonword" };
+                else if (typeof e === "string")
+                    node = { t: "char", test: (x) => x === e };
+                else
+                    node = { t: "char", test: e };
+            }
+            else if ("*+?{".includes(c))
+                return fail("nothing to repeat");
+            else if (c === "]" || c === "}")
+                return fail("unescaped ] or }");
+            else
+                node = { t: "char", test: (x) => x === c };
+            // a quantifier
+            const q = s[i];
+            if (q === "*" || q === "+" || q === "?" || q === "{") {
+                if (node.t === "assert")
+                    fail("nothing to repeat");
+                i++;
+                let min = 0;
+                let max = null;
+                if (q === "+")
+                    min = 1;
+                else if (q === "?")
+                    max = 1;
+                else if (q === "{") {
+                    const a = count();
+                    if (a === null)
+                        fail("bad repetition");
+                    min = a;
+                    max = min;
+                    if (s[i] === ",") {
+                        i++;
+                        max = s[i] === "}" ? null : count();
+                        if (max === null && s[i] !== "}")
+                            fail("bad repetition");
+                    }
+                    if (s[i] !== "}")
+                        fail("bad repetition");
+                    i++;
+                    if (min > MAX_REPEAT || (max !== null && (max > MAX_REPEAT || max < min)))
+                        fail("bad repetition");
+                }
+                if (s[i] === "?")
+                    i++; // lazy: the same answer for a yes/no match
+                const again = s[i];
+                if (again !== undefined && "*+?{".includes(again))
+                    fail("nothing to repeat");
+                node = { t: "rep", node, min, max };
+            }
+            items.push(node);
+        }
+        return items.length === 1 ? items[0] : { t: "cat", items };
+    };
+    try {
+        const tree = alt();
+        if (i < s.length)
+            fail("unbalanced parentheses");
+        const prog = [];
+        const emit = (n) => {
+            if (prog.length > MAX_PROGRAM)
+                fail("pattern too large");
+            if (n.t === "char")
+                prog.push({ op: "char", test: n.test });
+            else if (n.t === "assert")
+                prog.push({ op: "assert", kind: n.kind });
+            else if (n.t === "cat")
+                for (const x of n.items)
+                    emit(x);
+            else if (n.t === "alt") {
+                const jumps = [];
+                n.items.forEach((x, k) => {
+                    if (k < n.items.length - 1) {
+                        const split = { op: "split", x: prog.length + 1, y: 0 };
+                        prog.push(split);
+                        emit(x);
+                        const j = { op: "jmp", x: 0 };
+                        prog.push(j);
+                        jumps.push(j);
+                        split.y = prog.length;
+                    }
+                    else
+                        emit(x);
+                });
+                for (const j of jumps)
+                    j.x = prog.length;
+            }
+            else {
+                for (let k = 0; k < n.min; k++)
+                    emit(n.node);
+                if (n.max === null) {
+                    const split = { op: "split", x: prog.length + 1, y: 0 };
+                    prog.push(split);
+                    emit(n.node);
+                    prog.push({ op: "jmp", x: prog.indexOf(split) });
+                    split.y = prog.length;
+                }
+                else
+                    for (let k = n.min; k < n.max; k++) {
+                        const split = { op: "split", x: prog.length + 1, y: 0 };
+                        prog.push(split);
+                        emit(n.node);
+                        split.y = prog.length;
+                    }
+            }
+        };
+        emit(tree);
+        prog.push({ op: "match" });
+        if (prog.length > MAX_PROGRAM)
+            fail("pattern too large");
+        return { prog };
+    }
+    catch (e) {
+        if (e instanceof PatternError)
+            return e.message;
+        throw e;
+    }
+}
+/** Whether the pattern matches anywhere in the text (a search, not a full match). */
+export function patternMatches(p, text) {
+    const chars = Array.from(text);
+    const n = chars.length;
+    const { prog } = p;
+    const mark = new Int32Array(prog.length).fill(-1);
+    const add = (list, pc, pos) => {
+        const stack = [pc];
+        while (stack.length) {
+            const at = stack.pop();
+            if (mark[at] === pos)
+                continue;
+            mark[at] = pos;
+            const inst = prog[at];
+            if (inst.op === "match")
+                return true;
+            if (inst.op === "jmp")
+                stack.push(inst.x);
+            else if (inst.op === "split")
+                stack.push(inst.y, inst.x);
+            else if (inst.op === "char")
+                list.push(at);
+            else {
+                const before = pos > 0 && isWord(chars[pos - 1]);
+                const after = pos < n && isWord(chars[pos]);
+                const ok = inst.kind === "bol"
+                    ? pos === 0
+                    : inst.kind === "eol"
+                        ? pos === n
+                        : inst.kind === "word"
+                            ? before !== after
+                            : before === after;
+                if (ok)
+                    stack.push(at + 1);
+            }
+        }
+        return false;
+    };
+    let list = [];
+    for (let pos = 0;; pos++) {
+        if (add(list, 0, pos))
+            return true;
+        if (pos === n)
+            return false;
+        const c = chars[pos];
+        const next = [];
+        for (const at of list) {
+            const inst = prog[at];
+            if (inst.test(c) && add(next, at + 1, pos + 1))
+                return true;
+        }
+        list = next;
+    }
+}
+// ---------------------------------------------------------------- JSON values
+const PATH = /^\$(?:\.[A-Za-z_][A-Za-z0-9_]*|\[[0-9]{1,4}\])*$/;
+const ABSENT = Symbol("absent");
+/** The value at a JSON path (`$`, `.name`, `[index]`), or ABSENT. */
+function at(value, path) {
+    let v = value;
+    for (const m of path.slice(1).matchAll(/\.([A-Za-z_][A-Za-z0-9_]*)|\[([0-9]+)\]/g)) {
+        if (m[1] !== undefined) {
+            if (!isObj(v) || !Object.hasOwn(v, m[1]))
+                return ABSENT;
+            v = v[m[1]];
+        }
+        else {
+            const k = Number(m[2]);
+            if (!Array.isArray(v) || k >= v.length)
+                return ABSENT;
+            v = v[k];
+        }
+    }
+    return v;
+}
+const isInt = (v) => typeof v === "number" && Number.isSafeInteger(v);
+const isScalar = (v) => v === null ||
+    typeof v === "boolean" ||
+    isInt(v) ||
+    (typeof v === "string" && Array.from(v).length <= 1000);
+/** Deep JSON equality (a number equals a number of the same value; true is never 1). */
+function jsonEq(a, b) {
+    if (typeof a === "number" || typeof b === "number")
+        return a === b;
+    if (Array.isArray(a) || Array.isArray(b))
+        return (Array.isArray(a) &&
+            Array.isArray(b) &&
+            a.length === b.length &&
+            a.every((x, k) => jsonEq(x, b[k])));
+    if (isObj(a) || isObj(b)) {
+        if (!isObj(a) || !isObj(b))
+            return false;
+        const ka = Object.keys(a).sort();
+        const kb = Object.keys(b).sort();
+        return canonical(ka) === canonical(kb) && ka.every((k) => jsonEq(a[k], b[k]));
+    }
+    return a === b;
+}
+/** Every number in it is a safe integer (no floats in a hashed object). */
+function integersOnly(v) {
+    if (typeof v === "number")
+        return Number.isSafeInteger(v);
+    if (Array.isArray(v))
+        return v.every(integersOnly);
+    if (isObj(v))
+        return Object.values(v).every(integersOnly);
+    return true;
+}
+function depthOf(v) {
+    if (Array.isArray(v))
+        return 1 + Math.max(0, ...v.map(depthOf));
+    if (isObj(v))
+        return 1 + Math.max(0, ...Object.values(v).map(depthOf));
+    return 0;
+}
+/** A value in integer milli-units (spec/findings.md §5a.2), or null. */
+export function milliOf(v) {
+    let text;
+    if (typeof v === "number") {
+        if (!Number.isFinite(v))
+            return null;
+        if (Number.isInteger(v)) {
+            const m = v * 1000;
+            return Number.isSafeInteger(v) && Number.isSafeInteger(m) ? m : null;
+        }
+        if (Math.abs(v) >= 1e15)
+            return null;
+        text = String(v);
+    }
+    else if (typeof v === "string")
+        text = v;
+    else
+        return null;
+    const m = /^(-?)([0-9]{1,15})(?:\.([0-9]{1,3}))?$/.exec(text);
+    if (!m)
+        return null;
+    const n = Number(m[2]) * 1000 + Number((m[3] ?? "").padEnd(3, "0"));
+    return m[1] ? -n : n;
+}
+// ---------------------------------------------------------------- the schema subset (§5a.3)
+const TYPES = ["object", "array", "string", "integer", "number", "boolean", "null"];
+const SCHEMA_KEYS = [
+    "type",
+    "enum",
+    "const",
+    "required",
+    "properties",
+    "additionalProperties",
+    "items",
+    "minItems",
+    "maxItems",
+    "minLength",
+    "maxLength",
+    "minimum",
+    "maximum",
+    "pattern",
+    "title",
+    "description",
+];
+/** Why a schema is outside the subset, or undefined. */
+export function checkSchema(schema) {
+    if (!integersOnly(schema))
+        return "numbers must be integers";
+    if (depthOf(schema) > 16)
+        return "nested more than 16 levels";
+    if (new TextEncoder().encode(canonical(schema)).length > 8192)
+        return "larger than 8192 bytes";
+    const walk = (x) => {
+        if (!isObj(x))
+            return "a schema must be an object";
+        for (const k of Object.keys(x).sort()) {
+            const v = x[k];
+            if (!SCHEMA_KEYS.includes(k))
+                return `unsupported keyword ${k}`;
+            const bad = `bad value for ${k}`;
+            if (k === "type") {
+                const list = Array.isArray(v) ? v : [v];
+                if (list.length === 0 ||
+                    !list.every((t) => typeof t === "string" && TYPES.includes(t)) ||
+                    new Set(list).size !== list.length)
+                    return bad;
+            }
+            else if (k === "enum") {
+                if (!Array.isArray(v) || v.length === 0 || v.length > 100)
+                    return bad;
+            }
+            else if (k === "required") {
+                if (!Array.isArray(v) || v.length > 100 || !v.every((r) => typeof r === "string"))
+                    return bad;
+            }
+            else if (k === "properties") {
+                if (!isObj(v) || Object.keys(v).length > 100)
+                    return bad;
+                for (const name of Object.keys(v).sort()) {
+                    const e = walk(v[name]);
+                    if (e)
+                        return e;
+                }
+            }
+            else if (k === "additionalProperties") {
+                if (typeof v !== "boolean") {
+                    const e = walk(v);
+                    if (e)
+                        return e;
+                }
+            }
+            else if (k === "items") {
+                const e = walk(v);
+                if (e)
+                    return e;
+            }
+            else if (["minItems", "maxItems", "minLength", "maxLength"].includes(k)) {
+                if (!isInt(v) || v < 0)
+                    return bad;
+            }
+            else if (k === "minimum" || k === "maximum") {
+                if (!isInt(v))
+                    return bad;
+            }
+            else if (k === "pattern") {
+                const p = compilePattern(v);
+                if (typeof p === "string")
+                    return `pattern: ${p}`;
+            }
+            else if (k === "title" || k === "description") {
+                if (typeof v !== "string")
+                    return bad;
+            }
+        }
+        return undefined;
+    };
+    return walk(schema);
+}
+const typeOf = (v) => v === null
+    ? ["null"]
+    : typeof v === "boolean"
+        ? ["boolean"]
+        : typeof v === "number"
+            ? Number.isInteger(v)
+                ? ["integer", "number"]
+                : ["number"]
+            : typeof v === "string"
+                ? ["string"]
+                : Array.isArray(v)
+                    ? ["array"]
+                    : ["object"];
+/** The first place a value breaks a (checked) schema, or undefined (spec/findings.md §5a.3). */
+export function schemaError(value, schema, path = "$") {
+    const s = schema;
+    const types = typeOf(value);
+    if (s.type !== undefined) {
+        const want = (Array.isArray(s.type) ? s.type : [s.type]);
+        if (!want.some((t) => types.includes(t)))
+            return `${path}: expected ${want.join(" or ")}`;
+    }
+    if ("const" in s && !jsonEq(value, s.const))
+        return `${path}: not the expected value`;
+    if (Array.isArray(s.enum) && !s.enum.some((x) => jsonEq(value, x)))
+        return `${path}: not one of the allowed values`;
+    if (typeof value === "string") {
+        const n = Array.from(value).length;
+        if (isInt(s.minLength) && n < s.minLength)
+            return `${path}: shorter than ${s.minLength} characters`;
+        if (isInt(s.maxLength) && n > s.maxLength)
+            return `${path}: longer than ${s.maxLength} characters`;
+        if (typeof s.pattern === "string") {
+            const p = compilePattern(s.pattern);
+            if (n > MAX_MATCH_TEXT || !patternMatches(p, value))
+                return `${path}: doesn't match the pattern`;
+        }
+    }
+    if (typeof value === "number") {
+        if (isInt(s.minimum) && value < s.minimum)
+            return `${path}: less than ${s.minimum}`;
+        if (isInt(s.maximum) && value > s.maximum)
+            return `${path}: more than ${s.maximum}`;
+    }
+    if (Array.isArray(value)) {
+        if (isInt(s.minItems) && value.length < s.minItems)
+            return `${path}: fewer than ${s.minItems} items`;
+        if (isInt(s.maxItems) && value.length > s.maxItems)
+            return `${path}: more than ${s.maxItems} items`;
+        if (s.items !== undefined)
+            for (let k = 0; k < value.length; k++) {
+                const e = schemaError(value[k], s.items, `${path}[${k}]`);
+                if (e)
+                    return e;
+            }
+    }
+    if (isObj(value)) {
+        if (Array.isArray(s.required))
+            for (const r of s.required)
+                if (!Object.hasOwn(value, r))
+                    return `${path}: missing ${r}`;
+        const props = isObj(s.properties) ? s.properties : {};
+        for (const k of Object.keys(props).sort())
+            if (Object.hasOwn(value, k)) {
+                const e = schemaError(value[k], props[k], `${path}.${k}`);
+                if (e)
+                    return e;
+            }
+        if (s.additionalProperties !== undefined && s.additionalProperties !== true)
+            for (const k of Object.keys(value).sort()) {
+                if (Object.hasOwn(props, k))
+                    continue;
+                if (s.additionalProperties === false)
+                    return `${path}: unexpected property ${k}`;
+                const e = schemaError(value[k], s.additionalProperties, `${path}.${k}`);
+                if (e)
+                    return e;
+            }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------- the predicates (§5a)
+const OPS = ["equals", "in", "matches", "range", "exists"];
+const ANSWER_OPS = ["contains", "not_contains", "matches", "schema"];
+/** Why a `tool_args` or `answer` predicate is invalid, or undefined. */
+export function checkPredicate(p) {
+    if (!isObj(p) || Object.keys(p).length !== 1)
+        return "a predicate is an object with one key";
+    const [key, arg] = Object.entries(p)[0];
+    if (!integersOnly(arg))
+        return "numbers in a predicate must be integers";
+    if (key === "tool_args") {
+        if (!isObj(arg))
+            return "tool_args must be an object";
+        const extra = Object.keys(arg).filter((k) => !["tool", "path", "for", ...OPS].includes(k));
+        if (extra.length)
+            return `tool_args has unknown fields: ${extra.sort().join(", ")}`;
+        if (typeof arg.tool !== "string" || arg.tool.length === 0 || arg.tool.length > 128)
+            return "tool_args.tool must be a tool name";
+        if (arg.path !== undefined &&
+            !(typeof arg.path === "string" && arg.path.length <= 256 && PATH.test(arg.path)))
+            return "tool_args.path must be a JSON path like $.a.b[0]";
+        if (arg.for !== undefined && arg.for !== "some" && arg.for !== "every")
+            return 'tool_args.for must be "some" or "every"';
+        const ops = OPS.filter((k) => k in arg);
+        if (ops.length !== 1)
+            return "tool_args needs exactly one of equals, in, matches, range, exists";
+        const v = arg[ops[0]];
+        if (ops[0] === "equals" && !isScalar(v))
+            return "tool_args.equals must be a string, an integer, true, false or null";
+        if (ops[0] === "in" &&
+            !(Array.isArray(v) && v.length > 0 && v.length <= 100 && v.every(isScalar)))
+            return "tool_args.in must be 1-100 strings, integers, booleans or nulls";
+        if (ops[0] === "matches") {
+            const c = compilePattern(v);
+            if (typeof c === "string")
+                return `tool_args.matches: ${c}`;
+        }
+        if (ops[0] === "range") {
+            const r = v;
+            if (!isObj(r) ||
+                Object.keys(r).some((k) => !["min", "max", "unit"].includes(k)) ||
+                (r.min === undefined && r.max === undefined) ||
+                (r.min !== undefined && !isInt(r.min)) ||
+                (r.max !== undefined && !isInt(r.max)) ||
+                (isInt(r.min) && isInt(r.max) && r.min > r.max) ||
+                (r.unit !== undefined && r.unit !== "milli"))
+                return 'tool_args.range must be {min?, max?, unit?: "milli"} with integer bounds, min <= max';
+        }
+        if (ops[0] === "exists" && typeof v !== "boolean")
+            return "tool_args.exists must be true or false";
+        return undefined;
+    }
+    if (key === "answer") {
+        const ops = isObj(arg) ? Object.keys(arg) : [];
+        if (!isObj(arg) || ops.length !== 1 || !ANSWER_OPS.includes(ops[0]))
+            return "answer must be an object with exactly one of contains, not_contains, matches, schema";
+        const op = ops[0];
+        const v = arg[op];
+        if (op === "contains" || op === "not_contains") {
+            if (typeof v !== "string" || v.length === 0 || Array.from(v).length > 1000)
+                return `answer.${op} must be a string of 1-1000 characters`;
+        }
+        else if (op === "matches") {
+            const c = compilePattern(v);
+            if (typeof c === "string")
+                return `answer.matches: ${c}`;
+        }
+        else {
+            const e = checkSchema(v);
+            if (e)
+                return `answer.schema: ${e}`;
+        }
+        return undefined;
+    }
+    return "unsupported predicate";
+}
+const verdict = (result, gap) => (gap ? { result, gap } : { result });
+/** Whether one value satisfies a (checked) tool_args operation. */
+function satisfies(arg, value) {
+    if ("exists" in arg)
+        return (value !== ABSENT) === arg.exists;
+    if (value === ABSENT)
+        return false;
+    if ("equals" in arg)
+        return isScalarValue(value) && jsonEq(value, arg.equals);
+    if ("in" in arg)
+        return isScalarValue(value) && arg.in.some((x) => jsonEq(value, x));
+    if ("matches" in arg) {
+        if (typeof value !== "string" || Array.from(value).length > MAX_MATCH_TEXT)
+            return false;
+        return patternMatches(compilePattern(arg.matches), value);
+    }
+    const r = arg.range;
+    const n = r.unit === "milli"
+        ? milliOf(value)
+        : typeof value === "number" && Number.isSafeInteger(value)
+            ? value
+            : null;
+    return n !== null && (r.min === undefined || n >= r.min) && (r.max === undefined || n <= r.max);
+}
+const isScalarValue = (v) => v === null || typeof v === "boolean" || typeof v === "string" || typeof v === "number";
+/** A `tool_args` predicate over the tool calls before `before` (spec/findings.md §5a.2). */
+export function judgeArgs(arg, uses, before) {
+    const tool = arg.tool;
+    const path = typeof arg.path === "string" ? arg.path : "$";
+    const named = uses.filter((u) => u.seq < before && u.tool === tool);
+    const judged = named.map((u) => (u.hasArgs ? satisfies(arg, at(u.args, path)) : null));
+    if (arg.for === "every") {
+        const k = judged.indexOf(false);
+        if (k >= 0)
+            return verdict("fail", `${tool} was called with arguments outside the plan at ${path} (seq ${named[k].seq})`);
+        if (judged.includes(null))
+            return verdict("cannot_verify", `${tool}'s arguments aren't on the record`);
+        return verdict("pass");
+    }
+    if (!named.length)
+        return verdict("fail", `${tool} was never called`);
+    if (judged.includes(true))
+        return verdict("pass");
+    if (judged.includes(null))
+        return verdict("cannot_verify", `${tool}'s arguments aren't on the record`);
+    return verdict("fail", `no ${tool} call had arguments matching the plan at ${path}`);
+}
+const TRIM = " \t\n\r";
+function trim(s) {
+    let a = 0;
+    let b = s.length;
+    while (a < b && TRIM.includes(s[a]))
+        a++;
+    while (b > a && TRIM.includes(s[b - 1]))
+        b--;
+    return s.slice(a, b);
+}
+/** The JSON an answer holds: the whole text, or one ``` fence around it; ABSENT when it isn't JSON. */
+export function answerJson(text) {
+    let t = trim(text);
+    if (t.startsWith("```")) {
+        const nl = t.indexOf("\n");
+        t = nl < 0 ? "" : t.slice(nl + 1);
+        t = trim(t);
+        if (t.endsWith("```"))
+            t = trim(t.slice(0, -3));
+    }
+    try {
+        return JSON.parse(t);
+    }
+    catch {
+        return ABSENT;
+    }
+}
+/** An `answer` predicate over the last final answer before `before` (spec/findings.md §5a.4). */
+export function judgeAnswer(arg, answers, before) {
+    const last = [...answers].reverse().find((a) => a.seq < before);
+    if (!last)
+        return verdict("cannot_verify", "no final answer on the record before the claim");
+    const text = last.text;
+    if (typeof arg.contains === "string")
+        return text.includes(arg.contains)
+            ? verdict("pass")
+            : verdict("fail", "the answer doesn't contain the expected text");
+    if (typeof arg.not_contains === "string")
+        return text.includes(arg.not_contains)
+            ? verdict("fail", "the answer contains text the plan rules out")
+            : verdict("pass");
+    if (typeof arg.matches === "string") {
+        if (Array.from(text).length > MAX_MATCH_TEXT)
+            return verdict("cannot_verify", "the answer is too long to match");
+        return patternMatches(compilePattern(arg.matches), text)
+            ? verdict("pass")
+            : verdict("fail", "the answer doesn't match the pattern");
+    }
+    const value = answerJson(text);
+    if (value === ABSENT)
+        return verdict("fail", "the answer isn't JSON");
+    const e = schemaError(value, arg.schema);
+    return e ? verdict("fail", `the answer doesn't match the schema (${e})`) : verdict("pass");
+}