@reticlehq/server 2.11.0 → 2.13.0

package/dist/events/contradictions.d.ts

@@ -113,5 +113,64 @@ export interface ContradictionOptions {
      * with no view.
      */
     renderProved?: boolean | undefined;
+    /**
+     * The document currently under observation, as the session derived it from its own event stream.
+     *
+     * Every rule below reasons about "the same window", and a window is scoped by time and by
+     * ring-buffer capacity and by nothing else — so it can still hold the traffic of a page a full
+     * navigation or a reload has already thrown away. Naming that traffic as the cause of an action
+     * taken now is true about the bytes and false about the world.
+     *
+     * Undefined means nobody could say which document is current (an SDK too old to stamp one, a caller
+     * with no session in hand), and the scoping then does nothing at all — `isSameDocument` treats
+     * absence as current on both sides, so the engine behaves exactly as it did before this existed.
+     */
+    currentDocumentId?: string | undefined;
+    /**
+     * The edit epoch currently in force, as the session derived it from its own event stream.
+     *
+     * The edit-shaped half of `currentDocumentId`. A hot update replaces modules and re-renders inside
+     * the SAME document, so the document id cannot see it and observations of code the agent has
+     * already rewritten go on answering for it in silence.
+     *
+     * Undefined means nobody could say (an SDK too old to stamp one, a page with no hot-update channel,
+     * a caller with no session in hand) and the scoping then does nothing at all — `isSameEditEpoch`
+     * treats absence as current on both sides.
+     */
+    currentEditEpoch?: number | undefined;
+    /**
+     * The page under test, as the session last recorded it — the app's own origin, in URL form.
+     *
+     * The first-party/third-party axis. Every rule below asks "did the app disagree with itself", and
+     * a failed analytics beacon is not the app: reported independently from several apps, any
+     * analytics package installed was enough to grade a correct drive `contradicted`, and on one app
+     * EVERY assertion came back that way forever, because it fires a branding call on page load. A
+     * verdict field that answers "no" to everything has stopped being a verdict field.
+     *
+     * Third-party traffic is dropped here rather than reported at a lower severity, for the reason the
+     * dev-tooling split is: the rules below would each have to learn to say it. The exclusion is never
+     * silent — the URLs ride out in the same disclosure line the toolchain's do — and the calls
+     * themselves are untouched in `reticle_network` and the event timeline.
+     *
+     * Undefined disables the axis, exactly as an undefined `currentDocumentId` disables the document
+     * one: a caller that cannot say which page is under test gets the behaviour it had before this.
+     */
+    appOrigin?: string | undefined;
 }
+/**
+ * Cross-channel contradictions in this window, with the edit-epoch caveat attached when it applies.
+ *
+ * Cross-epoch evidence is LABELLED rather than excluded, which is the opposite of what the document
+ * scoping does, and the difference is the point. A navigation is total — it throws away the page,
+ * the refs, the in-flight requests and the state — so nothing recorded before it is still about the
+ * world, and dropping it is the only honest option. A hot update is not: most modules, most of the
+ * DOM, the whole network log and every console line survive one, so most of what was observed a
+ * second before an edit is still true a second after. Excluding it would empty windows that hold
+ * real findings, and an emptied window reads as "nothing happened" — which is the more expensive of
+ * the two wrong answers and the one this whole family of checks exists to prevent.
+ *
+ * So the findings stand and the caveat is said out loud, and only when it is unambiguous: EVERY
+ * observation in the window predates the edit. One post-edit observation and the agent is already
+ * looking at the code it wrote, so the label would be noise.
+ */
 export declare function findContradictions(allEvents: readonly ReticleEvent[], options?: ContradictionOptions): Contradiction[];

package/dist/events/contradictions.js

@@ -1,4 +1,5 @@
-import { ContradictionKind, EventType, MUTATING_METHODS, isDevToolingUrl, } 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';
 import { findEchoMismatches } from './echo-mismatch.js';
@@ -11,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.
@@ -138,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`).
  *
@@ -148,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);
@@ -162,9 +205,76 @@ function splitDevTooling(events) {
     });
     return { app, ignored };
 }
+/**
+ * Cross-channel contradictions in this window, with the edit-epoch caveat attached when it applies.
+ *
+ * Cross-epoch evidence is LABELLED rather than excluded, which is the opposite of what the document
+ * scoping does, and the difference is the point. A navigation is total — it throws away the page,
+ * the refs, the in-flight requests and the state — so nothing recorded before it is still about the
+ * world, and dropping it is the only honest option. A hot update is not: most modules, most of the
+ * DOM, the whole network log and every console line survive one, so most of what was observed a
+ * second before an edit is still true a second after. Excluding it would empty windows that hold
+ * real findings, and an emptied window reads as "nothing happened" — which is the more expensive of
+ * the two wrong answers and the one this whole family of checks exists to prevent.
+ *
+ * So the findings stand and the caveat is said out loud, and only when it is unambiguous: EVERY
+ * observation in the window predates the edit. One post-edit observation and the agent is already
+ * looking at the code it wrote, so the label would be noise.
+ */
 export function findContradictions(allEvents, options = {}) {
+    const found = findWindowContradictions(allEvents, options);
+    const predates = allEvents.length > 0 &&
+        allEvents.every((e) => !isSameEditEpoch(e.editEpoch, options.currentEditEpoch));
+    if (!predates)
+        return found;
+    // Prepended, not appended: the caveat governs how everything under it should be read, and it has
+    // to survive the rules that return early with a single finding of their own.
+    return [
+        {
+            kind: ContradictionKind.EVIDENCE_PREDATES_EDIT,
+            claim: 'these observations describe the code as it is now',
+            counter: 'every one of them was recorded before the last hot update landed in the page',
+            detail: 'the source changed and the page re-rendered after this evidence was captured, so it describes code that has since been replaced — nothing here is necessarily wrong, but nothing here has seen the edit either. Drive the app again to verify the current code',
+        },
+        ...found,
+    ];
+}
+function findWindowContradictions(allEvents, options) {
     const found = [];
-    const { app: events, 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 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 === scoped.length) {
+        return [
+            {
+                kind: ContradictionKind.EVIDENCE_SUPERSEDED,
+                claim: 'this window holds observations that could answer for the action',
+                counter: describeSuperseded('observations', superseded),
+                detail: 'a full navigation or a reload built a new document, and everything recorded here belongs to the old one — citing it would name requests, errors and state that no longer describe anything on screen',
+            },
+        ];
+    }
+    // ── 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.
@@ -197,7 +307,22 @@ export function findContradictions(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');
@@ -205,7 +330,13 @@ export function findContradictions(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,
@@ -220,7 +351,7 @@ export function findContradictions(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',
@@ -268,60 +399,155 @@ export function findContradictions(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) {
-            found.push({
-                kind: ContradictionKind.RESPONSE_IGNORED,
-                claim: `${String(ignoredWrites.length)} write(s) succeeded on the server`,
-                counter: 'nothing on the client changed — no DOM, store or route movement',
-                detail: ignoredWrites.map(describe).join('; '),
-            });
+            // ...unless THIS document handed the consequence to another browsing context. An OAuth sign-in
+            // posts, succeeds, and continues in a popup the in-page SDK cannot follow (#508): the original
+            // tab legitimately never changes, and response-ignored would accuse it of ignoring a response
+            // it handed off. The opened-context event flips the reading from "the client did nothing" to
+            // "the client went where we cannot look". Scoped like every rule here to the attribution floor
+            // (`options.actionSince`; the local below is declared later, for the window rules).
+            const contextFloor = options.actionSince;
+            const openedContext = events.some((e) => e.type === EventType.CONTEXT_OPENED && contextFloor !== undefined && e.t >= contextFloor);
+            found.push(openedContext
+                ? {
+                    kind: ContradictionKind.CONSEQUENCE_ELSEWHERE,
+                    claim: `${String(ignoredWrites.length)} write(s) succeeded on the server`,
+                    counter: 'this document never changed because the page opened another browsing context during this window (e.g. an OAuth popup), where the in-page SDK cannot observe the result',
+                    detail: ignoredWrites.map(describe).join('; '),
+                }
+                : {
+                    kind: ContradictionKind.RESPONSE_IGNORED,
+                    claim: `${String(ignoredWrites.length)} write(s) succeeded on the server`,
+                    counter: 'nothing on the client changed — no DOM, store or route movement',
+                    detail: ignoredWrites.map(describe).join('; '),
+                });
         }
     }
+    // ── The app announced a consequence and nothing else moved ─────────────────────────────────
+    // Scoped as tightly as the evidence allows, because this rule fires on the ABSENCE of everything
+    // else and that is the easiest way to build a false positive.
+    //
+    // Only when the window is otherwise EMPTY: no DOM, no store, no route (`!advanced`) and no request
+    // at all. A request means the app reached for something, and whether it settled, failed or was
+    // ignored belongs to three other rules — firing here too would report one fact twice.
+    //
+    // `successSignals` reuses the failure-shaped filter above: an app that announced `deploy:failed`
+    // is correctly reporting that nothing happened, and accusing it inverts the meaning of the one app
+    // doing this right.
+    //
+    // And only for a window attributed to an ACTION. `reticle_assert` OBSERVES — there is no click
+    // whose consequence should have corroborated anything, so an assert over a quiet window carrying
+    // one signal is an ordinary read, not a claim nothing backs. Without this the rule reddened eight
+    // existing tests that assert exactly that, which is the false-positive class this scoping exists
+    // to prevent.
+    if (options.actionSince !== undefined &&
+        false === advanced &&
+        0 === settled.length &&
+        successSignals.length > 0) {
+        found.push({
+            kind: ContradictionKind.SIGNAL_WITHOUT_CONSEQUENCE,
+            claim: `the app fired ${successSignals.map((s) => `"${s}"`).join(', ')}`,
+            counter: 'nothing else in the window moved — no DOM, no store, no route, no request — so the only ' +
+                'evidence that anything happened is the app saying so',
+            detail: 'a signal emitted from the value the app was ASKED for, rather than the one it committed, ' +
+                'reads identically to one that worked',
+        });
+    }
     // ── The same write fired more than once, inside ONE action's window ─────────────────────────
     // Attribution is the whole rule here, not a refinement of it: counting `method + url` over whatever
     // window the caller handed in turns two legitimate separate saves into a double submit. See
     // ContradictionOptions.actionSince.
+    //
+    // A captured request body joins the identity. A command-bus API posts every mutation to one URL
+    // and discriminates on a body field (`{"command":"study.stage.set"}` vs `{"command":"mesh.plan"}`),
+    // so under URL alone each of those distinct writes read as a repeat of the first, and clean
+    // verdicts degraded to unknown behind doubles that were never doubles. When no body was captured
+    // (capture off, or a non-text body, which reports a type marker instead) there is nothing to
+    // compare and the URL alone stands, as before; a window where only some calls carried bodies
+    // 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;
-            const key = `${call.method} ${call.url}`;
-            writeCounts.set(key, (writeCounts.get(key) ?? 0) + 1);
+            const label = `${call.method} ${call.url}`;
+            const body = asString(event.data['requestBody']);
+            const key = body === undefined || 0 === body.length ? label : `${label} ${body}`;
+            const entry = writeCounts.get(key) ?? { label, count: 0 };
+            entry.count += 1;
+            writeCounts.set(key, entry);
         }
-        for (const [key, count] of writeCounts) {
+        for (const [, { label, count }] of writeCounts) {
             if (count < 2)
                 continue;
             found.push({
                 kind: ContradictionKind.DUPLICATE_REQUEST,
                 claim: 'one user action was performed',
                 counter: `the same write fired ${String(count)} times`,
-                detail: `${key} ×${String(count)}`,
+                detail: `${label} ×${String(count)}`,
             });
         }
     }
@@ -329,7 +555,7 @@ export function findContradictions(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']))
@@ -347,9 +573,9 @@ export function findContradictions(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

@@ -31,6 +31,22 @@ export interface DeclaredExpectations {
     rendersContent: boolean;
 }
 export declare function declaredExpectations(predicate: Predicate | undefined): DeclaredExpectations;
+/**
+ * Did the caller name a consequence that does not depend on the response body?
+ *
+ * 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, 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. An `absent` element is not a consequence the
+ * body cannot own.
+ */
+export declare function declaresBodyIndependentChannel(predicate: Predicate | undefined): boolean;
 /**
  * Does a call the window recorded match a failure the caller declared?
  *
@@ -41,5 +57,6 @@ export declare function declaredExpectations(predicate: Predicate | undefined):
 export declare function matchesDeclaredFailure(call: {
     method: string;
     url: string;
+    matchUrl?: string;
     status: number | undefined;
 }, declared: readonly DeclaredNetFailure[]): boolean;

package/dist/events/declared.js

@@ -53,6 +53,47 @@ export function declaredExpectations(predicate) {
         walk(predicate);
     return { netFailures, rendersContent };
 }
+/**
+ * Did the caller name a consequence that does not depend on the response body?
+ *
+ * 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, 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. An `absent` element is not a consequence the
+ * body cannot own.
+ */
+export function declaresBodyIndependentChannel(predicate) {
+    if (predicate === undefined)
+        return false;
+    const walk = (p) => {
+        switch (p.kind) {
+            case PredicateKind.ALL_OF:
+                return p.predicates.some(walk);
+            case PredicateKind.TEXT:
+                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 ||
+                        p.query.role !== undefined ||
+                        p.query.name !== undefined ||
+                        p.query.testid !== undefined));
+            default:
+                return false;
+        }
+    };
+    return walk(predicate);
+}
 /**
  * Does a call the window recorded match a failure the caller declared?
  *
@@ -64,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,6 +195,8 @@ export function findEchoMismatches(events, actionSince) {
             continue;
         const echoed = scalarsByKey(response);
         const asked = scalarsByKey(request);
+        if (!responseRestatesRequest(asked, echoed))
+            continue;
         const dropped = [];
         for (const [key, wanted] of asked) {
             // More than one requested value for a key (a before/after pair, a list of items) makes "what

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. */