@reticlehq/server 2.10.0 → 2.12.0

package/dist/events/predicate-eval.js

@@ -160,8 +160,140 @@ 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.
+ *
+ * `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 +303,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 +324,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 +356,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,
@@ -235,21 +392,37 @@ 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 } }
-            : {
+        if (matches.length !== p.count &&
+            0 === matches.length &&
+            targetsUnobservedChannel(p) &&
+            !sawSubresources) {
+            return {
                 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)}`,
+                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) {
+        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 +469,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',
         };
 }
@@ -340,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)
@@ -351,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

@@ -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.
  *
@@ -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,9 +116,27 @@ 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)
-        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.
+        //
+        // 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}`;
+    }
     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;
 } | {
@@ -50,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;
@@ -97,3 +108,54 @@ 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', ...] }`.
+ *
+ * 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[]>>;