@reticlehq/server 2.4.0 → 2.6.0

package/dist/flows/replay.js

@@ -1,5 +1,7 @@
 import { DANGEROUS_ACTION_CONFIRM_ARG, ReticleCommand, QueryBy, } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
+import { predicateToExpect, enforcedOnReplay } from './predicate-to-expect.js';
+import { PredicateSchema } from '../events/predicate.js';
 import { asString, asRecord } from '../tools/tools-helpers.js';
 /**
  * The note attached when a testid resolves to multiple live elements (the first match is used).
@@ -35,10 +37,38 @@ function sourceFromResult(res) {
     if (typeof source['file'] !== 'string' || typeof source['line'] !== 'number')
         return undefined;
     const out = { file: source['file'], line: source['line'] };
-    if (typeof source['column'] === 'number')
+    if ('number' === typeof source['column'])
         out['column'] = source['column'];
     return out;
 }
+/**
+ * Capture an act into every in-flight recording, or do nothing when none is running.
+ *
+ * Every tool that drives the page must call this. reticle_act_and_wait did not, which is the tool
+ * the documented agent recipe drives with — so "record start -> drive -> record stop -> flow_save"
+ * saved a flow with zero steps.
+ */
+export function captureAct(recordings, args, res) {
+    if (0 === recordings.active().length)
+        return;
+    const step = compileActStep(args, res);
+    // Keep the assertion the agent actually made. `act_and_wait { until }` IS the agent saying what
+    // success means — 12 of 14 calls in a day carried one — and dropping it produced a flow graded
+    // "assertion-free: it will pass even if the feature is broken", which is the regression-suite
+    // story failing at its last step. Only kinds FlowExpect can express survive; see
+    // predicate-to-expect.ts.
+    const until = args['until'] ?? args['predicate'];
+    if (until !== undefined) {
+        const parsed = PredicateSchema.safeParse(until);
+        // Only what a replay actually CHECKS — recording an unenforced assertion would grade the flow
+        // "asserted" while nothing verifies it, which is a false green in the feature built to prevent
+        // them. See enforcedOnReplay.
+        const expect = parsed.success ? enforcedOnReplay(predicateToExpect(parsed.data)) : undefined;
+        if (expect !== undefined)
+            step.expect = expect;
+    }
+    recordings.capture(step);
+}
 /**
  * Compile a single reticle_act invocation into a normalized RecordedStep using the action result. Anchor
  * priority mirrors synthesizeAnchor: a data-testid is the gold standard; failing that, the element's
@@ -46,10 +76,20 @@ function sourceFromResult(res) {
  * a volatile ref. Only when neither is available is the step ref-bound (in-session only).
  */
 export function compileActStep(args, res) {
-    const r = asRecord(res);
+    const { args: compiled, stable } = compileAnchorArgs(asRecord(res), asString(args['ref']) ?? '', asString(args['action']) ?? '', replayActionArgs(args['args']));
+    return { tool: ReticleTool.ACT, stable, args: compiled };
+}
+/**
+ * The ONE anchor chooser: testid (gold) > role+name (identifies an instance) > component/source
+ * (the JSX site) > a volatile ref (in-session only).
+ *
+ * It is shared because it was not: `compileSequenceStep` understood only a testid, so every
+ * act_sequence sub-step on a testid-less app compiled to a ref, saved as the degraded `unresolved`
+ * sentinel, and drifted on every replay — while a single act on the very same element compiled a
+ * perfectly stable anchor.
+ */
+function compileAnchorArgs(r, ref, action, actArgs) {
     const testid = asString(r['testid']);
-    const action = asString(args['action']) ?? '';
-    const actArgs = replayActionArgs(args['args']);
     const source = sourceFromResult(r);
     if (testid !== undefined) {
         // The testid anchors the step; source rides along purely so a failure can name a file. Carrying
@@ -62,7 +102,7 @@ export function compileActStep(args, res) {
         };
         if (source !== undefined)
             testidArgs['source'] = source;
-        return { tool: ReticleTool.ACT, stable: true, args: testidArgs };
+        return { args: testidArgs, stable: true };
     }
     // Role + NAME before component: a component/source anchor names the JSX site, so every row's copy
     // of the same control collapses onto it. The accessible name separates them, and it is also the
@@ -80,7 +120,7 @@ export function compileActStep(args, res) {
         };
         if (source !== undefined)
             roleArgs['source'] = source;
-        return { tool: ReticleTool.ACT, stable: true, args: roleArgs };
+        return { args: roleArgs, stable: true };
     }
     const component = asString(r['component']);
     if (component !== undefined || source !== undefined) {
@@ -89,15 +129,15 @@ export function compileActStep(args, res) {
             componentArgs['component'] = component;
         if (source !== undefined)
             componentArgs['source'] = source;
-        return { tool: ReticleTool.ACT, stable: true, args: componentArgs };
+        return { args: componentArgs, stable: true };
     }
-    return {
-        tool: ReticleTool.ACT,
-        stable: false,
-        args: { ref: asString(args['ref']) ?? '', action, args: actArgs },
-    };
+    return { args: { ref, action, args: actArgs }, stable: false };
 }
-/** Compile an reticle_act_sequence invocation, normalizing each sub-step to its testid where resolvable. */
+/**
+ * Compile an reticle_act_sequence invocation, normalizing each sub-step through the SAME anchor
+ * priority a single act uses (see compileAnchorArgs) — not testid-or-nothing, which is what made
+ * every sequence unreplayable on an app without testids.
+ */
 export function compileSequenceStep(args, res) {
     const inputSteps = Array.isArray(args['steps']) ? args['steps'] : [];
     const resolved = Array.isArray(asRecord(res)['steps'])
@@ -106,14 +146,10 @@ export function compileSequenceStep(args, res) {
     let stable = inputSteps.length > 0;
     const subSteps = inputSteps.map((raw, i) => {
         const step = asRecord(raw);
-        const action = asString(step['action']) ?? '';
-        const stepArgs = replayActionArgs(step['args']);
-        const testid = asString(asRecord(resolved[i])['testid']);
-        if (testid !== undefined) {
-            return { by: QueryBy.TESTID, value: testid, action, args: stepArgs };
-        }
-        stable = false;
-        return { ref: asString(step['ref']) ?? '', action, args: stepArgs };
+        const compiled = compileAnchorArgs(asRecord(resolved[i]), asString(step['ref']) ?? '', asString(step['action']) ?? '', replayActionArgs(step['args']));
+        if (!compiled.stable)
+            stable = false;
+        return compiled.args;
     });
     return { tool: ReticleTool.ACT_SEQUENCE, stable, args: { steps: subSteps } };
 }
@@ -181,7 +217,7 @@ async function resolveRef(session, step) {
             : { ref };
     }
     const ref = asString(step.ref);
-    if (ref === undefined || ref.length === 0) {
+    if (ref === undefined || 0 === ref.length) {
         throw new Error('step has no resolvable anchor (testid, role+name, component) and no ref');
     }
     return { ref, note: 'replayed by stale ref (not portable across sessions)' };

package/dist/flows/role-anchor-nearest.d.ts

@@ -0,0 +1,6 @@
+/** Present controls, as role + accessible name. */
+export interface RoleCandidate {
+    role: string;
+    name: string;
+}
+export declare function nearestRoleName(role: string, missing: string, present: readonly RoleCandidate[]): string | null;

package/dist/flows/role-anchor-nearest.js

@@ -0,0 +1,45 @@
+/**
+ * The closest surviving control to a role+name anchor that no longer resolves.
+ *
+ * `runRoleStep` returned `nearest: null` as a literal, so `flow_heal` answered "no nearest match
+ * cleared the confidence floor" for every role-anchored drift — which reads as a judgement about
+ * candidates when in fact nothing had looked. Reported from a real sweep: a three-step flow failed
+ * on `button named 'Menu' did not resolve` and heal called it unhealable, however small the change.
+ *
+ * What this does NOT do is make role anchors auto-healable, and that restraint is the point. A
+ * testid is an identifier a developer put there deliberately; a role name is user-visible text where
+ * "Save" and "Save as" are one edit apart. Silently rebinding a step to a similar-looking control is
+ * precisely the wrong-element green this product exists to catch. So the bar here is deliberately
+ * higher than the testid path's: same role, unambiguous, and genuinely close — otherwise null, and
+ * the agent is told to add a testid.
+ */
+import { editDistance } from './flow-replay.js';
+/**
+ * A name must be at least this similar to be worth showing: at most a third of it changed. A looser
+ * bar turns "no candidate" into "a confident wrong one", which is worse than saying nothing.
+ */
+const MAX_CHANGED_FRACTION = 1 / 3;
+export function nearestRoleName(role, missing, present) {
+    const sameRole = present.filter((candidate) => candidate.role === role);
+    if (0 === sameRole.length)
+        return null;
+    const budget = Math.floor(missing.length * MAX_CHANGED_FRACTION);
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    let tied = false;
+    for (const candidate of sameRole) {
+        const distance = editDistance(missing, candidate.name);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate.name;
+            tied = false;
+        }
+        else if (distance === bestDistance) {
+            tied = true;
+        }
+    }
+    // A tie is a coin flip between two live controls; naming one would be inventing confidence.
+    if (null === best || tied || bestDistance > budget)
+        return null;
+    return best;
+}

package/dist/flows/role-drift-reason.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What to say when a role+name anchor no longer resolves.
+ *
+ * The old message could contradict itself in the one case that matters most:
+ *
+ *   role anchor button "Add User" not found; the closest surviving button is "Add User"
+ *
+ * Read literally that says the control both is and is not there, and it cost a reporter real
+ * debugging time. What it means is more useful than a rename: the stored name and the live
+ * accessible name are the SAME STRING, so the name is not what changed — the query matched nothing
+ * for some other reason.
+ *
+ * In the reported case the recorded name came from a `placeholder` — `reticle_query` reports
+ * `name:"Search User"` for `<input type="search" placeholder="Search User">` with no label — and the
+ * replay resolver computes accessible names differently, so the round trip cannot close. That is a
+ * real bug in its own right (two accessible-name implementations disagreeing), and while it is open
+ * the message is the only thing the reader has, because `flow_heal` correctly refuses to rebind a
+ * role anchor on its own.
+ */
+export declare function roleDriftReason(role: string, name: string, nearest: string | null): string;

package/dist/flows/role-drift-reason.js

@@ -0,0 +1,39 @@
+/**
+ * What to say when a role+name anchor no longer resolves.
+ *
+ * The old message could contradict itself in the one case that matters most:
+ *
+ *   role anchor button "Add User" not found; the closest surviving button is "Add User"
+ *
+ * Read literally that says the control both is and is not there, and it cost a reporter real
+ * debugging time. What it means is more useful than a rename: the stored name and the live
+ * accessible name are the SAME STRING, so the name is not what changed — the query matched nothing
+ * for some other reason.
+ *
+ * In the reported case the recorded name came from a `placeholder` — `reticle_query` reports
+ * `name:"Search User"` for `<input type="search" placeholder="Search User">` with no label — and the
+ * replay resolver computes accessible names differently, so the round trip cannot close. That is a
+ * real bug in its own right (two accessible-name implementations disagreeing), and while it is open
+ * the message is the only thing the reader has, because `flow_heal` correctly refuses to rebind a
+ * role anchor on its own.
+ */
+/** Same name to a reader: case and surrounding whitespace are not a rename. */
+function sameName(a, b) {
+    return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+export function roleDriftReason(role, name, nearest) {
+    const label = `${role} "${name}"`;
+    if (null === nearest) {
+        return (`role anchor ${label} not found, and no surviving ${role} has a similar name — ` +
+            'anchor this step to a data-testid');
+    }
+    if (sameName(name, nearest)) {
+        // The one case the old wording made unreadable. Say what is ruled OUT — that is the information.
+        return (`role anchor ${label} did not resolve, but a ${role} with an identical name is on the page — ` +
+            'so this is NOT a rename and editing the label will not fix it. The recorded name and the ' +
+            'name the resolver computes disagree, which happens when the recorded one came from a ' +
+            'placeholder or title rather than a label or aria-label. Anchor this step to a data-testid.');
+    }
+    return (`role anchor ${label} not found; the closest surviving ${role} is "${nearest}" — ` +
+        'confirm it is the same control before rebinding, or add a data-testid');
+}

package/dist/flows/server-verify.d.ts

@@ -7,7 +7,7 @@
  */
 import type { SuiteVerdict } from '@reticlehq/core';
 import type { ToolDeps } from '../tools/tools.js';
-import { type ProjectCloud } from './../cloud/cloud-config.js';
+import { type ProjectCloud } from '../cloud/cloud-config.js';
 import { type ServerVerification } from '../cloud/cloud-sync.js';
 /** Map the hosted runner's report onto the local suite-verdict shape (status/total/passed/failed/failures). */
 export declare function toSuiteVerdict(report: ServerVerification): SuiteVerdict;

package/dist/flows/server-verify.js

@@ -1,4 +1,4 @@
-import { VerifyMode } from './../cloud/cloud-config.js';
+import { VerifyMode } from '../cloud/cloud-config.js';
 import { submitServerVerification } from '../cloud/cloud-sync.js';
 const PASS = 'pass';
 const UNVERIFIED = 'unverified';
@@ -14,12 +14,12 @@ export function toSuiteVerdict(report) {
     }));
     const total = report.flows.length;
     const passed = total - failures.length;
-    const status = report.verdict === PASS && failures.length === 0 ? 'pass' : 'fail';
+    const status = report.verdict === PASS && 0 === failures.length ? 'pass' : 'fail';
     return { status, total, passed, failed: failures.length, summary: report.summary, failures };
 }
 /** Run the suite on the hosted runner, or null to signal the caller should replay locally. */
 export async function runServerVerify(deps, cloud, sessionId, flows) {
-    if (cloud.verify !== VerifyMode.SERVER || cloud.config === null)
+    if (cloud.verify !== VerifyMode.SERVER || null === cloud.config)
         return null;
     let previewUrl;
     try {
@@ -29,10 +29,10 @@ export async function runServerVerify(deps, cloud, sessionId, flows) {
         previewUrl = undefined;
     }
     // The server hits the URL itself; with no URL (or a localhost one it can't reach) fall back to local.
-    if (previewUrl === undefined || previewUrl.length === 0)
+    if (previewUrl === undefined || 0 === previewUrl.length)
         return null;
     const report = await submitServerVerification({ previewUrl, flows, source: SOURCE }, cloud.config, (url, init) => fetch(url, init));
-    if (report === null)
+    if (null === report)
         return null;
     // The hosted runner said it couldn't actually verify (e.g. it's not enabled yet). Never surface that as
     // a pass or a fail — fall back to the real local replay so the verdict reflects a browser that ran.

package/dist/flows/suite-flakes.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Accrue a suite run's outcomes into the flake ledger, and report what the ledger knows.
+ *
+ * This existed twice — once in `flow_verify`'s sequential branch and once, after #240, in its
+ * parallel branch. That duplication is not incidental: the parallel branch shipped WITHOUT it, so an
+ * agent verifying in parallel built no flake evidence at all and never saw the quarantine set, and
+ * nothing went red because the other copy was still correct. One function both branches call is what
+ * makes that miss impossible on one side only.
+ *
+ * It is also what makes the behaviour testable. The handler itself needs a live browser session, so
+ * both branches were only ever pinned by tests that RE-IMPLEMENTED this loop — which passed with the
+ * shipped code reverted (measured on #240: 4/4 green with the fix absent). Extracted, the real thing
+ * runs in a unit test.
+ *
+ * Best-effort on both halves, deliberately: a flake ledger is memory, not a gate. A full disk must
+ * never turn a working verification into an error.
+ */
+import { ReplayStatus } from '@reticlehq/core';
+import type { FileSystemPort } from '../project/fs-port.js';
+/** Just the shape this needs from a replay — so a test does not have to build a whole result. */
+export interface FlakeOutcome {
+    readonly name: string;
+    readonly status: ReplayStatus;
+}
+/**
+ * Record every outcome, then ask which flows are intermittent.
+ *
+ * Anything that is not `OK` — `ERROR` or `DRIFT` — counts as a failure for the ledger. That is the
+ * rule both call sites already used, preserved rather than chosen here.
+ */
+export declare function recordSuiteFlakes(fs: FileSystemPort, reticleRoot: string, runs: readonly {
+    readonly replay: FlakeOutcome;
+}[]): Promise<readonly string[]>;

package/dist/flows/suite-flakes.js

@@ -0,0 +1,32 @@
+/**
+ * Accrue a suite run's outcomes into the flake ledger, and report what the ledger knows.
+ *
+ * This existed twice — once in `flow_verify`'s sequential branch and once, after #240, in its
+ * parallel branch. That duplication is not incidental: the parallel branch shipped WITHOUT it, so an
+ * agent verifying in parallel built no flake evidence at all and never saw the quarantine set, and
+ * nothing went red because the other copy was still correct. One function both branches call is what
+ * makes that miss impossible on one side only.
+ *
+ * It is also what makes the behaviour testable. The handler itself needs a live browser session, so
+ * both branches were only ever pinned by tests that RE-IMPLEMENTED this loop — which passed with the
+ * shipped code reverted (measured on #240: 4/4 green with the fix absent). Extracted, the real thing
+ * runs in a unit test.
+ *
+ * Best-effort on both halves, deliberately: a flake ledger is memory, not a gate. A full disk must
+ * never turn a working verification into an error.
+ */
+import { ReplayStatus } from '@reticlehq/core';
+import { FlakeStore } from './flake-store.js';
+/**
+ * Record every outcome, then ask which flows are intermittent.
+ *
+ * Anything that is not `OK` — `ERROR` or `DRIFT` — counts as a failure for the ledger. That is the
+ * rule both call sites already used, preserved rather than chosen here.
+ */
+export async function recordSuiteFlakes(fs, reticleRoot, runs) {
+    const flakes = new FlakeStore(fs, reticleRoot);
+    for (const { replay } of runs) {
+        await flakes.record(replay.name, ReplayStatus.OK === replay.status).catch(() => undefined);
+    }
+    return flakes.flakyFlows().catch(() => []);
+}

package/dist/flows/verify-change-tools.js

@@ -1,14 +1,15 @@
 import { z } from 'zod';
+import { verdictForSuite } from './verify-change-verdict.js';
+import { attributedFailures } from './attributed-failure.js';
 import { Verified } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asRecord, asString } from '../tools/tools-helpers.js';
-import { loadNamedFlows, resolveChangedFiles } from '../cli-flow-commands.js';
+import { loadNamedFlows, resolveChangedFiles } from '../cli/cli-flow-commands.js';
 import { affectedSavedFlows } from './flow-sources.js';
 import { FLOW_TOOLS } from './flow-tools.js';
 import { findContradictions } from '../events/contradictions.js';
 import { parseControls } from '../tools/coverage-tools.js';
 import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
-const PASS = 'pass';
 export const VERIFY_CHANGE_TOOLS = [
     {
         name: ReticleTool.VERIFY_CHANGE,
@@ -57,13 +58,13 @@ export const VERIFY_CHANGE_TOOLS = [
         },
         handler: async (deps, args) => {
             const files = Array.isArray(args['files'])
-                ? args['files'].filter((f) => typeof f === 'string')
+                ? args['files'].filter((f) => 'string' === typeof f)
                 : [];
             const since = asString(args['since']);
             const changedFiles = await resolveChangedFiles(files, since);
             const flows = await loadNamedFlows(deps.fs, deps.reticleRoot);
             const { affected, unknownProvenance } = affectedSavedFlows(flows, changedFiles);
-            if (changedFiles.length === 0) {
+            if (0 === changedFiles.length) {
                 return {
                     verified: Verified.UNKNOWN,
                     because: 'no changed files were given, so there was nothing to decide about',
@@ -77,10 +78,10 @@ export const VERIFY_CHANGE_TOOLS = [
             }
             // The guard: an uncovered change is UNKNOWN. Reporting `yes` here would mean "your change is
             // fine" on the strength of having run nothing at all.
-            if (affected.length === 0) {
+            if (0 === affected.length) {
                 return {
                     verified: Verified.UNKNOWN,
-                    because: `no saved flow covers ${changedFiles.length === 1 ? 'this file' : 'these files'} — record one with reticle_record { action: "start" } then reticle_flow_save, or verify by driving the app directly`,
+                    because: `no saved flow covers ${1 === changedFiles.length ? 'this file' : 'these files'} — record one with reticle_record { action: "start" } then reticle_flow_save, or verify by driving the app directly`,
                     changedFiles,
                     flowsRun: [],
                     unknownProvenance,
@@ -104,11 +105,32 @@ export const VERIFY_CHANGE_TOOLS = [
             }));
             const failed = suite.failed ?? 0;
             const passed = suite.passed ?? 0;
-            const failedSuite = suite.status !== PASS || failed > 0;
-            if (failedSuite) {
+            // `unverifiable` is NOT a failure — the suite ran and proved nothing, which is the same fact
+            // this tool answers UNKNOWN for an uncovered change. Treating it as a red emitted a bug_found
+            // that nothing earned. See verify-change-verdict.
+            const verdict = verdictForSuite(String(suite.status), failed);
+            // A NO must be EARNED by a failing flow genuinely tied to the changed files. `affectedSavedFlows`
+            // re-runs any flow whose sources it cannot determine — over-running beats skipping — and those
+            // land in `unknownProvenance`. Judging the change on them produced a negative verdict whose own
+            // explanation admitted the evidence was not tied to the file. See attributed-failure.
+            const failingNames = Array.isArray(suite.failures)
+                ? suite.failures
+                    .map((f) => 'object' === typeof f && f !== null ? asString(asRecord(f)['flow']) : undefined)
+                    .filter((n) => n !== undefined)
+                : // No per-failure detail: the failure is somewhere in the set that ran, so ask the question
+                    // of all of them rather than guessing which.
+                    affected;
+            const attributed = attributedFailures(failingNames, unknownProvenance);
+            const earnedNo = verdict === Verified.NO && attributed.length > 0;
+            const reported = verdict === Verified.NO && !earnedNo ? Verified.UNKNOWN : verdict;
+            if (reported !== Verified.YES) {
                 return {
-                    verified: Verified.NO,
-                    because: `${String(failed)} of ${String(suite.total ?? affected.length)} covering flows failed${provenanceNote}`,
+                    verified: reported,
+                    because: earnedNo
+                        ? `${String(failed)} of ${String(suite.total ?? affected.length)} covering flows failed, including ${attributed.join(', ')}, which cover the changed files${provenanceNote}`
+                        : verdict === Verified.NO
+                            ? `flows failed, but Reticle cannot tell which sources any of them cover (${failingNames.join(', ')}) — so this says nothing about the files you changed. Re-record them so their sources are stamped, or read the replay yourself`
+                            : `the covering flows ran but proved nothing (${String(suite.status)}) — they assert no observable consequence, so a green from them would not have meant your change is safe${provenanceNote}`,
                     changedFiles,
                     flowsRun: affected,
                     suite,

package/dist/flows/verify-change-verdict.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What a replayed suite's status entitles `verify_change` to claim.
+ *
+ * This was `suite.status !== 'pass'` meaning failure. That was true while the only statuses were
+ * pass and fail — but `flow_verify` now reports `unverifiable` for a suite that ran and proved
+ * nothing (an empty suite used to report `pass`, which was a false green). Under the old test,
+ * `unverifiable` fell into the failure branch: a suite that proved nothing came back as proof the
+ * change was broken, and emitted a `bug_found` for it.
+ *
+ * `unverifiable` is the same fact this tool already handles elsewhere as "no saved flow covers this
+ * change" — answered UNKNOWN, with the comment calling it "the honest answer, never a green: nothing
+ * ran, so nothing was proved". A red nothing earned is the mirror image of that green.
+ */
+import { Verified } from '@reticlehq/core';
+export declare function verdictForSuite(status: string, failedCount: number): Verified;

package/dist/flows/verify-change-verdict.js

@@ -0,0 +1,25 @@
+/**
+ * What a replayed suite's status entitles `verify_change` to claim.
+ *
+ * This was `suite.status !== 'pass'` meaning failure. That was true while the only statuses were
+ * pass and fail — but `flow_verify` now reports `unverifiable` for a suite that ran and proved
+ * nothing (an empty suite used to report `pass`, which was a false green). Under the old test,
+ * `unverifiable` fell into the failure branch: a suite that proved nothing came back as proof the
+ * change was broken, and emitted a `bug_found` for it.
+ *
+ * `unverifiable` is the same fact this tool already handles elsewhere as "no saved flow covers this
+ * change" — answered UNKNOWN, with the comment calling it "the honest answer, never a green: nothing
+ * ran, so nothing was proved". A red nothing earned is the mirror image of that green.
+ */
+import { Verified } from '@reticlehq/core';
+const PASS = 'pass';
+const FAIL = 'fail';
+export function verdictForSuite(status, failedCount) {
+    // A real failure outranks everything: flows ran and some went red.
+    if (failedCount > 0 || status === FAIL)
+        return Verified.NO;
+    if (status === PASS)
+        return Verified.YES;
+    // `unverifiable`, or any status added later. Nothing was proved, so nothing is claimed.
+    return Verified.UNKNOWN;
+}

package/dist/flows/watch-batcher.d.ts

@@ -4,10 +4,10 @@
  * a quiet window, so we compute affected flows once per edit, not per keystroke. The scheduler (setTimeout)
  * is injected, keeping the batching logic pure and unit-testable.
  */
-export interface WatchBatcher {
+interface WatchBatcher {
     onChange(file: string): void;
 }
-export interface WatchBatcherOptions {
+interface WatchBatcherOptions {
     debounceMs: number;
     /** Injected scheduler (setTimeout) — deterministic in tests. */
     schedule: (fn: () => void, ms: number) => void;
@@ -15,3 +15,4 @@ export interface WatchBatcherOptions {
     onFlush: (files: string[]) => void;
 }
 export declare function createWatchBatcher(options: WatchBatcherOptions): WatchBatcher;
+export {};

package/dist/honesty/already-true.d.ts

@@ -0,0 +1,2 @@
+import type { Predicate } from '../events/predicate.js';
+export declare function readsDomState(predicate: Predicate): boolean;

package/dist/honesty/already-true.js

@@ -0,0 +1,31 @@
+/**
+ * Which predicates can be satisfied by something that was already true before the action.
+ *
+ * Event-based kinds (net, signal, route, console, animation, settled) are evaluated against the
+ * event buffer floored at the act's own cursor, so a stale event cannot satisfy them — that floor is
+ * why `act_and_wait` can trust them at all. `state` is read through the same floored path.
+ *
+ * `element` and `text` read the LIVE DOM, where no floor exists. A condition that held before the
+ * click holds after it and passes instantly, whatever the action did. Measured in the field: a click
+ * asserted with `{ kind: 'text', contains: 'Parallel Routes' }` returned `verified: "yes"` in 478ms
+ * against `routeChanges: 0`, because the predicate matched the nav link that was already on screen —
+ * the real navigation landed 1.8 seconds later.
+ *
+ * So these are the kinds worth evaluating BEFORE the act, to find out whether the green means
+ * anything.
+ */
+import { PredicateKind } from '@reticlehq/core';
+export function readsDomState(predicate) {
+    switch (predicate.kind) {
+        case PredicateKind.ELEMENT:
+        case PredicateKind.TEXT:
+            return true;
+        case PredicateKind.ALL_OF:
+        case PredicateKind.ANY_OF:
+            return predicate.predicates.some(readsDomState);
+        case PredicateKind.NOT:
+            return readsDomState(predicate.predicate);
+        default:
+            return false;
+    }
+}

package/dist/honesty/blind-spots.d.ts

@@ -6,12 +6,25 @@
  */
 export { BlindSpotKind } from '@reticlehq/core';
 import { BlindSpotKind, type ReticleEvent } from '@reticlehq/core';
-export interface BlindSpot {
+interface BlindSpot {
     kind: BlindSpotKind;
     count: number;
 }
-export interface CoverageStatement {
-    coverage: 'full' | 'partial';
+/**
+ * Whether the observation window saw everything it was asked about.
+ *
+ * NOT core's VerdictStatus, which happens to spell one of its values 'partial' too: that one grades
+ * a verification RUN (some flows passed, some failed), this one grades what could be OBSERVED. Two
+ * meanings behind one string is exactly how a comparison ends up reading the wrong field, so they
+ * stay separate vocabularies.
+ */
+export declare const Coverage: {
+    readonly FULL: "full";
+    readonly PARTIAL: "partial";
+};
+export type Coverage = (typeof Coverage)[keyof typeof Coverage];
+interface CoverageStatement {
+    coverage: Coverage;
     /** Present only when partial — the human/agent-legible list of what went unobserved. */
     note?: string;
     spots: BlindSpot[];
@@ -52,3 +65,22 @@ export declare function blindSpotsFromEvents(events: readonly ReticleEvent[]): B
  * from what happened to be said recently.
  */
 export declare function blindSpotsFromState(state: Readonly<Record<string, number>>): BlindSpot[];
+/**
+ * Events the BROWSER's own transport queue threw away inside this window, or 0.
+ *
+ * `RATE_LIMITED` — the BRIDGE sampling because events arrived faster than its per-second cap — is
+ * already the one blind spot that `impeachesCapture`, on the reasoning that a green over a window
+ * you did not fully see "would only describe what was observed". `TRANSPORT_OVERFLOW` is the exact
+ * same loss on the other side of the wire, and it was read in journal rollups and NOWHERE on the
+ * verdict path. So the identical condition downgraded a verdict from one side of the socket and was
+ * invisible from the other: a window that dropped 34 events graded `proved`, in a sentence whose own
+ * words were "over a clean capture".
+ *
+ * `TRUNCATED` is deliberately NOT counted. It names the channel it capped (a DOM-mutation flood on
+ * any busy page) and is routine churn; treating it as lost evidence would caveat every verdict on
+ * every real app, and a caveat that is always present is one nobody reads. TRANSPORT_OVERFLOW is the
+ * honest "arbitrary events are gone" marker — it cannot say which.
+ */
+export declare function droppedByTransport(events: readonly ReticleEvent[]): number;
+/** The impeaching note for a transport gap, or undefined when the window was intact. */
+export declare function transportGapNote(events: readonly ReticleEvent[]): string | undefined;