@reticlehq/server 2.9.0 → 2.11.0

package/dist/events/stale-response.js

@@ -91,6 +91,49 @@ function flights(events) {
  */
 const MAX_FLIGHTS_PER_PATH = 60;
 /** The one contradiction, or none. Reported once per window — a race is a fact about the window. */
+/**
+ * How long after a superseded response lands we look for the app reacting to it.
+ *
+ * A handler runs on the microtask that resolves the fetch; the render follows within a frame or two.
+ * Beyond this the connection between the response and any change is speculation.
+ */
+const APPLY_WINDOW_MS = 500;
+/**
+ * How far BEFORE the completion stamp a reaction still counts as reacting to it.
+ *
+ * Not a fudge factor — a correction for which of the two is stamped first. `NET_REQUEST` is emitted
+ * when the observer's wrapper sees the fetch settle, and the app's own handler runs on the same
+ * microtask; in practice the app's state write, signal and DOM text land at or a millisecond BEFORE
+ * the completion event that caused them.
+ *
+ * So a strictly-forward window could not see the application at all, and the rule could never fire on
+ * real traffic however plainly the app misbehaved. Sixteen passing unit tests did not catch that,
+ * because synthetic events are written with the reaction placed after the cause.
+ */
+const APPLY_SLACK_MS = 100;
+/**
+ * Did the app REACT to this response — did anything user-visible move after it landed?
+ *
+ * The question the rule could not previously ask, and the difference between a defect and a
+ * correctly-handled race. An app that guards against superseded responses still RACES: two requests
+ * overlap and settle out of order exactly as before. What it does not do is act on the loser.
+ *
+ * Without this check the rule fires identically on both, which is worse than not having it: a
+ * detector that accuses correct code teaches people to ignore it, and it takes the true positives
+ * down with it.
+ */
+function appliedAfter(events, settledAt) {
+    return events.some((event) => {
+        if (event.t < settledAt - APPLY_SLACK_MS || event.t > settledAt + APPLY_WINDOW_MS)
+            return false;
+        return (event.type === EventType.STATE_CHANGE ||
+            event.type === EventType.SIGNAL ||
+            event.type === EventType.DOM_TEXT ||
+            event.type === EventType.DOM_ADDED ||
+            event.type === EventType.DOM_REMOVED ||
+            event.type === EventType.DOM_ATTR);
+    });
+}
 export function findStaleResponses(events) {
     // Grouped by path first: two reads of DIFFERENT endpoints can never race, and comparing them was
     // the bulk of the work on any real page, which talks to many endpoints at once.
@@ -105,13 +148,13 @@ export function findStaleResponses(events) {
     }
     for (const group of byPath.values()) {
         const reads = group.slice(-MAX_FLIGHTS_PER_PATH);
-        const found = raceIn(reads);
+        const found = raceIn(reads, events);
         if (found !== undefined)
             return [found];
     }
     return [];
 }
-function raceIn(reads) {
+function raceIn(reads, events) {
     for (const first of reads) {
         for (const second of reads) {
             if (first.id === second.id)
@@ -127,6 +170,10 @@ function raceIn(reads) {
             // Parallel pagination is not a race — see differsOnlyByEnumeration.
             if (differsOnlyByEnumeration(queryOf(first.url), queryOf(second.url)))
                 continue;
+            // The race happened. Whether it MATTERS is whether the app acted on the loser — an app that
+            // drops superseded responses races just as visibly and is not broken.
+            if (!appliedAfter(events, first.settledAt))
+                continue;
             return {
                 kind: ContradictionKind.STALE_RESPONSE_APPLIED,
                 claim: `both reads of ${pathOf(first.url)} returned successfully and the page settled`,

package/dist/events/unit-mismatch.d.ts

@@ -1,5 +1,5 @@
 import { type ReticleEvent } from '@reticlehq/core';
-import type { Contradiction } from './contradictions.js';
+import type { OwnContradiction } from './contradictions.js';
 /**
  * @param prior events from BEFORE the window, used only to learn what the API has stated.
  *
@@ -13,4 +13,4 @@ import type { Contradiction } from './contradictions.js';
  * every other rule blame this action for events it did not cause, and would re-report every earlier
  * mistake on every assert.
  */
-export declare function findUnitMismatches(events: readonly ReticleEvent[], prior?: readonly ReticleEvent[]): Contradiction[];
+export declare function findUnitMismatches(events: readonly ReticleEvent[], prior?: readonly ReticleEvent[]): OwnContradiction[];

package/dist/flows/flow-tools.js

@@ -14,6 +14,7 @@ import { resolveProjectCloud } from '../cloud/cloud-config.js';
 import { buildSuiteVerdict } from './decision.js';
 import { classifyFlowAssertions } from './flow-classify.js';
 import { isValidFlowName, flowPath } from '../project/reticle-dir.js';
+import { FlowStore } from './flows.js';
 import { replayNamedFlow, flowErrorMessage, latestRecordedFlow, sessionProjectId, } from './flow-replay-run.js';
 import { persistAndSyncVerificationRun } from '../runs/verification-sync.js';
 import { runServerVerify } from './server-verify.js';
@@ -67,6 +68,24 @@ export function leaseFailureReplay(name, error) {
 }
 /** Stand-in path for a flow whose name fails the path-segment guard — never a real join. */
 const INVALID_FLOW_NAME_PATH = '(invalid flow name — not a usable path)';
+/**
+ * The flow store a SESSION's artifacts belong in, and the root it resolved to.
+ *
+ * `deps.flows` is bound to the daemon's own root at construction, which is right only when the
+ * daemon happens to have been started in the project it is driving. When a resolver is wired and it
+ * names a different project, the write has to go there instead — so the store is rebound for this
+ * call. Rebinding is cheap: a FlowStore is a filesystem port, a root and a clock.
+ *
+ * Returns `deps.flows` unchanged when nothing is wired or the roots already agree, so the common
+ * case allocates nothing and behaves exactly as before.
+ */
+function flowsForSession(deps, projectId) {
+    const resolved = deps.artifactRootFor?.(projectId);
+    if (resolved === undefined || resolved.root === deps.reticleRoot) {
+        return { flows: deps.flows, root: deps.reticleRoot };
+    }
+    return { flows: new FlowStore(deps.fs, resolved.root, { now: deps.now }), root: resolved.root };
+}
 export const FLOW_TOOLS = [
     {
         name: ReticleTool.FLOW_SAVE,
@@ -132,16 +151,26 @@ export const FLOW_TOOLS = [
             const emptyRefusal = emptyFlowRefusal(program.steps.length, name);
             if (emptyRefusal !== undefined)
                 return Promise.resolve(emptyRefusal);
-            return deps.flows.save(program, annotations, projectId).then(async (res) => {
+            const { flows, root } = flowsForSession(deps, projectId);
+            return flows.save(program, annotations, projectId).then(async (res) => {
                 if (!res.ok)
                     return { error: flowErrorMessage(res.code), code: res.code };
                 deps.annotations.clear(name);
                 // Grade the saved flow's assertions so the agent learns immediately if it just saved a flow
                 // that asserts nothing observable (passes even when the feature is broken).
-                const loaded = await deps.flows.load(res.value.name, projectId);
+                const loaded = await flows.load(res.value.name, projectId);
+                // The absolute path, always. A save that reports success and not WHERE cost a reporter a
+                // `find` across their disk to discover it had landed in an unrelated repo. The name came
+                // back from a save that succeeded, so the guard is a type narrowing rather than a doubt.
+                const saved = res.value.name;
+                const path = isValidFlowName(saved) ? flowPath(root, saved, projectId) : undefined;
                 return loaded.ok
-                    ? { ...res.value, assertions: classifyFlowAssertions(loaded.value) }
-                    : res.value;
+                    ? {
+                        ...res.value,
+                        ...(path === undefined ? {} : { path }),
+                        assertions: classifyFlowAssertions(loaded.value),
+                    }
+                    : { ...res.value, ...(path === undefined ? {} : { path }) };
             });
         },
     },
@@ -292,7 +321,7 @@ export const FLOW_TOOLS = [
             unverifiable: z
                 .object({ reason: z.string() })
                 .optional()
-                .describe('Set on an ok replay that cannot fail: the flow asserts no observable consequence, so it passes even when the feature is broken. Same reason reticle_flow_verify reports.'),
+                .describe('Set on an ok replay that cannot fail: the flow asserts no observable consequence, so it passes even when the feature is broken. Same reason reticle_verify{action:"flows"} reports.'),
             decision: z
                 .object({
                 verdict: z.string(),

package/dist/flows/predicate-to-expect.js

@@ -25,6 +25,14 @@ export function predicateToExpect(predicate) {
             return 0 === Object.keys(net).length ? undefined : { net };
         }
         case PredicateKind.CONSOLE: {
+            // `contains` has no representation in FlowExpect.console (core keeps `level` and `absent`
+            // and nothing else). Copying the rest through anyway would record an assertion the agent
+            // never made: {console, level:'warn', contains:'no-op', absent:true} would save "no warn
+            // entries at all", a false red on any unrelated warning, and in the presence direction it
+            // saves a strictly weaker claim than the one chosen. This file's own rule applies: record
+            // nothing rather than something different, so the flow stays assertion-free there instead.
+            if (predicate.contains !== undefined)
+                return undefined;
             const console_ = {};
             if (predicate.level !== undefined)
                 console_.level = predicate.level;

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { sessionRoot } from '../project/session-root.js';
 import { verdictForSuite } from './verify-change-verdict.js';
 import { attributedFailures } from './attributed-failure.js';
 import { Verified } from '@reticlehq/core';
@@ -62,7 +63,10 @@ export const VERIFY_CHANGE_TOOLS = [
                 : [];
             const since = asString(args['since']);
             const changedFiles = await resolveChangedFiles(files, since);
-            const flows = await loadNamedFlows(deps.fs, deps.reticleRoot);
+            // Same root flow_save wrote to. A read that resolved differently would report "no flows
+            // covered this change" over flows that exist, which reads as a clean result rather than
+            // an error, so the disagreement would be invisible.
+            const flows = await loadNamedFlows(deps.fs, sessionRoot(deps, asString(args['sessionId'])));
             const { affected, unknownProvenance } = affectedSavedFlows(flows, changedFiles);
             if (0 === changedFiles.length) {
                 return {
@@ -97,7 +101,7 @@ export const VERIFY_CHANGE_TOOLS = [
             const cursor = cursorBeforeReplay(deps, args);
             const verify = FLOW_TOOLS.find((tool) => tool.name === ReticleTool.FLOW_VERIFY);
             if (verify === undefined)
-                throw new Error('reticle_flow_verify is not registered');
+                throw new Error('the whole-suite replay tool is not registered');
             const suite = asRecord(await verify.handler(deps, {
                 names: affected,
                 ...(asNumber(args['parallel']) === undefined ? {} : { parallel: args['parallel'] }),

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

@@ -84,3 +84,12 @@ export declare function blindSpotsFromState(state: Readonly<Record<string, numbe
 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;
+/**
+ * Is the state channel dark?
+ *
+ * Nothing subscribed means NO state change is observed, so an empty `stateDiffs` is a statement
+ * about Reticle rather than about the app. Derived here, once, because two callers now need it —
+ * the act path's causal summary and the instrumentation-gap surface — and a second spelling of this
+ * predicate would eventually disagree with the first about what "unwatched" means.
+ */
+export declare function isStateUnwatched(spots: readonly BlindSpot[]): boolean;

package/dist/honesty/blind-spots.js

@@ -45,10 +45,12 @@ const LABEL = {
     // nothing here can support. Names the one-line fix, because the reader is the one who can apply it.
     [BlindSpotKind.UNWATCHED_STATE]: () => 'no subscribable store is registered, so NO state change is observed — an empty stateDiffs here means unwatched, not unchanged (register the store itself in your reticle-dev module: registerStore(name, store), not a getter)',
     [BlindSpotKind.WRAPPED_NETWORK]: () => 'fetch was already wrapped before Reticle, so recorded requests may differ from what was sent',
-    // A fact about the app's wiring, not a tally. Says what the empty network view MEANS, because an
-    // empty one here is indistinguishable from "this app made no backend calls" — and that reading is
-    // the false green: every IPC call went unseen and every `assert { net }` over them is vacuous.
-    [BlindSpotKind.UNOBSERVED_IPC]: () => "this Electron renderer has no Reticle preload, so NO ipcRenderer.invoke is observed — an empty network view here means unseen, not none (add require('@reticlehq/electron/preload') to your preload)",
+    // A fact about the app's wiring, not a tally. Says what a network view WITHOUT ipc:// records
+    // MEANS, because that state here is indistinguishable from "this app made no backend calls" —
+    // and that reading is the false green: every IPC call went unseen and every `assert { net }` over
+    // them is vacuous. Document-initiated loads ARE seen since subresource observation (#447), so
+    // the note names the missing half instead of claiming the whole view is blind.
+    [BlindSpotKind.UNOBSERVED_IPC]: () => "this Electron renderer has no Reticle preload, so NO ipcRenderer.invoke is observed; document-initiated loads may still appear, so a view with no ipc:// records means unseen IPC, not none (add require('@reticlehq/electron/preload') to your preload)",
 };
 /**
  * Blind spots that IMPEACH the capture, as opposed to bounding what it covers.
@@ -150,3 +152,14 @@ export function transportGapNote(events) {
         ? undefined
         : `the browser dropped ${String(dropped)} event(s) in this window (transport queue overflow), so events that would have contradicted this may never have arrived`;
 }
+/**
+ * Is the state channel dark?
+ *
+ * Nothing subscribed means NO state change is observed, so an empty `stateDiffs` is a statement
+ * about Reticle rather than about the app. Derived here, once, because two callers now need it —
+ * the act path's causal summary and the instrumentation-gap surface — and a second spelling of this
+ * predicate would eventually disagree with the first about what "unwatched" means.
+ */
+export function isStateUnwatched(spots) {
+    return spots.some((spot) => spot.kind === BlindSpotKind.UNWATCHED_STATE && spot.count > 0);
+}

package/dist/honesty/gap-ledger.d.ts

@@ -0,0 +1,52 @@
+import { type InstrumentationGap } from '@reticlehq/core';
+/**
+ * What this session still cannot see, accumulated across its verdicts.
+ *
+ * A gap reported on one verdict and then forgotten is a note. A gap that is still standing when the
+ * agent asks "am I done?" is a piece of work — and that difference is the entire discipline
+ * mechanism, because an agent finishing a task is the one moment it will act on a cost it can close.
+ *
+ * ## Why the LAST verdict decides, not the whole history
+ *
+ * The honest question is "is this app still unverifiable in this way", not "was it ever". An agent
+ * that hits a gap, adds the build plugin and re-verifies has CLOSED it — the later verdict simply
+ * stops emitting that kind — and a ledger that still reported it would punish exactly the behaviour
+ * this exists to cause. Nobody instruments an app twice for a tool that never notices the first time.
+ *
+ * So `open()` reflects the most recent verdict, and `everSeen` is kept separately for the summary,
+ * where "you hit this and fixed it" is worth saying and is not a reason to withhold done.
+ */
+export declare class GapLedger {
+    #private;
+    /**
+     * Record what the verdict just reported. An empty list is a real observation — it is how a gap
+     * gets closed — so it must not be ignored as "nothing to record".
+     */
+    note(gaps: readonly InstrumentationGap[]): void;
+    /** Gaps the most recent verdict still reported. The ones that are work right now. */
+    open(): readonly InstrumentationGap[];
+    /** Every kind seen in this session, including ones since closed. */
+    get everSeen(): readonly string[];
+    /**
+     * Did this session leave the app less verifiable than it could be?
+     *
+     * The one question a "have I finished" call needs answered, and the one a session summary turns
+     * into `unproven` rather than `verified`.
+     */
+    get hasOpen(): boolean;
+}
+/**
+ * Record a verdict's gaps against the session that produced it.
+ *
+ * Tolerates a session with no ledger, and that is a statement about the seam rather than a hedge:
+ * `Session` is satisfied structurally, and dozens of specs — plus any consumer embedding this engine
+ * — build one as an object literal rather than through the constructor. Such a session is a real
+ * caller, it simply keeps no ledger, and recording is a side effect that must never be the reason a
+ * verdict fails to return.
+ *
+ * One helper rather than an optional-chain at each call site: the tolerance is a decision, and a
+ * decision spelled `?.` in two places is one nobody can find later.
+ */
+export declare function noteSessionGaps(session: {
+    gaps?: GapLedger;
+}, gaps: readonly InstrumentationGap[]): void;

package/dist/honesty/gap-ledger.js

@@ -0,0 +1,63 @@
+import { dedupeGaps } from '@reticlehq/core';
+/**
+ * What this session still cannot see, accumulated across its verdicts.
+ *
+ * A gap reported on one verdict and then forgotten is a note. A gap that is still standing when the
+ * agent asks "am I done?" is a piece of work — and that difference is the entire discipline
+ * mechanism, because an agent finishing a task is the one moment it will act on a cost it can close.
+ *
+ * ## Why the LAST verdict decides, not the whole history
+ *
+ * The honest question is "is this app still unverifiable in this way", not "was it ever". An agent
+ * that hits a gap, adds the build plugin and re-verifies has CLOSED it — the later verdict simply
+ * stops emitting that kind — and a ledger that still reported it would punish exactly the behaviour
+ * this exists to cause. Nobody instruments an app twice for a tool that never notices the first time.
+ *
+ * So `open()` reflects the most recent verdict, and `everSeen` is kept separately for the summary,
+ * where "you hit this and fixed it" is worth saying and is not a reason to withhold done.
+ */
+export class GapLedger {
+    #open = [];
+    #everSeen = new Set();
+    /**
+     * Record what the verdict just reported. An empty list is a real observation — it is how a gap
+     * gets closed — so it must not be ignored as "nothing to record".
+     */
+    note(gaps) {
+        this.#open = dedupeGaps(gaps);
+        for (const gap of gaps)
+            this.#everSeen.add(gap.kind);
+    }
+    /** Gaps the most recent verdict still reported. The ones that are work right now. */
+    open() {
+        return this.#open;
+    }
+    /** Every kind seen in this session, including ones since closed. */
+    get everSeen() {
+        return [...this.#everSeen];
+    }
+    /**
+     * Did this session leave the app less verifiable than it could be?
+     *
+     * The one question a "have I finished" call needs answered, and the one a session summary turns
+     * into `unproven` rather than `verified`.
+     */
+    get hasOpen() {
+        return this.#open.length > 0;
+    }
+}
+/**
+ * Record a verdict's gaps against the session that produced it.
+ *
+ * Tolerates a session with no ledger, and that is a statement about the seam rather than a hedge:
+ * `Session` is satisfied structurally, and dozens of specs — plus any consumer embedding this engine
+ * — build one as an object literal rather than through the constructor. Such a session is a real
+ * caller, it simply keeps no ledger, and recording is a side effect that must never be the reason a
+ * verdict fails to return.
+ *
+ * One helper rather than an optional-chain at each call site: the tolerance is a decision, and a
+ * decision spelled `?.` in two places is one nobody can find later.
+ */
+export function noteSessionGaps(session, gaps) {
+    session.gaps?.note(gaps);
+}

package/dist/honesty/instrumentation-gaps.d.ts

@@ -0,0 +1,55 @@
+import { type InstrumentationGap } from '@reticlehq/core';
+/**
+ * The gaps ONE action revealed, derived from facts the act path already holds.
+ *
+ * Pure, and deliberately fed by primitives rather than by the action result: every fact below is
+ * already computed for other reasons — `actedSource` for the red-verdict file:line, `stateUnwatched`
+ * because an empty `stateDiffs` would otherwise read as "the app changed nothing", the signal count
+ * and route movement for the causal summary. Nothing here costs a new observation. The gap surface
+ * is a second reading of evidence Reticle was already collecting and then discarding.
+ *
+ * ## Each kind carries its OWN gate
+ *
+ * The rule is that a gap fires only when the verdict came back weaker because of it — and "weaker"
+ * is different per kind, so a single global flag would be a lie in both directions:
+ *
+ *  - a missing source mapping costs nothing on a PASS. The act path already says so in as many
+ *    words: on green nobody needs the file:line and it is noise. It costs a great deal on a red,
+ *    where it is the first thing the agent wants;
+ *  - a missing store costs nothing unless the caller ASKED about state;
+ *  - a silent mutation costs nothing if the app proved the outcome some other way.
+ *
+ * Encoding the gates per kind is what keeps this from degenerating into a linter that fires on every
+ * uninstrumented control on the page. That surface would be ignored within a day, and it would take
+ * the true positives with it.
+ */
+export interface ActionInstrumentationFacts {
+    /** Did the verdict pass? Several gates turn on this, in different directions. */
+    pass: boolean;
+    /** True when the outcome was positively PROVED rather than inferred. */
+    proved?: boolean;
+    /**
+     * Does Reticle know a `file:line` for what this verdict is about?
+     *
+     * A boolean rather than the source itself, deliberately: the act path holds a `{file, line}` and
+     * the assert path holds a formatted string it remembered from the last act. The gap does not care
+     * which — only whether the agent can be pointed at code — and taking the shape would make one of
+     * the two callers convert for no reason.
+     */
+    sourceKnown: boolean;
+    /** The ref that was driven, for the report. */
+    ref?: string | undefined;
+    /** Did the caller's predicate ask about registered state? */
+    stateAsked: boolean;
+    /** True when the session has no store registered to read. */
+    stateUnwatched: boolean;
+    /** Did the DOM move in this action's window? */
+    domMutated: boolean;
+    /** How many app signals fired in the window. */
+    signalsFired: number;
+    /** Did the route change in this action's window? */
+    routeChanged: boolean;
+    /** Did anything signal that route change? */
+    routeSignalFired: boolean;
+}
+export declare function gapsForAction(facts: ActionInstrumentationFacts): InstrumentationGap[];

package/dist/honesty/instrumentation-gaps.js

@@ -0,0 +1,21 @@
+import { InstrumentationGapKind, dedupeGaps, instrumentationGap, } from '@reticlehq/core';
+export function gapsForAction(facts) {
+    const gaps = [];
+    // A red verdict names the control and cannot name the line that renders it. That is the round trip
+    // the agent is about to spend, and the one a build plugin removes permanently.
+    if (!facts.pass && !facts.sourceKnown) {
+        gaps.push(instrumentationGap(InstrumentationGapKind.NO_SOURCE_MAPPING, 'the control that was driven carries no source mapping', 'this verdict can name the control but not the file and line that render it, so finding the code is a separate search', { ...(facts.ref === undefined ? {} : { ref: facts.ref }) }));
+    }
+    // Asked about state, and there is no state channel to answer from.
+    if (facts.stateAsked && facts.stateUnwatched) {
+        gaps.push(instrumentationGap(InstrumentationGapKind.NO_STORE_REGISTERED, 'no store is registered, and this assertion was about state', 'the assertion could not be answered from the deterministic channel and had to fall back to what the DOM happens to show'));
+    }
+    // The app moved and said nothing, and Reticle could not prove the outcome another way.
+    if (facts.domMutated && 0 === facts.signalsFired && true !== facts.proved) {
+        gaps.push(instrumentationGap(InstrumentationGapKind.NO_SIGNAL_ON_MUTATION, 'the DOM changed and no signal fired for it', 'the outcome had to be inferred from the DOM instead of read from the app asserting its own success, which is the strongest evidence available', { ...(facts.ref === undefined ? {} : { ref: facts.ref }) }));
+    }
+    if (facts.routeChanged && !facts.routeSignalFired) {
+        gaps.push(instrumentationGap(InstrumentationGapKind.NO_ROUTE_SIGNAL, 'the route changed and nothing signalled it', 'route consequences cannot be asserted on this app, so a navigation can only be checked by what rendered afterwards'));
+    }
+    return dedupeGaps(gaps);
+}

package/dist/honesty/observability.d.ts

@@ -0,0 +1,37 @@
+import type { InstrumentationGap } from '@reticlehq/core';
+/**
+ * Of the controls this session drove, how many could Reticle fully observe?
+ *
+ * The first honest denominator this product has ever had. `reticle_verify{action:"coverage"}`
+ * already answers "which controls did you not drive"; this answers the question underneath it —
+ * *of the ones you did drive, how many could the app actually answer for?* A high untouched-count is
+ * work remaining for the agent. A low observability is work remaining in the APP, and no amount of
+ * driving closes it.
+ *
+ * ## Two things it deliberately refuses to do
+ *
+ * **It does not report a percentage for an empty run.** 0/0 rendered as 100% is the most flattering
+ * possible reading of no evidence at all, and a coverage number that starts perfect is one nobody
+ * believes the first time it drops.
+ *
+ * **It does not count app-level gaps against a control.** An unregistered store or an unsignalled
+ * route is missing from the application, not from a button. Attributing it to whichever control
+ * happened to be driven would put the number on the wrong thing and make it move for reasons the
+ * agent cannot act on. Those gaps are reported alongside, not divided into.
+ */
+export interface Observability {
+    /** Distinct controls driven this session. */
+    driven: number;
+    /** How many of them Reticle could fully observe. */
+    observable: number;
+    /** Rounded percentage. OMITTED when nothing was driven — see above. */
+    percent?: number;
+}
+export declare function observabilityOf(drivenRefs: Iterable<string>, gaps: readonly InstrumentationGap[]): Observability;
+export interface CoverageRegression {
+    was: number;
+    now: number;
+}
+export declare function coverageRegressed(best: {
+    percent: number;
+} | undefined, current: Observability): CoverageRegression | undefined;

package/dist/honesty/observability.js

@@ -0,0 +1,40 @@
+export function observabilityOf(
+// Iterable, not an array: the session holds these as a Set, and making the caller spread it would
+// be a conversion that exists only to satisfy a signature.
+drivenRefs, gaps) {
+    const driven = new Set(drivenRefs);
+    const impaired = new Set();
+    for (const gap of gaps) {
+        // App-level gaps carry no ref, and a gap on a control this session never drove is about some
+        // earlier route — neither belongs in a ratio over what WAS driven.
+        if (gap.ref !== undefined && driven.has(gap.ref))
+            impaired.add(gap.ref);
+    }
+    const observable = driven.size - impaired.size;
+    if (0 === driven.size)
+        return { driven: 0, observable: 0 };
+    return { driven: driven.size, observable, percent: Math.round((observable / driven.size) * 100) };
+}
+/**
+ * The floor under the number, shipped with it rather than after it.
+ *
+ * A coverage figure with no downgrade check is a figure that gets gamed, and we would be the ones
+ * teaching agents to game it: the cheapest way to stop a gap firing is to stop asserting the thing
+ * that revealed it. The same reasoning already runs for flow assertions in `assertion-tiers-store`,
+ * where a flow that passes more weakly than it used to is a finding rather than a pass.
+ *
+ * Returns undefined — not a false — when there is nothing honest to compare. A first run has no
+ * best to fall from, and a run that drove almost nothing is evidence of a short session rather than
+ * of a regression.
+ */
+/** Below this, a run is too small for its ratio to mean anything. */
+const MIN_DRIVEN_TO_COMPARE = 3;
+export function coverageRegressed(best, current) {
+    if (best === undefined)
+        return undefined;
+    if (current.percent === undefined)
+        return undefined;
+    if (current.driven < MIN_DRIVEN_TO_COMPARE)
+        return undefined;
+    return current.percent < best.percent ? { was: best.percent, now: current.percent } : undefined;
+}

package/dist/honesty/verified.js

@@ -133,7 +133,23 @@ export function decideVerified(inputs) {
     // A vacuous green: nothing was actually proved. Grade NONE means no signal, no request, no state
     // change and no element was pinned — the assertion could not have failed, which makes passing it
     // evidence of nothing.
+    // Two different facts used to share this answer. Everything above has already ruled out a failure,
+    // a contradiction, a dirty capture, a pending write and an unread one — so when the window ALSO
+    // settled, the engine did not fail to see: it saw the whole window, ran every oracle, and found
+    // nothing wrong. That is `no-fault`, and telling it apart from "I could not see" is the difference
+    // between "assert something" and "look again with better coverage".
+    //
+    // Gated on `true === settled` rather than on a caller's say-so. A call that returned before the app
+    // stopped moving has not earned this, whatever it declared — which is what stops `no-fault` from
+    // becoming the green-forever button an always-available "nothing was wrong" would be.
     if (honesty.grade === HonestyGrade.NONE) {
+        if (true === settled) {
+            return {
+                verified: Verified.NO_FAULT,
+                verifiedReason: VerifiedReason.NOTHING_DECLARED,
+                because: 'the page settled and no channel reported a problem, but nothing was declared to prove — this is not verification. Assert a consequence the action CHANGES (a signal, a request, a route, or store state) to get one',
+            };
+        }
         return {
             verified: Verified.UNKNOWN,
             verifiedReason: VerifiedReason.VACUOUS_GRADE,

package/dist/index.d.ts

@@ -28,6 +28,24 @@ export { VisualStore } from './visual/visual-store.js';
 export { diffPng } from './visual/visual-diff.js';
 export type { VisualDiffResult, VisualRect, DiffOptions } from './visual/visual-diff.js';
 export { crawl } from './crawl/crawl.js';
+/**
+ * The contradiction pass, and the seam a consumer adds its own rules through.
+ *
+ * Exported because a service embedding this engine grades a recording the same way the tools do, and
+ * without these it would have to re-implement the fold — a second implementation of the one thing
+ * this product is judged on, and the one nobody dogfoods is the one that rots.
+ */
+export { findContradictions } from './events/contradictions.js';
+/**
+ * The MCP server factory, so a consumer can serve the tool surface it composed.
+ *
+ * Without this the composition seam is unreachable from outside the package: a consumer can build the
+ * list and has nothing to hand it to.
+ */
+export { createMcpServer } from './mcp/mcp.js';
+export type { Contradiction, ContradictionOptions } from './events/contradictions.js';
+export { registerContradictionFold, registeredContradictionFolds, } from './events/contradiction-folds.js';
+export type { ContradictionFold } from './events/contradiction-folds.js';
 export { MCP_SSE_PATH, MCP_MESSAGE_PATH } from '@reticlehq/core';
 export { BrowserPool, DEFAULT_LEASE_TTL_MS } from './pool/browser-pool.js';
 export type { Lease, Launcher, PooledBrowser } from './pool/browser-pool.js';
@@ -133,7 +151,6 @@ export interface RunningServer {
     close: () => Promise<void>;
 }
 export { resolveBridgeSecurity } from './bridge/bridge-security.js';
-/** Start the Reticle bridge (browser WS endpoint) and, by default, the MCP stdio server. */
 export declare function start(options?: StartOptions): Promise<RunningServer>;
 /**
  * Start the Reticle bridge in daemon mode: a single HTTP server handles both the WebSocket