@crewhaus/tool-schema 0.7.0 → 0.8.1

package/dist/lib/records.d.ts

@@ -8,6 +8,7 @@
  * foreign key point at something that exists.
  */
 import { type Schema, type ValidationError } from "./jsonschema";
+import type { RegexAnswers } from "./regex-answers";
 export type RowFailure = {
     /** 0-based index of the row in the input array. */
     row: number;
@@ -16,10 +17,23 @@ export type RowFailure = {
     errors: ValidationError[];
 };
 export type RecordsReport = {
+    /** False when any row failed OR could not be decided. */
     ok: boolean;
     total: number;
     passed: number;
     failed: number;
+    /**
+     * Rows with no verdict, neither passed nor failed: the call's work budget
+     * ran out on or before them (a schema's anyOf/oneOf/allOf over shared
+     * $refs multiplied past it), or a `pattern` could not be run to an answer
+     * on them.
+     */
+    undetermined: number;
+    /** The first undetermined row and why, or null. */
+    undeterminedFrom: {
+        row: number;
+        reason: string;
+    } | null;
     /** Failures, capped at `maxFailedRows`. */
     failures: RowFailure[];
     /** True when the failure list was cut short; `failed` is still the true count. */
@@ -41,6 +55,8 @@ export type ValidateRecordsOptions = {
     maxFailedRows: number;
     /** A field whose value identifies the row in the report. */
     idField: string | null;
+    /** Answers for the schema's patterns; see `ValidateOptions.regex`. */
+    regex?: RegexAnswers;
 };
 export declare const DEFAULT_RECORDS_OPTIONS: ValidateRecordsOptions;
 /**

package/dist/lib/records.js

@@ -7,7 +7,7 @@
  * does every row match the schema, is the key actually unique, and does every
  * foreign key point at something that exists.
  */
-import { validateValue } from "./jsonschema";
+import { defaultWorkLimit, validateValue, } from "./jsonschema";
 import { canonicalize, getPath, isPlainObject, preview, typeOf } from "./value";
 /** Joins a path and a keyword into one map key; a character no path contains. */
 const ISSUE_SEPARATOR = String.fromCharCode(0);
@@ -40,13 +40,25 @@ export function validateRecords(rows, schema, options = {}) {
     const issues = new Map();
     const unsupported = new Set();
     let failed = 0;
+    let undetermined = 0;
+    let undeterminedFrom = null;
+    // One budget for the whole call, sized by all the rows together: a
+    // per-row budget would let 20,000 hostile rows each spend a full one.
+    const budget = { used: 0, limit: defaultWorkLimit(rows, schema) };
     rows.forEach((row, index) => {
         const result = validateValue(row, schema, {
             assertFormat: opts.assertFormat,
             maxErrors: opts.maxErrorsPerRow,
+            budget,
+            ...(opts.regex === undefined ? {} : { regex: opts.regex }),
         });
         for (const keyword of result.unsupportedKeywords)
             unsupported.add(keyword);
+        if (result.undetermined !== null) {
+            undetermined += 1;
+            undeterminedFrom ??= { row: index, reason: result.undetermined };
+            return;
+        }
         if (result.valid)
             return;
         failed += 1;
@@ -80,10 +92,12 @@ export function validateRecords(rows, schema, options = {}) {
     const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
     const topIssues = [...issues.values()].sort((a, b) => b.rows - a.rows || byCodeUnit(a.path, b.path) || byCodeUnit(a.keyword, b.keyword));
     return {
-        ok: failed === 0,
+        ok: failed === 0 && undetermined === 0,
         total: rows.length,
-        passed: rows.length - failed,
+        passed: rows.length - failed - undetermined,
         failed,
+        undetermined,
+        undeterminedFrom,
         failures,
         truncated: failed > failures.length,
         topIssues,

package/dist/lib/regex-answers.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Caller-supplied patterns, answered off this thread.
+ *
+ * A `matches` check, a JSON Schema `pattern` and a JSONPath `=~` filter all
+ * run a regex someone else wrote over text someone else chose, and the
+ * evaluators that ask are synchronous. A synchronous `RegExp` cannot be
+ * interrupted: `a*a*a*a*b` over 200 characters held the whole process for
+ * 3.5 s, over 400 for 108 s. And when JavaScriptCore gives up on a
+ * backtracking match it returns "no match", so a gate read a real match as a
+ * miss.
+ *
+ * So the evaluator does not run the pattern. It asks {@link RegexAnswers},
+ * which answers from what the worker in `@crewhaus/tool-safety/regex` has
+ * already settled and records anything else as pending. A caller runs the
+ * evaluator once to learn what it will ask, {@link RegexAnswers.resolve}s the
+ * pending questions in one worker session under one deadline, and runs it
+ * again with the answers ({@link withRegexAnswers} does the loop). Every
+ * answer is tri-state: a pattern that could not be run to an answer is
+ * `undetermined`, never `false`, and one the screen refuses (bad syntax, or
+ * a shape that backtracks exponentially) is `refused`, with the reason.
+ *
+ * {@link testPatternSync} is the fallback for a synchronous caller that has
+ * no answers to hand (a library call from another package): the same screen,
+ * a cap on the input it will run over on this thread, and JavaScriptCore's
+ * give-up read as undetermined. It bounds the exponential shapes and the
+ * false verdict, not a polynomial pattern's time; a tool reaches for
+ * {@link RegexAnswers} instead.
+ */
+import { type RegexRejectCode, type RegexSession } from "@crewhaus/tool-safety/regex";
+/** What a caller's pattern says about one input. */
+export type RegexAnswer = boolean
+/** Refused before it ran: invalid syntax, bad flags, or a catastrophic shape. */
+ | {
+    readonly refused: string;
+    readonly code: RegexRejectCode;
+}
+/** Could not be run to an answer: the deadline, the engine giving up, a cap. */
+ | {
+    readonly undetermined: string;
+};
+/** Where a tool call's patterns run: its abort signal, and whose runaway workers they count as. */
+export type RegexRunContext = {
+    readonly signal?: AbortSignal;
+    readonly runawayKey?: string;
+};
+/** The pattern screen's limits for caller patterns: long schema patterns (a URI, a language tag) pass. */
+export declare const CALLER_PATTERN_LIMITS: {
+    readonly maxPatternChars: 10000;
+};
+/** Wall-clock budget for all of one call's pattern questions. */
+export declare const CALLER_PATTERN_DEADLINE_MS = 5000;
+/** The longest single input a pattern is run over in the worker. */
+export declare const CALLER_PATTERN_MAX_ITEM_CHARS = 1048576;
+/** The most distinct (pattern, input) questions one call may ask. */
+export declare const MAX_PATTERN_QUESTIONS = 1000000;
+/** The longest input {@link testPatternSync} runs a pattern over on the caller's thread. */
+export declare const SYNC_PATTERN_MAX_INPUT_CHARS = 65536;
+/**
+ * Test seam: {@link RegexAnswers.resolve} runs its questions in what `wrap`
+ * returns for the worker session it opens, so a test can script an answer
+ * the real engine gives only when it is slow enough (a give-up) instead of
+ * depending on how fast the machine is. Pass `undefined` to restore.
+ */
+export declare function _setRegexAnswersSessionForTest(wrap: ((real: RegexSession) => RegexSession) | undefined): void;
+/** The ctx fields a tool's `execute` receives that a regex run uses. */
+export declare function regexRunContext(ctx: unknown): RegexRunContext;
+/**
+ * The answers a synchronous evaluator reads, and the questions it has asked
+ * that are not answered yet.
+ */
+export declare class RegexAnswers {
+    #private;
+    /**
+     * The answer for `pattern` (with `flags`) on `input`, or undefined when it
+     * is not known yet; the question is then recorded, for {@link resolve}.
+     * The evaluator decides what to assume meanwhile. Past
+     * {@link MAX_PATTERN_QUESTIONS} distinct questions in one call, a new one
+     * is answered undetermined rather than recorded.
+     */
+    lookup(pattern: string, flags: string, input: string): RegexAnswer | undefined;
+    /** How many questions wait for {@link resolve}. */
+    get pending(): number;
+    /**
+     * Forget the pending questions: for an evaluator whose answer no pattern
+     * can change (it ran out of its own work budget), so a caller running it
+     * in rounds stops instead of answering them.
+     */
+    discardPending(): void;
+    /**
+     * Answer every pending question in one worker session: one `testEach` per
+     * pattern over the inputs it was asked about, all of them within
+     * `deadlineMs`. What the worker cannot answer is recorded as undetermined
+     * (or refused), so after this nothing is pending.
+     */
+    resolve(ctx?: RegexRunContext, options?: {
+        readonly deadlineMs?: number;
+    }): Promise<void>;
+}
+/**
+ * Run a synchronous evaluator that reads {@link RegexAnswers}, resolving
+ * what it asked and running it again, until a run asks nothing new. An
+ * evaluator whose later questions depend on earlier answers (a JSON Schema
+ * `if`, the next filter in a path) settles in a few rounds; past
+ * `maxRounds` the result is undetermined rather than a guess. All rounds
+ * share one deadline.
+ */
+export declare function withRegexAnswers<T>(evaluate: (answers: RegexAnswers) => T, ctx?: RegexRunContext, options?: {
+    readonly maxRounds?: number;
+    readonly deadlineMs?: number;
+}): Promise<{
+    readonly value: T;
+} | {
+    readonly undetermined: string;
+}>;
+/** A screened, compiled caller pattern, or why it was refused. */
+export type ScreenedPattern = {
+    readonly ok: true;
+    readonly regex: RegExp;
+} | {
+    readonly ok: false;
+    readonly answer: {
+        refused: string;
+        code: RegexRejectCode;
+    };
+};
+/** Screen and compile a caller pattern for {@link runPatternSync}; remembered per pattern. */
+export declare function screenCallerPattern(pattern: string, flags: string): ScreenedPattern;
+/**
+ * Run a screened pattern on this thread: an input longer than
+ * {@link SYNC_PATTERN_MAX_INPUT_CHARS} is not run, and a no-match that took
+ * as long as JavaScriptCore's give-up is undetermined.
+ */
+export declare function runPatternSync(regex: RegExp, input: string): RegexAnswer;
+/**
+ * Run a caller's pattern on this thread, for a synchronous caller with no
+ * {@link RegexAnswers} to hand. The pattern is screened (a refused one is
+ * `refused`), an input longer than {@link SYNC_PATTERN_MAX_INPUT_CHARS} is
+ * not run, and a no-match that took as long as JavaScriptCore's give-up is
+ * undetermined. That bounds the exponential shapes and the false verdict;
+ * a polynomial pattern's time is bounded only by the input cap.
+ */
+export declare function testPatternSync(pattern: string, flags: string, input: string): RegexAnswer;

package/dist/lib/regex-answers.js

@@ -0,0 +1,289 @@
+/**
+ * Caller-supplied patterns, answered off this thread.
+ *
+ * A `matches` check, a JSON Schema `pattern` and a JSONPath `=~` filter all
+ * run a regex someone else wrote over text someone else chose, and the
+ * evaluators that ask are synchronous. A synchronous `RegExp` cannot be
+ * interrupted: `a*a*a*a*b` over 200 characters held the whole process for
+ * 3.5 s, over 400 for 108 s. And when JavaScriptCore gives up on a
+ * backtracking match it returns "no match", so a gate read a real match as a
+ * miss.
+ *
+ * So the evaluator does not run the pattern. It asks {@link RegexAnswers},
+ * which answers from what the worker in `@crewhaus/tool-safety/regex` has
+ * already settled and records anything else as pending. A caller runs the
+ * evaluator once to learn what it will ask, {@link RegexAnswers.resolve}s the
+ * pending questions in one worker session under one deadline, and runs it
+ * again with the answers ({@link withRegexAnswers} does the loop). Every
+ * answer is tri-state: a pattern that could not be run to an answer is
+ * `undetermined`, never `false`, and one the screen refuses (bad syntax, or
+ * a shape that backtracks exponentially) is `refused`, with the reason.
+ *
+ * {@link testPatternSync} is the fallback for a synchronous caller that has
+ * no answers to hand (a library call from another package): the same screen,
+ * a cap on the input it will run over on this thread, and JavaScriptCore's
+ * give-up read as undetermined. It bounds the exponential shapes and the
+ * false verdict, not a polynomial pattern's time; a tool reaches for
+ * {@link RegexAnswers} instead.
+ */
+import { compileUserRegex, describeRegexOutcome, openRegexSession, } from "@crewhaus/tool-safety/regex";
+/** The pattern screen's limits for caller patterns: long schema patterns (a URI, a language tag) pass. */
+export const CALLER_PATTERN_LIMITS = { maxPatternChars: 10_000 };
+/** Wall-clock budget for all of one call's pattern questions. */
+export const CALLER_PATTERN_DEADLINE_MS = 5_000;
+/** The longest single input a pattern is run over in the worker. */
+export const CALLER_PATTERN_MAX_ITEM_CHARS = 1_048_576;
+/** The most distinct (pattern, input) questions one call may ask. */
+export const MAX_PATTERN_QUESTIONS = 1_000_000;
+/** The longest input {@link testPatternSync} runs a pattern over on the caller's thread. */
+export const SYNC_PATTERN_MAX_INPUT_CHARS = 65_536;
+/**
+ * A no-match that took this long is JavaScriptCore abandoning the match,
+ * not a real no-match (the tool-safety README measured give-ups at 0.4-3 s,
+ * genuine no-matches in microseconds to milliseconds).
+ */
+const GIVE_UP_MS = 100;
+const realSession = (real) => real;
+let wrapSession = realSession;
+/**
+ * Test seam: {@link RegexAnswers.resolve} runs its questions in what `wrap`
+ * returns for the worker session it opens, so a test can script an answer
+ * the real engine gives only when it is slow enough (a give-up) instead of
+ * depending on how fast the machine is. Pass `undefined` to restore.
+ */
+export function _setRegexAnswersSessionForTest(wrap) {
+    wrapSession = wrap ?? realSession;
+}
+/** The ctx fields a tool's `execute` receives that a regex run uses. */
+export function regexRunContext(ctx) {
+    const c = ctx;
+    return {
+        ...(c?.signal === undefined ? {} : { signal: c.signal }),
+        ...(typeof c?.runContext?.sessionId === "string" ? { runawayKey: c.runContext.sessionId } : {}),
+    };
+}
+const keyOf = (pattern, flags) => `${flags}\u0000${pattern}`;
+/**
+ * The answers a synchronous evaluator reads, and the questions it has asked
+ * that are not answered yet.
+ */
+export class RegexAnswers {
+    #known = new Map();
+    #pending = new Map();
+    #asked = 0;
+    /**
+     * The answer for `pattern` (with `flags`) on `input`, or undefined when it
+     * is not known yet; the question is then recorded, for {@link resolve}.
+     * The evaluator decides what to assume meanwhile. Past
+     * {@link MAX_PATTERN_QUESTIONS} distinct questions in one call, a new one
+     * is answered undetermined rather than recorded.
+     */
+    lookup(pattern, flags, input) {
+        const key = keyOf(pattern, flags);
+        const known = this.#known.get(key)?.get(input);
+        if (known !== undefined)
+            return known;
+        let group = this.#pending.get(key);
+        if (group?.inputs.has(input) === true)
+            return undefined;
+        if (this.#asked >= MAX_PATTERN_QUESTIONS) {
+            return {
+                undetermined: `the call asked more than ${MAX_PATTERN_QUESTIONS} distinct pattern questions`,
+            };
+        }
+        if (group === undefined) {
+            group = { pattern, flags, inputs: new Set() };
+            this.#pending.set(key, group);
+        }
+        group.inputs.add(input);
+        this.#asked += 1;
+        return undefined;
+    }
+    /** How many questions wait for {@link resolve}. */
+    get pending() {
+        let n = 0;
+        for (const group of this.#pending.values())
+            n += group.inputs.size;
+        return n;
+    }
+    /**
+     * Forget the pending questions: for an evaluator whose answer no pattern
+     * can change (it ran out of its own work budget), so a caller running it
+     * in rounds stops instead of answering them.
+     */
+    discardPending() {
+        this.#pending.clear();
+    }
+    #settle(group, input, answer) {
+        const key = keyOf(group.pattern, group.flags);
+        let answers = this.#known.get(key);
+        if (answers === undefined) {
+            answers = new Map();
+            this.#known.set(key, answers);
+        }
+        answers.set(input, answer);
+    }
+    /**
+     * Answer every pending question in one worker session: one `testEach` per
+     * pattern over the inputs it was asked about, all of them within
+     * `deadlineMs`. What the worker cannot answer is recorded as undetermined
+     * (or refused), so after this nothing is pending.
+     */
+    async resolve(ctx = {}, options = {}) {
+        const deadlineMs = options.deadlineMs ?? CALLER_PATTERN_DEADLINE_MS;
+        const groups = [...this.#pending.values()];
+        this.#pending.clear();
+        if (groups.length === 0)
+            return;
+        const started = performance.now();
+        const session = wrapSession(openRegexSession());
+        try {
+            for (const group of groups) {
+                const inputs = [...group.inputs];
+                const left = Math.floor(deadlineMs - (performance.now() - started));
+                if (left < 1) {
+                    for (const input of inputs) {
+                        this.#settle(group, input, {
+                            undetermined: `the call's ${deadlineMs} ms for running patterns ran out before this one could run`,
+                        });
+                    }
+                    continue;
+                }
+                let total = inputs.length;
+                for (const input of inputs)
+                    total += input.length;
+                const outcome = await session.run({
+                    op: "testEach",
+                    pattern: group.pattern,
+                    flags: group.flags,
+                    inputs,
+                    maxMatches: inputs.length,
+                    onGiveUp: "skip",
+                    deadlineMs: left,
+                    maxInputChars: total,
+                    maxItemChars: CALLER_PATTERN_MAX_ITEM_CHARS,
+                    limits: CALLER_PATTERN_LIMITS,
+                    ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
+                    ...(ctx.runawayKey === undefined ? {} : { runawayKey: ctx.runawayKey }),
+                });
+                this.#record(group, inputs, outcome);
+            }
+        }
+        finally {
+            session.close();
+        }
+    }
+    #record(group, inputs, outcome) {
+        if (outcome.status === "rejected") {
+            const refused = { refused: describeRegexOutcome(outcome), code: outcome.code };
+            for (const input of inputs)
+                this.#settle(group, input, refused);
+            return;
+        }
+        // A full answer, or the part of one a timeout or give-up left behind.
+        const result = outcome.status === "ok"
+            ? outcome.result
+            : outcome.status === "timeout" || outcome.status === "gave-up"
+                ? outcome.partial
+                : undefined;
+        const why = outcome.status === "ok"
+            ? `the regex engine gave up on this input, or it is longer than the ${CALLER_PATTERN_MAX_ITEM_CHARS} characters a pattern is run over`
+            : describeRegexOutcome(outcome);
+        const matched = new Set(result?.matched ?? []);
+        const skipped = new Set(result?.undetermined ?? []);
+        const scanned = result?.scanned ?? 0;
+        for (const [i, input] of inputs.entries()) {
+            if (i >= scanned || skipped.has(i)) {
+                this.#settle(group, input, { undetermined: why });
+            }
+            else {
+                this.#settle(group, input, matched.has(i));
+            }
+        }
+    }
+}
+/**
+ * Run a synchronous evaluator that reads {@link RegexAnswers}, resolving
+ * what it asked and running it again, until a run asks nothing new. An
+ * evaluator whose later questions depend on earlier answers (a JSON Schema
+ * `if`, the next filter in a path) settles in a few rounds; past
+ * `maxRounds` the result is undetermined rather than a guess. All rounds
+ * share one deadline.
+ */
+export async function withRegexAnswers(evaluate, ctx = {}, options = {}) {
+    const maxRounds = options.maxRounds ?? 8;
+    const deadlineMs = options.deadlineMs ?? CALLER_PATTERN_DEADLINE_MS;
+    const started = performance.now();
+    const answers = new RegexAnswers();
+    for (let round = 0; round < maxRounds; round++) {
+        const value = evaluate(answers);
+        if (answers.pending === 0)
+            return { value };
+        const left = Math.max(1, Math.floor(deadlineMs - (performance.now() - started)));
+        await answers.resolve(ctx, { deadlineMs: left });
+    }
+    return {
+        undetermined: `the patterns' answers kept changing which patterns were asked for, past ${maxRounds} rounds`,
+    };
+}
+/** Recently screened patterns, least recent first: a loop over rows compiles each once. */
+const screened = new Map();
+const SCREENED_ENTRIES = 512;
+/** Screen and compile a caller pattern for {@link runPatternSync}; remembered per pattern. */
+export function screenCallerPattern(pattern, flags) {
+    const key = keyOf(pattern, flags);
+    const known = screened.get(key);
+    if (known !== undefined) {
+        screened.delete(key);
+        screened.set(key, known);
+        return known;
+    }
+    const compiled = compileUserRegex(pattern, flags, CALLER_PATTERN_LIMITS);
+    const out = compiled.ok
+        ? { ok: true, regex: compiled.regex }
+        : {
+            ok: false,
+            answer: {
+                refused: `pattern refused (${compiled.code}): ${compiled.reason}`,
+                code: compiled.code,
+            },
+        };
+    if (screened.size >= SCREENED_ENTRIES)
+        screened.delete(screened.keys().next().value);
+    screened.set(key, out);
+    return out;
+}
+/**
+ * Run a screened pattern on this thread: an input longer than
+ * {@link SYNC_PATTERN_MAX_INPUT_CHARS} is not run, and a no-match that took
+ * as long as JavaScriptCore's give-up is undetermined.
+ */
+export function runPatternSync(regex, input) {
+    if (input.length > SYNC_PATTERN_MAX_INPUT_CHARS) {
+        return {
+            undetermined: `the input is ${input.length} characters, more than the ${SYNC_PATTERN_MAX_INPUT_CHARS} a pattern is run over on the caller's thread`,
+        };
+    }
+    regex.lastIndex = 0;
+    const started = performance.now();
+    const hit = regex.test(input);
+    const ms = performance.now() - started;
+    if (!hit && ms >= GIVE_UP_MS) {
+        return {
+            undetermined: `the regex engine gave up after ${Math.round(ms)} ms, which it reports as no match, so whether it matches is unknown`,
+        };
+    }
+    return hit;
+}
+/**
+ * Run a caller's pattern on this thread, for a synchronous caller with no
+ * {@link RegexAnswers} to hand. The pattern is screened (a refused one is
+ * `refused`), an input longer than {@link SYNC_PATTERN_MAX_INPUT_CHARS} is
+ * not run, and a no-match that took as long as JavaScriptCore's give-up is
+ * undetermined. That bounds the exponential shapes and the false verdict;
+ * a polynomial pattern's time is bounded only by the input cap.
+ */
+export function testPatternSync(pattern, flags, input) {
+    const s = screenCallerPattern(pattern, flags);
+    return s.ok ? runPatternSync(s.regex, input) : s.answer;
+}

package/dist/lib/schemadiff.d.ts

@@ -19,8 +19,27 @@ export type SchemaDiffResult = {
         unknown: number;
     };
 };
+/**
+ * The deepest a schema may nest, counting every object and array, for it to
+ * be diffed. Each level is a level of recursion here, and the stack's own
+ * limit moves with the platform and with how warm the code is: a schema
+ * near it came back answered in one process and as a crash in another. A
+ * fixed limit answers the same everywhere. It also bounds the pointers: every
+ * change carries its full path, so a schema differing at every level made a
+ * result the square of its depth. The same limit tool-data puts on a
+ * document.
+ */
+export declare const MAX_SCHEMA_DEPTH = 256;
+/**
+ * Whether `value` nests deeper than `limit` objects and arrays, read with an
+ * explicit stack and abandoned as soon as it does. An object reached again
+ * (only a caller's own value can share one) is walked again only when it is
+ * reached deeper, so a cycle is too deep rather than endless.
+ */
+export declare function nestsDeeperThan(value: unknown, limit: number): boolean;
 /**
  * Diff two schemas and classify each change. See the module comment for what
  * "compatible" means here and for the cases deliberately left `unknown`.
+ * Refuses a schema nested past {@link MAX_SCHEMA_DEPTH}, before reading it.
  */
 export declare function diffSchemas(before: unknown, after: unknown): SchemaDiffResult;