@reticlehq/server 2.13.0 → 2.14.0

package/dist/events/predicate-eval.js

@@ -1,6 +1,8 @@
 import { EventType, PredicateKind, StreamDirection, isDevToolingUrl, urlForMatch, REDACTED_VALUE, } from '@reticlehq/core';
 import { describeObserved } from './observed-in-window.js';
-import { withoutUrlRaw } from './event-filters.js';
+import { netEvidence } from './net-evidence.js';
+import { checkRequestBody, newRequestBodyState, requestBodyVerdict, } from './predicate-request-body.js';
+export { evalConsole } from './predicate-console.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.
@@ -103,7 +105,7 @@ function structurallyEqual(got, want) {
     return keys.every((k) => k in b && structurallyEqual(a[k], b[k]));
 }
 /** Shallow JSON pattern match: each key in `pattern` must match (see matchValue). */
-function dataMatches(actual, pattern) {
+export function dataMatches(actual, pattern) {
     for (const [key, want] of Object.entries(pattern)) {
         if (!matchValue(actual[key], want))
             return false;
@@ -158,16 +160,13 @@ function observedNetCalls(events, urlContains) {
     });
     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.
  */
 const MAX_BODY_IN_FAILURE = 200;
 /** Enough of a body to see what differed, without paying for a whole payload in the verdict. */
-function clipBody(body) {
+export function clipBody(body) {
     return body.length <= MAX_BODY_IN_FAILURE ? body : `${body.slice(0, MAX_BODY_IN_FAILURE)}…`;
 }
 /**
@@ -177,7 +176,7 @@ function clipBody(body) {
  * applied too, so the caller was shown a predicate it had not written and told nothing matched it.
  * A printed filter that is narrower than the real one is worse than none: it is believed.
  */
-function describeNetFilter(p) {
+export function describeNetFilter(p) {
     const { kind: _kind, count: _count, since: _since, ...filter } = p;
     return JSON.stringify(filter);
 }
@@ -251,6 +250,45 @@ const DOCUMENT_ONLY_SUFFIXES = [
     '.eot',
     '.webmanifest',
 ];
+/**
+ * File suffixes a click typically downloads or navigates to as a document, never as fetch/XHR.
+ *
+ * Sibling of DOCUMENT_ONLY_SUFFIXES, not a member of it. Those are subresources: once resource
+ * timing is live, a miss is evidence. A click on `<a href="/export.pdf">` is a navigation (or a
+ * Content-Disposition attachment). Resource timing of stylesheets does not make it visible, so
+ * grading the miss as "0 network calls" / a 404 is the lie #805 exists to stop — even on a page
+ * whose observer is running. `.js` / `.json` stay off this list for the same reason they stay off
+ * the other: they are routinely fetched.
+ */
+const NATIVE_DOWNLOAD_SUFFIXES = [
+    '.pdf',
+    '.csv',
+    '.tsv',
+    '.zip',
+    '.gz',
+    '.tar',
+    '.xlsx',
+    '.xls',
+    '.docx',
+    '.doc',
+    '.pptx',
+    '.ppt',
+    '.ods',
+    '.odt',
+    '.rtf',
+    '.7z',
+    '.rar',
+];
+/**
+ * Does this filter target a class of request the observer cannot see?
+ *
+ * Read off `urlContains` only, and only when the pattern ENDS in one of the suffixes — a filter of
+ * `/api/` that happens to contain `.css` somewhere in a query string is still an ordinary XHR
+ * target. Query strings and fragments are stripped first, since `favicon.ico?v=2` is the same asset.
+ */
+function filterPath(urlContains) {
+    return (urlContains.split('#')[0] ?? '').split('?')[0]?.toLowerCase() ?? '';
+}
 /**
  * Does this filter target a class of request the observer cannot see?
  *
@@ -259,10 +297,36 @@ const DOCUMENT_ONLY_SUFFIXES = [
  * target. Query strings and fragments are stripped first, since `favicon.ico?v=2` is the same asset.
  */
 function targetsUnobservedChannel(p) {
-    if (p.urlContains === undefined)
+    const url = p.urlContains;
+    if (undefined === url)
         return false;
-    const path = (p.urlContains.split('#')[0] ?? '').split('?')[0]?.toLowerCase() ?? '';
-    return DOCUMENT_ONLY_SUFFIXES.some((suffix) => path.endsWith(suffix));
+    return DOCUMENT_ONLY_SUFFIXES.some((suffix) => filterPath(url).endsWith(suffix));
+}
+function targetsNativeDownload(p) {
+    const url = p.urlContains;
+    if (undefined === url)
+        return false;
+    return NATIVE_DOWNLOAD_SUFFIXES.some((suffix) => filterPath(url).endsWith(suffix));
+}
+function nativeDownloadReason(p) {
+    return (`no fetch or XHR matched ${describeNetFilter(p)}. A native download or document navigation ` +
+        `(an <a href> to a file, a Content-Disposition attachment, <a download>) never goes through ` +
+        `fetch or XMLHttpRequest, so an empty net window is not a 404 and is not evidence the export ` +
+        `failed. This is unobservable on the net channel. Assert the link href, or check the file ` +
+        `outside the browser — Reticle cannot see the bytes land`);
+}
+function nativeDownloadMiss(events, p) {
+    if (!targetsNativeDownload(p))
+        return undefined;
+    const reason = nativeDownloadReason(p);
+    return {
+        pass: false,
+        failureReason: reason,
+        inconclusive: reason,
+        observed: observedNetCalls(events, p.urlContains),
+        expected: `a fetch or XHR matching ${describeNetFilter(p)}`,
+        assertion: 'net.native-download',
+    };
 }
 /**
  * Initiator types the browser SDK's resource-timing observer stamps onto document-initiated records
@@ -308,6 +372,34 @@ function unobservedChannelReason(p) {
         `Nothing here says the app is wrong. Check it outside the browser, or assert something the ` +
         `document does not fetch on its own`);
 }
+/**
+ * Appended to a zero-match `net` negative whose window starts at SDK attach.
+ *
+ * Every event's `t` is stamped `performance.now() - #start`, where `#start` is taken when the SDK
+ * is constructed, so `t` is never negative and a window with `since === 0` begins AT attach — never
+ * before it. Whatever the page did between navigation start and attach left no event at all, so
+ * "no matching call" over such a window cannot be told apart from "the call was made while nothing
+ * was watching yet".
+ *
+ * The gap is routine rather than exotic: a `fetch` from an effect in a root provider, or a classic
+ * `<script>` at the end of `<body>`, fires before a deferred module script has run. Reported from
+ * the field, the verdict then read as proof the request was never made, and reporters went looking
+ * for the defect in code that was working — restarting dev servers and re-reading providers to
+ * establish the request was invisible rather than absent.
+ *
+ * Same argument as DOCUMENT_ONLY_SUFFIXES one axis over: that one is a channel Reticle does not
+ * watch, this is a stretch of TIME it was not yet watching.
+ *
+ * The grade is deliberately NOT downgraded to `inconclusive`. A missing API call is the finding this
+ * oracle exists to make, and it is the strongest grade available for the startup class — session
+ * restore, feature flags, bootstrap config — which is exactly the class that silently breaks on
+ * reload. Every window an action opens carries `since > 0` and is untouched. What changes is only
+ * what the negative CLAIMS: it stops asserting the request never happened, and names the assertion
+ * that can settle it, because the state such a request produces IS observable after attach.
+ */
+const PRE_ATTACH_CAVEAT = ' — note that this window starts where the SDK attached, and requests made before that are never ' +
+    'captured, so a miss here cannot tell a call that was never made apart from one made before the ' +
+    'page connected; if the call is expected during startup, assert on the state it produces instead';
 export function evalNet(events, p) {
     const since = p.since ?? 0;
     /**
@@ -341,6 +433,7 @@ export function evalNet(events, p) {
      * a truncated one cannot (#614).
      */
     let truncatedBody;
+    const requestState = newRequestBodyState();
     const matches = events.filter((e) => {
         if (e.type !== EventType.NET_REQUEST || e.t < since)
             return false;
@@ -390,6 +483,8 @@ export function evalNet(events, p) {
                 return false;
             }
         }
+        if (!checkRequestBody(d, p, requestState))
+            return false;
         return true;
     });
     if (unobservableStatus && 0 === matches.length) {
@@ -413,6 +508,9 @@ export function evalNet(events, p) {
             assertion: 'net.bodyContains',
         };
     }
+    const requestVerdict = requestBodyVerdict(requestState, p, matches.length);
+    if (requestVerdict !== undefined)
+        return requestVerdict;
     // 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.
@@ -440,6 +538,11 @@ 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) {
+        if (0 === matches.length) {
+            const download = nativeDownloadMiss(events, p);
+            if (download !== undefined)
+                return download;
+        }
         if (matches.length !== p.count &&
             0 === matches.length &&
             targetsUnobservedChannel(p) &&
@@ -451,15 +554,27 @@ export function evalNet(events, p) {
                 assertion: 'net.count',
             };
         }
-        return evalExactCount({
+        const counted = evalExactCount({
             matched: matches.length,
             want: p.count,
             noun: 'network call(s)',
             filter: describeNetFilter(p),
             assertion: 'net.count',
         });
+        // Same blind head, second door: "saw 0" over a whole-session window is the same claim the
+        // presence branch makes, and just as unable to see a startup call. A `count: 0` assertion is
+        // left alone on purpose — it PASSES here, and turning that green into a non-pass is a grade
+        // change, not a wording one.
+        return 0 === matches.length && 0 === since && counted.failureReason !== undefined
+            ? { ...counted, failureReason: `${counted.failureReason}${PRE_ATTACH_CAVEAT}` }
+            : counted;
     }
     const hit = matches[0];
+    if (hit === undefined) {
+        const download = nativeDownloadMiss(events, p);
+        if (download !== undefined)
+            return download;
+    }
     if (hit === undefined && targetsUnobservedChannel(p) && !sawSubresources) {
         const reason = unobservedChannelReason(p);
         return {
@@ -472,10 +587,10 @@ export function evalNet(events, p) {
         };
     }
     return hit !== undefined
-        ? { pass: true, evidence: netEvidence(hit.data) }
+        ? { pass: true, evidence: netEvidence(hit.data, p) }
         : {
             pass: false,
-            failureReason: `no network call matched ${JSON.stringify(p)}`,
+            failureReason: `no network call matched ${JSON.stringify(p)}${0 === since ? PRE_ATTACH_CAVEAT : ''}`,
             // 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: observedNetCalls(events, p.urlContains),
@@ -483,103 +598,6 @@ export function evalNet(events, p) {
             assertion: 'net.present',
         };
 }
-/** The only console levels Reticle instruments (console.info/debug/trace are NOT patched). */
-const CONSOLE_LEVEL_TYPE = {
-    log: EventType.CONSOLE_LOG,
-    warn: EventType.CONSOLE_WARN,
-    error: EventType.CONSOLE_ERROR,
-};
-export function evalConsole(events, p) {
-    const since = p.since ?? 0;
-    // Reticle only instruments console.log/warn/error. A level outside that set is never captured,
-    // so its events can't exist — and an `absent` assertion on it would verify NOTHING while
-    // reporting green. Fail loudly instead of false-passing.
-    if (p.level !== undefined && p.level !== 'error' && CONSOLE_LEVEL_TYPE[p.level] === undefined) {
-        return {
-            pass: false,
-            failureReason: `console level '${p.level}' is not captured — Reticle instruments console.log, console.warn, console.error only`,
-            observed: `level '${p.level}' is not instrumented, so no event of it can ever exist`,
-            expected: 'a level Reticle captures: log, warn, or error',
-            assertion: 'console.uninstrumented-level',
-        };
-    }
-    const matches = events.filter((e) => {
-        if (e.t < since)
-            return false;
-        const isErr = e.type === EventType.CONSOLE_ERROR || e.type === EventType.ERROR_UNCAUGHT;
-        if (p.level === undefined) {
-            return (e.type === EventType.CONSOLE_LOG ||
-                e.type === EventType.CONSOLE_WARN ||
-                e.type === EventType.CONSOLE_ERROR ||
-                e.type === EventType.ERROR_UNCAUGHT);
-        }
-        if ('error' === p.level)
-            return isErr;
-        return e.type === CONSOLE_LEVEL_TYPE[p.level];
-    });
-    // A text match narrows the population to entries whose captured message contains the substring.
-    // With `absent: true` this is the whole point: "THIS message did not appear", not "no messages
-    // appeared" — the difference between a regression check and a fragile one that any unrelated
-    // warning anywhere in the app breaks.
-    const wanted = 'contains' in p ? p.contains : undefined;
-    // Captured messages are strings (stringifyArgs in the browser observer), but a malformed or
-    // foreign event must not crash the evaluator: non-strings stringify defensively, and objects
-    // go through JSON.stringify rather than a default toString that would print '[object Object]'.
-    const asText = (v) => {
-        if ('string' === typeof v)
-            return v;
-        try {
-            return JSON.stringify(v) ?? '';
-        }
-        catch {
-            return '';
-        }
-    };
-    const matching = wanted !== undefined
-        ? matches.filter((e) => asText(e.data['message']).includes(wanted))
-        : matches;
-    if (true === p.absent) {
-        if (wanted !== undefined && 0 === matching.length && matches.length > 0) {
-            // Other entries exist but none carries the substring: exactly the pass an absence-with-match
-            // asserts. Name both counts so the caller can tell this from a silent window.
-            return {
-                pass: true,
-                evidence: { absent: true, contains: wanted },
-            };
-        }
-        return 0 === matching.length
-            ? { pass: true, evidence: { absent: true } }
-            : {
-                pass: false,
-                failureReason: wanted !== undefined
-                    ? `expected no ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)} but found ${String(matching.length)}`
-                    : `expected no ${p.level ?? 'console'} entries but found ${String(matches.length)}`,
-                observed: wanted !== undefined
-                    ? `${String(matching.length)} ${p.level ?? 'console'} entr${1 === matching.length ? 'y' : 'ies'} containing ${JSON.stringify(wanted)}`
-                    : `${String(matches.length)} ${p.level ?? 'console'} entr${1 === matches.length ? 'y' : 'ies'}`,
-                expected: wanted !== undefined
-                    ? `no ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)}`
-                    : `no ${p.level ?? 'console'} entries`,
-                assertion: wanted !== undefined ? 'console.absent-contains' : 'console.absent',
-                evidence: matching.map((e) => e.data),
-            };
-    }
-    return matching.length > 0
-        ? { pass: true, evidence: matching.map((e) => e.data) }
-        : {
-            pass: false,
-            failureReason: wanted !== undefined
-                ? `no ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)} found`
-                : `no ${p.level ?? 'console'} entries found`,
-            observed: wanted !== undefined
-                ? `no ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)} in the window`
-                : `no ${p.level ?? 'console'} entries in the window`,
-            expected: wanted !== undefined
-                ? `at least one ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)}`
-                : `at least one ${p.level ?? 'console'} entry`,
-            assertion: 'console.present',
-        };
-}
 export function evalAnimation(events, p) {
     const wantType = true === p.completed ? EventType.ANIM_END : EventType.ANIM_START;
     const hit = events.find((e) => {

package/dist/events/predicate-parse.js

@@ -106,9 +106,42 @@ 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, parsed.error.issues)} ` +
+        `not evaluated, so no verdict was produced. ${accepted(kind, parsed.error.issues)}` +
+        `${misplacedCallFields(input)} ` +
         `A valid ${kind} predicate looks like: ${exampleFor(kind)}`);
 }
+/**
+ * Arguments of the CALL that agents write inside the predicate instead.
+ *
+ * Reported from the field on `timeout_ms`, nested in `until` on an `act_and_wait` that had already
+ * timed out once at the default budget. The rejection said "unknown field", which reads as "there is
+ * no such thing" — so the obvious retry is to delete it and silently give up the longer budget that
+ * was the point of writing it. It is not an unknown field; it is a real argument one level too deep.
+ */
+const CALL_LEVEL_FIELDS = [
+    'timeout_ms',
+    'sessionId',
+    'ref',
+    'action',
+    'args',
+    'target',
+    'intent',
+];
+/** The clause naming where a misplaced call argument goes, or '' when nothing was misplaced. */
+function misplacedCallFields(input) {
+    if ('object' !== typeof input || null === input)
+        return '';
+    const written = Object.keys(input);
+    const misplaced = CALL_LEVEL_FIELDS.filter((field) => written.includes(field));
+    if (0 === misplaced.length)
+        return '';
+    const list = misplaced.join(', ');
+    // Named as a MOVE, not as a removal. Deleting the field is the reading of "unknown field" that
+    // costs the caller the thing it asked for.
+    return (` ${list} ${1 === misplaced.length ? 'is an argument' : 'are arguments'} of the CALL, not of ` +
+        `the predicate: ${1 === misplaced.length ? 'move it' : 'move them'} up beside \`until\` rather ` +
+        'than dropping it — nesting is why the predicate did not parse.');
+}
 /**
  * What WOULD have worked, in the same breath as what did not.
  *

package/dist/events/predicate-request-body.d.ts

@@ -0,0 +1,50 @@
+import { type EvalResult } from './predicate-eval.js';
+import type { PredicateKind } from '@reticlehq/core';
+import type { Predicate } from './predicate-schema.js';
+/** The net predicate as `describeNetFilter` types it. */
+type NetPredicate = Extract<Predicate, {
+    kind: typeof PredicateKind.NET;
+}>;
+/** A net predicate, narrowed to the fields this module reads. */
+interface RequestBodyPredicate {
+    requestBodyContains?: string;
+    requestBodyMatches?: Record<string, unknown>;
+}
+/**
+ * What the filtering pass learned about calls that matched everything else.
+ *
+ * Accumulated during the single pass over events rather than recomputed after it, the way the
+ * response-side trackers already are.
+ */
+export interface RequestBodyState {
+    /** A call matched everything else but carried no recorded request body. */
+    unrecorded: boolean;
+    /** The request body a clause was checked against and did not match. */
+    mismatch?: string;
+    /** The prefix of a TRUNCATED request body the clause did not hold over — undecidable, not absent. */
+    truncated?: string;
+    /**
+     * A key whose CAPTURED value is `[REDACTED]`, so the clause cannot be judged at all.
+     *
+     * Request bodies go through the same redaction path as responses before they are ever recorded,
+     * so a clause on a sensitive key is unsatisfiable whatever the app sent. Grading that a mismatch
+     * would blame the application for the SDK's own redaction and send someone to fix a correct
+     * payload.
+     */
+    redactedField?: string;
+}
+export declare function newRequestBodyState(): RequestBodyState;
+/**
+ * Does this event satisfy the predicate's request-body clauses? Records why not in `state`.
+ *
+ * Returns true when there is nothing to check, so callers can apply it unconditionally.
+ */
+export declare function checkRequestBody(data: Record<string, unknown>, predicate: RequestBodyPredicate, state: RequestBodyState): boolean;
+/**
+ * The verdict for a request-body clause nothing satisfied, or `undefined` to fall through.
+ *
+ * Ranked the way the response side ranks its own: the two nobody could have answered (redacted,
+ * unrecorded, truncated) come before the one that WAS answered and came out false.
+ */
+export declare function requestBodyVerdict(state: RequestBodyState, predicate: NetPredicate, matchCount: number): EvalResult | undefined;
+export {};

package/dist/events/predicate-request-body.js

@@ -0,0 +1,120 @@
+/**
+ * Asserting on what the UI SENT, not on what came back (#798).
+ *
+ * `net.bodyContains` searches the response only, and the comment on it says why: searching the
+ * request too would let it pass on the very defect it exists to catch (the app sent `1187.01`, so
+ * that string is in the request whatever the server then did with it). That reasoning is right, and
+ * it leaves a real gap. For a filter, a search box or a form, the thing under test IS the outgoing
+ * payload — "applying this filter actually sends it" had no verdict at all, only
+ * `reticle_network { bodies: true }` and a person reading `requestBody` by eye.
+ *
+ * So these are separate fields rather than a mode on `bodyContains`: neither assertion can then be
+ * satisfied by the wrong half of the exchange.
+ *
+ * Extracted from `predicate-eval.ts`, which was at the 1000-line cap.
+ */
+import { REDACTED_VALUE } from '@reticlehq/core';
+import { clipBody, dataMatches, describeNetFilter, str, } from './predicate-eval.js';
+export function newRequestBodyState() {
+    return { unrecorded: false };
+}
+/**
+ * Does this event satisfy the predicate's request-body clauses? Records why not in `state`.
+ *
+ * Returns true when there is nothing to check, so callers can apply it unconditionally.
+ */
+export function checkRequestBody(data, predicate, state) {
+    const { requestBodyContains, requestBodyMatches } = predicate;
+    if (undefined === requestBodyContains && undefined === requestBodyMatches)
+        return true;
+    const sent = str(data['requestBody']);
+    if (sent === undefined) {
+        state.unrecorded = true;
+        return false;
+    }
+    const wasTruncated = true === data['requestBodyTruncated'];
+    const note = () => {
+        // The same rule the response side keeps: a needle missing from a body we hold only the first N
+        // bytes of is undecidable, not absent.
+        if (wasTruncated)
+            state.truncated ??= sent;
+        else
+            state.mismatch ??= sent;
+        return false;
+    };
+    if (requestBodyContains !== undefined && !sent.includes(requestBodyContains))
+        return note();
+    if (requestBodyMatches === undefined)
+        return true;
+    let payload;
+    try {
+        payload = JSON.parse(sent);
+    }
+    catch {
+        // Not JSON (a form post, plain text). A shallow key match cannot be applied, and guessing at
+        // form encoding here would answer a different question than the one asked. Use
+        // `requestBodyContains` for those.
+        return note();
+    }
+    if (null === payload || typeof payload !== 'object' || Array.isArray(payload))
+        return note();
+    const actual = payload;
+    const redacted = Object.keys(requestBodyMatches).find((key) => REDACTED_VALUE === actual[key]);
+    if (redacted !== undefined) {
+        state.redactedField ??= redacted;
+        return false;
+    }
+    return dataMatches(actual, requestBodyMatches) ? true : note();
+}
+/**
+ * The verdict for a request-body clause nothing satisfied, or `undefined` to fall through.
+ *
+ * Ranked the way the response side ranks its own: the two nobody could have answered (redacted,
+ * unrecorded, truncated) come before the one that WAS answered and came out false.
+ */
+export function requestBodyVerdict(state, predicate, matchCount) {
+    if (matchCount > 0)
+        return undefined;
+    const wanted = JSON.stringify(predicate.requestBodyContains ?? predicate.requestBodyMatches);
+    if (state.redactedField !== undefined) {
+        const field = JSON.stringify(state.redactedField);
+        return {
+            pass: false,
+            inconclusive: `a call matching ${describeNetFilter(predicate)} was made, but its ${field} was REDACTED before the body was recorded, so this clause cannot be judged — a redacted field is unknown, not different. Assert on a non-sensitive key, or on the effect the value had`,
+            observed: `a matching request whose ${field} is ${REDACTED_VALUE}`,
+            expected: `a request body matching ${wanted}`,
+            assertion: 'net.requestBodyMatches',
+        };
+    }
+    if (state.unrecorded) {
+        return {
+            pass: false,
+            failureReason: `a call matched but its REQUEST body was not recorded, so the request-body clause could not be checked — enable it where the app calls connect(): reticle({ captureNetworkBodies: true })`,
+            observed: 'a matching call with no recorded request body',
+            expected: `a request body matching ${wanted}`,
+            assertion: 'net.requestBody',
+        };
+    }
+    if (state.truncated !== undefined) {
+        return {
+            pass: false,
+            inconclusive: `a call matching ${describeNetFilter(predicate)} was sent with a request body that was TRUNCATED before it was recorded, and the clause did not hold over the part that was kept — so this is undecidable, not a failure`,
+            observed: `the first ${String(state.truncated.length)} characters of a truncated request body ${JSON.stringify(clipBody(state.truncated))}`,
+            expected: `a request body matching ${wanted}`,
+            assertion: 'net.requestBody',
+        };
+    }
+    if (state.mismatch !== undefined) {
+        // Named separately from "no call matched", for the reason the response side already learned: the
+        // request DID fire, and reporting zero matches sends the caller to check the url and the method,
+        // which are both fine, instead of to the value the UI actually sent.
+        return {
+            pass: false,
+            failureReason: `a call matching ${describeNetFilter(predicate)} was sent with ${JSON.stringify(clipBody(state.mismatch))}, which does not match the request-body clause — the request fired, the payload is what differed`,
+            observed: `request body ${JSON.stringify(clipBody(state.mismatch))}`,
+            expected: `a request body matching ${wanted}`,
+            assertion: 'net.requestBody',
+        };
+    }
+    return undefined;
+}

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

@@ -31,6 +31,24 @@ export declare const RouteDecidedBy: {
  * about where the app is, which is the failure this predicate exists to prevent.
  */
 export declare function routePathOf(pathname: string, hash: string): string;
+/**
+ * The resolved parts of a route, from a `ROUTE_CHANGE` event or a session URL.
+ *
+ * `routePath` is where the ROUTER is (the fragment path under a hash router). `docPath` + `hash`
+ * is the NAVIGABLE value a `reticle_navigate` can be pointed at. Call sites pick; collapsing
+ * them into one string is how a hash-router miss lands as "every page is `/`".
+ */
+export interface RouteParts {
+    routePath: string;
+    docPath: string;
+    hash: string;
+    search: string;
+    full: string;
+}
+/** A `ROUTE_CHANGE` event, or its `data` — one reading, so the sixth copy cannot drift. */
+export declare function routeOfEvent(eventOrData: ReticleEvent | Record<string, unknown>): RouteParts | undefined;
+/** Same shape from a session URL (the fallback when the tab hard-loaded and emitted no route event). */
+export declare function routeOfUrl(url: string): RouteParts | undefined;
 export declare function evalRoute(events: ReticleEvent[], p: Extract<Predicate, {
     kind: typeof PredicateKind.ROUTE;
 }>, 
@@ -43,4 +61,6 @@ export declare function evalRoute(events: ReticleEvent[], p: Extract<Predicate,
  * `reticle_snapshot({ mode: 'status' }).route` one call later. Optional so a caller with no session
  * (a replayed window) keeps the old answer instead of inventing a route.
  */
-currentUrl?: string): EvalResult;
+currentUrl?: string, 
+/** Event-time floor for the window, so a request already in flight before it is not counted. */
+since?: number): EvalResult;