@reticlehq/server 2.11.0 → 2.13.0

package/dist/events/event-filters.js

@@ -1,4 +1,4 @@
-import { EventType } from '@reticlehq/core';
+import { EventType, URL_RAW, urlForMatch } from '@reticlehq/core';
 import { asString, asNumber } from '../tools/tools-helpers.js';
 import { mergeNetworkDetail } from '../input/network-detail.js';
 /**
@@ -55,7 +55,7 @@ export function matchNet(e, method, urlContains, status, ok) {
     if (method !== undefined && asString(d['method'])?.toUpperCase() !== method.toUpperCase()) {
         return false;
     }
-    if (urlContains !== undefined && !(asString(d['url']) ?? '').includes(urlContains)) {
+    if (urlContains !== undefined && !urlForMatch(d).includes(urlContains)) {
         return false;
     }
     if (status !== undefined && asNumber(d['status']) !== status)
@@ -86,6 +86,23 @@ export function reconcileNet(events) {
         .map((e) => ({ ...e, data: { ...e.data, status: 'pending', pending: true } }));
     return [...completed, ...unresolved].sort((a, b) => a.t - b.t);
 }
+/**
+ * Strip the grader-only raw URL before an event is rendered to the agent.
+ *
+ * `urlRaw` exists so `urlContains` can match a path redaction rewrote. It is a secret-bearing field
+ * by construction (the whole reason `url` was redacted) and must never appear in observe, evidence,
+ * or a network listing.
+ */
+export function withoutUrlRaw(event) {
+    if (typeof event !== 'object' || null === event)
+        return event;
+    const rec = event;
+    const data = rec['data'];
+    if (typeof data !== 'object' || null === data || !(URL_RAW in data))
+        return event;
+    const { [URL_RAW]: _raw, ...rest } = data;
+    return { ...rec, data: rest };
+}
 export function projectNetCall(e, includeBodies = true) {
     const status = e.data['status'];
     const ms = asNumber(e.data['durationMs']);

package/dist/events/observed-in-window.d.ts

@@ -10,3 +10,15 @@
  * not do what you thought) versus things happened but not that one (you named it wrong).
  */
 export declare function describeObserved(noun: string, seen: readonly string[]): string;
+/**
+ * The third answer, and the one this file existed to make room for: things happened, and they belong
+ * to a document that has since been replaced.
+ *
+ * `describeObserved` already separates "nothing happened" from "things happened but not that one",
+ * because those need different fixes. A window whose evidence was discarded as superseded is a third
+ * case needing a third fix, and it is the one that reads most like the first: everything that could
+ * have answered the question is gone, so a bare "nothing happened in this window" is available and
+ * wrong. The remedy is in the sentence, because an agent that cannot act on a caveat learns to skip
+ * it — here the remedy is to drive the action again against the page now on screen.
+ */
+export declare function describeSuperseded(noun: string, count: number): string;

package/dist/events/observed-in-window.js

@@ -19,3 +19,20 @@ export function describeObserved(noun, seen) {
     const rest = unique.length - shown.length;
     return `${noun} seen in this window: ${shown.join(', ')}${rest > 0 ? `, and ${String(rest)} more` : ''}`;
 }
+/**
+ * The third answer, and the one this file existed to make room for: things happened, and they belong
+ * to a document that has since been replaced.
+ *
+ * `describeObserved` already separates "nothing happened" from "things happened but not that one",
+ * because those need different fixes. A window whose evidence was discarded as superseded is a third
+ * case needing a third fix, and it is the one that reads most like the first: everything that could
+ * have answered the question is gone, so a bare "nothing happened in this window" is available and
+ * wrong. The remedy is in the sentence, because an agent that cannot act on a caveat learns to skip
+ * it — here the remedy is to drive the action again against the page now on screen.
+ */
+export function describeSuperseded(noun, count) {
+    return (`no ${noun} belong to the document currently on screen: ${String(count)} ${noun} were observed ` +
+        `and every one of them belongs to a document that has since been replaced (the page reloaded or ` +
+        `navigated). This says nothing about the app — the evidence went away with the page that produced ` +
+        `it. Re-drive the action against the page now on screen`);
+}

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

@@ -15,3 +15,16 @@ import type { Predicate } from './predicate-schema.js';
  * that reads as the subject of an unrelated test is a half-hour somebody loses later.
  */
 export declare function declaresState(predicate: Predicate): boolean;
+/**
+ * Does the caller's predicate judge the DOM — an `element` or `text` clause anywhere in the tree?
+ *
+ * The question behind it is where a verdict is allowed to point. A DOM predicate has its own locus:
+ * the element it matched, whose `file:line` the descriptor already carries. A `signal`/`net`/`state`
+ * failure has none — there is no node for "the request was never made" — and that is the one case
+ * where the verdict borrows the last driven control's line, because the handler that should have
+ * fired lives there.
+ *
+ * Walks composites for the same reason `declaresState` does: `allOf[{element}, {signal}]` looked at
+ * the DOM exactly as much as a bare `{element}` did.
+ */
+export declare function declaresDom(predicate: Predicate): boolean;

package/dist/events/predicate-asks.js

@@ -24,3 +24,25 @@ export function declaresState(predicate) {
         return declaresState(predicate.predicate);
     return false;
 }
+/**
+ * Does the caller's predicate judge the DOM — an `element` or `text` clause anywhere in the tree?
+ *
+ * The question behind it is where a verdict is allowed to point. A DOM predicate has its own locus:
+ * the element it matched, whose `file:line` the descriptor already carries. A `signal`/`net`/`state`
+ * failure has none — there is no node for "the request was never made" — and that is the one case
+ * where the verdict borrows the last driven control's line, because the handler that should have
+ * fired lives there.
+ *
+ * Walks composites for the same reason `declaresState` does: `allOf[{element}, {signal}]` looked at
+ * the DOM exactly as much as a bare `{element}` did.
+ */
+export function declaresDom(predicate) {
+    if (predicate.kind === PredicateKind.ELEMENT || predicate.kind === PredicateKind.TEXT)
+        return true;
+    if (predicate.kind === PredicateKind.ALL_OF || predicate.kind === PredicateKind.ANY_OF) {
+        return predicate.predicates.some(declaresDom);
+    }
+    if (predicate.kind === PredicateKind.NOT)
+        return declaresDom(predicate.predicate);
+    return false;
+}

package/dist/events/predicate-eval.js

@@ -1,5 +1,6 @@
-import { EventType, PredicateKind, StreamDirection, isDevToolingUrl, } from '@reticlehq/core';
+import { EventType, PredicateKind, StreamDirection, isDevToolingUrl, urlForMatch, REDACTED_VALUE, } from '@reticlehq/core';
 import { describeObserved } from './observed-in-window.js';
+import { withoutUrlRaw } from './event-filters.js';
 // 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.
@@ -140,6 +141,26 @@ function describeCall(e) {
     const status = num(e.data['status']);
     return status === undefined ? head : `${head} → ${String(status)}`;
 }
+/**
+ * What a miss should say when the displayed URL was redacted. Matching uses `urlRaw` when present;
+ * an older SDK has no copy, and this is the sentence both reporters asked for.
+ */
+const REDACTED_PATH_HINT = 'this path segment was redacted — the literal you matched may be here, try bodyContains';
+function observedNetCalls(events, urlContains) {
+    const calls = events.filter((e) => e.type === EventType.NET_REQUEST);
+    const base = describeObserved('calls', calls.map(describeCall));
+    if (urlContains === undefined)
+        return base;
+    const encoded = encodeURIComponent(REDACTED_VALUE);
+    const redacted = calls.some((e) => {
+        const url = str(e.data['url']) ?? '';
+        return url.includes(REDACTED_VALUE) || url.includes(encoded);
+    });
+    return redacted ? `${base}; ${REDACTED_PATH_HINT}` : base;
+}
+function netEvidence(data) {
+    return withoutUrlRaw({ data }).data;
+}
 /**
  * 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.
@@ -160,6 +181,35 @@ function describeNetFilter(p) {
     const { kind: _kind, count: _count, since: _since, ...filter } = p;
     return JSON.stringify(filter);
 }
+/** Same, for a signal: the matcher as applied, with the cardinality and the floor taken out. */
+function describeSignalFilter(p) {
+    const { kind: _kind, count: _count, since: _since, ...filter } = p;
+    return JSON.stringify(filter);
+}
+/**
+ * Exact cardinality, once, for every channel that can count its matches.
+ *
+ * `net` and `signal` are the same assertion over different evidence — "this happened EXACTLY n
+ * times" — and the interesting half is the same on both: an over-count is `decided`, because a
+ * window only accumulates and a count cannot come back down, so waiting out the rest of the budget
+ * to report a double-fire buys nothing but latency.
+ *
+ * `noun` names the population in prose ("network call(s)", "signal(s)"), `filter` is the matcher as
+ * applied, and `assertion` is the oracle that judged it.
+ */
+function evalExactCount(args) {
+    const { matched, want, noun, filter, assertion } = args;
+    if (matched === want)
+        return { pass: true, evidence: { matched } };
+    return {
+        pass: false,
+        ...(matched > want ? { decided: true } : {}),
+        failureReason: `expected ${String(want)} ${noun} matching ${filter}, saw ${String(matched)}`,
+        observed: `${String(matched)} matching ${noun}`,
+        expected: `exactly ${String(want)} matching ${filter}`,
+        assertion,
+    };
+}
 /**
  * URL suffixes only the DOCUMENT fetches, which the network observer therefore never records.
  *
@@ -285,6 +335,12 @@ export function evalNet(events, p) {
      * a UI wiring bug that did not exist, when the defect was the value the server answered with.
      */
     let bodyMismatch;
+    /**
+     * The prefix of a TRUNCATED body the needle was not found in. Held apart from `bodyMismatch`
+     * because the two are different verdicts: a full body without the needle decides the assertion,
+     * a truncated one cannot (#614).
+     */
+    let truncatedBody;
     const matches = events.filter((e) => {
         if (e.type !== EventType.NET_REQUEST || e.t < since)
             return false;
@@ -292,7 +348,7 @@ export function evalNet(events, p) {
         if (p.method !== undefined && str(d['method'])?.toUpperCase() !== p.method.toUpperCase()) {
             return false;
         }
-        if (p.urlContains !== undefined && !(str(d['url']) ?? '').includes(p.urlContains)) {
+        if (p.urlContains !== undefined && !urlForMatch(d).includes(p.urlContains)) {
             return false;
         }
         if (p.status !== undefined) {
@@ -321,6 +377,15 @@ export function evalNet(events, p) {
                 return false;
             }
             if (!response.includes(p.bodyContains)) {
+                // A needle missing from a body we only hold the FIRST N BYTES of is undecidable, not
+                // absent: the rest of the response was never recorded, so nothing here can say whether it
+                // was in there (#614). Grading it `pass: false` with "the response value is what differed"
+                // is the inversion the honesty rules exist to prevent — an unknown reported as decided,
+                // against a response that was very likely correct.
+                if (true === d['responseBodyTruncated']) {
+                    truncatedBody ??= response;
+                    return false;
+                }
                 bodyMismatch ??= response;
                 return false;
             }
@@ -348,6 +413,18 @@ export function evalNet(events, p) {
             assertion: 'net.bodyContains',
         };
     }
+    // Ranked ABOVE the mismatch branch: when both a truncated and a full body missed the needle,
+    // the honest verdict is the undecidable one. Deciding on the full body would report a failure
+    // the truncated call may well contradict.
+    if (truncatedBody !== undefined && 0 === matches.length) {
+        return {
+            pass: false,
+            inconclusive: `a call matching ${describeNetFilter(p)} was answered with a body that was TRUNCATED before it was recorded, and ${JSON.stringify(p.bodyContains)} is not in the part that was kept — so this is undecidable, not a failure. Raise the capture cap or assert on something inside the recorded prefix`,
+            observed: `the first ${String(truncatedBody.length)} characters of a truncated response body ${JSON.stringify(clipBody(truncatedBody))}`,
+            expected: `a response 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.
@@ -363,26 +440,24 @@ export function evalNet(events, p) {
     // 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).
     if (p.count !== undefined) {
-        return matches.length === p.count
-            ? { pass: true, evidence: { matched: matches.length } }
-            : 0 === matches.length && targetsUnobservedChannel(p) && !sawSubresources
-                ? {
-                    pass: false,
-                    failureReason: unobservedChannelReason(p),
-                    inconclusive: unobservedChannelReason(p),
-                    assertion: 'net.count',
-                }
-                : {
-                    pass: false,
-                    // 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 ${describeNetFilter(p)}`,
-                    assertion: 'net.count',
-                };
+        if (matches.length !== p.count &&
+            0 === matches.length &&
+            targetsUnobservedChannel(p) &&
+            !sawSubresources) {
+            return {
+                pass: false,
+                failureReason: unobservedChannelReason(p),
+                inconclusive: unobservedChannelReason(p),
+                assertion: 'net.count',
+            };
+        }
+        return evalExactCount({
+            matched: matches.length,
+            want: p.count,
+            noun: 'network call(s)',
+            filter: describeNetFilter(p),
+            assertion: 'net.count',
+        });
     }
     const hit = matches[0];
     if (hit === undefined && targetsUnobservedChannel(p) && !sawSubresources) {
@@ -391,19 +466,19 @@ export function evalNet(events, p) {
             pass: false,
             failureReason: reason,
             inconclusive: reason,
-            observed: describeObserved('calls', events.filter((e) => e.type === EventType.NET_REQUEST).map(describeCall)),
+            observed: observedNetCalls(events, p.urlContains),
             expected: `at least one call matching ${describeNetFilter(p)}`,
             assertion: 'net.unobserved-channel',
         };
     }
     return hit !== undefined
-        ? { pass: true, evidence: hit.data }
+        ? { pass: true, evidence: netEvidence(hit.data) }
         : {
             pass: false,
             failureReason: `no network call matched ${JSON.stringify(p)}`,
             // Same reasoning as the signal miss: "no matching call" cannot be told apart from "the app
             // made no calls at all", and those need different fixes.
-            observed: describeObserved('calls', events.filter((e) => e.type === EventType.NET_REQUEST).map(describeCall)),
+            observed: observedNetCalls(events, p.urlContains),
             expected: `at least one call matching ${JSON.stringify(p)}`,
             assertion: 'net.present',
         };
@@ -527,7 +602,7 @@ export function evalAnimation(events, p) {
         };
 }
 export function evalSignal(events, p) {
-    const hit = events.find((e) => {
+    const isMatch = (e) => {
         if (e.type !== EventType.SIGNAL)
             return false;
         if (p.name !== undefined && str(e.data['name']) !== p.name)
@@ -538,7 +613,22 @@ export function evalSignal(events, p) {
                 return false;
         }
         return true;
-    });
+    };
+    // `count` (exact) turns presence into a cardinality assertion, exactly as it does on `net`. The
+    // double-fire is invisible to every state-only oracle — a handler wired twice leaves the store in
+    // the right shape and fires the signal twice — and so is the wrong-name fire, where the intended
+    // signal fires once beside a mistyped sibling and a presence check cannot say which is which.
+    // Counting only what the MATCHER matched is what separates them. Omit = presence (≥1).
+    if (p.count !== undefined) {
+        return evalExactCount({
+            matched: events.filter(isMatch).length,
+            want: p.count,
+            noun: 'signal(s)',
+            filter: describeSignalFilter(p),
+            assertion: 'signal.count',
+        });
+    }
+    const hit = events.find(isMatch);
     if (hit !== undefined)
         return { pass: true, evidence: hit.data };
     // Near-miss: show signals that fired with the same name (so the agent sees the real data).

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

@@ -14,10 +14,4 @@
  */
 import { z } from 'zod';
 import { PredicateSchema } from './predicate-eval.js';
-/**
- * Parse a predicate, or throw an Error whose message is a sentence.
- *
- * Deliberately still THROWS: every call site already handles a throw, and turning this into a
- * result type would mean touching three handlers to gain nothing the message does not already say.
- */
 export declare function parsePredicate(input: unknown): z.infer<typeof PredicateSchema>;

package/dist/events/predicate-parse.js

@@ -67,7 +67,35 @@ function describeIssue(issue) {
  * Deliberately still THROWS: every call site already handles a throw, and turning this into a
  * result type would mean touching three handlers to gain nothing the message does not already say.
  */
+/**
+ * The placeholder `verify_next` puts in the `until` it suggests, sent back unchanged.
+ *
+ * The nudge hands the agent a ready-made `act_and_wait` call with `ref` and `action` filled in from
+ * the act that dispatched, and leaves the consequence blank on purpose: naming it is the one part
+ * only the agent can know, and guessing would be Reticle inventing the assertion.
+ *
+ * Sent verbatim it parses as a perfectly valid text predicate that simply never matches, so the
+ * verdict came back `verified:"no"` / "the declared consequence did not hold" — blaming the app for
+ * a placeholder the agent forgot to replace, and sending it to hunt a defect that does not exist.
+ * Measured on a live app before this guard: a confident, wrong, actionable-looking answer, which is
+ * the exact failure the rest of this file exists to avoid.
+ */
+const UNFILLED_PLACEHOLDER = /^<name the consequence/i;
+function placeholderValue(input) {
+    if ('object' !== typeof input || null === input)
+        return undefined;
+    const value = input['value'];
+    return 'string' === typeof value && UNFILLED_PLACEHOLDER.test(value) ? value : undefined;
+}
 export function parsePredicate(input) {
+    const unfilled = placeholderValue(input);
+    if (unfilled !== undefined) {
+        throw new Error(`that predicate still carries the placeholder from verify_next ("${unfilled}"). Nothing ran, ` +
+            'and no verdict was produced — which is deliberate: as written it would have failed and ' +
+            'blamed the app for a value you had not filled in yet. Replace it with the consequence ' +
+            'this action actually causes, and prefer one the action CHANGES: a signal, a request, a ' +
+            'route, or store state. Text on screen that was already there proves nothing.');
+    }
     const parsed = PredicateSchema.safeParse(input);
     if (parsed.success)
         return parsed.data;
@@ -78,7 +106,7 @@ export function parsePredicate(input) {
     // back is how the zod array became unreadable in the first place.
     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)} ` +
+        `not evaluated, so no verdict was produced. ${accepted(kind, parsed.error.issues)} ` +
         `A valid ${kind} predicate looks like: ${exampleFor(kind)}`);
 }
 /**
@@ -88,12 +116,24 @@ export function parsePredicate(input) {
  * round trip on the one call path that produces verdicts. Naming the accepted fields — or, when the
  * kind itself is the mistake, the accepted kinds — makes the retry informed instead.
  */
-function accepted(kind) {
+function accepted(kind, issues) {
     const fields = predicateFieldsFor(kind);
     if (0 < fields.length) {
         // A field whose value is an object is the one an agent cannot guess from its name alone, so
         // expand it in the same breath rather than making the shape a second round trip.
-        const nested = Object.entries(predicateNestedFieldsFor(kind))
+        //
+        // Only the field the rejection actually points at, though. Expanding every object-valued field
+        // of the kind makes the sentence longer the more the schema grows, and buries the one clause
+        // that answers the question asked — the same argument this file already makes for showing one
+        // example per kind instead of a generic one. `element` is the only kind with an object-valued
+        // field today, so the two agree except when the mistake is somewhere else entirely, which is
+        // the case pinned in the tests.
+        const all = predicateNestedFieldsFor(kind);
+        const blamed = new Set(issues
+            .map((issue) => issue.path[0])
+            .filter((field) => 'string' === typeof field));
+        const nested = Object.entries(all)
+            .filter(([field]) => blamed.has(field))
             .map(([field, keys]) => ` ${field} accepts: ${keys.join(', ')}.`)
             .join('');
         return `${kind} accepts: ${fields.join(', ')}.${nested}`;

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

@@ -0,0 +1,8 @@
+/**
+ * The reason this predicate cannot be evaluated, or undefined when it can.
+ *
+ * Only checks what is knowable WITHOUT the page — a locator that names fields the resolver drops is
+ * wrong whatever the DOM contains, which is what makes it safe to refuse before acting. Anything
+ * that depends on what is actually rendered is still decided after the action, where it belongs.
+ */
+export declare function unevaluablePredicateReason(predicate: unknown): string | undefined;

package/dist/events/predicate-precheck.js

@@ -0,0 +1,41 @@
+import { residualQueryChecks } from './predicate-schema.js';
+/** Composite predicates nest; the unusable one can be at any depth. */
+const NESTED_KEYS = ['predicates', 'predicate'];
+const isRecord = (v) => 'object' === typeof v && null !== v;
+/** Every element query in a predicate tree, in the order a reader would meet them. */
+function elementQueries(predicate, found = []) {
+    if (!isRecord(predicate))
+        return found;
+    if (isRecord(predicate['query']))
+        found.push(predicate['query']);
+    for (const key of NESTED_KEYS) {
+        const nested = predicate[key];
+        if (Array.isArray(nested))
+            for (const child of nested)
+                elementQueries(child, found);
+        else if (isRecord(nested))
+            elementQueries(nested, found);
+    }
+    return found;
+}
+/**
+ * The reason this predicate cannot be evaluated, or undefined when it can.
+ *
+ * Only checks what is knowable WITHOUT the page — a locator that names fields the resolver drops is
+ * wrong whatever the DOM contains, which is what makes it safe to refuse before acting. Anything
+ * that depends on what is actually rendered is still decided after the action, where it belongs.
+ */
+export function unevaluablePredicateReason(predicate) {
+    for (const query of elementQueries(predicate)) {
+        const residual = residualQueryChecks(query);
+        if (0 === residual.unusable.length)
+            continue;
+        return (`the element locator ignores ${residual.unusable.map((f) => `\`${f}\``).join(', ')} ` +
+            `in ${JSON.stringify(query)} — it resolves by the first of by+value, component/source, role, ` +
+            'text, label, placeholder, testid, alt that is present, and nothing here can check the rest. ' +
+            'Assert them one locator at a time, or move the extra field into the locator. ' +
+            'Nothing was acted on: this predicate could never have been evaluated, so refusing it costs ' +
+            'you nothing and spending the action on it would have cost you the verdict.');
+    }
+    return undefined;
+}

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

@@ -17,6 +17,20 @@ export declare const RouteDecidedBy: {
     readonly CHANGE: "route-change";
     readonly CURRENT: "current-route";
 };
+/**
+ * The path the router is actually on.
+ *
+ * Under a hash router the document pathname is `/` on every page and the whole route lives in the
+ * fragment — which is why `contains` below matches the full route. `pathname` was left comparing the
+ * document path, so `{ pathname: '/posts/12/show' }` could never pass on a HashRouter app, the
+ * standard router for a packaged Electron/Tauri renderer. That is a guaranteed false red: Reticle
+ * telling a user their working app is broken.
+ *
+ * The fragment WINS rather than being accepted alongside the document path. Honouring both would
+ * make `{ pathname: '/' }` trivially true on every hash-routed page — a green that says nothing
+ * about where the app is, which is the failure this predicate exists to prevent.
+ */
+export declare function routePathOf(pathname: string, hash: string): string;
 export declare function evalRoute(events: ReticleEvent[], p: Extract<Predicate, {
     kind: typeof PredicateKind.ROUTE;
 }>, 

package/dist/events/predicate-route.js

@@ -17,6 +17,26 @@ export const RouteDecidedBy = {
     CHANGE: 'route-change',
     CURRENT: 'current-route',
 };
+/**
+ * The path the router is actually on.
+ *
+ * Under a hash router the document pathname is `/` on every page and the whole route lives in the
+ * fragment — which is why `contains` below matches the full route. `pathname` was left comparing the
+ * document path, so `{ pathname: '/posts/12/show' }` could never pass on a HashRouter app, the
+ * standard router for a packaged Electron/Tauri renderer. That is a guaranteed false red: Reticle
+ * telling a user their working app is broken.
+ *
+ * The fragment WINS rather than being accepted alongside the document path. Honouring both would
+ * make `{ pathname: '/' }` trivially true on every hash-routed page — a green that says nothing
+ * about where the app is, which is the failure this predicate exists to prevent.
+ */
+export function routePathOf(pathname, hash) {
+    if (!hash.startsWith('#/'))
+        return pathname;
+    const withoutHash = hash.slice(1);
+    const query = withoutHash.indexOf('?');
+    return -1 === query ? withoutHash : withoutHash.slice(0, query);
+}
 /**
  * The session's live URL, split the way a route-change event already carries it.
  *
@@ -30,6 +50,7 @@ function readCurrentRoute(url) {
     const hash = parsed?.hash ?? '';
     return {
         pathname,
+        routePath: routePathOf(pathname, hash),
         full: `${pathname}${search}${hash}`,
         decidedBy: RouteDecidedBy.CURRENT,
         data: { pathname, search, hash, url, decidedBy: RouteDecidedBy.CURRENT },
@@ -55,12 +76,17 @@ 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 },
-        }
+        ? (() => {
+            const changedPath = str(last.data['pathname']) ?? str(last.data['to']) ?? '';
+            const changedHash = str(last.data['hash']) ?? '';
+            return {
+                pathname: changedPath,
+                routePath: routePathOf(changedPath, changedHash),
+                full: `${changedPath}${str(last.data['search']) ?? ''}${changedHash}`,
+                decidedBy: RouteDecidedBy.CHANGE,
+                data: { ...last.data, decidedBy: RouteDecidedBy.CHANGE },
+            };
+        })()
         : currentUrl === undefined || 0 === currentUrl.length
             ? undefined
             : readCurrentRoute(currentUrl);
@@ -73,11 +99,13 @@ currentUrl) {
             assertion: 'route.changed',
         };
     }
-    const pathname = reading.pathname;
+    // The ROUTER's path, not the document's — see routePathOf.
+    const pathname = reading.routePath;
     if (p.pathname !== undefined && pathname !== p.pathname) {
         return {
             pass: false,
-            failureReason: `${describeRouteSource(reading)} is '${pathname}', expected '${p.pathname}'`,
+            // No ` is` after the clause: it read "route changed to is '/'".
+            failureReason: `${describeRouteSource(reading)} '${pathname}', expected '${p.pathname}'`,
             observed: `${describeRouteSource(reading)} '${pathname}'`,
             expected: `route '${p.pathname}'`,
             assertion: 'route.pathname',

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

@@ -56,6 +56,11 @@ export type Predicate = {
     kind: typeof PredicateKind.SIGNAL;
     name?: string;
     dataMatches?: Record<string, unknown>;
+    /**
+     * Exact number of matching signals in the window — the same cardinality assertion `net`
+     * carries, on the channel the app itself speaks. Omit for presence (≥1).
+     */
+    count?: number;
     since?: number;
 } | {
     kind: typeof PredicateKind.STATE;
@@ -103,6 +108,45 @@ export declare const PredicateSchema: z.ZodType<Predicate>;
  * wall. Empty for a kind that is not in the union.
  */
 export declare function predicateFieldsFor(kind: string): readonly string[];
+/**
+ * Is this tool parameter ACTUALLY the predicate union?
+ *
+ * Not a name check. `until` is overloaded on this surface — the act/assert family means a predicate
+ * by it, while reticle_observe / _network / _console mean a NUMBER, an upper cursor bound — so any
+ * caller keying on the word would treat a numeric parameter as a predicate and describe it to the
+ * agent as an object. Keying on the schema cannot make that mistake.
+ *
+ * Lives beside the schema because two callers now ask the question: the lean tool surface, which
+ * compacts these parameters, and `reticle_tools`, which spells their grammar out on request. Two
+ * spellings of "is this a predicate" is one chance for the surface and the grammar to disagree.
+ */
+export declare function isPredicateParam(schema: z.ZodTypeAny): boolean;
+/**
+ * Every kind's fields, in one block an agent can write a predicate from.
+ *
+ * The tool surface advertises the KIND list and points at `reticle_tools` for the fields, because
+ * inlining the 12-variant recursive union in the declared JSON Schema costs thousands of characters
+ * per predicate parameter, re-sent every turn, to describe a grammar most calls use one variant of.
+ * That trade is right — but the pointer has to land somewhere, and it landed on a parameter
+ * description reading "same shape as reticle_assert". So the grammar was reachable from nothing, and
+ * an agent that could not find `route`'s fields fell back to a `text` check where a route check was
+ * meant: the weaker oracle, which is the expensive half of an undiscoverable grammar.
+ *
+ * Derived from the schema, like `predicateFieldsFor` and for the same reason: a hand-written grammar
+ * that drifts is worse than none, because the agent trusts it and retries into the same wall.
+ */
+export declare function predicateGrammar(): Readonly<Record<string, string>>;
+/**
+ * The keys of a field that is an object, once its wrappers are peeled. Empty for anything else.
+ *
+ * Exported so the wrapper handling is asserted against THIS function rather than through the
+ * rendered sentence. Reached only that way, a wrapper it fails to peel returns `[]`, the old
+ * message prints unchanged, and nothing reddens — a regression with no symptom.
+ *
+ * No top-level predicate field is currently declared behind a wrapper, so the real schema exercises
+ * none of these paths; that is exactly why they are worth a case each.
+ */
+export declare function nestedKeysOf(schema: z.ZodTypeAny | undefined): readonly string[];
 /**
  * One level into the fields that are themselves objects — `{ query: ['by', 'value', ...] }`.
  *