@reticlehq/server 2.13.1 → 2.14.0

package/dist/daemon/dev-servers.d.ts

@@ -1,4 +1,4 @@
-import { type DevServerEntry } from '@reticlehq/core';
+import { type DevServerEntry } from '@reticlehq/core/artifacts';
 /** Injected so the reading is unit-testable without a real home or real processes. */
 export interface DevServerIo {
     readdir: (dir: string) => string[];

package/dist/daemon/dev-servers.js

@@ -18,7 +18,7 @@
  */
 import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { DevServerEntrySchema, devServerRegistryPort, liveDevServers, } from '@reticlehq/core';
+import { DevServerEntrySchema, devServerRegistryPort, liveDevServers, } from '@reticlehq/core/artifacts';
 /** process.kill(pid, 0) throws iff the process is gone — the same probe the daemon registry uses. */
 function isAliveNow(pid) {
     try {

package/dist/daemon/loopback-alias.d.ts

@@ -18,7 +18,7 @@
  */
 /** IPv6 loopback. The other half of what `localhost` can mean. */
 export declare const IPV6_LOOPBACK = "::1";
-export interface LoopbackAlias {
+interface LoopbackAlias {
     /** False when the alias could not be bound — the daemon still serves IPv4 as before. */
     opened: boolean;
     close: () => Promise<void>;
@@ -30,3 +30,4 @@ export interface LoopbackAlias {
  * trust holds — the alias does not widen who may connect, only which address they may name.
  */
 export declare function openLoopbackAlias(port: number): Promise<LoopbackAlias>;
+export {};

package/dist/daemon/startup-failure.d.ts

@@ -0,0 +1,11 @@
+/** The structured log event emitted when the daemon child cannot start. */
+export declare const DAEMON_START_FAILED_EVENT = "reticle_daemon_start_failed";
+/**
+ * Return the most recent startup cause written by this launch attempt.
+ *
+ * Daemon logs are append-only across launches, so an event name alone is not enough: surfacing an
+ * older failure would confidently diagnose the wrong attempt. The parent supplies the timestamp it
+ * captured immediately before spawning and this reader ignores every earlier record. Malformed or
+ * unavailable logs are best-effort misses; the caller still has its generic fallback diagnosis.
+ */
+export declare function readDaemonStartupCause(path: string, sinceMs: number): string | undefined;

package/dist/daemon/startup-failure.js

@@ -0,0 +1,46 @@
+import { readFileSync } from 'node:fs';
+/** The structured log event emitted when the daemon child cannot start. */
+export const DAEMON_START_FAILED_EVENT = 'reticle_daemon_start_failed';
+/**
+ * Return the most recent startup cause written by this launch attempt.
+ *
+ * Daemon logs are append-only across launches, so an event name alone is not enough: surfacing an
+ * older failure would confidently diagnose the wrong attempt. The parent supplies the timestamp it
+ * captured immediately before spawning and this reader ignores every earlier record. Malformed or
+ * unavailable logs are best-effort misses; the caller still has its generic fallback diagnosis.
+ */
+export function readDaemonStartupCause(path, sinceMs) {
+    let contents;
+    try {
+        contents = readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const lines = contents.split('\n');
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const line = lines[index]?.trim();
+        if (undefined === line || 0 === line.length)
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof record !== 'object' || null === record)
+            continue;
+        const candidate = record;
+        if (candidate.event !== DAEMON_START_FAILED_EVENT)
+            continue;
+        if (typeof candidate.t !== 'string' || typeof candidate.error !== 'string')
+            continue;
+        const recordedAt = Date.parse(candidate.t);
+        const error = candidate.error.trim();
+        if (!Number.isFinite(recordedAt) || recordedAt < sinceMs || 0 === error.length)
+            continue;
+        return error;
+    }
+    return undefined;
+}

package/dist/events/contradictions.d.ts

@@ -156,21 +156,15 @@ export interface ContradictionOptions {
      * one: a caller that cannot say which page is under test gets the behaviour it had before this.
      */
     appOrigin?: string | undefined;
+    /**
+     * The traffic the assertion actually named — `urlContains` from each net clause, `''` for a clause
+     * that named the whole channel.
+     *
+     * Used only by `duplicate-request`, to tell "the write you asked about fired twice" from "some
+     * other endpoint is busy". Undefined disables the split and every duplicate is reported as it was
+     * before, which is what a caller with no predicate (a bare `observe`) should get: with nothing
+     * declared, nothing is unrelated.
+     */
+    namedNetUrls?: readonly string[] | undefined;
 }
-/**
- * Cross-channel contradictions in this window, with the edit-epoch caveat attached when it applies.
- *
- * Cross-epoch evidence is LABELLED rather than excluded, which is the opposite of what the document
- * scoping does, and the difference is the point. A navigation is total — it throws away the page,
- * the refs, the in-flight requests and the state — so nothing recorded before it is still about the
- * world, and dropping it is the only honest option. A hot update is not: most modules, most of the
- * DOM, the whole network log and every console line survive one, so most of what was observed a
- * second before an edit is still true a second after. Excluding it would empty windows that hold
- * real findings, and an emptied window reads as "nothing happened" — which is the more expensive of
- * the two wrong answers and the one this whole family of checks exists to prevent.
- *
- * So the findings stand and the caveat is said out loud, and only when it is unambiguous: EVERY
- * observation in the window predates the edit. One post-edit observation and the agent is already
- * looking at the code it wrote, so the label would be noise.
- */
 export declare function findContradictions(allEvents: readonly ReticleEvent[], options?: ContradictionOptions): Contradiction[];

package/dist/events/contradictions.js

@@ -21,6 +21,32 @@ function netCall(e) {
             : true === e.data['ok'] || (e.data['ok'] === undefined && (status ?? 0) < 400),
     };
 }
+/**
+ * The failed calls that a LATER successful call to the same endpoint replaced.
+ *
+ * Identity, not index: each `netCall` is a fresh object held by `settled`, and `settled` is built
+ * from events in sequence order, so "later" is simply "further along the array". Compared on
+ * `matchUrl` so a cache-buster or a changing query token cannot make a retry look like a different
+ * call — the same normalisation every other url comparison here uses.
+ */
+function recoveredByRetry(settled) {
+    const out = new Set();
+    for (let i = 0; i < settled.length; i += 1) {
+        const call = settled[i];
+        if (call === undefined || false !== call.ok)
+            continue;
+        for (let j = i + 1; j < settled.length; j += 1) {
+            const later = settled[j];
+            if (later === undefined)
+                continue;
+            if (true === later.ok && later.method === call.method && later.matchUrl === call.matchUrl) {
+                out.add(call);
+                break;
+            }
+        }
+    }
+    return out;
+}
 /**
  * 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
@@ -221,6 +247,42 @@ function splitForeignTraffic(events, appOrigin) {
  * observation in the window predates the edit. One post-edit observation and the agent is already
  * looking at the code it wrote, so the label would be noise.
  */
+/**
+ * Below this, repeated writes are a BURST, whatever their spacing.
+ *
+ * A double submit is two clicks, or one click and a re-render: milliseconds apart. Nothing a human
+ * or a StrictMode remount does lands on a quarter-second grid, so this is the floor under which
+ * regularity means nothing.
+ */
+const POLL_MIN_INTERVAL_MS = 250;
+/**
+ * How far a gap may sit from the median and still count as the same cadence.
+ *
+ * Loose on purpose: a real poll drifts under load, and a `setInterval` competing with a busy main
+ * thread is not metronomic. Tight enough that a burst followed by a late retry — the shape a double
+ * submit plus a user's second attempt makes — is not read as a rhythm.
+ */
+const POLL_JITTER_RATIO = 0.4;
+/**
+ * Is this the same write on a steady interval, rather than the same write twice?
+ *
+ * THREE samples minimum, and that is the load-bearing part: two writes give one gap, and a single
+ * gap cannot distinguish a cadence from a coincidence. Two writes stay a duplicate however far
+ * apart they are, which is the classic double submit and every case this rule was written for.
+ */
+function isSteadyCadence(times) {
+    if (times.length < 3)
+        return false;
+    const ordered = [...times].sort((a, b) => a - b);
+    const gaps = [];
+    for (let i = 1; i < ordered.length; i += 1)
+        gaps.push((ordered[i] ?? 0) - (ordered[i - 1] ?? 0));
+    const sorted = [...gaps].sort((a, b) => a - b);
+    const median = sorted[Math.floor(sorted.length / 2)] ?? 0;
+    if (median < POLL_MIN_INTERVAL_MS)
+        return false;
+    return gaps.every((gap) => Math.abs(gap - median) <= median * POLL_JITTER_RATIO);
+}
 export function findContradictions(allEvents, options = {}) {
     const found = findWindowContradictions(allEvents, options);
     const predates = allEvents.length > 0 &&
@@ -303,7 +365,20 @@ function findWindowContradictions(allEvents, options) {
             },
         ];
     }
-    const failed = settled.filter((c) => false === c.ok);
+    // A failure the app RECOVERED from is not evidence against anything.
+    //
+    // Reported from the field on an app whose api-client documents the pattern every token-refreshing
+    // app has: a 401 re-hydrates the session and retries once. One extraction produced a 401 and then
+    // a 200 to the same endpoint, with exactly one extraction in state, and Reticle called it two
+    // separate contradictions. Both were false, both cost calls to disprove, and a rule that
+    // manufactures reds costs more trust than a missed bug does.
+    //
+    // Structural, not a timing heuristic: what makes it a retry is that a LATER call to the same
+    // method and url SUCCEEDED. The write landed, so the UI was entitled to move and a success signal
+    // was entitled to fire. Filtered at the definition rather than at the two reading sites, because
+    // both rules make the same claim about the same evidence and a fix in one is a fix in half.
+    const recovered = recoveredByRetry(settled);
+    const failed = settled.filter((c) => false === c.ok && !recovered.has(c));
     // The failures NOBODY declared — see ContradictionOptions.expectedFailures. Only the heuristic
     // "the UI moved while a request failed" rule reads this; the sharp rules still read `failed`.
     const unexpected = failed.filter((c) => !matchesDeclaredFailure(c, options.expectedFailures ?? []));
@@ -352,12 +427,33 @@ function findWindowContradictions(allEvents, options) {
         e.type === EventType.DOM_TEXT);
     const fetched = events.some((e) => e.type === EventType.NET_REQUEST || e.type === EventType.NET_PENDING);
     if (routed && !hashAnchorOnly && !rendered && !fetched && true !== options.renderProved) {
-        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',
-        });
+        // A console error in the SAME window turns "nothing rendered" from an absence into a positive
+        // claim: the destination did not merely fail to produce content, it crashed while trying to.
+        // Reported once as `unknown` when this held — a React hooks error and an empty destination were
+        // both in hand, and the honest, definitive answer was available and not given (#897).
+        const consoleErrors = events
+            .filter((e) => e.type === EventType.CONSOLE_ERROR)
+            .map((e) => asString(e.data['message']))
+            .filter((m) => undefined !== m && m.length > 0);
+        if (consoleErrors.length > 0) {
+            found.push({
+                kind: ContradictionKind.ROUTE_RENDERED_NOTHING_CRASHED,
+                claim: 'the app navigated to a new route',
+                counter: `nothing was rendered for it, and the console shows why: ${consoleErrors[0] ?? ''}`,
+                detail: `the URL moved but the destination produced no content, and the same window logged ` +
+                    `${String(consoleErrors.length)} console error(s) — the first: "${consoleErrors[0] ?? ''}". ` +
+                    'The destination crashed rather than merely rendering nothing; read the error for the ' +
+                    'component and line at fault.',
+            });
+        }
+        else {
+            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
@@ -524,7 +620,7 @@ function findWindowContradictions(allEvents, options) {
          * distinguishes them.
          */
         const navigatedAt = events.find((e) => EventType.ROUTE_CHANGE === e.type && e.t >= actionSince)?.t;
-        const writeCounts = new Map();
+        const writeTimes = new Map();
         for (const event of events) {
             if (event.type !== EventType.NET_REQUEST || event.t < actionSince)
                 continue;
@@ -536,18 +632,54 @@ function findWindowContradictions(allEvents, options) {
             const label = `${call.method} ${call.url}`;
             const body = asString(event.data['requestBody']);
             const key = body === undefined || 0 === body.length ? label : `${label} ${body}`;
-            const entry = writeCounts.get(key) ?? { label, count: 0 };
-            entry.count += 1;
-            writeCounts.set(key, entry);
+            const entry = writeTimes.get(key) ?? { label, times: [], landed: 0 };
+            entry.times.push(event.t);
+            // Counted separately from the occurrences, because the claim is about what APPLIED.
+            if (false !== call.ok)
+                entry.landed += 1;
+            writeTimes.set(key, entry);
         }
-        for (const [, { label, count }] of writeCounts) {
-            if (count < 2)
+        /**
+         * Did the assertion name this endpoint?
+         *
+         * `undefined` means the caller declared nothing (a bare `observe`), and with nothing declared
+         * nothing is unrelated — every duplicate keeps the behaviour it had. An empty-string entry is a
+         * net clause with no `urlContains`, which named the whole channel and therefore matches
+         * everything.
+         */
+        const named = options.namedNetUrls;
+        const wasNamed = (label) => named === undefined || named.some((u) => label.includes(u));
+        for (const [, { label, times, landed }] of writeTimes) {
+            if (times.length < 2)
+                continue;
+            // A DOUBLE SUBMIT is a write that landed twice. Two attempts of which one failed is a RETRY,
+            // and the field case is the commonest retry there is: a 401 that refreshed a token and went
+            // again, one row created, reported here as `duplicate-request ×2`. Two attempts that both
+            // failed are not a double submit either — nothing applied even once, so the claim "one user
+            // action was performed" is not contradicted by them. A call with no verdict at all still
+            // counts, because absence of a status is not evidence the write was rejected.
+            if (landed < 2)
+                continue;
+            // A steady cadence is a POLL, and a poll is not a double submit. An app that polls could not
+            // produce a verdict at all: a camera scan loop POSTing until it acquires a lock had every
+            // assertion that had already seen its consequence come back `unknown` behind writes that
+            // were the app working correctly (#673).
+            if (isSteadyCadence(times))
                 continue;
+            // A burst the assertion never mentioned is still worth telling the caller about -- a retry
+            // loop or a bursty beacon is a real finding -- but it is not evidence about the consequence
+            // they declared, so it is reported and decides nothing. The named case keeps its downgrade:
+            // "the write you asked about fired twice" is exactly what this rule is for.
+            const related = wasNamed(label);
             found.push({
-                kind: ContradictionKind.DUPLICATE_REQUEST,
-                claim: 'one user action was performed',
-                counter: `the same write fired ${String(count)} times`,
-                detail: `${label} ×${String(count)}`,
+                kind: related
+                    ? ContradictionKind.DUPLICATE_REQUEST
+                    : ContradictionKind.DUPLICATE_REQUEST_UNRELATED,
+                claim: related
+                    ? 'one user action was performed'
+                    : 'the assertion did not name this endpoint',
+                counter: `the same write fired ${String(times.length)} times`,
+                detail: `${label} ×${String(times.length)}`,
             });
         }
     }

package/dist/events/declared.d.ts

@@ -24,11 +24,22 @@ export interface DeclaredNetFailure {
     urlContains?: string;
     status?: number;
 }
-export interface DeclaredExpectations {
+interface DeclaredExpectations {
     /** Requests the caller declared would FAIL, so failing is the expected outcome, not a disagreement. */
     netFailures: readonly DeclaredNetFailure[];
     /** The caller required something to be ON SCREEN — an element or text, present rather than absent. */
     rendersContent: boolean;
+    /**
+     * The `urlContains` of every net clause the predicate carries, failure or not.
+     *
+     * Distinct from `netFailures`, which is about EXPECTED failures. This answers a different
+     * question: which traffic did the caller actually mention? A rule that reports on writes the
+     * assertion never named is reporting on something else, and must not decide this verdict (#673).
+     *
+     * A net clause with no `urlContains` names ALL traffic — it asked about the whole channel — which
+     * is why an empty-string entry is meaningful and is preserved rather than skipped.
+     */
+    netUrls: readonly string[];
 }
 export declare function declaredExpectations(predicate: Predicate | undefined): DeclaredExpectations;
 /**
@@ -60,3 +71,4 @@ export declare function matchesDeclaredFailure(call: {
     matchUrl?: string;
     status: number | undefined;
 }, declared: readonly DeclaredNetFailure[]): boolean;
+export {};

package/dist/events/declared.js

@@ -17,11 +17,57 @@
  * opposite of a consequence — honouring either would suppress a real finding on the strength of
  * something that never happened. Pure: a predicate in, a description out.
  */
-import { PredicateKind } from '@reticlehq/core';
+import { PredicateKind, QueryBy } from '@reticlehq/core';
 /** Below this, a status is a success or a redirect: not a declared failure. */
 const FAILURE_STATUS_MIN = 400;
+/** Statuses that mean the caller was refused — the proof of an auth/authz denial, not a fault. */
+const AUTH_DENIAL_STATUSES = [401, 403];
+/** ARIA roles that ARE the error UI — waiting for an alert is how the first report asserted a 401. */
+const DENIAL_ROLES = new Set(['alert', 'alertdialog']);
+/**
+ * Phrases that name a denial rather than a success. Conservative and multi-word where a short
+ * token would match a greeting ("invalid date" is not an auth failure).
+ */
+const DENIAL_TEXT_MARKERS = [
+    'access denied',
+    'unauthorized',
+    'forbidden',
+    'invalid key',
+    'invalid credentials',
+    'incorrect email',
+    'incorrect password',
+    'not authorized',
+    'permission denied',
+    'unauthenticated',
+    'not allowed',
+];
+function isDenialPhrase(text) {
+    const lower = text.toLowerCase();
+    return DENIAL_TEXT_MARKERS.some((marker) => lower.includes(marker));
+}
+function isDenialRole(role) {
+    return DENIAL_ROLES.has(role.toLowerCase());
+}
+function isDenialQuery(query) {
+    if (undefined !== query.role && isDenialRole(query.role))
+        return true;
+    if (QueryBy.ROLE === query.by && undefined !== query.value && isDenialRole(query.value)) {
+        return true;
+    }
+    for (const field of [query.name, query.text, query.value, query.label]) {
+        if ('string' === typeof field && isDenialPhrase(field))
+            return true;
+    }
+    return false;
+}
+function pushAuthDenialStatuses(into) {
+    for (const status of AUTH_DENIAL_STATUSES) {
+        into.push({ status });
+    }
+}
 export function declaredExpectations(predicate) {
     const netFailures = [];
+    const netUrls = [];
     let rendersContent = false;
     const walk = (p) => {
         switch (p.kind) {
@@ -30,6 +76,7 @@ export function declaredExpectations(predicate) {
                     walk(child);
                 return;
             case PredicateKind.NET: {
+                netUrls.push(p.urlContains ?? '');
                 const declaredFailure = false === p.ok || (p.status !== undefined && p.status >= FAILURE_STATUS_MIN);
                 if (!declaredFailure)
                     return;
@@ -41,9 +88,18 @@ export function declaredExpectations(predicate) {
                 return;
             }
             case PredicateKind.ELEMENT:
+                if (true !== p.absent) {
+                    rendersContent = true;
+                    if (isDenialQuery(p.query))
+                        pushAuthDenialStatuses(netFailures);
+                }
+                return;
             case PredicateKind.TEXT:
-                if (true !== p.absent)
+                if (true !== p.absent) {
                     rendersContent = true;
+                    if (isDenialPhrase(p.contains))
+                        pushAuthDenialStatuses(netFailures);
+                }
                 return;
             default:
                 return;
@@ -51,7 +107,7 @@ export function declaredExpectations(predicate) {
     };
     if (predicate !== undefined)
         walk(predicate);
-    return { netFailures, rendersContent };
+    return { netFailures, rendersContent, netUrls };
 }
 /**
  * Did the caller name a consequence that does not depend on the response body?

package/dist/events/echo-mismatch.js

@@ -23,6 +23,9 @@ import { ContradictionKind, EventType, MUTATING_METHODS } from '@reticlehq/core'
  *    as a half-applied write. The gate was on the RESPONSE being a success and never on the REQUEST
  *    being a write, so every successful call carrying a body read as a save — and the same key name
  *    legitimately means different things on the two sides of a request/response pair;
+ *  - identity keys (`id`, `*_id`) and create sentinels (`0`, `""`, `null`) are not compared. A
+ *    create that sends `sub_category_id: 0` and gets back `19314` assigned the row; two id spaces
+ *    that share a field name were never expected to match. Both used to fire on every healthy POST;
  *  - 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
@@ -71,6 +74,23 @@ function normalize(value) {
         return String(value);
     return undefined;
 }
+/**
+ * Values that mean "server, you decide", not a field the caller asked to persist. A create that
+ * sends `0` for the new row's id, or an empty string the backend fills in, is the usual REST shape
+ * — not a dropped write.
+ */
+function isSentinelValue(value) {
+    return 0 === value || '' === value || null === value;
+}
+/**
+ * Keys that name an identity, not a persisted attribute. The server assigns these (create returns a
+ * new id; a public id and an internal row id share a field name). Comparing them as echoes is how
+ * this kind fired on every healthy POST-create and poisoned later asserts in the same window.
+ */
+function isIdentityKey(key) {
+    const lower = key.toLowerCase();
+    return 'id' === lower || lower.endsWith('_id');
+}
 /**
  * Every scalar value the response carries for each key, at any depth.
  *
@@ -78,20 +98,22 @@ function normalize(value) {
  * `{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) {
+function scalarsByKey(body, into = new Map(), depth = 0, omitSentinels = false) {
     if (depth > 6 || into.size > MAX_ECHO_KEYS)
         return into;
     if (Array.isArray(body)) {
         for (const item of body)
-            scalarsByKey(item, into, depth + 1);
+            scalarsByKey(item, into, depth + 1, omitSentinels);
         return into;
     }
     if (!isRecord(body))
         return into;
     for (const [key, value] of Object.entries(body)) {
+        if (omitSentinels && isSentinelValue(value))
+            continue;
         const scalar = normalize(value);
         if (scalar === undefined) {
-            scalarsByKey(value, into, depth + 1);
+            scalarsByKey(value, into, depth + 1, omitSentinels);
             continue;
         }
         const seen = into.get(key) ?? new Set();
@@ -117,6 +139,46 @@ const EchoDiscriminator = {
  * A response carrying this many times more scalar keys than the request, overlapping on fewer than
  * `MIN_SHARED_KEYS`, is a snapshot that happened to reuse a name — not an echo of the write.
  */
+/**
+ * The two halves of an ADDRESSED write: a key that NAMES the field to set, and a generic container
+ * holding the value to set it to — `{"slot":"_dim","value":"3D"}`, `{"field":"locale","value":"fr"}`.
+ *
+ * A container key cannot be compared across documents by name. `value` in the request means "the
+ * value of the field named by `slot`"; `value` in the response means "the value of whichever field
+ * this node belongs to", and a document holding many addressed fields holds many `value` nodes. The
+ * flat by-key comparison below therefore measures the request's value against an unrelated sibling
+ * field's value, which is not evidence about the target field at all.
+ *
+ * Measured in the field, and it produced a FALSE RED on a passing assertion: the request asked
+ * `{"slot":"_dim","value":"3D"}`; the server applied it (`brief.dim: "3D"`, and the interview
+ * advanced from `{kind:"question"}` to `{kind:"geometry", payload:{dim:"3D"}}`); and this kind
+ * reported "asked 3d, got cfd", where `cfd` is `brief.slots._family.value` — a different slot,
+ * set earlier in the same interview. The next call on the same endpoint DID mirror into
+ * `slots.<slot>.value` and passed clean, so the kind misfires exactly when a server persists an
+ * addressed field somewhere other than a mirror named after it. That is a normal API shape.
+ *
+ * Cost of getting this wrong: a manufactured red is worse than a missed one here. Reticle's whole
+ * proposition is that an agent must not talk itself past a red; a heuristic that invents them
+ * teaches, inside a single session, that a `contradicted` verdict may be noise worth arguing with.
+ *
+ * The addressing key itself is still compared. If the server echoes a DIFFERENT `slot` than the one
+ * requested, that is a genuine dropped write and this file should say so.
+ */
+const ADDRESSING_KEYS = new Set(['slot', 'field', 'key', 'path', 'property']);
+const CONTAINER_KEYS = new Set(['value', 'val', 'newvalue']);
+/** True when the request says "set the field named X" rather than carrying the fields themselves. */
+function isAddressedWrite(asked) {
+    let addressed = false;
+    let container = false;
+    for (const key of asked.keys()) {
+        const lower = key.toLowerCase();
+        if (ADDRESSING_KEYS.has(lower))
+            addressed = true;
+        if (CONTAINER_KEYS.has(lower))
+            container = true;
+    }
+    return addressed && container;
+}
 const SNAPSHOT_KEY_RATIO = 3;
 const MIN_SHARED_KEYS = 2;
 /**
@@ -194,16 +256,23 @@ export function findEchoMismatches(events, actionSince) {
         if (request === undefined || response === undefined)
             continue;
         const echoed = scalarsByKey(response);
-        const asked = scalarsByKey(request);
+        const asked = scalarsByKey(request, new Map(), 0, true);
         if (!responseRestatesRequest(asked, echoed))
             continue;
+        // See ADDRESSING_KEYS: on an addressed write the container key names nothing on its own, so
+        // comparing it by name across the two documents compares two different fields.
+        const addressed = isAddressedWrite(asked);
         const dropped = [];
         for (const [key, wanted] of asked) {
+            if (addressed && CONTAINER_KEYS.has(key.toLowerCase()))
+                continue;
             // 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;
+            if (isIdentityKey(key))
+                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.
@@ -222,8 +291,8 @@ export function findEchoMismatches(events, actionSince) {
         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${attribution}`,
+            counter: `its own echo shows ${String(dropped.length)} field(s) that differ from the request — ${dropped.join('; ')}`,
+            detail: `${method} ${url} — the server answered OK and returned a different value than it was asked to set${attribution}`,
         });
     }
     return found;

package/dist/events/lineage.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Where a runtime value came from: state path ← the signal that preceded it ← the request behind it.
+ *
+ * The prior art this issue names (`firatorhan/sentinel`'s `get_lineage`) builds the same chain by
+ * picking "the most recent action whose payload contains this value", then "an API call whose type
+ * matches". That is CORRELATION, and for a devtool a human reads it is the right trade — the reader
+ * discounts it on sight.
+ *
+ * Reticle's output is read by an agent that acts on it, so the same chain presented as fact is the
+ * false-green shape this project exists to refuse. The join here is deliberately no cleverer than
+ * theirs; what is different is that every link carries how much it is worth:
+ *
+ * - a state path that changed is OBSERVED — we have the event;
+ * - "this signal caused it" is INFERRED, and the wording says so;
+ * - several candidates are NAMED rather than narrowed to the most recent, because choosing is the
+ *   one thing a correlation cannot justify;
+ * - no candidate says the value was not seen to pass through one, and reaches for nothing.
+ *
+ * Read-only. Produces no verdict, is not reachable from an assert path, and changes nothing.
+ */
+import { type ReticleEvent } from '@reticlehq/core';
+/** What the caller is asking about. `value` narrows a path that changed more than once. */
+export interface LineageQuery {
+    path: string;
+    value?: string;
+}
+/** One line of the chain, with the confidence that produced it. */
+export interface LineageLink {
+    /** Which stream this came from. */
+    kind: 'state' | 'signal' | 'net';
+    /** The rendered line, already carrying its own hedge. */
+    text: string;
+    /** True only when this is an event we hold. A join is never observed. */
+    observed: boolean;
+    /** Every candidate, when more than one could explain the link. Present only when ambiguous. */
+    candidates?: string[];
+}
+export interface Lineage {
+    /** False when the path was never seen to change — a different answer from an empty chain. */
+    found: boolean;
+    chain: LineageLink[];
+    /** Why the chain stops where it does, when it stops early. */
+    note?: string;
+}
+/**
+ * The chain, most recent change first.
+ *
+ * Stops at the first link with nothing to point at, and says why. Walking past a gap would mean
+ * joining across a hole in the evidence, which is exactly the step that turns a correlation into a
+ * claim.
+ */
+export declare function traceLineage(events: readonly ReticleEvent[], query: LineageQuery): Lineage;