@reticlehq/server 2.7.0 → 2.9.0

package/dist/events/predicate.js

@@ -5,8 +5,21 @@ import { selectPath, capDepth } from '../session/state-select.js';
 import { describeTestidMiss } from './testid-near-miss.js';
 import { predicateToExpectedLinks } from '../capsule/predicate-to-links.js';
 import { isAmbient, ambientKeyOf } from '../journal/ambient.js';
-import { PredicateSchema, matchValue, evalNet, evalRoute, evalConsole, evalAnimation, evalSignal, evalSettled, } from './predicate-eval.js';
+import { evalRoute } from './predicate-route.js';
+import { PredicateSchema, matchValue, evalNet, evalConsole, evalAnimation, evalSignal, evalSettled, residualQueryChecks, satisfiesResiduals, describeResidual, } from './predicate-eval.js';
 export { PredicateSchema, PredicateKind };
+/**
+ * A composite result that carries a child's "nobody could evaluate this" up to the verdict rule.
+ *
+ * `decideVerified` already treats `inconclusive` correctly and does it ahead of the failure clause,
+ * so all a composite has to do is stop dropping the field on its way out. `pass` stays false because
+ * nothing was proven; what changes is that the verdict reads UNKNOWN rather than blaming the app for
+ * a clause the CALL under-specified.
+ */
+function unreadableComposite(child, evidence) {
+    const reason = child.inconclusive ?? 'a sub-predicate could not be evaluated';
+    return { pass: false, failureReason: reason, inconclusive: reason, evidence };
+}
 async function matchOnce(session, query, state) {
     const res = await session.command(ReticleCommand.MATCH, { query, state });
     if (!res.ok)
@@ -14,8 +27,44 @@ async function matchOnce(session, query, state) {
     return (res.result ?? { matched: false, count: 0, elements: [] });
 }
 async function evalElement(session, query, state, absent, diagnose) {
-    const match = await matchOnce(session, query, state);
+    // 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
@@ -114,8 +163,134 @@ async function evalElement(session, query, state, absent, diagnose) {
         ...(present.length > 0 ? { evidence: { presentTestids: present } } : {}),
     };
 }
+/** The single element of a list, or undefined when there is not exactly one. */
+function oneOf(names) {
+    return 1 === names.length ? names[0] : undefined;
+}
+/**
+ * `readState`'s truncation report, when the caps actually fired.
+ *
+ * Its PRESENCE is the warning — the field is omitted entirely on an intact read, which is what lets
+ * "the list is short" stay distinguishable from "I shortened the list".
+ */
+function truncationOf(result) {
+    if ('object' !== typeof result || null === result)
+        return undefined;
+    const report = result.truncation;
+    return 'object' === typeof report && null !== report
+        ? report
+        : undefined;
+}
+/** A scoped `readState` reply, narrowed to the shape `selectPath` would have produced. */
+function asSelection(result) {
+    if ('object' !== typeof result || null === result)
+        return undefined;
+    const record = result;
+    return 'boolean' === typeof record.found
+        ? { found: record.found, value: record.value }
+        : undefined;
+}
+/**
+ * A NAMED store needs no whole-store read. `reticle_state`'s scoped mode selects the path out of the
+ * RAW store IN-PAGE and returns only it, so the assertion resolves in one round trip against a payload
+ * the size of the value — not the store. The unnamed case below still needs the wide read, because
+ * that is how it discovers WHICH store carries the path; only the named branch changes.
+ *
+ * A scoped read answers `found: false` for both "no such store" and "no such path", so the two are
+ * kept distinct here using the `storeNames` list the reply always carries — otherwise the payload gets
+ * cheaper while the message gets worse.
+ */
+async function evalStateNamed(session, p, storeName) {
+    const scoped = await session.command(ReticleCommand.STATE_READ, {
+        store: storeName,
+        path: p.path,
+    });
+    if (!scoped.ok) {
+        return {
+            pass: false,
+            failureReason: 'state read failed',
+            observed: 'the store could not be read',
+            expected: 'a readable registered store',
+            assertion: 'state.unreadable',
+        };
+    }
+    const reply = (scoped.result ?? {});
+    const names = Array.isArray(reply.storeNames) ? reply.storeNames : [];
+    // Resolve the value. A CURRENT SDK honours the scoped read and answers `{ found, value }` selected
+    // in-page — the whole point of this path. An OLDER SDK (version skew) or any transport that ignores
+    // `path` answers the whole-store shape `{ stores }`; walk the path server-side there so the verdict
+    // stays correct across SDK versions. The scoped win is simply unavailable on the old ones.
+    const scopedSel = asSelection(scoped.result);
+    const wholeStores = reply.stores;
+    const scopedKeys = Array.isArray(reply.availableKeys)
+        ? reply.availableKeys
+        : undefined;
+    let selection;
+    if (scopedSel !== undefined) {
+        selection =
+            scopedKeys === undefined
+                ? { found: scopedSel.found, value: scopedSel.value }
+                : { found: scopedSel.found, value: scopedSel.value, availableKeys: scopedKeys };
+    }
+    else if (wholeStores !== undefined) {
+        selection = selectPath(wholeStores[storeName], p.path);
+    }
+    else {
+        selection = { found: false };
+    }
+    // "no store named X" and "X has no such path" both surface as found:false; keep them distinct using
+    // the store list the reply carries, or the message regresses while the payload improves.
+    const storeAbsent = wholeStores !== undefined
+        ? !(storeName in wholeStores)
+        : names.length > 0 && !names.includes(storeName);
+    if (!selection.found && storeAbsent) {
+        return {
+            pass: false,
+            failureReason: `no store named '${storeName}' is registered (${names.join(', ')})`,
+            observed: `store '${storeName}' is not registered`,
+            expected: `a registered store named '${storeName}'`,
+            assertion: 'state.store-missing',
+            evidence: { searchedStores: names },
+        };
+    }
+    // A scoped sub-tree can itself be too big for the caps; a comparison against a value known to be
+    // incomplete is an unanswered question, not a failure. Same rule the whole-store path applies.
+    if (truncationOf(scoped.result) !== undefined) {
+        const reason = `state '${p.path}' could not be read intact — the transport caps truncated it, so the ` +
+            'value was never compared. Assert a narrower path, or a smaller field inside it';
+        return { pass: false, failureReason: reason, inconclusive: reason };
+    }
+    if (!selection.found) {
+        return {
+            pass: false,
+            failureReason: `state path '${p.path}' not found in store '${storeName}'`,
+            observed: `no path '${p.path}' in store '${storeName}'`,
+            expected: `store '${storeName}' to expose '${p.path}'`,
+            assertion: 'state.path-missing',
+            evidence: { availableKeys: selection.availableKeys },
+        };
+    }
+    const want = p.equals === undefined ? '*' : p.equals;
+    if (matchValue(selection.value, want)) {
+        return {
+            pass: true,
+            evidence: { store: storeName, path: p.path, value: capDepth(selection.value, 1) },
+        };
+    }
+    return {
+        pass: false,
+        failureReason: `state '${p.path}' is ${JSON.stringify(capDepth(selection.value, 0))}, expected ${JSON.stringify(want)}`,
+        observed: `${p.path} = ${JSON.stringify(capDepth(selection.value, 0))}`,
+        expected: `${p.path} = ${JSON.stringify(want)}`,
+        assertion: 'state.equals',
+        evidence: { store: storeName, path: p.path, value: capDepth(selection.value, 1) },
+    };
+}
 async function evalState(session, p) {
-    const res = await session.command(ReticleCommand.STATE_READ, p.store !== undefined ? { store: p.store } : {});
+    // Named store: one scoped read, no whole-store payload (issue #336).
+    if (p.store !== undefined)
+        return await evalStateNamed(session, p, p.store);
+    const res = await session.command(ReticleCommand.STATE_READ, {});
     if (!res.ok) {
         return {
             pass: false,
@@ -127,17 +302,75 @@ async function evalState(session, p) {
     }
     const stores = (res.result ?? {}).stores ?? {};
     const names = Object.keys(stores);
-    const storeName = p.store ?? (1 === names.length ? names[0] : undefined);
+    // Ambiguity is about the PATH, not the store count.
+    //
+    // Registering more than one store is normal — an app store, a query cache, and the render meter
+    // Reticle registers itself — and asking "which of these three?" when only one of them HAS the
+    // path is a question with one possible answer. It was costing a real verdict: a bench-app drive
+    // asserting `{path:'view'}` returned `unknown` while the same response body carried the matching
+    // `view` state diff. `unknown` is not a pass, so that is a verification that did not happen.
+    //
+    // So narrow to the stores that actually carry the path, and refuse only when THOSE collide.
+    const candidates = p.store === undefined ? names.filter((n) => selectPath(stores[n], p.path).found) : [];
+    const storeName = p.store ?? (1 === names.length ? names[0] : oneOf(candidates));
     if (storeName === undefined) {
-        // Neither of these is a finding about the app. With several stores registered the call simply did
-        // not say which one to read; with none, there is nothing to read at all. No assertion was
-        // evaluated either way, so this is inconclusive rather than failed — see honesty/inconclusive.
-        const reason = 0 === names.length
-            ? 'no registered store to read state from'
-            : `multiple stores (${names.join(', ')}); name one with \`store\``;
-        return { pass: false, failureReason: reason, inconclusive: reason };
+        // With no store registered there is nothing to read, and with two stores that both carry the
+        // path there is no way to pick — neither is a finding about the app, no assertion was evaluated,
+        // so both are inconclusive rather than failed. See honesty/inconclusive.
+        //
+        // Zero candidates is the one case that is NOT a question: every registered store was searched
+        // and none exposes the path, so the assertion cannot hold anywhere. That is the same verdict a
+        // named store has always produced for a missing path, and it falls through to it below.
+        if (0 === names.length) {
+            const reason = 'no registered store to read state from';
+            return { pass: false, failureReason: reason, inconclusive: reason };
+        }
+        if (candidates.length > 1) {
+            // Names the stores that actually collide. Listing all of them made the reader weigh
+            // candidates that could never have matched.
+            const reason = `multiple stores (${candidates.join(', ')}) expose '${p.path}'; name one with \`store\``;
+            return { pass: false, failureReason: reason, inconclusive: reason };
+        }
+        return {
+            pass: false,
+            failureReason: `state path '${p.path}' not found in any registered store (${names.join(', ')})`,
+            observed: `no path '${p.path}' in ${names.join(', ')}`,
+            expected: `some registered store to expose '${p.path}'`,
+            assertion: 'state.path-missing',
+            evidence: { searchedStores: names },
+        };
+    }
+    let selection = selectPath(stores[storeName], p.path);
+    // The whole-store read walks into a value the transport caps may already have mangled.
+    //
+    // `readState` has a SCOPED mode that selects the path out of the RAW store before sanitising, added
+    // precisely so a large or deep path still resolves. This path was not using it, so a store with one
+    // big collection in it truncated the small value sitting beside it, and the comparison then ran
+    // against the literal string "[TRUNCATED]" and returned a confident `no`. Measured on the Atlas
+    // fixture: a one-element array reported as a failed assertion while the same payload's state diffs
+    // showed the assertion holding.
+    //
+    // Re-read only when a cap actually fired, so an intact read costs exactly what it did before.
+    if (truncationOf(res.result) !== undefined) {
+        const scoped = await session.command(ReticleCommand.STATE_READ, {
+            store: storeName,
+            path: p.path,
+        });
+        const result = scoped.ok ? scoped.result : undefined;
+        const scopedTruncation = truncationOf(result);
+        if (scopedTruncation !== undefined) {
+            // Even the raw sub-tree was too big. Nothing here knows what the value IS, so nothing here can
+            // say the assertion failed — that would be an accusation the evidence does not support.
+            const reason = `state '${p.path}' could not be read intact — the transport caps truncated it, so the ` +
+                'value was never compared. Assert a narrower path, or a smaller field inside it';
+            return { pass: false, failureReason: reason, inconclusive: reason };
+        }
+        if (result !== undefined) {
+            const scopedSelection = asSelection(result);
+            if (scopedSelection !== undefined)
+                selection = scopedSelection;
+        }
     }
-    const selection = selectPath(stores[storeName], p.path);
     if (!selection.found) {
         return {
             pass: false,
@@ -183,11 +416,16 @@ diagnose = true) {
         case PredicateKind.ELEMENT:
             return evalElement(session, predicate.query, predicate.state, predicate.absent ?? false, diagnose);
         case PredicateKind.TEXT:
-            return evalElement(session, { text: predicate.contains }, true === predicate.visible ? ElementState.VISIBLE : undefined, predicate.absent ?? false, diagnose);
+            return evalElement(session, 
+            // `scope` passes straight through: the text predicate has always been an element query
+            // with only `text` filled in, so scoping it needs the field, not a second code path.
+            undefined === predicate.scope
+                ? { text: predicate.contains }
+                : { text: predicate.contains, scope: predicate.scope }, true === predicate.visible ? ElementState.VISIBLE : undefined, predicate.absent ?? false, diagnose);
         case PredicateKind.NET:
             return evalNet(events, predicate);
         case PredicateKind.ROUTE:
-            return evalRoute(events, predicate);
+            return evalRoute(events, predicate, session.url);
         case PredicateKind.CONSOLE:
             return evalConsole(events, predicate);
         case PredicateKind.ANIMATION:
@@ -206,27 +444,55 @@ diagnose = true) {
         }
         case PredicateKind.ALL_OF: {
             const results = await Promise.all(predicate.predicates.map((p) => evaluatePredicate(session, p, since, diagnose)));
-            const failed = results.find((r) => !r.pass);
-            return failed === undefined
-                ? { pass: true, evidence: results.map((r) => r.evidence) }
-                : {
+            // A clause that genuinely failed OUTRANKS one nobody could read. Softening a real failure to
+            // UNKNOWN would hide the defect the agent came for, which is the more expensive of the two
+            // mistakes; the reverse — grading an unreadable clause as a defect in the app — is the one
+            // that was happening.
+            const failed = results.find((r) => !r.pass && r.inconclusive === undefined);
+            if (failed !== undefined) {
+                return {
                     pass: false,
                     failureReason: failed.failureReason ?? 'a sub-predicate of allOf failed',
+                    // A conjunction is decided as soon as ONE clause is: nothing the others do later can
+                    // rescue it. This is what makes the early exit reach real calls, since an exact count is
+                    // usually asserted alongside the UI change it is meant to accompany.
+                    ...(true === failed.decided ? { decided: true } : {}),
                     evidence: results,
                 };
+            }
+            const unreadable = results.find((r) => r.inconclusive !== undefined);
+            if (unreadable !== undefined)
+                return unreadableComposite(unreadable, results);
+            return { pass: true, evidence: results.map((r) => r.evidence) };
         }
         case PredicateKind.ANY_OF: {
             const results = await Promise.all(predicate.predicates.map((p) => evaluatePredicate(session, p, since, diagnose)));
             const passed = results.find((r) => r.pass);
-            return passed !== undefined
-                ? { pass: true, evidence: passed.evidence }
-                : { pass: false, failureReason: 'no sub-predicate of anyOf matched', evidence: results };
+            if (passed !== undefined)
+                return { pass: true, evidence: passed.evidence };
+            // "No sub-predicate matched" is a claim anyOf is not entitled to make while one of them was
+            // never read: the unreadable clause might have been the one that would have matched.
+            const unreadable = results.find((r) => r.inconclusive !== undefined);
+            if (unreadable !== undefined)
+                return unreadableComposite(unreadable, results);
+            return { pass: false, failureReason: 'no sub-predicate of anyOf matched', evidence: results };
         }
         case PredicateKind.NOT: {
             const inner = await evaluatePredicate(session, predicate.predicate, since, diagnose);
+            // The sharpest case of the three, and the only one that produced a GREEN. `not` read the
+            // child's `pass: false` as "the inner predicate did not hold" and passed — so an assertion
+            // nobody could evaluate became a verdict of verified, manufactured out of a missing reading.
+            // You cannot negate an answer nobody had.
+            if (inner.inconclusive !== undefined)
+                return unreadableComposite(inner, inner);
+            // A green negation used to return a bare `{ pass: true }`, so the payload fell back to
+            // whatever the caller had — every element matching the OUTER locator. Three clauses negating
+            // three different names then produced byte-identical responses, which reads as a checker that
+            // dropped the name rather than one that correctly found all three absent. The evidence is the
+            // whole answer here: what was looked for, and that it was not there.
             return inner.pass
                 ? { pass: false, failureReason: 'negated predicate unexpectedly held', evidence: inner }
-                : { pass: true };
+                : { pass: true, evidence: { negated: predicate.predicate, held: false, saw: inner } };
         }
         default:
             return { pass: false, failureReason: 'unknown predicate' };
@@ -342,6 +608,14 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
             void evaluatePredicate(session, predicate, since, false)
                 .then((r) => {
                 if (!r.pass) {
+                    // Final already: stop rather than spend a budget that cannot change the answer. Only
+                    // where the evaluator could PROVE it (see EvalResult.decided) — an ordinary miss keeps
+                    // waiting, because "it has not happened yet" and "it will not happen" are the same
+                    // reading until the budget ends.
+                    if (true === r.decided) {
+                        finish(r);
+                        return;
+                    }
                     // A time-based failure knows when it could stop being one — re-check THEN rather than on
                     // the next blind tick. Without this, every `settled` wait paid up to a full poll interval
                     // of dead time after the quiet window had already closed: measured at 566–627ms across

package/dist/flows/annotate-tools.js

@@ -118,6 +118,9 @@ export const ANNOTATE_TOOLS = [
             recovery: z.string().optional(),
             target: z.string().optional(),
             compiled: z.string().optional(),
+            // Set when the compiled annotation would overstate what a replay can check — e.g. a
+            // success-state that flow_save will grade assertion-free (#395).
+            note: z.string().optional(),
             code: z.string().optional(),
         },
         handler: (deps, args) => {

package/dist/flows/annotate.js

@@ -1,4 +1,4 @@
-import { AnnotationErrorCode, AnnotationKind, AnnotationTarget, COMPILED_PREDICATE_PREFIX, } from '@reticlehq/core';
+import { AnnotationErrorCode, AnnotationKind, AnnotationTarget, COMPILED_PREDICATE_PREFIX, flowExpectHasConsequence, flowExpectIsPresenceOnly, } from '@reticlehq/core';
 /**
  * The PURE compiler at the heart of the annotation facet. A structured annotation +
  * the current captured-step count → an AnnotateOutcome (a result envelope + the patch to apply to
@@ -96,11 +96,25 @@ function stepPatch(a, stepCount, stepExpect) {
         patch: { stepIndex: stepCount - 1, stepExpect },
     };
 }
+// A success end-condition that is not an observable CONSEQUENCE (signal / net / state) cannot lift
+// the flow above the grade flow_save will give it. Saying "will succeed when ..." without that
+// caveat is the #395 contradiction: annotate promises a check that flow_save then grades
+// assertion-free, so a flow that only checks the console replays green through any regression. Name
+// the grade here, using the same consequence/presence classification every grader shares.
+const SUCCESS_ASSERTION_FREE_NOTE = 'This success-state is not an observable consequence, so flow_save will grade the flow assertion-free — it passes even when the feature is broken. Use a signal / net / state success-state to give the flow something that can fail.';
+const SUCCESS_PRESENCE_ONLY_NOTE = 'This success-state only checks element presence, so flow_save will grade the flow presence-only — a locator healed to the wrong element still passes it. Use a signal / net / state success-state to assert an observable consequence.';
 function flowSuccess(a, success) {
-    return {
-        result: { ok: true, target: AnnotationTarget.FLOW, compiled: describeCompiled(a) },
-        patch: { success },
+    const result = {
+        ok: true,
+        target: AnnotationTarget.FLOW,
+        compiled: describeCompiled(a),
     };
+    if (!flowExpectHasConsequence(success)) {
+        result.note = flowExpectIsPresenceOnly(success)
+            ? SUCCESS_PRESENCE_ONLY_NOTE
+            : SUCCESS_ASSERTION_FREE_NOTE;
+    }
+    return { result, patch: { success } };
 }
 /**
  * Human-readable confirmation text for the recorder strip / tool result,

package/dist/flows/coverage.d.ts

@@ -9,11 +9,18 @@ interface DeclaredSurface {
     signals: readonly string[];
     flows: readonly string[];
 }
-interface CoverageDimension {
+export interface CoverageDimension {
     total: number;
     covered: number;
-    /** Percent covered, rounded; 100 when nothing is declared (vacuously complete). */
-    pct: number;
+    /**
+     * Percent covered, rounded. PRESENT ONLY WHEN IT WAS MEASURED — absent when nothing is declared,
+     * same rule as the honesty layer's `{ pct?: number; partial: boolean }`.
+     *
+     * This used to report 100 for an empty surface ("vacuously complete"), which made
+     * `covered: 0, total: 0, pct: 100` — a contradiction the caller had to notice unaided, in output an
+     * agent reads to decide whether its change is covered.
+     */
+    pct?: number;
     /** Declared-but-never-exercised members — what "everything" is silently missing. */
     uncovered: string[];
 }
@@ -21,8 +28,34 @@ export interface Coverage {
     testids: CoverageDimension;
     signals: CoverageDimension;
     flows: CoverageDimension;
-    /** Overall percent across all three dimensions combined. */
-    overallPct: number;
+    /** Overall percent across all three dimensions combined; absent when nothing is declared. */
+    overallPct?: number;
 }
+/** The gate's outcome when the project has recorded no flows at all — not a pass, and not a failure. */
+export declare const NO_FLOWS = "no_flows";
+/**
+ * What to do about it, since the empty state is otherwise indistinguishable from success.
+ *
+ * Names the TOOLS, not a `reticle record` CLI verb: this CLI does not dispatch one, and a suggestion
+ * that errors is a second dead end on top of the first (see suggested-commands-exist.test.ts). Same
+ * wording as the empty-suite verdict, which is the same situation reached from `reticle verify`.
+ */
+export declare const NO_FLOWS_NOTE = "no flows recorded \u2014 nothing was checked. Record one with reticle_record { action: \"start\" }, then reticle_flow_save.";
+/** The gate's flow-coverage line. `pct` and `outcome` are mutually exclusive by construction. */
+export interface FlowCoverageReport {
+    covered: number;
+    total: number;
+    pct?: number;
+    outcome?: typeof NO_FLOWS;
+    note?: string;
+}
+/**
+ * Report flow coverage so that an EMPTY suite cannot be read as a passing one.
+ *
+ * Same rule `buildSuiteVerdict` already applies to `reticle verify`, where zero flows reports
+ * `unverifiable` rather than "all 0 flows pass": a green that cannot go red is not a pass. Callers
+ * must treat a present `outcome` as not-passing.
+ */
+export declare function flowCoverageReport(flows: CoverageDimension): FlowCoverageReport;
 export declare function computeCoverage(declared: DeclaredSurface, exercised: DeclaredSurface): Coverage;
 export {};

package/dist/flows/coverage.js

@@ -4,11 +4,36 @@
  * (contract testids/signals/flows) actually touched by passing verification, so "everything" is honest
  * about what everything means. Pure set math; the deviation report + gate carry the number.
  */
+/** The gate's outcome when the project has recorded no flows at all — not a pass, and not a failure. */
+export const NO_FLOWS = 'no_flows';
+/**
+ * What to do about it, since the empty state is otherwise indistinguishable from success.
+ *
+ * Names the TOOLS, not a `reticle record` CLI verb: this CLI does not dispatch one, and a suggestion
+ * that errors is a second dead end on top of the first (see suggested-commands-exist.test.ts). Same
+ * wording as the empty-suite verdict, which is the same situation reached from `reticle verify`.
+ */
+export const NO_FLOWS_NOTE = 'no flows recorded — nothing was checked. Record one with reticle_record { action: "start" }, then reticle_flow_save.';
+/**
+ * Report flow coverage so that an EMPTY suite cannot be read as a passing one.
+ *
+ * Same rule `buildSuiteVerdict` already applies to `reticle verify`, where zero flows reports
+ * `unverifiable` rather than "all 0 flows pass": a green that cannot go red is not a pass. Callers
+ * must treat a present `outcome` as not-passing.
+ */
+export function flowCoverageReport(flows) {
+    const { covered, total } = flows;
+    if (0 === total)
+        return { covered, total, outcome: NO_FLOWS, note: NO_FLOWS_NOTE };
+    return { covered, total, ...(flows.pct === undefined ? {} : { pct: flows.pct }) };
+}
 function dimension(declared, exercised) {
     const uncovered = declared.filter((d) => !exercised.has(d));
     const covered = declared.length - uncovered.length;
-    const pct = 0 === declared.length ? 100 : Math.round((covered / declared.length) * 100);
-    return { total: declared.length, covered, pct, uncovered };
+    const base = { total: declared.length, covered, uncovered };
+    if (0 === declared.length)
+        return base;
+    return { ...base, pct: Math.round((covered / declared.length) * 100) };
 }
 export function computeCoverage(declared, exercised) {
     const testids = dimension(declared.testids, new Set(exercised.testids));
@@ -16,6 +41,7 @@ export function computeCoverage(declared, exercised) {
     const flows = dimension(declared.flows, new Set(exercised.flows));
     const total = testids.total + signals.total + flows.total;
     const covered = testids.covered + signals.covered + flows.covered;
-    const overallPct = 0 === total ? 100 : Math.round((covered / total) * 100);
-    return { testids, signals, flows, overallPct };
+    if (0 === total)
+        return { testids, signals, flows };
+    return { testids, signals, flows, overallPct: Math.round((covered / total) * 100) };
 }

package/dist/flows/decision.d.ts

@@ -1,5 +1,20 @@
 import { type FlowFile, type FlowReplayResult, type ReplayDecision, type SuiteVerdict } from '@reticlehq/core';
 export declare function buildDecision(result: FlowReplayResult, flow?: FlowFile): ReplayDecision;
+/**
+ * Aggregate per-flow replays into one suite verdict — the autonomous loop's consolidated answer
+ * after a build: did anything break, and what's the prioritized fix list. Pure: pass the already
+ * decision-annotated replay results + their flows. Passing flows are counted; only failures carry
+ * detail (token-cheap), each with the actionable decision so the agent fixes without re-querying.
+ */
+/**
+ * Why a green replay still verified nothing, or undefined when it genuinely did.
+ *
+ * A flow with no steps, or one that asserts no observable consequence, replays green no matter what
+ * the app does — the grader already knows this at save time and says so. Counting it as `passed`
+ * turned that warning into "all 1 flow pass", which is a false green in the exact feature sold as
+ * the regression suite. Classified only when the flow file is available; never guessed.
+ */
+export declare function unverifiableReason(flow: FlowFile | undefined): string | undefined;
 export declare function buildSuiteVerdict(runs: ReadonlyArray<{
     replay: FlowReplayResult;
     flow?: FlowFile;

package/dist/flows/decision.js

@@ -100,7 +100,7 @@ function suiteVerdictOf(status) {
  * turned that warning into "all 1 flow pass", which is a false green in the exact feature sold as
  * the regression suite. Classified only when the flow file is available; never guessed.
  */
-function unverifiableReason(flow) {
+export function unverifiableReason(flow) {
     if (flow === undefined)
         return undefined;
     if (0 === flow.steps.length) {

package/dist/flows/flow-classify.js

@@ -27,7 +27,7 @@ export const FlowAssertionGrade = {
     /** Performs actions but asserts nothing observable — passes even if the feature is broken. */
     ASSERTION_FREE: 'assertion-free',
 };
-const ASSERTION_FREE_WARNING = 'This flow performs actions but asserts no observable consequence — it will pass even if the feature is broken. Add a consequence assertion with reticle_annotate (assert-signal / assert-net) or a success-state.';
+const ASSERTION_FREE_WARNING = 'This flow performs actions but asserts no observable consequence, so it will pass even if the feature is broken. Add a consequence assertion with reticle_annotate (assert-signal / assert-net) or a success-state.';
 const PRESENCE_ONLY_WARNING = 'This flow only checks element presence, not an observable consequence (signal/network). A locator healed to the wrong element can still pass it. Add a consequence assertion (assert-signal / assert-net / success-state).';
 const INTENT_WITHOUT_OUTCOME_WARNING = 'This flow declares a business intent but asserts no observable outcome (signal/network) — it claims to verify a goal it cannot actually check. Add a success-state consequence so the flow fails when the goal stops being met.';
 // Consequence vs presence-only classification lives in @reticlehq/core (one source for all graders).

package/dist/flows/flow-replay-run.js

@@ -2,7 +2,7 @@ import { EventType, FLOW_SIGNAL_TIMEOUT_MS, FlowErrorCode, RecordedFlowSchema, R
 import { asString } from '../tools/tools-helpers.js';
 import { replayFlow } from './flow-replay.js';
 import { assertSuccess, dynamicTestids, successLabel, SUCCESS_STEP_TOOL } from './flow-success.js';
-import { buildDecision } from './decision.js';
+import { buildDecision, unverifiableReason } from './decision.js';
 import { waitForPredicate } from '../events/predicate.js';
 import { computeSegments } from '../journal/rollups.js';
 import { AssertionTiersStore } from './assertion-tiers-store.js';
@@ -174,6 +174,13 @@ export async function replayNamedFlow(deps, args) {
         return errored;
     }
     const result = { name, status, steps };
+    // A green that cannot go red is not a pass. `reticle_flow_verify` already refuses to count these,
+    // via this same function -- a single-flow caller saw a bare `ok` and had no way to learn the flow
+    // asserts nothing. Derived from the same helper on purpose: two copies of this judgement would
+    // drift, and the sibling tools would then disagree about the same flow.
+    const cannotFail = status === ReplayStatus.OK ? unverifiableReason(loaded.value) : undefined;
+    if (cannotFail !== undefined)
+        result.unverifiable = { reason: cannotFail };
     if (status !== ReplayStatus.OK)
         result.decision = buildDecision(result, loaded.value);
     applyStartPathHint(result, startPathHint);