@reticlehq/server 2.12.0 → 2.13.0

package/dist/events/contradictions.js

@@ -1,4 +1,4 @@
-import { ContradictionKind, EventType, MUTATING_METHODS, isDevToolingUrl, isSameDocument, isSameEditEpoch, } from '@reticlehq/core';
+import { ContradictionKind, EventType, MUTATING_METHODS, isDevToolingUrl, isSameDocument, isThirdPartyUrl, isSameEditEpoch, urlForMatch, } from '@reticlehq/core';
 import { describeSuperseded } from './observed-in-window.js';
 import { findStaleResponses } from './stale-response.js';
 import { findBodyFailures } from './body-failures.js';
@@ -12,6 +12,7 @@ function netCall(e) {
     return {
         method: (asString(e.data['method']) ?? '').toUpperCase(),
         url: asString(e.data['url']) ?? '',
+        matchUrl: urlForMatch(e.data),
         status,
         // `ok` is authoritative when present (IPC sets it explicitly); status is the HTTP fallback.
         // Neither present = no verdict was ever reported, which stays undefined all the way through.
@@ -139,6 +140,45 @@ const NET_TYPES = new Set([
     EventType.NET_REQUEST,
     EventType.NET_STREAM,
 ]);
+/**
+ * Hash-router paths put the route in the fragment (`#/settings`, `#!/home`). An in-page skip link
+ * does not (`#main-content`, `#`, empty). The blank-destination rule must still see the former.
+ */
+function isInPageFragment(hash) {
+    if ('' === hash || '#' === hash)
+        return true;
+    const body = hash.startsWith('#') ? hash.slice(1) : hash;
+    return !body.startsWith('/') && !body.startsWith('!');
+}
+function hrefAsUrl(value) {
+    if (value === undefined || '' === value)
+        return undefined;
+    try {
+        return new URL(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Same origin + pathname + search, different in-page fragment — a skip link, not a new view.
+ *
+ * Returns false when `from`/`to` are missing, so older events without hrefs keep the existing rule.
+ */
+function isSameDocumentHashAnchor(event) {
+    if (event.type !== EventType.ROUTE_CHANGE)
+        return false;
+    const from = hrefAsUrl(asString(event.data['from']));
+    const to = hrefAsUrl(asString(event.data['to']));
+    if (from === undefined || to === undefined)
+        return false;
+    if (from.origin !== to.origin || from.pathname !== to.pathname || from.search !== to.search) {
+        return false;
+    }
+    if (from.hash === to.hash)
+        return false;
+    return isInPageFragment(to.hash);
+}
 /**
  * Split the window into the app's traffic and the dev toolchain's own (see `DevToolingChannel`).
  *
@@ -149,13 +189,15 @@ const NET_TYPES = new Set([
  * every action. The overlay's own 404s and duplicate fetches are the same story on other checks,
  * which is why the split happens ONCE here rather than in the one check that reported it.
  */
-function splitDevTooling(events) {
+function splitForeignTraffic(events, appOrigin) {
     const ignored = [];
     const app = events.filter((e) => {
         if (!NET_TYPES.has(e.type))
             return true;
         const url = asString(e.data['url']);
-        if (!isDevToolingUrl(url))
+        // Somebody else's code, twice over: the toolchain's own channel, and any site that is not the
+        // app under test. Neither can answer the question every rule below asks.
+        if (!isDevToolingUrl(url) && !isThirdPartyUrl(url, appOrigin))
             return true;
         if (url !== undefined && !ignored.includes(url))
             ignored.push(url);
@@ -199,19 +241,19 @@ export function findContradictions(allEvents, options = {}) {
 }
 function findWindowContradictions(allEvents, options) {
     const found = [];
-    const { app: allApp, ignored: ignoredDevTooling } = splitDevTooling(allEvents);
+    const { app: allApp, ignored: ignoredForeign } = splitForeignTraffic(allEvents, options.appOrigin);
     // ── Evidence belonging to a document that has since been replaced ───────────────────────────
     // Scoped ONCE, here, for the same reason the dev-tooling split is: every rule below asks "what
     // else was in this window", and answering that with a dead page's traffic is a defect in all of
     // them rather than in whichever one reported it. Applied after the dev-tooling split so the count
     // reported below is the app's own evidence and not the toolchain's noise.
-    const events = allApp.filter((e) => isSameDocument(e.documentId, options.currentDocumentId));
-    const superseded = allApp.length - events.length;
+    const scoped = allApp.filter((e) => isSameDocument(e.documentId, options.currentDocumentId));
+    const superseded = allApp.length - scoped.length;
     // An empty window was always allowed to mean "nothing happened"; that reading is only unsafe once
     // supersession is what emptied it. Reported ALONE and before every rule below, because a window
     // with nothing left in it is exactly the shape `action-had-no-effect` fires on — so without this
     // the fix would have swapped a wrong citation for a wrong accusation.
-    if (superseded > 0 && 0 === events.length) {
+    if (superseded > 0 && 0 === scoped.length) {
         return [
             {
                 kind: ContradictionKind.EVIDENCE_SUPERSEDED,
@@ -221,6 +263,18 @@ function findWindowContradictions(allEvents, options) {
             },
         ];
     }
+    // ── Evidence that predates the action ───────────────────────────────────────────────────────
+    // The attribution floor, and it is scoped ONCE here for the same reason the two filters above are:
+    // a rule that reads "what else was in this window" and gets handed traffic from before the caller
+    // acted is not refining its answer, it is answering about somebody else's action. Three rules
+    // (`duplicate-request`, `signal-without-consequence`, `consequence-elsewhere`) each checked this
+    // for themselves and the other six swept the whole window — which is how an assert with no `since`
+    // came to be judged against everything that had ever happened in the tab.
+    //
+    // Undefined means nothing attributed the window to an action at all; the floor then does nothing,
+    // and the consequence rules below decline to speak instead. See `advanced`.
+    const floor = options.actionSince;
+    const events = floor === undefined ? scoped : scoped.filter((e) => e.t >= floor);
     const settled = events.filter((e) => e.type === EventType.NET_REQUEST).map(netCall);
     // ── Overlapping reads that settled out of order ─────────────────────────────────────────────
     // Independent of any action, so it runs on every window: the race is a property of the timeline.
@@ -253,7 +307,22 @@ function findWindowContradictions(allEvents, options) {
     // The failures NOBODY declared — see ContradictionOptions.expectedFailures. Only the heuristic
     // "the UI moved while a request failed" rule reads this; the sharp rules still read `failed`.
     const unexpected = failed.filter((c) => !matchesDeclaredFailure(c, options.expectedFailures ?? []));
-    const advanced = uiAdvanced(events);
+    /**
+     * Did the UI move — and is anybody entitled to say so?
+     *
+     * `undefined` is the third answer and the point of the tri-state: "the UI moved forward while a
+     * request failed" is a claim about CAUSATION, and over a window nothing attributed to an action
+     * the two halves merely co-occurred. A passive `reticle_assert` performs nothing, so ambient
+     * traffic — a poll, a page-load bootstrap, a branding call — is not its consequence and must not
+     * decide its verdict.
+     *
+     * Typed rather than gated with a boolean so it cannot be skipped: every rule that reasons from UI
+     * movement has to answer `undefined` explicitly, including one added later. The rules that read
+     * the app's OWN claims (a success signal over a failed call) or its payloads (a 2xx whose body
+     * says it failed, a field echoed back wrong) are untouched — those are things the app said, not
+     * consequences anybody inferred, and they are true whoever caused them.
+     */
+    const advanced = floor === undefined ? undefined : uiAdvanced(events);
     const signals = events
         .filter((e) => e.type === EventType.SIGNAL)
         .map((e) => asString(e.data['name']) ?? 'signal');
@@ -261,7 +330,13 @@ function findWindowContradictions(allEvents, options) {
     // A navigation that neither fetches nor renders arrived nowhere. Distinct from a dead control:
     // the control worked, the DESTINATION is empty — which is why every "did the click do something"
     // heuristic passes it, a route change being unambiguously something.
-    const routed = events.some((e) => e.type === EventType.ROUTE_CHANGE);
+    const routeEvents = events.filter((e) => e.type === EventType.ROUTE_CHANGE);
+    const routed = routeEvents.length > 0;
+    // A skip link (`href="#main-content"`) is a same-document hash change. The observable
+    // consequences are location.hash, focus, and scroll — not a DOM mutation. Treating it as a
+    // blank destination made "did my skip link work" unanswerable. Hash-router paths (`#/invoices`)
+    // still go through the rule: those ARE a new view.
+    const hashAnchorOnly = routed && routeEvents.every(isSameDocumentHashAnchor);
     // `dom.text` counts as rendered, and it has to: React reconciles a destination IN PLACE far more
     // often than it adds nodes. Measured on three ordinary sidebar navigations of the bench app — every
     // one emitted { dom.attr:2, dom.text:2, render.commit, state.change } and ZERO dom.added/removed,
@@ -276,7 +351,7 @@ function findWindowContradictions(allEvents, options) {
         e.type === EventType.DOM_REMOVED ||
         e.type === EventType.DOM_TEXT);
     const fetched = events.some((e) => e.type === EventType.NET_REQUEST || e.type === EventType.NET_PENDING);
-    if (routed && !rendered && !fetched && true !== options.renderProved) {
+    if (routed && !hashAnchorOnly && !rendered && !fetched && true !== options.renderProved) {
         found.push({
             kind: ContradictionKind.ROUTE_RENDERED_NOTHING,
             claim: 'the app navigated to a new route',
@@ -324,26 +399,48 @@ function findWindowContradictions(allEvents, options) {
     // Ordering cannot decide this: an optimistic UI legitimately fires its success signal BEFORE the
     // response, so "the claim must follow the failure" would miss the real defect. What separates them
     // is not when the app spoke, it is whether it took it back.
-    if (failed.length > 0 && successSignals.length > 0 && !failureAcknowledged(events)) {
+    // WHAT failed decides this, not whether an action was attributed.
+    //
+    // The claim is a thing the app said, so the attribution floor does not apply to it — the flagship
+    // false green is an app asserting success on a PASSIVE assert while its own write failed, and
+    // requiring an action would lose exactly that. But the COUNTER was any failure in the window, and
+    // that is the same window statement scoped out of every other rule here. Measured: two of the
+    // three false positives surviving the first scoping pass were this rule.
+    //
+    // A success signal claims a CHANGE was made. A failed mutation is evidence against that claim; a
+    // failed read is not. Background polls, prefetches and telemetry GETs fail constantly in healthy
+    // apps and say nothing about whether a write landed. Structural, not a timing heuristic, and the
+    // distinction was already encoded next door in `isMutating`.
+    const failedWrites = failed.filter(isMutating);
+    // The same scoping, for the same reason, one branch down. "The UI moved forward" is also a claim
+    // that something CHANGED, and it was still reading ANY failure — so a first-party poll failing
+    // during an action contradicted a verdict the action had genuinely earned. Measured on the
+    // observation benchmark: one of two false positives across 47 cells, and the argument for it is
+    // the paragraph above, which had simply not been carried down here.
+    const unexpectedWrites = unexpected.filter(isMutating);
+    if (failedWrites.length > 0 && successSignals.length > 0 && !failureAcknowledged(events)) {
         found.push({
             kind: ContradictionKind.SIGNAL_CONTRADICTED,
             claim: `the app fired ${successSignals.map((s) => `"${s}"`).join(', ')}`,
-            counter: `${String(failed.length)} request(s) in the same window failed`,
-            detail: failed.map(describe).join('; '),
+            counter: `${String(failedWrites.length)} write(s) in the same window failed`,
+            detail: failedWrites.map(describe).join('; '),
         });
     }
-    else if (unexpected.length > 0 && advanced && !misattributed && !failureAcknowledged(events)) {
+    else if (unexpectedWrites.length > 0 &&
+        true === advanced &&
+        !misattributed &&
+        !failureAcknowledged(events)) {
         found.push({
             kind: ContradictionKind.UI_ADVANCED_REQUEST_FAILED,
             claim: 'the UI moved forward (DOM/store/route changed)',
-            counter: `${String(unexpected.length)} request(s) in the same window failed`,
-            detail: unexpected.map(describe).join('; '),
+            counter: `${String(unexpectedWrites.length)} request(s) in the same window failed`,
+            detail: unexpectedWrites.map(describe).join('; '),
         });
     }
     // ── A write succeeded and nothing on the client moved ───────────────────────────────────────
     // Writes only: a GET that changes nothing is a prefetch; a POST that changes nothing is a lost
     // write, a response parsed into the void, or a render that never happened.
-    if (!advanced) {
+    if (false === advanced) {
         const ignoredWrites = settled.filter((c) => true === c.ok && isMutating(c));
         if (ignoredWrites.length > 0) {
             // ...unless THIS document handed the consequence to another browsing context. An OAuth sign-in
@@ -387,7 +484,7 @@ function findWindowContradictions(allEvents, options) {
     // existing tests that assert exactly that, which is the false-positive class this scoping exists
     // to prevent.
     if (options.actionSince !== undefined &&
-        !advanced &&
+        false === advanced &&
         0 === settled.length &&
         successSignals.length > 0) {
         found.push({
@@ -413,10 +510,26 @@ function findWindowContradictions(allEvents, options) {
     // compares nothing rather than guess.
     const actionSince = options.actionSince;
     if (actionSince !== undefined) {
+        /**
+         * When the window navigated, and therefore when a write stops belonging to the user's action.
+         *
+         * React StrictMode double-invokes a mount effect in development, so clicking a nav link lands
+         * two identical writes inside the action's own window. Nothing scoped them out and they read as
+         * a double submit — measured on the observation benchmark as one of two false positives.
+         *
+         * The route change is the structural tell, not a heuristic: the claim this rule makes is "one
+         * user action was performed", and writes that follow a navigation belong to the mount of the
+         * view navigated TO. A real double submit fires from the view it is already on, with nothing in
+         * between — and one that navigates AFTER submitting is still counted, because the order is what
+         * distinguishes them.
+         */
+        const navigatedAt = events.find((e) => EventType.ROUTE_CHANGE === e.type && e.t >= actionSince)?.t;
         const writeCounts = new Map();
         for (const event of events) {
             if (event.type !== EventType.NET_REQUEST || event.t < actionSince)
                 continue;
+            if (navigatedAt !== undefined && event.t >= navigatedAt)
+                continue;
             const call = netCall(event);
             if (!isMutating(call))
                 continue;
@@ -442,7 +555,7 @@ function findWindowContradictions(allEvents, options) {
     // Gated on the UI having moved: an in-flight request while the app is still visibly waiting is
     // just a slow request, not a contradiction. It becomes one when the app proceeded regardless —
     // which is also what makes a later `{ kind: "settled" }` assertion a false green.
-    if (advanced) {
+    if (true === advanced) {
         const settledIds = new Set(events
             .filter((e) => e.type === EventType.NET_REQUEST)
             .map((e) => asString(e.data['id']))
@@ -460,9 +573,9 @@ function findWindowContradictions(allEvents, options) {
                 // the finding says which URLs, so an agent reading it can see what Reticle chose to ignore.
                 detail: [
                     inFlight.map((p) => describe(p.call)).join('; '),
-                    ...(0 === ignoredDevTooling.length
+                    ...(0 === ignoredForeign.length
                         ? []
-                        : [`ignored as dev tooling: ${ignoredDevTooling.join(', ')}`]),
+                        : [`ignored as dev tooling or third-party: ${ignoredForeign.join(', ')}`]),
                 ].join(' — '),
             });
         }

package/dist/events/declared.d.ts

@@ -36,13 +36,15 @@ export declare function declaredExpectations(predicate: Predicate | undefined):
  *
  * The unread-body clause exists for the case where the body is the ONLY channel that could have
  * contradicted the screen — a 200 with per-item failures inside, a GraphQL error that is also a
- * 200. A declared string on screen, store path, or signal that held is a different channel, and
- * grading `unknown` there costs a real verdict (measured: a 201 plus the unique row, unread body,
- * agent went to enable capture instead of finishing the drive).
+ * 200. A declared string on screen, store path, signal, route, or an element located by role /
+ * name / testid that held is a different channel, and grading `unknown` there costs a real
+ * verdict (measured: a 201 plus the unique row, unread body, agent went to enable capture instead
+ * of finishing the drive).
  *
  * Same conservatism as `declaredExpectations`: only the top level and `allOf`. An `anyOf` branch
  * may never have held, and honouring it would skip the unread caveat on the strength of a net
- * success that was the branch that actually matched.
+ * success that was the branch that actually matched. An `absent` element is not a consequence the
+ * body cannot own.
  */
 export declare function declaresBodyIndependentChannel(predicate: Predicate | undefined): boolean;
 /**
@@ -55,5 +57,6 @@ export declare function declaresBodyIndependentChannel(predicate: Predicate | un
 export declare function matchesDeclaredFailure(call: {
     method: string;
     url: string;
+    matchUrl?: string;
     status: number | undefined;
 }, declared: readonly DeclaredNetFailure[]): boolean;

package/dist/events/declared.js

@@ -58,13 +58,15 @@ export function declaredExpectations(predicate) {
  *
  * The unread-body clause exists for the case where the body is the ONLY channel that could have
  * contradicted the screen — a 200 with per-item failures inside, a GraphQL error that is also a
- * 200. A declared string on screen, store path, or signal that held is a different channel, and
- * grading `unknown` there costs a real verdict (measured: a 201 plus the unique row, unread body,
- * agent went to enable capture instead of finishing the drive).
+ * 200. A declared string on screen, store path, signal, route, or an element located by role /
+ * name / testid that held is a different channel, and grading `unknown` there costs a real
+ * verdict (measured: a 201 plus the unique row, unread body, agent went to enable capture instead
+ * of finishing the drive).
  *
  * Same conservatism as `declaredExpectations`: only the top level and `allOf`. An `anyOf` branch
  * may never have held, and honouring it would skip the unread caveat on the strength of a net
- * success that was the branch that actually matched.
+ * success that was the branch that actually matched. An `absent` element is not a consequence the
+ * body cannot own.
  */
 export function declaresBodyIndependentChannel(predicate) {
     if (predicate === undefined)
@@ -77,9 +79,15 @@ export function declaresBodyIndependentChannel(predicate) {
                 return true !== p.absent;
             case PredicateKind.SIGNAL:
             case PredicateKind.STATE:
+            case PredicateKind.ROUTE:
                 return true;
             case PredicateKind.ELEMENT:
-                return true !== p.absent && (p.query.value !== undefined || p.query.text !== undefined);
+                return (true !== p.absent &&
+                    (p.query.value !== undefined ||
+                        p.query.text !== undefined ||
+                        p.query.role !== undefined ||
+                        p.query.name !== undefined ||
+                        p.query.testid !== undefined));
             default:
                 return false;
         }
@@ -97,7 +105,8 @@ export function matchesDeclaredFailure(call, declared) {
     return declared.some((d) => {
         if (d.method !== undefined && d.method.toUpperCase() !== call.method.toUpperCase())
             return false;
-        if (d.urlContains !== undefined && !call.url.includes(d.urlContains))
+        const haystack = call.matchUrl ?? call.url;
+        if (d.urlContains !== undefined && !haystack.includes(d.urlContains))
             return false;
         if (d.status !== undefined && d.status !== call.status)
             return false;

package/dist/events/echo-mismatch.js

@@ -28,7 +28,15 @@ import { ContradictionKind, EventType, MUTATING_METHODS } from '@reticlehq/core'
  *  - values are compared NORMALISED (trimmed, case-folded, numbers as numbers), so `FR` vs `fr` and
  *    `1` vs `1.0` stay silent while `fr` vs `en` speaks;
  *  - if the key appears anywhere in the response carrying the requested value, it is treated as
- *    applied — an envelope that echoes both the old and the new value is not a dropped write.
+ *    applied — an envelope that echoes both the old and the new value is not a dropped write;
+ *  - the response must look like a restatement of the request before any key is compared. Reported
+ *    from the field: a command bus POSTed `{command:'chat.send', ...}` and the server answered with
+ *    the current viewer snapshot. The message arrived over the socket and rendered. `id` in the
+ *    snapshot meant the viewer, `id` in the request meant the message, and this kind fired. A
+ *    snapshot that shares a key name is not an echo. A discriminator the request carries that the
+ *    response does not, or a fat body that shares one coincidental key, is skipped. The existing
+ *    single-value / not-echoed-at-all guards still trade false negatives away — this narrows on
+ *    shape, not on value types.
  *
  * The residue after those filters is a field the caller set, the server echoed back, and the echoed
  * value is a genuinely different value. That is worth one line of an agent's attention.
@@ -94,6 +102,60 @@ function scalarsByKey(body, into = new Map(), depth = 0) {
 }
 const OK_MIN = 200;
 const OK_MAX = 300;
+/**
+ * Body keys that name the operation rather than a field being persisted. A command bus puts one of
+ * these on the request; a snapshot of the current viewer does not echo it. Their absence on the
+ * response is the cheapest honest signal that the body is not a restatement of the write.
+ */
+const EchoDiscriminator = {
+    COMMAND: 'command',
+    ACTION: 'action',
+    OP: 'op',
+    PROCEDURE: 'procedure',
+};
+/**
+ * A response carrying this many times more scalar keys than the request, overlapping on fewer than
+ * `MIN_SHARED_KEYS`, is a snapshot that happened to reuse a name — not an echo of the write.
+ */
+const SNAPSHOT_KEY_RATIO = 3;
+const MIN_SHARED_KEYS = 2;
+/**
+ * True when the response looks like a restatement of the request, so overlapping key names can be
+ * read as an echo rather than a coincidence.
+ *
+ * Half the request's comparable keys must appear in the response. That keeps a partial echo
+ * (`{density, locale}` answered with only `locale`) in scope, and drops a three-field command whose
+ * snapshot shares one name. A request that names an operation the response does not repeat is not
+ * an echo at all, regardless of any other overlap.
+ */
+function responseRestatesRequest(asked, echoed) {
+    const comparable = [];
+    for (const [key, wanted] of asked) {
+        if (1 === wanted.size)
+            comparable.push(key);
+    }
+    if (0 === comparable.length)
+        return false;
+    let present = 0;
+    for (const key of comparable) {
+        if (echoed.has(key))
+            present += 1;
+    }
+    let requestHasDiscriminator = false;
+    let responseHasDiscriminator = false;
+    for (const key of Object.values(EchoDiscriminator)) {
+        if (asked.has(key))
+            requestHasDiscriminator = true;
+        if (echoed.has(key))
+            responseHasDiscriminator = true;
+    }
+    if (requestHasDiscriminator && !responseHasDiscriminator)
+        return false;
+    if (echoed.size > comparable.length * SNAPSHOT_KEY_RATIO && present < MIN_SHARED_KEYS) {
+        return false;
+    }
+    return present * 2 >= comparable.length;
+}
 /**
  * Contradictions for writes whose response echoes a different value than the request asked for.
  *
@@ -133,19 +195,7 @@ export function findEchoMismatches(events, actionSince) {
             continue;
         const echoed = scalarsByKey(response);
         const asked = scalarsByKey(request);
-        // The response has to be ECHO-SHAPED before any key can contradict anything. An echo restates
-        // what was sent, so most of the request's scalar keys reappear somewhere in it; a snapshot that
-        // happens to share a key or two does not (#506: `{"command":"chat.send"}` answered with the
-        // viewer snapshot read one incidental shared key as an attempted echo of a write that fully
-        // applied). Requiring a strict majority of the request's keys to appear keeps every documented
-        // true positive — an envelope restates most of its fields — and deliberately trades the rare
-        // half-echoed write away, the same direction MAX_ECHO_KEYS already trades in.
-        let shared = 0;
-        for (const key of asked.keys()) {
-            if (echoed.has(key))
-                shared += 1;
-        }
-        if (shared * 2 <= asked.size)
+        if (!responseRestatesRequest(asked, echoed))
             continue;
         const dropped = [];
         for (const [key, wanted] of asked) {

package/dist/events/event-filters.d.ts

@@ -32,6 +32,14 @@ export declare function matchNet(e: ReticleEvent, method: string | undefined, ur
  * pending: true }` so a numeric `status` filter excludes them but `urlContains`/`method` match.
  */
 export declare function reconcileNet(events: ReticleEvent[]): ReticleEvent[];
+/**
+ * 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 declare function withoutUrlRaw(event: unknown): unknown;
 /** Compact network-call summary for reticle_network output — drops event plumbing (t, type,
  * sessionId, ref, id, initiator, ok) the agent never needs, keeping only method/url/status/ms.
  * This is the bulk of the token cost: raw ReticleEvent objects are ~5x larger than this. */

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/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.
@@ -314,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;
@@ -321,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) {
@@ -350,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;
             }
@@ -377,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.
@@ -418,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',
         };

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;