@crewhaus/tool-schema 0.7.0 → 0.8.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+CrewHaus Factory
+Copyright 2026 Max Meier
+
+This product includes software developed by Max Meier
+(operating as StudioMax — https://studiomax.io) and contributors.
+
+The CrewHaus name and logo are trademarks of Max Meier. See
+https://github.com/crewhaus/factory/blob/main/TRADEMARK.md for the
+use-of-marks policy.

package/README.md

@@ -12,7 +12,7 @@ answer twice — and say exactly which field, at which path, was wrong.
 ```yaml
 tools:
   - all-schema        # every tool below
-  - -JsonSchemaInfer  # ...except this one
+  - -jsonSchemaInfer  # ...except this one
 ```
 
 | Tool | What it does |
@@ -64,6 +64,55 @@ sitting in a branch this particular value never reached is not in it. A
 
 `format` follows Draft-07 and is an annotation until you pass `assertFormat`.
 
+A recursive schema may recurse through any keyword, `anyOf`, `oneOf`, `not`,
+`if` and `contains` included; only the same `$ref` reached twice at the same
+place in the value is reported as a cycle. Depth is counted where the value
+nests, so a recursive schema follows a value 512 levels deep whatever
+keywords it recurses through; a deeper value, or a schema nested so deep the
+walk would overflow the stack, is `undetermined` rather than a verdict.
+
+**The work is bounded.** `anyOf`, `oneOf` and `allOf` over `$ref`s that share
+a target multiply, so a small schema can ask for billions of evaluations.
+Each call gets a budget of subschema evaluations, sized to the value and the
+schema: each node of the value (a long string or key counting as a node per
+256 characters) is allowed as many evaluations as the schema has subschemas
+written out, at least 64 and at most 1,024, and a call gets at least 500,000
+and at most 20 million (a few seconds). A schema written as a tree checks each
+of its subschemas at most once per value node, so a wide or nested union over
+thousands of valid rows is answered; only a `$ref` reached again at the same
+place goes past it. A check whose cost follows the value's size — a string's
+length, pattern or format, `uniqueItems`, listing an object's keys, each
+`enum` candidate (an enum is indexed once, so a value is one lookup), each
+key tested against each `patternProperties` pattern (compiled once per
+schema), a `const` comparison — is charged for that size, and an error
+message is built only when it is kept, from a preview that reads just the
+part it shows. When a schema needs more, `JsonSchemaValidate` answers
+`valid: null` with `undetermined: true` and the reason, never a verdict
+either way; `ValidateRecords` shares one budget across its rows and counts
+the rows it could not decide as `undetermined`, neither passed nor failed,
+with `ok: false`. A failing union's message is at most 1,000 characters:
+when its branches' reasons do not fit, each is cut to an equal share and a
+short one keeps all of it, so a nested union's decisive reason survives.
+
+**Patterns never run on the caller's thread.** A schema's `pattern` and
+`patternProperties`, and `Assert`'s `matches`/`notMatches`, are regexes the
+caller wrote, run over text the caller chose; a synchronous `RegExp` cannot be
+interrupted, and when JavaScriptCore gives up on a backtracking match it says
+"no match". So each tool asks every pattern question first, answers them all
+in one `@crewhaus/tool-safety` regex worker under a five-second deadline, and
+then evaluates with the answers (a schema whose later patterns depend on
+earlier answers, through `if` or a union, takes a few rounds). A pattern the
+screen refuses, because it backtracks exponentially (`(a+)+`, `(\w+\s?)*`) or
+is past 10,000 characters, makes the schema malformed (`schemaValid: false`),
+and fails an `Assert` check as an invalid regex does. One that cannot be run
+to an answer (the deadline, the engine giving up, which includes a no-match
+slower than 100 ms) leaves the value `undetermined`, never invalid or valid,
+and an `Assert` check `undetermined` and not ok. `Branch`, `DecisionTable`,
+`RuleScore`, `LeadAssign`, `SequenceRun` and `ErrorClassify` in
+`@crewhaus/tool-flow` read the same answers. A library caller of `runChecks` or `validateValue` with no
+answers gets a bounded fallback on its own thread: the same screen, at most
+64 KiB of input per pattern, and a give-up read as undetermined.
+
 ## The formats
 
 Each format is a stated subset, not a full grammar, and each rejects the grey

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export declare const validateEnum: RegisteredTool;
 export declare const validateFormat: RegisteredTool;
 export declare const validateUniqueKeys: RegisteredTool;
 export declare const validateReferences: RegisteredTool;
+/** The most characters the paths of the changes SchemaDiff lists may add up to. */
+export declare const MAX_LISTED_PATH_CHARS = 1000000;
 export declare const schemaDiff: RegisteredTool;
 export declare const schemaSummarize: RegisteredTool;
 /** Every tool this package registers, in the order a catalog should list them. */
@@ -24,4 +26,10 @@ export declare const SCHEMA_TOOLS: ReadonlyArray<RegisteredTool>;
  * find it missing, or subtly different, in the other. There is one
  * vocabulary and one evaluator, and this is where it lives.
  */
-export { ASSERT_OPS, type AssertOp, type AssertReport, type Check, type CheckResult, checkRequired, runChecks, } from "./lib/assert";
+export { ASSERT_OPS, type AssertOp, type AssertReport, type Check, type CheckResult, askCheckPatterns, checkRequired, checksVerdict, runChecks, } from "./lib/assert";
+/**
+ * Caller patterns answered in the worker, for the other packages whose
+ * synchronous evaluators run a regex someone else wrote: ask, resolve once,
+ * then read (see `./lib/regex-answers`).
+ */
+export { _setRegexAnswersSessionForTest, CALLER_PATTERN_DEADLINE_MS, MAX_PATTERN_QUESTIONS, type RegexAnswer, RegexAnswers, type RegexRunContext, regexRunContext, testPatternSync, withRegexAnswers, } from "./lib/regex-answers";

package/dist/index.js

@@ -18,12 +18,13 @@
  */
 import { buildTool } from "@crewhaus/tool-builder";
 import { z } from "zod";
-import { ASSERT_OPS, checkRequired, runChecks } from "./lib/assert";
+import { ASSERT_OPS, askCheckPatterns, checkRequired, runChecks } from "./lib/assert";
 import { compareValues, firstDifference } from "./lib/compare";
 import { FORMAT_NAMES, checkFormat, matchingFormats } from "./lib/formats";
 import { inferSchema } from "./lib/infer";
 import { checkSchemaShape, validateValue } from "./lib/jsonschema";
 import { checkReferences, collectFieldValues, findDuplicates, validateRecords as validateRecordsFn, } from "./lib/records";
+import { RegexAnswers, regexRunContext, withRegexAnswers } from "./lib/regex-answers";
 import { diffSchemas } from "./lib/schemadiff";
 import { closestMatch } from "./lib/suggest";
 import { renderFieldTable, summarizeSchema } from "./lib/summarize";
@@ -83,14 +84,43 @@ export const jsonSchemaValidate = buildTool({
         .refine(present("value"), { message: "value is required, even when it is null" }),
     readOnly: true,
     concurrencySafe: true,
-    execute: async (input) => {
+    execute: async (input, ctx) => {
         const problems = schemaProblemReport(input.schema);
         if (problems !== null)
             return problems;
-        const result = validateValue(input.value, input.schema, {
-            assertFormat: input.assertFormat ?? false,
-            maxErrors: input.maxErrors ?? 100,
-        });
+        // The schema's patterns run in the worker, never on this thread; the
+        // walk runs once to learn what they are asked, and again with answers.
+        const run = await withRegexAnswers((regex) => {
+            const pass = validateValue(input.value, input.schema, {
+                assertFormat: input.assertFormat ?? false,
+                maxErrors: input.maxErrors ?? 100,
+                regex,
+            });
+            if (pass.workExhausted)
+                regex.discardPending();
+            return pass;
+        }, regexRunContext(ctx));
+        if ("undetermined" in run) {
+            return json({
+                valid: null,
+                undetermined: true,
+                reason: run.undetermined,
+                errorsBeforeStopping: [],
+            });
+        }
+        const result = run.value;
+        if (result.undetermined !== null) {
+            // Not a verdict either way: `valid` is null, never false or true.
+            return json({
+                valid: null,
+                undetermined: true,
+                reason: result.undetermined,
+                errorsBeforeStopping: result.errors,
+                ...(result.unsupportedKeywords.length > 0
+                    ? { unsupportedKeywords: result.unsupportedKeywords }
+                    : {}),
+            });
+        }
         return json({
             valid: result.valid,
             errorCount: result.errors.length,
@@ -161,21 +191,34 @@ export const validateRecords = buildTool({
     }),
     readOnly: true,
     concurrencySafe: true,
-    execute: async (input) => {
+    execute: async (input, ctx) => {
         const problems = schemaProblemReport(input.schema);
         if (problems !== null)
             return problems;
-        const report = validateRecordsFn(input.records, input.schema, {
+        const run = await withRegexAnswers((regex) => validateRecordsFn(input.records, input.schema, {
             assertFormat: input.assertFormat ?? false,
             maxErrorsPerRow: input.maxErrorsPerRow ?? 10,
             maxFailedRows: input.maxFailedRows ?? 50,
             idField: input.idField ?? null,
-        });
+            regex,
+        }), regexRunContext(ctx));
+        if ("undetermined" in run) {
+            return json({
+                ok: false,
+                total: input.records.length,
+                undetermined: input.records.length,
+                reason: run.undetermined,
+            });
+        }
+        const report = run.value;
         const head = {
             ok: report.ok,
             total: report.total,
             passed: report.passed,
             failed: report.failed,
+            ...(report.undetermined > 0
+                ? { undetermined: report.undetermined, undeterminedFrom: report.undeterminedFrom }
+                : {}),
             topIssues: report.topIssues.slice(0, 20),
             ...(report.unsupportedKeywords.length > 0
                 ? { unsupportedKeywords: report.unsupportedKeywords }
@@ -213,13 +256,20 @@ export const assert = buildTool({
         .refine(present("value"), { message: "value is required, even when it is null" }),
     readOnly: true,
     concurrencySafe: true,
-    execute: async (input) => {
-        const report = runChecks(input.value, input.checks);
+    execute: async (input, ctx) => {
+        const checks = input.checks;
+        // `matches` patterns run in the worker, before the checks are read.
+        const regex = new RegexAnswers();
+        askCheckPatterns(input.value, checks, regex);
+        await regex.resolve(regexRunContext(ctx));
+        const report = runChecks(input.value, checks, { regex });
+        const undetermined = report.undetermined > 0 ? { undetermined: report.undetermined } : {};
         if (input.failuresOnly === true) {
             return json({
                 ok: report.ok,
                 passed: report.passed,
                 failed: report.failed,
+                ...undetermined,
                 failures: report.failures,
             });
         }
@@ -227,6 +277,7 @@ export const assert = buildTool({
             ok: report.ok,
             passed: report.passed,
             failed: report.failed,
+            ...undetermined,
             results: report.results,
         });
     },
@@ -586,6 +637,8 @@ export const validateReferences = buildTool({
         });
     },
 });
+/** The most characters the paths of the changes SchemaDiff lists may add up to. */
+export const MAX_LISTED_PATH_CHARS = 1_000_000;
 export const schemaDiff = buildTool({
     name: "SchemaDiff",
     description: "Diff two JSON Schemas and classify every change as compatible, breaking or undecidable for a reader of the data. Use before shipping a contract change, to answer whether existing payloads still validate — an undecidable change is reported as such, never rounded to safe.",
@@ -604,12 +657,32 @@ export const schemaDiff = buildTool({
         const changes = input.breakingOnly === true
             ? result.changes.filter((c) => c.compat !== "compatible")
             : result.changes;
+        // Every change carries its full path, so one long name high in a schema
+        // is repeated in every change below it: a result the square of the
+        // input. The changes are listed until their paths reach the cap, and
+        // the rest are counted; the verdict and the counts cover them all.
+        const listed = [];
+        let pathChars = 0;
+        for (const change of changes) {
+            pathChars += change.path.length;
+            if (pathChars > MAX_LISTED_PATH_CHARS)
+                break;
+            listed.push(change);
+        }
+        const omitted = changes.length - listed.length;
         return json({
             identical: result.identical,
             verdict: result.verdict,
             backwardCompatible: result.backwardCompatible,
             counts: result.counts,
-            changes,
+            changes: listed,
+            ...(omitted > 0
+                ? {
+                    truncated: true,
+                    omitted,
+                    detail: `${omitted} of the ${changes.length} changes are not listed: their paths would pass ${MAX_LISTED_PATH_CHARS} characters. The verdict and counts cover every change; diff a nested part on its own to list the rest`,
+                }
+                : {}),
             note: "backward compatible means every value valid under `before` is still valid under `after`",
         });
     },
@@ -675,4 +748,10 @@ export const SCHEMA_TOOLS = Object.freeze([
  * find it missing, or subtly different, in the other. There is one
  * vocabulary and one evaluator, and this is where it lives.
  */
-export { ASSERT_OPS, checkRequired, runChecks, } from "./lib/assert";
+export { ASSERT_OPS, askCheckPatterns, checkRequired, checksVerdict, runChecks, } from "./lib/assert";
+/**
+ * Caller patterns answered in the worker, for the other packages whose
+ * synchronous evaluators run a regex someone else wrote: ask, resolve once,
+ * then read (see `./lib/regex-answers`).
+ */
+export { _setRegexAnswersSessionForTest, CALLER_PATTERN_DEADLINE_MS, MAX_PATTERN_QUESTIONS, RegexAnswers, regexRunContext, testPatternSync, withRegexAnswers, } from "./lib/regex-answers";

package/dist/lib/assert.d.ts

@@ -1,3 +1,4 @@
+import { type RegexAnswers } from "./regex-answers";
 /** Every comparison {@link runChecks} understands. */
 export declare const ASSERT_OPS: readonly ["equals", "notEquals", "contains", "notContains", "matches", "notMatches", "startsWith", "endsWith", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "exists", "notExists", "isEmpty", "isNotEmpty", "isType", "hasLength", "minLength", "maxLength", "oneOf", "notOneOf", "hasFormat"];
 export type AssertOp = (typeof ASSERT_OPS)[number];
@@ -22,17 +23,34 @@ export type CheckResult = {
     expected: string | null;
     /** Empty when the check passed. */
     reason: string;
+    /**
+     * Set when the check could not be evaluated: its pattern could not be run
+     * to an answer. It is not ok (a gate fails closed), but it did not fail
+     * either, and `reason` says why. Absent on every other check.
+     */
+    undetermined?: true;
 };
 export type AssertReport = {
     ok: boolean;
     passed: number;
+    /** Checks that did not pass, the undetermined ones included. */
     failed: number;
+    /** Of `failed`, the checks that could not be evaluated. */
+    undetermined: number;
     results: CheckResult[];
     /** Just the failures, for a caller that only wants to print those. */
     failures: CheckResult[];
 };
 /** Empty means: absent, null, the empty string, an empty array or an empty object. */
 export declare function isEmptyValue(value: unknown): boolean;
+/**
+ * Ask `answers` about every pattern `checks` will test against `value`, so
+ * one {@link RegexAnswers.resolve} settles them all before
+ * {@link runChecks} reads them. A caller evaluating several check lists
+ * against one value (a table's rows, a router's arms) asks for every list
+ * first, then resolves once.
+ */
+export declare function askCheckPatterns(value: unknown, checks: ReadonlyArray<Check>, answers: RegexAnswers): void;
 /**
  * Run every check against `value` and report which held.
  *
@@ -44,8 +62,25 @@ export declare function isEmptyValue(value: unknown): boolean;
  * A malformed check (a bad regex, a non-numeric bound) fails that check with
  * an explanatory reason rather than throwing, so one typo cannot take down a
  * whole gate.
+ *
+ * `matches` and `notMatches` read their answers from `options.regex`, which
+ * the calling tool resolved in the worker (see {@link askCheckPatterns});
+ * without it they fall back to a bounded run on this thread. A check whose
+ * pattern could not be run to an answer is not ok and carries
+ * `undetermined: true`; its reason says so whatever `message` the check set.
+ */
+export declare function runChecks(value: unknown, checks: ReadonlyArray<Check>, options?: {
+    readonly regex?: RegexAnswers;
+}): AssertReport;
+/**
+ * What a check list says as a whole, three ways. Under `all`, a check that
+ * definitely failed decides it (`fail`); otherwise an undetermined one leaves
+ * it `undetermined`. Under `any`, a check that passed decides it (`pass`);
+ * otherwise an undetermined one leaves it `undetermined`. A router or a
+ * scorer that reads `report.ok` alone would take an undetermined check for a
+ * miss and fall through to the next arm or the default.
  */
-export declare function runChecks(value: unknown, checks: Check[]): AssertReport;
+export declare function checksVerdict(report: AssertReport, mode?: "all" | "any"): "pass" | "fail" | "undetermined";
 /**
  * Which of `paths` are present and non-empty in `value`, and which are not.
  * "Present" means the path resolves; "non-empty" applies