@reticlehq/server 2.7.0 → 2.9.0

package/dist/events/contradictions.js

@@ -4,6 +4,7 @@ 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';
+import { matchesDeclaredFailure } from './declared.js';
 function netCall(e) {
     const status = asNumber(e.data['status']);
     return {
@@ -171,7 +172,7 @@ export function findContradictions(allEvents, options = {}) {
     // 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));
+    found.push(...findEchoMismatches(events, options.actionSince));
     // ── A money value written back at the wrong SCALE ───────────────────────────────────────────
     found.push(...findUnitMismatches(events, options.prior ?? []));
     // ── The action landed on something that does not react ──────────────────────────────────────
@@ -192,6 +193,9 @@ export function findContradictions(allEvents, options = {}) {
         ];
     }
     const failed = settled.filter((c) => false === c.ok);
+    // 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 ?? []));
     const advanced = uiAdvanced(events);
     const signals = events
         .filter((e) => e.type === EventType.SIGNAL)
@@ -215,7 +219,7 @@ export function findContradictions(allEvents, options = {}) {
         e.type === EventType.DOM_REMOVED ||
         e.type === EventType.DOM_TEXT);
     const fetched = events.some((e) => e.type === EventType.NET_REQUEST || e.type === EventType.NET_PENDING);
-    if (routed && !rendered && !fetched) {
+    if (routed && !rendered && !fetched && true !== options.renderProved) {
         found.push({
             kind: ContradictionKind.ROUTE_RENDERED_NOTHING,
             claim: 'the app navigated to a new route',
@@ -259,12 +263,12 @@ export function findContradictions(allEvents, options = {}) {
             detail: failed.map(describe).join('; '),
         });
     }
-    else if (failed.length > 0 && advanced && !misattributed && !failureAcknowledged(events)) {
+    else if (unexpected.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('; '),
+            counter: `${String(unexpected.length)} request(s) in the same window failed`,
+            detail: unexpected.map(describe).join('; '),
         });
     }
     // ── A write succeeded and nothing on the client moved ───────────────────────────────────────
@@ -281,23 +285,32 @@ export function findContradictions(allEvents, options = {}) {
             });
         }
     }
-    // ── 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 same write fired more than once, inside ONE action's window ─────────────────────────
+    // Attribution is the whole rule here, not a refinement of it: counting `method + url` over whatever
+    // window the caller handed in turns two legitimate separate saves into a double submit. See
+    // ContradictionOptions.actionSince.
+    const actionSince = options.actionSince;
+    if (actionSince !== undefined) {
+        const writeCounts = new Map();
+        for (const event of events) {
+            if (event.type !== EventType.NET_REQUEST || event.t < actionSince)
+                continue;
+            const call = netCall(event);
+            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

package/dist/events/declared.d.ts

@@ -0,0 +1,45 @@
+/**
+ * What the caller DECLARED before acting — the oracle, read back.
+ *
+ * `act_and_wait` asks the agent to name the expected consequence BEFORE the action, and that
+ * declaration was then thrown away: everything downstream judged the window as if nobody had said
+ * what they were expecting. Two measured consequences, one bug:
+ *
+ *  - An error path can be declared exactly — `{ net, POST, /api/login, status: 500 }` — and the
+ *    contradiction hunter still reported `ui-advanced-request-failed`, because a failed request plus
+ *    a moved DOM is all it can see. The failure was EXPECTED and said so in the predicate, so a
+ *    verdict of "channels disagree" is a statement about a disagreement nobody had.
+ *  - A destination whose content was asserted and FOUND was still reported as
+ *    `route-rendered-nothing`, a clause the element evidence beside it disproves.
+ *
+ * Deliberately conservative about what counts as declared. Only what the caller REQUIRED is read:
+ * the top level and `allOf` chains. An `anyOf` branch may never have held, and a `not` declares the
+ * 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 type { Predicate } from './predicate-eval.js';
+/** A failing call the caller named in advance — matched against the window's real calls. */
+export interface DeclaredNetFailure {
+    method?: string;
+    urlContains?: string;
+    status?: number;
+}
+export 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;
+}
+export declare function declaredExpectations(predicate: Predicate | undefined): DeclaredExpectations;
+/**
+ * Does a call the window recorded match a failure the caller declared?
+ *
+ * Every field the caller named must agree — a declaration about `POST /api/login → 500` says nothing
+ * about `POST /api/orders`, and treating it as a blanket amnesty for failed requests would remove
+ * the check rather than inform it. Fields the caller left out are not constraints.
+ */
+export declare function matchesDeclaredFailure(call: {
+    method: string;
+    url: string;
+    status: number | undefined;
+}, declared: readonly DeclaredNetFailure[]): boolean;

package/dist/events/declared.js

@@ -0,0 +1,73 @@
+/**
+ * What the caller DECLARED before acting — the oracle, read back.
+ *
+ * `act_and_wait` asks the agent to name the expected consequence BEFORE the action, and that
+ * declaration was then thrown away: everything downstream judged the window as if nobody had said
+ * what they were expecting. Two measured consequences, one bug:
+ *
+ *  - An error path can be declared exactly — `{ net, POST, /api/login, status: 500 }` — and the
+ *    contradiction hunter still reported `ui-advanced-request-failed`, because a failed request plus
+ *    a moved DOM is all it can see. The failure was EXPECTED and said so in the predicate, so a
+ *    verdict of "channels disagree" is a statement about a disagreement nobody had.
+ *  - A destination whose content was asserted and FOUND was still reported as
+ *    `route-rendered-nothing`, a clause the element evidence beside it disproves.
+ *
+ * Deliberately conservative about what counts as declared. Only what the caller REQUIRED is read:
+ * the top level and `allOf` chains. An `anyOf` branch may never have held, and a `not` declares the
+ * 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';
+/** Below this, a status is a success or a redirect: not a declared failure. */
+const FAILURE_STATUS_MIN = 400;
+export function declaredExpectations(predicate) {
+    const netFailures = [];
+    let rendersContent = false;
+    const walk = (p) => {
+        switch (p.kind) {
+            case PredicateKind.ALL_OF:
+                for (const child of p.predicates)
+                    walk(child);
+                return;
+            case PredicateKind.NET: {
+                const declaredFailure = false === p.ok || (p.status !== undefined && p.status >= FAILURE_STATUS_MIN);
+                if (!declaredFailure)
+                    return;
+                netFailures.push({
+                    ...(p.method === undefined ? {} : { method: p.method }),
+                    ...(p.urlContains === undefined ? {} : { urlContains: p.urlContains }),
+                    ...(p.status === undefined ? {} : { status: p.status }),
+                });
+                return;
+            }
+            case PredicateKind.ELEMENT:
+            case PredicateKind.TEXT:
+                if (true !== p.absent)
+                    rendersContent = true;
+                return;
+            default:
+                return;
+        }
+    };
+    if (predicate !== undefined)
+        walk(predicate);
+    return { netFailures, rendersContent };
+}
+/**
+ * Does a call the window recorded match a failure the caller declared?
+ *
+ * Every field the caller named must agree — a declaration about `POST /api/login → 500` says nothing
+ * about `POST /api/orders`, and treating it as a blanket amnesty for failed requests would remove
+ * the check rather than inform it. Fields the caller left out are not constraints.
+ */
+export function matchesDeclaredFailure(call, declared) {
+    return declared.some((d) => {
+        if (d.method !== undefined && d.method.toUpperCase() !== call.method.toUpperCase())
+            return false;
+        if (d.urlContains !== undefined && !call.url.includes(d.urlContains))
+            return false;
+        if (d.status !== undefined && d.status !== call.status)
+            return false;
+        return true;
+    });
+}

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

@@ -1,4 +1,10 @@
 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[];
+/**
+ * Contradictions for writes whose response echoes a different value than the request asked for.
+ *
+ * `actionSince` is the attribution floor `findContradictions` already keeps — the event time the
+ * action that opened this window was dispatched. A finding about a request that had already settled
+ * before the agent acted otherwise reads as a verdict on the change it just made.
+ */
+export declare function findEchoMismatches(events: readonly ReticleEvent[], actionSince?: number): Contradiction[];

package/dist/events/echo-mismatch.js

@@ -1,4 +1,4 @@
-import { ContradictionKind, EventType } from '@reticlehq/core';
+import { ContradictionKind, EventType, MUTATING_METHODS } from '@reticlehq/core';
 /**
  * A write that returned OK and quietly did not apply part of what it was asked to.
  *
@@ -18,6 +18,11 @@ import { ContradictionKind, EventType } from '@reticlehq/core';
  * 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 requests that are WRITES are considered. Reported from the field: a lookup that sends its
+ *    key in the body (`POST /get-branding` with `{workspace_id}`) and gets a record back was graded
+ *    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;
  *  - 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
@@ -89,12 +94,33 @@ function scalarsByKey(body, into = new Map(), depth = 0) {
 }
 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) {
+/**
+ * Contradictions for writes whose response echoes a different value than the request asked for.
+ *
+ * `actionSince` is the attribution floor `findContradictions` already keeps — the event time the
+ * action that opened this window was dispatched. A finding about a request that had already settled
+ * before the agent acted otherwise reads as a verdict on the change it just made.
+ */
+export function findEchoMismatches(events, actionSince) {
     const found = [];
     for (const event of events) {
         if (event.type !== EventType.NET_REQUEST)
             continue;
+        // `MUTATING_METHODS` is the one definition of "is this a write" in the codebase — the same list
+        // `contradictions.ts`'s `isMutating` reads. A read has no fields to half-apply.
+        //
+        // KNOWN LIMIT, stated because it is easy to read this fix as bigger than it is: POST is in that
+        // list, so a lookup that POSTs its key and gets a record back — the shape actually reported —
+        // still reaches the comparison below. Method is the only signal available here, and a read-shaped
+        // POST is genuinely indistinguishable from a write by method alone.
+        //
+        // The tempting next step is to skip a pair whose JSON types disagree (a string key sent, a number
+        // echoed). Deliberately not taken: that also silences `{"qty":"5"}` answered with `3`, which is a
+        // real dropped write. A false negative here is a missed bug in someone's app, and that is not a
+        // trade this file makes to quieten a false positive.
+        const method = 'string' === typeof event.data['method'] ? event.data['method'] : '';
+        if (!MUTATING_METHODS.includes(method.toUpperCase()))
+            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'];
@@ -126,12 +152,14 @@ export function findEchoMismatches(events) {
         if (0 === dropped.length)
             continue;
         const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
-        const method = 'string' === typeof event.data['method'] ? event.data['method'] : '';
+        const attribution = actionSince !== undefined && event.t < actionSince
+            ? ' — this request completed before the action being verified, so the finding is not about that change'
+            : '';
         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`,
+            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}`,
         });
     }
     return found;

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

@@ -57,7 +57,7 @@ interface NetCallView {
      */
     oneWay?: boolean;
 }
-export declare function projectNetCall(e: ReticleEvent): NetCallView;
+export declare function projectNetCall(e: ReticleEvent, includeBodies?: boolean): NetCallView;
 /**
  * Compact console-log summary for reticle_console output.
  *

package/dist/events/event-filters.js

@@ -86,7 +86,7 @@ export function reconcileNet(events) {
         .map((e) => ({ ...e, data: { ...e.data, status: 'pending', pending: true } }));
     return [...completed, ...unresolved].sort((a, b) => a.t - b.t);
 }
-export function projectNetCall(e) {
+export function projectNetCall(e, includeBodies = true) {
     const status = e.data['status'];
     const ms = asNumber(e.data['durationMs']);
     const statusText = asString(e.data['statusText']);
@@ -106,11 +106,14 @@ export function projectNetCall(e) {
         view.contentType = contentType;
     if (responseSize !== undefined)
         view.responseSize = responseSize;
-    if (requestBody !== undefined)
+    // Bodies dominate the payload of the most-called read tool, and are only occasionally the part
+    // anyone wanted — `bodies: false` on reticle_network drops them for a body-free listing (#401).
+    if (includeBodies && requestBody !== undefined)
         view.requestBody = requestBody;
-    if (responseBody !== undefined)
+    if (includeBodies && responseBody !== undefined)
         view.responseBody = responseBody;
-    if (true === e.data['requestBodyTruncated'] || true === e.data['responseBodyTruncated']) {
+    if (includeBodies &&
+        (true === e.data['requestBodyTruncated'] || true === e.data['responseBodyTruncated'])) {
         view.bodyTruncated = true;
     }
     if (ms !== undefined)

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

@@ -1,72 +1,6 @@
-import { ElementState, PredicateKind, type ElementQuery, type ReticleEvent } from '@reticlehq/core';
-import { z } from 'zod';
-export type Predicate = {
-    kind: typeof PredicateKind.ELEMENT;
-    query: ElementQuery;
-    state?: ElementState;
-    absent?: boolean;
-} | {
-    kind: typeof PredicateKind.TEXT;
-    contains: string;
-    visible?: boolean;
-    absent?: boolean;
-} | {
-    kind: typeof PredicateKind.NET;
-    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;
-} | {
-    kind: typeof PredicateKind.ROUTE;
-    pathname?: string;
-    contains?: string;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.CONSOLE;
-    level?: string;
-    absent?: boolean;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.ANIMATION;
-    name?: string;
-    target?: string;
-    completed?: boolean;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.SIGNAL;
-    name?: string;
-    dataMatches?: Record<string, unknown>;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.STATE;
-    store?: string;
-    path: string;
-    equals?: unknown;
-} | {
-    kind: typeof PredicateKind.SETTLED;
-    quietMs?: number;
-} | {
-    kind: typeof PredicateKind.ALL_OF;
-    predicates: Predicate[];
-} | {
-    kind: typeof PredicateKind.ANY_OF;
-    predicates: Predicate[];
-} | {
-    kind: typeof PredicateKind.NOT;
-    predicate: Predicate;
-};
-export declare const PredicateSchema: z.ZodType<Predicate>;
-/**
- * The fields a given predicate kind accepts, read off the schema itself.
- *
- * Derived rather than listed so the two can never disagree: a rejection message that names a stale
- * field set is worse than one that names none, because the agent trusts it and retries into the same
- * wall. Empty for a kind that is not in the union.
- */
-export declare function predicateFieldsFor(kind: string): readonly string[];
+import { PredicateKind, type ReticleEvent } from '@reticlehq/core';
+import type { Predicate } from './predicate-schema.js';
+export * from './predicate-schema.js';
 export interface EvalResult {
     pass: boolean;
     /**
@@ -85,6 +19,19 @@ export interface EvalResult {
      * not a defect in the user's app, and reporting it as one puts agent mistakes into the bug count.
      */
     inconclusive?: string;
+    /**
+     * No later event in this window can change this answer, so waiting out the rest of the budget
+     * buys nothing.
+     *
+     * Set ONLY where that is provable, which is rarer than it looks. "The toast never appeared" is not
+     * decided — it is only knowable when the budget ends, and ending early there would manufacture the
+     * false negative the budget exists to prevent. Exact cardinality IS decided once exceeded, because
+     * a window only accumulates matches and a count cannot come back down.
+     *
+     * A scheduling fact, never a verdict: `pass` already says what the answer is, and this only says
+     * that it is final.
+     */
+    decided?: boolean;
     evidence?: unknown;
     failureReason?: string;
     /**
@@ -113,6 +60,7 @@ export interface EvalResult {
     expected?: string;
     assertion?: string;
 }
+export declare function str(value: unknown): string | undefined;
 /**
  * Match one value against a pattern. Supports `*` (present), strict equality, and operators:
  * `{$gte,$lte,$gt,$lt}` (numbers), `{$contains}` (array membership or substring), `{$length}`.
@@ -121,9 +69,6 @@ export declare function matchValue(got: unknown, want: unknown): boolean;
 export declare function evalNet(events: ReticleEvent[], p: Extract<Predicate, {
     kind: typeof PredicateKind.NET;
 }>): EvalResult;
-export declare function evalRoute(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: typeof PredicateKind.ROUTE;
-}>): EvalResult;
 export declare function evalConsole(events: ReticleEvent[], p: Extract<Predicate, {
     kind: typeof PredicateKind.CONSOLE;
 }>): EvalResult;