@reticlehq/server 3.9.0 → 3.10.1

package/dist/features/compare/outside/value-dictionary.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Values the app compares its fields with, read from the scripts it serves. No instrumentation:
+ * the page HTML and its scripts are fetched the way a browser fetches them.
+ *
+ * In `values.route === "progress"` the field named route gets "progress". `switch (x.route)` cases
+ * and `["a", "b"].includes(x.route)` give their literals the same way. An explorer that does not
+ * know this never types the value, and the branch behind it (a conditional step, a special mode)
+ * stays unseen. A field matches a name when its folded name equals the name, or ends with a name of
+ * three or more characters.
+ *
+ * The same scripts give the url parameters the page reads and the values it compares each with
+ * (`urlParamValues`).
+ */
+/** Values by folded name. */
+export type ValueDictionary = ReadonlyMap<string, readonly string[]>;
+/** The most script files read for one page. */
+export declare const MAX_SCRIPTS = 40;
+/** A name, lowercase, letters and digits only. */
+export declare const foldName: (name: string) => string;
+export declare const scriptSources: (html: string) => string[];
+export declare const chunkImports: (js: string) => string[];
+/** `[name, literal]` for each comparison of a named value with a string literal, in source order. */
+export declare function comparedLiterals(js: string): [string, string][];
+export declare function buildDictionary(pairs: readonly (readonly [string, string])[]): ValueDictionary;
+/** The values for a field with this name, or none. */
+export declare function magicValues(dictionary: ValueDictionary, name: string): readonly string[];
+/**
+ * `[parameter, literal]` for each url parameter the page reads, such as
+ * `new URLSearchParams(location.search).get("scenario")`, with each literal compared in the code
+ * after that read. A state behind the url (`?scenario=deferred`) is then a start page of its own.
+ */
+export declare function urlParamValues(js: string): [string, string][];
+/**
+ * The keys the app listens for, in source order, each once: the literals its scripts compare a key
+ * event's `key` or `code` with, then its shortcut strings. A build that answers to the wrong key
+ * shows a difference only when that key is pressed.
+ */
+export declare function appKeys(js: string): string[];
+/** What the scripts of a page tell the plan. */
+export interface ScriptHints {
+    dictionary: ValueDictionary;
+    /** The keys the app listens for (`appKeys`), each once. */
+    keys: readonly string[];
+    /** The values each url parameter is compared with, in source order, each value once. */
+    urlParams: ReadonlyMap<string, readonly string[]>;
+}
+/**
+ * Fetch the page and its scripts, following script src and imported chunks, up to `MAX_SCRIPTS`
+ * files. `fetchText` answers undefined for a file it could not get; that file adds nothing.
+ */
+export declare function harvestScripts(pageUrl: string, fetchText: (url: string) => Promise<string | undefined>): Promise<ScriptHints>;

package/dist/features/compare/outside/value-dictionary.js

@@ -0,0 +1,227 @@
+/**
+ * Values the app compares its fields with, read from the scripts it serves. No instrumentation:
+ * the page HTML and its scripts are fetched the way a browser fetches them.
+ *
+ * In `values.route === "progress"` the field named route gets "progress". `switch (x.route)` cases
+ * and `["a", "b"].includes(x.route)` give their literals the same way. An explorer that does not
+ * know this never types the value, and the branch behind it (a conditional step, a special mode)
+ * stays unseen. A field matches a name when its folded name equals the name, or ends with a name of
+ * three or more characters.
+ *
+ * The same scripts give the url parameters the page reads and the values it compares each with
+ * (`urlParamValues`).
+ */
+/** The most script files read for one page. */
+export const MAX_SCRIPTS = 40;
+/** The most values kept for one name. */
+const MAX_VALUES = 4;
+/** The longest literal kept: a longer one is text, not a value a field is compared with. */
+const MAX_LITERAL = 40;
+/** A name this short matches only exactly: `id` must not match every field that ends in "id". */
+const MIN_SUFFIX = 3;
+const SCRIPT_SRC = /<script[^>]+src=["']([^"']+)["']/g;
+/** A module path: a built chunk, or a source module a dev server serves, with an optional query. */
+const CHUNK = /["'](\.{0,2}\/[\w./@-]+\.(?:m?js|jsx|tsx?)(?:\?[^"']*)?)["']/g;
+/** Library code and the dev server's own client: they hold no comparison of the app's fields. */
+const NOT_APP = /\/node_modules\/|^\/@/;
+const NAME_THEN_LITERAL = /\.([A-Za-z_$][\w$]*)\s*[!=]==?\s*["']([^"'\\]{1,40})["']/g;
+const LITERAL_THEN_NAME = /["']([^"'\\]{1,40})["']\s*[!=]==?\s*[\w$.]*\.([A-Za-z_$][\w$]*)\b/g;
+/** `switch (x.name) { ... }`: the body, up to a bound, holds the cases. */
+const SWITCH = /switch\s*\(\s*[\w$.]*\.([A-Za-z_$][\w$]*)\s*\)\s*\{([\s\S]{0,3000}?)\}/g;
+const CASE = /case\s*["']([^"'\\]{1,40})["']\s*:/g;
+/**
+ * `["a", "b"].includes(x.name)`. Each repeated item must end in a comma and the count is bounded, so
+ * there is one way to match a list: an optional comma inside a repeated group backtracked exponentially
+ * on a hostile script, and compare reads scripts from any page.
+ */
+const INCLUDES = /\[\s*((?:["'][^"'\\]{1,40}["']\s*,\s*){0,30}["'][^"'\\]{1,40}["'])\s*,?\s*\]\.includes\(\s*[\w$.]*\.([A-Za-z_$][\w$]*)\s*\)/g;
+/**
+ * What `typeof` returns. A `typeof x.name === "string"` check compares a type, not a value the app expects in
+ * the field; bundled libraries are full of them, and they gave a field named Name the value "string".
+ */
+const TYPE_NAMES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'object',
+    'function',
+    'undefined',
+    'symbol',
+    'bigint',
+]);
+const QUOTED = /["']([^"'\\]{1,40})["']/g;
+/** A name, lowercase, letters and digits only. */
+export const foldName = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+export const scriptSources = (html) => [...html.matchAll(SCRIPT_SRC)].map((m) => m[1] ?? '').filter((src) => src.length > 0);
+export const chunkImports = (js) => [...js.matchAll(CHUNK)]
+    .map((m) => m[1] ?? '')
+    .filter((src) => src.length > 0 && !NOT_APP.test(src));
+/** `[name, literal]` for each comparison of a named value with a string literal, in source order. */
+export function comparedLiterals(js) {
+    const found = [];
+    for (const m of js.matchAll(NAME_THEN_LITERAL)) {
+        found.push({ at: m.index, pair: [m[1] ?? '', m[2] ?? ''] });
+    }
+    for (const m of js.matchAll(LITERAL_THEN_NAME)) {
+        found.push({ at: m.index, pair: [m[2] ?? '', m[1] ?? ''] });
+    }
+    for (const m of js.matchAll(SWITCH)) {
+        for (const c of (m[2] ?? '').matchAll(CASE)) {
+            found.push({ at: m.index + c.index, pair: [m[1] ?? '', c[1] ?? ''] });
+        }
+    }
+    for (const m of js.matchAll(INCLUDES)) {
+        for (const v of (m[1] ?? '').matchAll(QUOTED)) {
+            found.push({ at: m.index + v.index, pair: [m[2] ?? '', v[1] ?? ''] });
+        }
+    }
+    return found
+        .filter((f) => !TYPE_NAMES.has(f.pair[1]))
+        .sort((a, b) => a.at - b.at)
+        .map((f) => f.pair);
+}
+export function buildDictionary(pairs) {
+    const out = new Map();
+    for (const [name, value] of pairs) {
+        const key = foldName(name);
+        const values = out.get(key) ?? [];
+        if (key.length > 0 &&
+            value.length > 0 &&
+            value.length <= MAX_LITERAL &&
+            !values.includes(value)) {
+            out.set(key, [...values, value].slice(0, MAX_VALUES));
+        }
+    }
+    return out;
+}
+/** The values for a field with this name, or none. */
+export function magicValues(dictionary, name) {
+    const folded = foldName(name);
+    if (0 === folded.length) {
+        return [];
+    }
+    const exact = dictionary.get(folded);
+    if (exact !== undefined) {
+        return exact;
+    }
+    for (const [key, values] of dictionary) {
+        if (key.length >= MIN_SUFFIX && folded.endsWith(key)) {
+            return values;
+        }
+    }
+    return [];
+}
+/** `src` as an absolute url against `base`, or `src` when it cannot be resolved. */
+function resolve(src, base) {
+    try {
+        return new URL(src, base).href;
+    }
+    catch {
+        return src;
+    }
+}
+/** `.get("name")`: a read of a url parameter when the code before it names the url. */
+const PARAM_GET = /\.get\(\s*["']([A-Za-z_][\w-]{0,30})["']\s*\)/g;
+const NEAR_URL = /URLSearchParams|searchParams|location/;
+/** How far before a `.get(...)` the url must be named. */
+const URL_BEFORE_CHARS = 200;
+/** How far after a `.get(...)` the compared literals are read. Minified code renames the variable. */
+const PARAM_AFTER_CHARS = 3000;
+const PARAM_LITERAL = /[!=]==?\s*["']([\w-]{1,30})["']|["']([\w-]{1,30})["']\s*[!=]==|case\s*["']([\w-]{1,30})["']\s*:/g;
+/**
+ * `[parameter, literal]` for each url parameter the page reads, such as
+ * `new URLSearchParams(location.search).get("scenario")`, with each literal compared in the code
+ * after that read. A state behind the url (`?scenario=deferred`) is then a start page of its own.
+ */
+export function urlParamValues(js) {
+    const out = [];
+    for (const m of js.matchAll(PARAM_GET)) {
+        const before = js.slice(Math.max(0, m.index - URL_BEFORE_CHARS), m.index);
+        if (!NEAR_URL.test(before)) {
+            continue;
+        }
+        for (const v of js.slice(m.index, m.index + PARAM_AFTER_CHARS).matchAll(PARAM_LITERAL)) {
+            out.push([m[1] ?? '', v[1] ?? v[2] ?? v[3] ?? '']);
+        }
+    }
+    return out;
+}
+/** The names a key event's key is read by: `e.key === "k"`, `e.code === "Slash"`. */
+const KEY_NAMES = new Set(['key', 'code']);
+/** A longer literal compared with a key is text, not a key name. */
+const MAX_KEY_CHARS = 12;
+/** A shortcut string in a hotkey table: "mod+k", "ctrl+shift+p". */
+const SHORTCUT = /["']((?:(?:mod|ctrl|control|cmd|command|meta|alt|option|shift)\+){1,3}[A-Za-z0-9/?.,;=-])["']/gi;
+const SHORTCUT_JOIN = '+';
+/** "mod" is Meta on a Mac and Control elsewhere, so a "mod" shortcut is pressed both ways. */
+const MOD = 'mod';
+const MOD_KEYS = ['Meta', 'Control'];
+const MODIFIER_KEY = {
+    ctrl: 'Control',
+    control: 'Control',
+    cmd: 'Meta',
+    command: 'Meta',
+    meta: 'Meta',
+    alt: 'Alt',
+    option: 'Alt',
+    shift: 'Shift',
+};
+/** The key names of one shortcut string, each modifier as the key a press names. */
+function shortcutPresses(shortcut) {
+    const parts = shortcut.split(SHORTCUT_JOIN);
+    const last = parts.at(-1) ?? '';
+    const mods = parts.slice(0, -1).map((m) => m.toLowerCase());
+    const each = mods.includes(MOD) ? MOD_KEYS : [undefined];
+    return each.map((mod) => [...mods.map((m) => (MOD === m ? (mod ?? '') : (MODIFIER_KEY[m] ?? m))), last].join(SHORTCUT_JOIN));
+}
+/**
+ * The keys the app listens for, in source order, each once: the literals its scripts compare a key
+ * event's `key` or `code` with, then its shortcut strings. A build that answers to the wrong key
+ * shows a difference only when that key is pressed.
+ */
+export function appKeys(js) {
+    const out = new Set();
+    for (const [name, value] of comparedLiterals(js)) {
+        if (KEY_NAMES.has(foldName(name)) && value.length <= MAX_KEY_CHARS) {
+            out.add(value);
+        }
+    }
+    for (const m of js.matchAll(SHORTCUT)) {
+        for (const press of shortcutPresses(m[1] ?? '')) {
+            out.add(press);
+        }
+    }
+    return [...out];
+}
+/**
+ * Fetch the page and its scripts, following script src and imported chunks, up to `MAX_SCRIPTS`
+ * files. `fetchText` answers undefined for a file it could not get; that file adds nothing.
+ */
+export async function harvestScripts(pageUrl, fetchText) {
+    const html = (await fetchText(pageUrl)) ?? '';
+    const queue = scriptSources(html).map((src) => resolve(src, pageUrl));
+    const seen = new Set();
+    const pairs = [];
+    const urlParams = new Map();
+    const keys = new Set();
+    while (queue.length > 0 && seen.size < MAX_SCRIPTS) {
+        const url = queue.shift() ?? '';
+        if (seen.has(url)) {
+            continue;
+        }
+        seen.add(url);
+        const js = (await fetchText(url)) ?? '';
+        queue.push(...chunkImports(js).map((src) => resolve(src, url)));
+        pairs.push(...comparedLiterals(js));
+        for (const key of appKeys(js)) {
+            keys.add(key);
+        }
+        for (const [param, value] of urlParamValues(js)) {
+            const values = urlParams.get(param) ?? [];
+            if (!values.includes(value)) {
+                urlParams.set(param, [...values, value]);
+            }
+        }
+    }
+    return { dictionary: buildDictionary(pairs), keys: [...keys], urlParams };
+}

package/dist/features/compare/visible-content.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What a person can read and use on a page, from its accessibility tree.
+ *
+ * Two builds of one app are compared on this, so it keeps only what a person sees: the accessible
+ * name, the value, the element's own text, and the checked, selected, disabled, expanded and pressed
+ * states. Refs, layout, test ids, source locations and component names change between builds with
+ * nothing visible changing, so they are removed. Focus is removed too: it moves with timing.
+ *
+ * One line for each element that shows something, in page order. Case is folded, spacing is folded,
+ * and an ellipsis is dropped, because a cut at another width is not a change in content.
+ */
+/** The visible content of an accessibility tree, one line for each element that shows something. */
+export declare function visibleLines(tree: string): string[];
+/**
+ * The visible content with the role of each control and structure element kept: `cell`,
+ * `cell john doe`, `button save`. Text alone cannot see a change of structure: an empty cell that
+ * keeps the columns of a table aligned, a button that became plain text, or a checkbox removed while
+ * its label stays. A line with a text-only role is its text, and it is dropped when it has no text.
+ */
+export declare function structureLines(tree: string): string[];

package/dist/features/compare/visible-content.js

@@ -0,0 +1,125 @@
+/**
+ * What a person can read and use on a page, from its accessibility tree.
+ *
+ * Two builds of one app are compared on this, so it keeps only what a person sees: the accessible
+ * name, the value, the element's own text, and the checked, selected, disabled, expanded and pressed
+ * states. Refs, layout, test ids, source locations and component names change between builds with
+ * nothing visible changing, so they are removed. Focus is removed too: it moves with timing.
+ *
+ * One line for each element that shows something, in page order. Case is folded, spacing is folded,
+ * and an ellipsis is dropped, because a cut at another width is not a change in content.
+ */
+/** The accessible name: the first quoted part after the role, up to the next field. */
+const NAME = /^\s*- \S+ "(.*?)"(?= \(ref=| \[|$)/;
+/** A quoted field, up to the next field. */
+const quotedField = (field) => new RegExp(`\\[${field}="(.*?)"\\](?= \\[| \\(|$)`);
+const VALUE = quotedField('value');
+const OWN_TEXT = quotedField('text');
+/** The state group the snapshot writes, such as `[disabled,checked]`. */
+const STATES = /\[((?:[a-z]+)(?:,[a-z]+)*)\]/g;
+/** The states a person can see on a control. */
+const SHOWN_STATES = new Set([
+    'checked',
+    'selected',
+    'disabled',
+    'expanded',
+    'pressed',
+]);
+/** A state the snapshot writes that moves with timing, not with the build. */
+const UNSHOWN_STATE = 'focused';
+const ELLIPSIS = '…';
+const VALUE_JOIN = ' = ';
+const fold = (text) => text.toLowerCase().replaceAll(ELLIPSIS, '').split(/\s+/).filter(Boolean).join(' ');
+function statesOf(line) {
+    const found = [];
+    for (const match of line.matchAll(STATES)) {
+        const group = (match[1] ?? '').split(',');
+        // A group with any word that is not a state is another field, for example `[grid]`.
+        if (group.every((word) => SHOWN_STATES.has(word) || UNSHOWN_STATE === word)) {
+            found.push(...group.filter((word) => SHOWN_STATES.has(word)));
+        }
+    }
+    return found;
+}
+/** The visible line for one tree line, or '' when the element shows nothing. */
+function visibleLine(line) {
+    const name = fold(NAME.exec(line)?.[1] ?? '');
+    const value = fold(VALUE.exec(line)?.[1] ?? '');
+    const text = fold(OWN_TEXT.exec(line)?.[1] ?? '');
+    const states = statesOf(line);
+    const parts = [];
+    if (name.length > 0) {
+        parts.push(name);
+    }
+    if (text.length > 0) {
+        parts.push(text);
+    }
+    let out = parts.join(' ');
+    if (value.length > 0) {
+        out = out.length > 0 ? `${out}${VALUE_JOIN}${value}` : value;
+    }
+    if (states.length > 0) {
+        const shown = `[${states.join(',')}]`;
+        out = out.length > 0 ? `${out} ${shown}` : shown;
+    }
+    return out;
+}
+/** The visible content of an accessibility tree, one line for each element that shows something. */
+export function visibleLines(tree) {
+    return tree
+        .split('\n')
+        .map(visibleLine)
+        .filter((line) => line.length > 0);
+}
+/** The role at the start of a tree line. */
+const ROLE = /^\s*- ([\w-]+)/;
+/**
+ * Roles that only hold text. A correct build can show the same words in another container, so a
+ * line with one of these roles is compared as its text alone.
+ */
+const TEXT_ROLES = new Set([
+    'generic',
+    'text',
+    'none',
+    'presentation',
+    'group',
+    'paragraph',
+    'status',
+    'note',
+    'log',
+    'strong',
+    'emphasis',
+    'code',
+    'blockquote',
+    'caption',
+    'label',
+    'time',
+    'mark',
+    'subscript',
+    'superscript',
+    'deletion',
+    'insertion',
+]);
+/**
+ * The visible content with the role of each control and structure element kept: `cell`,
+ * `cell john doe`, `button save`. Text alone cannot see a change of structure: an empty cell that
+ * keeps the columns of a table aligned, a button that became plain text, or a checkbox removed while
+ * its label stays. A line with a text-only role is its text, and it is dropped when it has no text.
+ */
+export function structureLines(tree) {
+    const out = [];
+    for (const line of tree.split('\n')) {
+        const role = ROLE.exec(line)?.[1];
+        if (role === undefined) {
+            continue;
+        }
+        const shown = visibleLine(line);
+        if (!TEXT_ROLES.has(role)) {
+            out.push(shown.length > 0 ? `${role} ${shown}` : role);
+        }
+        else if (shown.length > 0) {
+            out.push(shown);
+        }
+    }
+    return out;
+}

package/dist/features/crawl/crawl-empty.js

@@ -7,8 +7,9 @@
  * the zero carry its own diagnosis rather than guess at a cause.
  */
 export function crawlEmptyNote(outcome) {
-    if (outcome.stepsRun > 0)
+    if (outcome.stepsRun > 0) {
         return undefined;
+    }
     if (outcome.maxSteps <= 0) {
         return 'nothing was clicked because maxSteps is 0 — raise it to crawl at all';
     }

package/dist/features/crawl/crawl-exhaustive.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `reticle_crawl { exhaustive: true }` — explore every reachable state, drive every write's failure
+ * path and the edge cases of every state, take the code coverage, fold all of it into the ledger,
+ * and say what is left.
+ *
+ * It answers in crawl's own shape, so every caller that reads a crawl keeps working, and adds one
+ * `exhaustive` block with what only this mode knows.
+ */
+import type { FileSystemPort } from '../../memory/project/fs/fs-port.js';
+import { type RawScriptCoverage } from '../exhaust/code-coverage.js';
+import { type ExploreReport } from '../exhaust/explorer.js';
+import { type PortSession } from '../exhaust/session-port.js';
+/** The share of a GIVEN budget kept back for edge cases. What exploring leaves goes to them too. */
+export declare const EDGE_SHARE = 0.25;
+/**
+ * With no budget given, each phase gets what the crawl found, up to a ceiling. Exploring stops on
+ * its own when no state is left; the ceiling only bounds an app too large to finish. A fixed 400,
+ * split by share, ran out on bench-app before the edge drive reached its third page.
+ */
+export declare const ExhaustBudget: {
+    readonly EXPLORE_CEILING: 600;
+    /** A failure path replays the write's path, breaks it and fires it. */
+    readonly FAILURE_PER_WRITE: 12;
+    readonly FAILURE_CEILING: 150;
+    /** Enough for the first few probes of one control, each a replay and a few presses. */
+    readonly EDGE_PER_CONTROL: 15;
+    readonly EDGE_CEILING: 450;
+};
+/** The failure and edge budgets for what exploring found. */
+export declare function scaledBudget(found: Pick<ExploreReport, 'surfaces' | 'writes'>): {
+    failure: number;
+    edges: number;
+};
+export declare function runExhaustive(input: {
+    sessions: {
+        get(id: string): PortSession | undefined;
+    };
+    session: PortSession;
+    startUrl: string;
+    /** A fixed budget, split by share. Absent: each phase gets what the crawl found (`scaledBudget`). */
+    maxActions?: number;
+    settleMs: number;
+    /** What to type into a field, given the page it is on — a secret is only for its own origin. */
+    fillValue: (label: string, pageUrl: string) => string;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    setMocks?: (sessionUrl: string, rules: {
+        urlContains: string;
+        method?: string;
+        abort?: boolean;
+    }[]) => Promise<boolean>;
+    takeCode?: (sessionUrl: string) => Promise<readonly RawScriptCoverage[] | undefined>;
+    fs: FileSystemPort;
+    reticleRoot: string;
+}): Promise<Record<string, unknown>>;

package/dist/features/crawl/crawl-exhaustive.js

@@ -0,0 +1,138 @@
+/**
+ * `reticle_crawl { exhaustive: true }` — explore every reachable state, drive every write's failure
+ * path and the edge cases of every state, take the code coverage, fold all of it into the ledger,
+ * and say what is left.
+ *
+ * It answers in crawl's own shape, so every caller that reads a crawl keeps working, and adds one
+ * `exhaustive` block with what only this mode knows.
+ */
+import { BehaviourFindingKind } from '@reticlehq/core';
+import { emptyCodeCoverage, foldCodeCoverage, } from '../exhaust/code-coverage.js';
+import { driveEdges } from '../exhaust/edges/edge-drive.js';
+import { explore } from '../exhaust/explorer.js';
+import { driveFailureBranches } from '../exhaust/failure-branches.js';
+import { failureFindings } from '../exhaust/invariants.js';
+import { LedgerStore, levelsOf, regressions } from '../exhaust/ledger.js';
+import { sessionPort } from '../exhaust/session-port.js';
+/** The share of a GIVEN budget kept back for failure paths, so exploring cannot starve them. */
+const FAILURE_SHARE = 0.25;
+/** The share of a GIVEN budget kept back for edge cases. What exploring leaves goes to them too. */
+export const EDGE_SHARE = 0.25;
+/**
+ * With no budget given, each phase gets what the crawl found, up to a ceiling. Exploring stops on
+ * its own when no state is left; the ceiling only bounds an app too large to finish. A fixed 400,
+ * split by share, ran out on bench-app before the edge drive reached its third page.
+ */
+export const ExhaustBudget = {
+    EXPLORE_CEILING: 600,
+    /** A failure path replays the write's path, breaks it and fires it. */
+    FAILURE_PER_WRITE: 12,
+    FAILURE_CEILING: 150,
+    /** Enough for the first few probes of one control, each a replay and a few presses. */
+    EDGE_PER_CONTROL: 15,
+    EDGE_CEILING: 450,
+};
+/** The failure and edge budgets for what exploring found. */
+export function scaledBudget(found) {
+    const controls = new Set(found.surfaces.flatMap((s) => [...s.requests, ...s.fields, ...s.inert]));
+    return {
+        failure: Math.min(ExhaustBudget.FAILURE_CEILING, ExhaustBudget.FAILURE_PER_WRITE * found.writes.length),
+        edges: Math.min(ExhaustBudget.EDGE_CEILING, ExhaustBudget.EDGE_PER_CONTROL * controls.size),
+    };
+}
+export async function runExhaustive(input) {
+    const port = sessionPort({
+        sessions: input.sessions,
+        start: input.session,
+        startUrl: input.startUrl,
+        settleMs: input.settleMs,
+        now: input.now,
+        sleep: input.sleep,
+        ...(input.setMocks === undefined ? {} : { setMocks: input.setMocks }),
+    });
+    const given = input.maxActions;
+    const exploreBudget = given === undefined
+        ? ExhaustBudget.EXPLORE_CEILING
+        : given - Math.floor(given * FAILURE_SHARE) - Math.floor(given * EDGE_SHARE);
+    const report = await explore(port, {
+        maxActions: exploreBudget,
+        fillValue: (label) => input.fillValue(label, port.current().url),
+    });
+    const scaled = scaledBudget(report);
+    const failureBudget = given === undefined ? scaled.failure : Math.floor(given * FAILURE_SHARE);
+    const edgeBudget = given === undefined
+        ? scaled.edges
+        : Math.floor(given * EDGE_SHARE) + Math.max(0, exploreBudget - report.actions);
+    const branches = await driveFailureBranches(port, report.writes, { maxActions: failureBudget });
+    const edges = await driveEdges(port, report.surfaces, {
+        maxActions: edgeBudget,
+        now: input.now,
+        known: report.anomalies.map((a) => `${a.control}\n${a.kind}`),
+    });
+    const take = await input.takeCode?.(port.current().url);
+    const ledger = await new LedgerStore(input.fs, input.reticleRoot).merge({
+        routes: { reached: report.routes },
+        controls: { seen: report.seen, touched: report.touched },
+        writes: {
+            seen: report.writes.map((w) => w.key),
+            branched: branches.branched,
+            unhandled: branches.unhandled.map((u) => u.key),
+        },
+        edges: { probed: edges.probed },
+        findings: [...failureFindings(branches, report.writes), ...edges.found.map((f) => f.finding)],
+        ...(take === undefined
+            ? {}
+            : { code: foldCodeCoverage(emptyCodeCoverage(), take), codeTakenAt: input.now() }),
+    });
+    const anomalies = [
+        ...report.anomalies.map((a) => ({ kind: a.kind, ref: '', desc: a.control, detail: a.detail })),
+        ...branches.unhandled.map((u) => ({
+            kind: BehaviourFindingKind.FAILURE_UNHANDLED,
+            ref: '',
+            desc: u.key,
+            detail: u.detail,
+        })),
+        ...edges.found.map((f) => ({
+            kind: f.finding.kind,
+            ref: '',
+            desc: f.control,
+            detail: f.finding.detail,
+            ...(f.finding.source === undefined ? {} : { source: f.finding.source }),
+        })),
+    ];
+    const counts = {};
+    for (const a of anomalies) {
+        counts[a.kind] = (counts[a.kind] ?? 0) + 1;
+    }
+    return {
+        interactiveFound: report.seen.length,
+        stepsRun: report.actions,
+        anomalies,
+        counts,
+        visited: report.touched,
+        truncated: report.frontier > 0 || report.budgetExhausted,
+        exhaustive: {
+            states: report.states,
+            routes: report.routes,
+            frontier: report.frontier,
+            unreachable: report.unreachable,
+            budgetExhausted: report.budgetExhausted,
+            writes: report.writes.map((w) => w.key),
+            failureBranches: branches,
+            edges: {
+                probed: edges.probed.length,
+                findings: edges.found.length,
+                actions: edges.actions,
+                budgetExhausted: edges.budgetExhausted,
+                ...(edges.failed > 0 ? { failed: edges.failed } : {}),
+            },
+            levels: levelsOf(ledger),
+            regressed: regressions(ledger),
+            ...(take === undefined
+                ? {
+                    codeNote: 'code coverage needs a browser Reticle drives (`reticle drive`, or RETICLE_CDP_URL)',
+                }
+                : {}),
+        },
+    };
+}

package/dist/features/crawl/crawl-tools.d.ts

@@ -1,12 +1,19 @@
-import type { ToolDef } from '../../surface/tools/tool-kit.js';
+import type { MockRule } from '../../portal/input/network-mock.js';
+import type { ToolDef, ToolDeps } from '../../surface/tools/tool-kit.js';
 /**
  * The configured secret for a field, only on the origin the crawl started on. The field name comes
  * from whatever page is on screen, so without the check a page on another origin could name an
  * empty textbox after a secret and have the crawl type it in.
  */
+/**
+ * How the exhaustive crawl breaks a request: the driven browser first, then the leased page the
+ * session runs in. `reticle mcp --headless` drives a lease, and the mock tool already reaches it the
+ * same way. Undefined when neither exists, so the crawl says why its failure paths were skipped.
+ */
+export declare function exhaustiveMocks(deps: ToolDeps, sessionId: string): ((url: string, rules: MockRule[]) => Promise<boolean>) | undefined;
 export declare function crawlSecret(startUrl: string, env: Readonly<Record<string, string | undefined>>): (name: string, pageUrl: string) => string | undefined;
 /**
- * The autonomous "smart monkey" tool. Builds on reticle_explore (which only LISTS) by
+ * The autonomous "smart monkey" tool. Builds on the interactive snapshot (which only LISTS) by
  * actually clicking each reachable control and classifying the reaction. DESTRUCTIVE by nature —
  * it drives the app — so it's an explicit, bounded tool, never part of a passive read.
  */