agentfootprint 6.44.0 → 6.45.0

package/dist/esm/lib/context-bisect/types.d.ts

@@ -0,0 +1,448 @@
+/**
+ * context-bisect types — RFC-003 Part B: the contextual-bug localizer
+ * ("git bisect for context").
+ *
+ * Pattern: assembly contract. Part B is pure ASSEMBLY over shipped pieces:
+ *          footprintjs 9.8.0's complete causal DAG (control edges, honesty
+ *          markers, `EdgeWeigher` hook) × influence-core scoring (D6) ×
+ *          consumer-run counterfactual ablation. No new engine features,
+ *          no new typed events.
+ * Role:    `src/lib/context-bisect/` leaf. Exported via
+ *          `agentfootprint/observe`.
+ *
+ * ## The two-tier honest-claims discipline (RFC-003 §B2)
+ *
+ * Every number in these types belongs to exactly ONE of two tiers, and the
+ * docs say which:
+ *
+ *   - **CORRELATIONAL** — edge weights, suspect scores, rankings. These are
+ *     deterministic embedding-geometry PROXIES (influence-core composite:
+ *     semantic alignment between what a source wrote and what the LLM step
+ *     produced). They mean "high semantic alignment", never "the model
+ *     answered BECAUSE of this". A report without reruns stops here and is
+ *     marked `mode: 'correlational'`.
+ *
+ *   - **CAUSAL** — ablation verdicts ONLY. A suspect earns `verdict:
+ *     'confirmed'` exclusively by counterfactual evidence: the consumer's
+ *     `AblationRunner` re-ran the scenario WITHOUT the suspect N seeded
+ *     times and the outcome flipped (with baseline stability checked and
+ *     variance reported — never a single-run verdict).
+ *
+ * Slice completeness is bounded by tracking — and SAYS so: untracked reads
+ * (`$getArgs()` / env / silent reads), missing control-dependence lookups,
+ * missing read tracking, and depth/node truncation all surface as
+ * `honestyFlags` on the report, mirrored from footprintjs's own A2/A4
+ * markers.
+ */
+import type { CommitBundle, RuntimeSnapshot, StageSnapshot } from 'footprintjs/advanced';
+import type { ControlDepLookup } from 'footprintjs/trace';
+import type { Embedder, InfluenceWeights } from '../influence-core/index.js';
+/**
+ * Minimal structural envelope for captured typed events — satisfied by
+ * `AgentfootprintEvent` (collect with `agent.on('*', e => events.push(e))`).
+ * Structural so a consumer can hand in any array shaped like this.
+ */
+export interface CapturedEventLike {
+    readonly type: string;
+    readonly payload: unknown;
+    readonly meta: {
+        readonly runtimeStageId: string;
+    };
+}
+/**
+ * Minimal per-step quality lookup for trigger derivation — satisfied by
+ * footprintjs's `QualityRecorder` (structural, decoupled).
+ */
+export interface QualityTriggerLookup {
+    getLowest(): {
+        runtimeStageId: string;
+        entry: {
+            score: number;
+            stageName: string;
+        };
+    } | undefined;
+}
+/**
+ * The frozen evidence of one completed run — a structural SUPERSET of the
+ * trace-toolpack's `TraceToolpackArtifacts`, so the same bag literal can
+ * serve `traceToolpack(...)` and `localizeContextBug(...)`: every
+ * runtimeStageId in the report drills straight into the toolpack tools.
+ *
+ * - `snapshot` — `executor.getSnapshot()` / `agent.getLastSnapshot()`.
+ * - `controlDeps` — OPTIONAL `controlDepRecorder().asLookup()` from the
+ *   run. With it, the slice includes `[control: <rule label>]` edges to
+ *   the deciders that routed execution. Without it, the report carries the
+ *   `no-control-deps` honesty flag.
+ * - `quality` — OPTIONAL `QualityRecorder` from the run; its
+ *   lowest-scoring step is the default trigger when `atStep` is absent.
+ * - `events` — OPTIONAL captured typed events; used to extract LLM-call
+ *   step ids (`stream.llm_start`) when `llmCallIds` is not given.
+ * - `llmCallIds` — explicit override: the runtimeStageIds of LLM-call
+ *   executions (the steps whose parent edges D7 weighs).
+ */
+export interface ContextBugArtifacts {
+    readonly snapshot: RuntimeSnapshot;
+    readonly controlDeps?: ControlDepLookup;
+    readonly quality?: QualityTriggerLookup;
+    readonly events?: readonly CapturedEventLike[];
+    readonly llmCallIds?: readonly string[];
+}
+/**
+ * What kind of context source a suspect is — picks which ablation adapter
+ * applies. `'stage'` is the honest fallback for slice nodes the classifier
+ * cannot map to an ablatable source (pipeline plumbing, plain stages).
+ */
+export type SuspectKind = 'tool' | 'injection' | 'memory' | 'arg' | 'stage';
+/** Kind-specific identity + the text the semantic refinement embedded. */
+export interface SuspectDetail {
+    /** Tool name (kind 'tool'). */
+    readonly toolName?: string;
+    /** Injection id (kind 'injection' / 'memory') — `Injection.id`. */
+    readonly injectionId?: string;
+    /** Injection flavor (fact / skill / rag / memory / …), when known. */
+    readonly flavor?: string;
+    /**
+     * The suspect's own content text (tool result / injection rawContent),
+     * already redaction-scrubbed by footprintjs at commit time. This is
+     * what the embedder saw for `semanticScore`.
+     */
+    readonly text?: string;
+}
+/**
+ * One hop of a suspect's evidence path — the argmax-weight chain from the
+ * trigger step back to the suspect. Control edges carry `kind: 'control'`
+ * and (when decide() supplied one) the rule label in `key`.
+ */
+export interface EdgePathStep {
+    /** Child (downstream) step. The first hop's `from` is the trigger. */
+    readonly from: string;
+    readonly fromName: string;
+    /** Parent (upstream) step. The last hop's `to` is the suspect. */
+    readonly to: string;
+    readonly toName: string;
+    readonly kind: 'data' | 'control';
+    /** State key (data) or decide() rule label (control), when present. */
+    readonly key?: string;
+    /** Edge weight — 1.0 unless D7 weighed it (child was an LLM call). */
+    readonly weight: number;
+}
+/** Per-run similarity statistics — variance ALWAYS reported (D9). */
+export interface SimilarityStats {
+    readonly mean: number;
+    readonly min: number;
+    readonly max: number;
+    /** Population standard deviation across the N seeded reruns. */
+    readonly stdev: number;
+}
+/** Min/median/max of a cost metric across a probe's seeded reruns. */
+export interface CostRange {
+    readonly median: number;
+    readonly min: number;
+    readonly max: number;
+}
+/**
+ * Per-probe COST (loops/tokens) across its seeded reruns — the second readout
+ * (proposal 004). Present on `AblationRunStats` ONLY when the runner reported
+ * `RunCost`. Absent otherwise (quality-only, byte-identical to before).
+ */
+export interface CostStats {
+    readonly samples: number;
+    readonly loops?: CostRange;
+    readonly tokens?: CostRange;
+}
+/** Evidence from N seeded ablation reruns of one probe. */
+export interface AblationRunStats {
+    /** Seeded reruns performed (the consumer's runner was called N times). */
+    readonly samples: number;
+    /** Runs where `outcomeChanged(original, ablated)` was true. */
+    readonly flips: number;
+    /** Embedding similarity of each ablated output to the original. */
+    readonly similarity: SimilarityStats;
+    /** COST readout across the same reruns — present only when the runner
+     *  reported `RunCost` (proposal 004). */
+    readonly cost?: CostStats;
+}
+export type AblationVerdictKind = 'confirmed' | 'not-confirmed' | 'inconclusive';
+/**
+ * The ONLY causal claim in the report (§B2). `'confirmed'` = ablating the
+ * suspect flipped the outcome in a MAJORITY of N seeded reruns while the
+ * un-ablated baseline stayed stable. `'inconclusive'` = mixed flips, or an
+ * unstable baseline (the scenario itself doesn't reproduce — no ablation
+ * verdict is trustworthy then). `'not-confirmed'` = no flip observed; the
+ * suspect's score remains a correlational proxy only.
+ */
+export interface AblationVerdict {
+    readonly verdict: AblationVerdictKind;
+    /** Human-readable claim, phrased at the right tier (causal vs proxy). */
+    readonly claim: string;
+}
+/**
+ * A missing-context candidate (interface #3): a unit that was available for the
+ * turn but never reached the model. The mirror of a `Suspect`'s ablation
+ * verdict — `confirmed` here means RESTORING the unit flipped the outcome in a
+ * majority of seeded reruns on a stable baseline. Without a restoration runner
+ * it carries only `id`/`content` (a candidate, not a causal claim).
+ */
+export interface RestoredCandidate {
+    readonly id: string;
+    readonly content?: string;
+    /** Seeded restoration-probe stats (causal tier only). */
+    readonly runs?: AblationRunStats;
+    /** Restoration verdict (causal tier only). */
+    readonly verdict?: AblationVerdict;
+}
+/** One ranked suspect. */
+export interface Suspect {
+    /**
+     * runtimeStageId of the slice node this suspect lives at — drillable
+     * with the trace-toolpack tools (`trace_node(source)` etc.).
+     */
+    readonly source: string;
+    readonly stageName: string;
+    readonly kind: SuspectKind;
+    readonly detail?: SuspectDetail;
+    /**
+     * The ranking key — CORRELATIONAL proxy (§B2):
+     * `structuralScore × semanticScore` when a semantic refinement exists,
+     * else `structuralScore`. Means "semantically aligned and causally
+     * UPSTREAM", never "caused".
+     *
+     * Comparison caveat: a suspect WITHOUT content text (kind 'stage'/'arg',
+     * or a path through control edges only) keeps its bare structural score
+     * — an UPPER BOUND with no content evidence behind it. Plumbing can
+     * legitimately rank above ablatable sources; the ablation verdicts (and
+     * `semanticScore`'s presence) are what disambiguate.
+     */
+    readonly score: number;
+    /**
+     * Max-product of edge weights along the best path from the trigger to
+     * this node (1.0 when no D7-weighted LLM edge is on the path).
+     */
+    readonly structuralScore: number;
+    /**
+     * Influence-core composite of the suspect's own content vs the trigger
+     * step's output (clamped to [0, 1]); only for suspects with a known
+     * content text. The same proxy disclaimers as D6 apply.
+     */
+    readonly semanticScore?: number;
+    /**
+     * TRUE when `score` includes a content signal (semanticScore present).
+     * FALSE = path-only structural score — an UPPER BOUND that can reach 1.0
+     * through control-edge paths alone; rank such suspects with care and
+     * prefer ablation verdicts to disambiguate. (Machine-readable twin of
+     * the "path only — no content signal" report marking.)
+     */
+    readonly hasContentEvidence: boolean;
+    /** Evidence path, trigger → … → suspect, control edges labeled. */
+    readonly edgePath: readonly EdgePathStep[];
+    /** The counterfactual to run — absent for kind 'stage'. */
+    readonly ablation?: AblationSpec;
+    /** CAUSAL tier — present only when an `AblationRunner` was supplied. */
+    readonly verdict?: AblationVerdict;
+    /** The rerun evidence behind `verdict`. */
+    readonly runs?: AblationRunStats;
+    /** The COST readout (proposal 004) — present only when the runner reported
+     *  `RunCost`. A WEAKER tier than `verdict`: it shows removal reduced cost
+     *  beyond a placebo band, NOT that the work was "wasted". */
+    readonly cost?: CostVerdict;
+}
+/**
+ * The COST verdict for a suspect — a context bug's second cost (proposal 004).
+ * A WEAKER, gated tier than the flip `verdict`: it shows removing the suspect
+ * REDUCED cost (loops/tokens) beyond a length-matched placebo band with a stable
+ * sign — **necessity for the cost, NOT proof the work was "wasted".**
+ */
+export interface CostVerdict {
+    /** Removing the suspect reduced cost beyond the placebo band, stably. */
+    readonly reducedCostOnRemoval: boolean;
+    /** Loops saved by removal (baseline median − suspect median). */
+    readonly loopsSaved: number;
+    /** Tokens saved by removal. */
+    readonly tokensSaved: number;
+    /** Sign stable across seeds AND a placebo band existed to clear. When false,
+     *  `reducedCostOnRemoval` is not trustworthy (treat as no cost evidence). */
+    readonly stable: boolean;
+}
+/**
+ * The 2×2 class a suspect falls in, derived by `classifySuspect` from its flip
+ * `verdict` (quality) and its `cost` verdict. The no-bug cell is
+ * `'no-detected-effect'` — never "innocent": a piece can matter in ways neither
+ * axis sees (overdetermination, same-loops-different-path).
+ */
+export type SuspectClass = 'content-bug' | 'cost-cause' | 'both' | 'no-detected-effect';
+/**
+ * What to remove for one counterfactual rerun. The library BUILDS specs
+ * (one per suspect kind) and provides `applyAblations` to apply them to
+ * the inputs an agent is constructed from; the consumer's `AblationRunner`
+ * re-runs the scenario with the spec applied.
+ *
+ * THE TOOL SEAM (documented because `AgentOptions` has no `ignoredTools`):
+ * agentfootprint has no runtime tool kill-switch — tools enter an agent at
+ * construction (`.tools([...])` / injection `inject.tools`). Tool ablation
+ * therefore happens where tools are DECLARED: the runner rebuilds the
+ * agent with `applyAblations(specs, { tools }).tools`. The same pattern
+ * covers injections (rebuild without the excluded `Injection.id`s) and
+ * memory (filter `MemoryEntry`s by id before attaching).
+ */
+export type AblationSpec = 
+/** Drop these tools from the catalog the agent is built with. */
+{
+    readonly kind: 'tool';
+    readonly ignoredTools: readonly string[];
+}
+/** Drop these injections (facts / skills / instructions / steering / rag). */
+ | {
+    readonly kind: 'injection';
+    readonly excludeInjectionIds: readonly string[];
+}
+/** Drop these memory entries (matched by `MemoryEntry.id`). */
+ | {
+    readonly kind: 'memory';
+    readonly excludeMemoryIds: readonly string[];
+}
+/**
+ * The suspect is run INPUT (`$getArgs()` / seed args) — there is nothing
+ * the library can filter. The consumer's runner must override the arg
+ * itself (e.g. re-run with a neutralized field). `source` names the step
+ * that consumed the untracked input.
+ */
+ | {
+    readonly kind: 'arg';
+    readonly source: string;
+    readonly note: string;
+};
+/**
+ * Consumer-supplied counterfactual runner: re-run the SAME scenario with
+ * every spec in `specs` applied, and return the run's output text.
+ *
+ * Contract:
+ * - `specs` may be empty — that is the BASELINE probe (re-run unchanged);
+ *   its outputs measure the scenario's natural variance.
+ * - `run.seed` varies 0..N-1 across the N samples of one probe. Thread it
+ *   into any stochastic knob (sampling temperature seed, mock script
+ *   selection) so reruns are deterministic-but-distinct; ignore it for
+ *   fully deterministic scenarios.
+ * - Build a FRESH agent/provider per call — scripted mock providers are
+ *   stateful (replies consume in order).
+ */
+/**
+ * The COST of one re-run — the second readout the two-score localizer reads
+ * from the SAME ablation (proposal 004). Both optional; cost scoring is opt-in
+ * by a runner that reports them. `loops` = agent loop iterations the run took;
+ * `tokens` = total tokens it consumed.
+ */
+export interface RunCost {
+    readonly loops?: number;
+    readonly tokens?: number;
+}
+/**
+ * Consumer-supplied counterfactual runner (above). Returns the run's output
+ * text — OR, to ALSO unlock the cost score (proposal 004), `{ output, cost }`
+ * from the SAME re-run (one ablation, two readouts). Backward-compatible:
+ * `runAblationProbe` normalizes both shapes, so a bare-string runner keeps
+ * quality-only behavior unchanged.
+ */
+export type AblationRunner = (specs: readonly AblationSpec[], run: {
+    readonly seed: number;
+}) => Promise<string | {
+    readonly output: string;
+    readonly cost?: RunCost;
+}>;
+/**
+ * Did the ablated output mean something DIFFERENT from the original?
+ * Default: embedding similarity below `flipThreshold`. Override with a
+ * domain comparator (e.g. compare extracted decisions) — recommended with
+ * `mockEmbedder`, whose cosine compresses prose into ~0.85–0.97 (the C1
+ * calibration note: absolute thresholds only with real embedders).
+ */
+export type OutcomeComparator = (original: string, ablated: string) => boolean | Promise<boolean>;
+/** The rerun configuration that upgrades the report to the causal tier. */
+export interface AblationRerun {
+    readonly runner: AblationRunner;
+    /** The original (buggy) output the reruns are compared against. */
+    readonly originalOutput: string;
+    /** Seeded reruns per probe. Default 3. Never below 2 (no single-run verdicts — D9). */
+    readonly samples?: number;
+    /** Outcome-flip comparator. Default: similarity < `flipThreshold`. */
+    readonly outcomeChanged?: OutcomeComparator;
+    /** Similarity floor for the DEFAULT comparator. Default 0.8. */
+    readonly flipThreshold?: number;
+    /** Ablate only the top-K ranked suspects that carry a spec. Default 5. */
+    readonly maxSuspects?: number;
+}
+/** Slice-shape numbers — how much evidence the ranking stands on. */
+export interface SliceStats {
+    readonly nodes: number;
+    readonly dataEdges: number;
+    readonly controlEdges: number;
+    /** Edges that received a D7 (LLM-influence) weight. */
+    readonly weightedEdges: number;
+    /** Nodes that ALSO consumed untracked sources (args/env/silent reads). */
+    readonly incompleteNodes: number;
+    readonly maxDepth: number;
+    readonly maxNodes: number;
+    /** Present when a limit actually cut the slice (footprintjs A4). */
+    readonly truncated?: {
+        readonly byDepth: boolean;
+        readonly byNodes: boolean;
+    };
+}
+export type HonestyFlagKind = 'slice-truncated' | 'untracked-sources' | 'no-control-deps' | 'no-read-tracking' | 'no-llm-call-ids' | 'baseline-unstable';
+export interface HonestyFlag {
+    readonly flag: HonestyFlagKind;
+    readonly note: string;
+}
+/** The localizer's full output (D8). */
+export interface ContextBugReport {
+    /** The trigger step the slice was rooted at. */
+    readonly step: string;
+    readonly stepName: string;
+    /** Where the trigger came from. */
+    readonly triggerSource: 'explicit' | 'quality' | 'custom';
+    /** The quality score that selected the trigger (quality source only). */
+    readonly triggerScore?: number;
+    /**
+     * `'correlational'` — no `AblationRunner` supplied: the report STOPS at
+     * the ranking; every score is a proxy and no causal claim is made.
+     * `'causal'` — suspects additionally carry ablation verdicts (§B2: the
+     * verdicts are the only causal claims; the scores stay proxies).
+     */
+    readonly mode: 'correlational' | 'causal';
+    /** Ranked suspects, best (most aligned + upstream) first. */
+    readonly suspects: readonly Suspect[];
+    /**
+     * Missing-context candidates (interface #3): units that were available for
+     * the turn but never reached the model. Each carries a RESTORATION verdict
+     * when a restoration runner was supplied (causal tier — restoring it flipped
+     * the outcome). Absent when no `missingContext` option was passed.
+     */
+    readonly dropped?: readonly RestoredCandidate[];
+    readonly sliceStats: SliceStats;
+    /** ⚠ everything that bounds what this report can honestly claim. */
+    readonly honestyFlags: readonly HonestyFlag[];
+    /** Ablation baseline probe stats (causal mode only). */
+    readonly baseline?: AblationRunStats;
+    /** Restoration baseline probe stats — the missing-context tier's twin of
+     *  `baseline` (present only when a restoration runner ran). An unstable one
+     *  also raises a `baseline-unstable` honesty flag. */
+    readonly restorationBaseline?: AblationRunStats;
+}
+export declare const CONTEXT_BISECT_DEFAULTS: {
+    /** Slice depth budget (forwarded to `causalChain`). */
+    readonly maxDepth: 12;
+    /** Slice node budget (forwarded to `causalChain`). */
+    readonly maxNodes: 80;
+    /** Ranked suspects kept on the report. */
+    readonly maxSuspects: 12;
+    /** Chars of written content embedded per step text (D7). */
+    readonly maxTextChars: 2000;
+    /** Seeded reruns per ablation probe (D9 — never single-run verdicts). */
+    readonly samples: 3;
+    /** Default similarity floor for the default outcome comparator. */
+    readonly flipThreshold: 0.8;
+    /** Ablation probes budget for `bisectCulprits`. */
+    readonly maxProbes: 24;
+    /** Independent-culprit search rounds for `bisectCulprits`. */
+    readonly maxCulprits: 4;
+};
+export type { CommitBundle, ControlDepLookup, Embedder, InfluenceWeights, RuntimeSnapshot, StageSnapshot, };

package/dist/esm/lib/context-bisect/walk-to-root.d.ts

@@ -0,0 +1,103 @@
+/**
+ * walk-to-root — L4: the influence-guided backtracking debugger (proposal 007).
+ *
+ * `walkToRoot` walks BACKWARD from the symptom across loops to find the ROOT context source of a
+ * DECISION bug (root ≠ proximate). Per hop: NARROW with per-loop influence (L3) → HOP along
+ * `writerId` provenance to the loop that produced the culprit → ISOLATE with run-wide ablation (L2).
+ * Pure orchestration over shipped tiers — no new scorer, no new ablation.
+ *
+ * Home: `context-bisect` (consumes Trajectory + shortlist + the localizer's ablation).
+ *
+ * HONESTY (the proxy CAN misdirect the hop — folded in from review):
+ * - The per-hop narrow is a correlational PROXY (FA-dominated) — it points at a neighborhood and
+ *   CANNOT separate a planted instruction from an innocent same-topic sibling. Three guards: (1) BEAM
+ *   not top-1 (keep siblings in play); (2) ablation is the ONLY discriminator (a wrong-branch hop that
+ *   doesn't flip is never `root`); (3) the narrow reorders, never drops. Remaining caveat: if the narrow
+ *   never surfaces the true root into the beam, ablation never tests it and the walk stops shallow — a
+ *   recall blind spot, amplified in a single chain.
+ * - `root` is CAUSAL (ablation-only): set only when run-wide ablation flips on a stable baseline.
+ *   Without a `rerun`, the walk is correlational and `root` is absent.
+ * - FLAT charts only for the cross-loop hop — grouped loop frames are scope-isolated (degraded + flagged).
+ * - Three first-class honest stops (never silent): `unseparated-siblings`, `overdetermined-or-incomplete`,
+ *   `untracked-origin`.
+ *
+ * VALIDATION (the descent edge is now populated on real agents — proposal 008): `assembleTrajectory`
+ * surfaces each loop's proximate `lastToolResult` on the WALK-ONLY `LoopFrame.proximateToolSource`
+ * field (writer = the PRODUCING loop's tool-calls stage — a cross-loop edge). `writtenByOf` reads it,
+ * so on a real flat agent with tool calls the cross-loop DESCENT fires (proven at the component level:
+ * the enrichment populates the edge on a real trajectory + the algorithm descends on it). It is
+ * WALK-ONLY — not in `contextSources` — so L3's narrow + its measured recall are untouched.
+ * END-TO-END VALIDATED (ctxbug/harness/eval-l4-walk.mjs): on a REAL agentfootprint misdirect agent
+ * with a realistic embedder (bge) for the narrow and a REAL causal ablation (rebuild the agent WITHOUT
+ * the planted fact → the outcome flips), the walk BURIES the plant at the symptom, DESCENDS via the
+ * proximate tool edge to the wrong-decision loop, and ablation convicts `root = the planted
+ * instruction` — where flat single-trigger localize does not. FLAT only — grouped's run-level
+ * `lastToolResult` lives outside the per-scope inner logs (deferred, degrade-flagged below).
+ */
+import type { Embedder } from '../influence-core/index.js';
+import { type SuspectClassifier } from './localize.js';
+import type { Trajectory } from './trajectory.js';
+import type { AblationRerun, AblationVerdict, ContextBugArtifacts, HonestyFlag, SuspectKind } from './types.js';
+/** One honest stop reason when the walk cannot cleanly descend/convict. */
+export type RootCauseNote = 'unseparated-siblings' | 'overdetermined-or-incomplete' | 'untracked-origin';
+/** One hop of the symptom→root walk. */
+export interface RootCauseHop {
+    /** The loop this hop examined. */
+    readonly loopIndex: number;
+    /** The narrowed culprit at this hop (joins a localizer Suspect 1:1). */
+    readonly suspectId: string;
+    readonly kind: SuspectKind;
+    /** The narrow is text-similarity — a PROXY, never causal. */
+    readonly narrowedBy: 'text-similarity';
+    /** The causal convict — present only when a `rerun` ablated this hop's suspect. */
+    readonly verdict?: AblationVerdict;
+    /** The provenance writer this hop's culprit came from (runtimeStageId). */
+    readonly writtenBy?: string;
+    /** The loopIndex the walk descended to next (the writer's frame); absent if it stopped here. */
+    readonly cameFrom?: number;
+    /** A first-class honest stop, when applicable. */
+    readonly note?: RootCauseNote;
+}
+export interface RootCausePath {
+    /** Symptom → … in walk order. */
+    readonly hops: readonly RootCauseHop[];
+    /** The DEEPEST ablation-convicted hop (CAUSAL). Absent without a flip / without a rerun. */
+    readonly root?: RootCauseHop;
+    readonly honestyFlags: readonly HonestyFlag[];
+    readonly truncated?: {
+        readonly byHops: boolean;
+        readonly byAblations: boolean;
+    };
+}
+export interface WalkToRootOptions {
+    readonly embedder: Embedder;
+    /** The convict tier. Without it the walk is correlational and `root` is absent. */
+    readonly rerun?: AblationRerun;
+    /** Top-k writers ablated per hop (NOT top-1 — the proxy can't separate same-topic siblings). Default 2. */
+    readonly beamK?: number;
+    /** Forwarded to the per-loop narrow. */
+    readonly recencyDecay?: number;
+    readonly k?: number;
+    /** Walk-depth budget. Default 8. */
+    readonly maxHops?: number;
+    /** Total ablation-probe budget across the whole walk. Default 24. */
+    readonly maxAblations?: number;
+    readonly classifier?: SuspectClassifier;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Resolve every `writerId` to the index of the frame whose `bodyIds` contains it (NOT via
+ * `parseRuntimeStageId` — that yields executionIndex, not loopIndex). A writer not in any frame
+ * (run prelude / root-seeded) maps to `undefined`. Invariant: each id lands in exactly one frame.
+ */
+export declare function buildWriterFrameIndex(trajectory: Trajectory): Map<string, number>;
+/**
+ * Walk backward from the symptom to the root context source — from a recorded run.
+ * Thin wrapper: `assembleTrajectory` then {@link walkTrajectory}. See module docs for the honesty model.
+ */
+export declare function walkToRoot(artifacts: ContextBugArtifacts, opts: WalkToRootOptions): Promise<RootCausePath>;
+/**
+ * The walk itself, over an already-assembled {@link Trajectory} (composable + directly testable).
+ * FLAT charts only for the cross-loop hop; grouped charts degrade (within-loop) with a flag.
+ */
+export declare function walkTrajectory(trajectory: Trajectory, opts: WalkToRootOptions): Promise<RootCausePath>;

package/dist/esm/lib/influence-core/attributability.d.ts

@@ -0,0 +1,72 @@
+/**
+ * rankingConfidence — honesty marker for an influence ranking (RFC-003 honesty
+ * marker; influence-core block D6). Internal concept: "attributability".
+ *
+ * Pattern: pure, embedder-free function over a `scoreInfluence` result.
+ *          Deterministic; no I/O.
+ * Role:    `src/lib/influence-core/` leaf. The honesty companion to the
+ *          four-signal scorer: it says when the ranking is a SHORTLIST,
+ *          not a verdict.
+ *
+ * ## Why this exists (the measured blind spot)
+ *
+ * Output-similarity influence ranks sources by how much they resemble the
+ * final answer. That is structurally blind to ABSENCE / CROWDING bugs: a
+ * culprit that caused the error by *displacing* context (history truncation,
+ * context dilution) need not resemble the answer — so it ranks low, or below
+ * an innocent that the answer happens to talk about. The tell is not a low
+ * absolute score; it is a FLAT top — no source clearly dominates. This
+ * function reports that flatness honestly so consumers escalate to ablation
+ * (the causal tier) instead of trusting a confident-but-wrong rank-1.
+ *
+ * Honest claim (RFC-002 §2 discipline): `clearWinner` is a proxy for "the
+ * ranking has a clear lead", never "the lead is the cause". A clear lead can
+ * still be an innocent the answer rationalizes over — only ablation makes
+ * causal claims.
+ */
+import type { ConfidenceStrategy, InfluenceScore, RankingConfidence } from './types.js';
+/**
+ * Default strategy: ABSOLUTE top-2 gap `s0 − s1 >= threshold`. Simple and
+ * interpretable, but embedder-relative (the gap scale depends on the embedding
+ * geometry). Use `ratioStrategy` for cross-embedder transfer.
+ */
+export declare function marginStrategy(threshold?: number): ConfidenceStrategy;
+/**
+ * Scale-invariant strategy: top-2 gap as a FRACTION of the top score,
+ * `(s0 − s1) / |s0| >= threshold`. Transfers across embedders / answer lengths
+ * where the absolute margin does not. A zero (or all-equal) top is never a
+ * clear winner.
+ */
+export declare function ratioStrategy(threshold?: number): ConfidenceStrategy;
+export interface RankingConfidenceOptions {
+    /**
+     * The decisiveness rule. Default: `marginStrategy(clearWinnerMargin)`.
+     * When set, it WINS — `clearWinnerMargin` is ignored. Bring your own
+     * (e.g. entropy / dispersion) or use the shipped `ratioStrategy`.
+     */
+    readonly strategy?: ConfidenceStrategy;
+    /** Threshold for the DEFAULT margin strategy (ignored when `strategy` is
+     *  set). Default: `DEFAULT_CLEAR_WINNER_MARGIN` (0.05). */
+    readonly clearWinnerMargin?: number;
+    /** Score band below the top defining the shortlist to double-check.
+     *  Default: `DEFAULT_SHORTLIST_BAND` (0.1). Recommended >=
+     *  `clearWinnerMargin` so the shortlist is at least as wide as the
+     *  winning gap (the function also guarantees the runner-up is shortlisted
+     *  when there is no clear winner, so a smaller value is safe). */
+    readonly shortlistBand?: number;
+}
+/**
+ * Assess whether an influence ranking has a clear winner to trust as a lead,
+ * or is too close to call and should be confirmed by ablation.
+ *
+ * Guarantees (relied on by the localizer): the returned `shortlist` always
+ * contains `lead` when there is one, and — when there is NO clear winner and
+ * there are ≥2 suspects — always contains the runner-up too (so ablation over
+ * the shortlist covers the real culprit even if it ranked below an innocent).
+ *
+ * @param scores `scoreInfluence` output (any order — re-sorted defensively).
+ *               Ids are assumed unique (as `scoreInfluence` enforces); the
+ *               shortlist is de-duplicated defensively regardless.
+ * @throws Error on negative or NaN options.
+ */
+export declare function rankingConfidence(scores: readonly InfluenceScore[], options?: RankingConfidenceOptions): RankingConfidence;