@reticlehq/server 2.14.0 → 3.2.0

package/dist/honesty/blind-spots.js

@@ -1,248 +0,0 @@
-/**
- * Blind-spot register — the never-silent statement of what the layer CANNOT see. Closed shadow roots,
- * cross-origin iframes, and virtualized-unmounted rows are documented limits; a result that touched one
- * says so (`coverage: partial — 2 cross-origin frames unobserved`) instead of implying it saw everything.
- * Pure formatting over the counted blind spots the observers report.
- */
-// The kind enum lives in core (it crosses the wire in a BLIND_SPOT event); re-exported here so existing
-// honesty-side imports keep working.
-export { BlindSpotKind } from '@reticlehq/core';
-import { AppRuntime, BlindSpotKind, EventType, PredicateKind, ReticleEnv, TRANSPORT_LIMITS, isDesktopBlindSpot, } from '@reticlehq/core';
-/**
- * Whether the observation window saw everything it was asked about.
- *
- * NOT core's VerdictStatus, which happens to spell one of its values 'partial' too: that one grades
- * a verification RUN (some flows passed, some failed), this one grades what could be OBSERVED. Two
- * meanings behind one string is exactly how a comparison ends up reading the wrong field, so they
- * stay separate vocabularies.
- */
-export const Coverage = {
-    FULL: 'full',
-    PARTIAL: 'partial',
-};
-const LABEL = {
-    [BlindSpotKind.CLOSED_SHADOW_ROOT]: (n) => `${String(n)} closed shadow root${1 === n ? '' : 's'} unobserved`,
-    [BlindSpotKind.CROSS_ORIGIN_IFRAME]: (n) => `${String(n)} cross-origin frame${1 === n ? '' : 's'} unobserved`,
-    // The DOM of these frames IS observed; only their network is not. Saying so precisely matters — a
-    // flat "unobserved" would discard a real capability and push agents back to guessing.
-    [BlindSpotKind.UNINSTRUMENTED_FRAME]: (n) => `${String(n)} same-origin frame${1 === n ? '' : 's'} observed for DOM but not network — requests they make are invisible`,
-    [BlindSpotKind.VIRTUALIZED_UNMOUNTED]: (n) => `${String(n)} virtualized unmounted row${1 === n ? '' : 's'} unobserved`,
-    // Not "some rows we could not see" — the events never reached the observer, so this window is a
-    // SAMPLE of what the app did. Phrased as a caveat on what the whole result MEANS.
-    // Names a NUMBER, not a variable. "Raise it for a busy app" leaves the reader to invent a value,
-    // and the one who reported this had to guess before finding one that worked. The default was
-    // raised in the same change, so a page still hitting the cap after that is genuinely unusual and
-    // deserves a concrete next value rather than an adjective.
-    [BlindSpotKind.RATE_LIMITED]: (n) => `${String(n)} event${1 === n ? '' : 's'} dropped by the bridge rate cap, so this window is SAMPLED. Set ${ReticleEnv.MAX_MESSAGES_PER_SECOND}=${String(TRANSPORT_LIMITS.MAX_MESSAGES_PER_SECOND * 5)} and restart the daemon, then re-run this drive`,
-    // Not a count of things — a single fact about the page. Phrased so the coverage line reads as a
-    // caveat on what the network view MEANS, not as a tally.
-    // A count of unverifiable ACTIONS, not of things we failed to look at. The distinction matters:
-    // nothing here was missed, there was simply never a verdict to observe, and no amount of extra
-    // instrumentation would produce one.
-    [BlindSpotKind.VERDICTLESS_SEND]: (n) => `${String(n)} one-way IPC send${1 === n ? '' : 's'} dispatched with NO verdict — the renderer never learns whether the main process handled ${1 === n ? 'it' : 'them'}, so this cannot be confirmed from the page`,
-    // Not a tally — a fact about the app's wiring, phrased as what the EMPTY state channel means. An
-    // agent reading `stateDiffs: []` otherwise reads "the app changed no state", which is a claim
-    // nothing here can support. Names the one-line fix, because the reader is the one who can apply it.
-    [BlindSpotKind.UNWATCHED_STATE]: () => 'no subscribable store is registered, so NO state change is observed — an empty stateDiffs here means unwatched, not unchanged (register the store itself in your reticle-dev module: registerStore(name, store), not a getter)',
-    [BlindSpotKind.WRAPPED_NETWORK]: () => 'fetch was already wrapped before Reticle, so recorded requests may differ from what was sent',
-    // A fact about the app's wiring, not a tally. Says what a network view WITHOUT ipc:// records
-    // MEANS, because that state here is indistinguishable from "this app made no backend calls" —
-    // and that reading is the false green: every IPC call went unseen and every `assert { net }` over
-    // them is vacuous. Document-initiated loads ARE seen since subresource observation (#447), so
-    // the note names the missing half instead of claiming the whole view is blind.
-    [BlindSpotKind.UNOBSERVED_IPC]: () => "this Electron renderer has no Reticle preload, so NO ipcRenderer.invoke is observed; document-initiated loads may still appear, so a view with no ipc:// records means unseen IPC, not none (add require('@reticlehq/electron/preload') to your preload)",
-};
-/**
- * Blind spots that IMPEACH the capture, as opposed to bounding what it covers.
- *
- * The distinction decides whether a verdict is downgraded to UNKNOWN or merely carries a caveat, and
- * conflating them breaks the tool in one direction or the other:
- *
- *  - **Impeaching**: events were DROPPED, so the window itself is a sample and any claim over it may
- *    be a false negative. Nothing observed can be trusted to be complete.
- *  - **Bounding**: a region is structurally unobservable — a cross-origin frame, a closed shadow
- *    root, the 9,970 virtualized rows that were never rendered. What WAS observed is completely and
- *    correctly observed; there is simply a boundary, and it is usually permanent.
- *
- * Treating the second kind as impeaching made every verdict on any virtualized list UNKNOWN — which
- * is most data-heavy software, permanently. A tool that answers "unknown" to everything is as
- * useless as one that answers "yes" to everything, and it is the same failure: a verdict that does
- * not depend on the evidence.
- */
-export function impeachesCapture(kind) {
-    return kind === BlindSpotKind.RATE_LIMITED;
-}
-/** Compose the coverage statement. `full` (no note) when nothing was unobserved. */
-export function buildCoverageStatement(spots) {
-    const present = spots.filter((s) => s.count > 0);
-    if (0 === present.length)
-        return { coverage: Coverage.FULL, spots: [] };
-    // Each label carries its own ending. Appending a blanket " unobserved" here produced
-    // "...may differ from what was sent unobserved" for the wrapped-network caveat, which is a
-    // sentence rather than a count — and the same dangle appeared the moment a second prose-shaped
-    // spot (rate-limited sampling) was added.
-    // A kind this daemon does not know about still has to READ as a blind spot. An SDK newer than the
-    // daemon can report one, and `LABEL[kind](count)` threw a TypeError on the verdict path when it
-    // did — turning "there is something I could not see" into a crashed assert, which is worse than
-    // either the caveat or the silence. Unknown kinds degrade to their own name.
-    const label = (s) => 'function' === typeof LABEL[s.kind] ? LABEL[s.kind](s.count) : `${s.kind} (${String(s.count)})`;
-    const note = `${Coverage.PARTIAL} — ${present.map(label).join(', ')}`;
-    return { coverage: Coverage.PARTIAL, note, spots: present };
-}
-/**
- * Reduce a window's BLIND_SPOT events to one spot per kind — the LATEST reported count wins (the sensor
- * emits only on change, so the last value is the live count). This is how a result's coverage is derived
- * from what the SDK observed during the action, with no extra round-trip.
- */
-export function blindSpotsFromEvents(events) {
-    const latest = new Map();
-    for (const e of events) {
-        if (e.type !== EventType.BLIND_SPOT)
-            continue;
-        const kind = e.data['kind'];
-        const count = e.data['count'];
-        if ('string' === typeof kind && 'number' === typeof count) {
-            latest.set(kind, count);
-        }
-    }
-    return [...latest].map(([kind, count]) => ({ kind, count }));
-}
-/**
- * Drop Electron-only coverage rows unless this session is actually an Electron renderer.
- *
- * The kinds live in the same vocabulary as "no store registered", so listing whatever is present
- * reported a Vite + React tab as an un-instrumented Electron renderer. The session already knows
- * the runtime (PAGE_HEALTH). Unknown runtime (older SDK) keeps the rows — dropping them would hide
- * a real missing-preload warning.
- */
-export function spotsForRuntime(spots, runtime) {
-    if (runtime === undefined || AppRuntime.ELECTRON === runtime)
-        return [...spots];
-    return spots.filter((spot) => !isDesktopBlindSpot(spot.kind));
-}
-/**
- * Blind spots from the session's remembered LEVEL state rather than from a window of events.
- *
- * The SDK emits BLIND_SPOT only when the count changes, so a page that mounted cross-origin frames at
- * load announces them once and is silent thereafter. Deriving coverage from one act's window then
- * reports "full" for a page a third of which is unobservable — and the act tool's own description
- * tells harnesses to gate on that block. Ask the session what is true now instead of inferring it
- * from what happened to be said recently.
- *
- * `runtime` gates Electron-only kinds (see `spotsForRuntime`) so a web session cannot inherit them
- * from the coverage vocabulary.
- */
-export function blindSpotsFromState(state, runtime) {
-    const spots = Object.entries(state).map(([kind, count]) => ({
-        kind: kind,
-        count,
-    }));
-    return spotsForRuntime(spots, runtime);
-}
-/**
- * Events the BROWSER's own transport queue threw away inside this window, or 0.
- *
- * `RATE_LIMITED` — the BRIDGE sampling because events arrived faster than its per-second cap — is
- * already the one blind spot that `impeachesCapture`, on the reasoning that a green over a window
- * you did not fully see "would only describe what was observed". `TRANSPORT_OVERFLOW` is the exact
- * same loss on the other side of the wire, and it was read in journal rollups and NOWHERE on the
- * verdict path. So the identical condition downgraded a verdict from one side of the socket and was
- * invisible from the other: a window that dropped 34 events graded `proved`, in a sentence whose own
- * words were "over a clean capture".
- *
- * `TRUNCATED` is deliberately NOT counted. It names the channel it capped (a DOM-mutation flood on
- * any busy page) and is routine churn; treating it as lost evidence would caveat every verdict on
- * every real app, and a caveat that is always present is one nobody reads. TRANSPORT_OVERFLOW is the
- * honest "arbitrary events are gone" marker — it cannot say which.
- */
-function droppedByTransport(events) {
-    let dropped = 0;
-    for (const e of events) {
-        if (e.type !== EventType.TRANSPORT_OVERFLOW)
-            continue;
-        const n = e.data['dropped'];
-        dropped += 'number' === typeof n ? n : 0;
-    }
-    return dropped;
-}
-/**
- * When an absence assertion targets a page with regions Reticle cannot observe, "the element is
- * absent" means only "it is absent in what I CAN see". Returns a note when that distinction
- * matters, undefined otherwise.
- *
- * Fires on three blind-spot kinds:
- *   - CROSS_ORIGIN_IFRAME (only when the predicate is scoped to a frame region)
- *   - VIRTUALIZED_UNMOUNTED — a row that was never rendered could hold the element
- *   - CLOSED_SHADOW_ROOT — a subtree Reticle cannot see into
- */
-export function absenceBlindSpotNote(predicate, spots) {
-    // `not(element)` is the third spelling of an absence assertion — the `not` wrapper IS the
-    // negation, so the inner predicate will not carry `absent: true`. Unwrap and synthesize it.
-    // `not(element { absent: true })` is a double negative — presence — and a positive match is
-    // not threatened by an unobservable region.
-    if (PredicateKind.NOT === predicate.kind && predicate.predicate !== undefined) {
-        if (PredicateKind.ELEMENT === predicate.predicate.kind) {
-            if (true === predicate.predicate.absent)
-                return undefined;
-            return absenceBlindSpotNote({ ...predicate.predicate, absent: true }, spots);
-        }
-        return undefined;
-    }
-    if (PredicateKind.ELEMENT !== predicate.kind || true !== predicate.absent)
-        return undefined;
-    const relevant = spots.filter((spot) => spot.count > 0 &&
-        (spot.kind === BlindSpotKind.CROSS_ORIGIN_IFRAME
-            ? undefined !== predicate.query?.scope
-            : spot.kind === BlindSpotKind.VIRTUALIZED_UNMOUNTED ||
-                spot.kind === BlindSpotKind.CLOSED_SHADOW_ROOT));
-    if (0 === relevant.length)
-        return undefined;
-    const statement = buildCoverageStatement(relevant);
-    return `the absence assertion targeted a region Reticle could not observe (${statement.note ?? 'partial coverage'}), so a passing DOM check cannot prove absence`;
-}
-/** The impeaching note for a transport gap, or undefined when the window was intact. */
-export function transportGapNote(events) {
-    const dropped = droppedByTransport(events);
-    return 0 === dropped
-        ? undefined
-        : `the browser dropped ${String(dropped)} event(s) in this window (transport queue overflow), so events that would have contradicted this may never have arrived`;
-}
-/**
- * Is the state channel dark?
- *
- * Nothing subscribed means NO state change is observed, so an empty `stateDiffs` is a statement
- * about Reticle rather than about the app. Derived here, once, because two callers now need it —
- * the act path's causal summary and the instrumentation-gap surface — and a second spelling of this
- * predicate would eventually disagree with the first about what "unwatched" means.
- */
-export function isStateUnwatched(spots) {
-    return spots.some((spot) => spot.kind === BlindSpotKind.UNWATCHED_STATE && spot.count > 0);
-}
-/**
- * Does a passing verdict on this predicate REST on the window being complete?
- *
- * Only an absence claim does. A positive assertion that passed found its evidence, and events aged
- * out elsewhere in the buffer do not unmake it. An absence claim concluded "nothing is there" — and
- * the thing the buffer dropped is precisely the disproof, so "absent" degrades to "absent in what I
- * still hold".
- *
- * The distinction is not optional. Scarce-loss is recorded for AGE eviction too, so `lostSince(0)`
- * is true on any session older than the 60s cutoff; impeaching every verdict over a caller-chosen
- * window would make `unknown` the answer to everything, which this repo has already paid for once.
- */
-export function restsOnCompleteWindow(predicate) {
-    if (PredicateKind.NOT === predicate.kind)
-        return true;
-    // An exact cardinality of ZERO is the third spelling of an absence claim, and reading only
-    // `absent` missed it: `{ kind: "net", urlContains: "/api/auth/sign-in", count: 0 }` says "this
-    // request was never made", and the call the buffer evicted is precisely the disproof. It was
-    // graded `yes` over a window known to have lost scarce evidence — the exact false green the two
-    // clauses above exist to prevent, reached by the one spelling they did not cover (#668).
-    //
-    // Only zero. `count: 2` asserts calls were MADE and found them; events aged out elsewhere in the
-    // buffer do not unmake a positive finding, which is the same reason a plain presence assertion is
-    // left alone here.
-    if (0 === predicate.count)
-        return true;
-    return true === predicate.absent;
-}

package/dist/honesty/body-capture-remedy.d.ts

@@ -1,42 +0,0 @@
-/**
- * What to tell a caller whose assertion needs response bodies, given what the connected SDK can do.
- *
- * The remedy used to be one fixed sentence naming `captureNetworkBodies`. Reported from the field:
- * six verdicts came back `unknown`/`outcome_unread` advising that setting against a pinned
- * `@reticlehq/react` from before it existed. The reporter set the env var, restarted, got the
- * identical message, and worked it out by elimination.
- *
- * The daemon is TOLD the page's SDK version at HELLO and threw it away after computing skew. Nothing
- * new has to be observed to say the true thing — it only has to be kept.
- *
- * Same class as the version-skew remedy that named a React package on Vue projects: remedy text that
- * does not check whether it applies. A wrong remedy is worse than none, because it is followed.
- */
-/** The release that introduced `captureNetworkBodies` — see the browser observer's history. */
-export declare const BODY_CAPTURE_MIN_VERSION = "2.4.0";
-/**
- * The remedy for this session, or the honest statement that there is none.
- *
- * An UNKNOWN version is treated as capable. A hand-wired connect reports none, and guessing "too
- * old" there would hide a working fix from someone who could have used it; the opposite guess costs
- * one wasted read. The asymmetry decides it.
- */
-export declare function bodyCaptureRemedy(sdkVersion: string | undefined): string;
-/**
- * Refuse a body clause the session cannot answer, BEFORE the action is spent.
- *
- * Reported: an `act_and_wait` matched the right call and returned `verified: "no"` with "a matching
- * call with no recorded body", because that project's `connect()` does not pass
- * `captureNetworkBodies` — and the reporter could not change it, since it was not their project's
- * config to edit for an unrelated verification task. The action bought nothing that was not knowable
- * in advance, and on a drive that mutates state an action is not always repeatable. That is what
- * makes this a pre-flight rather than a better failure message.
- *
- * Refuses ONLY on a DECLARED `captureBodies: false`. An SDK too old to announce the setting sends
- * nothing, and refusing on silence would break every session predating the announcement for a clause
- * many of them satisfy — the same asymmetry that makes an unknown VERSION count as capable.
- */
-export declare function bodyClauseRefusal(predicate: unknown, session: {
-    captureBodies?: boolean | undefined;
-    sdkVersion?: string | undefined;
-}): string | undefined;

package/dist/honesty/body-capture-remedy.js

@@ -1,95 +0,0 @@
-/**
- * What to tell a caller whose assertion needs response bodies, given what the connected SDK can do.
- *
- * The remedy used to be one fixed sentence naming `captureNetworkBodies`. Reported from the field:
- * six verdicts came back `unknown`/`outcome_unread` advising that setting against a pinned
- * `@reticlehq/react` from before it existed. The reporter set the env var, restarted, got the
- * identical message, and worked it out by elimination.
- *
- * The daemon is TOLD the page's SDK version at HELLO and threw it away after computing skew. Nothing
- * new has to be observed to say the true thing — it only has to be kept.
- *
- * Same class as the version-skew remedy that named a React package on Vue projects: remedy text that
- * does not check whether it applies. A wrong remedy is worse than none, because it is followed.
- */
-/** The release that introduced `captureNetworkBodies` — see the browser observer's history. */
-export const BODY_CAPTURE_MIN_VERSION = '2.4.0';
-/**
- * Compare two dotted versions numerically.
- *
- * String comparison inverts exactly where it hurts: `'2.10.0' < '2.4.0'` lexically, so a NEWER SDK
- * would be told it is too old and the working remedy withheld. A prerelease suffix is dropped rather
- * than parsed — `2.13.0-rc.1` is 2.13 for this question, and nothing here needs finer.
- */
-function isAtLeast(version, minimum) {
-    const parts = (v) => v
-        .split('-')[0]
-        ?.split('.')
-        .map((n) => Number.parseInt(n, 10) || 0) ?? [];
-    const have = parts(version);
-    const want = parts(minimum);
-    for (let i = 0; i < Math.max(have.length, want.length); i += 1) {
-        const a = have[i] ?? 0;
-        const b = want[i] ?? 0;
-        if (a !== b)
-            return a > b;
-    }
-    return true;
-}
-/** The sentence naming the setting — only ever produced for an SDK that HAS it. */
-const ENABLE_IT = 'Turn it on where your app calls connect(): `reticle.connect({ captureNetworkBodies: true })`, ' +
-    'or for the Vite plugin `reticle({ captureNetworkBodies: true })` / VITE_RETICLE_CAPTURE_BODIES=1. ' +
-    'Then re-run the action.';
-/**
- * The remedy for this session, or the honest statement that there is none.
- *
- * An UNKNOWN version is treated as capable. A hand-wired connect reports none, and guessing "too
- * old" there would hide a working fix from someone who could have used it; the opposite guess costs
- * one wasted read. The asymmetry decides it.
- */
-export function bodyCaptureRemedy(sdkVersion) {
-    if (sdkVersion !== undefined && !isAtLeast(sdkVersion, BODY_CAPTURE_MIN_VERSION)) {
-        return (`this page's SDK is ${sdkVersion}, and body capture needs ${BODY_CAPTURE_MIN_VERSION} or ` +
-            'newer — the setting does not exist in your version, so there is nothing to switch on. ' +
-            'Upgrade the SDK, or assert on something else this session can see.');
-    }
-    return ENABLE_IT;
-}
-/** Clause names that can only be answered from a recorded body. */
-const BODY_CLAUSE_FIELDS = ['bodyContains', 'requestBodyContains'];
-/** Does this predicate, or anything nested in it, ask about a body? */
-function asksAboutBody(predicate) {
-    if (null === predicate || 'object' !== typeof predicate)
-        return false;
-    const node = predicate;
-    if (BODY_CLAUSE_FIELDS.some((f) => node[f] !== undefined))
-        return true;
-    // The reported shape is an `allOf` carrying route + console + the net clause that needs bodies.
-    // Checking only the top level would miss every realistic call.
-    const nested = node['predicates'] ?? node['predicate'];
-    if (Array.isArray(nested))
-        return nested.some(asksAboutBody);
-    return asksAboutBody(nested);
-}
-/**
- * Refuse a body clause the session cannot answer, BEFORE the action is spent.
- *
- * Reported: an `act_and_wait` matched the right call and returned `verified: "no"` with "a matching
- * call with no recorded body", because that project's `connect()` does not pass
- * `captureNetworkBodies` — and the reporter could not change it, since it was not their project's
- * config to edit for an unrelated verification task. The action bought nothing that was not knowable
- * in advance, and on a drive that mutates state an action is not always repeatable. That is what
- * makes this a pre-flight rather than a better failure message.
- *
- * Refuses ONLY on a DECLARED `captureBodies: false`. An SDK too old to announce the setting sends
- * nothing, and refusing on silence would break every session predating the announcement for a clause
- * many of them satisfy — the same asymmetry that makes an unknown VERSION count as capable.
- */
-export function bodyClauseRefusal(predicate, session) {
-    if (false !== session.captureBodies)
-        return undefined;
-    if (!asksAboutBody(predicate))
-        return undefined;
-    return ('this assertion reads a request/response BODY, and this session is not recording them — it ' +
-        `would fail whatever the app did. Nothing ran, so no action was spent. ${bodyCaptureRemedy(session.sdkVersion)}`);
-}

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

@@ -1,151 +0,0 @@
-import { type Intent, type JournalAction } from '@reticlehq/core/artifacts';
-/**
- * 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. */
-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;
-export {};