@reticlehq/server 2.14.0 → 3.2.0

package/dist/judgement/capsule/capsule-store.js

@@ -0,0 +1,113 @@
+import { join } from 'node:path';
+import { z } from 'zod';
+import { FlowStepSchema } from '@reticlehq/core';
+import { reticleDirPaths } from '../../memory/project/dir/reticle-dir.js';
+/**
+ * Bug capsules. When an assertion fails, the evidence that explains it is in hand exactly once —
+ * at the moment of the failure. A capsule persists that moment as a *replayable artifact*: the minimal
+ * failing steps, the consequence that was supposed to hold, and the divergence that was observed instead.
+ *
+ * This is deliberately fail-to-pass shaped (SWE-bench style): a capsule reproduces a bug NOW and, once the
+ * fix lands, it is exactly a regression flow. Capsules are ordinary flow files plus evidence, so they
+ * replay through the existing machinery rather than needing a second runner.
+ */
+/**
+ * The capsule file-format version. Declared ABOVE the schema so the schema, the writer and this
+ * constant cannot disagree about the number.
+ */
+export const CAPSULE_VERSION = 1;
+const CapsuleSchema = z.object({
+    version: z.literal(CAPSULE_VERSION),
+    id: z.string(),
+    /** The flow the failure happened in, when it came from one (a bare assert has no flow). */
+    flow: z.string().optional(),
+    createdAt: z.number(),
+    /** Why it was captured — a failed assertion, a crawl anomaly, a human review pin. */
+    origin: z.string(),
+    /** The consequence that was supposed to hold. */
+    expected: z.string(),
+    /** What was observed instead — the first-divergence sentence. */
+    observed: z.string(),
+    /** Minimal steps to reproduce (prefix-trimmed). */
+    steps: z.array(FlowStepSchema),
+});
+/** Capsule ids are filenames — refuse anything that could escape the capsules directory. */
+export function isValidCapsuleId(id) {
+    return /^[a-zA-Z0-9._-]+$/.test(id) && id !== '.' && id !== '..' && id.length <= 128;
+}
+export class CapsuleStore {
+    #fs;
+    #dir;
+    constructor(fs, root) {
+        this.#fs = fs;
+        this.#dir = reticleDirPaths(root).capsules;
+    }
+    #pathFor(id) {
+        return join(this.#dir, `${id}.json`);
+    }
+    /** Persist a capsule. Best-effort by design: capturing evidence must never fail the run that found it. */
+    async save(capsule) {
+        if (!isValidCapsuleId(capsule.id))
+            return false;
+        try {
+            await this.#fs.mkdir(this.#dir);
+            const tmp = `${this.#pathFor(capsule.id)}.tmp`;
+            await this.#fs.writeFile(tmp, `${JSON.stringify(capsule, null, 2)}\n`);
+            await this.#fs.rename(tmp, this.#pathFor(capsule.id));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Capsule ids on disk, newest-first by id (ids are time-prefixed). Never throws. */
+    async list() {
+        try {
+            if (!(await this.#fs.exists(this.#dir)))
+                return [];
+            const entries = await this.#fs.readdir(this.#dir);
+            return entries
+                .filter((e) => e.endsWith('.json'))
+                .map((e) => e.slice(0, -'.json'.length))
+                .sort()
+                .reverse();
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Read one capsule; undefined when missing or malformed (never throws). */
+    async read(id) {
+        if (!isValidCapsuleId(id))
+            return undefined;
+        try {
+            const parsed = JSON.parse(await this.#fs.readFile(this.#pathFor(id)));
+            const result = CapsuleSchema.safeParse(parsed);
+            return result.success ? result.data : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Every readable capsule, newest-first — what `reticle capsules` prints. */
+    async all() {
+        const out = [];
+        for (const id of await this.list()) {
+            const capsule = await this.read(id);
+            if (capsule !== undefined)
+                out.push(capsule);
+        }
+        return out;
+    }
+}
+/** Deterministic, path-safe capsule id: time-ordered so `list` sorts newest-first for free. */
+export function capsuleId(now, label) {
+    const safe = label.replace(/[^a-zA-Z0-9._-]/g, '-').slice(0, 40);
+    return `${String(now)}-${safe.length > 0 ? safe : 'capsule'}`;
+}
+/** The minimal reproduction: the steps up to and including the one that failed (prefix trim). */
+export function minimalSteps(steps, failedIndex) {
+    if (failedIndex < 0)
+        return [...steps];
+    return steps.slice(0, failedIndex + 1);
+}

package/dist/judgement/capsule/capsule.d.ts

@@ -0,0 +1,42 @@
+import { type ReticleEvent } from '@reticlehq/core';
+import { type CausalSummary } from './causal-summary.js';
+import { type Divergence, type ExpectedLink } from './divergence.js';
+/**
+ * The divergence capsule (Tier 2) — the whole packet on a red: the attributed causal summary, the
+ * FIRST divergence (where declared ≠ observed), and the BLAST RADIUS (truth that changed OUTSIDE the
+ * declared consequence — an act that also fired an undeclared signal or mutated an unexpected store).
+ * Blast radius is how a "green" that did extra damage still gets caught. Pure composition of the parts;
+ * the paste-ready repair packet and wiring onto red results build on this.
+ */
+export interface DivergenceCapsule {
+    summary: CausalSummary;
+    firstDivergence: Divergence | null;
+    /** Observed consequences not in the declared set — unexpected side effects. */
+    blastRadius: string[];
+}
+/**
+ * Observed signals, store changes and REQUESTS the flow never declared — the side effects.
+ *
+ * Network was missing here for a long time, and it is the channel that carries the damage. An action
+ * satisfying every consequence it declared and also firing a request nobody asked for came back with
+ * an empty radius — which is the exact shape this idea exists for: a click that works AND posts
+ * somewhere else. A signal and a store change stay inside the page; a request leaves the machine.
+ *
+ * Declared requests are matched by `urlContains`, the same rule the divergence walk uses, so a flow
+ * that asked for `/api/order` is not told about `/api/order`.
+ */
+export declare function blastRadius(expected: readonly ExpectedLink[], observed: readonly ReticleEvent[]): string[];
+/** Compose the full capsule from the declared chain and the observed (attributed) event window. */
+export declare function buildDivergenceCapsule(expected: readonly ExpectedLink[], observed: readonly ReticleEvent[], truncated?: boolean): DivergenceCapsule;
+/**
+ * The capsule as it travels on a verdict RESPONSE — without its causal summary.
+ *
+ * The same response already carries `summary`, computed by `causalSummary()` over the same window,
+ * so shipping the capsule's copy sent the identical block twice. Measured on a 61-call drive of the
+ * a 61-call drive, 9 of 9 capsules duplicated it exactly — **14% of the
+ * whole run's token cost**, carrying nothing the reader did not already have two fields up.
+ *
+ * Wire-only. `capsule-store` persists the FULL capsule, because a stored capsule is read on its own
+ * and a summary-less one would be unreadable.
+ */
+export declare function wireCapsule(capsule: DivergenceCapsule): Omit<DivergenceCapsule, 'summary'>;

package/dist/judgement/capsule/capsule.js

@@ -0,0 +1,73 @@
+import { ConsequenceKind, EventType } from '@reticlehq/core';
+import { causalSummary } from './causal-summary.js';
+import { firstDivergence } from './divergence.js';
+/**
+ * Observed signals, store changes and REQUESTS the flow never declared — the side effects.
+ *
+ * Network was missing here for a long time, and it is the channel that carries the damage. An action
+ * satisfying every consequence it declared and also firing a request nobody asked for came back with
+ * an empty radius — which is the exact shape this idea exists for: a click that works AND posts
+ * somewhere else. A signal and a store change stay inside the page; a request leaves the machine.
+ *
+ * Declared requests are matched by `urlContains`, the same rule the divergence walk uses, so a flow
+ * that asked for `/api/order` is not told about `/api/order`.
+ */
+export function blastRadius(expected, observed) {
+    const declaredSignals = new Set(expected
+        .filter((l) => ConsequenceKind.SIGNAL === l.kind)
+        .map((l) => l.name));
+    const declaredStates = new Set(expected
+        .filter((l) => ConsequenceKind.STATE === l.kind)
+        .map((l) => l.name));
+    const declaredUrls = expected
+        .filter((l) => ConsequenceKind.NET === l.kind)
+        .map((l) => l.urlContains);
+    const radius = [];
+    const add = (value) => {
+        if (!radius.includes(value))
+            radius.push(value);
+    };
+    for (const event of observed) {
+        if (event.type === EventType.NET_REQUEST) {
+            const url = event.data['url'];
+            if ('string' !== typeof url)
+                continue;
+            if (declaredUrls.some((fragment) => url.includes(fragment)))
+                continue;
+            const method = event.data['method'];
+            add(`net ${'string' === typeof method ? method : 'request'} ${url}`);
+            continue;
+        }
+        const name = event.data['name'];
+        if (typeof name !== 'string')
+            continue;
+        if (event.type === EventType.SIGNAL && !declaredSignals.has(name))
+            add(`signal ${name}`);
+        if (event.type === EventType.STATE_CHANGE && !declaredStates.has(name))
+            add(`state ${name}`);
+    }
+    return radius;
+}
+/** Compose the full capsule from the declared chain and the observed (attributed) event window. */
+export function buildDivergenceCapsule(expected, observed, truncated = false) {
+    return {
+        summary: causalSummary(observed, { truncated }),
+        firstDivergence: firstDivergence(expected, observed, truncated),
+        blastRadius: blastRadius(expected, observed),
+    };
+}
+/**
+ * The capsule as it travels on a verdict RESPONSE — without its causal summary.
+ *
+ * The same response already carries `summary`, computed by `causalSummary()` over the same window,
+ * so shipping the capsule's copy sent the identical block twice. Measured on a 61-call drive of the
+ * a 61-call drive, 9 of 9 capsules duplicated it exactly — **14% of the
+ * whole run's token cost**, carrying nothing the reader did not already have two fields up.
+ *
+ * Wire-only. `capsule-store` persists the FULL capsule, because a stored capsule is read on its own
+ * and a summary-less one would be unreadable.
+ */
+export function wireCapsule(capsule) {
+    const { summary: _omitted, ...rest } = capsule;
+    return rest;
+}

package/dist/judgement/capsule/causal-summary.d.ts

@@ -0,0 +1,119 @@
+import { type ReticleEvent } from '@reticlehq/core';
+/**
+ * The causal summary (Tier 1) — the bounded ~50–100 token block on EVERY act, green included: what the
+ * app did in the act's window, as counts + a headline, not a raw event dump. Diffs come from the
+ * storage/state events; attribution from. Pure composition over the attributed event window.
+ */
+interface StateDiff {
+    path: string;
+    from: unknown;
+    to: unknown;
+    /**
+     * WHEN this path moved, in the session's elapsed ms.
+     *
+     * The whole reason a transient was invisible. A store that ends internally consistent can have been
+     * inconsistent on the way there, and a from→to pair cannot express that — measured on a real
+     * dashboard, an account switch moved `accountId` immediately and `payments` 160 ms later,
+     * so for 160 ms the header named one tenant while the rows belonged to another. Both diffs were
+     * reported; nothing said they were 160 ms apart, and waiting for the page to settle is by
+     * construction waiting for the evidence to disappear. The timestamp was on the event all along.
+     */
+    atMs: number;
+}
+interface StorageDiff {
+    key: string;
+    from?: unknown;
+    to?: unknown;
+}
+export interface CausalSummary {
+    /**
+     * `total`/`errors` describe the APP's traffic. `ignoredDevTooling` is the count of calls the dev
+     * toolchain made about itself (Next's error overlay, HMR, the Vite client — see
+     * `DevToolingChannel`), which Reticle deliberately leaves out of the settle decision and out of
+     * contradiction hunting. Present only when there were any: a trim is never silent, so an agent can
+     * always see that something was ignored and go read it in the timeline.
+     */
+    net: {
+        total: number;
+        errors: number;
+        ignoredDevTooling?: number;
+        headline?: string;
+    };
+    consoleErrors: number;
+    statePathsChanged: string[];
+    storageKeysChanged: string[];
+    /** Before→after for each changed store path — the diffs, not just the names. Values capped. */
+    stateDiffs: StateDiff[];
+    /**
+     * How long the store took to stop moving: last state change − first, in ms. Present only when more
+     * than one path changed, because with a single change there is no interval to describe.
+     *
+     * A FACT, not a verdict. Many apps update progressively and that is fine; calling every stagger a
+     * defect would make this a noise generator. But a non-zero value is the exact window in which the
+     * UI showed a MIXTURE of old and new, and that window is where the tenant-mismatch class of bug
+     * lives — so it is stated once, cheaply, and the agent decides.
+     */
+    stateSettleMs?: number;
+    /** Before→after for each changed storage key. Values capped. */
+    storageDiffs: StorageDiff[];
+    /**
+     * How many entries each list dropped to stay within MAX_SUMMARY_ENTRIES. Present only when
+     * something was dropped, so a trim is never silent — the same rule `ignoredDevTooling` follows.
+     */
+    elided?: Partial<Record<CappedList, number>>;
+    route?: string;
+    signals: string[];
+    layoutShift?: number;
+    longTasks: number;
+    /**
+     * TRUE when no store was subscribed, so `statePathsChanged`/`stateDiffs` are empty because nothing
+     * was watching — not because the app changed nothing.
+     *
+     * The two readings are the same empty list, and the wrong one is the one an agent takes: "state
+     * did not change" is a claim about the app, and this codebase would rather say "I could not see"
+     * than say something confident and wrong. Present only when the channel is dark, so a wired app
+     * pays nothing and the field's PRESENCE is what carries the meaning — the same rule
+     * `stateSettleMs` and `elided` follow.
+     */
+    stateUnwatched?: true;
+    /**
+     * TRUE when the ring buffer evicted events belonging to this window, so every count and list here
+     * is a FLOOR, not a total — `net.total: 0` means "none survived", never "none happened".
+     *
+     * The same distinction `stateUnwatched` draws, from the other cause, and it was the more expensive
+     * one. A field app rewrote one localStorage key thousands of times a minute; the no-op writes
+     * starved the buffer (`held: 2000, dropped: 70482`), and the verdict for that window reported
+     * `net.total: 0`, `stateDiffs: []` and "state never changed" — while a POST that had returned 200
+     * in that exact window carried the entire root cause in its body. The agent read the zero and was
+     * about to report "clicking Accept fires no network request", which points a developer at the
+     * click handler instead of at the payload the server rejected.
+     *
+     * `honesty.integrity.losses` already said `buffer_loss`. It was not enough: the headline fields an
+     * agent reads to form a verdict are these, and a bare `0` several levels above a nested integrity
+     * flag reads as a fact. The absolute and the caveat must not be separable, so the caveat rides on
+     * the summary that carries the absolutes.
+     */
+    truncated?: true;
+}
+/** What only the SESSION knows — level facts the event window cannot contain. See `stateUnwatched`. */
+interface SummaryContext {
+    stateUnwatched?: boolean;
+    /** Did the buffer drop events from this window — see `CausalSummary.truncated`. */
+    truncated?: boolean;
+}
+/**
+ * THE INVARIANT: every field of this summary has a bounded size that does not depend on how much the
+ * app did. A verdict travels in the same payload as its evidence, so an unbounded evidence field is
+ * an unbounded chance that the verdict is the part a client truncates — and an agent that cannot read
+ * the verdict has run the verification and got nothing, which is indistinguishable from not running
+ * it. Measured: one click on a page with a registered TanStack Query store returned ~363KB, because
+ * `capValue` bounded each diff and nothing bounded the COUNT of them.
+ *
+ * 20 keeps the signal that is actually read — the first paths to move, and the settle window over all
+ * of them — while the full names of everything that changed stay one `reticle_state` call away.
+ */
+export declare const MAX_SUMMARY_ENTRIES = 20;
+/** The lists that are capped, named so `elided` can say which one lost entries. */
+type CappedList = 'statePathsChanged' | 'storageKeysChanged' | 'stateDiffs' | 'storageDiffs' | 'signals';
+export declare function causalSummary(events: readonly ReticleEvent[], context?: SummaryContext): CausalSummary;
+export {};

package/dist/judgement/capsule/causal-summary.js

@@ -0,0 +1,172 @@
+import { EventType, PerfMetric, isDevToolingUrl } from '@reticlehq/core';
+import { routeOfEvent } from '@reticlehq/engine/question/predicate/predicate-route.js';
+/**
+ * THE INVARIANT: every field of this summary has a bounded size that does not depend on how much the
+ * app did. A verdict travels in the same payload as its evidence, so an unbounded evidence field is
+ * an unbounded chance that the verdict is the part a client truncates — and an agent that cannot read
+ * the verdict has run the verification and got nothing, which is indistinguishable from not running
+ * it. Measured: one click on a page with a registered TanStack Query store returned ~363KB, because
+ * `capValue` bounded each diff and nothing bounded the COUNT of them.
+ *
+ * 20 keeps the signal that is actually read — the first paths to move, and the settle window over all
+ * of them — while the full names of everything that changed stay one `reticle_state` call away.
+ */
+export const MAX_SUMMARY_ENTRIES = 20;
+/** Trim one list to the cap and report the loss. Order is arrival order, so the head is the earliest. */
+function cap(list, name, elided) {
+    if (list.length <= MAX_SUMMARY_ENTRIES)
+        return list;
+    elided[name] = list.length - MAX_SUMMARY_ENTRIES;
+    return list.slice(0, MAX_SUMMARY_ENTRIES);
+}
+function pushUnique(list, value) {
+    if ('string' === typeof value && value.length > 0 && !list.includes(value))
+        list.push(value);
+}
+/** Keep a diff value bounded so the per-act summary never bloats: primitives capped to a short string. */
+const MAX_DIFF_LEN = 140;
+/** Truncate to at most MAX_DIFF_LEN chars total, including the ellipsis marker. */
+function truncate(text) {
+    return text.length > MAX_DIFF_LEN ? `${text.slice(0, MAX_DIFF_LEN - 1)}…` : text;
+}
+function capValue(value) {
+    if (value === undefined || null === value)
+        return value;
+    if ('string' === typeof value)
+        return truncate(value);
+    if ('number' === typeof value || 'boolean' === typeof value)
+        return value;
+    // Objects/arrays: a shallow, length-capped JSON repr (never a deep dump on the hot path).
+    try {
+        return truncate(JSON.stringify(value));
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
+/**
+ * The span over which the store was still moving — and therefore possibly self-inconsistent.
+ *
+ * Omitted for 0 or 1 diffs (no interval) and for a spread of 0 (everything landed in one tick), so a
+ * store that updates atomically pays nothing and the field's PRESENCE is what carries the meaning.
+ */
+function stateSettle(diffs) {
+    if (diffs.length < 2)
+        return {};
+    const times = diffs.map((d) => d.atMs);
+    const spread = Math.max(...times) - Math.min(...times);
+    return spread > 0 ? { stateSettleMs: spread } : {};
+}
+export function causalSummary(events, context = {}) {
+    let netTotal = 0;
+    let netErrors = 0;
+    let ignoredDevTooling = 0;
+    let headline;
+    let consoleErrors = 0;
+    const statePathsChanged = [];
+    const storageKeysChanged = [];
+    const stateDiffs = [];
+    const storageDiffs = [];
+    let route;
+    const signals = [];
+    let layoutShift;
+    let longTasks = 0;
+    for (const event of events) {
+        const data = event.data;
+        switch (event.type) {
+            case EventType.NET_REQUEST: {
+                if (isDevToolingUrl('string' === typeof data['url'] ? data['url'] : undefined)) {
+                    ignoredDevTooling += 1;
+                    break;
+                }
+                netTotal += 1;
+                const status = data['status'];
+                const failed = false === data['ok'] || ('number' === typeof status && status >= 400);
+                if (failed) {
+                    netErrors += 1;
+                    // Headline is the first failing request — the thing most worth the agent's eye.
+                    headline ??= `${String(data['method'])} ${String(data['url'])} ${String(status)}`;
+                }
+                break;
+            }
+            case EventType.CONSOLE_ERROR:
+            case EventType.ERROR_UNCAUGHT:
+                consoleErrors += 1;
+                break;
+            case EventType.STATE_CHANGE: {
+                pushUnique(statePathsChanged, data['name']);
+                // The subscribed-store observer emits { name, path, value, old } — `value` is the AFTER side
+                // (`new` is accepted too for any producer that uses it). Presence of either makes it a real
+                // before→after diff rather than a bare reading.
+                const path = 'string' === typeof data['path'] ? data['path'] : data['name'];
+                const hasAfter = 'value' in data || 'new' in data;
+                if ('string' === typeof path && path.length > 0 && ('old' in data || hasAfter)) {
+                    const after = 'value' in data ? data['value'] : data['new'];
+                    stateDiffs.push({
+                        path,
+                        from: capValue(data['old']),
+                        to: capValue(after),
+                        atMs: event.t,
+                    });
+                }
+                break;
+            }
+            case EventType.STORAGE_CHANGE: {
+                pushUnique(storageKeysChanged, data['key']);
+                const key = data['key'];
+                if ('string' === typeof key && key.length > 0) {
+                    storageDiffs.push({ key, from: capValue(data['old']), to: capValue(data['new']) });
+                }
+                break;
+            }
+            case EventType.ROUTE_CHANGE: {
+                // The ROUTER's path. Reporting the document pathname left `route: "/"` on every action of a
+                // hash-routed app — the same reading that made a route predicate unsatisfiable there, and an
+                // agent reasoning off this field would conclude the route never changed. See routeOfEvent.
+                const routed = routeOfEvent(data);
+                if (routed !== undefined)
+                    route = routed.routePath;
+                break;
+            }
+            case EventType.SIGNAL:
+                pushUnique(signals, data['name']);
+                break;
+            case EventType.PERF:
+                if (data['metric'] === PerfMetric.CLS && 'number' === typeof data['value']) {
+                    layoutShift = Math.max(layoutShift ?? 0, data['value']);
+                }
+                else if (data['metric'] === PerfMetric.LONGTASK) {
+                    longTasks += 1;
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    const elided = {};
+    // `stateSettleMs` is computed over EVERY diff, before the cap: the interval is a fact about the
+    // store, and shrinking it because the evidence was trimmed would make the transient window read as
+    // narrower than it was — the one number here that must survive the trim intact.
+    const settle = stateSettle(stateDiffs);
+    return {
+        net: {
+            total: netTotal,
+            errors: netErrors,
+            ...(0 === ignoredDevTooling ? {} : { ignoredDevTooling }),
+            ...(headline === undefined ? {} : { headline }),
+        },
+        consoleErrors,
+        statePathsChanged: cap(statePathsChanged, 'statePathsChanged', elided),
+        storageKeysChanged: cap(storageKeysChanged, 'storageKeysChanged', elided),
+        stateDiffs: cap(stateDiffs, 'stateDiffs', elided),
+        ...settle,
+        storageDiffs: cap(storageDiffs, 'storageDiffs', elided),
+        ...(route === undefined ? {} : { route }),
+        signals: cap(signals, 'signals', elided),
+        ...(0 === Object.keys(elided).length ? {} : { elided }),
+        ...(layoutShift === undefined ? {} : { layoutShift }),
+        longTasks,
+        ...(true === context.stateUnwatched ? { stateUnwatched: true } : {}),
+        ...(true === context.truncated ? { truncated: true } : {}),
+    };
+}

package/dist/judgement/capsule/divergence.d.ts

@@ -0,0 +1,26 @@
+import { type ExpectedLink, type ReticleEvent } from '@reticlehq/core';
+/**
+ * First-divergence — the brain of the divergence capsule (Tier 2). Given the chain the flow DECLARED
+ * should happen (its mustHold, as ordered expected links) and what was OBSERVED, walk the declaration and
+ * report the FIRST link where expected ≠ observed, values side by side. That single link is where the
+ * fault lives — the agent fixes it without re-exploring. Pure; the acceptance bar is that for every
+ * hidden-500 / hung-request fixture it names the correct link.
+ */
+/**
+ * The links a capsule can walk. Defined in the shared vocabulary, because the rules that decide a
+ * verdict produce this shape and the explanation of a red verdict consumes it, and neither should
+ * have to reach into the other to name the same thing. Re-exported here so the places that already
+ * read it from this file still can.
+ */
+export type { ExpectedLink };
+export interface Divergence {
+    /** The declared link that did not hold. */
+    expected: ExpectedLink;
+    /** Human description of what was observed instead (the closest attempt, or "nothing"). */
+    observed: string;
+}
+/**
+ * Walk the declared chain in order; return the first link not satisfied by the observed events (with a
+ * side-by-side of what happened instead), or null when the whole chain held.
+ */
+export declare function firstDivergence(expected: readonly ExpectedLink[], observed: readonly ReticleEvent[], truncated?: boolean): Divergence | null;

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

@@ -0,0 +1,126 @@
+/**
+ * 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 '../../language/flows/flow-classify.js';
+import { successLabel } from '../../language/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 (0 === flowCount) {
+        return 'No saved flows yet — record the critical journeys (reticle_record{action:"start"}) so the agent learns the app.';
+    }
+    const parts = [
+        `${String(flowCount)} flow${1 === flowCount ? '' : '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('. ') + '.';
+}