@reticlehq/server 2.2.1 → 2.4.0

package/dist/events/body-failures.js

@@ -0,0 +1,113 @@
+import { ContradictionKind, EventType } from '@reticlehq/core';
+/**
+ * A request that returned 2xx and reported failure INSIDE its body.
+ *
+ * The status line is not the outcome. Three shapes make this routine rather than exotic:
+ *
+ *  - **GraphQL** answers HTTP 200 for every error it has ever produced. `errors: [...]` in a 200 body
+ *    is the normal way a GraphQL request fails, so any verdict that reads only the status is blind to
+ *    the entire error surface of an entire ecosystem.
+ *  - **Bulk endpoints** answer 200 for the batch and put per-item results in the body. Measured on a
+ *    shipments console: `POST /api/bulk-hold` → 200, banner reads "9 shipments held", and three of
+ *    the nine carry `{"ok": false, "error": "carrier_locked"}`. Reticle had that body in hand and
+ *    reported `verified: "yes"`.
+ *  - **Envelope APIs** answer 200 with `{"success": false}` — common wherever a gateway normalises
+ *    status codes.
+ *
+ * Every channel above the body agrees with the lie: the request succeeded, the UI advanced, the page
+ * settled, nothing 5xx'd. Only the payload disagrees, which is why this needs body capture — and why
+ * an agent reading a status column can never catch it.
+ */
+/** Keys whose truthiness means "this failed". Checked at the top level and per item. */
+const FAILURE_FLAGS = ['ok', 'success', 'succeeded'];
+/** Keys that, when carrying content, name a failure. */
+const ERROR_KEYS = ['error', 'errors', 'errorMessage', 'failureReason'];
+/** Arrays worth walking for per-item outcomes. Bulk APIs converge on a handful of names. */
+const ITEM_KEYS = ['results', 'items', 'data', 'records', 'responses'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Whether one object reports a failure of its own. */
+function reportsFailure(item) {
+    if (!isRecord(item))
+        return false;
+    for (const flag of FAILURE_FLAGS) {
+        if (item[flag] === false)
+            return true;
+    }
+    for (const key of ERROR_KEYS) {
+        const value = item[key];
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            if (value.length > 0)
+                return true;
+            continue;
+        }
+        // An empty string or an explicit null is an API saying "no error", not an error.
+        if (typeof value === 'string' && value.length === 0)
+            continue;
+        return true;
+    }
+    return false;
+}
+/** Failed / total across the first item array found. Zero total when the body is not a batch. */
+function itemOutcomes(body) {
+    for (const key of ITEM_KEYS) {
+        const list = body[key];
+        if (!Array.isArray(list) || list.length === 0)
+            continue;
+        const failed = list.filter(reportsFailure).length;
+        return { failed, total: list.length };
+    }
+    return { failed: 0, total: 0 };
+}
+function parse(raw) {
+    if (typeof raw !== 'string' || raw.length === 0)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined; // not JSON — nothing to read, and guessing at prose would invent findings
+    }
+}
+const OK_MIN = 200;
+const OK_MAX = 300;
+/** Contradictions for 2xx responses whose bodies report failure. One per offending call. */
+export function findBodyFailures(events) {
+    const found = [];
+    for (const event of events) {
+        if (event.type !== EventType.NET_REQUEST)
+            continue;
+        const status = event.data['status'];
+        if (typeof status !== 'number' || status < OK_MIN || status >= OK_MAX)
+            continue;
+        const body = parse(event.data['responseBody']);
+        if (body === undefined)
+            continue;
+        const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
+        const method = typeof event.data['method'] === 'string' ? event.data['method'] : '';
+        const where = `${method} ${url} → ${String(status)}`;
+        const { failed, total } = itemOutcomes(body);
+        if (failed > 0) {
+            found.push({
+                kind: ContradictionKind.PARTIAL_FAILURE_IN_OK_RESPONSE,
+                claim: `the request returned ${String(status)} and the page treated it as done`,
+                counter: `its body reports ${String(failed)} of ${String(total)} items FAILED`,
+                detail: `${where} — a batch endpoint's status describes the BATCH, not the items; whatever the UI says it did, ${String(failed)} of them did not happen`,
+            });
+            continue;
+        }
+        if (reportsFailure(body)) {
+            found.push({
+                kind: ContradictionKind.PARTIAL_FAILURE_IN_OK_RESPONSE,
+                claim: `the request returned ${String(status)} and the page treated it as done`,
+                counter: 'its body reports the operation FAILED',
+                detail: `${where} — the status line and the payload disagree; the payload is the outcome (a GraphQL error is always a 200)`,
+            });
+        }
+    }
+    return found;
+}

package/dist/events/contradictions.d.ts

@@ -0,0 +1,53 @@
+import { ContradictionKind, type ReticleEvent } from '@reticlehq/core';
+/**
+ * The contradiction hunter.
+ *
+ * Every other check in Reticle reads ONE channel and asks "did something bad happen there?" — a
+ * console error, a 500, a control that did nothing. A human can do that too, just slower.
+ *
+ * This asks a question a human structurally cannot: do the channels DISAGREE with each other? A
+ * person watching an app has exactly one channel open — the screen. The agent holds the DOM, the
+ * store, the app's own signals, the console and the network in one causally ordered window, so it
+ * can catch the case where the screen says one thing and the network says the opposite.
+ *
+ * That gap is where false greens live. The archetype ships in both desktop demos: click Archive, the
+ * row disappears, the status line reads "archived", and the IPC call rejected into a swallowed
+ * `.catch()`. A screenshot agrees. A DOM assertion agrees. A human agrees. Only the disagreement
+ * between channels reveals it.
+ *
+ * Pure: a window of events in, findings out. No session, no IO, no clock.
+ */
+export interface Contradiction {
+    kind: ContradictionKind;
+    /** What one channel asserted — the optimistic half. */
+    claim: string;
+    /** What the other channel asserted — the half that contradicts it. */
+    counter: string;
+    /** Concrete evidence, so the agent can go straight to the call or the control. */
+    detail: string;
+}
+export interface ContradictionOptions {
+    /** The action that opened this window, when one did. Enables the no-effect check. */
+    action?: string | undefined;
+    /**
+     * Events from BEFORE the window, used only to LEARN — never reported on. Some disagreements are
+     * with something the API stated earlier in the session, which an action-scoped window cannot
+     * contain. See `findUnitMismatches` for the measured case this exists for.
+     */
+    prior?: readonly ReticleEvent[] | undefined;
+    /**
+     * DOM mutations observed INSIDE the target's own subtree, as the act tool measured them.
+     *
+     * The no-effect check used to require a completely empty window, which is a statement about the
+     * PAGE rather than about the action — and no real app has a quiet page. Measured on a shipments
+     * console with a background event stream: clicking an inert heading produced `domMutatedWithin: 0`
+     * and four ambient events (a scroll position, an unrelated store update, a perf sample), so the
+     * window was not empty and the dead control went unreported. The user's framing of this is exact:
+     * the DOM moving after an action is not evidence that the action moved it.
+     *
+     * Undefined means the caller did not measure it — the check then falls back to the empty-window
+     * test, which is weaker but never wrong in the direction of a false accusation.
+     */
+    mutatedWithin?: number | undefined;
+}
+export declare function findContradictions(events: readonly ReticleEvent[], options?: ContradictionOptions): Contradiction[];

package/dist/events/contradictions.js

@@ -0,0 +1,282 @@
+import { ContradictionKind, EventType, MUTATING_METHODS } from '@reticlehq/core';
+import { findStaleResponses } from './stale-response.js';
+import { findBodyFailures } from './body-failures.js';
+import { findEchoMismatches } from './echo-mismatch.js';
+import { findUnitMismatches } from './unit-mismatch.js';
+import { asNumber, asString } from '../tools/tools-helpers.js';
+function netCall(e) {
+    const status = asNumber(e.data['status']);
+    return {
+        method: (asString(e.data['method']) ?? '').toUpperCase(),
+        url: asString(e.data['url']) ?? '',
+        status,
+        // `ok` is authoritative when present (IPC sets it explicitly); status is the HTTP fallback.
+        // Neither present = no verdict was ever reported, which stays undefined all the way through.
+        ok: e.data['ok'] === undefined && status === undefined
+            ? undefined
+            : e.data['ok'] === true || (e.data['ok'] === undefined && (status ?? 0) < 400),
+    };
+}
+/**
+ * Did the user-visible application state move forward? DOM, store and route only — deliberately NOT
+ * network, animation or signal. The question every rule below asks is "did the app act as if it
+ * succeeded", and a request firing is not the app acting as if anything.
+ */
+function uiAdvanced(events) {
+    return events.some((e) => e.type === EventType.DOM_ADDED ||
+        e.type === EventType.DOM_REMOVED ||
+        e.type === EventType.DOM_ATTR ||
+        e.type === EventType.DOM_TEXT ||
+        e.type === EventType.STATE_CHANGE ||
+        e.type === EventType.ROUTE_CHANGE);
+}
+function isMutating(call) {
+    return MUTATING_METHODS.includes(call.method);
+}
+/**
+ * State paths/values that read as the app recording a failure rather than hiding one.
+ *
+ * English-only, and knowingly so — this is the softest edge in the file. It is a fallback for when
+ * the structural check below cannot decide, not the primary signal.
+ */
+const ACKNOWLEDGED = /error|fail|invalid|reject|denied|unable|could not|couldn't/i;
+/**
+ * Below this length an error string is too generic to be evidence — "no", "err", a bare code — and
+ * could coincide with unrelated state text.
+ */
+const MIN_ECHOED_ERROR_LENGTH = 8;
+/**
+ * Wording that blames the USER — bad credentials, no permission, wrong input. Distinct from
+ * ACKNOWLEDGED, which merely means "a failure was recorded": an app can honestly report a failure
+ * ("server error, try again") without misattributing it.
+ */
+const BLAMES_USER = /denied|invalid|unauthor|forbidden|incorrect|wrong |not allowed|not permitted/i;
+/** A server-fault status: the user cannot fix it and should never be asked to. */
+const SERVER_FAULT_MIN = 500;
+/**
+ * Did the app record the failure in its OWN state — the layer the UI renders from?
+ *
+ * Without this, "the UI moved while a request failed" fires on correct code: a handler that catches
+ * the rejection and renders "could not add" also moves the UI. Both look identical at the level of
+ * "DOM changed + request failed"; what separates them is whether the app acknowledged the failure
+ * anywhere, or silently proceeded as if it had succeeded.
+ *
+ * Deliberately NOT satisfied by a console error. `console.error` is invisible to the user, so an app
+ * that logs and then shows success is still lying to whoever is looking at it — precisely the case
+ * worth reporting.
+ *
+ * A heuristic, and the one soft edge in this file: an app that surfaces failure through a value this
+ * pattern does not recognize will produce a finding a human must dismiss. That direction is the safe
+ * one — a false alarm costs a glance, a missed false green ships.
+ */
+function failureAcknowledged(events) {
+    // STRUCTURAL first, and language-independent: if the app put the failed call's OWN error text into
+    // its state, it plainly knows the call failed — whatever language it says so in. The lexical
+    // patterns below are English-only, so without this a German or Japanese app that surfaces its
+    // failure perfectly well would be reported as hiding it.
+    const errors = events
+        .filter((e) => e.type === EventType.NET_REQUEST && e.data['ok'] !== true)
+        .map((e) => asString(e.data['error']))
+        .filter((text) => text !== undefined && text.length >= MIN_ECHOED_ERROR_LENGTH);
+    const echoesAnError = events.some((e) => {
+        if (e.type !== EventType.STATE_CHANGE)
+            return false;
+        const value = asString(e.data['value']);
+        return value !== undefined && errors.some((text) => value.includes(text));
+    });
+    if (echoesAnError)
+        return true;
+    return events.some((e) => {
+        // A failure-shaped SIGNAL is an acknowledgement too. An app that fires `auth:denied` has plainly
+        // not proceeded as if it succeeded, whatever its state paths happen to be named.
+        if (e.type === EventType.SIGNAL)
+            return ACKNOWLEDGED.test(asString(e.data['name']) ?? '');
+        if (e.type !== EventType.STATE_CHANGE)
+            return false;
+        const path = asString(e.data['path']) ?? '';
+        const value = e.data['value'];
+        return ACKNOWLEDGED.test(path) || (typeof value === 'string' && ACKNOWLEDGED.test(value));
+    });
+}
+function describe(call) {
+    return `${call.method} ${call.url}${call.status === undefined ? '' : ` → ${String(call.status)}`}`;
+}
+/**
+ * Actions that are SUPPOSED to make something happen, so producing nothing is a finding.
+ *
+ * Deliberately narrow. `hover`, `focus` and `scrollIntoView` can legitimately move nothing, and
+ * `fill`/`type` change an input's value without necessarily mutating the DOM tree — flagging those
+ * would manufacture noise, which is the failure mode opposite to a false green and just as bad.
+ */
+const MUST_DO_SOMETHING = new Set(['click', 'dblclick', 'submit']);
+/**
+ * Whether NOTHING in this window is attributable to the action.
+ *
+ * Ambient churn is deliberately not counted as evidence the action worked — a background event
+ * stream, a polling store, a perf sample and a scroll position all move on their own. What counts:
+ *
+ *  - a mutation inside the target's own subtree (what the target itself did),
+ *  - a request (the action asked the server for something),
+ *  - a navigation, or a dialog/live region appearing — the two ways a real reaction legitimately
+ *    lands OUTSIDE the target, e.g. a modal portalled to the body.
+ *
+ * The last clause is what keeps this from manufacturing noise: a button that opens a modal mutates
+ * nothing within itself, and must not be called dead.
+ */
+function didNothing(events, requests, mutatedWithin) {
+    if (mutatedWithin === undefined)
+        return events.length === 0;
+    if (mutatedWithin > 0 || requests.length > 0)
+        return false;
+    return !events.some((e) => e.type === EventType.ROUTE_CHANGE || e.type === EventType.VISIBLE_SHOWN);
+}
+export function findContradictions(events, options = {}) {
+    const found = [];
+    const settled = events.filter((e) => e.type === EventType.NET_REQUEST).map(netCall);
+    // ── Overlapping reads that settled out of order ─────────────────────────────────────────────
+    // Independent of any action, so it runs on every window: the race is a property of the timeline.
+    found.push(...findStaleResponses(events));
+    // ── A 2xx whose BODY says it failed ─────────────────────────────────────────────────────────
+    // Needs body capture; silent without it, which is why the assert path also declares when bodies
+    // were never recorded rather than letting an unread payload read as an empty one.
+    found.push(...findBodyFailures(events));
+    found.push(...findEchoMismatches(events));
+    // ── A money value written back at the wrong SCALE ───────────────────────────────────────────
+    found.push(...findUnitMismatches(events, options.prior ?? []));
+    // ── The action landed on something that does not react ──────────────────────────────────────
+    // Checked first and returned alone: nothing is attributable to the action, so every rule below is
+    // reasoning about someone else's events.
+    const action = (options.action ?? '').toLowerCase();
+    if (MUST_DO_SOMETHING.has(action) && didNothing(events, settled, options.mutatedWithin)) {
+        const measured = options.mutatedWithin !== undefined;
+        return [
+            {
+                kind: ContradictionKind.ACTION_HAD_NO_EFFECT,
+                claim: `the ${action} was dispatched and the page settled`,
+                counter: measured
+                    ? 'nothing changed inside the target, and no request, navigation or dialog followed — whatever else moved on the page was not this'
+                    : 'no channel observed anything at all — DOM, store, route, network, signal, console',
+                detail: 'the target does not react to this action (a non-interactive wrapper resolved instead of the control, a disabled handler, or a no-op) — settling proves only that the page was quiet, which a page that did nothing always is',
+            },
+        ];
+    }
+    const failed = settled.filter((c) => c.ok === false);
+    const advanced = uiAdvanced(events);
+    const signals = events
+        .filter((e) => e.type === EventType.SIGNAL)
+        .map((e) => asString(e.data['name']) ?? 'signal');
+    // ── The route moved and nothing was rendered for it ─────────────────────────────────────────
+    // A navigation that neither fetches nor renders arrived nowhere. Distinct from a dead control:
+    // the control worked, the DESTINATION is empty — which is why every "did the click do something"
+    // heuristic passes it, a route change being unambiguously something.
+    const routed = events.some((e) => e.type === EventType.ROUTE_CHANGE);
+    const rendered = events.some((e) => e.type === EventType.DOM_ADDED || e.type === EventType.DOM_REMOVED);
+    const fetched = events.some((e) => e.type === EventType.NET_REQUEST || e.type === EventType.NET_PENDING);
+    if (routed && !rendered && !fetched) {
+        found.push({
+            kind: ContradictionKind.ROUTE_RENDERED_NOTHING,
+            claim: 'the app navigated to a new route',
+            counter: 'nothing was rendered for it — no content added or removed, and no request made',
+            detail: 'the URL moved but the destination produced no content: a route with no view, a view that returned null, or data the page never asked for. A control that navigates always looks alive, so this is invisible to a dead-control check. Confirm by reading the page — a view revealed from DOM that already existed emits this same window',
+        });
+    }
+    // ── The app claimed success while its own request failed ────────────────────────────────────
+    // A signal is the sharper claim: the app did not merely LOOK right, it explicitly asserted
+    // success. When both hold it is one fact, so only the sharper one is reported.
+    // ── The server faulted and the app blamed the user ──────────────────────────────────────────
+    // Checked BEFORE the success-claim rules, because it is the sharper reading of the same events:
+    // the app did not claim success, it claimed the wrong failure. Telling someone their password is
+    // wrong while the backend is down sends them to fix something they cannot fix.
+    const serverFaults = settled.filter((c) => c.ok === false && c.status !== undefined && c.status >= SERVER_FAULT_MIN);
+    const userBlame = [
+        ...signals.filter((name) => BLAMES_USER.test(name)),
+        ...events
+            .filter((e) => e.type === EventType.STATE_CHANGE)
+            .map((e) => asString(e.data['value']) ?? '')
+            .filter((value) => BLAMES_USER.test(value)),
+    ];
+    const misattributed = serverFaults.length > 0 && userBlame.length > 0;
+    if (misattributed) {
+        found.push({
+            kind: ContradictionKind.FAILURE_MISATTRIBUTED,
+            claim: `the app told the user they were at fault (${userBlame.map((b) => `"${b}"`).join(', ')})`,
+            counter: 'the server returned a 5xx — the user cannot fix this and the real fault is unreported',
+            detail: serverFaults.map(describe).join('; '),
+        });
+    }
+    // A failure-shaped signal is not a success claim, so it must not be read as one: saying "the app
+    // claimed success" about an app that plainly reported a failure is true in outline and wrong in
+    // its reasoning, which is how a checker stops being believed.
+    const successSignals = signals.filter((name) => !ACKNOWLEDGED.test(name));
+    if (failed.length > 0 && successSignals.length > 0) {
+        found.push({
+            kind: ContradictionKind.SIGNAL_CONTRADICTED,
+            claim: `the app fired ${successSignals.map((s) => `"${s}"`).join(', ')}`,
+            counter: `${String(failed.length)} request(s) in the same window failed`,
+            detail: failed.map(describe).join('; '),
+        });
+    }
+    else if (failed.length > 0 && advanced && !misattributed && !failureAcknowledged(events)) {
+        found.push({
+            kind: ContradictionKind.UI_ADVANCED_REQUEST_FAILED,
+            claim: 'the UI moved forward (DOM/store/route changed)',
+            counter: `${String(failed.length)} request(s) in the same window failed`,
+            detail: failed.map(describe).join('; '),
+        });
+    }
+    // ── A write succeeded and nothing on the client moved ───────────────────────────────────────
+    // Writes only: a GET that changes nothing is a prefetch; a POST that changes nothing is a lost
+    // write, a response parsed into the void, or a render that never happened.
+    if (!advanced) {
+        const ignoredWrites = settled.filter((c) => c.ok === true && isMutating(c));
+        if (ignoredWrites.length > 0) {
+            found.push({
+                kind: ContradictionKind.RESPONSE_IGNORED,
+                claim: `${String(ignoredWrites.length)} write(s) succeeded on the server`,
+                counter: 'nothing on the client changed — no DOM, store or route movement',
+                detail: ignoredWrites.map(describe).join('; '),
+            });
+        }
+    }
+    // ── The same write fired more than once ─────────────────────────────────────────────────────
+    const writeCounts = new Map();
+    for (const call of settled) {
+        if (!isMutating(call))
+            continue;
+        const key = `${call.method} ${call.url}`;
+        writeCounts.set(key, (writeCounts.get(key) ?? 0) + 1);
+    }
+    for (const [key, count] of writeCounts) {
+        if (count < 2)
+            continue;
+        found.push({
+            kind: ContradictionKind.DUPLICATE_REQUEST,
+            claim: 'one user action was performed',
+            counter: `the same write fired ${String(count)} times`,
+            detail: `${key} ×${String(count)}`,
+        });
+    }
+    // ── The UI advanced over a request that never came back ─────────────────────────────────────
+    // Gated on the UI having moved: an in-flight request while the app is still visibly waiting is
+    // just a slow request, not a contradiction. It becomes one when the app proceeded regardless —
+    // which is also what makes a later `{ kind: "settled" }` assertion a false green.
+    if (advanced) {
+        const settledIds = new Set(events
+            .filter((e) => e.type === EventType.NET_REQUEST)
+            .map((e) => asString(e.data['id']))
+            .filter((id) => id !== undefined));
+        const inFlight = events
+            .filter((e) => e.type === EventType.NET_PENDING)
+            .map((e) => ({ id: asString(e.data['id']), call: netCall(e) }))
+            .filter((p) => p.id === undefined || !settledIds.has(p.id));
+        if (inFlight.length > 0) {
+            found.push({
+                kind: ContradictionKind.REQUEST_NEVER_SETTLED,
+                claim: 'the UI moved forward and the action reported done',
+                counter: `${String(inFlight.length)} request(s) were still in flight`,
+                detail: inFlight.map((p) => describe(p.call)).join('; '),
+            });
+        }
+    }
+    return found;
+}

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

@@ -0,0 +1,4 @@
+import { type ReticleEvent } from '@reticlehq/core';
+import type { Contradiction } from './contradictions.js';
+/** Contradictions for writes whose response echoes a different value than the request asked for. */
+export declare function findEchoMismatches(events: readonly ReticleEvent[]): Contradiction[];

package/dist/events/echo-mismatch.js

@@ -0,0 +1,138 @@
+import { ContradictionKind, EventType } from '@reticlehq/core';
+/**
+ * A write that returned OK and quietly did not apply part of what it was asked to.
+ *
+ * Measured on a desktop preferences write: the request asked for `{density:'compact', locale:'fr'}`,
+ * the response echoed `{"ok":true,"saved":{"density":"compact","locale":"en"}}`, the UI said
+ * "Preferences saved", and every channel agreed. `locale` was silently discarded. Nothing above the
+ * payload can see this — the status is 200, the body reports no failure, the UI advanced, the page
+ * settled. It is a false green with the evidence already in hand.
+ *
+ * The shape is ordinary in real backends: a field not in the UPDATE statement, a schema that strips
+ * unknown keys, a PATCH that honours a subset, an enum that falls back to a default.
+ *
+ * ## Why this is narrow on purpose
+ *
+ * Servers legitimately transform what they echo — trimming, lower-casing, rounding, canonicalising,
+ * filling defaults, assigning ids and timestamps. A rule that flagged every echoed field that differs
+ * would fire on healthy APIs constantly, and a contradiction kind that cries wolf gets filtered out
+ * by the agents reading it, taking the true positives with it. So:
+ *
+ *  - only keys the request actually SENT are considered;
+ *  - only scalars, since deep structural diffing is where the false positives live;
+ *  - values are compared NORMALISED (trimmed, case-folded, numbers as numbers), so `FR` vs `fr` and
+ *    `1` vs `1.0` stay silent while `fr` vs `en` speaks;
+ *  - if the key appears anywhere in the response carrying the requested value, it is treated as
+ *    applied — an envelope that echoes both the old and the new value is not a dropped write.
+ *
+ * The residue after those filters is a field the caller set, the server echoed back, and the echoed
+ * value is a genuinely different value. That is worth one line of an agent's attention.
+ */
+/** Bodies larger than this are skipped — a diff over a huge payload is neither cheap nor legible. */
+const MAX_ECHO_KEYS = 200;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Any JSON value, not just an object. An HTTP write sends an object; an IPC call sends its ARGUMENT
+ * LIST, so `savePrefs({locale})` arrives as `[{"locale":"fr"}]`. Requiring a top-level object here
+ * silently excluded every desktop write from this check — the exact platform the finding came from.
+ */
+function parse(raw) {
+    if (typeof raw !== 'string' || raw.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Comparable form of a scalar. Non-scalars return undefined and are never compared. */
+function normalize(value) {
+    if (typeof value === 'string')
+        return value.trim().toLowerCase();
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? String(value) : undefined;
+    if (typeof value === 'boolean')
+        return String(value);
+    return undefined;
+}
+/**
+ * Every scalar value the response carries for each key, at any depth.
+ *
+ * Depth matters because the echo is usually nested — `{ok:true, saved:{...}}`, `{data:{...}}`,
+ * `{result:{...}}` — and demanding the same path as the request would miss nearly every real API.
+ * Collecting ALL values for a key is what makes the "echoes both old and new" case safe.
+ */
+function scalarsByKey(body, into = new Map(), depth = 0) {
+    if (depth > 6 || into.size > MAX_ECHO_KEYS)
+        return into;
+    if (Array.isArray(body)) {
+        for (const item of body)
+            scalarsByKey(item, into, depth + 1);
+        return into;
+    }
+    if (!isRecord(body))
+        return into;
+    for (const [key, value] of Object.entries(body)) {
+        const scalar = normalize(value);
+        if (scalar === undefined) {
+            scalarsByKey(value, into, depth + 1);
+            continue;
+        }
+        const seen = into.get(key) ?? new Set();
+        seen.add(scalar);
+        into.set(key, seen);
+    }
+    return into;
+}
+const OK_MIN = 200;
+const OK_MAX = 300;
+/** Contradictions for writes whose response echoes a different value than the request asked for. */
+export function findEchoMismatches(events) {
+    const found = [];
+    for (const event of events) {
+        if (event.type !== EventType.NET_REQUEST)
+            continue;
+        // IPC reports `ok` rather than a status; HTTP reports a status. Either must say success — a write
+        // that already failed is a different (and louder) finding than one that half-applied.
+        const status = event.data['status'];
+        const httpOk = typeof status === 'number' && status >= OK_MIN && status < OK_MAX;
+        if (!httpOk && event.data['ok'] !== true)
+            continue;
+        const request = parse(event.data['requestBody']);
+        const response = parse(event.data['responseBody']);
+        if (request === undefined || response === undefined)
+            continue;
+        const echoed = scalarsByKey(response);
+        const asked = scalarsByKey(request);
+        const dropped = [];
+        for (const [key, wanted] of asked) {
+            // More than one requested value for a key (a before/after pair, a list of items) makes "what
+            // was asked for" ambiguous, and a guess here is exactly how this kind would earn a reputation
+            // for crying wolf.
+            if (wanted.size !== 1)
+                continue;
+            const values = echoed.get(key);
+            // Not echoed at all = no evidence either way. Only a key the server chose to report back can
+            // contradict the request, and silence is not a contradiction.
+            if (values === undefined || values.size === 0)
+                continue;
+            const [want] = [...wanted];
+            if (want !== undefined && !values.has(want))
+                dropped.push(`${key}: asked ${want}, got ${[...values].join('/')}`);
+        }
+        if (dropped.length === 0)
+            continue;
+        const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
+        const method = typeof event.data['method'] === 'string' ? event.data['method'] : '';
+        found.push({
+            kind: ContradictionKind.WRITE_FIELD_IGNORED,
+            claim: 'the write returned success and the page treated it as saved',
+            counter: `its own echo shows ${String(dropped.length)} field(s) NOT applied — ${dropped.join('; ')}`,
+            detail: `${method} ${url} — the server answered OK and returned a different value than it was asked to set, so the write half-applied; the UI has no way to know and will show the value the user typed`,
+        });
+    }
+    return found;
+}

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

@@ -16,8 +16,15 @@ export declare const OBSERVE_FILTER_BUCKETS: Record<string, readonly string[]>;
  * nothing rather than throwing — a typo narrows the result, it never crashes the observe.
  */
 export declare function eventMatchesFilters(e: ReticleEvent, filters: readonly string[]): boolean;
-/** Match a net.request event against optional method/url/status filters (reticle_network). */
-export declare function matchNet(e: ReticleEvent, method: string | undefined, urlContains: string | undefined, status: number | undefined): boolean;
+/**
+ * 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 declare function matchNet(e: ReticleEvent, method: string | undefined, urlContains: string | undefined, status: number | undefined, ok?: boolean): boolean;
 /**
  * Reconcile network events into completed calls + still-in-flight calls. A NET_PENDING whose
  * `id` never gets a matching NET_REQUEST is an unresolved/hung request — the case
@@ -41,6 +48,14 @@ interface NetCallView {
     ms?: number;
     /** Authoritative response headers merged from the driven (CDP) path — present only when driven. */
     headers?: Record<string, string>;
+    /**
+     * A fire-and-forget desktop IPC send (`ipcRenderer.send`): dispatched, outcome unknowable.
+     *
+     * Carried into the projection on purpose. Such a record has no `status` and no `ok`, and without
+     * this flag a reader has no way to tell "the outcome is unknown" from "the fields were dropped" —
+     * which is the reading that turns an unverifiable call into an assumed success.
+     */
+    oneWay?: boolean;
 }
 export declare function projectNetCall(e: ReticleEvent): NetCallView;
 /**
@@ -96,4 +111,3 @@ interface ConsoleEmptyHint {
 }
 export declare function consoleEmptyHint(allConsole: ReticleEvent[]): ConsoleEmptyHint;
 export {};
-//# sourceMappingURL=event-filters.d.ts.map