@reticlehq/server 2.2.1 → 2.4.0

package/dist/events/event-filters.js

@@ -42,8 +42,15 @@ export function eventMatchesFilters(e, filters) {
     }
     return false;
 }
-/** Match a net.request event against optional method/url/status filters (reticle_network). */
-export function matchNet(e, method, urlContains, status) {
+/**
+ * Match a net.request event against optional method/url/status/ok filters (reticle_network).
+ *
+ * `ok` is the filter the tool's own description points at for desktop IPC, whose 200/500 is derived
+ * rather than sent by any server. A still-PENDING call never matches an `ok` filter in either
+ * direction: unresolved is not the same as failed, and answering "yes, it failed" about a request
+ * still in flight is the false green this whole surface exists to prevent.
+ */
+export function matchNet(e, method, urlContains, status, ok) {
     const d = e.data;
     if (method !== undefined && asString(d['method'])?.toUpperCase() !== method.toUpperCase()) {
         return false;
@@ -53,6 +60,8 @@ export function matchNet(e, method, urlContains, status) {
     }
     if (status !== undefined && asNumber(d['status']) !== status)
         return false;
+    if (ok !== undefined && d['ok'] !== ok)
+        return false;
     return true;
 }
 /**
@@ -106,6 +115,8 @@ export function projectNetCall(e) {
     }
     if (ms !== undefined)
         view.ms = ms;
+    if (e.data['oneWay'] === true)
+        view.oneWay = true;
     const headers = e.data['headers'];
     if (headers !== null && typeof headers === 'object') {
         view.headers = headers;
@@ -182,4 +193,3 @@ export function consoleEmptyHint(allConsole) {
     }
     return { totalInWindow: allConsole.length, byLevel };
 }
-//# sourceMappingURL=event-filters.js.map

package/dist/events/json-salvage.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Read what CAN be read out of a truncated JSON payload.
+ *
+ * Response bodies are capped (8192 bytes) so one enormous payload cannot blow the transport budget.
+ * The cap is right; treating what it produces as "no body" is not. Measured on a 10,000-row console:
+ * the list response is 19,932 bytes, arrives truncated mid-object, `JSON.parse` throws, and every
+ * body-based check — currency reconciliation, per-item failures, unit mismatches — silently reported
+ * nothing on the one page with the most data to be wrong about.
+ *
+ * Worse, the tool then advised turning on body capture, which was already on. Advice that cannot
+ * work is more expensive than silence: it sends the reader to change a setting that is already
+ * correct, and teaches them the tool does not know what it is looking at.
+ *
+ * A truncated array of records is still mostly complete records. This recovers the ones that closed
+ * before the cut and reports how many it had to drop, so a partial answer is delivered AS partial
+ * rather than as a clean one.
+ */
+export interface Salvaged {
+    /** Parsed values — one whole body, or the records recovered from a truncated one. */
+    values: unknown[];
+    /** True when the payload was incomplete and only part of it could be read. */
+    partial: boolean;
+}
+/**
+ * Parse a body, falling back to whole records when it was cut short.
+ *
+ * The nesting caveat is real and stated rather than hidden: an object cut mid-nesting contributes its
+ * completed CHILDREN instead of itself, so a salvaged set can hold records the envelope would have
+ * grouped differently. For field-level comparison — is this id's currency rendered correctly — that
+ * costs nothing, because each record still carries its own id and its own fields.
+ */
+export declare function salvageJson(raw: string): Salvaged;

package/dist/events/json-salvage.js

@@ -0,0 +1,96 @@
+/**
+ * Read what CAN be read out of a truncated JSON payload.
+ *
+ * Response bodies are capped (8192 bytes) so one enormous payload cannot blow the transport budget.
+ * The cap is right; treating what it produces as "no body" is not. Measured on a 10,000-row console:
+ * the list response is 19,932 bytes, arrives truncated mid-object, `JSON.parse` throws, and every
+ * body-based check — currency reconciliation, per-item failures, unit mismatches — silently reported
+ * nothing on the one page with the most data to be wrong about.
+ *
+ * Worse, the tool then advised turning on body capture, which was already on. Advice that cannot
+ * work is more expensive than silence: it sends the reader to change a setting that is already
+ * correct, and teaches them the tool does not know what it is looking at.
+ *
+ * A truncated array of records is still mostly complete records. This recovers the ones that closed
+ * before the cut and reports how many it had to drop, so a partial answer is delivered AS partial
+ * rather than as a clean one.
+ */
+/**
+ * Complete `{...}` objects inside a truncated payload, in order.
+ *
+ * NOT top-level ones: a cut body is typically `{"rows":[{…},{…},{…` where the OUTER brace never
+ * closes, so nothing at depth 0 completes and a depth-0 scan recovers exactly nothing. The records
+ * are one level in.
+ *
+ * Objects are kept only at the SHALLOWEST depth at which anything closes — that is the record level.
+ * Keeping every depth would also return each record's nested children (a shipment's legs, an order's
+ * line items), and those carry their own `id` and `status`, which would pollute the comparison with
+ * values that were never meant to be rendered as rows.
+ */
+function completeObjects(text) {
+    const found = [];
+    let depth = 0;
+    const starts = [];
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i += 1) {
+        const ch = text[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === '{') {
+            starts.push(i);
+            depth += 1;
+            continue;
+        }
+        if (ch === '}') {
+            depth -= 1;
+            // A negative depth means the cut removed an opening brace; nothing further is trustworthy.
+            if (depth < 0)
+                break;
+            const start = starts.pop();
+            if (start !== undefined)
+                found.push({ depth: depth + 1, text: text.slice(start, i + 1) });
+        }
+    }
+    if (found.length === 0)
+        return [];
+    const shallowest = Math.min(...found.map((f) => f.depth));
+    return found.filter((f) => f.depth === shallowest).map((f) => f.text);
+}
+/**
+ * Parse a body, falling back to whole records when it was cut short.
+ *
+ * The nesting caveat is real and stated rather than hidden: an object cut mid-nesting contributes its
+ * completed CHILDREN instead of itself, so a salvaged set can hold records the envelope would have
+ * grouped differently. For field-level comparison — is this id's currency rendered correctly — that
+ * costs nothing, because each record still carries its own id and its own fields.
+ */
+export function salvageJson(raw) {
+    try {
+        return { values: [JSON.parse(raw)], partial: false };
+    }
+    catch {
+        // fall through to record-level recovery
+    }
+    const values = [];
+    for (const chunk of completeObjects(raw)) {
+        try {
+            values.push(JSON.parse(chunk));
+        }
+        catch {
+            // a chunk that still will not parse is simply not recovered
+        }
+    }
+    return { values, partial: true };
+}

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

@@ -15,6 +15,8 @@ export type Predicate = {
     method?: string;
     urlContains?: string;
     status?: number;
+    /** Did the call succeed? The honest field for IPC, which has no status code. */
+    ok?: boolean;
     since?: number;
     count?: number;
 } | {
@@ -103,4 +105,3 @@ export declare function evalSignal(events: ReticleEvent[], p: Extract<Predicate,
 export declare function evalSettled(events: ReticleEvent[], p: Extract<Predicate, {
     kind: 'settled';
 }>, now: number): EvalResult;
-//# sourceMappingURL=predicate-eval.d.ts.map

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