@reticlehq/server 2.10.0 → 2.12.0

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

@@ -3,6 +3,10 @@ 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, unverifiableReason } from './decision.js';
+import { classifyFlowAssertions } from './flow-classify.js';
+import { dischargeFlowIntent, flowIntentStatement, flowReplayVerdictId } from './flow-intent.js';
+import { IntentStore } from '../intent/intent-store.js';
+import { sessionRoot } from '../project/session-root.js';
 import { waitForPredicate } from '../events/predicate.js';
 import { computeSegments } from '../journal/rollups.js';
 import { AssertionTiersStore } from './assertion-tiers-store.js';
@@ -10,7 +14,7 @@ import { toFlowSources } from './flow-sources.js';
 import { reportAndAccumulate } from '../journal/deviation-service.js';
 import { EnvelopeStore } from '../journal/envelope-store.js';
 import { homedir } from 'node:os';
-import { syncRunRecordToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { cloudFetch, syncRunRecordToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
 import { log } from '../log.js';
 export function latestRecordedFlow(events) {
@@ -66,7 +70,7 @@ async function recordReplayRun(deps, name, status, driftSteps, durationMs, proje
     const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
     if (null === cloud.config || !cloud.policy.memory)
         return; // not attached / memory disabled → local only
-    const result = await syncRunRecordToCloud({ kind: RunKind.FLOW_REPLAY, name, status: runStatus, at: deps.now(), durationMs }, projectId, cloud.config, (url, init) => fetch(url, init));
+    const result = await syncRunRecordToCloud({ kind: RunKind.FLOW_REPLAY, name, status: runStatus, at: deps.now(), durationMs }, projectId, cloud.config, cloudFetch);
     if (result.outcome !== SyncOutcome.SYNCED) {
         log('cloud-run-record-sync-failed', { flow: name, status: result.status, error: result.error });
     }
@@ -120,6 +124,13 @@ export async function replayNamedFlow(deps, args) {
             error: { code: loaded.code, message: flowErrorMessage(loaded.code) },
         };
     }
+    // What this flow is FOR, from the shared ledger — so a failure can report the business outcome
+    // that stopped being true before the step that stopped being green. Undefined when nothing
+    // declared one, which the decision then says plainly rather than inventing a goal from step names.
+    const intents = new IntentStore(deps.fs, sessionRoot(deps, asString(args['sessionId'])), {
+        now: deps.now,
+    });
+    const intentSaid = await flowIntentStatement(intents, loaded.value);
     const session = deps.sessions.resolve(asString(args['sessionId']));
     // Captured before replay: if the tab isn't on the flow's start page, a step-1 drift is a wrong-page
     // symptom, not a regression — surface that on the decision instead of a bare "a step no longer matches".
@@ -156,6 +167,18 @@ export async function replayNamedFlow(deps, args) {
         })), 
         // Record what this flow COVERS so a later deletion can be scoped to the files that changed.
         toFlowSources([{ name, steps: loaded.value.steps }])[0]?.sources ?? []);
+        // The ledger learns what this run proved. Only a flow that COULD have gone red discharges: an
+        // assertion-free flow is never bound, and `dischargeIntent` refuses an unbound intent, so the
+        // guard here is the cheap half of a rule the ledger already enforces. `grade` is what makes a
+        // later weakening visible — an intent re-proved by a weaker flow says so in the git diff.
+        if (unverifiableReason(loaded.value) === undefined) {
+            const provedAt = deps.now();
+            await dischargeFlowIntent(intents, loaded.value, {
+                verdictId: flowReplayVerdictId(name, provedAt),
+                grade: classifyFlowAssertions(loaded.value).grade,
+                at: provedAt,
+            });
+        }
     }
     // Push-default: the deviation report over this drive's segments, learned across runs. Best-effort.
     const deviation = await computeReplayDeviation(deps, session, replayFloor);
@@ -167,7 +190,7 @@ export async function replayNamedFlow(deps, args) {
             steps,
             error: { code: ReplayStatus.ERROR, message: failed.error ?? 'flow action failed' },
         };
-        errored.decision = buildDecision(errored, loaded.value);
+        errored.decision = buildDecision(errored, loaded.value, intentSaid);
         applyStartPathHint(errored, startPathHint);
         if (deviation !== undefined)
             errored.deviation = deviation;
@@ -182,7 +205,7 @@ export async function replayNamedFlow(deps, args) {
     if (cannotFail !== undefined)
         result.unverifiable = { reason: cannotFail };
     if (status !== ReplayStatus.OK)
-        result.decision = buildDecision(result, loaded.value);
+        result.decision = buildDecision(result, loaded.value, intentSaid);
     applyStartPathHint(result, startPathHint);
     if (deviation !== undefined)
         result.deviation = deviation;

package/dist/flows/flow-success.js

@@ -38,9 +38,21 @@ export function successLabel(success) {
 export function successToPredicate(success, dynamic) {
     const parts = [];
     if (success.signal !== undefined) {
-        parts.push(success.signalData !== undefined
-            ? { kind: PredicateKind.SIGNAL, name: success.signal, dataMatches: success.signalData }
-            : { kind: PredicateKind.SIGNAL, name: success.signal });
+        const signal = {
+            kind: PredicateKind.SIGNAL,
+            name: success.signal,
+        };
+        if (success.signalData !== undefined)
+            signal.dataMatches = success.signalData;
+        if (success.signalCount !== undefined) {
+            signal.count = success.signalCount;
+            // Same post-settle reasoning as net.count: the success waiter is wait-until-true, so an exact
+            // count is transiently satisfied the instant the FIRST matching signal fires — before a
+            // double-fire's duplicate arrives. Gating on `settled` forces the count to be read only after
+            // the app goes quiet, by which point the duplicate IS counted and the over-count fails.
+            parts.push({ kind: PredicateKind.SETTLED });
+        }
+        parts.push(signal);
     }
     if (success.net !== undefined) {
         const net = { kind: PredicateKind.NET };

package/dist/flows/flow-tools.js

@@ -6,7 +6,7 @@ import { recordSuiteFlakes } from './suite-flakes.js';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
 import { log } from '../log.js';
-import { syncFlowToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { cloudFetch, syncFlowToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 import { mapWithConcurrency, resolveConcurrency } from './parallel-suite.js';
 import { acquireLeasedSession } from '../tools/lease-tools.js';
 import { homedir } from 'node:os';
@@ -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';
@@ -29,7 +30,7 @@ async function syncSavedFlowToCloud(deps, flow, projectId) {
     const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
     if (null === cloud.config || !cloud.policy.flows)
         return; // not attached / flows disabled → local only
-    const result = await syncFlowToCloud(flow, cloud.config, projectId, (url, init) => fetch(url, init));
+    const result = await syncFlowToCloud(flow, cloud.config, projectId, cloudFetch);
     if (result.outcome !== SyncOutcome.SYNCED) {
         log('cloud-flow-sync-failed', { flow: flow.name, status: result.status, error: result.error });
     }
@@ -67,6 +68,35 @@ 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 };
+}
+/**
+ * How a save reports that nobody said what the flow is for.
+ *
+ * Declared once and shared by every save tool: an undeclared field is stripped from
+ * `structuredContent` by a schema-strict MCP client, so a save path that forgot this line would
+ * report the nudge to the unit tests and to nobody else.
+ */
+const INTENT_GAP_FIELD = z
+    .unknown()
+    .optional()
+    .describe('Present ONLY when the flow was saved with nothing saying what it is for: { kind, missing, cost, fix }. The flow is on disk either way — this never blocks a save. Close it by saving again with `intent`, or by setting the flow file’s `intentId` to an intent already in the ledger. Nothing here is ever derived from the flow name, the steps or the assertions: a guessed goal reads as the author’s own words.');
 export const FLOW_TOOLS = [
     {
         name: ReticleTool.FLOW_SAVE,
@@ -79,6 +109,10 @@ export const FLOW_TOOLS = [
             flowName: z
                 .string()
                 .describe('Name for the flow file (saved to .reticle/flows/<flowName>.json). Use again in reticle_flow{action:"load"} / reticle_flow_replay.'),
+            intent: z
+                .string()
+                .optional()
+                .describe('What this flow is FOR, in prose: which user does what, and what should become true. Answer it here rather than in a second call. Without it the flow still saves, but the day it goes red the report can only name the step that broke, not the thing that stopped being true.'),
             sessionId: z
                 .string()
                 .optional()
@@ -105,6 +139,7 @@ export const FLOW_TOOLS = [
                 warning: z.string().optional(),
             })
                 .optional(),
+            intentGap: INTENT_GAP_FIELD,
             error: z.string().optional(),
             code: z.string().optional(),
         },
@@ -119,7 +154,9 @@ export const FLOW_TOOLS = [
             }
             // fold any structured annotations (expect/dynamic/success/intent) onto the saved flow.
             const success = deps.annotations.success(name);
-            const intent = deps.annotations.intent(name);
+            // The inline argument wins over an annotation left from an earlier call: it is the more recent
+            // statement, and it is the one the author just typed.
+            const intent = asString(args['intent']) ?? deps.annotations.intent(name);
             const annotations = {
                 stepExpect: deps.annotations.stepExpect(name),
                 dynamic: deps.annotations.dynamic(name),
@@ -132,16 +169,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 }) };
             });
         },
     },
@@ -448,6 +495,10 @@ export const FLOW_TOOLS = [
                 .string()
                 .optional()
                 .describe('Override the flow name embedded in the recorded flow. Omit to use the recorder-assigned name.'),
+            intent: z
+                .string()
+                .optional()
+                .describe('What this flow is FOR, in prose: which user does what, and what should become true. The recorder captures clicks, not goals, so this is the only place the goal can come from. Without it the flow still saves, but the day it goes red the report can only name the step that broke.'),
             ...{
                 sessionId: z
                     .string()
@@ -462,6 +513,7 @@ export const FLOW_TOOLS = [
             stepCount: z.number().optional(),
             degraded: z.number().optional(),
             empty: z.boolean().optional(),
+            intentGap: INTENT_GAP_FIELD,
             error: z.string().optional(),
             code: z.string().optional(),
         },
@@ -475,7 +527,12 @@ export const FLOW_TOOLS = [
                 };
             }
             const override = asString(aliasParam(args, 'flowName', ['flow'])['flowName']);
-            const flow = override !== undefined ? { ...recorded.flow, name: override } : recorded.flow;
+            const intent = asString(args['intent']);
+            const flow = {
+                ...recorded.flow,
+                ...(override === undefined ? {} : { name: override }),
+                ...(intent === undefined ? {} : { intent }),
+            };
             // The store stamps the project into the file AND routes it to the per-project subdir (a shared
             // daemon serves many apps), so location and content agree from one source of truth.
             const emptyRecorded = emptyFlowRefusal(flow.steps.length, flow.name);

package/dist/flows/flows.d.ts

@@ -1,5 +1,5 @@
 import { FlowErrorCode } from '@reticlehq/core';
-import type { FlowAnchor, FlowExpect, FlowFile, FlowStep, HealChange } from '@reticlehq/core';
+import type { FlowAnchor, FlowExpect, FlowFile, FlowStep, HealChange, InstrumentationGap } from '@reticlehq/core';
 import type { CompiledProgram, RecordedStep } from './recordings.js';
 import type { FileSystemPort } from '../project/fs-port.js';
 /** A monotonic clock injected for createdAt — never call Date.now inside the store (rule 7). */
@@ -30,6 +30,11 @@ interface SaveSummary {
     stepCount: number;
     degraded: number;
     empty: boolean;
+    /**
+     * Present only when the flow was saved with nothing saying what it is for. Never blocks the save,
+     * and absent the moment the flow carries prose or an `intentId`. See `flowIntentGap`.
+     */
+    intentGap?: InstrumentationGap;
 }
 /**
  * The structured annotations folded onto a flow at save time: per-step

package/dist/flows/flows.js

@@ -3,6 +3,8 @@ import { AnchorKind, DEGRADED_ANCHOR_ROLE, FLOW_FILE_VERSION, FlowErrorCode, Flo
 import { ReticleTool } from '../tools/tool-names.js';
 import { asString, asRecord } from '../tools/tools-helpers.js';
 import { applyHealChanges } from './heal.js';
+import { flowIntentGap, linkFlowIntent } from './flow-intent.js';
+import { IntentStore } from '../intent/intent-store.js';
 import { flowDir, flowPath, reticleDirPaths, isValidFlowName } from '../project/reticle-dir.js';
 /**
  * A projectId only scopes storage when it's a safe single path segment (it's stamped from the
@@ -168,6 +170,34 @@ export class FlowStore {
     #serialize(flow) {
         return `${JSON.stringify(flow, null, JSON_INDENT)}\n`;
     }
+    /**
+     * Register the flow's business goal in the intent ledger and stamp the row's id onto the flow.
+     *
+     * Both save paths route through here — the compiled-recording one and the in-page recorder one —
+     * because a flow's goal must land in the ledger whichever way the flow arrived. A flow with no
+     * goal is returned untouched and nothing is written, so an older flow keeps its exact bytes.
+     */
+    #linkIntent(flow) {
+        return linkFlowIntent(new IntentStore(this.#fs, this.#root, this.#clock), flow);
+    }
+    /**
+     * What a caller is told about a flow that just landed on disk.
+     *
+     * Both save paths build it here rather than each assembling their own object, because the two used
+     * to be duplicates and the intent nudge is exactly the kind of field that gets added to one of a
+     * pair. A flow saved by the recorder and a flow saved from a compiled recording are the same
+     * regression test, and must not report differently for having arrived by a different door.
+     */
+    #summary(flow) {
+        const gap = flowIntentGap(flow);
+        return {
+            name: flow.name,
+            stepCount: flow.steps.length,
+            degraded: flow.steps.filter((s) => true === s.degraded).length,
+            empty: 0 === flow.steps.length,
+            ...(gap === undefined ? {} : { intentGap: gap }),
+        };
+    }
     /**
      * Convert a CompiledProgram (testid-normalized) into an anchored, on-disk flow + write it.
      * Optionally fold structured annotations (per-step expect, dynamic[], success) onto
@@ -186,19 +216,10 @@ export class FlowStore {
             createdAt: this.#clock.now(),
             steps,
         };
-        const flow = withAnnotations(base, annotations);
+        const flow = await this.#linkIntent(withAnnotations(base, annotations));
         await this.#fs.mkdir(flowDir(this.#root, pid));
         await this.#fs.writeFile(flowPath(this.#root, program.name, pid), this.#serialize(flow));
-        const degraded = flow.steps.filter((s) => true === s.degraded).length;
-        return {
-            ok: true,
-            value: {
-                name: program.name,
-                stepCount: flow.steps.length,
-                degraded,
-                empty: 0 === flow.steps.length,
-            },
-        };
+        return { ok: true, value: this.#summary(flow) };
     }
     /**
      * Persist an already-anchored FlowFile captured in-page (no recompilation). The
@@ -215,19 +236,10 @@ export class FlowStore {
         const parsed = FlowFileSchema.safeParse(stamped);
         if (!parsed.success)
             return { ok: false, code: FlowErrorCode.PARSE_FAILED };
-        const valid = parsed.data;
+        const valid = await this.#linkIntent(parsed.data);
         await this.#fs.mkdir(flowDir(this.#root, pid));
         await this.#fs.writeFile(flowPath(this.#root, asFlowName(valid.name), pid), this.#serialize(valid));
-        const degraded = valid.steps.filter((s) => true === s.degraded).length;
-        return {
-            ok: true,
-            value: {
-                name: valid.name,
-                stepCount: valid.steps.length,
-                degraded,
-                empty: 0 === valid.steps.length,
-            },
-        };
+        return { ok: true, value: this.#summary(valid) };
     }
     /**
      * Apply confident testid rebinds to an on-disk flow (the reticle_flow_heal

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

@@ -8,9 +8,12 @@ export function predicateToExpect(predicate) {
         case PredicateKind.SIGNAL: {
             if (predicate.name === undefined)
                 return undefined;
-            return predicate.dataMatches === undefined
-                ? { signal: predicate.name }
-                : { signal: predicate.name, signalData: predicate.dataMatches };
+            const signal = { signal: predicate.name };
+            if (predicate.dataMatches !== undefined)
+                signal.signalData = predicate.dataMatches;
+            if (predicate.count !== undefined)
+                signal.signalCount = predicate.count;
+            return signal;
         }
         case PredicateKind.NET: {
             const net = {};
@@ -25,6 +28,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/server-verify.js

@@ -1,5 +1,6 @@
 import { VerifyMode } from '../cloud/cloud-config.js';
-import { submitServerVerification } from '../cloud/cloud-sync.js';
+import { CLOUD_VERIFY_TIMEOUT_MS, cloudFetch, submitServerVerification, } from '../cloud/cloud-sync.js';
+import { log } from '../log.js';
 const PASS = 'pass';
 const UNVERIFIED = 'unverified';
 const SOURCE = 'reticle-mcp';
@@ -31,7 +32,20 @@ export async function runServerVerify(deps, cloud, sessionId, flows) {
     // The server hits the URL itself; with no URL (or a localhost one it can't reach) fall back to local.
     if (previewUrl === undefined || 0 === previewUrl.length)
         return null;
-    const report = await submitServerVerification({ previewUrl, flows, source: SOURCE }, cloud.config, (url, init) => fetch(url, init));
+    // The submit blocks while the hosted runner drives a real browser, so it gets the long budget — but a
+    // budget it must have: this is awaited inside the verify tool, and an unbounded wait here is an MCP
+    // call that never returns. A timeout is reported and then falls back to the local replay below.
+    const report = await submitServerVerification({ previewUrl, flows, source: SOURCE }, cloud.config, async (url, init) => {
+        try {
+            return await cloudFetch(url, init, CLOUD_VERIFY_TIMEOUT_MS);
+        }
+        catch (error) {
+            log('cloud-server-verify-failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    });
     if (null === report)
         return null;
     // The hosted runner said it couldn't actually verify (e.g. it's not enabled yet). Never surface that as

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 {
@@ -193,7 +197,10 @@ async function inspectAfterReplay(deps, args, cursor) {
     }
     try {
         const session = deps.sessions.resolve(asString(args['sessionId']));
-        const contradictions = findContradictions(session.eventsSince(cursor));
+        const contradictions = findContradictions(session.eventsSince(cursor), {
+            currentDocumentId: session.currentDocumentId,
+            currentEditEpoch: session.currentEditEpoch,
+        });
         const snapshot = await session.command(ReticleCommand.SNAPSHOT, {
             mode: SnapshotMode.INTERACTIVE,
         });

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

@@ -65,22 +65,14 @@ export declare function blindSpotsFromEvents(events: readonly ReticleEvent[]): B
  * from what happened to be said recently.
  */
 export declare function blindSpotsFromState(state: Readonly<Record<string, number>>): BlindSpot[];
+/** The impeaching note for a transport gap, or undefined when the window was intact. */
+export declare function transportGapNote(events: readonly ReticleEvent[]): string | undefined;
 /**
- * Events the BROWSER's own transport queue threw away inside this window, or 0.
- *
- * `RATE_LIMITED` — the BRIDGE sampling because events arrived faster than its per-second cap — is
- * already the one blind spot that `impeachesCapture`, on the reasoning that a green over a window
- * you did not fully see "would only describe what was observed". `TRANSPORT_OVERFLOW` is the exact
- * same loss on the other side of the wire, and it was read in journal rollups and NOWHERE on the
- * verdict path. So the identical condition downgraded a verdict from one side of the socket and was
- * invisible from the other: a window that dropped 34 events graded `proved`, in a sentence whose own
- * words were "over a clean capture".
+ * Is the state channel dark?
  *
- * `TRUNCATED` is deliberately NOT counted. It names the channel it capped (a DOM-mutation flood on
- * any busy page) and is routine churn; treating it as lost evidence would caveat every verdict on
- * every real app, and a caveat that is always present is one nobody reads. TRANSPORT_OVERFLOW is the
- * honest "arbitrary events are gone" marker — it cannot say which.
+ * 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 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;
+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.
@@ -133,7 +135,7 @@ export function blindSpotsFromState(state) {
  * every real app, and a caveat that is always present is one nobody reads. TRANSPORT_OVERFLOW is the
  * honest "arbitrary events are gone" marker — it cannot say which.
  */
-export function droppedByTransport(events) {
+function droppedByTransport(events) {
     let dropped = 0;
     for (const e of events) {
         if (e.type !== EventType.TRANSPORT_OVERFLOW)
@@ -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);
+}