@reticlehq/server 2.6.0 → 2.8.0

package/dist/events/predicate.js

@@ -5,8 +5,20 @@ 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 { PredicateSchema, matchValue, evalNet, evalRoute, 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 +26,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,6 +162,33 @@ 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;
+}
 async function evalState(session, p) {
     const res = await session.command(ReticleCommand.STATE_READ, p.store !== undefined ? { store: p.store } : {});
     if (!res.ok) {
@@ -127,17 +202,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,
@@ -206,24 +339,43 @@ 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',
                     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);
             return inner.pass
                 ? { pass: false, failureReason: 'negated predicate unexpectedly held', evidence: inner }
                 : { pass: true };

package/dist/events/ring-buffer.d.ts

@@ -24,6 +24,14 @@ export declare class RingBuffer {
     since(cursor: number): ReticleEvent[];
     /** Events within the last `windowMs`, relative to `now`. */
     window(windowMs: number, now: number): ReticleEvent[];
+    /**
+     * Did this buffer evict scarce evidence that belonged to a window opened at `cursor`?
+     *
+     * The one honest input to "was the capture clean". A `false` here means every non-churn event in
+     * the window is still held, whatever the drop counter says — and the drop counter says a great
+     * deal, because age eviction runs on every push.
+     */
+    lostSince(cursor: number): boolean;
     /** Snapshot of buffer health for the agent — live events held and cumulative drops since connect. */
     bufferHealth(): {
         total: number;

package/dist/events/ring-buffer.js

@@ -23,6 +23,16 @@ export class RingBuffer {
     #head = 0;
     #totalBytes = 0;
     #droppedCount = 0;
+    /**
+     * The timestamp of the newest NON-CHURN event this buffer has ever evicted, or `undefined` if it
+     * has never lost one. This — not the drop counter — is what impeaches an observation window.
+     *
+     * The counter cannot answer the question. It moves for age eviction (everything past 60s, on every
+     * push) and for churn eviction (the low-signal floor, sacrificed on purpose so scarce evidence
+     * survives), neither of which is evidence lost from the window an agent just observed. See
+     * `lostSince` and `ring-buffer-window-loss.test.ts`.
+     */
+    #lastScarceLossT;
     constructor(options = {}) {
         this.#maxEvents = options.maxEvents ?? RING_BUFFER_DEFAULTS.MAX_EVENTS;
         this.#maxAgeMs = options.maxAgeMs ?? RING_BUFFER_DEFAULTS.MAX_AGE_MS;
@@ -81,7 +91,10 @@ export class RingBuffer {
             }
             const victim = this.#findChurnAfterHead();
             if (-1 === victim) {
-                // Buffer genuinely full of high-signal events — fall back to FIFO so it stays bounded.
+                // Buffer genuinely full of high-signal events — fall back to FIFO so it stays bounded. This
+                // is the one eviction path that destroys scarce evidence, and the only one that should ever
+                // make a verdict say it could not see.
+                this.#noteScarceLoss(this.#head);
                 this.#totalBytes -= this.#eventBytes[this.#head] ?? 0;
                 this.#head += 1;
                 continue;
@@ -91,6 +104,7 @@ export class RingBuffer {
             this.#eventBytes.splice(victim, 1);
         }
         while (this.#liveCount() > 0 && (this.#events[this.#head]?.t ?? cutoff) < cutoff) {
+            this.#noteScarceLoss(this.#head);
             this.#totalBytes -= this.#eventBytes[this.#head] ?? 0;
             this.#head += 1;
         }
@@ -102,6 +116,25 @@ export class RingBuffer {
             this.#head = 0;
         }
     }
+    /** Record an eviction at `index` as scarce loss, unless it was the churn floor being sacrificed. */
+    #noteScarceLoss(index) {
+        const victim = this.#events[index];
+        if (victim === undefined || CHURN_TYPES.has(victim.type))
+            return;
+        if (this.#lastScarceLossT === undefined || victim.t > this.#lastScarceLossT) {
+            this.#lastScarceLossT = victim.t;
+        }
+    }
+    /**
+     * Did this buffer evict scarce evidence that belonged to a window opened at `cursor`?
+     *
+     * The one honest input to "was the capture clean". A `false` here means every non-churn event in
+     * the window is still held, whatever the drop counter says — and the drop counter says a great
+     * deal, because age eviction runs on every push.
+     */
+    lostSince(cursor) {
+        return this.#lastScarceLossT !== undefined && this.#lastScarceLossT >= cursor;
+    }
     /** First churn event after the head, or -1 if none within the bounded scan (keeps eviction cheap). */
     #findChurnAfterHead() {
         const end = Math.min(this.#events.length, this.#head + CHURN_SCAN_LIMIT);

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-tools.js

@@ -367,23 +367,31 @@ export const FLOW_TOOLS = [
                 requested.length > 0) {
                 const concurrency = resolveConcurrency(requested.length, pool.capacity(), parallelArg);
                 const outcomes = await mapWithConcurrency(requested, concurrency, async (flowName) => {
-                    const lease = await acquireLeasedSession(pool, (id) => deps.sessions.get(id) !== undefined, appUrl);
+                    const start = deps.now();
+                    const lease = await acquireLeasedSession(pool, deps.sessions, appUrl, projectId);
                     try {
-                        return await replayNamedFlow(deps, { flowName, sessionId: lease.sessionId });
+                        const replay = await replayNamedFlow(deps, { flowName, sessionId: lease.sessionId });
+                        return { replay, durationMs: deps.now() - start };
                     }
                     finally {
-                        // Always release: a crashed flow must never leak a slot and starve the rest of the suite.
                         await lease.release().catch(() => undefined);
                     }
                 });
                 const parallelRuns = await Promise.all(outcomes.map(async (o, i) => {
                     const name = requested[i] ?? '';
-                    const replay = o.ok && o.value !== undefined ? o.value : leaseFailureReplay(name, o.error);
+                    const replay = o.ok && o.value !== undefined ? o.value.replay : leaseFailureReplay(name, o.error);
                     const loaded = await deps.flows.load(name, projectId).catch(() => null);
                     const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
                     return flow === undefined ? { replay } : { replay, flow };
                 }));
+                const timed = outcomes.map((o, i) => ({
+                    replay: o.ok && o.value !== undefined
+                        ? o.value.replay
+                        : leaseFailureReplay(requested[i] ?? '', o.error),
+                    durationMs: o.ok && o.value !== undefined ? o.value.durationMs : 0,
+                }));
                 const flaky = await recordSuiteFlakes(deps.fs, deps.reticleRoot, parallelRuns);
+                await persistAndSyncVerificationRun(deps, timed, projectId);
                 const verdict = buildSuiteVerdict(parallelRuns);
                 return flaky.length > 0 ? { ...verdict, flaky: [...flaky] } : verdict;
             }

package/dist/flows/heal-run.js

@@ -16,7 +16,7 @@ const HEAL_MESSAGES = {
     NOTHING: 'nothing to heal — every anchor resolved on replay',
     HEALED: "rewrote drifted testid anchors to their nearest surviving match and re-verified the flow's success consequence still fires",
     DRIFT_DRY: 'confident rebind(s) proposed — re-run with apply:true to write them to disk',
-    UNHEALABLE: `drift found, but no nearest match cleared the confidence floor (HEAL_CONFIDENCE_MIN=${HEAL_CONFIDENCE_MIN}); file left untouched — add a data-testid or fix the flow by hand`,
+    UNHEALABLE: `drift found, but no nearest match cleared the confidence floor (HEAL_CONFIDENCE_MIN=${HEAL_CONFIDENCE_MIN}); file left untouched; add a data-testid or fix the flow by hand`,
     HEALED_UNVERIFIED: 'rewrote drifted testid anchors — but this flow declares no success consequence, so the rebind resolves a locator without proving the intent still holds. Add a success-state assertion (reticle_annotate) so future heals can be verified.',
     CONSEQUENCE_BROKEN: 'rebind resolves the drifted locator to a surviving element, but the healed flow no longer satisfies its success consequence — refusing to write (a heal that loses the intent would ship a green-but-dead test). Fix by hand and verify',
 };

package/dist/honesty/blind-spots.js

@@ -7,7 +7,7 @@
 // The kind enum lives in core (it crosses the wire in a BLIND_SPOT event); re-exported here so existing
 // honesty-side imports keep working.
 export { BlindSpotKind } from '@reticlehq/core';
-import { BlindSpotKind, EventType } from '@reticlehq/core';
+import { BlindSpotKind, EventType, ReticleEnv, TRANSPORT_LIMITS, } from '@reticlehq/core';
 /**
  * Whether the observation window saw everything it was asked about.
  *
@@ -29,7 +29,11 @@ const LABEL = {
     [BlindSpotKind.VIRTUALIZED_UNMOUNTED]: (n) => `${String(n)} virtualized unmounted row${1 === n ? '' : 's'} unobserved`,
     // Not "some rows we could not see" — the events never reached the observer, so this window is a
     // SAMPLE of what the app did. Phrased as a caveat on what the whole result MEANS.
-    [BlindSpotKind.RATE_LIMITED]: (n) => `${String(n)} event${1 === n ? '' : 's'} dropped by the bridge rate cap, so this window is SAMPLED — raise RETICLE_MAX_MESSAGES_PER_SECOND for a busy app`,
+    // Names a NUMBER, not a variable. "Raise it for a busy app" leaves the reader to invent a value,
+    // and the one who reported this had to guess before finding one that worked. The default was
+    // raised in the same change, so a page still hitting the cap after that is genuinely unusual and
+    // deserves a concrete next value rather than an adjective.
+    [BlindSpotKind.RATE_LIMITED]: (n) => `${String(n)} event${1 === n ? '' : 's'} dropped by the bridge rate cap, so this window is SAMPLED. Set ${ReticleEnv.MAX_MESSAGES_PER_SECOND}=${String(TRANSPORT_LIMITS.MAX_MESSAGES_PER_SECOND * 5)} and restart the daemon, then re-run this drive`,
     // Not a count of things — a single fact about the page. Phrased so the coverage line reads as a
     // caveat on what the network view MEANS, not as a tally.
     // A count of unverifiable ACTIONS, not of things we failed to look at. The distinction matters:

package/dist/honesty/honesty.d.ts

@@ -5,6 +5,7 @@
  * block. Harnesses gate on it (e.g. "grade ≥ net AND integrity clean"). This is pure composition +
  * assessment — all five components already exist individually; wiring it onto results is a later step.
  */
+import type { CaptureLoss } from '@reticlehq/core';
 /** Assertion grade, strongest first — the tier the verdict actually proved. */
 export declare const HonestyGrade: {
     readonly SIGNAL: "signal";
@@ -23,6 +24,15 @@ interface HonestyInputs {
     coveragePartial?: boolean;
     truncated?: boolean;
     blindSpots?: readonly string[];
+    /**
+     * The machine-readable half of `issues` — WHICH kind of loss, from core's closed `CaptureLoss`.
+     *
+     * `issues` is prose built for an agent to read, and prose is not something a dashboard can group
+     * by: `unclean_capture` became a large share of all field verdicts with no way to ask which of its three
+     * causes produced them. Passed by the caller rather than derived here, because only the caller
+     * knows whether a blind-spot note came from the browser transport or from a boundary in the page.
+     */
+    losses?: readonly CaptureLoss[];
 }
 export interface HonestyBlock {
     grade: HonestyGrade;
@@ -40,6 +50,7 @@ export interface HonestyBlock {
     integrity: {
         clean: boolean;
         issues: string[];
+        losses?: CaptureLoss[];
     };
 }
 export declare function buildHonestyBlock(inputs: HonestyInputs): HonestyBlock;

package/dist/honesty/honesty.js

@@ -46,7 +46,15 @@ export function buildHonestyBlock(inputs) {
             ? {}
             : { envelope: { samples, sufficient: samples >= MIN_ENVELOPE_SAMPLES } }),
         coverage: { ...(pct === undefined ? {} : { pct }), partial },
-        integrity: { clean: 0 === issues.length, issues },
+        integrity: {
+            clean: 0 === issues.length,
+            issues,
+            // Only when something was actually lost. An empty array beside `clean: true` would be a field
+            // that is always present and always says nothing, which is how a signal gets tuned out.
+            ...(0 === issues.length || undefined === inputs.losses || 0 === inputs.losses.length
+                ? {}
+                : { losses: [...new Set(inputs.losses)] }),
+        },
     };
 }
 /** Whether a verdict's honesty block clears the harness's bar. Reasons list every failed criterion. */

package/dist/honesty/unsettled.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What an `unsettled` verdict was waiting for, and what its window held instead.
+ *
+ * `unsettled` is the commonest reason a verdict comes back `unknown`, and all it said was that the
+ * page "never settled" — a sentence equally true of a page that polls, a page that animates, and a
+ * page whose write is still open. Those need three different next moves, and an agent handed the
+ * sentence cannot tell which it is holding, so the drive stops there. An `unknown` that explains
+ * itself is a retry; one that does not is a dead end.
+ *
+ * Two releases already tuned this window and neither is undone here. The budget is still spent in
+ * full before anything is called unsettled (settle-in-flight.ts), and the app is still given its
+ * reaction window before any accusation (waitForReaction). This only describes what was true at the
+ * moment the budget genuinely ran out.
+ *
+ * It rides in `because`, beside `verifiedReason`, rather than in a field of its own: the verdict has
+ * one sentence an agent is known to read, and a caveat parked anywhere else is a caveat nobody reads.
+ */
+import type { Predicate } from '../events/predicate.js';
+export interface UnsettledWindow {
+    /** What the wait was for, in the caller's own terms — see `describeWaitTarget`. */
+    waitedFor: string;
+    /** Requests that started in this window and had not come back, as "METHOD url". */
+    stillInFlight: readonly string[];
+}
+/**
+ * The wait, in one phrase.
+ *
+ * The default matters most: a call that declares no `until` waits for the page to go IDLE, and an
+ * agent that never chose that wait cannot be expected to recognise it in a timeout about it.
+ */
+export declare function describeWaitTarget(predicate: Predicate): string;
+/**
+ * The `because` sentence for an unsettled verdict: the wait, the observation, the next move.
+ *
+ * The two branches are the point. An outstanding write is worth waiting for and worth asserting
+ * directly; page churn is neither, and telling an agent to raise its timeout on churn sells it a
+ * slower dead end. Without the detail the sentence is the one that shipped before, so a caller that
+ * cannot supply the facts loses nothing.
+ */
+export declare function unsettledBecause(base: string, window: UnsettledWindow | undefined): string;

package/dist/honesty/unsettled.js

@@ -0,0 +1,78 @@
+/**
+ * What an `unsettled` verdict was waiting for, and what its window held instead.
+ *
+ * `unsettled` is the commonest reason a verdict comes back `unknown`, and all it said was that the
+ * page "never settled" — a sentence equally true of a page that polls, a page that animates, and a
+ * page whose write is still open. Those need three different next moves, and an agent handed the
+ * sentence cannot tell which it is holding, so the drive stops there. An `unknown` that explains
+ * itself is a retry; one that does not is a dead end.
+ *
+ * Two releases already tuned this window and neither is undone here. The budget is still spent in
+ * full before anything is called unsettled (settle-in-flight.ts), and the app is still given its
+ * reaction window before any accusation (waitForReaction). This only describes what was true at the
+ * moment the budget genuinely ran out.
+ *
+ * It rides in `because`, beside `verifiedReason`, rather than in a field of its own: the verdict has
+ * one sentence an agent is known to read, and a caveat parked anywhere else is a caveat nobody reads.
+ */
+import { PredicateKind } from '@reticlehq/core';
+/** Enough to recognise the one that is stuck; not so many that a chatty window eats the verdict. */
+const MAX_LISTED_REQUESTS = 3;
+/**
+ * The wait, in one phrase.
+ *
+ * The default matters most: a call that declares no `until` waits for the page to go IDLE, and an
+ * agent that never chose that wait cannot be expected to recognise it in a timeout about it.
+ */
+export function describeWaitTarget(predicate) {
+    switch (predicate.kind) {
+        case PredicateKind.SETTLED:
+            return 'the page to go idle';
+        case PredicateKind.SIGNAL:
+            return predicate.name === undefined ? 'any signal' : `signal '${predicate.name}'`;
+        case PredicateKind.NET:
+            return `a request${predicate.method === undefined ? '' : ` ${predicate.method}`}${predicate.urlContains === undefined ? '' : ` matching '${predicate.urlContains}'`}`;
+        case PredicateKind.ROUTE:
+            return `a route change${predicate.pathname === undefined ? '' : ` to '${predicate.pathname}'`}${predicate.contains === undefined ? '' : ` containing '${predicate.contains}'`}`;
+        case PredicateKind.STATE:
+            return `state at '${predicate.path}'`;
+        case PredicateKind.TEXT:
+            return `text containing '${predicate.contains}'`;
+        case PredicateKind.ELEMENT:
+            return `an element matching ${JSON.stringify(predicate.query)}`;
+        case PredicateKind.CONSOLE:
+            return 'a console message';
+        case PredicateKind.ANIMATION:
+            return predicate.name === undefined ? 'an animation' : `animation '${predicate.name}'`;
+        case PredicateKind.ALL_OF:
+            return `all of (${predicate.predicates.map(describeWaitTarget).join('; ')})`;
+        case PredicateKind.ANY_OF:
+            return `any of (${predicate.predicates.map(describeWaitTarget).join('; ')})`;
+        case PredicateKind.NOT:
+            return `the absence of ${describeWaitTarget(predicate.predicate)}`;
+    }
+}
+/**
+ * The `because` sentence for an unsettled verdict: the wait, the observation, the next move.
+ *
+ * The two branches are the point. An outstanding write is worth waiting for and worth asserting
+ * directly; page churn is neither, and telling an agent to raise its timeout on churn sells it a
+ * slower dead end. Without the detail the sentence is the one that shipped before, so a caller that
+ * cannot supply the facts loses nothing.
+ */
+export function unsettledBecause(base, window) {
+    if (window === undefined)
+        return `${base} — re-check, or assert a consequence that settles`;
+    if (0 === window.stillInFlight.length) {
+        return (`${base}. It waited for ${window.waitedFor}, and no request started in this window was left ` +
+            'open — what kept the page busy was its own churn (a poll, a timer, an animation), so waiting ' +
+            'longer will not help. Assert the consequence you care about (a signal, a route change, or ' +
+            'store state) instead of waiting for idle, and re-check if the app is genuinely slow');
+    }
+    const shown = window.stillInFlight.slice(0, MAX_LISTED_REQUESTS);
+    const rest = window.stillInFlight.length - shown.length;
+    return (`${base}. It waited for ${window.waitedFor}, and ${String(window.stillInFlight.length)} ` +
+        `request(s) started in this window had not come back: ${shown.join(', ')}` +
+        `${rest > 0 ? `, and ${String(rest)} more` : ''} — re-check once they land, raise timeout_ms, ` +
+        'or assert the request itself so the wait ends on the response rather than on idle');
+}

package/dist/honesty/verified.d.ts

@@ -1,5 +1,6 @@
 import { Verified, VerifiedReason } from '@reticlehq/core';
 import { type HonestyBlock } from './honesty.js';
+import { type UnsettledWindow } from './unsettled.js';
 /**
  * The decision rule: eight trust dimensions in, one answer out.
  *
@@ -51,6 +52,12 @@ interface VerifiedInputs {
      * never read. See `hasUnreadWriteOutcome` — the status line describes the transport, not the result.
      */
     outcomeUnread?: boolean;
+    /**
+     * What the wait was for and what the window held when it ended — read ONLY by the two clauses that
+     * answer UNSETTLED, which is the commonest reason a verdict comes back `unknown` and was also the
+     * least actionable. Optional: without it those clauses say exactly what they said before.
+     */
+    unsettled?: UnsettledWindow;
 }
 interface VerifiedVerdict {
     verified: Verified;