@reticlehq/server 2.8.0 → 2.9.0

package/dist/events/predicate-eval.d.ts

@@ -1,91 +1,6 @@
-import { ElementState, PredicateKind, type ElementDescriptor, type ElementQuery, type ReticleEvent } from '@reticlehq/core';
-import { z } from 'zod';
-export type Predicate = {
-    kind: typeof PredicateKind.ELEMENT;
-    query: ElementQuery;
-    state?: ElementState;
-    absent?: boolean;
-} | {
-    kind: typeof PredicateKind.TEXT;
-    contains: string;
-    visible?: boolean;
-    absent?: boolean;
-} | {
-    kind: typeof PredicateKind.NET;
-    method?: string;
-    urlContains?: string;
-    status?: number;
-    /** Did the call succeed? The honest field for IPC, which has no status code. */
-    ok?: boolean;
-    since?: number;
-    count?: number;
-} | {
-    kind: typeof PredicateKind.ROUTE;
-    pathname?: string;
-    contains?: string;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.CONSOLE;
-    level?: string;
-    absent?: boolean;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.ANIMATION;
-    name?: string;
-    target?: string;
-    completed?: boolean;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.SIGNAL;
-    name?: string;
-    dataMatches?: Record<string, unknown>;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.STATE;
-    store?: string;
-    path: string;
-    equals?: unknown;
-} | {
-    kind: typeof PredicateKind.SETTLED;
-    quietMs?: number;
-} | {
-    kind: typeof PredicateKind.ALL_OF;
-    predicates: Predicate[];
-} | {
-    kind: typeof PredicateKind.ANY_OF;
-    predicates: Predicate[];
-} | {
-    kind: typeof PredicateKind.NOT;
-    predicate: Predicate;
-};
-export interface ResidualQueryChecks {
-    /** Dropped fields this side CAN check, as [field, wanted value] pairs. */
-    checks: [string, string][];
-    /** Dropped fields with no descriptor to check them against — refuse rather than ignore. */
-    unusable: string[];
-}
-/**
- * Split a query's dropped fields into the ones the server can still enforce and the ones it cannot.
- *
- * The alternative — refuse every dropped field — breaks calls that work today and that our own
- * cheatsheet advertises (`{ role: "button", text: "Save" }`), and breaks them into no verdict at all.
- * Enforcing what we can and refusing only the rest keeps those calls working AS WRITTEN, which is the
- * outcome the caller was already assuming.
- */
-export declare function residualQueryChecks(query: ElementQuery): ResidualQueryChecks;
-/** Does this element satisfy every field the locator dropped? */
-export declare function satisfiesResiduals(element: ElementDescriptor, checks: readonly [string, string][]): boolean;
-/** How the element's own reading of a dropped field should be REPORTED back on a failure. */
-export declare function describeResidual(element: ElementDescriptor, field: string): string;
-export declare const PredicateSchema: z.ZodType<Predicate>;
-/**
- * The fields a given predicate kind accepts, read off the schema itself.
- *
- * Derived rather than listed so the two can never disagree: a rejection message that names a stale
- * field set is worse than one that names none, because the agent trusts it and retries into the same
- * wall. Empty for a kind that is not in the union.
- */
-export declare function predicateFieldsFor(kind: string): readonly string[];
+import { PredicateKind, type ReticleEvent } from '@reticlehq/core';
+import type { Predicate } from './predicate-schema.js';
+export * from './predicate-schema.js';
 export interface EvalResult {
     pass: boolean;
     /**
@@ -104,6 +19,19 @@ export interface EvalResult {
      * not a defect in the user's app, and reporting it as one puts agent mistakes into the bug count.
      */
     inconclusive?: string;
+    /**
+     * No later event in this window can change this answer, so waiting out the rest of the budget
+     * buys nothing.
+     *
+     * Set ONLY where that is provable, which is rarer than it looks. "The toast never appeared" is not
+     * decided — it is only knowable when the budget ends, and ending early there would manufacture the
+     * false negative the budget exists to prevent. Exact cardinality IS decided once exceeded, because
+     * a window only accumulates matches and a count cannot come back down.
+     *
+     * A scheduling fact, never a verdict: `pass` already says what the answer is, and this only says
+     * that it is final.
+     */
+    decided?: boolean;
     evidence?: unknown;
     failureReason?: string;
     /**
@@ -132,6 +60,7 @@ export interface EvalResult {
     expected?: string;
     assertion?: string;
 }
+export declare function str(value: unknown): string | undefined;
 /**
  * Match one value against a pattern. Supports `*` (present), strict equality, and operators:
  * `{$gte,$lte,$gt,$lt}` (numbers), `{$contains}` (array membership or substring), `{$length}`.
@@ -140,9 +69,6 @@ export declare function matchValue(got: unknown, want: unknown): boolean;
 export declare function evalNet(events: ReticleEvent[], p: Extract<Predicate, {
     kind: typeof PredicateKind.NET;
 }>): EvalResult;
-export declare function evalRoute(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: typeof PredicateKind.ROUTE;
-}>): EvalResult;
 export declare function evalConsole(events: ReticleEvent[], p: Extract<Predicate, {
     kind: typeof PredicateKind.CONSOLE;
 }>): EvalResult;

package/dist/events/predicate-eval.js

@@ -1,289 +1,10 @@
-import { ElementQuerySchema, ElementState, EventType, PredicateKind, QueryBy, StreamDirection, isDevToolingUrl, } from '@reticlehq/core';
-import { z } from 'zod';
+import { EventType, PredicateKind, StreamDirection, isDevToolingUrl, } from '@reticlehq/core';
 import { describeObserved } from './observed-in-window.js';
-/**
- * Spellings an agent plausibly reaches for, mapped to the real field.
- *
- * `route` spells its field `pathname` while `state`, in the same union, spells its `path`. Every one
- * of these was silently DROPPED before, and because these kinds have all-optional fields, dropping
- * the only key supplied left a predicate that asserts nothing and passes on anything.
- */
-const PREDICATE_ALIASES = {
-    // `text`/`value` on a `text` predicate: the kind is called "text", so `text:` is the first thing
-    // anyone writes for it, and `value` follows from the element query's own `value` field. Both were
-    // hard rejections, and a rejected predicate produces NO verdict at all — the drive ends with
-    // nothing rather than with a failure, which is the worst outcome of the three.
-    [PredicateKind.TEXT]: { text: 'contains', value: 'contains' },
-    // `urlContains`/`url` reported from the field: an agent that had just written
-    // `net { urlContains }` applied the same word to `route`, which spells it `contains`, and got
-    // `unrecognized_keys` with no list of what would have worked. The parallel it assumed is a fair
-    // one — route's `contains` matches the WHOLE route (path + query + fragment), so "the URL
-    // contains this" is precisely what it does — and asserting a redirect after login is the single
-    // most common thing an agent reaches for here.
-    [PredicateKind.ROUTE]: { path: 'pathname', urlContains: 'contains', url: 'contains' },
-    [PredicateKind.NET]: { url: 'urlContains' },
-    [PredicateKind.SIGNAL]: { data: 'dataMatches' },
-};
-/**
- * Element-query fields an agent writes FLAT on an `element` predicate instead of nested under
- * `query`. `reticle_query` takes exactly these at the top level, so an agent that has just located
- * something writes the same words again when it asserts on it — and got `query: Required` plus an
- * `unknown field` list for its trouble. Lifting them is unambiguous: they have no other meaning on
- * this kind.
- */
-const ELEMENT_QUERY_FIELDS = [
-    'by',
-    'value',
-    'role',
-    'name',
-    'text',
-    'label',
-    'placeholder',
-    'testid',
-    'alt',
-    'component',
-];
-/**
- * The locator fields the browser actually CONSUMES for a given query — mirrors the precedence in
- * `findIn` (packages/browser/src/dom/query.ts).
- *
- * An element query is not a conjunction. It is a first-match dispatch: `by`+`value` wins, then the
- * component/source anchor, then `role` (which alone also consumes `name`), then the first of
- * text/label/placeholder/testid/alt that is present. Every OTHER field the caller wrote is dropped on
- * the floor, silently, and the match reported as if the whole query had been honoured.
- *
- * Duplicated here on purpose. The alternative is to send the question to the browser, and the browser
- * cannot answer it: by the time a match comes back, the fields it ignored are indistinguishable from
- * the fields it used.
- */
-function usedQueryFields(query) {
-    const used = new Set();
-    if (query.by !== undefined && query.value !== undefined) {
-        used.add('by').add('value');
-        if (QueryBy.ROLE === query.by)
-            used.add('name');
-        if (QueryBy.COMPONENT === query.by)
-            used.add('component');
-        return used;
-    }
-    if (query.component !== undefined || query.source !== undefined)
-        return used.add('component');
-    if (query.role !== undefined)
-        return used.add('role').add('name');
-    for (const field of ['text', 'label', 'placeholder', 'testid', 'alt']) {
-        if (query[field] !== undefined)
-            return used.add(field);
-    }
-    return used;
-}
-/**
- * How a dropped field is checked back on the server, against the descriptor the match returned.
- *
- * `value` is the field this exists for: `{ role: "textbox", name: "GST amount", value: "274.58" }`
- * read as a locator has no `by`, so the value half was discarded and the predicate collapsed to "a
- * textbox named GST amount exists" — trivially true against an EMPTY field. Comparison is TRIMMED and
- * exact: an input's value is a value, not prose, and a trailing space in either the app or the
- * predicate is not a finding anybody wants. `""` asserts the field is empty, which describe() reports
- * by omitting the field entirely.
- *
- * `role`/`name`/`value` compare against exactly what `reticle_query` REPORTS, so the words an agent
- * copies out of a query result are the words that match here. `text` is a substring match, matching
- * Testing Library's `exact: false`, and falls back to the name because describe() omits `text` when it
- * equals the accessible name.
- */
-const RESIDUAL_CHECKS = {
-    value: (element, want) => (element.value ?? '').trim() === want.trim(),
-    role: (element, want) => element.role === want,
-    name: (element, want) => element.name.trim() === want.trim(),
-    text: (element, want) => (element.text ?? element.name).includes(want),
-};
-/**
- * Split a query's dropped fields into the ones the server can still enforce and the ones it cannot.
- *
- * The alternative — refuse every dropped field — breaks calls that work today and that our own
- * cheatsheet advertises (`{ role: "button", text: "Save" }`), and breaks them into no verdict at all.
- * Enforcing what we can and refusing only the rest keeps those calls working AS WRITTEN, which is the
- * outcome the caller was already assuming.
- */
-export function residualQueryChecks(query) {
-    const used = usedQueryFields(query);
-    const checks = [];
-    const unusable = [];
-    for (const field of ELEMENT_QUERY_FIELDS) {
-        const want = query[field];
-        if (want === undefined || used.has(field))
-            continue;
-        if ('string' === typeof want && RESIDUAL_CHECKS[field] !== undefined)
-            checks.push([field, want]);
-        else
-            unusable.push(field);
-    }
-    return { checks, unusable };
-}
-/** Does this element satisfy every field the locator dropped? */
-export function satisfiesResiduals(element, checks) {
-    return checks.every(([field, want]) => true === RESIDUAL_CHECKS[field]?.(element, want));
-}
-/** How the element's own reading of a dropped field should be REPORTED back on a failure. */
-export function describeResidual(element, field) {
-    const reading = 'value' === field
-        ? (element.value ?? '')
-        : 'text' === field
-            ? (element.text ?? element.name)
-            : 'role' === field
-                ? element.role
-                : element.name;
-    return `${element.role} "${element.name}" ${field}=${JSON.stringify(reading)}`;
-}
-/** Rename known aliases before parse; an explicit canonical key always wins. */
-function applyPredicateAliases(input) {
-    if (typeof input !== 'object' || null === input || Array.isArray(input))
-        return input;
-    const obj = input;
-    const kind = 'string' === typeof obj['kind'] ? obj['kind'] : '';
-    const aliases = PREDICATE_ALIASES[kind];
-    let out = obj;
-    if (aliases !== undefined) {
-        out = { ...obj };
-        for (const [from, to] of Object.entries(aliases)) {
-            if (out[from] === undefined)
-                continue;
-            if (out[to] === undefined)
-                out[to] = out[from];
-            delete out[from];
-        }
-    }
-    return PredicateKind.ELEMENT === kind ? liftElementQuery(out) : out;
-}
-/**
- * Fold flat query fields into `query`. An explicit `query` wins outright — a caller that supplied
- * both told us which one it meant, and merging the two would invent a locator neither side wrote.
- */
-function liftElementQuery(obj) {
-    const loose = ELEMENT_QUERY_FIELDS.filter((field) => obj[field] !== undefined);
-    if (0 === loose.length)
-        return obj;
-    const out = { ...obj };
-    const query = {};
-    for (const field of loose) {
-        query[field] = out[field];
-        delete out[field];
-    }
-    if (out['query'] === undefined)
-        out['query'] = query;
-    return out;
-}
-/**
- * Strict on every branch. A key that is nobody's spelling is now a schema error naming it, instead of
- * a stripped field and a green — see predicate-strict.test.ts for the MCP session that found this.
- *
- * Built on demand rather than at module scope: the `allOf`/`anyOf`/`not` branches reference
- * `PredicateSchema` itself, which does not exist yet while this module is initialising. Calling it
- * after init is what makes the union introspectable — see `predicateFieldsFor`.
- */
-function predicateUnion() {
-    return z.discriminatedUnion('kind', [
-        z
-            .object({
-            kind: z.literal(PredicateKind.ELEMENT),
-            query: ElementQuerySchema,
-            state: z.nativeEnum(ElementState).optional(),
-            absent: z.boolean().optional(),
-        })
-            .strict(),
-        z
-            .object({
-            kind: z.literal(PredicateKind.TEXT),
-            contains: z.string(),
-            visible: z.boolean().optional(),
-            absent: z.boolean().optional(),
-        })
-            .strict(),
-        z
-            .object({
-            kind: z.literal(PredicateKind.NET),
-            method: z.string().optional(),
-            urlContains: z.string().optional(),
-            status: z.number().optional(),
-            ok: z.boolean().optional(),
-            since: z.number().optional(),
-            count: z.number().int().nonnegative().optional(),
-        })
-            .strict(),
-        z
-            .object({
-            kind: z.literal(PredicateKind.ROUTE),
-            pathname: z.string().optional(),
-            contains: z.string().optional(),
-            since: z.number().optional(),
-        })
-            .strict(),
-        z
-            .object({
-            kind: z.literal(PredicateKind.CONSOLE),
-            level: z.string().optional(),
-            absent: z.boolean().optional(),
-            since: z.number().optional(),
-        })
-            .strict(),
-        z
-            .object({
-            kind: z.literal(PredicateKind.ANIMATION),
-            name: z.string().optional(),
-            target: z.string().optional(),
-            completed: z.boolean().optional(),
-            since: z.number().optional(),
-        })
-            .strict(),
-        z
-            .object({
-            kind: z.literal(PredicateKind.SIGNAL),
-            name: z.string().optional(),
-            dataMatches: z.record(z.unknown()).optional(),
-            since: z.number().optional(),
-        })
-            .strict(),
-        z
-            .object({
-            kind: z.literal(PredicateKind.STATE),
-            store: z.string().optional(),
-            path: z.string(),
-            equals: z.unknown().optional(),
-        })
-            .strict(),
-        z
-            .object({
-            kind: z.literal(PredicateKind.SETTLED),
-            quietMs: z.number().positive().optional(),
-        })
-            .strict(),
-        z
-            .object({ kind: z.literal(PredicateKind.ALL_OF), predicates: z.array(PredicateSchema) })
-            .strict(),
-        z
-            .object({ kind: z.literal(PredicateKind.ANY_OF), predicates: z.array(PredicateSchema) })
-            .strict(),
-        z.object({ kind: z.literal(PredicateKind.NOT), predicate: PredicateSchema }).strict(),
-    ]);
-}
-export const PredicateSchema = z.lazy(() => z.preprocess(applyPredicateAliases, predicateUnion()));
-/**
- * The fields a given predicate kind accepts, read off the schema itself.
- *
- * Derived rather than listed so the two can never disagree: a rejection message that names a stale
- * field set is worse than one that names none, because the agent trusts it and retries into the same
- * wall. Empty for a kind that is not in the union.
- */
-export function predicateFieldsFor(kind) {
-    for (const option of predicateUnion().options) {
-        const literal = option.shape['kind'];
-        if (literal instanceof z.ZodLiteral && literal.value === kind) {
-            return Object.keys(option.shape).filter((field) => 'kind' !== field);
-        }
-    }
-    return [];
-}
-function str(value) {
+// The predicate SHAPE — the discriminated union, its aliases and its zod schema — lives in
+// predicate-schema.ts. Re-exported here so every existing importer of this module is unaffected:
+// the two halves are one public surface, split only because the file outgrew the size backstop.
+export * from './predicate-schema.js';
+export function str(value) {
     return 'string' === typeof value ? value : undefined;
 }
 function num(value) {
@@ -419,8 +140,46 @@ function describeCall(e) {
     const status = num(e.data['status']);
     return status === undefined ? head : `${head} → ${String(status)}`;
 }
+/**
+ * How much of a response body a failure may quote. Enough to see the value that differed on the
+ * bodies this field is used against (a JSON answer), and not a whole payload in every verdict.
+ */
+const MAX_BODY_IN_FAILURE = 200;
+/** Enough of a body to see what differed, without paying for a whole payload in the verdict. */
+function clipBody(body) {
+    return body.length <= MAX_BODY_IN_FAILURE ? body : `${body.slice(0, MAX_BODY_IN_FAILURE)}…`;
+}
+/**
+ * The filter as APPLIED, every field of it.
+ *
+ * The count failure used to print `{method, urlContains, status}` while `ok` and `bodyContains` were
+ * applied too, so the caller was shown a predicate it had not written and told nothing matched it.
+ * A printed filter that is narrower than the real one is worse than none: it is believed.
+ */
+function describeNetFilter(p) {
+    const { kind: _kind, count: _count, since: _since, ...filter } = p;
+    return JSON.stringify(filter);
+}
 export function evalNet(events, p) {
     const since = p.since ?? 0;
+    /**
+     * Did any call match everything EXCEPT the body assertion, while carrying no recorded body?
+     *
+     * Bodies are opt-in, so without them a body predicate can never hold — and "no call matched" would
+     * send the caller to check the url and the method, which are both fine, instead of to the one
+     * setting that makes the assertion possible. Tracked while filtering rather than recomputed after,
+     * because it is the same pass over the same events.
+     */
+    let matchedButUnrecorded = false;
+    /**
+     * The response body of a call that matched everything EXCEPT the body assertion, and HAD one.
+     *
+     * Reported by the first field user of `bodyContains`: a body mismatch was formatted as
+     * "expected 1 network call(s) matching {method, urlContains, status}, saw 0" — the body assertion
+     * was applied but not printed — so the verdict read "the request never fired" and sent them hunting
+     * a UI wiring bug that did not exist, when the defect was the value the server answered with.
+     */
+    let bodyMismatch;
     const matches = events.filter((e) => {
         if (e.type !== EventType.NET_REQUEST || e.t < since)
             return false;
@@ -435,8 +194,43 @@ export function evalNet(events, p) {
             return false;
         if (p.ok !== undefined && callSucceeded(d) !== p.ok)
             return false;
+        if (p.bodyContains !== undefined) {
+            // The RESPONSE body only, and this is the whole point of the field. Searching the request too
+            // would let `bodyContains: "1187.01"` pass on the very defect it exists to catch: the app SENT
+            // that number, so it is in the request whatever the server then did with it. The server's answer
+            // is the one channel a UI cannot fake.
+            const response = str(d['responseBody']);
+            if (response === undefined) {
+                matchedButUnrecorded = true;
+                return false;
+            }
+            if (!response.includes(p.bodyContains)) {
+                bodyMismatch ??= response;
+                return false;
+            }
+        }
         return true;
     });
+    if (matchedButUnrecorded && 0 === matches.length) {
+        return {
+            pass: false,
+            failureReason: `a call matched but its body was not recorded, so \`bodyContains\` could not be checked — enable it where the app calls connect(): reticle({ captureNetworkBodies: true })`,
+            observed: 'a matching call with no recorded body',
+            expected: `a body containing ${JSON.stringify(p.bodyContains)}`,
+            assertion: 'net.bodyContains',
+        };
+    }
+    if (bodyMismatch !== undefined && 0 === matches.length) {
+        // The call is there and its body is there; only the VALUE differs. Counting it as zero matches
+        // points at the wiring, which is the one place the defect is not.
+        return {
+            pass: false,
+            failureReason: `a call matching ${describeNetFilter(p)} was made and answered ${JSON.stringify(clipBody(bodyMismatch))}, which does not contain ${JSON.stringify(p.bodyContains)} — the request fired, the response value is what differed`,
+            observed: `response body ${JSON.stringify(clipBody(bodyMismatch))}`,
+            expected: `a response body containing ${JSON.stringify(p.bodyContains)}`,
+            assertion: 'net.bodyContains',
+        };
+    }
     // `count` (exact) turns presence into a cardinality assertion — catches the double-submit /
     // useEffect-double-fire / retry-storm regression class, where the request DID fire (presence passes)
     // but fired the WRONG number of times. Without `count`, the matcher is presence-only (≥1).
@@ -445,9 +239,13 @@ export function evalNet(events, p) {
             ? { pass: true, evidence: { matched: matches.length } }
             : {
                 pass: false,
-                failureReason: `expected ${String(p.count)} network call(s) matching ${JSON.stringify({ method: p.method, urlContains: p.urlContains, status: p.status })}, saw ${String(matches.length)}`,
+                // Monotonic: more matches than asked for can never become exactly the number asked for.
+                // This is the double-submit — two writes 59ms apart — so the finding that matters most was
+                // also the one that took the caller's whole budget to report.
+                ...(matches.length > p.count ? { decided: true } : {}),
+                failureReason: `expected ${String(p.count)} network call(s) matching ${describeNetFilter(p)}, saw ${String(matches.length)}`,
                 observed: `${String(matches.length)} matching network call(s)`,
-                expected: `exactly ${String(p.count)} matching ${JSON.stringify({ method: p.method, urlContains: p.urlContains, status: p.status })}`,
+                expected: `exactly ${String(p.count)} matching ${describeNetFilter(p)}`,
                 assertion: 'net.count',
             };
     }
@@ -464,45 +262,6 @@ export function evalNet(events, p) {
             assertion: 'net.present',
         };
 }
-export function evalRoute(events, p) {
-    const routes = events.filter((e) => e.type === EventType.ROUTE_CHANGE);
-    const last = routes.at(-1);
-    if (last === undefined) {
-        return {
-            pass: false,
-            failureReason: 'no route change observed',
-            observed: 'no route change in the window',
-            expected: `a route change to ${p.pathname ?? p.contains ?? 'any route'}`,
-            assertion: 'route.changed',
-        };
-    }
-    const pathname = str(last.data['pathname']) ?? str(last.data['to']) ?? '';
-    if (p.pathname !== undefined && pathname !== p.pathname) {
-        return {
-            pass: false,
-            failureReason: `route is '${pathname}', expected '${p.pathname}'`,
-            observed: `route '${pathname}'`,
-            expected: `route '${p.pathname}'`,
-            assertion: 'route.pathname',
-        };
-    }
-    // `contains` matches the WHOLE route — path + query + fragment — while `pathname` above stays an
-    // exact path match. A hash router keeps the entire route in the fragment, so matching pathname
-    // alone made `contains` unsatisfiable for every HashRouter app; that is the standard router for a
-    // packaged Electron/Tauri renderer, where an absolute pushState would rewrite the URL to a
-    // nonexistent file.
-    const fullRoute = `${pathname}${str(last.data['search']) ?? ''}${str(last.data['hash']) ?? ''}`;
-    if (p.contains !== undefined && !fullRoute.includes(p.contains)) {
-        return {
-            pass: false,
-            failureReason: `route '${fullRoute}' does not contain '${p.contains}'`,
-            observed: `route '${fullRoute}'`,
-            expected: `a route containing '${p.contains}'`,
-            assertion: 'route.contains',
-        };
-    }
-    return { pass: true, evidence: last.data };
-}
 /** The only console levels Reticle instruments (console.info/debug/trace are NOT patched). */
 const CONSOLE_LEVEL_TYPE = {
     log: EventType.CONSOLE_LOG,

package/dist/events/predicate-parse.js

@@ -15,8 +15,36 @@
 import { z } from 'zod';
 import { PredicateKind } from '@reticlehq/core';
 import { PredicateSchema, predicateFieldsFor } from './predicate-eval.js';
-/** A valid call, short enough to sit inside an error without becoming the error. */
-const EXAMPLE = '{ kind: "signal", name: "todos:loaded" }';
+/**
+ * One valid call PER KIND, because an example of another kind answers a question nobody asked.
+ *
+ * This was a single `signal` example shown for every rejection. Watched on a real drive: an agent got
+ * the `element` shape wrong, was shown a `signal` example, got `element` wrong again, and was shown
+ * the same `signal` example. A rejected predicate produces no verdict at all, so each of those was a
+ * round trip that ended with nothing — and the one field an agent most needs (`element`'s nested
+ * `query`) is exactly what a flat example cannot convey.
+ *
+ * Short by design: an example that grows past a line stops being read.
+ */
+const EXAMPLES = {
+    [PredicateKind.ELEMENT]: '{ kind: "element", query: { role: "button", name: "Save" } }',
+    [PredicateKind.TEXT]: '{ kind: "text", contains: "Saved" }',
+    [PredicateKind.NET]: '{ kind: "net", method: "POST", urlContains: "/api/save", status: 200 }',
+    [PredicateKind.ROUTE]: '{ kind: "route", pathname: "/dashboard" }',
+    [PredicateKind.CONSOLE]: '{ kind: "console", level: "error", absent: true }',
+    [PredicateKind.ANIMATION]: '{ kind: "animation", name: "slide-in", completed: true }',
+    [PredicateKind.SIGNAL]: '{ kind: "signal", name: "todos:loaded" }',
+    [PredicateKind.STATE]: '{ kind: "state", path: "cart.total", equals: 0 }',
+    [PredicateKind.SETTLED]: '{ kind: "settled" }',
+    [PredicateKind.ALL_OF]: '{ kind: "allOf", predicates: [{ kind: "text", contains: "Saved" }, { kind: "console", level: "error", absent: true }] }',
+    [PredicateKind.ANY_OF]: '{ kind: "anyOf", predicates: [{ kind: "text", contains: "Saved" }, { kind: "text", contains: "Updated" }] }',
+    [PredicateKind.NOT]: '{ kind: "not", predicate: { kind: "text", contains: "Error" } }',
+};
+/** The fallback, for when the KIND itself is the mistake and there is no shape to demonstrate. */
+const GENERIC_EXAMPLE = '{ kind: "text", contains: "Saved" }';
+function exampleFor(kind) {
+    return EXAMPLES[kind] ?? GENERIC_EXAMPLE;
+}
 /** `path: ["net","urlContains"]` → `net.urlContains`; an empty path means the object itself. */
 function pathOf(issue) {
     return 0 === issue.path.length ? 'the predicate' : issue.path.map(String).join('.');
@@ -51,7 +79,7 @@ export function parsePredicate(input) {
     const issues = parsed.error.issues.slice(0, 3).map(describeIssue).join('; ');
     throw new Error(`that predicate did not parse (kind "${kind}"): ${issues}. Nothing ran — the predicate was ` +
         `not evaluated, so no verdict was produced. ${accepted(kind)} ` +
-        `A valid call looks like: ${EXAMPLE}`);
+        `A valid ${kind} predicate looks like: ${exampleFor(kind)}`);
 }
 /**
  * What WOULD have worked, in the same breath as what did not.

package/dist/events/predicate-route.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The `route` oracle. Split out of predicate-eval.ts, which was at the file-size backstop.
+ *
+ * Route is the one predicate with TWO sources of truth — a navigation inside the window and where the
+ * app is right now — and keeping that reconciliation in one place is what makes it readable.
+ */
+import { PredicateKind, type ReticleEvent } from '@reticlehq/core';
+import { type EvalResult, type Predicate } from './predicate-eval.js';
+/**
+ * Which fact answered a `route` predicate: a navigation inside the window, or where the app is now.
+ *
+ * Reported on every route result because the two are different claims. "It changed to /login" proves
+ * a redirect; "it was already /login" does not, and an agent asserting a post-login redirect has to
+ * be able to tell them apart. Silently conflating them would trade one wrong verdict for another.
+ */
+export declare const RouteDecidedBy: {
+    readonly CHANGE: "route-change";
+    readonly CURRENT: "current-route";
+};
+export declare function evalRoute(events: ReticleEvent[], p: Extract<Predicate, {
+    kind: typeof PredicateKind.ROUTE;
+}>, 
+/**
+ * Where the app is RIGHT NOW, if the caller can say.
+ *
+ * Without it a route predicate could only ever be answered by a navigation inside the window, so
+ * "did the session survive a reload?" — which by definition produces no route change — and "we
+ * landed on /login" after a completed navigate were both a guaranteed false red, contradicted by
+ * `reticle_snapshot({ mode: 'status' }).route` one call later. Optional so a caller with no session
+ * (a replayed window) keeps the old answer instead of inventing a route.
+ */
+currentUrl?: string): EvalResult;