@reticlehq/server 2.13.1 → 2.14.0

package/dist/events/lineage.js

@@ -0,0 +1,122 @@
+/**
+ * Where a runtime value came from: state path ← the signal that preceded it ← the request behind it.
+ *
+ * The prior art this issue names (`firatorhan/sentinel`'s `get_lineage`) builds the same chain by
+ * picking "the most recent action whose payload contains this value", then "an API call whose type
+ * matches". That is CORRELATION, and for a devtool a human reads it is the right trade — the reader
+ * discounts it on sight.
+ *
+ * Reticle's output is read by an agent that acts on it, so the same chain presented as fact is the
+ * false-green shape this project exists to refuse. The join here is deliberately no cleverer than
+ * theirs; what is different is that every link carries how much it is worth:
+ *
+ * - a state path that changed is OBSERVED — we have the event;
+ * - "this signal caused it" is INFERRED, and the wording says so;
+ * - several candidates are NAMED rather than narrowed to the most recent, because choosing is the
+ *   one thing a correlation cannot justify;
+ * - no candidate says the value was not seen to pass through one, and reaches for nothing.
+ *
+ * Read-only. Produces no verdict, is not reachable from an assert path, and changes nothing.
+ */
+import { EventType } from '@reticlehq/core';
+import { asString } from '../tools/tools-helpers.js';
+/**
+ * How far back to look for a cause.
+ *
+ * Wide enough for a fetch → dispatch → render sequence, narrow enough that an unrelated signal a
+ * page-load earlier cannot be offered as a candidate. Not a correctness bound: widening it produces
+ * MORE named candidates, never a wrong single answer, because ambiguity is reported rather than
+ * resolved.
+ */
+const CAUSE_WINDOW_MS = 5_000;
+function stateChangesFor(events, query) {
+    return events.filter((e) => {
+        if (e.type !== EventType.STATE_CHANGE)
+            return false;
+        const path = asString(e.data['path']);
+        if (path === undefined || !path.includes(query.path))
+            return false;
+        if (query.value === undefined)
+            return true;
+        return String(e.data['value']) === query.value;
+    });
+}
+/** Events of one kind inside the causal window before `t`, oldest first. */
+function precursors(events, type, t) {
+    return events.filter((e) => e.type === type && e.t < t && e.t >= t - CAUSE_WINDOW_MS);
+}
+/**
+ * Render an inferred link, hedged according to how many things could explain it.
+ *
+ * The wording IS the deliverable. `← USER_FETCH_SUCCESS` reads as fact; the two forms below read as
+ * what they are, and a reader who skims still sees the hedge because it is in the first few words.
+ */
+function inferredLink(kind, labels) {
+    const one = labels[0] ?? '';
+    if (1 === labels.length) {
+        return { kind, text: `← likely ${one} (inferred from timing, 1 candidate)`, observed: false };
+    }
+    return {
+        kind,
+        text: `← ambiguous: ${String(labels.length)} candidates (${labels.join(', ')}) — not resolved, because timing alone cannot choose between them`,
+        observed: false,
+        candidates: labels,
+    };
+}
+function signalLabel(e) {
+    return asString(e.data['name']) ?? '(unnamed signal)';
+}
+function netLabel(e) {
+    const method = asString(e.data['method']) ?? 'GET';
+    const url = asString(e.data['url']) ?? '(unknown url)';
+    const status = e.data['status'];
+    return `${method} ${url}${'number' === typeof status ? ` (${String(status)})` : ''}`;
+}
+/**
+ * The chain, most recent change first.
+ *
+ * Stops at the first link with nothing to point at, and says why. Walking past a gap would mean
+ * joining across a hole in the evidence, which is exactly the step that turns a correlation into a
+ * claim.
+ */
+export function traceLineage(events, query) {
+    const changes = stateChangesFor(events, query);
+    const latest = changes[changes.length - 1];
+    if (latest === undefined) {
+        return {
+            found: false,
+            chain: [],
+            note: `'${query.path}' was never seen to change in this window, so there is nothing to trace back from. It may be set before Reticle connected, or held somewhere no registered store exposes.`,
+        };
+    }
+    const observedValue = String(latest.data['value']);
+    const chain = [
+        {
+            kind: 'state',
+            text: `${asString(latest.data['path']) ?? query.path} = ${observedValue}  (observed: state change at ${String(latest.t)}ms)`,
+            observed: true,
+        },
+    ];
+    const signals = precursors(events, EventType.SIGNAL, latest.t);
+    if (0 === signals.length) {
+        return {
+            found: true,
+            chain,
+            note: 'No signal fired in the window before this change, so the value was not seen to pass through one. Nothing further is claimed — the change is real, its cause is not in evidence.',
+        };
+    }
+    chain.push(inferredLink('signal', signals.map(signalLabel)));
+    // Anchored on the OLDEST candidate signal: a request that preceded any of them could have produced
+    // it, and narrowing to the newest would quietly discard candidates for the link below.
+    const anchor = signals[0]?.t ?? latest.t;
+    const calls = precursors(events, EventType.NET_REQUEST, anchor);
+    if (0 === calls.length) {
+        return {
+            found: true,
+            chain,
+            note: 'No request preceded that signal in the window, so the chain stops there rather than joining across a gap in the evidence.',
+        };
+    }
+    chain.push(inferredLink('net', calls.map(netLabel)));
+    return { found: true, chain };
+}

package/dist/events/net-evidence.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What a network verdict returns as its PROOF.
+ *
+ * Split out of predicate-eval.ts, which sits at the size backstop, and split HERE because this is a
+ * separate question from "did the predicate hold": that file decides the answer, this one decides
+ * what is shown to justify it. The two failure modes differ too. A wrong verdict is a wrong verdict;
+ * wrong evidence is a verdict nobody can check, or one that costs forty times what it is worth.
+ */
+import { PredicateKind } from '@reticlehq/core';
+import type { Predicate } from './predicate-schema.js';
+/**
+ * The matched call, as the proof of the claim that was actually made.
+ *
+ * A predicate asking about status and url is proved by status and url; returning the whole payload
+ * beside them is cost with no bearing on the verdict. A predicate asking `bodyContains` is proved BY
+ * the body, and that one keeps it in full — clipping a body a check consumed would be weakening the
+ * check to make it cheaper, which is the trade this codebase does not make.
+ */
+export declare function netEvidence(data: Record<string, unknown>, p: Extract<Predicate, {
+    kind: typeof PredicateKind.NET;
+}>): unknown;

package/dist/events/net-evidence.js

@@ -0,0 +1,81 @@
+/**
+ * What a network verdict returns as its PROOF.
+ *
+ * Split out of predicate-eval.ts, which sits at the size backstop, and split HERE because this is a
+ * separate question from "did the predicate hold": that file decides the answer, this one decides
+ * what is shown to justify it. The two failure modes differ too. A wrong verdict is a wrong verdict;
+ * wrong evidence is a verdict nobody can check, or one that costs forty times what it is worth.
+ */
+import { PredicateKind } from '@reticlehq/core';
+import { withoutUrlRaw } from './event-filters.js';
+/**
+ * How much of a body the evidence for a PASS may carry when the check never read it.
+ *
+ * Enough to see the shape of what the server answered — a JSON document's opening keys — and not the
+ * document itself. Measured in the field: six `act_and_wait` calls asserting `{ urlContains, status
+ * 200 }` through one interview each returned the server's whole answer, ~9.6KB of the same document
+ * growing by one slot per step, so almost all of it was a re-send of what the agent already had. The
+ * evidence block was 9,693 of an 11,194-byte result.
+ *
+ * Larger than `MAX_BODY_IN_FAILURE`, and deliberately: a failure quotes the value that DIFFERED and
+ * knows which one that is, while a pass is showing the caller what came back and has no such anchor.
+ */
+const MAX_BODY_IN_EVIDENCE = 512;
+/** Body fields a net predicate can read, and the clause that reads each. */
+const BODY_EVIDENCE_FIELDS = {
+    responseBody: 'bodyContains',
+    requestBody: 'requestBodyContains',
+};
+/**
+ * How much of the body around a matched needle is quoted.
+ *
+ * Enough to see the needle in its structure — the key it sits under, the value beside it — without
+ * the document it came from.
+ */
+const BODY_MATCH_CONTEXT = 120;
+/** Where a quoted window starts, and the elision markers that keep it honest at both ends. */
+function windowAround(body, at, needle) {
+    const from = Math.max(0, at - BODY_MATCH_CONTEXT);
+    const to = Math.min(body.length, at + needle.length + BODY_MATCH_CONTEXT);
+    return `${from > 0 ? '…' : ''}${body.slice(from, to)}${to < body.length ? '…' : ''}`;
+}
+/** The head of a body, for a claim that never read it. Elision is VISIBLE — see the note below. */
+function headOf(body) {
+    return body.length <= MAX_BODY_IN_EVIDENCE ? body : `${body.slice(0, MAX_BODY_IN_EVIDENCE)}…`;
+}
+/**
+ * The matched call, as the proof of the claim that was actually made.
+ *
+ * A predicate asking about status and url is proved by status and url; returning the whole payload
+ * beside them is cost with no bearing on the verdict. A predicate asking `bodyContains` is proved BY
+ * the body, and that one keeps it in full — clipping a body a check consumed would be weakening the
+ * check to make it cheaper, which is the trade this codebase does not make.
+ */
+export function netEvidence(data, p) {
+    const stripped = withoutUrlRaw({ data }).data;
+    if (null === stripped || 'object' !== typeof stripped)
+        return stripped;
+    const clause = p;
+    const out = { ...stripped };
+    for (const [field, askedBy] of Object.entries(BODY_EVIDENCE_FIELDS)) {
+        const body = out[field];
+        if ('string' !== typeof body || body.length <= MAX_BODY_IN_EVIDENCE)
+            continue;
+        const needle = clause[askedBy];
+        const at = 'string' === typeof needle ? body.indexOf(needle) : -1;
+        if (at < 0) {
+            // No clause read this body, or the pass came from elsewhere: the head shows the shape of the
+            // answer. The ellipsis is load-bearing — a silently shortened body reads as "the server
+            // answered this much", a different and wrong fact — and `responseSize` rides alongside
+            // untouched, so the real length stays available and `reticle_network` fetches the rest.
+            out[field] = headOf(body);
+            continue;
+        }
+        // The clause matched. What proves it is the MATCH, not the document it was found in: the needle
+        // in its context, plus where it was. Six field verdicts each returned the same 8KB interview
+        // document to prove one substring of it, and the document proved nothing the window does not.
+        out[field] = windowAround(body, at, needle);
+        out['bodyMatchAt'] = at;
+    }
+    return out;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Console predicates: the assertion agents lean on hardest, and the one with a structural blind spot.
+ *
+ * Split out of `predicate-eval.ts` when it crossed the file cap. Cohesive on its own terms — the
+ * level map, the channel-liveness gate, and the absent/present branches are one subject, and nothing
+ * else in the evaluator reads a CONSOLE_* event.
+ */
+import { PredicateKind, type ReticleEvent } from '@reticlehq/core';
+import type { EvalResult } from './predicate-eval.js';
+import type { Predicate } from './predicate-schema.js';
+export declare function evalConsole(events: ReticleEvent[], p: Extract<Predicate, {
+    kind: typeof PredicateKind.CONSOLE;
+}>): EvalResult;

package/dist/events/predicate-console.js

@@ -0,0 +1,138 @@
+/**
+ * Console predicates: the assertion agents lean on hardest, and the one with a structural blind spot.
+ *
+ * Split out of `predicate-eval.ts` when it crossed the file cap. Cohesive on its own terms — the
+ * level map, the channel-liveness gate, and the absent/present branches are one subject, and nothing
+ * else in the evaluator reads a CONSOLE_* event.
+ */
+import { CONSOLE_ATTACH_NOTE, EventType, PredicateKind } from '@reticlehq/core';
+/** The only console levels Reticle instruments (console.info/debug/trace are NOT patched). */
+const CONSOLE_LEVEL_TYPE = {
+    log: EventType.CONSOLE_LOG,
+    warn: EventType.CONSOLE_WARN,
+    error: EventType.CONSOLE_ERROR,
+};
+/**
+ * Has the console channel reported ANYTHING in this window, at any level?
+ *
+ * Liveness, on the same argument `observerSawSubresources` makes for resource timing: one entry
+ * anywhere proves the channel reaches this document, so the caller is not looking at a dead read.
+ * Any level counts — a `console.log` proves the patch is in place just as well as an error would,
+ * and asking only about the ASSERTED level would re-fire the caveat on every quiet window of a
+ * chatty page, which is a toll paid where the warning is not true.
+ *
+ * It does not CLOSE the blind stretch — that is about time before attach and cannot be closed from
+ * this side. It only rules out the reading the caveat's wording would get wrong.
+ */
+function channelReported(events, since) {
+    return events.some((e) => e.t >= since &&
+        (e.type === EventType.CONSOLE_LOG ||
+            e.type === EventType.CONSOLE_WARN ||
+            e.type === EventType.CONSOLE_ERROR ||
+            e.type === EventType.CONSOLE_INFO ||
+            e.type === EventType.CONSOLE_DEBUG ||
+            e.type === EventType.ERROR_UNCAUGHT));
+}
+export function evalConsole(events, p) {
+    const since = p.since ?? 0;
+    // Reticle only instruments console.log/warn/error. A level outside that set is never captured,
+    // so its events can't exist — and an `absent` assertion on it would verify NOTHING while
+    // reporting green. Fail loudly instead of false-passing.
+    if (p.level !== undefined && p.level !== 'error' && CONSOLE_LEVEL_TYPE[p.level] === undefined) {
+        return {
+            pass: false,
+            failureReason: `console level '${p.level}' is not captured — Reticle instruments console.log, console.warn, console.error only`,
+            observed: `level '${p.level}' is not instrumented, so no event of it can ever exist`,
+            expected: 'a level Reticle captures: log, warn, or error',
+            assertion: 'console.uninstrumented-level',
+        };
+    }
+    const matches = events.filter((e) => {
+        if (e.t < since)
+            return false;
+        const isErr = e.type === EventType.CONSOLE_ERROR || e.type === EventType.ERROR_UNCAUGHT;
+        if (p.level === undefined) {
+            return (e.type === EventType.CONSOLE_LOG ||
+                e.type === EventType.CONSOLE_WARN ||
+                e.type === EventType.CONSOLE_ERROR ||
+                e.type === EventType.ERROR_UNCAUGHT);
+        }
+        if ('error' === p.level)
+            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) {
+        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,
+                    // Only when the window starts at attach AND nothing came through at all. An entry
+                    // anywhere in the window proves the channel reaches this document, which is the case
+                    // the caveat's wording would misdescribe; a window an action opened has `since > 0` and
+                    // was fully observed. Costs nothing on every other pass, which is most of them.
+                    ...(0 === since && !channelReported(events, since)
+                        ? { unobservedBefore: CONSOLE_ATTACH_NOTE }
+                        : {}),
+                },
+            }
+            : {
+                pass: false,
+                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 matching.length > 0
+        ? { pass: true, evidence: matching.map((e) => e.data) }
+        : {
+            pass: false,
+            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-element.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Element and text predicates: everything that resolves a locator against the live DOM.
+ *
+ * Split out of `predicate.ts` when it crossed the file cap. It is a cohesive unit on its own terms —
+ * one round-trip protocol (`matchOnce`), the fields the browser locator drops and this side enforces
+ * back (`residualQueryChecks`), the absent/present asymmetry, and the near-miss diagnostics that only
+ * ever enrich a failure. Nothing else in the predicate layer talks to `ReticleCommand.MATCH`.
+ */
+import { type ElementQuery, type ElementState, type MatchResult } from '@reticlehq/core';
+import { type EvalResult } from './predicate-eval.js';
+import type { PredicateSession } from './predicate.js';
+export declare function matchOnce(session: PredicateSession, query: ElementQuery, state: ElementState | undefined): Promise<MatchResult>;
+export declare function evalElement(session: PredicateSession, query: ElementQuery, state: ElementState | undefined, absent: boolean, diagnose: boolean): Promise<EvalResult>;

package/dist/events/predicate-element.js

@@ -0,0 +1,214 @@
+/**
+ * Element and text predicates: everything that resolves a locator against the live DOM.
+ *
+ * Split out of `predicate.ts` when it crossed the file cap. It is a cohesive unit on its own terms —
+ * one round-trip protocol (`matchOnce`), the fields the browser locator drops and this side enforces
+ * back (`residualQueryChecks`), the absent/present asymmetry, and the near-miss diagnostics that only
+ * ever enrich a failure. Nothing else in the predicate layer talks to `ReticleCommand.MATCH`.
+ */
+import { ReticleCommand, } from '@reticlehq/core';
+import { residualQueryChecks, satisfiesResiduals, describeResidual, } from './predicate-eval.js';
+import { describeTestidMiss } from './testid-near-miss.js';
+import { describeSplitTextMiss } from './split-text-miss.js';
+export async function matchOnce(session, query, state) {
+    const res = await session.command(ReticleCommand.MATCH, { query, state });
+    if (!res.ok)
+        return { matched: false, count: 0, elements: [] };
+    return (res.result ?? { matched: false, count: 0, elements: [] });
+}
+/**
+ * Roles that exist to ANNOUNCE something. An empty one is the container, not the message.
+ *
+ * Every toast and notification library mounts its live region at boot and never removes it, so a
+ * bare `{ role: "alert" }` presence check is satisfied on those apps with nothing on screen — it
+ * cannot fail, and a predicate that cannot fail is not a check. Restricted to these roles because
+ * they are the ones whose whole purpose is content: an unnamed `img`, `separator` or `progressbar`
+ * is an ordinary thing to assert the presence of, and is left alone.
+ */
+const ANNOUNCEMENT_ROLES = new Set([
+    'alert',
+    'alertdialog',
+    'status',
+    'log',
+    'marquee',
+    'timer',
+]);
+/**
+ * The matches that actually carry content, for a query that named none of its own.
+ *
+ * A `name`, `text` or `testid` in the query is already a specific claim and is never second-guessed
+ * here — this only fills the gap left by a query that asked for a role and nothing else.
+ */
+function substantiveMatches(query, elements) {
+    const bareRole = query.role !== undefined &&
+        query.name === undefined &&
+        query.text === undefined &&
+        query.testid === undefined;
+    if (!bareRole || !ANNOUNCEMENT_ROLES.has(query.role ?? ''))
+        return elements;
+    // Nothing described, nothing to judge. `elements` is only the described PREFIX of a match — the
+    // browser truncates it, and it can be empty while `count` is not. Calling that hollow would turn a
+    // truncation into a verdict, so an unjudgeable set keeps the old answer.
+    if (0 === elements.length)
+        return elements;
+    return elements.filter((e) => e.name.length > 0 || (e.text ?? '').trim().length > 0);
+}
+export async function evalElement(session, query, state, absent, diagnose) {
+    // Fields the browser's locator would have DROPPED, enforced back here — see residualQueryChecks.
+    // Checked before the round-trip when nothing can enforce them: a predicate that cannot be evaluated
+    // must say so rather than resolve to whatever the surviving half of it happened to match.
+    const residual = residualQueryChecks(query);
+    if (residual.unusable.length > 0) {
+        const reason = `the element locator ignores ${residual.unusable.map((f) => `\`${f}\``).join(', ')} ` +
+            `in ${JSON.stringify(query)} — it resolves by the first of by+value, component/source, role, ` +
+            'text, label, placeholder, testid, alt that is present, and nothing here can check the rest. ' +
+            'Assert them one locator at a time, or move the extra field into the locator';
+        return { pass: false, failureReason: reason, inconclusive: reason };
+    }
+    let match = await matchOnce(session, query, state);
+    const subject = JSON.stringify(query);
+    // A residual narrows the SET; `count` is every match while `elements` is only the described prefix,
+    // so a locator broad enough to be truncated cannot be narrowed honestly. Say so instead of guessing.
+    if (residual.checks.length > 0 && match.count > match.elements.length) {
+        const reason = `${String(match.count)} elements matched ${subject} and only ${String(match.elements.length)} were described, so ${residual.checks.map(([f]) => `\`${f}\``).join(', ')} could not be checked against all of them — narrow the locator`;
+        return { pass: false, failureReason: reason, inconclusive: reason };
+    }
+    const kept = match.elements.filter((element) => satisfiesResiduals(element, residual.checks));
+    // The locator found something and the dropped fields disagree with it. Reported separately from a
+    // plain miss because the fixes are opposite: the element IS there, its value is not what was claimed.
+    if (residual.checks.length > 0 && match.matched && 0 === kept.length && !absent) {
+        const wanted = residual.checks.map(([f, want]) => `${f}=${JSON.stringify(want)}`).join(', ');
+        return {
+            pass: false,
+            failureReason: `element matching ${subject} is present but ${wanted} does not hold`,
+            observed: match.elements
+                .map((element) => residual.checks.map(([f]) => describeResidual(element, f)).join(', '))
+                .join('; '),
+            expected: `an element matching ${subject} with ${wanted}`,
+            assertion: `element.${residual.checks[0]?.[0] ?? 'residual'}`,
+            evidence: match.elements,
+        };
+    }
+    if (residual.checks.length > 0) {
+        match = { ...match, matched: kept.length > 0, count: kept.length, elements: kept };
+    }
+    // A given-but-missing scope is handled ASYMMETRICALLY, because "absent" and "present" ask different
+    // questions of a scope that no longer exists:
+    //  - ABSENT: an element is trivially absent from a container that isn't there. This is also the
+    //    everyday "wait for the #overlay/#spinner/#modal to disappear" pattern (scope the wait to the
+    //    node being removed) — treating scopeMissing as a hard fail there burned the whole timeout and
+    //    flipped a correct green to red. So scopeMissing satisfies an absence check.
+    //  - PRESENT: you cannot confirm an element is present inside a scope that resolved to nothing, and
+    //    silently widening to the whole page is the original false green. So scopeMissing FAILS presence
+    //    (on the wait_for path this just keeps polling until the scope appears).
+    if (absent) {
+        if (true === match.scopeMissing) {
+            return { pass: true, evidence: { absent: true, scopeMissing: true } };
+        }
+        return match.matched
+            ? {
+                pass: false,
+                failureReason: `expected element to be absent but found ${String(match.count)}`,
+                observed: `${String(match.count)} element(s) matching ${subject}`,
+                expected: `no element matching ${subject}`,
+                assertion: 'element.absent',
+                evidence: match.elements,
+            }
+            : { pass: true, evidence: { absent: true } };
+    }
+    if (true === match.scopeMissing) {
+        return {
+            pass: false,
+            failureReason: `scope resolved to no element — cannot confirm ${subject} is present`,
+            observed: 'the requested scope is not on the page (unmounted or selector matched nothing)',
+            expected: `an element matching ${subject} within an existing scope`,
+            assertion: 'element.present',
+            evidence: { scopeMissing: true },
+        };
+    }
+    const announced = substantiveMatches(query, match.elements);
+    if (match.matched && (announced.length > 0 || 0 === match.elements.length)) {
+        return { pass: true, evidence: announced };
+    }
+    // Matched, but every match was a mounted-and-empty live region. Reported as its own failure rather
+    // than the plain miss below, because the fixes are opposite: the container IS on the page, so
+    // "no element matched" would send the caller looking for a render that already happened.
+    if (match.matched) {
+        return {
+            pass: false,
+            failureReason: `${String(match.count)} element(s) matched ${subject}, and every one is empty — ` +
+                'a live region mounted with no name and no text has announced nothing. Assert the ' +
+                'message itself (a `name` or `text` in the query) rather than the container',
+            observed: `${String(match.count)} empty '${query.role ?? ''}' region(s) with no name or text`,
+            expected: `a '${query.role ?? ''}' carrying a name or rendered text`,
+            assertion: 'element.announced',
+            evidence: match.elements,
+        };
+    }
+    // The near-miss diagnostic below costs one or two EXTRA MATCH round-trips. It only enriches a FAILED
+    // verdict, and a wait loop's interim rechecks read nothing but `pass` — so on the poll path (diagnose
+    // false) skip straight to the plain fail. Under an event flood a role+name element wait was firing
+    // two live-DOM scans per recheck for a diagnostic no interim eval ever reads; the final timeout eval
+    // still runs with diagnose=true and produces the full near-miss.
+    if (!diagnose) {
+        return {
+            pass: false,
+            failureReason: `no element matched ${subject}${state === undefined ? '' : ` in state '${state}'`}`,
+            observed: 'no matching element on the page',
+            expected: `an element matching ${subject}${state === undefined ? '' : ` in state '${state}'`}`,
+            assertion: 'element.present',
+        };
+    }
+    // Diagnostic near-miss: was it there but in the wrong state, or a similar element present?
+    if (state !== undefined) {
+        const relaxed = await matchOnce(session, query, undefined);
+        if (relaxed.matched) {
+            return {
+                pass: false,
+                failureReason: `element exists but not in state '${state}'`,
+                observed: `element matching ${subject} is present, states: ${relaxed.elements[0]?.states.join(', ') ?? 'unknown'}`,
+                expected: `element matching ${subject} in state '${state}'`,
+                assertion: 'element.state',
+                evidence: { nearMiss: relaxed.elements },
+            };
+        }
+    }
+    if (query.role !== undefined && query.name !== undefined) {
+        const roleOnly = await matchOnce(session, { role: query.role }, state);
+        if (roleOnly.matched) {
+            return {
+                pass: false,
+                failureReason: `no '${query.role}' named '${query.name}'; saw: ${roleOnly.elements
+                    .map((e) => e.name)
+                    .filter((n) => n.length > 0)
+                    .join(', ')}`,
+                observed: `${String(roleOnly.count)} '${query.role}' element(s), named: ${roleOnly.elements
+                    .map((e) => e.name)
+                    .filter((n) => n.length > 0)
+                    .join(', ')}`,
+                expected: `a '${query.role}' named '${query.name}'`,
+                assertion: 'element.role+name',
+                evidence: { nearMiss: roleOnly.elements },
+            };
+        }
+    }
+    // The testid near-miss: name what IS here, so a typo is one step from fixed rather than a dead
+    // end. reticle_query has always done this; the predicate path had no equivalent. See
+    // testid-near-miss.ts.
+    const present = match.hint?.presentTestids ?? [];
+    const alsoHere = query.testid === undefined ? undefined : describeTestidMiss(query.testid, present);
+    // A text miss where the string is on the page but split across children reads exactly like an
+    // element that never rendered. Naming the container is the difference between a retry and a bug
+    // report against working code. See split-text-miss.ts.
+    const splitText = describeSplitTextMiss(match.hint?.splitText, query.text);
+    const clause = splitText ?? (alsoHere === undefined || '' === alsoHere ? undefined : alsoHere);
+    const suffix = clause === undefined ? '' : ` — ${clause}`;
+    return {
+        pass: false,
+        failureReason: `no element matched ${subject}${state === undefined ? '' : ` in state '${state}'`}${suffix}`,
+        observed: `no matching element on the page${suffix}`,
+        expected: `an element matching ${subject}${state === undefined ? '' : ` in state '${state}'`}`,
+        assertion: 'element.present',
+        ...(present.length > 0 ? { evidence: { presentTestids: present } } : {}),
+    };
+}

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

@@ -1,4 +1,5 @@
 import { PredicateKind, type ReticleEvent } from '@reticlehq/core';
+export { evalConsole } from './predicate-console.js';
 import type { Predicate } from './predicate-schema.js';
 export * from './predicate-schema.js';
 export interface EvalResult {
@@ -66,12 +67,23 @@ export declare function str(value: unknown): string | undefined;
  * `{$gte,$lte,$gt,$lt}` (numbers), `{$contains}` (array membership or substring), `{$length}`.
  */
 export declare function matchValue(got: unknown, want: unknown): boolean;
+/** Shallow JSON pattern match: each key in `pattern` must match (see matchValue). */
+export declare function dataMatches(actual: Record<string, unknown>, pattern: Record<string, unknown>): boolean;
+/** Enough of a body to see what differed, without paying for a whole payload in the verdict. */
+export declare function clipBody(body: string): string;
+/**
+ * The filter as APPLIED, every field of it.
+ *
+ * The count failure used to print `{method, urlContains, status}` while `ok` and `bodyContains` were
+ * applied too, so the caller was shown a predicate it had not written and told nothing matched it.
+ * A printed filter that is narrower than the real one is worse than none: it is believed.
+ */
+export declare function describeNetFilter(p: Extract<Predicate, {
+    kind: typeof PredicateKind.NET;
+}>): string;
 export declare function evalNet(events: ReticleEvent[], p: Extract<Predicate, {
     kind: typeof PredicateKind.NET;
 }>): EvalResult;
-export declare function evalConsole(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: typeof PredicateKind.CONSOLE;
-}>): EvalResult;
 export declare function evalAnimation(events: ReticleEvent[], p: Extract<Predicate, {
     kind: typeof PredicateKind.ANIMATION;
 }>): EvalResult;