@reticlehq/server 2.11.0 → 2.12.0

package/dist/events/contradictions.js

@@ -1,4 +1,5 @@
-import { ContradictionKind, EventType, MUTATING_METHODS, isDevToolingUrl, } from '@reticlehq/core';
+import { ContradictionKind, EventType, MUTATING_METHODS, isDevToolingUrl, isSameDocument, isSameEditEpoch, } from '@reticlehq/core';
+import { describeSuperseded } from './observed-in-window.js';
 import { findStaleResponses } from './stale-response.js';
 import { findBodyFailures } from './body-failures.js';
 import { findEchoMismatches } from './echo-mismatch.js';
@@ -162,9 +163,64 @@ function splitDevTooling(events) {
     });
     return { app, ignored };
 }
+/**
+ * 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 function findContradictions(allEvents, options = {}) {
+    const found = findWindowContradictions(allEvents, options);
+    const predates = allEvents.length > 0 &&
+        allEvents.every((e) => !isSameEditEpoch(e.editEpoch, options.currentEditEpoch));
+    if (!predates)
+        return found;
+    // Prepended, not appended: the caveat governs how everything under it should be read, and it has
+    // to survive the rules that return early with a single finding of their own.
+    return [
+        {
+            kind: ContradictionKind.EVIDENCE_PREDATES_EDIT,
+            claim: 'these observations describe the code as it is now',
+            counter: 'every one of them was recorded before the last hot update landed in the page',
+            detail: 'the source changed and the page re-rendered after this evidence was captured, so it describes code that has since been replaced — nothing here is necessarily wrong, but nothing here has seen the edit either. Drive the app again to verify the current code',
+        },
+        ...found,
+    ];
+}
+function findWindowContradictions(allEvents, options) {
     const found = [];
-    const { app: events, ignored: ignoredDevTooling } = splitDevTooling(allEvents);
+    const { app: allApp, ignored: ignoredDevTooling } = splitDevTooling(allEvents);
+    // ── Evidence belonging to a document that has since been replaced ───────────────────────────
+    // Scoped ONCE, here, for the same reason the dev-tooling split is: every rule below asks "what
+    // else was in this window", and answering that with a dead page's traffic is a defect in all of
+    // them rather than in whichever one reported it. Applied after the dev-tooling split so the count
+    // reported below is the app's own evidence and not the toolchain's noise.
+    const events = allApp.filter((e) => isSameDocument(e.documentId, options.currentDocumentId));
+    const superseded = allApp.length - events.length;
+    // An empty window was always allowed to mean "nothing happened"; that reading is only unsafe once
+    // supersession is what emptied it. Reported ALONE and before every rule below, because a window
+    // with nothing left in it is exactly the shape `action-had-no-effect` fires on — so without this
+    // the fix would have swapped a wrong citation for a wrong accusation.
+    if (superseded > 0 && 0 === events.length) {
+        return [
+            {
+                kind: ContradictionKind.EVIDENCE_SUPERSEDED,
+                claim: 'this window holds observations that could answer for the action',
+                counter: describeSuperseded('observations', superseded),
+                detail: 'a full navigation or a reload built a new document, and everything recorded here belongs to the old one — citing it would name requests, errors and state that no longer describe anything on screen',
+            },
+        ];
+    }
     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.
@@ -290,18 +346,71 @@ export function findContradictions(allEvents, options = {}) {
     if (!advanced) {
         const ignoredWrites = settled.filter((c) => true === c.ok && isMutating(c));
         if (ignoredWrites.length > 0) {
-            found.push({
-                kind: ContradictionKind.RESPONSE_IGNORED,
-                claim: `${String(ignoredWrites.length)} write(s) succeeded on the server`,
-                counter: 'nothing on the client changed — no DOM, store or route movement',
-                detail: ignoredWrites.map(describe).join('; '),
-            });
+            // ...unless THIS document handed the consequence to another browsing context. An OAuth sign-in
+            // posts, succeeds, and continues in a popup the in-page SDK cannot follow (#508): the original
+            // tab legitimately never changes, and response-ignored would accuse it of ignoring a response
+            // it handed off. The opened-context event flips the reading from "the client did nothing" to
+            // "the client went where we cannot look". Scoped like every rule here to the attribution floor
+            // (`options.actionSince`; the local below is declared later, for the window rules).
+            const contextFloor = options.actionSince;
+            const openedContext = events.some((e) => e.type === EventType.CONTEXT_OPENED && contextFloor !== undefined && e.t >= contextFloor);
+            found.push(openedContext
+                ? {
+                    kind: ContradictionKind.CONSEQUENCE_ELSEWHERE,
+                    claim: `${String(ignoredWrites.length)} write(s) succeeded on the server`,
+                    counter: 'this document never changed because the page opened another browsing context during this window (e.g. an OAuth popup), where the in-page SDK cannot observe the result',
+                    detail: ignoredWrites.map(describe).join('; '),
+                }
+                : {
+                    kind: ContradictionKind.RESPONSE_IGNORED,
+                    claim: `${String(ignoredWrites.length)} write(s) succeeded on the server`,
+                    counter: 'nothing on the client changed — no DOM, store or route movement',
+                    detail: ignoredWrites.map(describe).join('; '),
+                });
         }
     }
+    // ── The app announced a consequence and nothing else moved ─────────────────────────────────
+    // Scoped as tightly as the evidence allows, because this rule fires on the ABSENCE of everything
+    // else and that is the easiest way to build a false positive.
+    //
+    // Only when the window is otherwise EMPTY: no DOM, no store, no route (`!advanced`) and no request
+    // at all. A request means the app reached for something, and whether it settled, failed or was
+    // ignored belongs to three other rules — firing here too would report one fact twice.
+    //
+    // `successSignals` reuses the failure-shaped filter above: an app that announced `deploy:failed`
+    // is correctly reporting that nothing happened, and accusing it inverts the meaning of the one app
+    // doing this right.
+    //
+    // And only for a window attributed to an ACTION. `reticle_assert` OBSERVES — there is no click
+    // whose consequence should have corroborated anything, so an assert over a quiet window carrying
+    // one signal is an ordinary read, not a claim nothing backs. Without this the rule reddened eight
+    // existing tests that assert exactly that, which is the false-positive class this scoping exists
+    // to prevent.
+    if (options.actionSince !== undefined &&
+        !advanced &&
+        0 === settled.length &&
+        successSignals.length > 0) {
+        found.push({
+            kind: ContradictionKind.SIGNAL_WITHOUT_CONSEQUENCE,
+            claim: `the app fired ${successSignals.map((s) => `"${s}"`).join(', ')}`,
+            counter: 'nothing else in the window moved — no DOM, no store, no route, no request — so the only ' +
+                'evidence that anything happened is the app saying so',
+            detail: 'a signal emitted from the value the app was ASKED for, rather than the one it committed, ' +
+                'reads identically to one that worked',
+        });
+    }
     // ── 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.
+    //
+    // A captured request body joins the identity. A command-bus API posts every mutation to one URL
+    // and discriminates on a body field (`{"command":"study.stage.set"}` vs `{"command":"mesh.plan"}`),
+    // so under URL alone each of those distinct writes read as a repeat of the first, and clean
+    // verdicts degraded to unknown behind doubles that were never doubles. When no body was captured
+    // (capture off, or a non-text body, which reports a type marker instead) there is nothing to
+    // compare and the URL alone stands, as before; a window where only some calls carried bodies
+    // compares nothing rather than guess.
     const actionSince = options.actionSince;
     if (actionSince !== undefined) {
         const writeCounts = new Map();
@@ -311,17 +420,21 @@ export function findContradictions(allEvents, options = {}) {
             const call = netCall(event);
             if (!isMutating(call))
                 continue;
-            const key = `${call.method} ${call.url}`;
-            writeCounts.set(key, (writeCounts.get(key) ?? 0) + 1);
+            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);
         }
-        for (const [key, count] of writeCounts) {
+        for (const [, { label, 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)}`,
+                detail: `${label} ×${String(count)}`,
             });
         }
     }

package/dist/events/declared.d.ts

@@ -31,6 +31,20 @@ export interface DeclaredExpectations {
     rendersContent: boolean;
 }
 export declare function declaredExpectations(predicate: Predicate | undefined): DeclaredExpectations;
+/**
+ * Did the caller name a consequence that does not depend on the response body?
+ *
+ * The unread-body clause exists for the case where the body is the ONLY channel that could have
+ * contradicted the screen — a 200 with per-item failures inside, a GraphQL error that is also a
+ * 200. A declared string on screen, store path, or signal that held is a different channel, and
+ * grading `unknown` there costs a real verdict (measured: a 201 plus the unique row, unread body,
+ * agent went to enable capture instead of finishing the drive).
+ *
+ * Same conservatism as `declaredExpectations`: only the top level and `allOf`. An `anyOf` branch
+ * may never have held, and honouring it would skip the unread caveat on the strength of a net
+ * success that was the branch that actually matched.
+ */
+export declare function declaresBodyIndependentChannel(predicate: Predicate | undefined): boolean;
 /**
  * Does a call the window recorded match a failure the caller declared?
  *

package/dist/events/declared.js

@@ -53,6 +53,39 @@ export function declaredExpectations(predicate) {
         walk(predicate);
     return { netFailures, rendersContent };
 }
+/**
+ * Did the caller name a consequence that does not depend on the response body?
+ *
+ * The unread-body clause exists for the case where the body is the ONLY channel that could have
+ * contradicted the screen — a 200 with per-item failures inside, a GraphQL error that is also a
+ * 200. A declared string on screen, store path, or signal that held is a different channel, and
+ * grading `unknown` there costs a real verdict (measured: a 201 plus the unique row, unread body,
+ * agent went to enable capture instead of finishing the drive).
+ *
+ * Same conservatism as `declaredExpectations`: only the top level and `allOf`. An `anyOf` branch
+ * may never have held, and honouring it would skip the unread caveat on the strength of a net
+ * success that was the branch that actually matched.
+ */
+export function declaresBodyIndependentChannel(predicate) {
+    if (predicate === undefined)
+        return false;
+    const walk = (p) => {
+        switch (p.kind) {
+            case PredicateKind.ALL_OF:
+                return p.predicates.some(walk);
+            case PredicateKind.TEXT:
+                return true !== p.absent;
+            case PredicateKind.SIGNAL:
+            case PredicateKind.STATE:
+                return true;
+            case PredicateKind.ELEMENT:
+                return true !== p.absent && (p.query.value !== undefined || p.query.text !== undefined);
+            default:
+                return false;
+        }
+    };
+    return walk(predicate);
+}
 /**
  * Does a call the window recorded match a failure the caller declared?
  *

package/dist/events/echo-mismatch.js

@@ -133,6 +133,20 @@ export function findEchoMismatches(events, actionSince) {
             continue;
         const echoed = scalarsByKey(response);
         const asked = scalarsByKey(request);
+        // The response has to be ECHO-SHAPED before any key can contradict anything. An echo restates
+        // what was sent, so most of the request's scalar keys reappear somewhere in it; a snapshot that
+        // happens to share a key or two does not (#506: `{"command":"chat.send"}` answered with the
+        // viewer snapshot read one incidental shared key as an attempted echo of a write that fully
+        // applied). Requiring a strict majority of the request's keys to appear keeps every documented
+        // true positive — an envelope restates most of its fields — and deliberately trades the rare
+        // half-echoed write away, the same direction MAX_ECHO_KEYS already trades in.
+        let shared = 0;
+        for (const key of asked.keys()) {
+            if (echoed.has(key))
+                shared += 1;
+        }
+        if (shared * 2 <= asked.size)
+            continue;
         const dropped = [];
         for (const [key, wanted] of asked) {
             // More than one requested value for a key (a before/after pair, a list of items) makes "what

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

@@ -10,3 +10,15 @@
  * 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;
+/**
+ * The third answer, and the one this file existed to make room for: things happened, and they belong
+ * to a document that has since been replaced.
+ *
+ * `describeObserved` already separates "nothing happened" from "things happened but not that one",
+ * because those need different fixes. A window whose evidence was discarded as superseded is a third
+ * case needing a third fix, and it is the one that reads most like the first: everything that could
+ * have answered the question is gone, so a bare "nothing happened in this window" is available and
+ * wrong. The remedy is in the sentence, because an agent that cannot act on a caveat learns to skip
+ * it — here the remedy is to drive the action again against the page now on screen.
+ */
+export declare function describeSuperseded(noun: string, count: number): string;

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

@@ -19,3 +19,20 @@ export function describeObserved(noun, seen) {
     const rest = unique.length - shown.length;
     return `${noun} seen in this window: ${shown.join(', ')}${rest > 0 ? `, and ${String(rest)} more` : ''}`;
 }
+/**
+ * The third answer, and the one this file existed to make room for: things happened, and they belong
+ * to a document that has since been replaced.
+ *
+ * `describeObserved` already separates "nothing happened" from "things happened but not that one",
+ * because those need different fixes. A window whose evidence was discarded as superseded is a third
+ * case needing a third fix, and it is the one that reads most like the first: everything that could
+ * have answered the question is gone, so a bare "nothing happened in this window" is available and
+ * wrong. The remedy is in the sentence, because an agent that cannot act on a caveat learns to skip
+ * it — here the remedy is to drive the action again against the page now on screen.
+ */
+export function describeSuperseded(noun, count) {
+    return (`no ${noun} belong to the document currently on screen: ${String(count)} ${noun} were observed ` +
+        `and every one of them belongs to a document that has since been replaced (the page reloaded or ` +
+        `navigated). This says nothing about the app — the evidence went away with the page that produced ` +
+        `it. Re-drive the action against the page now on screen`);
+}

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

@@ -15,3 +15,16 @@ import type { Predicate } from './predicate-schema.js';
  * that reads as the subject of an unrelated test is a half-hour somebody loses later.
  */
 export declare function declaresState(predicate: Predicate): boolean;
+/**
+ * Does the caller's predicate judge the DOM — an `element` or `text` clause anywhere in the tree?
+ *
+ * The question behind it is where a verdict is allowed to point. A DOM predicate has its own locus:
+ * the element it matched, whose `file:line` the descriptor already carries. A `signal`/`net`/`state`
+ * failure has none — there is no node for "the request was never made" — and that is the one case
+ * where the verdict borrows the last driven control's line, because the handler that should have
+ * fired lives there.
+ *
+ * Walks composites for the same reason `declaresState` does: `allOf[{element}, {signal}]` looked at
+ * the DOM exactly as much as a bare `{element}` did.
+ */
+export declare function declaresDom(predicate: Predicate): boolean;

package/dist/events/predicate-asks.js

@@ -24,3 +24,25 @@ export function declaresState(predicate) {
         return declaresState(predicate.predicate);
     return false;
 }
+/**
+ * Does the caller's predicate judge the DOM — an `element` or `text` clause anywhere in the tree?
+ *
+ * The question behind it is where a verdict is allowed to point. A DOM predicate has its own locus:
+ * the element it matched, whose `file:line` the descriptor already carries. A `signal`/`net`/`state`
+ * failure has none — there is no node for "the request was never made" — and that is the one case
+ * where the verdict borrows the last driven control's line, because the handler that should have
+ * fired lives there.
+ *
+ * Walks composites for the same reason `declaresState` does: `allOf[{element}, {signal}]` looked at
+ * the DOM exactly as much as a bare `{element}` did.
+ */
+export function declaresDom(predicate) {
+    if (predicate.kind === PredicateKind.ELEMENT || predicate.kind === PredicateKind.TEXT)
+        return true;
+    if (predicate.kind === PredicateKind.ALL_OF || predicate.kind === PredicateKind.ANY_OF) {
+        return predicate.predicates.some(declaresDom);
+    }
+    if (predicate.kind === PredicateKind.NOT)
+        return declaresDom(predicate.predicate);
+    return false;
+}

package/dist/events/predicate-eval.js

@@ -160,6 +160,35 @@ function describeNetFilter(p) {
     const { kind: _kind, count: _count, since: _since, ...filter } = p;
     return JSON.stringify(filter);
 }
+/** Same, for a signal: the matcher as applied, with the cardinality and the floor taken out. */
+function describeSignalFilter(p) {
+    const { kind: _kind, count: _count, since: _since, ...filter } = p;
+    return JSON.stringify(filter);
+}
+/**
+ * Exact cardinality, once, for every channel that can count its matches.
+ *
+ * `net` and `signal` are the same assertion over different evidence — "this happened EXACTLY n
+ * times" — and the interesting half is the same on both: an over-count is `decided`, because a
+ * window only accumulates and a count cannot come back down, so waiting out the rest of the budget
+ * to report a double-fire buys nothing but latency.
+ *
+ * `noun` names the population in prose ("network call(s)", "signal(s)"), `filter` is the matcher as
+ * applied, and `assertion` is the oracle that judged it.
+ */
+function evalExactCount(args) {
+    const { matched, want, noun, filter, assertion } = args;
+    if (matched === want)
+        return { pass: true, evidence: { matched } };
+    return {
+        pass: false,
+        ...(matched > want ? { decided: true } : {}),
+        failureReason: `expected ${String(want)} ${noun} matching ${filter}, saw ${String(matched)}`,
+        observed: `${String(matched)} matching ${noun}`,
+        expected: `exactly ${String(want)} matching ${filter}`,
+        assertion,
+    };
+}
 /**
  * URL suffixes only the DOCUMENT fetches, which the network observer therefore never records.
  *
@@ -363,26 +392,24 @@ export function evalNet(events, p) {
     // useEffect-double-fire / retry-storm regression class, where the request DID fire (presence passes)
     // but fired the WRONG number of times. Without `count`, the matcher is presence-only (≥1).
     if (p.count !== undefined) {
-        return matches.length === p.count
-            ? { pass: true, evidence: { matched: matches.length } }
-            : 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',
-                };
+        if (matches.length !== p.count &&
+            0 === matches.length &&
+            targetsUnobservedChannel(p) &&
+            !sawSubresources) {
+            return {
+                pass: false,
+                failureReason: unobservedChannelReason(p),
+                inconclusive: unobservedChannelReason(p),
+                assertion: 'net.count',
+            };
+        }
+        return evalExactCount({
+            matched: matches.length,
+            want: p.count,
+            noun: 'network call(s)',
+            filter: describeNetFilter(p),
+            assertion: 'net.count',
+        });
     }
     const hit = matches[0];
     if (hit === undefined && targetsUnobservedChannel(p) && !sawSubresources) {
@@ -527,7 +554,7 @@ export function evalAnimation(events, p) {
         };
 }
 export function evalSignal(events, p) {
-    const hit = events.find((e) => {
+    const isMatch = (e) => {
         if (e.type !== EventType.SIGNAL)
             return false;
         if (p.name !== undefined && str(e.data['name']) !== p.name)
@@ -538,7 +565,22 @@ export function evalSignal(events, p) {
                 return false;
         }
         return true;
-    });
+    };
+    // `count` (exact) turns presence into a cardinality assertion, exactly as it does on `net`. The
+    // double-fire is invisible to every state-only oracle — a handler wired twice leaves the store in
+    // the right shape and fires the signal twice — and so is the wrong-name fire, where the intended
+    // signal fires once beside a mistyped sibling and a presence check cannot say which is which.
+    // Counting only what the MATCHER matched is what separates them. Omit = presence (≥1).
+    if (p.count !== undefined) {
+        return evalExactCount({
+            matched: events.filter(isMatch).length,
+            want: p.count,
+            noun: 'signal(s)',
+            filter: describeSignalFilter(p),
+            assertion: 'signal.count',
+        });
+    }
+    const hit = events.find(isMatch);
     if (hit !== undefined)
         return { pass: true, evidence: hit.data };
     // Near-miss: show signals that fired with the same name (so the agent sees the real data).

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

@@ -14,10 +14,4 @@
  */
 import { z } from 'zod';
 import { PredicateSchema } from './predicate-eval.js';
-/**
- * Parse a predicate, or throw an Error whose message is a sentence.
- *
- * Deliberately still THROWS: every call site already handles a throw, and turning this into a
- * result type would mean touching three handlers to gain nothing the message does not already say.
- */
 export declare function parsePredicate(input: unknown): z.infer<typeof PredicateSchema>;

package/dist/events/predicate-parse.js

@@ -67,7 +67,35 @@ function describeIssue(issue) {
  * Deliberately still THROWS: every call site already handles a throw, and turning this into a
  * result type would mean touching three handlers to gain nothing the message does not already say.
  */
+/**
+ * The placeholder `verify_next` puts in the `until` it suggests, sent back unchanged.
+ *
+ * The nudge hands the agent a ready-made `act_and_wait` call with `ref` and `action` filled in from
+ * the act that dispatched, and leaves the consequence blank on purpose: naming it is the one part
+ * only the agent can know, and guessing would be Reticle inventing the assertion.
+ *
+ * Sent verbatim it parses as a perfectly valid text predicate that simply never matches, so the
+ * verdict came back `verified:"no"` / "the declared consequence did not hold" — blaming the app for
+ * a placeholder the agent forgot to replace, and sending it to hunt a defect that does not exist.
+ * Measured on a live app before this guard: a confident, wrong, actionable-looking answer, which is
+ * the exact failure the rest of this file exists to avoid.
+ */
+const UNFILLED_PLACEHOLDER = /^<name the consequence/i;
+function placeholderValue(input) {
+    if ('object' !== typeof input || null === input)
+        return undefined;
+    const value = input['value'];
+    return 'string' === typeof value && UNFILLED_PLACEHOLDER.test(value) ? value : undefined;
+}
 export function parsePredicate(input) {
+    const unfilled = placeholderValue(input);
+    if (unfilled !== undefined) {
+        throw new Error(`that predicate still carries the placeholder from verify_next ("${unfilled}"). Nothing ran, ` +
+            'and no verdict was produced — which is deliberate: as written it would have failed and ' +
+            'blamed the app for a value you had not filled in yet. Replace it with the consequence ' +
+            'this action actually causes, and prefer one the action CHANGES: a signal, a request, a ' +
+            'route, or store state. Text on screen that was already there proves nothing.');
+    }
     const parsed = PredicateSchema.safeParse(input);
     if (parsed.success)
         return parsed.data;
@@ -78,7 +106,7 @@ export function parsePredicate(input) {
     // back is how the zod array became unreadable in the first place.
     const issues = parsed.error.issues.slice(0, 3).map(describeIssue).join('; ');
     throw new Error(`that predicate did not parse (kind "${kind}"): ${issues}. Nothing ran — the predicate was ` +
-        `not evaluated, so no verdict was produced. ${accepted(kind)} ` +
+        `not evaluated, so no verdict was produced. ${accepted(kind, parsed.error.issues)} ` +
         `A valid ${kind} predicate looks like: ${exampleFor(kind)}`);
 }
 /**
@@ -88,12 +116,24 @@ export function parsePredicate(input) {
  * round trip on the one call path that produces verdicts. Naming the accepted fields — or, when the
  * kind itself is the mistake, the accepted kinds — makes the retry informed instead.
  */
-function accepted(kind) {
+function accepted(kind, issues) {
     const fields = predicateFieldsFor(kind);
     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))
+        //
+        // Only the field the rejection actually points at, though. Expanding every object-valued field
+        // of the kind makes the sentence longer the more the schema grows, and buries the one clause
+        // that answers the question asked — the same argument this file already makes for showing one
+        // example per kind instead of a generic one. `element` is the only kind with an object-valued
+        // field today, so the two agree except when the mistake is somewhere else entirely, which is
+        // the case pinned in the tests.
+        const all = predicateNestedFieldsFor(kind);
+        const blamed = new Set(issues
+            .map((issue) => issue.path[0])
+            .filter((field) => 'string' === typeof field));
+        const nested = Object.entries(all)
+            .filter(([field]) => blamed.has(field))
             .map(([field, keys]) => ` ${field} accepts: ${keys.join(', ')}.`)
             .join('');
         return `${kind} accepts: ${fields.join(', ')}.${nested}`;

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

@@ -56,6 +56,11 @@ export type Predicate = {
     kind: typeof PredicateKind.SIGNAL;
     name?: string;
     dataMatches?: Record<string, unknown>;
+    /**
+     * Exact number of matching signals in the window — the same cardinality assertion `net`
+     * carries, on the channel the app itself speaks. Omit for presence (≥1).
+     */
+    count?: number;
     since?: number;
 } | {
     kind: typeof PredicateKind.STATE;
@@ -103,6 +108,45 @@ 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[];
+/**
+ * Is this tool parameter ACTUALLY the predicate union?
+ *
+ * Not a name check. `until` is overloaded on this surface — the act/assert family means a predicate
+ * by it, while reticle_observe / _network / _console mean a NUMBER, an upper cursor bound — so any
+ * caller keying on the word would treat a numeric parameter as a predicate and describe it to the
+ * agent as an object. Keying on the schema cannot make that mistake.
+ *
+ * Lives beside the schema because two callers now ask the question: the lean tool surface, which
+ * compacts these parameters, and `reticle_tools`, which spells their grammar out on request. Two
+ * spellings of "is this a predicate" is one chance for the surface and the grammar to disagree.
+ */
+export declare function isPredicateParam(schema: z.ZodTypeAny): boolean;
+/**
+ * Every kind's fields, in one block an agent can write a predicate from.
+ *
+ * The tool surface advertises the KIND list and points at `reticle_tools` for the fields, because
+ * inlining the 12-variant recursive union in the declared JSON Schema costs thousands of characters
+ * per predicate parameter, re-sent every turn, to describe a grammar most calls use one variant of.
+ * That trade is right — but the pointer has to land somewhere, and it landed on a parameter
+ * description reading "same shape as reticle_assert". So the grammar was reachable from nothing, and
+ * an agent that could not find `route`'s fields fell back to a `text` check where a route check was
+ * meant: the weaker oracle, which is the expensive half of an undiscoverable grammar.
+ *
+ * Derived from the schema, like `predicateFieldsFor` and for the same reason: a hand-written grammar
+ * that drifts is worse than none, because the agent trusts it and retries into the same wall.
+ */
+export declare function predicateGrammar(): Readonly<Record<string, string>>;
+/**
+ * The keys of a field that is an object, once its wrappers are peeled. Empty for anything else.
+ *
+ * Exported so the wrapper handling is asserted against THIS function rather than through the
+ * rendered sentence. Reached only that way, a wrapper it fails to peel returns `[]`, the old
+ * message prints unchanged, and nothing reddens — a regression with no symptom.
+ *
+ * No top-level predicate field is currently declared behind a wrapper, so the real schema exercises
+ * none of these paths; that is exactly why they are worth a case each.
+ */
+export declare function nestedKeysOf(schema: z.ZodTypeAny | undefined): readonly string[];
 /**
  * One level into the fields that are themselves objects — `{ query: ['by', 'value', ...] }`.
  *