@reticlehq/server 2.4.0 → 2.6.0

package/dist/events/contradictions.js

@@ -1,4 +1,4 @@
-import { ContradictionKind, EventType, MUTATING_METHODS } from '@reticlehq/core';
+import { ContradictionKind, EventType, MUTATING_METHODS, isDevToolingUrl, } from '@reticlehq/core';
 import { findStaleResponses } from './stale-response.js';
 import { findBodyFailures } from './body-failures.js';
 import { findEchoMismatches } from './echo-mismatch.js';
@@ -14,7 +14,7 @@ function netCall(e) {
         // 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),
+            : true === e.data['ok'] || (e.data['ok'] === undefined && (status ?? 0) < 400),
     };
 }
 /**
@@ -95,7 +95,7 @@ function failureAcknowledged(events) {
             return false;
         const path = asString(e.data['path']) ?? '';
         const value = e.data['value'];
-        return ACKNOWLEDGED.test(path) || (typeof value === 'string' && ACKNOWLEDGED.test(value));
+        return ACKNOWLEDGED.test(path) || ('string' === typeof value && ACKNOWLEDGED.test(value));
     });
 }
 function describe(call) {
@@ -125,13 +125,44 @@ const MUST_DO_SOMETHING = new Set(['click', 'dblclick', 'submit']);
  */
 function didNothing(events, requests, mutatedWithin) {
     if (mutatedWithin === undefined)
-        return events.length === 0;
+        return 0 === events.length;
     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 = {}) {
+/** Net-shaped events — the only ones that carry a URL a dev-tooling channel could occupy. */
+const NET_TYPES = new Set([
+    EventType.NET_PENDING,
+    EventType.NET_REQUEST,
+    EventType.NET_STREAM,
+]);
+/**
+ * Split the window into the app's traffic and the dev toolchain's own (see `DevToolingChannel`).
+ *
+ * NOTHING below may judge the toolchain. Reported from a real drive: a correct Next.js navigation
+ * graded `verified: "no"` because the dev overlay was resolving a source map for an unrelated React
+ * key warning, and that in-flight `POST /__nextjs_original-stack-frames` read as "the UI advanced
+ * over a request that never settled". Every app that logs one dev warning got a false negative on
+ * every action. The overlay's own 404s and duplicate fetches are the same story on other checks,
+ * which is why the split happens ONCE here rather than in the one check that reported it.
+ */
+function splitDevTooling(events) {
+    const ignored = [];
+    const app = events.filter((e) => {
+        if (!NET_TYPES.has(e.type))
+            return true;
+        const url = asString(e.data['url']);
+        if (!isDevToolingUrl(url))
+            return true;
+        if (url !== undefined && !ignored.includes(url))
+            ignored.push(url);
+        return false;
+    });
+    return { app, ignored };
+}
+export function findContradictions(allEvents, options = {}) {
     const found = [];
+    const { app: events, ignored: ignoredDevTooling } = splitDevTooling(allEvents);
     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.
@@ -160,7 +191,7 @@ export function findContradictions(events, options = {}) {
             },
         ];
     }
-    const failed = settled.filter((c) => c.ok === false);
+    const failed = settled.filter((c) => false === c.ok);
     const advanced = uiAdvanced(events);
     const signals = events
         .filter((e) => e.type === EventType.SIGNAL)
@@ -170,7 +201,19 @@ export function findContradictions(events, options = {}) {
     // 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);
+    // `dom.text` counts as rendered, and it has to: React reconciles a destination IN PLACE far more
+    // often than it adds nodes. Measured on three ordinary sidebar navigations of the bench app — every
+    // one emitted { dom.attr:2, dom.text:2, render.commit, state.change } and ZERO dom.added/removed,
+    // so all three were flagged as blank destinations, `verified` came back "no" on a correct green,
+    // and a bug_found was emitted for a navigation that worked.
+    //
+    // Deliberately NOT `dom.attr`: the nav link marks itself active whether or not the destination
+    // rendered, which is the true positive this rule exists for. Deliberately NOT `render.commit`
+    // either: React commits a render for a component that returns null, which is one of the very bugs
+    // named in `detail` below.
+    const rendered = events.some((e) => e.type === EventType.DOM_ADDED ||
+        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) {
         found.push({
@@ -187,7 +230,7 @@ export function findContradictions(events, options = {}) {
     // 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 serverFaults = settled.filter((c) => false === c.ok && c.status !== undefined && c.status >= SERVER_FAULT_MIN);
     const userBlame = [
         ...signals.filter((name) => BLAMES_USER.test(name)),
         ...events
@@ -228,7 +271,7 @@ export function findContradictions(events, options = {}) {
     // 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));
+        const ignoredWrites = settled.filter((c) => true === c.ok && isMutating(c));
         if (ignoredWrites.length > 0) {
             found.push({
                 kind: ContradictionKind.RESPONSE_IGNORED,
@@ -274,7 +317,14 @@ export function findContradictions(events, options = {}) {
                 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('; '),
+                // The exclusion is never silent: if the toolchain's own traffic was dropped from this count,
+                // the finding says which URLs, so an agent reading it can see what Reticle chose to ignore.
+                detail: [
+                    inFlight.map((p) => describe(p.call)).join('; '),
+                    ...(0 === ignoredDevTooling.length
+                        ? []
+                        : [`ignored as dev tooling: ${ignoredDevTooling.join(', ')}`]),
+                ].join(' — '),
             });
         }
     }

package/dist/events/echo-mismatch.js

@@ -31,7 +31,7 @@ import { ContradictionKind, EventType } from '@reticlehq/core';
 /** 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);
+    return 'object' === typeof value && value !== null && !Array.isArray(value);
 }
 /**
  * Any JSON value, not just an object. An HTTP write sends an object; an IPC call sends its ARGUMENT
@@ -39,7 +39,7 @@ function isRecord(value) {
  * 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)
+    if (typeof raw !== 'string' || 0 === raw.length)
         return undefined;
     try {
         return JSON.parse(raw);
@@ -50,11 +50,11 @@ function parse(raw) {
 }
 /** Comparable form of a scalar. Non-scalars return undefined and are never compared. */
 function normalize(value) {
-    if (typeof value === 'string')
+    if ('string' === typeof value)
         return value.trim().toLowerCase();
-    if (typeof value === 'number')
+    if ('number' === typeof value)
         return Number.isFinite(value) ? String(value) : undefined;
-    if (typeof value === 'boolean')
+    if ('boolean' === typeof value)
         return String(value);
     return undefined;
 }
@@ -98,7 +98,7 @@ export function findEchoMismatches(events) {
         // 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;
+        const httpOk = 'number' === typeof status && status >= OK_MIN && status < OK_MAX;
         if (!httpOk && event.data['ok'] !== true)
             continue;
         const request = parse(event.data['requestBody']);
@@ -117,16 +117,16 @@ export function findEchoMismatches(events) {
             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)
+            if (values === undefined || 0 === values.size)
                 continue;
             const [want] = [...wanted];
             if (want !== undefined && !values.has(want))
                 dropped.push(`${key}: asked ${want}, got ${[...values].join('/')}`);
         }
-        if (dropped.length === 0)
+        if (0 === dropped.length)
             continue;
-        const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
-        const method = typeof event.data['method'] === 'string' ? event.data['method'] : '';
+        const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
+        const method = 'string' === typeof event.data['method'] ? event.data['method'] : '';
         found.push({
             kind: ContradictionKind.WRITE_FIELD_IGNORED,
             claim: 'the write returned success and the page treated it as saved',

package/dist/events/event-filters.js

@@ -98,7 +98,7 @@ export function projectNetCall(e) {
         method: asString(e.data['method']) ?? '',
         url: asString(e.data['url']) ?? '',
     };
-    if (typeof status === 'number' || typeof status === 'string')
+    if ('number' === typeof status || 'string' === typeof status)
         view.status = status;
     if (statusText !== undefined)
         view.statusText = statusText;
@@ -110,15 +110,15 @@ export function projectNetCall(e) {
         view.requestBody = requestBody;
     if (responseBody !== undefined)
         view.responseBody = responseBody;
-    if (e.data['requestBodyTruncated'] === true || e.data['responseBodyTruncated'] === true) {
+    if (true === e.data['requestBodyTruncated'] || true === e.data['responseBodyTruncated']) {
         view.bodyTruncated = true;
     }
     if (ms !== undefined)
         view.ms = ms;
-    if (e.data['oneWay'] === true)
+    if (true === e.data['oneWay'])
         view.oneWay = true;
     const headers = e.data['headers'];
-    if (headers !== null && typeof headers === 'object') {
+    if (headers !== null && 'object' === typeof headers) {
         view.headers = headers;
     }
     return view;
@@ -146,7 +146,7 @@ export function projectConsoleLog(e) {
     const source = asString(e.data['source']);
     const line = e.data['line'];
     if (source !== undefined && source.length > 0) {
-        view.source = typeof line === 'number' ? `${source}:${String(line)}` : source;
+        view.source = 'number' === typeof line ? `${source}:${String(line)}` : source;
     }
     return view;
 }
@@ -165,7 +165,7 @@ export function matchConsole(e, level) {
         return false;
     if (level === undefined)
         return true;
-    return (e.type === `console.${level}` || (level === 'error' && e.type === EventType.ERROR_UNCAUGHT));
+    return (e.type === `console.${level}` || ('error' === level && e.type === EventType.ERROR_UNCAUGHT));
 }
 /** How many present calls/levels a zero-match hint samples before truncating. */
 const HINT_SAMPLE_MAX = 5;

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

@@ -15,7 +15,7 @@
  * before the cut and reports how many it had to drop, so a partial answer is delivered AS partial
  * rather than as a clean one.
  */
-export interface Salvaged {
+interface Salvaged {
     /** Parsed values — one whole body, or the records recovered from a truncated one. */
     values: unknown[];
     /** True when the payload was incomplete and only part of it could be read. */
@@ -30,3 +30,4 @@ export interface Salvaged {
  * costs nothing, because each record still carries its own id and its own fields.
  */
 export declare function salvageJson(raw: string): Salvaged;
+export {};

package/dist/events/json-salvage.js

@@ -38,22 +38,22 @@ function completeObjects(text) {
         if (inString) {
             if (escaped)
                 escaped = false;
-            else if (ch === '\\')
+            else if ('\\' === ch)
                 escaped = true;
-            else if (ch === '"')
+            else if ('"' === ch)
                 inString = false;
             continue;
         }
-        if (ch === '"') {
+        if ('"' === ch) {
             inString = true;
             continue;
         }
-        if (ch === '{') {
+        if ('{' === ch) {
             starts.push(i);
             depth += 1;
             continue;
         }
-        if (ch === '}') {
+        if ('}' === ch) {
             depth -= 1;
             // A negative depth means the cut removed an opening brace; nothing further is trustworthy.
             if (depth < 0)
@@ -63,7 +63,7 @@ function completeObjects(text) {
                 found.push({ depth: depth + 1, text: text.slice(start, i + 1) });
         }
     }
-    if (found.length === 0)
+    if (0 === found.length)
         return [];
     const shallowest = Math.min(...found.map((f) => f.depth));
     return found.filter((f) => f.depth === shallowest).map((f) => f.text);

package/dist/events/observed-in-window.d.ts

@@ -0,0 +1,12 @@
+/**
+ * What DID happen, when the thing you asserted did not.
+ *
+ * "signal 'x' never fired" and "no matching network call" are true and useless: a typo'd name and a
+ * genuinely broken app produce the same sentence, and the agent cannot tell them apart without a
+ * round trip it does not know to make. `{ kind:'state' }` already answers a bad path by naming the
+ * stores that exist; this gives `signal` and `net` the same courtesy.
+ *
+ * It also distinguishes the two failures that matter: NOTHING happened in the window (the action did
+ * not do what you thought) versus things happened but not that one (you named it wrong).
+ */
+export declare function describeObserved(noun: string, seen: readonly string[]): string;

package/dist/events/observed-in-window.js

@@ -0,0 +1,21 @@
+/**
+ * What DID happen, when the thing you asserted did not.
+ *
+ * "signal 'x' never fired" and "no matching network call" are true and useless: a typo'd name and a
+ * genuinely broken app produce the same sentence, and the agent cannot tell them apart without a
+ * round trip it does not know to make. `{ kind:'state' }` already answers a bad path by naming the
+ * stores that exist; this gives `signal` and `net` the same courtesy.
+ *
+ * It also distinguishes the two failures that matter: NOTHING happened in the window (the action did
+ * not do what you thought) versus things happened but not that one (you named it wrong).
+ */
+/** Enough to recognise the one you meant; not so many that a chatty window floods the message. */
+const MAX_LISTED = 8;
+export function describeObserved(noun, seen) {
+    const unique = [...new Set(seen.filter((s) => s.length > 0))];
+    if (0 === unique.length)
+        return `no ${noun} at all in this window`;
+    const shown = unique.slice(0, MAX_LISTED);
+    const rest = unique.length - shown.length;
+    return `${noun} seen in this window: ${shown.join(', ')}${rest > 0 ? `, and ${String(rest)} more` : ''}`;
+}

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

@@ -1,17 +1,17 @@
-import { ElementState, type ElementQuery, type ReticleEvent } from '@reticlehq/core';
+import { ElementState, PredicateKind, type ElementQuery, type ReticleEvent } from '@reticlehq/core';
 import { z } from 'zod';
 export type Predicate = {
-    kind: 'element';
+    kind: typeof PredicateKind.ELEMENT;
     query: ElementQuery;
     state?: ElementState;
     absent?: boolean;
 } | {
-    kind: 'text';
+    kind: typeof PredicateKind.TEXT;
     contains: string;
     visible?: boolean;
     absent?: boolean;
 } | {
-    kind: 'net';
+    kind: typeof PredicateKind.NET;
     method?: string;
     urlContains?: string;
     status?: number;
@@ -20,46 +20,79 @@ export type Predicate = {
     since?: number;
     count?: number;
 } | {
-    kind: 'route';
+    kind: typeof PredicateKind.ROUTE;
     pathname?: string;
     contains?: string;
+    since?: number;
 } | {
-    kind: 'console';
+    kind: typeof PredicateKind.CONSOLE;
     level?: string;
     absent?: boolean;
     since?: number;
 } | {
-    kind: 'animation';
+    kind: typeof PredicateKind.ANIMATION;
     name?: string;
     target?: string;
     completed?: boolean;
+    since?: number;
 } | {
-    kind: 'signal';
+    kind: typeof PredicateKind.SIGNAL;
     name?: string;
     dataMatches?: Record<string, unknown>;
+    since?: number;
 } | {
-    kind: 'state';
+    kind: typeof PredicateKind.STATE;
     store?: string;
     path: string;
     equals?: unknown;
 } | {
-    kind: 'settled';
+    kind: typeof PredicateKind.SETTLED;
     quietMs?: number;
 } | {
-    kind: 'allOf';
+    kind: typeof PredicateKind.ALL_OF;
     predicates: Predicate[];
 } | {
-    kind: 'anyOf';
+    kind: typeof PredicateKind.ANY_OF;
     predicates: Predicate[];
 } | {
-    kind: 'not';
+    kind: typeof PredicateKind.NOT;
     predicate: Predicate;
 };
+/**
+ * Strict on every branch. A key that is nobody's spelling is now a schema error naming it, instead of
+ * a stripped field and a green — see predicate-strict.test.ts for the MCP session that found this.
+ */
 export declare const PredicateSchema: z.ZodType<Predicate>;
 export interface EvalResult {
     pass: boolean;
+    /**
+     * For a TIME-based failure: how long until this predicate could first become true, if nothing else
+     * changes. Purely a scheduling hint for `waitForPredicate` — it replaces a blind poll tick with one
+     * timed to the moment that matters, and never decides anything. Absent when the wait is on an
+     * external event (a request in flight settles when the server answers, not on a clock).
+     */
+    retryAfterMs?: number;
+    /**
+     * Set when the assertion could not be EVALUATED — the call was under-specified or there was
+     * nothing instrumented to read — rather than evaluated and found false. Carries the sentence that
+     * names what is missing.
+     *
+     * `pass` stays false because nothing was proven, but a false that nobody could have made true is
+     * not a defect in the user's app, and reporting it as one puts agent mistakes into the bug count.
+     */
+    inconclusive?: string;
     evidence?: unknown;
     failureReason?: string;
+    /**
+     * The wait ended because the TAB went away, not because the app did anything observable.
+     *
+     * A sibling of `inconclusive` and for the same reason: `pass` is false because nothing was
+     * proven, but nobody could have made it true, so grading it as a defect in the user's app is a
+     * false claim. Without this the verdict rule saw only `pass: false` and answered
+     * `assertion_failed` — "the declared consequence did not hold" — naming the component the agent
+     * had just clicked. See VerifiedReason.OBSERVATION_LOST.
+     */
+    observationLost?: boolean;
     /**
      * The failure, structured — what was seen, what was required, and which oracle judged it.
      *
@@ -82,19 +115,19 @@ export interface EvalResult {
  */
 export declare function matchValue(got: unknown, want: unknown): boolean;
 export declare function evalNet(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: 'net';
+    kind: typeof PredicateKind.NET;
 }>): EvalResult;
 export declare function evalRoute(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: 'route';
+    kind: typeof PredicateKind.ROUTE;
 }>): EvalResult;
 export declare function evalConsole(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: 'console';
+    kind: typeof PredicateKind.CONSOLE;
 }>): EvalResult;
 export declare function evalAnimation(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: 'animation';
+    kind: typeof PredicateKind.ANIMATION;
 }>): EvalResult;
 export declare function evalSignal(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: 'signal';
+    kind: typeof PredicateKind.SIGNAL;
 }>): EvalResult;
 /**
  * "The page has gone quiet": no network/DOM/animation activity for at least `quietMs`. Needs the
@@ -102,6 +135,6 @@ export declare function evalSignal(events: ReticleEvent[], p: Extract<Predicate,
  * now, not to any buffered event — so `now` is injected (CLAUDE.md rule 7), and the wait loop's
  * poll interval is what eventually flips this to pass once activity stops.
  */
-export declare function evalSettled(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: 'settled';
+export declare function evalSettled(allEvents: ReticleEvent[], p: Extract<Predicate, {
+    kind: typeof PredicateKind.SETTLED;
 }>, now: number): EvalResult;