@reticlehq/server 2.0.0

package/dist/crawl/crawl.js

@@ -0,0 +1,106 @@
+import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, DANGEROUS_ACTION_CONFIRM_ARG, EventType, ReticleCommand, } from '@reticlehq/core';
+import { parseInteractive, asRecord, asNumber, asString } from '../tools/tools-helpers.js';
+/** Any buffer event that proves the app reacted to a click (vs a dead/no-op control). */
+function isActivity(e) {
+    return (e.type === EventType.NET_REQUEST ||
+        e.type === EventType.DOM_ADDED ||
+        e.type === EventType.DOM_REMOVED ||
+        e.type === EventType.DOM_ATTR ||
+        e.type === EventType.DOM_TEXT ||
+        e.type === EventType.ROUTE_CHANGE ||
+        e.type === EventType.SIGNAL ||
+        e.type === EventType.ANIM_START ||
+        e.type === EventType.ANIM_END);
+}
+function isConsoleError(e) {
+    return e.type === EventType.CONSOLE_ERROR || e.type === EventType.ERROR_UNCAUGHT;
+}
+function failedRequests(events, floor) {
+    return events.filter((e) => {
+        if (e.type !== EventType.NET_REQUEST)
+            return false;
+        const status = asNumber(e.data['status']);
+        return status !== undefined && status >= floor;
+    });
+}
+/**
+ * The autonomous "smart monkey". Discovers every reachable interactive control once,
+ * then clicks each (bounded by maxSteps) and classifies the reaction into anomalies — console
+ * errors, failed requests, and DEAD controls (dispatched but the app did nothing). Pure
+ * orchestration over a CrawlSession: no browser/Node imports, fully unit-testable with a fake.
+ * Single-pass by design (no re-discovery) so it always terminates and never explodes on navigation.
+ */
+export async function crawl(session, opts, sleep) {
+    const maxSteps = opts.maxSteps ?? CRAWL_DEFAULTS.MAX_STEPS;
+    const settleMs = opts.settleMs ?? CRAWL_DEFAULTS.SETTLE_MS;
+    const snap = await session.command(ReticleCommand.SNAPSHOT, {
+        mode: 'interactive',
+        ...(opts.scope !== undefined ? { scope: opts.scope } : {}),
+    });
+    const tree = snap.ok ? ((snap.result ?? {}).tree ?? '') : '';
+    const items = parseInteractive(tree);
+    const anomalies = [];
+    const visited = [];
+    const counts = { consoleErrors: 0, failedRequests: 0, deadControls: 0 };
+    const seen = new Set();
+    let stepsRun = 0;
+    for (const item of items) {
+        if (stepsRun >= maxSteps)
+            break;
+        if (seen.has(item.desc))
+            continue; // don't re-click an identical control
+        seen.add(item.desc);
+        stepsRun += 1;
+        visited.push(item.desc);
+        const since = session.elapsed();
+        const act = await session.command(ReticleCommand.ACT, {
+            ref: item.ref,
+            action: ActionType.CLICK,
+            args: opts.confirmDangerous === true ? { [DANGEROUS_ACTION_CONFIRM_ARG]: true } : {},
+        });
+        await sleep(settleMs);
+        const events = session.eventsSince(since);
+        const errs = events.filter(isConsoleError);
+        for (const e of errs) {
+            counts.consoleErrors += 1;
+            anomalies.push({
+                kind: CrawlAnomalyKind.CONSOLE_ERROR,
+                ref: item.ref,
+                desc: item.desc,
+                detail: asString(e.data['message']) ?? e.type,
+            });
+        }
+        for (const e of failedRequests(events, CRAWL_DEFAULTS.FAILED_STATUS)) {
+            counts.failedRequests += 1;
+            const method = asString(e.data['method']) ?? '';
+            const url = asString(e.data['url']) ?? '';
+            const status = asNumber(e.data['status']);
+            anomalies.push({
+                kind: CrawlAnomalyKind.FAILED_REQUEST,
+                ref: item.ref,
+                desc: item.desc,
+                detail: `${method} ${url} → ${status ?? ''}`.trim(),
+            });
+        }
+        // DEAD: the click dispatched but the app produced no activity and no error to explain it.
+        const dispatched = asRecord(act.result)['dispatched'] !== false && act.ok;
+        if (dispatched && errs.length === 0 && !events.some(isActivity)) {
+            counts.deadControls += 1;
+            anomalies.push({
+                kind: CrawlAnomalyKind.DEAD_CONTROL,
+                ref: item.ref,
+                desc: item.desc,
+                detail: 'clicked but the app did nothing (no DOM/network/route/signal change)',
+            });
+        }
+    }
+    return {
+        interactiveFound: items.length,
+        stepsRun,
+        anomalies,
+        counts,
+        visited,
+        truncated: items.length > stepsRun,
+    };
+}
+//# sourceMappingURL=crawl.js.map

package/dist/crawl/crawl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crawl.js","sourceRoot":"","sources":["../../src/crawl/crawl.ts"],"names":[],"mappings":"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"}

package/dist/daemon-resilience.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Process-level resilience for the long-running daemon. The daemon serves many agents at once, so a
+ * single stray error must not take the whole fleet down:
+ *
+ *  - unhandledRejection (a fire-and-forget promise nobody awaited — the common case in async WS/pool
+ *    code) → LOG and keep running. One agent's async slip-up can't crash the daemon for everyone.
+ *  - uncaughtException (a synchronous throw escaped all try/catch) → the process state is undefined
+ *    per Node's guidance, so LOG a clear reason and exit cleanly; the next `reticle mcp` respawns a fresh
+ *    daemon, which beats crashing silently or limping along corrupt.
+ */
+export interface ProcessLike {
+    on(event: string, listener: (arg: unknown) => void): unknown;
+}
+type LogFn = (event: string, data: Record<string, unknown>) => void;
+export declare function installDaemonResilience(proc: ProcessLike, log: LogFn, onFatal: () => void): void;
+export {};
+//# sourceMappingURL=daemon-resilience.d.ts.map

package/dist/daemon-resilience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-resilience.d.ts","sourceRoot":"","sources":["../src/daemon-resilience.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC;CAC9D;AAED,KAAK,KAAK,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAMpE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAQhG"}

package/dist/daemon-resilience.js

@@ -0,0 +1,23 @@
+/**
+ * Process-level resilience for the long-running daemon. The daemon serves many agents at once, so a
+ * single stray error must not take the whole fleet down:
+ *
+ *  - unhandledRejection (a fire-and-forget promise nobody awaited — the common case in async WS/pool
+ *    code) → LOG and keep running. One agent's async slip-up can't crash the daemon for everyone.
+ *  - uncaughtException (a synchronous throw escaped all try/catch) → the process state is undefined
+ *    per Node's guidance, so LOG a clear reason and exit cleanly; the next `reticle mcp` respawns a fresh
+ *    daemon, which beats crashing silently or limping along corrupt.
+ */
+function describe(value) {
+    return value instanceof Error ? value.message : String(value);
+}
+export function installDaemonResilience(proc, log, onFatal) {
+    proc.on('unhandledRejection', (reason) => {
+        log('reticle_daemon_unhandled_rejection', { reason: describe(reason) });
+    });
+    proc.on('uncaughtException', (err) => {
+        log('reticle_daemon_uncaught_exception', { error: describe(err) });
+        onFatal();
+    });
+}
+//# sourceMappingURL=daemon-resilience.js.map

package/dist/daemon-resilience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-resilience.js","sourceRoot":"","sources":["../src/daemon-resilience.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,IAAiB,EAAE,GAAU,EAAE,OAAmB;IACxF,IAAI,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAe,EAAE,EAAE;QAChD,GAAG,CAAC,oCAAoC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1E,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAY,EAAE,EAAE;QAC5C,GAAG,CAAC,mCAAmC,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnE,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/daemon.d.ts

@@ -0,0 +1,26 @@
+export declare function logPath(port: number): string;
+export declare function readPid(port: number): number | null;
+export declare function isAlive(pid: number): boolean;
+export declare function writePid(port: number): void;
+export declare function removePid(port: number): void;
+export declare function isRunning(port: number): boolean;
+/**
+ * Find the port of a live reticle daemon by scanning ~/.reticle/daemon-<port>.pid files — so `reticle open`
+ * can "find the port" itself instead of making the user reconcile it. Returns the first live one
+ * (lowest port, deterministic), or null when none is running.
+ */
+export declare function discoverDaemonPort(): number | null;
+/**
+ * Sweep ~/.reticle for daemon-<port>.pid files whose process is no longer alive and delete them, so a
+ * crashed daemon never leaves a stale pidfile that confuses discovery or makes a port look "taken".
+ * Returns the ports reclaimed. `home` and `pidAlive` are injectable for testing (default to the real
+ * ~/.reticle and the process.kill(pid,0) liveness probe).
+ */
+export declare function reclaimStaleDaemons(home?: string, pidAlive?: (pid: number) => boolean): number[];
+/**
+ * Spawn the reticle daemon as a detached background process, redirecting output to the log file.
+ * Writes the PID file from the parent before returning so callers can call isRunning()
+ * immediately without a race window.
+ */
+export declare function spawnDaemon(nodeExec: string, scriptPath: string, args: string[], port: number): void;
+//# sourceMappingURL=daemon.d.ts.map

package/dist/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"AAmBA,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKnD;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO5C;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAG3C;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAG5C;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG/C;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAclD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,GAAE,MAAqB,EAC3B,QAAQ,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAiB,GAC3C,MAAM,EAAE,CA6BV;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,EAAE,MAAM,GACX,IAAI,CAWN"}

package/dist/daemon.js

@@ -0,0 +1,122 @@
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, openSync, readdirSync, } from 'node:fs';
+import { spawn } from 'node:child_process';
+const RETICLE_HOME = join(homedir(), '.reticle');
+function pidPath(port) {
+    return join(RETICLE_HOME, `daemon-${port}.pid`);
+}
+export function logPath(port) {
+    return join(RETICLE_HOME, `daemon-${port}.log`);
+}
+export function readPid(port) {
+    const path = pidPath(port);
+    if (!existsSync(path))
+        return null;
+    const n = parseInt(readFileSync(path, 'utf8').trim(), 10);
+    return isNaN(n) ? null : n;
+}
+export function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function writePid(port) {
+    mkdirSync(RETICLE_HOME, { recursive: true });
+    writeFileSync(pidPath(port), String(process.pid), 'utf8');
+}
+export function removePid(port) {
+    const path = pidPath(port);
+    if (existsSync(path))
+        unlinkSync(path);
+}
+export function isRunning(port) {
+    const pid = readPid(port);
+    return pid !== null && isAlive(pid);
+}
+/**
+ * Find the port of a live reticle daemon by scanning ~/.reticle/daemon-<port>.pid files — so `reticle open`
+ * can "find the port" itself instead of making the user reconcile it. Returns the first live one
+ * (lowest port, deterministic), or null when none is running.
+ */
+export function discoverDaemonPort() {
+    reclaimStaleDaemons(); // sweep crashed daemons' stale pidfiles before scanning for live ones
+    let found = null;
+    try {
+        for (const file of readdirSync(RETICLE_HOME)) {
+            const m = /^daemon-(\d+)\.pid$/.exec(file);
+            if (m === null)
+                continue;
+            const port = Number(m[1]);
+            if (isRunning(port) && (found === null || port < found))
+                found = port;
+        }
+    }
+    catch {
+        // no ~/.reticle yet → nothing running
+    }
+    return found;
+}
+/**
+ * Sweep ~/.reticle for daemon-<port>.pid files whose process is no longer alive and delete them, so a
+ * crashed daemon never leaves a stale pidfile that confuses discovery or makes a port look "taken".
+ * Returns the ports reclaimed. `home` and `pidAlive` are injectable for testing (default to the real
+ * ~/.reticle and the process.kill(pid,0) liveness probe).
+ */
+export function reclaimStaleDaemons(home = RETICLE_HOME, pidAlive = isAlive) {
+    const reclaimed = [];
+    let files;
+    try {
+        files = readdirSync(home);
+    }
+    catch {
+        return reclaimed; // no ~/.reticle yet → nothing to reclaim
+    }
+    for (const file of files) {
+        const match = /^daemon-(\d+)\.pid$/.exec(file);
+        if (match === null)
+            continue;
+        const path = join(home, file);
+        let pid = null;
+        try {
+            pid = parseInt(readFileSync(path, 'utf8').trim(), 10);
+            if (isNaN(pid))
+                pid = null;
+        }
+        catch {
+            pid = null; // unreadable pidfile counts as stale
+        }
+        if (pid === null || !pidAlive(pid)) {
+            try {
+                unlinkSync(path);
+                reclaimed.push(Number(match[1]));
+            }
+            catch {
+                // racing another reclaimer — fine, it's already gone
+            }
+        }
+    }
+    return reclaimed;
+}
+/**
+ * Spawn the reticle daemon as a detached background process, redirecting output to the log file.
+ * Writes the PID file from the parent before returning so callers can call isRunning()
+ * immediately without a race window.
+ */
+export function spawnDaemon(nodeExec, scriptPath, args, port) {
+    mkdirSync(RETICLE_HOME, { recursive: true });
+    const fd = openSync(logPath(port), 'a');
+    const child = spawn(nodeExec, [scriptPath, ...args], {
+        detached: true,
+        stdio: ['ignore', fd, fd],
+    });
+    if (child.pid !== undefined) {
+        writeFileSync(pidPath(port), String(child.pid), 'utf8');
+    }
+    child.unref();
+}
+//# sourceMappingURL=daemon.js.map

package/dist/daemon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.js","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"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"}

package/dist/domain/domain-model.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Build a compact "domain model" of an app's testable surface for an agent to read BEFORE testing:
+ * the demonstrated flows, what each one actually asserts, and — the differentiator — the GAPS
+ * between declared intent (capabilities the app registered: signals/testids) and what any flow
+ * actually verifies.
+ *
+ * Why (grounded): automation "checks the DOM, not the intent" — tests pass while real,
+ * integrated-system bugs ship (Bolton; Fowler Assertion-Free Testing). An agent that can see "you
+ * declared the signal order:placed but no flow asserts it" knows where the real risk is, instead of
+ * re-deriving the app's flows by reading all the source. Pairs with the flow assertion grades
+ * (flow-classify) so "rigorous" and "domain-aware" reinforce each other.
+ *
+ * Pure: no IO, no clock. The tool layer loads flows + contract and calls this.
+ */
+import { type CapabilitiesContract, type FlowFile, type RunRecord } from '@reticlehq/core';
+import { type FlowRisk } from './flow-risk.js';
+export interface DomainFlowSummary {
+    name: string;
+    steps: number;
+    grade: string;
+    /** True when the flow asserts a real consequence (signal/net), not just presence. */
+    asserts: boolean;
+    /**
+     * The success consequence that MUST hold for this flow to count as passing — the human-readable
+     * label of flow.success (e.g. a signal name or net URL). Undefined when the flow declares no
+     * success condition (then `asserts` is false: it tests nothing observable). This is the
+     * "what must hold for each flow" an agent needs before testing.
+     */
+    mustHold?: string;
+    warning?: string;
+    signals: string[];
+    testids: string[];
+    /** Combined run-history + assertion-quality risk (present when run history is supplied). */
+    risk?: FlowRisk;
+}
+export interface DomainGaps {
+    /** Flows that act but don't assert a consequence (grade !== asserted). */
+    unassertedFlows: string[];
+    /** Signals the app declared in capabilities that NO flow asserts — untested intent. */
+    declaredUntestedSignals: string[];
+    /** Testids the app declared that no saved flow exercises. */
+    declaredUntestedTestids: string[];
+}
+export interface DomainModel {
+    flowCount: number;
+    flows: DomainFlowSummary[];
+    declared: {
+        testids: number;
+        signals: string[];
+        stores: string[];
+    };
+    coverage: {
+        asserted: number;
+        presenceOnly: number;
+        assertionFree: number;
+    };
+    gaps: DomainGaps;
+    /** Flow names worst-risk first (run-history + assertion quality). Empty without run history. */
+    riskRanked: string[];
+    /** One-line headline an agent (or human) can read at a glance. */
+    summary: string;
+}
+export declare function buildDomainModel(flows: readonly FlowFile[], contract: CapabilitiesContract | null, runs?: readonly RunRecord[]): DomainModel;
+//# sourceMappingURL=domain-model.d.ts.map

package/dist/domain/domain-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-model.d.ts","sourceRoot":"","sources":["../../src/domain/domain-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,QAAQ,EAEb,KAAK,SAAS,EACf,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAA8C,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE3F,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4FAA4F;IAC5F,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,uFAAuF;IACvF,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAClC,6DAA6D;IAC7D,uBAAuB,EAAE,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACnE,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5E,IAAI,EAAE,UAAU,CAAC;IACjB,gGAAgG;IAChG,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;CACjB;AAiCD,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,QAAQ,EAAE,oBAAoB,GAAG,IAAI,EACrC,IAAI,GAAE,SAAS,SAAS,EAAO,GAC9B,WAAW,CA8Db"}

package/dist/domain/domain-model.js

@@ -0,0 +1,127 @@
+/**
+ * Build a compact "domain model" of an app's testable surface for an agent to read BEFORE testing:
+ * the demonstrated flows, what each one actually asserts, and — the differentiator — the GAPS
+ * between declared intent (capabilities the app registered: signals/testids) and what any flow
+ * actually verifies.
+ *
+ * Why (grounded): automation "checks the DOM, not the intent" — tests pass while real,
+ * integrated-system bugs ship (Bolton; Fowler Assertion-Free Testing). An agent that can see "you
+ * declared the signal order:placed but no flow asserts it" knows where the real risk is, instead of
+ * re-deriving the app's flows by reading all the source. Pairs with the flow assertion grades
+ * (flow-classify) so "rigorous" and "domain-aware" reinforce each other.
+ *
+ * Pure: no IO, no clock. The tool layer loads flows + contract and calls this.
+ */
+import { AnchorKind, } from '@reticlehq/core';
+import { classifyFlowAssertions, FlowAssertionGrade } from '../flows/flow-classify.js';
+import { successLabel } from '../flows/flow-success.js';
+import { flowRisk, latestRun, rankByRisk, RiskLevel } from './flow-risk.js';
+function flatten(steps) {
+    const out = [];
+    for (const s of steps) {
+        out.push(s);
+        if (s.steps !== undefined)
+            out.push(...flatten(s.steps));
+    }
+    return out;
+}
+function flowSignals(flow) {
+    const set = new Set();
+    for (const step of flatten(flow.steps)) {
+        if (step.anchor.kind === AnchorKind.SIGNAL)
+            set.add(step.anchor.name);
+        if (step.expect?.signal !== undefined)
+            set.add(step.expect.signal);
+    }
+    if (flow.success?.signal !== undefined)
+        set.add(flow.success.signal);
+    return [...set];
+}
+function flowTestids(flow) {
+    const set = new Set();
+    for (const step of flatten(flow.steps)) {
+        if (step.anchor.kind === AnchorKind.TESTID)
+            set.add(step.anchor.value);
+        if (step.expect?.element?.testid !== undefined)
+            set.add(step.expect.element.testid);
+    }
+    if (flow.success?.element?.testid !== undefined)
+        set.add(flow.success.element.testid);
+    return [...set];
+}
+const EMPTY_CONTRACT = { testids: [], signals: [], stores: [], flows: [] };
+export function buildDomainModel(flows, contract, runs = []) {
+    const caps = contract ?? EMPTY_CONTRACT;
+    const hasHistory = runs.length > 0;
+    const flowSummaries = flows.map((flow) => {
+        const c = classifyFlowAssertions(flow);
+        const summary = {
+            name: flow.name,
+            steps: c.totalSteps,
+            grade: c.grade,
+            asserts: c.hasConsequenceAssertion,
+            signals: flowSignals(flow),
+            testids: flowTestids(flow),
+        };
+        if (flow.success !== undefined)
+            summary.mustHold = successLabel(flow.success);
+        if (c.warning !== undefined)
+            summary.warning = c.warning;
+        if (hasHistory)
+            summary.risk = flowRisk(c.grade, latestRun(flow.name, runs));
+        return summary;
+    });
+    const testedSignals = new Set(flowSummaries.flatMap((f) => f.signals));
+    const testedTestids = new Set(flowSummaries.flatMap((f) => f.testids));
+    const coverage = {
+        asserted: flowSummaries.filter((f) => f.grade === FlowAssertionGrade.ASSERTED).length,
+        presenceOnly: flowSummaries.filter((f) => f.grade === FlowAssertionGrade.PRESENCE_ONLY).length,
+        assertionFree: flowSummaries.filter((f) => f.grade === FlowAssertionGrade.ASSERTION_FREE)
+            .length,
+    };
+    const gaps = {
+        unassertedFlows: flowSummaries.filter((f) => !f.asserts).map((f) => f.name),
+        declaredUntestedSignals: caps.signals.filter((s) => !testedSignals.has(s)),
+        declaredUntestedTestids: caps.testids.filter((t) => !testedTestids.has(t)),
+    };
+    const riskRanked = hasHistory
+        ? rankByRisk(flowSummaries
+            .filter((f) => f.risk !== undefined)
+            .map((f) => ({ name: f.name, risk: f.risk })))
+        : [];
+    // The most actionable fact — the riskiest flow to test first — when run history flagged one.
+    const top = riskRanked[0];
+    const topFlow = top === undefined ? undefined : flowSummaries.find((f) => f.name === top);
+    const topRisk = topFlow?.risk !== undefined &&
+        (topFlow.risk.level === RiskLevel.HIGH || topFlow.risk.level === RiskLevel.MEDIUM)
+        ? { name: topFlow.name, reason: topFlow.risk.reason }
+        : undefined;
+    return {
+        flowCount: flows.length,
+        flows: flowSummaries,
+        declared: { testids: caps.testids.length, signals: caps.signals, stores: caps.stores },
+        coverage,
+        gaps,
+        riskRanked,
+        summary: buildSummary(flows.length, coverage, gaps, topRisk),
+    };
+}
+function buildSummary(flowCount, coverage, gaps, topRisk) {
+    if (flowCount === 0) {
+        return 'No saved flows yet — record the critical journeys (reticle_record_start) so the agent learns the app.';
+    }
+    const parts = [
+        `${String(flowCount)} flow${flowCount === 1 ? '' : 's'}: ${String(coverage.asserted)} asserted, ${String(coverage.presenceOnly)} presence-only, ${String(coverage.assertionFree)} assertion-free`,
+    ];
+    if (topRisk !== undefined) {
+        parts.push(`test first: ${topRisk.name} (${topRisk.reason})`);
+    }
+    if (gaps.declaredUntestedSignals.length > 0) {
+        parts.push(`${String(gaps.declaredUntestedSignals.length)} declared signal(s) no flow asserts (${gaps.declaredUntestedSignals.join(', ')})`);
+    }
+    if (gaps.unassertedFlows.length > 0) {
+        parts.push(`${String(gaps.unassertedFlows.length)} flow(s) assert no consequence`);
+    }
+    return parts.join('. ') + '.';
+}
+//# sourceMappingURL=domain-model.js.map

package/dist/domain/domain-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-model.js","sourceRoot":"","sources":["../../src/domain/domain-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,UAAU,GAKX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAiB,MAAM,gBAAgB,CAAC;AA2C3F,SAAS,OAAO,CAAC,KAA0B;IACzC,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACZ,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,WAAW,CAAC,IAAc;IACjC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,UAAU,CAAC,MAAM;YAAE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtE,IAAI,IAAI,CAAC,MAAM,EAAE,MAAM,KAAK,SAAS;YAAE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS;QAAE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACrE,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;AAClB,CAAC;AAED,SAAS,WAAW,CAAC,IAAc;IACjC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,UAAU,CAAC,MAAM;YAAE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,SAAS;YAAE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,SAAS;QAAE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACtF,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,cAAc,GAAyB,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAEjG,MAAM,UAAU,gBAAgB,CAC9B,KAA0B,EAC1B,QAAqC,EACrC,OAA6B,EAAE;IAE/B,MAAM,IAAI,GAAG,QAAQ,IAAI,cAAc,CAAC;IACxC,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IAEnC,MAAM,aAAa,GAAwB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAC5D,MAAM,CAAC,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,OAAO,GAAsB;YACjC,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,KAAK,EAAE,CAAC,CAAC,UAAU;YACnB,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,OAAO,EAAE,CAAC,CAAC,uBAAuB;YAClC,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC;YAC1B,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC;SAC3B,CAAC;QACF,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;YAAE,OAAO,CAAC,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC9E,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS;YAAE,OAAO,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;QACzD,IAAI,UAAU;YAAE,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC7E,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC,CAAC;IAEH,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACvE,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAEvE,MAAM,QAAQ,GAAG;QACf,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,kBAAkB,CAAC,QAAQ,CAAC,CAAC,MAAM;QACrF,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,kBAAkB,CAAC,aAAa,CAAC,CAAC,MAAM;QAC9F,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,kBAAkB,CAAC,cAAc,CAAC;aACtF,MAAM;KACV,CAAC;IAEF,MAAM,IAAI,GAAe;QACvB,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAC3E,uBAAuB,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC1E,uBAAuB,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;KAC3E,CAAC;IAEF,MAAM,UAAU,GAAG,UAAU;QAC3B,CAAC,CAAC,UAAU,CACR,aAAa;aACV,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC;aACnC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAgB,EAAE,CAAC,CAAC,CAC5D;QACH,CAAC,CAAC,EAAE,CAAC;IAEP,6FAA6F;IAC7F,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,OAAO,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;IAC1F,MAAM,OAAO,GACX,OAAO,EAAE,IAAI,KAAK,SAAS;QAC3B,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,MAAM,CAAC;QAChF,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE;QACrD,CAAC,CAAC,SAAS,CAAC;IAEhB,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,MAAM;QACvB,KAAK,EAAE,aAAa;QACpB,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE;QACtF,QAAQ;QACR,IAAI;QACJ,UAAU;QACV,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC;KAC7D,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CACnB,SAAiB,EACjB,QAAiC,EACjC,IAAgB,EAChB,OAAqD;IAErD,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;QACpB,OAAO,uGAAuG,CAAC;IACjH,CAAC;IACD,MAAM,KAAK,GAAG;QACZ,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,cAAc,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,mBAAmB,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,iBAAiB;KAClM,CAAC;IACF,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,eAAe,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,IAAI,CAAC,uBAAuB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5C,KAAK,CAAC,IAAI,CACR,GAAG,MAAM,CAAC,IAAI,CAAC,uBAAuB,CAAC,MAAM,CAAC,wCAAwC,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACjI,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,gCAAgC,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC;AAChC,CAAC"}

package/dist/domain/domain-tools.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDef } from '../tools/tools.js';
+/**
+ * reticle_domain — the "learn the app before testing it" tool. Synthesizes every saved flow + the
+ * registered capabilities into a compact domain model: the journeys, what each asserts, and the
+ * GAPS (declared signals/testids no flow verifies). An agent reads this once instead of crawling
+ * the whole app or reading all the source — and it points straight at untested intent.
+ */
+export declare const DOMAIN_TOOLS: ToolDef[];
+//# sourceMappingURL=domain-tools.d.ts.map

package/dist/domain/domain-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-tools.d.ts","sourceRoot":"","sources":["../../src/domain/domain-tools.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,EA4DjC,CAAC"}

package/dist/domain/domain-tools.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { ReticleTool } from '../tools/tool-names.js';
+import { readContract } from '../project/reticle-dir.js';
+import { buildDomainModel } from './domain-model.js';
+/**
+ * reticle_domain — the "learn the app before testing it" tool. Synthesizes every saved flow + the
+ * registered capabilities into a compact domain model: the journeys, what each asserts, and the
+ * GAPS (declared signals/testids no flow verifies). An agent reads this once instead of crawling
+ * the whole app or reading all the source — and it points straight at untested intent.
+ */
+export const DOMAIN_TOOLS = [
+    {
+        name: ReticleTool.DOMAIN,
+        description: 'Read the app domain model BEFORE testing: every saved flow with its assertion grade, the consequence that MUST hold for it (mustHold = what it actually tests), the anchors/signals it exercises, plus GAPS — declared signals/testids that NO flow asserts (untested intent), and flows that assert no observable consequence. Use this to decide what to test and where the real risk is, instead of crawling the whole app. Reads .reticle/flows/ + .reticle/contract.json (no browser needed).',
+        inputSchema: {},
+        outputSchema: {
+            flowCount: z.number(),
+            flows: z.array(z.object({
+                name: z.string(),
+                steps: z.number(),
+                grade: z.string(),
+                asserts: z.boolean(),
+                mustHold: z
+                    .string()
+                    .optional()
+                    .describe('The success consequence that must hold for this flow (what it actually tests).'),
+                warning: z.string().optional(),
+                signals: z.array(z.string()),
+                testids: z.array(z.string()),
+            })),
+            declared: z.object({
+                testids: z.number(),
+                signals: z.array(z.string()),
+                stores: z.array(z.string()),
+            }),
+            coverage: z.object({
+                asserted: z.number(),
+                presenceOnly: z.number(),
+                assertionFree: z.number(),
+            }),
+            gaps: z.object({
+                unassertedFlows: z.array(z.string()),
+                declaredUntestedSignals: z.array(z.string()),
+                declaredUntestedTestids: z.array(z.string()),
+            }),
+            riskRanked: z
+                .array(z.string())
+                .describe('Flow names worst-risk first (run history + assertion quality). Test these first.'),
+            summary: z.string(),
+        },
+        handler: async (deps) => {
+            const names = await deps.flows.list();
+            const flows = [];
+            for (const name of names) {
+                const loaded = await deps.flows.load(name);
+                if (loaded.ok)
+                    flows.push(loaded.value);
+            }
+            const contract = await readContract(deps.fs, deps.reticleRoot);
+            const project = await deps.project.read();
+            const runs = project.ok ? project.file.runs : [];
+            return buildDomainModel(flows, contract.ok ? contract.capabilities : null, runs);
+        },
+    },
+];
+//# sourceMappingURL=domain-tools.js.map

package/dist/domain/domain-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-tools.js","sourceRoot":"","sources":["../../src/domain/domain-tools.ts"],"names":[],"mappings":"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"}