@reticlehq/server 2.9.0 → 2.11.0

package/dist/events/contradiction-folds.js

@@ -0,0 +1,42 @@
+import { log } from '../log.js';
+const FOLDS = [];
+/**
+ * Add a rule to every verdict this engine produces. Returns the undo.
+ *
+ * The undo is not a convenience: without it a registry is process-global state that tests cannot
+ * clean up, so each one starts depending on the order it ran in.
+ */
+export function registerContradictionFold(fold) {
+    FOLDS.push(fold);
+    return () => {
+        const at = FOLDS.indexOf(fold);
+        if (at !== -1)
+            FOLDS.splice(at, 1);
+    };
+}
+/** What is registered right now. Exported so a guard can assert the registry is empty by default. */
+export function registeredContradictionFolds() {
+    return [...FOLDS];
+}
+/**
+ * Run every registered rule, containing anything one of them throws.
+ *
+ * A registered fold is somebody else's code running inside every verdict path this package has. If a
+ * throw could propagate, one defect in a consumer's rule would take down `assert`, `act_and_wait`,
+ * `observe` and `crawl` at once — turning a missing finding into a dead engine. Contained and logged:
+ * the rules that did run still report, and the failure is visible rather than swallowed.
+ */
+export function runRegisteredFolds(events, options) {
+    const found = [];
+    for (const fold of FOLDS) {
+        try {
+            found.push(...fold(events, options));
+        }
+        catch (error) {
+            log('contradiction_fold_failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return found;
+}

package/dist/events/contradictions.d.ts

@@ -19,7 +19,16 @@ import { type DeclaredNetFailure } from './declared.js';
  * Pure: a window of events in, findings out. No session, no IO, no clock.
  */
 export interface Contradiction {
-    kind: ContradictionKind;
+    /**
+     * Typed `string`, not `ContradictionKind`, because the vocabulary is open at the EDGE.
+     *
+     * `ContradictionKind` enumerates what THIS package's rules emit, and every one of them is still
+     * checked against it — see `OwnContradiction`, which is what the folds below build. A rule
+     * registered by a consumer emits kinds this package has never heard of and must not have to add
+     * them here to be reportable: a shared enum is exactly how a consumer's private vocabulary ends up
+     * shipped in the free product by accident.
+     */
+    kind: string;
     /** What one channel asserted — the optimistic half. */
     claim: string;
     /** What the other channel asserted — the half that contradicts it. */
@@ -27,6 +36,15 @@ export interface Contradiction {
     /** Concrete evidence, so the agent can go straight to the call or the control. */
     detail: string;
 }
+/**
+ * A contradiction emitted by one of THIS package's rules — the kind is closed.
+ *
+ * Widening `Contradiction.kind` to `string` for the consumer seam would otherwise have made every
+ * emit site below accept a typo'd literal. This keeps them checked without closing the edge.
+ */
+export type OwnContradiction = Contradiction & {
+    kind: ContradictionKind;
+};
 export interface ContradictionOptions {
     /** The action that opened this window, when one did. Enables the no-effect check. */
     action?: string | undefined;

package/dist/events/contradictions.js

@@ -5,6 +5,7 @@ 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';
+import { runRegisteredFolds } from './contradiction-folds.js';
 function netCall(e) {
     const status = asNumber(e.data['status']);
     return {
@@ -255,7 +256,19 @@ export function findContradictions(allEvents, options = {}) {
     // 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) {
+    // An app that RETRACTED has not claimed success, whenever it fired the optimistic signal.
+    //
+    // The weaker UI rule below already consulted this and the sharper signal rule did not, so an app
+    // that announced "ack:requested", met a 500, and then correctly emitted "ack:failed" and rolled the
+    // row back was reported as explicitly asserting success — the strongest accusation this file makes,
+    // against code doing exactly the right thing. On a fixture suite the scenario's FIXED twin produced
+    // the same finding as the build that swallowed the failure, which makes the finding worthless on
+    // the one measurement that scores precision.
+    //
+    // Ordering cannot decide this: an optimistic UI legitimately fires its success signal BEFORE the
+    // response, so "the claim must follow the failure" would miss the real defect. What separates them
+    // is not when the app spoke, it is whether it took it back.
+    if (failed.length > 0 && successSignals.length > 0 && !failureAcknowledged(events)) {
         found.push({
             kind: ContradictionKind.SIGNAL_CONTRADICTED,
             claim: `the app fired ${successSignals.map((s) => `"${s}"`).join(', ')}`,
@@ -341,5 +354,7 @@ export function findContradictions(allEvents, options = {}) {
             });
         }
     }
-    return found;
+    // Consumer rules run LAST and over the same app-only window, so a service embedding this engine
+    // adds to the verdict rather than forking the file that produces it.
+    return [...found, ...runRegisteredFolds(events, options)];
 }

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

@@ -1,5 +1,5 @@
 import { type ReticleEvent } from '@reticlehq/core';
-import type { Contradiction } from './contradictions.js';
+import type { OwnContradiction } from './contradictions.js';
 /**
  * Contradictions for writes whose response echoes a different value than the request asked for.
  *
@@ -7,4 +7,4 @@ import type { Contradiction } from './contradictions.js';
  * 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[];
+export declare function findEchoMismatches(events: readonly ReticleEvent[], actionSince?: number): OwnContradiction[];

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

@@ -0,0 +1,17 @@
+import type { Predicate } from './predicate-schema.js';
+/**
+ * Did the caller's predicate ask about registered state?
+ *
+ * Walks composites, because `allOf[{net}, {state}]` asks about state exactly as much as a bare
+ * `{state}` does — and the gap that reveals is the same one either way.
+ *
+ * Lives here rather than at a call site because both the act path and the assert path need it, and
+ * two walkers over one predicate tree is two chances to disagree about what counts as asking.
+ *
+ * NOT in `predicate-schema.ts` next to `predicateFieldsFor`, where it would otherwise belong: five
+ * open contributor PRs are queued on that file and on `predicate-eval.ts`, and a one-function import
+ * is not worth handing five people a conflict. Named `predicate-asks` rather than `predicate-shape`
+ * because `predicate-shape.test.ts` already exists and is about something else entirely — a file
+ * that reads as the subject of an unrelated test is a half-hour somebody loses later.
+ */
+export declare function declaresState(predicate: Predicate): boolean;

package/dist/events/predicate-asks.js

@@ -0,0 +1,26 @@
+import { PredicateKind } from '@reticlehq/core';
+/**
+ * Did the caller's predicate ask about registered state?
+ *
+ * Walks composites, because `allOf[{net}, {state}]` asks about state exactly as much as a bare
+ * `{state}` does — and the gap that reveals is the same one either way.
+ *
+ * Lives here rather than at a call site because both the act path and the assert path need it, and
+ * two walkers over one predicate tree is two chances to disagree about what counts as asking.
+ *
+ * NOT in `predicate-schema.ts` next to `predicateFieldsFor`, where it would otherwise belong: five
+ * open contributor PRs are queued on that file and on `predicate-eval.ts`, and a one-function import
+ * is not worth handing five people a conflict. Named `predicate-asks` rather than `predicate-shape`
+ * because `predicate-shape.test.ts` already exists and is about something else entirely — a file
+ * that reads as the subject of an unrelated test is a half-hour somebody loses later.
+ */
+export function declaresState(predicate) {
+    if (predicate.kind === PredicateKind.STATE)
+        return true;
+    if (predicate.kind === PredicateKind.ALL_OF || predicate.kind === PredicateKind.ANY_OF) {
+        return predicate.predicates.some(declaresState);
+    }
+    if (predicate.kind === PredicateKind.NOT)
+        return declaresState(predicate.predicate);
+    return false;
+}

package/dist/events/predicate-eval.js

@@ -160,8 +160,111 @@ function describeNetFilter(p) {
     const { kind: _kind, count: _count, since: _since, ...filter } = p;
     return JSON.stringify(filter);
 }
+/**
+ * URL suffixes only the DOCUMENT fetches, which the network observer therefore never records.
+ *
+ * `network.ts` patches `fetch` and `XMLHttpRequest` and nothing else, so `<link rel=icon>`,
+ * `<link rel=manifest>`, stylesheets, fonts and `<img src>` are invisible to it. "No matching call"
+ * and "that class of call is not observed" are then indistinguishable, and the miss graded
+ * `assertion_failed` — a false RED. Reported from the field: an assert over `/favicon.ico`,
+ * `/site.webmanifest` and `/apple-touch-icon.png` returned `verified:"no"` while curl showed all
+ * three answering 200. A false negative here is worse than an unknown, because an agent that trusts
+ * it goes and "fixes" working code.
+ *
+ * Deliberately NOT here: `.js` and `.json`. Both are routinely fetched via `fetch`/XHR — a module
+ * preload and an API call can share a suffix — so downgrading them would hide real misses. This list
+ * is only the suffixes for which the document is the sole plausible initiator.
+ *
+ * This began as the smaller half of #447: it did not make these requests observable, it stopped
+ * Reticle claiming they did not happen. The other half, observing them via resource timing, has
+ * since landed in the browser SDK, so the two halves are no longer independent and this downgrade is
+ * now GATED: when the event stream carries at least one document-initiated record, the observer is
+ * demonstrably live and a miss over these suffixes is real evidence, graded a plain failure. Only a
+ * page whose stream holds no resource entry at all keeps the honest "cannot tell apart" answer,
+ * because there the observer may simply not exist.
+ */
+const DOCUMENT_ONLY_SUFFIXES = [
+    '.ico',
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.svg',
+    '.webp',
+    '.avif',
+    '.bmp',
+    '.css',
+    '.woff',
+    '.woff2',
+    '.ttf',
+    '.otf',
+    '.eot',
+    '.webmanifest',
+];
+/**
+ * Does this filter target a class of request the observer cannot see?
+ *
+ * Read off `urlContains` only, and only when the pattern ENDS in one of the suffixes — a filter of
+ * `/api/` that happens to contain `.css` somewhere in a query string is still an ordinary XHR
+ * target. Query strings and fragments are stripped first, since `favicon.ico?v=2` is the same asset.
+ */
+function targetsUnobservedChannel(p) {
+    if (p.urlContains === undefined)
+        return false;
+    const path = (p.urlContains.split('#')[0] ?? '').split('?')[0]?.toLowerCase() ?? '';
+    return DOCUMENT_ONLY_SUFFIXES.some((suffix) => path.endsWith(suffix));
+}
+/**
+ * Initiator types the browser SDK's resource-timing observer stamps onto document-initiated records
+ * (packages/browser/src/observers/network.ts). The patched transports sign themselves `fetch`,
+ * `xhr` or `beacon`, so any NET_REQUEST carrying one of these came from a `resource` entry, and its
+ * mere presence is proof the PerformanceObserver is alive on this page. Mirrors the wire; keep in
+ * sync with the browser package.
+ */
+const DOCUMENT_INITIATORS = new Set([
+    'link',
+    'css',
+    'img',
+    'script',
+    'manifest',
+    'other',
+]);
+/**
+ * Did the observer actually report a document-initiated load?
+ *
+ * This is the gate on the unobserved-channel downgrade above. Once subresource observation landed,
+ * a miss over `.ico`/`.css`/`.woff2` is no longer inherently unknowable: if the observer is live it
+ * would have seen the favicon load, so seeing none is evidence it never fired. But the observer is
+ * opt-in-by-engine, not guaranteed: on a renderer without `PerformanceObserver` (or before any
+ * resource entry exists) nothing distinguishes "not requested" from "not visible", and the honest
+ * answer stays inconclusive. Liveness is inferred from the same events being judged: one
+ * document-initiated record anywhere in the window proves the channel works.
+ */
+function observerSawSubresources(events) {
+    return events.some((e) => {
+        if (e.type !== EventType.NET_REQUEST)
+            return false;
+        const initiator = str(e.data['initiator']);
+        return initiator !== undefined && DOCUMENT_INITIATORS.has(initiator);
+    });
+}
+/** The sentence both zero-match branches hand to `inconclusive`. */
+function unobservedChannelReason(p) {
+    return (`no call matched ${describeNetFilter(p)}, and no document-initiated load was recorded either, ` +
+        `so this page exposed no resource timing to read: Reticle observes fetch and XMLHttpRequest ` +
+        `directly, while a request the document initiates (<link rel=icon|manifest|preload>, a ` +
+        `stylesheet, a font, <img src>) leaves no record, and that state cannot be told apart from the ` +
+        `request having been made. ` +
+        `Nothing here says the app is wrong. Check it outside the browser, or assert something the ` +
+        `document does not fetch on its own`);
+}
 export function evalNet(events, p) {
     const since = p.since ?? 0;
+    /**
+     * Computed once: the gate every zero-match downgrade below reads. True means the resource-timing
+     * observer is demonstrably live in this window, so a miss is evidence rather than blindness.
+     */
+    const sawSubresources = observerSawSubresources(events);
     /**
      * Did any call match everything EXCEPT the body assertion, while carrying no recorded body?
      *
@@ -171,6 +274,8 @@ export function evalNet(events, p) {
      * because it is the same pass over the same events.
      */
     let matchedButUnrecorded = false;
+    /** A call matched url/method but carried NO readable status (document-initiated subresource). */
+    let unobservableStatus = false;
     /**
      * The response body of a call that matched everything EXCEPT the body assertion, and HAD one.
      *
@@ -190,8 +295,19 @@ export function evalNet(events, p) {
         if (p.urlContains !== undefined && !(str(d['url']) ?? '').includes(p.urlContains)) {
             return false;
         }
-        if (p.status !== undefined && num(d['status']) !== p.status)
-            return false;
+        if (p.status !== undefined) {
+            const status = num(d['status']);
+            if (status === undefined) {
+                // Document-initiated subresources (link/css/img/manifest via resource timing) carry no
+                // readable status on engines without responseStatus. A failed assertion here would read
+                // "your change is broken" and send the caller to fix working code — the exact false
+                // negative the oracle exists to prevent. Downgrade to unknown instead.
+                unobservableStatus = true;
+                return false;
+            }
+            if (status !== p.status)
+                return false;
+        }
         if (p.ok !== undefined && callSucceeded(d) !== p.ok)
             return false;
         if (p.bodyContains !== undefined) {
@@ -211,6 +327,18 @@ export function evalNet(events, p) {
         }
         return true;
     });
+    if (unobservableStatus && 0 === matches.length) {
+        // The url/method matched a document-initiated subresource whose engine could not read a status.
+        // "No matching call" would be a lie in both directions: it may have succeeded, it may have 404'd
+        // on exactly the path mistake the caller is hunting. Say the truth — not observable here.
+        return {
+            pass: false,
+            inconclusive: `a document-initiated request matching ${describeNetFilter(p)} was observed, but this engine does not expose its status code (resource timing without responseStatus) — assert on the element or route instead, or check the network tab`,
+            observed: 'a matching request with no readable status',
+            expected: `a status of ${String(p.status)} on ${JSON.stringify(p.urlContains ?? '*')}`,
+            assertion: 'net.unobservable-status',
+        };
+    }
     if (matchedButUnrecorded && 0 === matches.length) {
         return {
             pass: false,
@@ -237,19 +365,37 @@ export function evalNet(events, p) {
     if (p.count !== undefined) {
         return matches.length === p.count
             ? { pass: true, evidence: { matched: matches.length } }
-            : {
-                pass: false,
-                // Monotonic: more matches than asked for can never become exactly the number asked for.
-                // This is the double-submit — two writes 59ms apart — so the finding that matters most was
-                // also the one that took the caller's whole budget to report.
-                ...(matches.length > p.count ? { decided: true } : {}),
-                failureReason: `expected ${String(p.count)} network call(s) matching ${describeNetFilter(p)}, saw ${String(matches.length)}`,
-                observed: `${String(matches.length)} matching network call(s)`,
-                expected: `exactly ${String(p.count)} matching ${describeNetFilter(p)}`,
-                assertion: 'net.count',
-            };
+            : 0 === matches.length && targetsUnobservedChannel(p) && !sawSubresources
+                ? {
+                    pass: false,
+                    failureReason: unobservedChannelReason(p),
+                    inconclusive: unobservedChannelReason(p),
+                    assertion: 'net.count',
+                }
+                : {
+                    pass: false,
+                    // Monotonic: more matches than asked for can never become exactly the number asked for.
+                    // This is the double-submit — two writes 59ms apart — so the finding that matters most was
+                    // also the one that took the caller's whole budget to report.
+                    ...(matches.length > p.count ? { decided: true } : {}),
+                    failureReason: `expected ${String(p.count)} network call(s) matching ${describeNetFilter(p)}, saw ${String(matches.length)}`,
+                    observed: `${String(matches.length)} matching network call(s)`,
+                    expected: `exactly ${String(p.count)} matching ${describeNetFilter(p)}`,
+                    assertion: 'net.count',
+                };
     }
     const hit = matches[0];
+    if (hit === undefined && targetsUnobservedChannel(p) && !sawSubresources) {
+        const reason = unobservedChannelReason(p);
+        return {
+            pass: false,
+            failureReason: reason,
+            inconclusive: reason,
+            observed: describeObserved('calls', events.filter((e) => e.type === EventType.NET_REQUEST).map(describeCall)),
+            expected: `at least one call matching ${describeNetFilter(p)}`,
+            assertion: 'net.unobserved-channel',
+        };
+    }
     return hit !== undefined
         ? { pass: true, evidence: hit.data }
         : {
@@ -296,25 +442,66 @@ export function evalConsole(events, p) {
             return isErr;
         return e.type === CONSOLE_LEVEL_TYPE[p.level];
     });
+    // A text match narrows the population to entries whose captured message contains the substring.
+    // With `absent: true` this is the whole point: "THIS message did not appear", not "no messages
+    // appeared" — the difference between a regression check and a fragile one that any unrelated
+    // warning anywhere in the app breaks.
+    const wanted = 'contains' in p ? p.contains : undefined;
+    // Captured messages are strings (stringifyArgs in the browser observer), but a malformed or
+    // foreign event must not crash the evaluator: non-strings stringify defensively, and objects
+    // go through JSON.stringify rather than a default toString that would print '[object Object]'.
+    const asText = (v) => {
+        if ('string' === typeof v)
+            return v;
+        try {
+            return JSON.stringify(v) ?? '';
+        }
+        catch {
+            return '';
+        }
+    };
+    const matching = wanted !== undefined
+        ? matches.filter((e) => asText(e.data['message']).includes(wanted))
+        : matches;
     if (true === p.absent) {
-        return 0 === matches.length
+        if (wanted !== undefined && 0 === matching.length && matches.length > 0) {
+            // Other entries exist but none carries the substring: exactly the pass an absence-with-match
+            // asserts. Name both counts so the caller can tell this from a silent window.
+            return {
+                pass: true,
+                evidence: { absent: true, contains: wanted },
+            };
+        }
+        return 0 === matching.length
             ? { pass: true, evidence: { absent: true } }
             : {
                 pass: false,
-                failureReason: `expected no ${p.level ?? 'console'} entries but found ${String(matches.length)}`,
-                observed: `${String(matches.length)} ${p.level ?? 'console'} entr${1 === matches.length ? 'y' : 'ies'}`,
-                expected: `no ${p.level ?? 'console'} entries`,
-                assertion: 'console.absent',
-                evidence: matches.map((e) => e.data),
+                failureReason: wanted !== undefined
+                    ? `expected no ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)} but found ${String(matching.length)}`
+                    : `expected no ${p.level ?? 'console'} entries but found ${String(matches.length)}`,
+                observed: wanted !== undefined
+                    ? `${String(matching.length)} ${p.level ?? 'console'} entr${1 === matching.length ? 'y' : 'ies'} containing ${JSON.stringify(wanted)}`
+                    : `${String(matches.length)} ${p.level ?? 'console'} entr${1 === matches.length ? 'y' : 'ies'}`,
+                expected: wanted !== undefined
+                    ? `no ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)}`
+                    : `no ${p.level ?? 'console'} entries`,
+                assertion: wanted !== undefined ? 'console.absent-contains' : 'console.absent',
+                evidence: matching.map((e) => e.data),
             };
     }
-    return matches.length > 0
-        ? { pass: true, evidence: matches.map((e) => e.data) }
+    return matching.length > 0
+        ? { pass: true, evidence: matching.map((e) => e.data) }
         : {
             pass: false,
-            failureReason: `no ${p.level ?? 'console'} entries found`,
-            observed: `no ${p.level ?? 'console'} entries in the window`,
-            expected: `at least one ${p.level ?? 'console'} entry`,
+            failureReason: wanted !== undefined
+                ? `no ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)} found`
+                : `no ${p.level ?? 'console'} entries found`,
+            observed: wanted !== undefined
+                ? `no ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)} in the window`
+                : `no ${p.level ?? 'console'} entries in the window`,
+            expected: wanted !== undefined
+                ? `at least one ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)}`
+                : `at least one ${p.level ?? 'console'} entry`,
             assertion: 'console.present',
         };
 }

package/dist/events/predicate-parse.js

@@ -14,7 +14,7 @@
  */
 import { z } from 'zod';
 import { PredicateKind } from '@reticlehq/core';
-import { PredicateSchema, predicateFieldsFor } from './predicate-eval.js';
+import { PredicateSchema, predicateFieldsFor, predicateNestedFieldsFor } from './predicate-eval.js';
 /**
  * One valid call PER KIND, because an example of another kind answers a question nobody asked.
  *
@@ -90,7 +90,13 @@ export function parsePredicate(input) {
  */
 function accepted(kind) {
     const fields = predicateFieldsFor(kind);
-    if (0 < fields.length)
-        return `${kind} accepts: ${fields.join(', ')}.`;
+    if (0 < fields.length) {
+        // A field whose value is an object is the one an agent cannot guess from its name alone, so
+        // expand it in the same breath rather than making the shape a second round trip.
+        const nested = Object.entries(predicateNestedFieldsFor(kind))
+            .map(([field, keys]) => ` ${field} accepts: ${keys.join(', ')}.`)
+            .join('');
+        return `${kind} accepts: ${fields.join(', ')}.${nested}`;
+    }
     return `"${kind}" is not a predicate kind — use one of: ${Object.values(PredicateKind).join(', ')}.`;
 }

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

@@ -38,6 +38,12 @@ export type Predicate = {
 } | {
     kind: typeof PredicateKind.CONSOLE;
     level?: string;
+    /**
+     * A substring the captured message must contain. With `absent: true` this flips the meaning
+     * from "no console entries at all" to "THIS message did not appear" — the assertion people
+     * actually write regression checks for (deprecation warnings, no-op handler notices).
+     */
+    contains?: string;
     absent?: boolean;
     since?: number;
 } | {
@@ -97,3 +103,15 @@ export declare const PredicateSchema: z.ZodType<Predicate>;
  * wall. Empty for a kind that is not in the union.
  */
 export declare function predicateFieldsFor(kind: string): readonly string[];
+/**
+ * One level into the fields that are themselves objects — `{ query: ['by', 'value', ...] }`.
+ *
+ * Naming the top-level fields alone leaves `element` unguessable: `query` is an object with its own
+ * required shape, and a plain CSS string works in `reticle_snapshot.scope` and `reticle_query.scope`,
+ * so assuming it works here is the natural guess. The rejection is the only place that inconsistency
+ * can be explained.
+ *
+ * One level only. Derived from the schema for the same reason `predicateFieldsFor` is: a stale field
+ * list is worse than none, because the agent trusts it and retries into the same wall.
+ */
+export declare function predicateNestedFieldsFor(kind: string): Readonly<Record<string, readonly string[]>>;

package/dist/events/predicate-schema.js

@@ -21,6 +21,10 @@ const PREDICATE_ALIASES = {
     // most common thing an agent reaches for here.
     [PredicateKind.ROUTE]: { path: 'pathname', urlContains: 'contains', url: 'contains' },
     [PredicateKind.NET]: { url: 'urlContains' },
+    // `textContains` on a `console` predicate: the reporter who hit the missing matcher reached for
+    // it first, by analogy with `net { urlContains }` — and that parallel is exactly right, since
+    // both mean "this entry must contain this substring". Accepted as an alias for `contains`.
+    [PredicateKind.CONSOLE]: { textContains: 'contains' },
     [PredicateKind.SIGNAL]: { data: 'dataMatches' },
     // `of` on a composite: it reads naturally, several assertion libraries spell it that way, and it has
     // no other meaning here. Observed twice in one drive on a real app, and each rejection cost a round
@@ -246,6 +250,7 @@ function predicateUnion() {
             .object({
             kind: z.literal(PredicateKind.CONSOLE),
             level: z.string().optional(),
+            contains: z.string().min(1).optional(),
             absent: z.boolean().optional(),
             since: z.number().optional(),
         })
@@ -307,3 +312,53 @@ export function predicateFieldsFor(kind) {
     }
     return [];
 }
+/** Peel optional/nullable/default/effects wrappers off a field to reach the schema underneath. */
+function unwrapSchema(schema) {
+    let current = schema;
+    for (;;) {
+        if (current instanceof z.ZodOptional ||
+            current instanceof z.ZodNullable ||
+            current instanceof z.ZodDefault) {
+            current = current._def.innerType;
+            continue;
+        }
+        if (current instanceof z.ZodEffects) {
+            current = current._def.schema;
+            continue;
+        }
+        return current;
+    }
+}
+/**
+ * One level into the fields that are themselves objects — `{ query: ['by', 'value', ...] }`.
+ *
+ * Naming the top-level fields alone leaves `element` unguessable: `query` is an object with its own
+ * required shape, and a plain CSS string works in `reticle_snapshot.scope` and `reticle_query.scope`,
+ * so assuming it works here is the natural guess. The rejection is the only place that inconsistency
+ * can be explained.
+ *
+ * One level only. Derived from the schema for the same reason `predicateFieldsFor` is: a stale field
+ * list is worse than none, because the agent trusts it and retries into the same wall.
+ */
+export function predicateNestedFieldsFor(kind) {
+    for (const option of predicateUnion().options) {
+        const literal = option.shape['kind'];
+        if (!(literal instanceof z.ZodLiteral) || literal.value !== kind)
+            continue;
+        const nested = {};
+        for (const [field, schema] of Object.entries(option.shape)) {
+            if ('kind' === field)
+                continue;
+            const inner = unwrapSchema(schema);
+            // `instanceof z.ZodObject` narrows to ZodObject<any>, whose `.shape` is `any`. Name the shape
+            // type so the keys are read off something typed rather than laundering an `any` through
+            // Object.keys.
+            if (inner instanceof z.ZodObject) {
+                const shape = inner.shape;
+                nested[field] = Object.keys(shape);
+            }
+        }
+        return nested;
+    }
+    return {};
+}

package/dist/events/stale-response.d.ts

@@ -1,4 +1,3 @@
 import { type ReticleEvent } from '@reticlehq/core';
-import type { Contradiction } from './contradictions.js';
-/** The one contradiction, or none. Reported once per window — a race is a fact about the window. */
-export declare function findStaleResponses(events: readonly ReticleEvent[]): Contradiction[];
+import type { OwnContradiction } from './contradictions.js';
+export declare function findStaleResponses(events: readonly ReticleEvent[]): OwnContradiction[];