@reticlehq/server 2.11.0 → 2.12.0

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/instrumentation-gaps.d.ts

@@ -29,20 +29,28 @@ export interface ActionInstrumentationFacts {
     /** True when the outcome was positively PROVED rather than inferred. */
     proved?: boolean;
     /**
-     * Does Reticle know a `file:line` for what this verdict is about?
+     * The `file:line` of the element this verdict is about, when the build plugin stamped one.
      *
-     * 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.
+     * 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.
      */
-    sourceKnown: boolean;
+    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. */
@@ -51,5 +59,21 @@ export interface ActionInstrumentationFacts {
     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

@@ -3,19 +3,75 @@ 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) {
+    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.
-    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'));
+    // 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', { ...(facts.ref === undefined ? {} : { ref: facts.ref }) }));
+        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);
 }

package/dist/honesty/tool-hit-rate.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Which tools this session called, and how reachable each one was.
+ *
+ * The generalisation of the capture ledger: it recorded a short list of read tools to answer one
+ * feature's disproof, and the question that followed is the same question asked of the whole table —
+ * most of the surface has never been observed being called at all, and a decision about what to cut
+ * or consolidate is about to be made. This is the instrument for that decision, and nothing else.
+ *
+ * ## Why the count alone is not enough
+ *
+ * A tool that goes uncalled because nobody was told it exists and a tool that goes uncalled because
+ * nobody wants it look identical in a call count. They are opposite conclusions. So every count is
+ * reported beside the tool's REACHABILITY — advertised on the default surface, advertised only on
+ * the extended one, or reachable solely by naming it to `reticle_run` — and the interesting cell is
+ * the one where an agent found a run-only tool anyway.
+ *
+ * ## The tiers are derived, never restated
+ *
+ * `tierOfTool` reads `CORE_TOOL_NAMES` and `EXTENDED_TOOL_NAMES` directly. A tool promoted or
+ * demoted between surfaces changes tier here with nothing edited. A local copy of either list would
+ * go stale on the first move and would then be wrong about the exact axis this exists to measure —
+ * and it would be wrong silently, in a report used to justify deleting things.
+ *
+ * ## What these numbers do NOT establish
+ *
+ *  - **One session is not a hit rate.** This is evidence about ONE run by ONE agent against ONE app.
+ *    A hit rate is a distribution over many sessions; a single session quoted as one is an anecdote
+ *    with a denominator drawn on it.
+ *  - **Never-called is not useless.** A tool one team reaches for once a month in an emergency and a
+ *    tool nobody has ever called are the same zero here. Frequency alone cannot separate them, so a
+ *    cut decided on frequency alone will delete the wrong things.
+ *  - **Absent is not zero.** A session with no ledger reports `observed: false`. It has not
+ *    established that no tools were called; it has established that nothing was watching.
+ *  - The tools that ran BEFORE this instrument existed in the process, or against a session this
+ *    daemon adopted after the fact, are simply missing rather than counted low.
+ */
+/** How an agent could have reached a tool. Derived from the surface sets — see above. */
+export declare const ToolTier: {
+    /** Advertised directly on the surface every user gets. */
+    readonly DEFAULT: "default";
+    /** Advertised only when the full schema-carrying surface is switched on. */
+    readonly EXTENDED: "extended";
+    /** Advertised nowhere: reachable only by naming it to `reticle_run`. */
+    readonly RUN_ONLY: "run-only";
+};
+export type ToolTier = (typeof ToolTier)[keyof typeof ToolTier];
+/** Which surface would have put this tool in front of an agent, read off that surface's own set. */
+export declare function tierOfTool(tool: string): ToolTier;
+/** How many tools fell in each tier on one side of the called/never-called split. */
+export interface TierCounts {
+    default: number;
+    extended: number;
+    runOnly: number;
+}
+export interface ToolHitRate {
+    /** False when this session carries no ledger — "not watched", never "nothing was called". */
+    observed: boolean;
+    /** The four-plus-two cells: every tier, called and never-called. Omitted when not observed. */
+    cells?: {
+        called: TierCounts;
+        neverCalled: TierCounts;
+    };
+    /** Each tool called this session, most-called first. */
+    called?: readonly {
+        tool: string;
+        tier: ToolTier;
+        calls: number;
+    }[];
+    /** Each tool in the table this session never called, by name. */
+    neverCalled?: readonly {
+        tool: string;
+        tier: ToolTier;
+    }[];
+}
+/**
+ * Cross one session's per-tool counts with the tool table.
+ *
+ * `allTools` is the DISPATCHABLE table — the names `reticle_run` will accept — passed in rather than
+ * imported, because the table is assembled in the module that owns this tool and importing it back
+ * would close a cycle. A tool counted but absent from the table still appears, so a name the table
+ * lost is visible rather than dropped.
+ */
+export declare function foldToolHitRate(input: {
+    calls: ReadonlyMap<string, number> | undefined;
+    allTools: readonly string[];
+}): ToolHitRate;

package/dist/honesty/tool-hit-rate.js

@@ -0,0 +1,90 @@
+import { CORE_TOOL_NAMES, EXTENDED_TOOL_NAMES } from '../tools/tool-surface.js';
+/**
+ * Which tools this session called, and how reachable each one was.
+ *
+ * The generalisation of the capture ledger: it recorded a short list of read tools to answer one
+ * feature's disproof, and the question that followed is the same question asked of the whole table —
+ * most of the surface has never been observed being called at all, and a decision about what to cut
+ * or consolidate is about to be made. This is the instrument for that decision, and nothing else.
+ *
+ * ## Why the count alone is not enough
+ *
+ * A tool that goes uncalled because nobody was told it exists and a tool that goes uncalled because
+ * nobody wants it look identical in a call count. They are opposite conclusions. So every count is
+ * reported beside the tool's REACHABILITY — advertised on the default surface, advertised only on
+ * the extended one, or reachable solely by naming it to `reticle_run` — and the interesting cell is
+ * the one where an agent found a run-only tool anyway.
+ *
+ * ## The tiers are derived, never restated
+ *
+ * `tierOfTool` reads `CORE_TOOL_NAMES` and `EXTENDED_TOOL_NAMES` directly. A tool promoted or
+ * demoted between surfaces changes tier here with nothing edited. A local copy of either list would
+ * go stale on the first move and would then be wrong about the exact axis this exists to measure —
+ * and it would be wrong silently, in a report used to justify deleting things.
+ *
+ * ## What these numbers do NOT establish
+ *
+ *  - **One session is not a hit rate.** This is evidence about ONE run by ONE agent against ONE app.
+ *    A hit rate is a distribution over many sessions; a single session quoted as one is an anecdote
+ *    with a denominator drawn on it.
+ *  - **Never-called is not useless.** A tool one team reaches for once a month in an emergency and a
+ *    tool nobody has ever called are the same zero here. Frequency alone cannot separate them, so a
+ *    cut decided on frequency alone will delete the wrong things.
+ *  - **Absent is not zero.** A session with no ledger reports `observed: false`. It has not
+ *    established that no tools were called; it has established that nothing was watching.
+ *  - The tools that ran BEFORE this instrument existed in the process, or against a session this
+ *    daemon adopted after the fact, are simply missing rather than counted low.
+ */
+/** How an agent could have reached a tool. Derived from the surface sets — see above. */
+export const ToolTier = {
+    /** Advertised directly on the surface every user gets. */
+    DEFAULT: 'default',
+    /** Advertised only when the full schema-carrying surface is switched on. */
+    EXTENDED: 'extended',
+    /** Advertised nowhere: reachable only by naming it to `reticle_run`. */
+    RUN_ONLY: 'run-only',
+};
+/** Which surface would have put this tool in front of an agent, read off that surface's own set. */
+export function tierOfTool(tool) {
+    if (CORE_TOOL_NAMES.has(tool))
+        return ToolTier.DEFAULT;
+    if (EXTENDED_TOOL_NAMES.has(tool))
+        return ToolTier.EXTENDED;
+    return ToolTier.RUN_ONLY;
+}
+function tally(tools) {
+    return {
+        default: tools.filter((tier) => ToolTier.DEFAULT === tier).length,
+        extended: tools.filter((tier) => ToolTier.EXTENDED === tier).length,
+        runOnly: tools.filter((tier) => ToolTier.RUN_ONLY === tier).length,
+    };
+}
+/**
+ * Cross one session's per-tool counts with the tool table.
+ *
+ * `allTools` is the DISPATCHABLE table — the names `reticle_run` will accept — passed in rather than
+ * imported, because the table is assembled in the module that owns this tool and importing it back
+ * would close a cycle. A tool counted but absent from the table still appears, so a name the table
+ * lost is visible rather than dropped.
+ */
+export function foldToolHitRate(input) {
+    const { calls } = input;
+    if (calls === undefined)
+        return { observed: false };
+    const called = [...calls]
+        .map(([tool, count]) => ({ tool, tier: tierOfTool(tool), calls: count }))
+        .sort((a, b) => b.calls - a.calls || a.tool.localeCompare(b.tool));
+    const neverCalled = input.allTools
+        .filter((tool) => !calls.has(tool))
+        .map((tool) => ({ tool, tier: tierOfTool(tool) }))
+        .sort((a, b) => a.tool.localeCompare(b.tool));
+    return {
+        observed: true,
+        cells: {
+            called: tally(called.map((entry) => entry.tier)),
+            neverCalled: tally(neverCalled.map((entry) => entry.tier)),
+        },
+        called,
+        neverCalled,
+    };
+}

package/dist/honesty/undeclared-change.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Is this verdict being drawn over code nobody said anything about?
+ *
+ * Declaring intent is opt-in, and nothing has ever noticed that a change landed and nobody said what
+ * it was supposed to make true. That is the moment it matters: a change with no declared intent can
+ * only be verified against itself, which is the definition of a false green.
+ *
+ * ## Why this fires on EVERY verdict, not once per change
+ *
+ * The house rule is that a gap nobody hit is a backlog, and a backlog reported as a finding is how
+ * an agent learns to stop reading findings. This clears that bar on the same test every other
+ * instrumentation gap clears it on: **did the absence make THIS verdict weaker?** An unwatched store
+ * weakens every state assertion made over it, not merely the first, so it is reported on every one.
+ * An undeclared change is the same shape — while nothing says what the edit was for, each verdict
+ * drawn after it is checked against nothing but itself, and that is true of the fifth one exactly as
+ * it was of the first. Reporting it once and then falling silent would leave four verdicts carrying
+ * a weakness they no longer disclose, which is the failure mode this whole surface exists to prevent.
+ *
+ * It is also not a backlog, because it is not a survey of the project: it is answered from what this
+ * session observed (an epoch that moved) about the verdict being returned right now, and it is
+ * closed by one call the agent can make immediately. A finding that stays open only because the
+ * agent has not made that call is a finding about the current verdict, not a chore.
+ *
+ * ## The silences, and why each one is required
+ *
+ *  - **An edit was actually OBSERVED.** The epoch degrades to `NO_EDITS_OBSERVED` outside Vite, and
+ *    that means "no edits observed", never "no edits happened" — a finding built on an absence
+ *    Reticle cannot see would be a fabrication.
+ *  - **The ledger holds nothing undischarged.** An open intent IS the declaration; silence is the
+ *    correct response to it, and declaring one is what turns this off from the next verdict on.
+ *
+ * ## Why "covers the work" is answered as "anything open at all"
+ *
+ * The tempting answer is to match the intent's `surface` against the files that changed. Reticle
+ * cannot do that honestly: it observes that an epoch advanced, not WHAT advanced — the hot-update
+ * channel reports a counter, not a diff — so any file-level matching would be inference dressed as a
+ * fact, and it would fire on an agent that had declared its intent perfectly well. Over-reporting on
+ * a correct agent is the direction of error that trains it to stop reading findings.
+ *
+ * So the question asked is the coarse one, and it is asked honestly: has the agent declared anything
+ * that is still outstanding? If it has, it is working to a stated purpose and this stays quiet.
+ */
+/**
+ * `openIntents` is a thunk rather than a list because reading the ledger touches disk, and the epoch
+ * check answers without it for every page that never reported a hot update — which is most of them.
+ * Once an edit HAS been observed the read happens per verdict, and that is the intended cost: the
+ * ledger is the only thing that can end it, so it has to be re-asked each time.
+ */
+export declare function isChangeUndeclared(
+/** The epoch the session is under now. Undefined when the page never stamped one. */
+currentEpoch: number | undefined, openIntents: () => Promise<readonly unknown[]>): Promise<boolean>;