@reticlehq/server 2.14.0 → 3.2.0

package/dist/events/net-evidence.js

@@ -1,81 +0,0 @@
-/**
- * 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/observed-in-window.d.ts

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

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

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

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

@@ -1,13 +0,0 @@
-/**
- * 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

@@ -1,138 +0,0 @@
-/**
- * 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

@@ -1,13 +0,0 @@
-/**
- * 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

@@ -1,214 +0,0 @@
-/**
- * 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 } } : {}),
-    };
-}