@reticlehq/server 2.2.0 → 2.3.0

package/dist/events/predicate-eval.js

@@ -18,6 +18,7 @@ export const PredicateSchema = z.lazy(() => z.discriminatedUnion('kind', [
         method: z.string().optional(),
         urlContains: z.string().optional(),
         status: z.number().optional(),
+        ok: z.boolean().optional(),
         since: z.number().optional(),
         count: z.number().int().nonnegative().optional(),
     }),
@@ -129,6 +130,21 @@ function dataMatches(actual, pattern) {
     }
     return true;
 }
+/**
+ * Did this call succeed, as the app experienced it?
+ *
+ * `ok` is authoritative when present — IPC sets it explicitly, because an IPC call has no status
+ * code and the 200/500 Reticle derives is a convenience, not a fact. Falling back to the HTTP status
+ * keeps ordinary web requests working without the observer having to set the field everywhere.
+ *
+ * This exists so an agent can assert on the OUTCOME rather than on a number Reticle invented.
+ */
+function callSucceeded(data) {
+    if (typeof data['ok'] === 'boolean')
+        return data['ok'];
+    const status = num(data['status']);
+    return status === undefined || status < 400;
+}
 export function evalNet(events, p) {
     const since = p.since ?? 0;
     const matches = events.filter((e) => {
@@ -143,6 +159,8 @@ export function evalNet(events, p) {
         }
         if (p.status !== undefined && num(d['status']) !== p.status)
             return false;
+        if (p.ok !== undefined && callSucceeded(d) !== p.ok)
+            return false;
         return true;
     });
     // `count` (exact) turns presence into a cardinality assertion — catches the double-submit /
@@ -192,11 +210,17 @@ export function evalRoute(events, p) {
             assertion: 'route.pathname',
         };
     }
-    if (p.contains !== undefined && !pathname.includes(p.contains)) {
+    // `contains` matches the WHOLE route — path + query + fragment — while `pathname` above stays an
+    // exact path match. A hash router keeps the entire route in the fragment, so matching pathname
+    // alone made `contains` unsatisfiable for every HashRouter app; that is the standard router for a
+    // packaged Electron/Tauri renderer, where an absolute pushState would rewrite the URL to a
+    // nonexistent file.
+    const fullRoute = `${pathname}${str(last.data['search']) ?? ''}${str(last.data['hash']) ?? ''}`;
+    if (p.contains !== undefined && !fullRoute.includes(p.contains)) {
         return {
             pass: false,
-            failureReason: `route '${pathname}' does not contain '${p.contains}'`,
-            observed: `route '${pathname}'`,
+            failureReason: `route '${fullRoute}' does not contain '${p.contains}'`,
+            observed: `route '${fullRoute}'`,
             expected: `a route containing '${p.contains}'`,
             assertion: 'route.contains',
         };
@@ -380,14 +404,38 @@ export function evalSettled(events, p, now) {
     for (const [id, pending] of pendingById) {
         inFlight += Math.max(0, pending - (doneById.get(id) ?? 0));
     }
-    if (inFlight > 0) {
+    // A completed request whose BODY is still streaming is not a finished request. `fetch` resolves at
+    // HEADERS, so on a Next.js App Router page the RSC payload reported complete 16 ms in while the
+    // Suspense boundary's content arrived 889 ms later — and the silence between them read as a settled
+    // page with a loading spinner still on screen. An OPEN with no CLOSE is in flight, counted the same
+    // way as a pending with no completion.
+    const openStreams = new Set();
+    for (const e of events) {
+        if (e.type !== EventType.NET_STREAM)
+            continue;
+        const id = str(e.data['id']);
+        if (id === undefined)
+            continue;
+        const direction = str(e.data['direction']);
+        if (direction === 'open')
+            openStreams.add(id);
+        else if (direction === 'close')
+            openStreams.delete(id);
+    }
+    const streaming = openStreams.size;
+    if (inFlight + streaming > 0) {
+        const what = streaming === 0
+            ? `${String(inFlight)} request(s) still in flight`
+            : inFlight === 0
+                ? `${String(streaming)} response body(ies) still streaming`
+                : `${String(inFlight)} request(s) in flight and ${String(streaming)} response body(ies) still streaming`;
         return {
             pass: false,
-            failureReason: `not settled: ${String(inFlight)} request(s) still in flight`,
-            observed: `${String(inFlight)} request(s) still in flight`,
-            expected: 'no requests in flight',
+            failureReason: `not settled: ${what}`,
+            observed: what,
+            expected: 'no requests in flight and no response bodies still streaming',
             assertion: 'settled.in-flight',
-            evidence: { settled: false, inFlight },
+            evidence: { settled: false, inFlight, ...(streaming > 0 ? { streaming } : {}) },
         };
     }
     let lastT = -1;
@@ -417,4 +465,3 @@ export function evalSettled(events, p, now) {
         evidence: { quietForMs, lastActivity: lastType },
     };
 }
-//# sourceMappingURL=predicate-eval.js.map

package/dist/events/predicate.d.ts

@@ -37,4 +37,3 @@ export declare function waitForPredicate(session: PredicateSession, predicate: P
  * green ⇏ this-branch-held, re-checks each branch and keeps the winners.
  */
 export declare function provenExpectedLinks(session: PredicateSession, predicate: Predicate, since?: number): Promise<ExpectedLink[]>;
-//# sourceMappingURL=predicate.d.ts.map

package/dist/events/predicate.js

@@ -219,6 +219,38 @@ const POLL_INTERVAL_MS = 150;
  *  DOM/STATE round-trips. Small enough that added pass-detection latency is negligible next to the
  *  poll cadence, large enough to collapse a per-frame event storm into a bounded recheck rate. */
 const MIN_RECHECK_GAP_MS = 25;
+/**
+ * How long an exact-count predicate keeps watching AFTER it first reads true.
+ *
+ * A count only rises while a window is open, so "exactly N" is a statement about the END of one and
+ * cannot be settled early — yet every wait here resolves the moment a check passes. Live, on a real
+ * payments dashboard: a Refund confirm fired TWO POSTs 59 ms apart, and
+ * `until: { kind:'net', method:'POST', urlContains:'/refund', count:1 }` returned
+ * `pass: true, matched: 1`. Not a counting bug — `evalNet` counts occurrences correctly. The wait had
+ * already stopped looking. So `count: 1` silently meant "at least 1", which is the assertion the
+ * caller wrote `count` specifically to avoid, and the branch implementing it claims to catch "the
+ * double-submit / useEffect-double-fire / retry-storm regression class".
+ *
+ * 300 ms is chosen against the measured defect: the observed double-submit gap was 59 ms, a React
+ * double-effect fires within one commit, and a retry storm is faster still. It is a real ceiling, not
+ * a proof — a duplicate arriving 400 ms later still passes. Widening it costs every exact-count
+ * assertion that latency, so this trades an unbounded false green for a bounded one and says so.
+ */
+const COUNT_CONFIRM_MS = 300;
+/**
+ * Does this predicate assert an exact cardinality anywhere inside it?
+ *
+ * Only these hold after passing. A presence-only predicate ("at least one") IS satisfiable early and
+ * must stay that way, or every ordinary wait pays the confirmation delay for nothing.
+ */
+function assertsExactCount(predicate) {
+    if (predicate.kind === 'allOf' || predicate.kind === 'anyOf') {
+        return predicate.predicates.some(assertsExactCount);
+    }
+    if (predicate.kind === 'not')
+        return assertsExactCount(predicate.predicate);
+    return predicate.kind === 'net' && predicate.count !== undefined;
+}
 /**
  * Evaluate now, else wait for it to become true (on each event + a poll) until timeout. `since` is
  * the event-time floor (see evaluatePredicate) so a waiter cannot resolve on a stale buffered event.
@@ -231,6 +263,10 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
             failureReason: error instanceof Error ? error.message : String(error),
         });
         let cooldownTimer;
+        // An exact-count wait keeps watching after it first reads true — see COUNT_CONFIRM_MS.
+        const holdsForCount = assertsExactCount(predicate);
+        let confirming = false;
+        let confirmTimer;
         const finish = (result) => {
             if (done)
                 return;
@@ -240,6 +276,8 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
             clearTimeout(timer);
             if (cooldownTimer !== undefined)
                 clearTimeout(cooldownTimer);
+            if (confirmTimer !== undefined)
+                clearTimeout(confirmTimer);
             resolve(result);
         };
         // Coalesce re-checks: at most ONE evaluatePredicate is ever in flight (each can be a browser
@@ -267,8 +305,25 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
             // final timeout eval below runs with full diagnostics.
             void evaluatePredicate(session, predicate, since, false)
                 .then((r) => {
-                if (r.pass)
+                if (!r.pass)
+                    return;
+                // "Exactly N" cannot be concluded from a passing sample — the count can still rise. Hold,
+                // re-evaluate WITH diagnostics, and let that second read be the verdict: if an N+1th
+                // arrived in the meantime it now fails, carrying observed/expected rather than a bare no.
+                if (!holdsForCount) {
                     finish(r);
+                    return;
+                }
+                if (confirming)
+                    return;
+                confirming = true;
+                confirmTimer = setTimeout(() => {
+                    void evaluatePredicate(session, predicate, since)
+                        .then(finish)
+                        .catch((error) => {
+                        finish(failed(error));
+                    });
+                }, COUNT_CONFIRM_MS);
             })
                 .catch((error) => {
                 finish(failed(error));
@@ -339,4 +394,3 @@ export async function provenExpectedLinks(session, predicate, since = 0) {
     }
     return predicateToExpectedLinks(predicate);
 }
-//# sourceMappingURL=predicate.js.map

package/dist/events/reaction.d.ts

@@ -31,4 +31,3 @@ interface ReactionDigest {
  */
 export declare function summarizeReaction(report: ReactionReport): ReactionDigest;
 export {};
-//# sourceMappingURL=reaction.d.ts.map

package/dist/events/reaction.js

@@ -57,4 +57,3 @@ export function buildReactionReport(events, windowMs) {
 export function summarizeReaction(report) {
     return { window_ms: report.window_ms, summary: report.summary };
 }
-//# sourceMappingURL=reaction.js.map

package/dist/events/reconcile.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Compare what the API SAID against what the page SHOWS.
+ *
+ * Every other check in Reticle reads one side. This reads both, which is the one comparison only
+ * something living inside the app can make: the response body and the rendered text are in the same
+ * process, and nothing else holds them at the same time. A screenshot has the render and not the
+ * data; a network log has the data and not the render; a human reading either one sees a number that
+ * looks right.
+ *
+ * Two findings, both measured on a real payments dashboard:
+ *
+ *  - **the wrong currency.** `GET /payments` returns `{amount: 7997, currency: "USD"}` and the row
+ *    renders "₹79.97". The number is correct, the unit is not — a dollar amount presented as rupees.
+ *    Every channel agrees: 200, the digits match the data, the page settles.
+ *  - **a status that is never shown.** `GET /settlements` returns `status: "on_hold"` with
+ *    `hold_reason: "kyc_documents_expired"`, and the badge reads "pending". A merchant reads
+ *    "pending" and waits, while the payout is blocked on expired documents.
+ *
+ * Pure: response bodies and page text in, findings out. No session, no DOM, no clock.
+ */
+/** A finding: one field of one entity whose rendering disagrees with the data. */
+export interface Mismatch {
+    entity: string;
+    field: string;
+    /** What the API returned. */
+    api: string;
+    /** What the page shows instead — absent when the value simply never appears. */
+    rendered?: string;
+    why: string;
+}
+/** Every object carrying an `id`, at any depth. These are the things a UI renders as rows. */
+export declare function entitiesIn(node: unknown, out?: Record<string, unknown>[]): Record<string, unknown>[];
+/**
+ * Compare entities against the page's rendered text.
+ *
+ * `pageText` is the visible text of the page — the snapshot's own tree is exactly this, so no new
+ * capability is needed to obtain it.
+ */
+export declare function reconcile(bodies: readonly unknown[], pageText: string): Mismatch[];

package/dist/events/reconcile.js

@@ -0,0 +1,211 @@
+/**
+ * Compare what the API SAID against what the page SHOWS.
+ *
+ * Every other check in Reticle reads one side. This reads both, which is the one comparison only
+ * something living inside the app can make: the response body and the rendered text are in the same
+ * process, and nothing else holds them at the same time. A screenshot has the render and not the
+ * data; a network log has the data and not the render; a human reading either one sees a number that
+ * looks right.
+ *
+ * Two findings, both measured on a real payments dashboard:
+ *
+ *  - **the wrong currency.** `GET /payments` returns `{amount: 7997, currency: "USD"}` and the row
+ *    renders "₹79.97". The number is correct, the unit is not — a dollar amount presented as rupees.
+ *    Every channel agrees: 200, the digits match the data, the page settles.
+ *  - **a status that is never shown.** `GET /settlements` returns `status: "on_hold"` with
+ *    `hold_reason: "kyc_documents_expired"`, and the badge reads "pending". A merchant reads
+ *    "pending" and waits, while the payout is blocked on expired documents.
+ *
+ * Pure: response bodies and page text in, findings out. No session, no DOM, no clock.
+ */
+/**
+ * Currency markers, symbol and code. Deliberately a closed list: currency is one of the few things an
+ * app renders that has a fixed, publicly agreed vocabulary, which is what makes this checkable
+ * without knowing anything about the app.
+ */
+const CURRENCY_MARKS = {
+    INR: ['₹', 'INR', 'Rs.', 'Rs '],
+    USD: ['$', 'USD', 'US$'],
+    EUR: ['€', 'EUR'],
+    GBP: ['£', 'GBP'],
+    JPY: ['¥', 'JPY'],
+    AED: ['AED', 'د.إ'],
+    SGD: ['SGD', 'S$'],
+    AUD: ['AUD', 'A$'],
+};
+/** Currencies whose minor unit is not 1/100. Rendering these needs a different divisor. */
+const ZERO_DECIMAL = new Set(['JPY', 'KRW', 'VND']);
+/** Fields that name a state — the ones a badge renders and a user acts on. */
+const STATE_FIELDS = new Set(['status', 'state']);
+const ITEM_KEYS = ['items', 'results', 'data', 'records', 'rows', 'entries'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Every object carrying an `id`, at any depth. These are the things a UI renders as rows. */
+export function entitiesIn(node, out = []) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            entitiesIn(item, out);
+        return out;
+    }
+    if (!isRecord(node))
+        return out;
+    if (node['id'] !== undefined)
+        out.push(node);
+    for (const key of ITEM_KEYS) {
+        if (node[key] !== undefined)
+            entitiesIn(node[key], out);
+    }
+    return out;
+}
+/**
+ * Every way a UI might print a minor-unit integer as a major-unit amount.
+ *
+ * Real interfaces group digits, and they do not agree on how: "44,573.44" in most of the world,
+ * "44.573,44" across much of Europe, and "1,22,464.06" under the Indian lakh convention. Matching only
+ * the ungrouped form finds nothing on any app that formats its money, which is all of them — measured
+ * on a logistics console whose cells read "₹44,573.44" while the check searched for "44573.44".
+ */
+function majorForms(minor, currency) {
+    if (ZERO_DECIMAL.has(currency))
+        return [String(minor), group(String(minor)), indian(String(minor))];
+    const plain = (minor / 100).toFixed(2);
+    const [whole = '', fraction = ''] = plain.split('.');
+    return [
+        plain,
+        `${group(whole)}.${fraction}`,
+        `${indian(whole)}.${fraction}`,
+        // European: dots group, comma is the decimal separator.
+        `${group(whole).replace(/,/g, '.')},${fraction}`,
+    ];
+}
+/** Western grouping: every three digits from the right. */
+function group(whole) {
+    return whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+/** Indian grouping: the last three digits, then pairs — 1,22,464. */
+function indian(whole) {
+    if (whole.length <= 3)
+        return whole;
+    const last = whole.slice(-3);
+    const rest = whole.slice(0, -3);
+    return `${rest.replace(/\B(?=(\d{2})+(?!\d))/g, ',')},${last}`;
+}
+/** Does the text show this amount marked as some OTHER currency? Returns that marker. */
+function wrongCurrencyMark(text, amounts, expected) {
+    for (const amount of amounts) {
+        const mark = markBefore(text, amount, expected);
+        if (mark !== undefined)
+            return mark;
+    }
+    return undefined;
+}
+function markBefore(text, amount, expected) {
+    const at = text.indexOf(amount);
+    if (at === -1)
+        return undefined; // this rendering is not on screen — try the next
+    // Look just before the number, where a symbol or code sits. A window, not the whole page: the
+    // point is what is attached to THIS amount.
+    const before = text.slice(Math.max(0, at - 12), at);
+    const expectedMarks = CURRENCY_MARKS[expected] ?? [expected];
+    if (expectedMarks.some((mark) => before.includes(mark)))
+        return undefined;
+    for (const [code, marks] of Object.entries(CURRENCY_MARKS)) {
+        if (code === expected)
+            continue;
+        for (const mark of marks) {
+            if (before.includes(mark))
+                return mark;
+        }
+    }
+    return undefined;
+}
+/** Every form a state value might legitimately be rendered as: `on_hold`, `on hold`, `On Hold`. */
+function renderedForms(value) {
+    const spaced = value.replace(/[_-]+/g, ' ');
+    return [value, spaced, spaced.replace(/\s+/g, '')];
+}
+function shows(text, value) {
+    const haystack = text.toLowerCase();
+    return renderedForms(value).some((form) => haystack.includes(form.toLowerCase()));
+}
+/**
+ * Compare entities against the page's rendered text.
+ *
+ * `pageText` is the visible text of the page — the snapshot's own tree is exactly this, so no new
+ * capability is needed to obtain it.
+ */
+export function reconcile(bodies, pageText) {
+    const entities = bodies.flatMap((body) => entitiesIn(body));
+    const found = [];
+    const seen = new Set();
+    // Every value each state field took across the response set — used to tell "this value is simply
+    // not rendered anywhere" (uninteresting) from "a DIFFERENT value of this same field is rendered"
+    // (a mapping bug). Without that distinction the check would flag any field a UI chooses not to show.
+    const vocabulary = new Map();
+    for (const entity of entities) {
+        for (const [field, value] of Object.entries(entity)) {
+            if (!STATE_FIELDS.has(field) || typeof value !== 'string')
+                continue;
+            const values = vocabulary.get(field) ?? new Set();
+            values.add(value);
+            vocabulary.set(field, values);
+        }
+    }
+    for (const entity of entities) {
+        // An id is a string or a number in every API worth reconciling; anything else is not an identity
+        // this can report against, so the record is skipped rather than stringified into nonsense.
+        const raw = entity['id'];
+        if (typeof raw !== 'string' && typeof raw !== 'number')
+            continue;
+        const id = String(raw);
+        // Any numeric field on an entity that declares a currency is money in THAT currency. Checking a
+        // fixed field name instead would only ever work on APIs that happen to call it `amount` — the
+        // three real ones measured here use `amount`, `declaredValueMinor` and `total`.
+        //
+        // The check is still tight, because a value only counts when the page renders it AS money: the
+        // number must appear with a currency marker attached. A non-money number that happens to share a
+        // decimal form (a weight, a count) is rendered bare and never reaches the comparison.
+        const currency = entity['currency'];
+        if (typeof currency === 'string') {
+            for (const [field, value] of Object.entries(entity)) {
+                if (typeof value !== 'number' || field === 'currency')
+                    continue;
+                const printed = majorForms(value, currency);
+                const wrong = wrongCurrencyMark(pageText, printed, currency);
+                const key = `${id}:currency`;
+                if (wrong === undefined || seen.has(key))
+                    continue;
+                seen.add(key);
+                found.push({
+                    entity: id,
+                    field: 'currency',
+                    api: currency,
+                    rendered: wrong,
+                    why: `the API reports ${currency} ${String(value)} (minor units, field "${field}") and the page shows it marked "${wrong}" — the number is right and the currency is not, so the amount reads as a different one entirely`,
+                });
+            }
+        }
+        for (const [field, value] of Object.entries(entity)) {
+            if (!STATE_FIELDS.has(field) || typeof value !== 'string')
+                continue;
+            if (shows(pageText, value))
+                continue;
+            // Only interesting if the page renders SOME value of this field — otherwise the UI just does
+            // not display it, which is a design choice and not a defect.
+            const others = [...(vocabulary.get(field) ?? [])].filter((v) => v !== value);
+            const shown = others.filter((v) => shows(pageText, v));
+            const key = `${id}:${field}`;
+            if (shown.length === 0 || seen.has(key))
+                continue;
+            seen.add(key);
+            found.push({
+                entity: id,
+                field,
+                api: value,
+                why: `the API reports ${field}="${value}" for ${id}, and no rendering of that value appears on the page — while other values of the same field are shown (${shown.join(', ')}), so this record is being displayed as something it is not`,
+            });
+        }
+    }
+    return found;
+}

package/dist/events/ring-buffer.d.ts

@@ -31,4 +31,3 @@ export declare class RingBuffer {
     };
 }
 export {};
-//# sourceMappingURL=ring-buffer.d.ts.map

package/dist/events/ring-buffer.js

@@ -131,4 +131,3 @@ export class RingBuffer {
         return { total: this.#liveCount(), dropped: this.#droppedCount };
     }
 }
-//# sourceMappingURL=ring-buffer.js.map

package/dist/events/stale-response.d.ts

@@ -0,0 +1,4 @@
+import { type ReticleEvent } from '@reticlehq/core';
+import type { Contradiction } from './contradictions.js';
+/** The one contradiction, or none. Reported once per window — a race is a fact about the window. */
+export declare function findStaleResponses(events: readonly ReticleEvent[]): Contradiction[];

package/dist/events/stale-response.js

@@ -0,0 +1,139 @@
+import { ContradictionKind, EventType } from '@reticlehq/core';
+function pathOf(url) {
+    const q = url.indexOf('?');
+    return q === -1 ? url : url.slice(0, q);
+}
+function queryOf(url) {
+    const q = url.indexOf('?');
+    return q === -1 ? '' : url.slice(q + 1);
+}
+/**
+ * Parameters that ENUMERATE a collection rather than select within it.
+ *
+ * Two overlapping reads that differ only in these are a fan-out, not a race: an app fetching page 0
+ * and page 5 in parallel wants both, and whichever lands last is not overwriting the other. Measured
+ * against a synthetic dashboard doing parallel pagination — every run reported a race, because the
+ * requests do overlap and do settle out of order, and the original rule looked no further than that.
+ *
+ * A filter race differs in a SELECTING parameter (`status`, `q`, a date range): the second request
+ * makes the first obsolete, both answer into the same view, and the slower one wins.
+ */
+const ENUMERATING_PARAMS = new Set([
+    'page',
+    'offset',
+    'cursor',
+    'limit',
+    'size',
+    'per_page',
+    'perPage',
+    'pageSize',
+    'after',
+    'before',
+    'start',
+    'end',
+]);
+/** Whether the two queries differ ONLY in how much of the same collection they ask for. */
+function differsOnlyByEnumeration(first, second) {
+    const a = new URLSearchParams(first);
+    const b = new URLSearchParams(second);
+    const keys = new Set([...a.keys(), ...b.keys()]);
+    let differed = false;
+    for (const key of keys) {
+        if (a.get(key) === b.get(key))
+            continue;
+        if (!ENUMERATING_PARAMS.has(key))
+            return false;
+        differed = true;
+    }
+    return differed;
+}
+/** Pair NET_PENDING with its NET_REQUEST by the id both carry. Unpaired events are still in flight. */
+function flights(events) {
+    const issued = new Map();
+    const out = [];
+    for (const event of events) {
+        const id = typeof event.data['id'] === 'string' ? event.data['id'] : undefined;
+        if (id === undefined)
+            continue;
+        const at = typeof event.t === 'number' ? event.t : 0;
+        if (event.type === EventType.NET_PENDING) {
+            const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
+            const method = typeof event.data['method'] === 'string' ? event.data['method'] : 'GET';
+            issued.set(id, { url, method, at });
+            continue;
+        }
+        if (event.type !== EventType.NET_REQUEST)
+            continue;
+        const start = issued.get(id);
+        if (start === undefined)
+            continue; // started before this window — its ordering is unknowable
+        out.push({
+            id,
+            url: start.url,
+            method: start.method.toUpperCase(),
+            issuedAt: start.at,
+            settledAt: at,
+        });
+    }
+    return out;
+}
+/**
+ * Most recent flights compared per endpoint.
+ *
+ * The comparison is pairwise, so an unbounded window is quadratic: measured at 548ms for 2000
+ * concurrent reads of one endpoint, paid on EVERY verdict. A verdict that costs half a second is a
+ * verdict agents stop asking for. Racing requests are adjacent in time by definition, so the most
+ * recent flights are where a race can be; older ones cannot overlap them anyway.
+ *
+ * Bounded rather than silent: this is a detection ceiling, not a truncation of reported data — a race
+ * among more than this many simultaneous reads of ONE endpoint goes unreported, and that is a
+ * deliberate trade for a hot path that runs on every assert.
+ */
+const MAX_FLIGHTS_PER_PATH = 60;
+/** The one contradiction, or none. Reported once per window — a race is a fact about the window. */
+export function findStaleResponses(events) {
+    // Grouped by path first: two reads of DIFFERENT endpoints can never race, and comparing them was
+    // the bulk of the work on any real page, which talks to many endpoints at once.
+    const byPath = new Map();
+    for (const flight of flights(events)) {
+        if (flight.method !== 'GET')
+            continue;
+        const path = pathOf(flight.url);
+        const group = byPath.get(path) ?? [];
+        group.push(flight);
+        byPath.set(path, group);
+    }
+    for (const group of byPath.values()) {
+        const reads = group.slice(-MAX_FLIGHTS_PER_PATH);
+        const found = raceIn(reads);
+        if (found !== undefined)
+            return [found];
+    }
+    return [];
+}
+function raceIn(reads) {
+    for (const first of reads) {
+        for (const second of reads) {
+            if (first.id === second.id)
+                continue;
+            if (second.issuedAt <= first.issuedAt)
+                continue; // `first` must be the earlier request
+            if (second.issuedAt >= first.settledAt)
+                continue; // sequential, not overlapping
+            if (second.settledAt >= first.settledAt)
+                continue; // settled in order — no race
+            if (queryOf(first.url) === queryOf(second.url))
+                continue; // a retry, not a superseding query
+            // Parallel pagination is not a race — see differsOnlyByEnumeration.
+            if (differsOnlyByEnumeration(queryOf(first.url), queryOf(second.url)))
+                continue;
+            return {
+                kind: ContradictionKind.STALE_RESPONSE_APPLIED,
+                claim: `both reads of ${pathOf(first.url)} returned successfully and the page settled`,
+                counter: `the SUPERSEDED request (${queryOf(first.url)}) settled ${String(Math.max(0, first.settledAt - second.settledAt))}ms AFTER the one that replaced it (${queryOf(second.url)}), so the screen is showing the older query's data`,
+                detail: 'a filter/search race: the newer request was issued while the older was still in flight, and the older answered last, so whichever query the server happens to be slower at wins — unless the app cancels superseded requests or drops responses that no longer match current state',
+            };
+        }
+    }
+    return undefined;
+}

package/dist/events/unit-mismatch.d.ts

@@ -0,0 +1,16 @@
+import { type ReticleEvent } from '@reticlehq/core';
+import type { Contradiction } from './contradictions.js';
+/**
+ * @param prior events from BEFORE the window, used only to learn what the API has stated.
+ *
+ * The scale error is a disagreement with a value the API gave EARLIER — by definition before the
+ * action that sends it back. `reticle_assert` scopes its window to the last act's cursor, so the
+ * stating response falls outside it and `known` is empty exactly when it matters. Measured live on
+ * the payments panel: `reticle_observe` over a wide window reported the mismatch while `assert` on
+ * the same session reported none — the verdict tool, the one an agent gates on, was the blind one.
+ *
+ * Prior events TEACH, they are never themselves findings: widening the window instead would make
+ * every other rule blame this action for events it did not cause, and would re-report every earlier
+ * mistake on every assert.
+ */
+export declare function findUnitMismatches(events: readonly ReticleEvent[], prior?: readonly ReticleEvent[]): Contradiction[];