@reticlehq/server 2.10.0 → 2.12.0

package/dist/honesty/feature-capture.d.ts

@@ -0,0 +1,150 @@
+import { type Intent, type JournalAction } from '@reticlehq/core';
+/**
+ * Were `reticle_context` and `reticle_intent` used at all — and did using them change anything?
+ *
+ * Both shipped with the same pre-registered disproof: *if agents never call it, cut it*. Nothing
+ * recorded whether they were called, so the disproof could never be run, and a feature whose
+ * disproof cannot be run is one nobody can kill. This is the smallest thing that makes the question
+ * answerable, per session, locally — an instrument, not a scold. The numbers exist so a FEATURE can
+ * be removed, never so an agent can be blamed for how it drove.
+ *
+ * ## Fold first, record only what nothing records
+ *
+ * Three of the four questions are already answerable from what is on disk. The intent ledger says
+ * what was declared; the journal says what was driven and what verdicts were drawn. Those are folded
+ * here and never re-stored, for the reason `run-context.ts` gives at length: two ways to compute one
+ * number is worse than one way.
+ *
+ * The journal does NOT record read-only calls — it holds actions and verdicts only. So "was
+ * `reticle_context` called" has no ledger to fold, and that one thing is recorded, in memory, on the
+ * session, by `CaptureLedger`. It is the whole of the new state.
+ *
+ * ## Absent is not zero
+ *
+ * A session this daemon has recorded nothing for — journaling off, a session adopted after the fact
+ * — reports `observed: false` and states no counts at all. It has not established that the features
+ * went unused; it has established that it was not watching. This repo has shipped the other bug
+ * twice.
+ */
+/**
+ * The calls this instrument needs and the journal does not keep.
+ *
+ * Deliberately a short explicit list rather than "everything that is not an action". Under-inclusion
+ * is the safe direction: a read tool missing from here lowers the hit side and the miss side by the
+ * same call, so the comparison the disproof turns on stays fair. Over-inclusion is not — a lifecycle
+ * or disk-side tool landing in here would be counted as a "read" the agent made of the app, which it
+ * was not.
+ */
+export declare const CAPTURED_TOOLS: ReadonlySet<string>;
+/** One recorded call: which tool, what it was about, and how far into the run it happened. */
+export interface CapturedCall {
+    tool: string;
+    /** The ref or target the call named, when it named one. Absent for a whole-page read. */
+    subject?: string;
+    /**
+     * The session's dispatched-action count at the moment of the call — the same counter that mints
+     * journal action ids, so it lines up with `reticle_context`'s own `step` whenever the journal is on.
+     */
+    afterActions: number;
+}
+/**
+ * The one thing that is stored rather than folded: the read-only calls the journal never sees.
+ *
+ * In memory and per session, the same shape as `GapLedger`. It is not durable on purpose — the
+ * question is about one run, and a second file on disk would be a second thing to reconcile with the
+ * journal.
+ */
+export declare class CaptureLedger {
+    #private;
+    /**
+     * One call, under the name of the tool that RAN — every tool, not just the read set above.
+     *
+     * Separate from `note` because it answers a different question and is bounded differently: this
+     * map cannot outgrow the tool table however long the session runs, so it needs no cap and never
+     * has to report a floor. See honesty/tool-hit-rate.ts for what it feeds.
+     */
+    noteTool(tool: string): void;
+    /** How many times each tool was called this session, in first-call order. */
+    toolCalls(): ReadonlyMap<string, number>;
+    note(call: CapturedCall): void;
+    calls(): readonly CapturedCall[];
+    /** How many calls fell off the front. Non-zero means the counts below are a floor. */
+    get dropped(): number;
+}
+/**
+ * Record one captured call against the session that made it.
+ *
+ * Tolerates a session that carries no ledger, exactly as `noteSessionGaps` does and for the same
+ * reason: `Session` is satisfied structurally, and many specs — plus any consumer embedding this
+ * engine — build one as an object literal. Such a session is a real caller that simply keeps no
+ * ledger, and an instrument must never be the reason a tool call throws. Its calls are then absent
+ * rather than counted as zero, which is what `observed: false` exists to say.
+ */
+export declare function noteCapturedCall(session: {
+    capture?: CaptureLedger;
+    actionCount?: number;
+}, call: Omit<CapturedCall, 'afterActions'>): void;
+/**
+ * Count one call against the session that made it, whichever tool it was.
+ *
+ * Tolerant of a ledger-less session for exactly the reason `noteCapturedCall` is: its calls are then
+ * absent rather than counted as zero, which is what `observed: false` exists to say.
+ */
+export declare function noteToolDispatched(session: {
+    capture?: CaptureLedger;
+}, tool: string): void;
+/** What one session's use of the two features looks like. Everything but `observed` is omitted when nothing was recorded. */
+export interface FeatureCapture {
+    /** False when this daemon recorded nothing for the session — "not watched", never "not used". */
+    observed: boolean;
+    /** The ledger dropped calls, so every count is a floor. Present only when true. */
+    truncated?: boolean;
+    context?: {
+        calls: number;
+        /** The dispatched-action count each call was made at, in order. */
+        atSteps: number[];
+        acted: number;
+        refetched: number;
+        readOther: number;
+        nothingAfter: number;
+    };
+    intents?: {
+        declared: number;
+        open: number;
+    };
+    missed?: {
+        verdictsWithNoIntentDeclared: number;
+        refetchedEstablished: number;
+    };
+}
+/**
+ * Did calling `reticle_context` change what happened next?
+ *
+ * The mechanical proxy, stated so it can be argued with: look at the very next recorded call. If an
+ * action was dispatched before it — the action counter moved — the agent ACTED, and the context
+ * plausibly helped. If instead the next call is a read of a subject the context had just supplied,
+ * the agent re-fetched what it had been handed, and the context did not help.
+ *
+ * ## What this proxy CANNOT see
+ *
+ *  - Whether the agent READ the response, reasoned over it, or wrote a better answer from it. There
+ *    is no signal for that anywhere, and this must not be mistaken for one.
+ *  - Anything that happens between two Reticle calls: source edits, calls to other MCP servers, a
+ *    turn ending, a human interrupting. A long gap is invisible and reads as adjacency.
+ *  - Reads that name no ref or target (a whole-page snapshot). They land in `readOther`, never in
+ *    `refetched`, so a snapshot that duplicated the context is under-counted, not over-counted.
+ *  - Causation. `acted` is proximity in a call sequence, nothing more. An agent that would have acted
+ *    anyway is indistinguishable from one the context unblocked.
+ *  - `reticle_context` called with no session connected — it answers there by design, and there is no
+ *    per-session ledger to record it against, so those calls are missing entirely.
+ *  - Two agents driving one session. Their calls interleave into one sequence and "next call" stops
+ *    meaning "next thing that agent did".
+ */
+export declare function foldFeatureCapture(input: {
+    calls: readonly CapturedCall[];
+    dropped: number;
+    actions: readonly JournalAction[];
+    intents: readonly Intent[];
+    /** The session's dispatched-action count now, so a run that ended on an action is not read as idle. */
+    finalActions: number;
+}): FeatureCapture;

package/dist/honesty/feature-capture.js

@@ -0,0 +1,233 @@
+import { IntentState, JournalVerdictEffectSchema, RUN_ESTABLISHED_CAP, } from '@reticlehq/core';
+import { subjectOf } from '../runs/run-context.js';
+import { ReticleTool } from '../tools/tool-names.js';
+/**
+ * Were `reticle_context` and `reticle_intent` used at all — and did using them change anything?
+ *
+ * Both shipped with the same pre-registered disproof: *if agents never call it, cut it*. Nothing
+ * recorded whether they were called, so the disproof could never be run, and a feature whose
+ * disproof cannot be run is one nobody can kill. This is the smallest thing that makes the question
+ * answerable, per session, locally — an instrument, not a scold. The numbers exist so a FEATURE can
+ * be removed, never so an agent can be blamed for how it drove.
+ *
+ * ## Fold first, record only what nothing records
+ *
+ * Three of the four questions are already answerable from what is on disk. The intent ledger says
+ * what was declared; the journal says what was driven and what verdicts were drawn. Those are folded
+ * here and never re-stored, for the reason `run-context.ts` gives at length: two ways to compute one
+ * number is worse than one way.
+ *
+ * The journal does NOT record read-only calls — it holds actions and verdicts only. So "was
+ * `reticle_context` called" has no ledger to fold, and that one thing is recorded, in memory, on the
+ * session, by `CaptureLedger`. It is the whole of the new state.
+ *
+ * ## Absent is not zero
+ *
+ * A session this daemon has recorded nothing for — journaling off, a session adopted after the fact
+ * — reports `observed: false` and states no counts at all. It has not established that the features
+ * went unused; it has established that it was not watching. This repo has shipped the other bug
+ * twice.
+ */
+/**
+ * The calls this instrument needs and the journal does not keep.
+ *
+ * Deliberately a short explicit list rather than "everything that is not an action". Under-inclusion
+ * is the safe direction: a read tool missing from here lowers the hit side and the miss side by the
+ * same call, so the comparison the disproof turns on stays fair. Over-inclusion is not — a lifecycle
+ * or disk-side tool landing in here would be counted as a "read" the agent made of the app, which it
+ * was not.
+ */
+export const CAPTURED_TOOLS = new Set([
+    ReticleTool.CONTEXT,
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.INSPECT,
+    ReticleTool.STATE,
+    ReticleTool.STORAGE,
+    ReticleTool.NETWORK,
+    ReticleTool.CONSOLE,
+    ReticleTool.OBSERVE,
+    ReticleTool.EXPLORE,
+]);
+/**
+ * How many calls the ledger holds before it starts dropping the oldest.
+ *
+ * A verification loop is 50–200 calls, so this is not reached in normal use; it exists so a runaway
+ * session cannot grow a per-session array without bound. When it IS reached the report says
+ * `truncated` rather than presenting a short count as a complete one.
+ */
+const CAPTURE_CAP = 2000;
+/**
+ * The one thing that is stored rather than folded: the read-only calls the journal never sees.
+ *
+ * In memory and per session, the same shape as `GapLedger`. It is not durable on purpose — the
+ * question is about one run, and a second file on disk would be a second thing to reconcile with the
+ * journal.
+ */
+export class CaptureLedger {
+    #calls = [];
+    #dropped = 0;
+    #tools = new Map();
+    /**
+     * One call, under the name of the tool that RAN — every tool, not just the read set above.
+     *
+     * Separate from `note` because it answers a different question and is bounded differently: this
+     * map cannot outgrow the tool table however long the session runs, so it needs no cap and never
+     * has to report a floor. See honesty/tool-hit-rate.ts for what it feeds.
+     */
+    noteTool(tool) {
+        this.#tools.set(tool, (this.#tools.get(tool) ?? 0) + 1);
+    }
+    /** How many times each tool was called this session, in first-call order. */
+    toolCalls() {
+        return this.#tools;
+    }
+    note(call) {
+        this.#calls.push(call);
+        if (this.#calls.length > CAPTURE_CAP) {
+            this.#calls.shift();
+            this.#dropped += 1;
+        }
+    }
+    calls() {
+        return this.#calls;
+    }
+    /** How many calls fell off the front. Non-zero means the counts below are a floor. */
+    get dropped() {
+        return this.#dropped;
+    }
+}
+/**
+ * Record one captured call against the session that made it.
+ *
+ * Tolerates a session that carries no ledger, exactly as `noteSessionGaps` does and for the same
+ * reason: `Session` is satisfied structurally, and many specs — plus any consumer embedding this
+ * engine — build one as an object literal. Such a session is a real caller that simply keeps no
+ * ledger, and an instrument must never be the reason a tool call throws. Its calls are then absent
+ * rather than counted as zero, which is what `observed: false` exists to say.
+ */
+export function noteCapturedCall(session, call) {
+    session.capture?.note({ ...call, afterActions: session.actionCount ?? 0 });
+}
+/**
+ * Count one call against the session that made it, whichever tool it was.
+ *
+ * Tolerant of a ledger-less session for exactly the reason `noteCapturedCall` is: its calls are then
+ * absent rather than counted as zero, which is what `observed: false` exists to say.
+ */
+export function noteToolDispatched(session, tool) {
+    session.capture?.noteTool(tool);
+}
+/**
+ * Every point in the run at which each subject became an established fact.
+ *
+ * "Established" is not a second definition: it is the rule `establishedFromJournal` folds by — an
+ * action with an observed settle outcome, filed under the ref or target it named — and `subjectOf`
+ * is imported from there rather than rewritten, so the two cannot drift apart.
+ */
+function establishedIndexes(actions) {
+    const out = new Map();
+    actions.forEach((action, index) => {
+        if (undefined === action.settled)
+            return;
+        const key = subjectOf(action);
+        if (undefined === key)
+            return;
+        const at = out.get(key);
+        if (at === undefined)
+            out.set(key, [index]);
+        else
+            at.push(index);
+    });
+    return out;
+}
+/** Was this subject already an established fact by the time a call at `afterActions` was made? */
+function wasEstablished(index, subject, afterActions) {
+    if (undefined === subject)
+        return false;
+    const at = index.get(subject);
+    if (at === undefined)
+        return false;
+    // Action `i` has been dispatched once the counter reads `i + 1`, so `i + 1 <= afterActions` is
+    // "already true when the call was made" — which is what keeps a FIRST look off this count. The
+    // lower bound is the run context's own window: a fact that has scrolled past RUN_ESTABLISHED_CAP
+    // is not something `reticle_context` would have handed back, so re-reading it is not a re-fetch.
+    return at.some((i) => i + 1 <= afterActions && i + 1 > afterActions - RUN_ESTABLISHED_CAP);
+}
+/**
+ * Did calling `reticle_context` change what happened next?
+ *
+ * The mechanical proxy, stated so it can be argued with: look at the very next recorded call. If an
+ * action was dispatched before it — the action counter moved — the agent ACTED, and the context
+ * plausibly helped. If instead the next call is a read of a subject the context had just supplied,
+ * the agent re-fetched what it had been handed, and the context did not help.
+ *
+ * ## What this proxy CANNOT see
+ *
+ *  - Whether the agent READ the response, reasoned over it, or wrote a better answer from it. There
+ *    is no signal for that anywhere, and this must not be mistaken for one.
+ *  - Anything that happens between two Reticle calls: source edits, calls to other MCP servers, a
+ *    turn ending, a human interrupting. A long gap is invisible and reads as adjacency.
+ *  - Reads that name no ref or target (a whole-page snapshot). They land in `readOther`, never in
+ *    `refetched`, so a snapshot that duplicated the context is under-counted, not over-counted.
+ *  - Causation. `acted` is proximity in a call sequence, nothing more. An agent that would have acted
+ *    anyway is indistinguishable from one the context unblocked.
+ *  - `reticle_context` called with no session connected — it answers there by design, and there is no
+ *    per-session ledger to record it against, so those calls are missing entirely.
+ *  - Two agents driving one session. Their calls interleave into one sequence and "next call" stops
+ *    meaning "next thing that agent did".
+ */
+export function foldFeatureCapture(input) {
+    const { calls, actions, intents } = input;
+    if (0 === calls.length && 0 === actions.length)
+        return { observed: false };
+    const established = establishedIndexes(actions);
+    const isRefetch = (call) => ReticleTool.CONTEXT !== call.tool &&
+        wasEstablished(established, call.subject, call.afterActions);
+    let acted = 0;
+    let refetched = 0;
+    let readOther = 0;
+    let nothingAfter = 0;
+    const atSteps = [];
+    calls.forEach((call, i) => {
+        if (ReticleTool.CONTEXT !== call.tool)
+            return;
+        atSteps.push(call.afterActions);
+        const next = calls[i + 1];
+        if (next === undefined) {
+            if (input.finalActions > call.afterActions)
+                acted += 1;
+            else
+                nothingAfter += 1;
+            return;
+        }
+        if (next.afterActions > call.afterActions)
+            acted += 1;
+        else if (isRefetch(next))
+            refetched += 1;
+        else
+            readOther += 1;
+    });
+    // A verdict is any journal action carrying the bounded verdict effect both verification tools
+    // write. Parsed with core's own schema rather than a local shape, for the usual reason.
+    const verdicts = actions.filter((a) => JournalVerdictEffectSchema.safeParse(a.effect).success);
+    return {
+        observed: true,
+        ...(input.dropped > 0 ? { truncated: true } : {}),
+        context: { calls: atSteps.length, atSteps, acted, refetched, readOther, nothingAfter },
+        intents: {
+            declared: intents.length,
+            open: intents.filter((it) => IntentState.PROVED !== it.state).length,
+        },
+        missed: {
+            // The coarse question, asked honestly. Nothing binds a verdict to a specific intent outside
+            // flow replay, so "covered" cannot mean "this intent proves this verdict" without inventing a
+            // link Reticle cannot observe — the same reason `undeclared-change.ts` asks only whether
+            // anything at all was declared. So this counts verdicts drawn against an EMPTY ledger, and
+            // stops at zero once anything is declared. That zero is not a claim that every verdict was
+            // covered; it is the end of what this can see.
+            verdictsWithNoIntentDeclared: 0 === intents.length ? verdicts.length : 0,
+            refetchedEstablished: calls.filter(isRefetch).length,
+        },
+    };
+}

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,79 @@
+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;
+    /**
+     * The `file:line` of the element this verdict is about, when the build plugin stamped one.
+     *
+     * Was a boolean, on the reasoning that the gap only needed to know WHETHER the agent could be
+     * pointed at code. That was true while the only gap reading it was the one that fires when the
+     * pointer is missing. It stopped being true the moment a gap wanted to CARRY the pointer: a gap is
+     * read back later, out of the ledger, by which time its `ref` is very likely dead, and a boolean
+     * cannot be turned back into a location. Both callers already hold this as a formatted string.
+     */
+    source?: string | undefined;
+    /** 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 app declare any capabilities at all?
+     *
+     * Undefined means NOT KNOWN, and not-known must never become an accusation — callers that predate
+     * this field keep their behaviour rather than start reporting a gap they cannot substantiate.
+     */
+    hasCapabilities?: boolean | undefined;
+    /** 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;
+    /**
+     * Did a code change land since the last verdict with nothing declaring what it was for?
+     *
+     * Arrives already decided, because the decision needs the intent ledger and this stays pure. Its
+     * gate — and the reasoning that keeps it from becoming a nag — lives in `isChangeUndeclared`, and
+     * that is the only place allowed to answer it.
+     */
+    changeUndeclared?: boolean;
+    /**
+     * How many intents the ledger still holds undischarged. Undefined when nothing consulted it.
+     *
+     * A count rather than a boolean because the message names the number: "one thing still unproved"
+     * and "four things still unproved" are different situations for an agent deciding whether it is
+     * finished, and a bare flag makes them read the same.
+     */
+    openIntentCount?: number;
+}
+export declare function gapsForAction(facts: ActionInstrumentationFacts): InstrumentationGap[];

package/dist/honesty/instrumentation-gaps.js

@@ -0,0 +1,77 @@
+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.source === undefined) {
+        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. Deliberately UNLOCATED: a store
+    // is registered once at app setup, nowhere near the control that was driven, and nothing in this
+    // window knows where that setup lives. Borrowing the acted line would send the agent to a file
+    // that cannot hold the fix — worse than no pointer, because it costs the trip as well.
+    // An app that declared NOTHING is told once, without having to be asked.
+    //
+    // The rule below fires only when an assertion about state could not be answered, which is correct
+    // for that gap and leaves the common case silent: an app whose capabilities file registers
+    // nothing drives fine, produces verdicts, and never mentions being under-instrumented — unless
+    // the agent happens to ask about state, which an agent with no reason to suspect a problem will
+    // not do. The session has known the answer the whole time and no verdict ever consulted it.
+    //
+    // Reported as the same kind, because it is the same missing thing seen from the other side, and
+    // guarded so the two conditions cannot report it twice.
+    if (false === facts.hasCapabilities || (facts.stateAsked && facts.stateUnwatched)) {
+        // Same missing thing, two ways of meeting it — and the sentence has to say which. Describing an
+        // assertion about state to an agent that made no such assertion is a false explanation, and a
+        // gap nobody can act on is worse than no gap: it costs the trip and teaches the wrong lesson.
+        const declaredNothing = false === facts.hasCapabilities;
+        gaps.push(instrumentationGap(InstrumentationGapKind.NO_STORE_REGISTERED, declaredNothing
+            ? 'this app declared no capabilities at all, so no state can be read from it'
+            : 'no store is registered, and this assertion was about state', declaredNothing
+            ? 'every verdict here rests on what the DOM happens to show, and reticle_state will stay empty however many flows are driven'
+            : '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', 
+        // The one gap here that can be LOCATED. It is about the element that was driven, and that
+        // element is exactly what `source` describes — so the pointer is a fact, not a guess. It
+        // also outlives the `ref` beside it, which is what makes this gap still actionable when
+        // coverage reads it back long after the page has re-rendered.
+        {
+            ...(facts.ref === undefined ? {} : { ref: facts.ref }),
+            ...(facts.source === undefined ? {} : { source: facts.source }),
+        }));
+    }
+    // Also unlocated, for the same reason: the remedy is a router adapter wired app-wide, not a line
+    // at the control that happened to trigger this navigation.
+    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'));
+    }
+    // The one gap here that is not about the app. Deliberately UNLOCATED and deliberately generic: the
+    // only honest thing to report is that the intent is absent. Naming the file that changed, or the
+    // control that was driven, would invite the reader to treat a guess as the declaration — and a
+    // guessed intent reads as the developer's own words, which is strictly worse than honest absence.
+    if (true === facts.changeUndeclared) {
+        gaps.push(instrumentationGap(InstrumentationGapKind.UNDECLARED_CHANGE, 'code changed since the last verdict and no intent says what the change was for', 'this verdict can only check the app against itself, so a green here means "nothing visibly broke" rather than "the change did what it was meant to"'));
+    }
+    // A green that does not settle what the run OWES.
+    //
+    // The mirror of `changeUndeclared` above, and the more expensive half: that fires when nothing was
+    // declared, this when something was and no verdict ever proved it. Measured on the bench fixture —
+    // an agent drew SEVEN green verdicts and reported FIXED on a form that still accepted a
+    // whitespace-only service, quoting its own patch as the evidence. Every verdict was honestly
+    // green; none of them was about the thing claimed, and nothing in the result said so.
+    //
+    // Only on a PASS: a failing verdict proved nothing and already says that, so adding this would be
+    // two sentences for one fact. It downgrades nothing either — the assertion did hold — it just
+    // names the debt on the result the agent is already reading, while it is deciding if it is done.
+    // `proved`, not `pass`, because a bare `{ settled }` wait scores the predicate true while proving
+    // nothing — the verdict comes back `no-fault`, and keying on `pass` attached "this verdict passed"
+    // to a result whose own `because` says it is not verification.
+    const owed = facts.openIntentCount ?? 0;
+    if (facts.pass && true === facts.proved && 0 < owed) {
+        gaps.push(instrumentationGap(InstrumentationGapKind.INTENT_UNDISCHARGED, `this verdict passed, and ${String(owed)} declared intent(s) are still unproved`, 'a green settles what it asserted, not what the run set out to do — reporting done here rests on the change looking right rather than on anything having checked it'));
+    }
+    return dedupeGaps(gaps);
+}