@reticlehq/server 2.14.0 → 3.2.0

package/dist/honesty/instrumentation-gaps.js

@@ -1,114 +0,0 @@
-import { InstrumentationGapKind, dedupeGaps, instrumentationGap, } from '@reticlehq/core/artifacts';
-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.
-    //
-    // ...unless the project TURNED THE STAMP OFF, which is a different situation with the opposite
-    // remedy. Reported from the field: a react-three-fiber app disabled `sourceMapping` because the
-    // stamp crashed it to a white screen, and every red verdict afterwards told the reader to install
-    // a build plugin that was already there. Only a definite `false` counts — an SDK that says nothing
-    // is unknown, and reading silence as an opt-out would mute the honest gap for every app that
-    // simply has no source mapping at all.
-    if (!facts.pass && facts.source === undefined) {
-        const off = true === facts.sourceMappingDisabled;
-        gaps.push(instrumentationGap(off ? InstrumentationGapKind.SOURCE_MAPPING_OFF : InstrumentationGapKind.NO_SOURCE_MAPPING, off
-            ? 'source mapping is turned off for this build, so no element carries data-reticle-source'
-            : '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.
-    //
-    // BOTH arms require `stateUnwatched`, which is the store registry. Keying the first on
-    // `hasCapabilities` alone made this fire on apps whose store IS registered and readable: an app
-    // that calls `registerStore()` without `registerCapabilities()` has no declaration and a perfectly
-    // good store, and got a gap saying "no state can be read from it" in the same response that
-    // carried `reticle_state { found: true }`, a populated `stateDiffs`, and `statePathsChanged`
-    // naming the store (#700). A gap contradicted by its own response tells the agent to redo work it
-    // has already done, and teaches it to distrust the whole block.
-    //
-    // The kind is NO_STORE_REGISTERED and every sentence it carries is about stores, so the store
-    // registry is what it must be keyed on. An undeclared-capabilities app with a working store is a
-    // different observation, and if it is worth reporting it needs its own kind and its own words.
-    if (facts.stateUnwatched && (false === facts.hasCapabilities || facts.stateAsked)) {
-        // 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"'));
-    }
-    /**
-     * Say how old the debt is, when it is old enough to change what the reader should do.
-     *
-     * The ledger is a PROJECT's, deliberately — "what does this still owe" outlives one session. But an
-     * intent declared minutes ago and one abandoned last week produce the same sentence, and the second
-     * one is not about the work in front of you. Naming the age separates them without weakening the
-     * gap, and without pretending a stale backlog is this verdict's fault.
-     */
-    const DAY_MS = 86_400_000;
-    function describeIntentAge(ageMs) {
-        if (ageMs === undefined || ageMs < DAY_MS)
-            return '';
-        const days = Math.floor(ageMs / DAY_MS);
-        return ` (the oldest for ${String(days)} day${1 === days ? '' : 's'} — a backlog this old is probably not what this run is about; retire them or prove them)`;
-    }
-    // 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${describeIntentAge(facts.oldestOpenIntentAgeMs)}`, '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/observability.d.ts

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

package/dist/honesty/observability.js

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

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

@@ -1,90 +0,0 @@
-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/uncaptured-bodies.d.ts

@@ -1,23 +0,0 @@
-/**
- * Say so when a payload exists but was not recorded.
- *
- * A `reticle_network` row for a POST lists method/url/status and nothing else, and an agent reading
- * that has no way to tell "this request had no interesting payload" from "Reticle was not looking at
- * payloads". The second reading is the dangerous one: on a real payments dashboard the defect WAS
- * the payload — a refund POSTing `amount: 1187.01` into a paise field, a 100x under-refund that
- * every other field in the record agrees is a clean 200.
- *
- * So an omission is declared rather than left to inference, with the one line that fixes it. Present
- * only when a body-bearing call was returned AND no body — request or response — was recorded
- * anywhere in the result, so an app that already captures bodies pays nothing and the field's
- * PRESENCE is the warning.
- */
-export declare function bodiesNotCaptured(calls: {
-    method?: string;
-    requestBody?: string;
-    responseBody?: string;
-}[], 
-/** The page SDK's version, so the remedy can check whether it applies. See body-capture-remedy. */
-sdkVersion?: string): {
-    bodiesNotCaptured?: string;
-};

package/dist/honesty/uncaptured-bodies.js

@@ -1,41 +0,0 @@
-import { bodyCaptureRemedy } from './body-capture-remedy.js';
-/** Methods that normally carry a payload — the ones where a missing body is worth explaining. */
-const BODY_BEARING_METHODS = new Set(['POST', 'PUT', 'PATCH']);
-/**
- * Say so when a payload exists but was not recorded.
- *
- * A `reticle_network` row for a POST lists method/url/status and nothing else, and an agent reading
- * that has no way to tell "this request had no interesting payload" from "Reticle was not looking at
- * payloads". The second reading is the dangerous one: on a real payments dashboard the defect WAS
- * the payload — a refund POSTing `amount: 1187.01` into a paise field, a 100x under-refund that
- * every other field in the record agrees is a clean 200.
- *
- * So an omission is declared rather than left to inference, with the one line that fixes it. Present
- * only when a body-bearing call was returned AND no body — request or response — was recorded
- * anywhere in the result, so an app that already captures bodies pays nothing and the field's
- * PRESENCE is the warning.
- */
-export function bodiesNotCaptured(calls, 
-/** The page SDK's version, so the remedy can check whether it applies. See body-capture-remedy. */
-sdkVersion) {
-    const bodyBearing = calls.filter((c) => BODY_BEARING_METHODS.has((c.method ?? '').toUpperCase()));
-    if (0 === bodyBearing.length)
-        return {};
-    // A recorded response body anywhere in the result proves capture is ON. An absent request body
-    // then means this payload was not stringified (a multipart upload, a body the SDK skipped), not
-    // that recording is off — and firing the note would contradict the body sitting in the same
-    // result, exactly on the question the note exists to answer. (#394)
-    if (calls.some((c) => c.responseBody !== undefined))
-        return {};
-    if (bodyBearing.some((c) => c.requestBody !== undefined))
-        return {};
-    return {
-        // Framework-neutral on purpose. The first version named vite.config, and driving a Next.js app
-        // returned that advice verbatim for a SERVER ACTION — a POST a Next user cannot fix in a Vite
-        // config they do not have. Remediation that does not apply to the reader's stack is worse than
-        // none: it sends them to edit a file that is not there and reads as a tool that does not know
-        // what it is looking at.
-        bodiesNotCaptured: 'request/response bodies are NOT being recorded, so an absent body here means UNSEEN, not ' +
-            `empty — the payload of these calls was never inspected. ${bodyCaptureRemedy(sdkVersion)}`,
-    };
-}

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

@@ -1,51 +0,0 @@
-/**
- * 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>;

package/dist/honesty/undeclared-change.js

@@ -1,56 +0,0 @@
-import { NO_EDITS_OBSERVED } from '@reticlehq/core';
-/**
- * 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 async function isChangeUndeclared(
-/** The epoch the session is under now. Undefined when the page never stamped one. */
-currentEpoch, openIntents) {
-    if (undefined === currentEpoch || NO_EDITS_OBSERVED === currentEpoch)
-        return false;
-    return 0 === (await openIntents()).length;
-}

package/dist/honesty/unread-outcome.d.ts

@@ -1,10 +0,0 @@
-import { type ReticleEvent } from '@reticlehq/core';
-/**
- * The writes whose outcome went unread, as "METHOD url".
- *
- * Named rather than counted, because a caveat an agent cannot locate is a caveat it learns to skip.
- * The sentence used to say "a write returned 2xx with a response body that was never recorded" and
- * name no write, which is unactionable on any page that makes more than one call.
- */
-export declare function unreadWriteLabels(events: readonly ReticleEvent[]): string[];
-export declare function hasUnreadWriteOutcome(events: readonly ReticleEvent[]): boolean;

package/dist/honesty/unread-outcome.js

@@ -1,77 +0,0 @@
-import { EventType, MUTATING_METHODS, NetInitiator, isDevToolingUrl, } from '@reticlehq/core';
-import { asString } from '../tools/tools-helpers.js';
-const IPC_METHOD = NetInitiator.IPC.toUpperCase();
-/**
- * A write whose outcome is sitting in a payload nobody read.
- *
- * `findBodyFailures` catches a 2xx that reports failure inside its body — but only when body capture
- * is on, and it is OFF by default. Without this, the same window produces `verified: "yes"` with the
- * reason "no channel disagreeing", which is true only because one channel was never opened. That is
- * lying by omission, and it is the precise failure this honesty layer exists to prevent.
- *
- * Measured on a shipments console: `POST /api/bulk-hold` → 200, banner reads "9 shipments held",
- * three of the nine failed inside the body. With capture on Reticle now says so. With capture off it
- * said `verified: "yes"`.
- *
- * Deliberately narrow, because over-warning trains agents to ignore the field:
- *
- *  - **writes only.** A GET's payload is what the UI renders, so the DOM already witnesses it. A
- *    write's outcome has no other witness.
- *  - **a payload that DEMONSTRABLY exists.** `responseSize > 0` with no recorded body means unread.
- *    An absent size or a genuinely empty response says nothing and is left alone — the distinction
- *    between "empty" and "unseen" is the whole point, so it must not be guessed.
- *  - **HTTP only.** An IPC record is excluded, and the reason is the rule's own premise: a 2xx is
- *    emitted by a framework whatever the app decided, so it describes the transport. An IPC `ok`
- *    means the main-process handler ran to completion without throwing — an application-level
- *    verdict, already reported. Treating the two as equivalent made every ordinary Electron action
- *    return `unknown` (measured: a healthy `todos:add` on the default config), which is the
- *    cry-wolf failure that teaches agents to ignore the field.
- *
- *    The residual gap is real and narrower: a handler that RESOLVES with a failure inside its payload
- *    is invisible without body capture. That case is `findBodyFailures`, which reads the payload and
- *    catches it precisely — with capture on, where it belongs.
- *
- *  - **the app's own traffic only.** The DEV TOOLCHAIN writes too: Next's overlay answers
- *    `POST /__nextjs_original-stack-frames` with a JSON body the moment the app logs one React
- *    warning, and nothing captures it. Judged as the app's write, that made every verdict in a Next
- *    dev app `unknown` — decided by a channel the caller never asked about, on a request the app did
- *    not make. `findContradictions` has split this traffic out for the same reason since the overlay
- *    turned correct navigations red; this rule was reading the unsplit window.
- */
-const OK_MIN = 200;
-const OK_MAX = 300;
-/**
- * The writes whose outcome went unread, as "METHOD url".
- *
- * Named rather than counted, because a caveat an agent cannot locate is a caveat it learns to skip.
- * The sentence used to say "a write returned 2xx with a response body that was never recorded" and
- * name no write, which is unactionable on any page that makes more than one call.
- */
-export function unreadWriteLabels(events) {
-    const labels = [];
-    for (const event of events) {
-        if (event.type !== EventType.NET_REQUEST)
-            continue;
-        const method = ('string' === typeof event.data['method'] ? event.data['method'] : '').toUpperCase();
-        if (method === IPC_METHOD || !MUTATING_METHODS.includes(method))
-            continue;
-        const url = asString(event.data['url']);
-        if (isDevToolingUrl(url))
-            continue;
-        const status = event.data['status'];
-        if (typeof status !== 'number' || status < OK_MIN || status >= OK_MAX)
-            continue;
-        if (event.data['responseBody'] !== undefined)
-            continue; // read — findBodyFailures judged it
-        const size = event.data['responseSize'];
-        if ('number' !== typeof size || size <= 0)
-            continue;
-        const label = `${method} ${url ?? ''}`.trim();
-        if (!labels.includes(label))
-            labels.push(label);
-    }
-    return labels;
-}
-export function hasUnreadWriteOutcome(events) {
-    return unreadWriteLabels(events).length > 0;
-}

package/dist/honesty/unsettled.d.ts

@@ -1,58 +0,0 @@
-/**
- * What an `unsettled` verdict was waiting for, and what its window held instead.
- *
- * `unsettled` is the commonest reason a verdict comes back `unknown`, and all it said was that the
- * page "never settled" — a sentence equally true of a page that polls, a page that animates, and a
- * page whose write is still open. Those need three different next moves, and an agent handed the
- * sentence cannot tell which it is holding, so the drive stops there. An `unknown` that explains
- * itself is a retry; one that does not is a dead end.
- *
- * Two releases already tuned this window and neither is undone here. The budget is still spent in
- * full before anything is called unsettled (settle-in-flight.ts), and the app is still given its
- * reaction window before any accusation (waitForReaction). This only describes what was true at the
- * moment the budget genuinely ran out.
- *
- * It rides in `because`, beside `verifiedReason`, rather than in a field of its own: the verdict has
- * one sentence an agent is known to read, and a caveat parked anywhere else is a caveat nobody reads.
- */
-import type { Predicate } from '../events/predicate.js';
-export interface UnsettledWindow {
-    /** What the wait was for, in the caller's own terms — see `describeWaitTarget`. */
-    waitedFor: string;
-    /** Requests that started in this window and had not come back, as "METHOD url". */
-    stillInFlight: readonly string[];
-    /**
-     * Endpoints called more than once in this window, as "METHOD url ×N" — see `repeatedRequestLabels`.
-     *
-     * The case `stillInFlight` structurally cannot see: a retry loop against a dead backend completes
-     * every attempt, so nothing is ever outstanding, and the verdict fell through to a sentence that
-     * blamed unnamed churn on an app whose whole problem was one endpoint being hammered. Optional —
-     * a caller that does not supply it gets exactly the sentence that shipped before.
-     */
-    repeated?: readonly string[];
-}
-/**
- * The wait, in one phrase.
- *
- * The default matters most: a call that declares no `until` waits for the page to go IDLE, and an
- * agent that never chose that wait cannot be expected to recognise it in a timeout about it.
- */
-export declare function describeWaitTarget(predicate: Predicate): string;
-/**
- * Did the assertion name a request that is still open?
- *
- * `waitForPredicate` reports a miss ("no request to /register") the moment the budget ends, even
- * when that same POST is sitting in `stillInFlight`. Grading that miss `no` is a race against the
- * backend, not a defect. Matching is the discriminator: an unrelated poll left open does not pardon
- * a named URL that never started.
- */
-export declare function namedNetIsInFlight(predicate: Predicate, stillInFlight: readonly string[]): boolean;
-/**
- * The `because` sentence for an unsettled verdict: the wait, the observation, the next move.
- *
- * The two branches are the point. An outstanding write is worth waiting for and worth asserting
- * directly; page churn is neither, and telling an agent to raise its timeout on churn sells it a
- * slower dead end. Without the detail the sentence is the one that shipped before, so a caller that
- * cannot supply the facts loses nothing.
- */
-export declare function unsettledBecause(base: string, window: UnsettledWindow | undefined): string;