@reticlehq/server 2.7.0 → 2.9.0

package/dist/events/predicate-eval.js

@@ -1,197 +1,10 @@
-import { ElementQuerySchema, ElementState, EventType, PredicateKind, 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',
-];
-/** 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) {
@@ -256,7 +69,37 @@ export function matchValue(got, want) {
         }
         return true;
     }
-    return got === want;
+    return structurallyEqual(got, want);
+}
+/**
+ * Value equality for the leaf comparison, because `===` could never match a literal.
+ *
+ * The expected side of a predicate is parsed out of the agent's JSON, so it is a fresh object every
+ * time — reference equality made `equals: ["a", "b"]` false against a store holding exactly
+ * `["a", "b"]`, and there was no value of the app's state that could have made it true. The mirror of
+ * a false green: an assertion nobody could satisfy, on the commonest thing there is to assert about.
+ *
+ * Deliberately strict about shape. An array is not an object, an extra key is a difference, and order
+ * is part of a list's value — `equals` means equals; `dataMatches` is the field-by-field one.
+ */
+function structurallyEqual(got, want) {
+    if (got === want)
+        return true;
+    if (null === got || null === want)
+        return false;
+    if ('object' !== typeof got || 'object' !== typeof want)
+        return false;
+    if (Array.isArray(got) !== Array.isArray(want))
+        return false;
+    if (Array.isArray(got) && Array.isArray(want)) {
+        return got.length === want.length && got.every((v, i) => structurallyEqual(v, want[i]));
+    }
+    const a = got;
+    const b = want;
+    const keys = Object.keys(a);
+    if (keys.length !== Object.keys(b).length)
+        return false;
+    return keys.every((k) => k in b && structurallyEqual(a[k], b[k]));
 }
 /** Shallow JSON pattern match: each key in `pattern` must match (see matchValue). */
 function dataMatches(actual, pattern) {
@@ -297,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;
@@ -313,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).
@@ -323,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',
             };
     }
@@ -342,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,
@@ -486,7 +367,7 @@ export function evalSignal(events, p) {
             ? `signal '${p.name ?? '(any)'}' fired ${String(sameName.length)}x, payload: ${JSON.stringify(sameName[0])}`
             : // Name what DID fire: a typo'd signal name and a genuinely dead action produce the same
                 // sentence otherwise, and the agent cannot tell them apart. See observed-in-window.ts.
-                `signal '${p.name ?? '(any)'}' never fired — ${describeObserved('signals', events.filter((e) => e.type === EventType.SIGNAL).map((e) => str(e.data['name']) ?? ''))}`,
+                `signal '${p.name ?? '(any)'}' never fired; ${describeObserved('signals', events.filter((e) => e.type === EventType.SIGNAL).map((e) => str(e.data['name']) ?? ''))}`,
         expected: p.dataMatches === undefined
             ? `signal '${p.name ?? '(any)'}' to fire`
             : `signal '${p.name ?? '(any)'}' with payload matching ${JSON.stringify(p.dataMatches)}`,

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;

package/dist/events/predicate-route.js

@@ -0,0 +1,102 @@
+/**
+ * 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 { EventType, PredicateKind } from '@reticlehq/core';
+import { str } 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 const RouteDecidedBy = {
+    CHANGE: 'route-change',
+    CURRENT: 'current-route',
+};
+/**
+ * The session's live URL, split the way a route-change event already carries it.
+ *
+ * Absolute (that is what the session tracks), but a relative value is accepted rather than thrown
+ * away — an unreadable URL is not worth losing the fallback over.
+ */
+function readCurrentRoute(url) {
+    const parsed = URL.canParse(url) ? new URL(url) : undefined;
+    const pathname = parsed?.pathname ?? url;
+    const search = parsed?.search ?? '';
+    const hash = parsed?.hash ?? '';
+    return {
+        pathname,
+        full: `${pathname}${search}${hash}`,
+        decidedBy: RouteDecidedBy.CURRENT,
+        data: { pathname, search, hash, url, decidedBy: RouteDecidedBy.CURRENT },
+    };
+}
+/** Name the source in the prose too — the structured `decidedBy` is for the agent, this is for a log. */
+function describeRouteSource(reading) {
+    return reading.decidedBy === RouteDecidedBy.CHANGE
+        ? 'route changed to'
+        : 'current route (no route change in the window)';
+}
+export function evalRoute(events, p, 
+/**
+ * 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) {
+    const routes = events.filter((e) => e.type === EventType.ROUTE_CHANGE);
+    const last = routes.at(-1);
+    const reading = last !== undefined
+        ? {
+            pathname: str(last.data['pathname']) ?? str(last.data['to']) ?? '',
+            full: `${str(last.data['pathname']) ?? str(last.data['to']) ?? ''}${str(last.data['search']) ?? ''}${str(last.data['hash']) ?? ''}`,
+            decidedBy: RouteDecidedBy.CHANGE,
+            data: { ...last.data, decidedBy: RouteDecidedBy.CHANGE },
+        }
+        : currentUrl === undefined || 0 === currentUrl.length
+            ? undefined
+            : readCurrentRoute(currentUrl);
+    if (reading === 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 = reading.pathname;
+    if (p.pathname !== undefined && pathname !== p.pathname) {
+        return {
+            pass: false,
+            failureReason: `${describeRouteSource(reading)} is '${pathname}', expected '${p.pathname}'`,
+            observed: `${describeRouteSource(reading)} '${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 = reading.full;
+    if (p.contains !== undefined && !fullRoute.includes(p.contains)) {
+        return {
+            pass: false,
+            failureReason: `${describeRouteSource(reading)} '${fullRoute}' does not contain '${p.contains}'`,
+            observed: `${describeRouteSource(reading)} '${fullRoute}'`,
+            expected: `a route containing '${p.contains}'`,
+            assertion: 'route.contains',
+        };
+    }
+    return { pass: true, evidence: reading.data };
+}