@reticlehq/server 2.14.0 → 3.2.0

package/dist/honesty/feature-capture.js

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

package/dist/honesty/gap-ledger.d.ts

@@ -1,52 +0,0 @@
-import { type InstrumentationGap } from '@reticlehq/core/artifacts';
-/**
- * What this session still cannot see, accumulated across its verdicts.
- *
- * A gap reported on one verdict and then forgotten is a note. A gap that is still standing when the
- * agent asks "am I done?" is a piece of work — and that difference is the entire discipline
- * mechanism, because an agent finishing a task is the one moment it will act on a cost it can close.
- *
- * ## Why the LAST verdict decides, not the whole history
- *
- * The honest question is "is this app still unverifiable in this way", not "was it ever". An agent
- * that hits a gap, adds the build plugin and re-verifies has CLOSED it — the later verdict simply
- * stops emitting that kind — and a ledger that still reported it would punish exactly the behaviour
- * this exists to cause. Nobody instruments an app twice for a tool that never notices the first time.
- *
- * So `open()` reflects the most recent verdict, and `everSeen` is kept separately for the summary,
- * where "you hit this and fixed it" is worth saying and is not a reason to withhold done.
- */
-export declare class GapLedger {
-    #private;
-    /**
-     * Record what the verdict just reported. An empty list is a real observation — it is how a gap
-     * gets closed — so it must not be ignored as "nothing to record".
-     */
-    note(gaps: readonly InstrumentationGap[]): void;
-    /** Gaps the most recent verdict still reported. The ones that are work right now. */
-    open(): readonly InstrumentationGap[];
-    /** Every kind seen in this session, including ones since closed. */
-    get everSeen(): readonly string[];
-    /**
-     * Did this session leave the app less verifiable than it could be?
-     *
-     * The one question a "have I finished" call needs answered, and the one a session summary turns
-     * into `unproven` rather than `verified`.
-     */
-    get hasOpen(): boolean;
-}
-/**
- * Record a verdict's gaps against the session that produced it.
- *
- * Tolerates a session with no ledger, and that is a statement about the seam rather than a hedge:
- * `Session` is satisfied structurally, and dozens of specs — plus any consumer embedding this engine
- * — build one as an object literal rather than through the constructor. Such a session is a real
- * caller, it simply keeps no ledger, and recording is a side effect that must never be the reason a
- * verdict fails to return.
- *
- * One helper rather than an optional-chain at each call site: the tolerance is a decision, and a
- * decision spelled `?.` in two places is one nobody can find later.
- */
-export declare function noteSessionGaps(session: {
-    gaps?: GapLedger;
-}, gaps: readonly InstrumentationGap[]): void;

package/dist/honesty/gap-ledger.js

@@ -1,63 +0,0 @@
-import { dedupeGaps } from '@reticlehq/core/artifacts';
-/**
- * What this session still cannot see, accumulated across its verdicts.
- *
- * A gap reported on one verdict and then forgotten is a note. A gap that is still standing when the
- * agent asks "am I done?" is a piece of work — and that difference is the entire discipline
- * mechanism, because an agent finishing a task is the one moment it will act on a cost it can close.
- *
- * ## Why the LAST verdict decides, not the whole history
- *
- * The honest question is "is this app still unverifiable in this way", not "was it ever". An agent
- * that hits a gap, adds the build plugin and re-verifies has CLOSED it — the later verdict simply
- * stops emitting that kind — and a ledger that still reported it would punish exactly the behaviour
- * this exists to cause. Nobody instruments an app twice for a tool that never notices the first time.
- *
- * So `open()` reflects the most recent verdict, and `everSeen` is kept separately for the summary,
- * where "you hit this and fixed it" is worth saying and is not a reason to withhold done.
- */
-export class GapLedger {
-    #open = [];
-    #everSeen = new Set();
-    /**
-     * Record what the verdict just reported. An empty list is a real observation — it is how a gap
-     * gets closed — so it must not be ignored as "nothing to record".
-     */
-    note(gaps) {
-        this.#open = dedupeGaps(gaps);
-        for (const gap of gaps)
-            this.#everSeen.add(gap.kind);
-    }
-    /** Gaps the most recent verdict still reported. The ones that are work right now. */
-    open() {
-        return this.#open;
-    }
-    /** Every kind seen in this session, including ones since closed. */
-    get everSeen() {
-        return [...this.#everSeen];
-    }
-    /**
-     * Did this session leave the app less verifiable than it could be?
-     *
-     * The one question a "have I finished" call needs answered, and the one a session summary turns
-     * into `unproven` rather than `verified`.
-     */
-    get hasOpen() {
-        return this.#open.length > 0;
-    }
-}
-/**
- * Record a verdict's gaps against the session that produced it.
- *
- * Tolerates a session with no ledger, and that is a statement about the seam rather than a hedge:
- * `Session` is satisfied structurally, and dozens of specs — plus any consumer embedding this engine
- * — build one as an object literal rather than through the constructor. Such a session is a real
- * caller, it simply keeps no ledger, and recording is a side effect that must never be the reason a
- * verdict fails to return.
- *
- * One helper rather than an optional-chain at each call site: the tolerance is a decision, and a
- * decision spelled `?.` in two places is one nobody can find later.
- */
-export function noteSessionGaps(session, gaps) {
-    session.gaps?.note(gaps);
-}

package/dist/honesty/honesty.d.ts

@@ -1,103 +0,0 @@
-/**
- * The honesty block — one machine-readable field composing everything that qualifies a verdict's
- * trustworthiness: the assertion grade, the attribution tier, the envelope maturity, the verified-surface
- * coverage, and the capture integrity. The invariant: a green may never LOOK stronger than its honesty
- * block. Harnesses gate on it (e.g. "grade ≥ net AND integrity clean"). This is pure composition +
- * assessment — all five components already exist individually; wiring it onto results is a later step.
- */
-import type { CaptureLoss } from '@reticlehq/core';
-/** Assertion grade, strongest first — the tier the verdict actually proved. */
-export declare const HonestyGrade: {
-    readonly SIGNAL: "signal";
-    readonly NET: "net";
-    readonly STATE: "state";
-    readonly PRESENCE: "presence";
-    readonly NONE: "none";
-};
-export type HonestyGrade = (typeof HonestyGrade)[keyof typeof HonestyGrade];
-interface HonestyInputs {
-    grade: HonestyGrade;
-    /** Present when a causal chain is presented; `window` = time-heuristic, never dataflow truth. */
-    attribution?: string;
-    envelopeSamples?: number;
-    coveragePct?: number;
-    coveragePartial?: boolean;
-    /**
-     * The sentence naming WHAT went unobserved, from `buildCoverageStatement`.
-     *
-     * Separate from `blindSpots`, which carries only the IMPEACHING notes — the ones that downgrade a
-     * verdict. A bounding spot does not impeach anything, so it never entered that list, and the flag
-     * that survived (`partial: true`) is unanswerable on its own: the verdict prose tells the reader
-     * to see `coverage` for what went unobserved, and there was nothing there to see.
-     */
-    coverageNote?: string;
-    truncated?: boolean;
-    blindSpots?: readonly string[];
-    /**
-     * The machine-readable half of `issues` — WHICH kind of loss, from core's closed `CaptureLoss`.
-     *
-     * `issues` is prose built for an agent to read, and prose is not something a dashboard can group
-     * by: `unclean_capture` became a large share of all field verdicts with no way to ask which of its three
-     * causes produced them. Passed by the caller rather than derived here, because only the caller
-     * knows whether a blind-spot note came from the browser transport or from a boundary in the page.
-     */
-    losses?: readonly CaptureLoss[];
-    /**
-     * Did the page go quiet inside the action's window? Omitted when nothing measured it.
-     *
-     * Settlement stopped being a veto over a declared consequence that held (see `verified.ts`), and a
-     * fact that no longer decides the verdict must not therefore disappear: a page that never goes
-     * idle is worth knowing about, and a caller who cares can still gate on it. Reported here rather
-     * than beside `verified`, where the answer belongs to the rule and not to its inputs.
-     */
-    settled?: boolean;
-}
-export interface HonestyBlock {
-    grade: HonestyGrade;
-    attribution?: string;
-    /** Present only when an envelope was actually sampled — never a fabricated zero. */
-    envelope?: {
-        samples: number;
-        sufficient: boolean;
-    };
-    /** `pct` is present only when it was measured (or provably full); `partial` is always known. */
-    coverage: {
-        pct?: number;
-        partial: boolean;
-        note?: string;
-    };
-    integrity: {
-        clean: boolean;
-        issues: string[];
-        losses?: CaptureLoss[];
-    };
-    /** Whether the page went quiet in this window — present only when it was measured. */
-    settled?: boolean;
-}
-export declare function buildHonestyBlock(inputs: HonestyInputs): HonestyBlock;
-interface HonestyBar {
-    /** The minimum grade a green must carry to be trusted (default: any). */
-    minGrade?: HonestyGrade;
-    /** Require capture integrity to be clean (no truncation / blind spots). */
-    requireIntegrityClean?: boolean;
-}
-/** Whether a verdict's honesty block clears the harness's bar. Reasons list every failed criterion. */
-export declare function meetsHonestyBar(block: HonestyBlock, bar?: HonestyBar): {
-    ok: boolean;
-    reasons: string[];
-};
-/**
- * The coverage sentence, kept only on a verdict that points at it.
- *
- * Exactly one branch of `decideVerified` promises it — the YES branch says "coverage was PARTIAL —
- * see `coverage` for what went unobserved". UNKNOWN keeps it too, because "I could not tell" is a
- * statement about what went unseen and the note is the answer. A NO has already named a concrete
- * counter-example, nothing directs the reader to `coverage`, and `partial` plus the spot kinds still
- * travel — so the prose there is cost with no question behind it.
- *
- * Measured: emitting it on every verdict regressed the benchmark's verification efficiency by 4.1%,
- * one note per observation. Accuracy outranks tokens, but this buys no accuracy — the promise is
- * kept wherever it is made.
- */
-export declare function honestyForVerdict(verified: string, honesty: HonestyBlock): HonestyBlock;
-export {};

package/dist/honesty/honesty.js

@@ -1,95 +0,0 @@
-/**
- * The honesty block — one machine-readable field composing everything that qualifies a verdict's
- * trustworthiness: the assertion grade, the attribution tier, the envelope maturity, the verified-surface
- * coverage, and the capture integrity. The invariant: a green may never LOOK stronger than its honesty
- * block. Harnesses gate on it (e.g. "grade ≥ net AND integrity clean"). This is pure composition +
- * assessment — all five components already exist individually; wiring it onto results is a later step.
- */
-import { Verified } from '@reticlehq/core';
-/** Assertion grade, strongest first — the tier the verdict actually proved. */
-export const HonestyGrade = {
-    SIGNAL: 'signal',
-    NET: 'net',
-    STATE: 'state',
-    PRESENCE: 'presence',
-    NONE: 'none',
-};
-const GRADE_RANK = {
-    [HonestyGrade.SIGNAL]: 4,
-    [HonestyGrade.NET]: 3,
-    [HonestyGrade.STATE]: 2,
-    [HonestyGrade.PRESENCE]: 1,
-    [HonestyGrade.NONE]: 0,
-};
-/** Below this envelope sample count a deviation verdict is noise, not judgment. */
-const MIN_ENVELOPE_SAMPLES = 3;
-/** Coverage when the SDK reported no blind spots during the window — it saw everything it can see. */
-const FULL_COVERAGE_PCT = 100;
-export function buildHonestyBlock(inputs) {
-    const issues = [];
-    if (true === inputs.truncated)
-        issues.push('capture truncated');
-    for (const spot of inputs.blindSpots ?? [])
-        issues.push(`blind spot: ${spot}`);
-    // Report only what was measured. `envelope` used to be emitted unconditionally with samples=0, so
-    // every act carried `sufficient: false` — and the tool description tells the agent to gate on this
-    // block, meaning an agent that obeyed rejected 100% of green verdicts on a value that never changed.
-    // A field that always reads "insufficient" is worse than an absent one: it looks like a finding.
-    const samples = inputs.envelopeSamples;
-    const partial = inputs.coveragePartial ?? false;
-    // Nothing blind reported ⇒ the SDK saw everything it is able to see. When coverage IS partial we know
-    // that much but not the fraction, so the percentage is omitted rather than invented.
-    const pct = inputs.coveragePct ?? (partial ? undefined : FULL_COVERAGE_PCT);
-    return {
-        grade: inputs.grade,
-        ...(inputs.attribution === undefined ? {} : { attribution: inputs.attribution }),
-        ...(samples === undefined
-            ? {}
-            : { envelope: { samples, sufficient: samples >= MIN_ENVELOPE_SAMPLES } }),
-        coverage: {
-            ...(pct === undefined ? {} : { pct }),
-            partial,
-            ...(partial && inputs.coverageNote !== undefined ? { note: inputs.coverageNote } : {}),
-        },
-        ...(inputs.settled === undefined ? {} : { settled: inputs.settled }),
-        integrity: {
-            clean: 0 === issues.length,
-            issues,
-            // Only when something was actually lost. An empty array beside `clean: true` would be a field
-            // that is always present and always says nothing, which is how a signal gets tuned out.
-            ...(0 === issues.length || undefined === inputs.losses || 0 === inputs.losses.length
-                ? {}
-                : { losses: [...new Set(inputs.losses)] }),
-        },
-    };
-}
-/** Whether a verdict's honesty block clears the harness's bar. Reasons list every failed criterion. */
-export function meetsHonestyBar(block, bar = {}) {
-    const reasons = [];
-    if (bar.minGrade !== undefined && GRADE_RANK[block.grade] < GRADE_RANK[bar.minGrade]) {
-        reasons.push(`grade ${block.grade} below required ${bar.minGrade}`);
-    }
-    if (true === bar.requireIntegrityClean && !block.integrity.clean) {
-        reasons.push(`integrity not clean: ${block.integrity.issues.join('; ')}`);
-    }
-    return { ok: 0 === reasons.length, reasons };
-}
-/**
- * The coverage sentence, kept only on a verdict that points at it.
- *
- * Exactly one branch of `decideVerified` promises it — the YES branch says "coverage was PARTIAL —
- * see `coverage` for what went unobserved". UNKNOWN keeps it too, because "I could not tell" is a
- * statement about what went unseen and the note is the answer. A NO has already named a concrete
- * counter-example, nothing directs the reader to `coverage`, and `partial` plus the spot kinds still
- * travel — so the prose there is cost with no question behind it.
- *
- * Measured: emitting it on every verdict regressed the benchmark's verification efficiency by 4.1%,
- * one note per observation. Accuracy outranks tokens, but this buys no accuracy — the promise is
- * kept wherever it is made.
- */
-export function honestyForVerdict(verified, honesty) {
-    if (Verified.NO !== verified || honesty.coverage.note === undefined)
-        return honesty;
-    const { note: _dropped, ...coverage } = honesty.coverage;
-    return { ...honesty, coverage };
-}

package/dist/honesty/instrumentation-gaps.d.ts

@@ -1,95 +0,0 @@
-import { type InstrumentationGap } from '@reticlehq/core/artifacts';
-/**
- * The gaps ONE action revealed, derived from facts the act path already holds.
- *
- * Pure, and deliberately fed by primitives rather than by the action result: every fact below is
- * already computed for other reasons — `actedSource` for the red-verdict file:line, `stateUnwatched`
- * because an empty `stateDiffs` would otherwise read as "the app changed nothing", the signal count
- * and route movement for the causal summary. Nothing here costs a new observation. The gap surface
- * is a second reading of evidence Reticle was already collecting and then discarding.
- *
- * ## Each kind carries its OWN gate
- *
- * The rule is that a gap fires only when the verdict came back weaker because of it — and "weaker"
- * is different per kind, so a single global flag would be a lie in both directions:
- *
- *  - a missing source mapping costs nothing on a PASS. The act path already says so in as many
- *    words: on green nobody needs the file:line and it is noise. It costs a great deal on a red,
- *    where it is the first thing the agent wants;
- *  - a missing store costs nothing unless the caller ASKED about state;
- *  - a silent mutation costs nothing if the app proved the outcome some other way.
- *
- * Encoding the gates per kind is what keeps this from degenerating into a linter that fires on every
- * uninstrumented control on the page. That surface would be ignored within a day, and it would take
- * the true positives with it.
- */
-export interface ActionInstrumentationFacts {
-    /** Did the verdict pass? Several gates turn on this, in different directions. */
-    pass: boolean;
-    /** True when the outcome was positively PROVED rather than inferred. */
-    proved?: boolean;
-    /**
-     * The `file:line` of the element this verdict is about, when the build plugin stamped one.
-     *
-     * Was a boolean, on the reasoning that the gap only needed to know WHETHER the agent could be
-     * pointed at code. That was true while the only gap reading it was the one that fires when the
-     * pointer is missing. It stopped being true the moment a gap wanted to CARRY the pointer: a gap is
-     * read back later, out of the ledger, by which time its `ref` is very likely dead, and a boolean
-     * cannot be turned back into a location. Both callers already hold this as a formatted string.
-     */
-    source?: string | undefined;
-    /** The ref that was driven, for the report. */
-    ref?: string | undefined;
-    /** Did the caller's predicate ask about registered state? */
-    stateAsked: boolean;
-    /** True when the session has no store registered to read. */
-    stateUnwatched: boolean;
-    /**
-     * Did the app declare any capabilities at all?
-     *
-     * Undefined means NOT KNOWN, and not-known must never become an accusation — callers that predate
-     * this field keep their behaviour rather than start reporting a gap they cannot substantiate.
-     */
-    hasCapabilities?: boolean | undefined;
-    /** Did the DOM move in this action's window? */
-    domMutated: boolean;
-    /** How many app signals fired in the window. */
-    signalsFired: number;
-    /** Did the route change in this action's window? */
-    routeChanged: boolean;
-    /** Did anything signal that route change? */
-    routeSignalFired: boolean;
-    /**
-     * Did a code change land since the last verdict with nothing declaring what it was for?
-     *
-     * Arrives already decided, because the decision needs the intent ledger and this stays pure. Its
-     * gate — and the reasoning that keeps it from becoming a nag — lives in `isChangeUndeclared`, and
-     * that is the only place allowed to answer it.
-     */
-    changeUndeclared?: boolean;
-    /**
-     * How many intents the ledger still holds undischarged. Undefined when nothing consulted it.
-     *
-     * A count rather than a boolean because the message names the number: "one thing still unproved"
-     * and "four things still unproved" are different situations for an agent deciding whether it is
-     * finished, and a bare flag makes them read the same.
-     */
-    openIntentCount?: number;
-    /**
-     * The page announced that this build has the `data-reticle-source` stamp switched OFF.
-     *
-     * Only `true` means anything: absent is "nobody said", which is every SDK predating the field and
-     * every hand-wired connect. See the HELLO field of the same name.
-     */
-    sourceMappingDisabled?: boolean;
-    /**
-     * How long the OLDEST open intent has been owed, in ms.
-     *
-     * A count alone cannot tell "you declared this a minute ago and have not proved it yet" from
-     * "this project has owed eighteen things since last week". Only the first is actionable on the
-     * result being read, and a number that is always large is a number people learn to skip — which
-     * is exactly how an honest gap gets filtered out along with the noise.
-     */
-    oldestOpenIntentAgeMs?: number;
-}
-export declare function gapsForAction(facts: ActionInstrumentationFacts): InstrumentationGap[];