agentfootprint 6.44.0 → 6.45.0

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

@@ -0,0 +1,94 @@
+/**
+ * EmbeddingCache — content-hash embedding cache (RFC-002 §3).
+ *
+ * Pattern: transparent Decorator — implements `Embedder` itself, so
+ *          every influence-core function (and any other embedder
+ *          consumer) takes a plain `Embedder` and the cache is pure
+ *          injection: wrap once, thread the SAME instance through
+ *          lint + margins + edge weights, and a description embedded
+ *          for the catalog lint is free for the margin scorer.
+ * Role:    `src/lib/influence-core/` leaf. No agent/runtime imports.
+ *
+ * ## Bounded honesty (the library convention)
+ *
+ * The cache is BOUNDED — `maxEntries` caps memory (LRU eviction), and
+ * the eviction count is VISIBLE via `stats()`. A consumer seeing
+ * `evictions > 0` knows the cache is thrashing and can size it up;
+ * nothing silently degrades out of view.
+ *
+ * ## Keying
+ *
+ * Entries are keyed by `contentHash(text)` — a fast non-cryptographic
+ * 64-bit FNV-1a (length-qualified). NOT a security boundary: it
+ * deduplicates embedding calls, it does not authenticate content.
+ * Collisions are astronomically unlikely at cache scale (≤ maxEntries
+ * live keys) but would silently return the colliding text's vector —
+ * acceptable for a similarity proxy, never rely on it for exact-match
+ * semantics. One cache per embedder instance: keys do NOT encode the
+ * model, so sharing one cache across different embedders would mix
+ * vector spaces (the same reason `MemoryStore` rejects mixed
+ * dimensions).
+ *
+ * ## Concurrency
+ *
+ * In-flight requests coalesce: N concurrent `embed()` calls for the
+ * same text issue ONE inner call (single-flight). Rejections are NOT
+ * cached — a failed embedding retries on the next request.
+ */
+import type { Embedder, EmbedArgs, EmbedBatchArgs } from './types.js';
+/**
+ * Fast, deterministic, browser-safe content hash (FNV-1a, two 32-bit
+ * lanes + length qualifier → "len-xxxxxxxxyyyyyyyy"). Non-cryptographic
+ * — cache keying only.
+ */
+export declare function contentHash(text: string): string;
+export interface EmbeddingCacheOptions {
+    /**
+     * Maximum cached vectors. Oldest (least recently used) entries are
+     * evicted past the cap; evictions are counted in `stats()`.
+     * Default 1024 — a 30-tool catalog plus a long run's reasoning
+     * steps fit with a wide margin.
+     */
+    readonly maxEntries?: number;
+}
+/** Visible cache health — the bounded-honesty surface. */
+export interface EmbeddingCacheStats {
+    /** Vectors currently held. */
+    readonly size: number;
+    /** The configured cap. */
+    readonly maxEntries: number;
+    /** Served from cache (includes coalesced in-flight joins). */
+    readonly hits: number;
+    /** Forwarded to the inner embedder. */
+    readonly misses: number;
+    /** Entries dropped to respect `maxEntries`. >0 = consider sizing up. */
+    readonly evictions: number;
+}
+/**
+ * Wrap an embedder with a bounded, content-hash-keyed LRU cache.
+ * See module docs for keying, bounds, and concurrency semantics.
+ */
+export declare class EmbeddingCache implements Embedder {
+    readonly dimensions: number;
+    private readonly inner;
+    private readonly maxEntries;
+    /** LRU store — Map iteration order is recency (refreshed on hit). */
+    private readonly vectors;
+    /** Single-flight joins — promises live here until settled. */
+    private readonly inflight;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(inner: Embedder, options?: EmbeddingCacheOptions);
+    embed(args: EmbedArgs): Promise<number[]>;
+    embedBatch(args: EmbedBatchArgs): Promise<number[][]>;
+    /** Visible cache health (bounded honesty — see module docs). */
+    stats(): EmbeddingCacheStats;
+    /** Drop all cached vectors. Stats counters are preserved. */
+    clear(): void;
+    private refresh;
+    private store;
+    private embedSequential;
+}
+/** Factory sugar — `embeddingCache(embedder)` reads like the built-ins. */
+export declare function embeddingCache(inner: Embedder, options?: EmbeddingCacheOptions): EmbeddingCache;

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

@@ -0,0 +1,26 @@
+import type { Embedder, EvidenceInput, InfluenceScore, InfluenceWeights } from './types.js';
+export interface ScoreContrastiveInfluenceArgs {
+    /** Evidence items (context sources) with their reasoning ancestors. */
+    readonly evidence: readonly EvidenceInput[];
+    /** The ACTUAL (e.g. buggy) output the evidence is scored against. */
+    readonly answerText: string;
+    /** A REFERENCE output to contrast against — a known-good / expected / prior
+     *  run. The shared-with-both similarity (topical innocents) cancels out. */
+    readonly referenceText: string;
+    /** Injected embedder. Wrap in an `EmbeddingCache` to share embeddings. */
+    readonly embedder: Embedder;
+    /** Composite weights. Default: paper priors 0.40/0.30/0.20/0.10. */
+    readonly weights?: InfluenceWeights;
+    /** PERSIST threshold T. Default 0.3. */
+    readonly persistenceThreshold?: number;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Score evidence by CONTRASTIVE influence: `sim(e, answer) − sim(e, reference)`
+ * for the FA term, the four-signal composite otherwise. Returns `InfluenceScore[]`
+ * sorted descending — drop-in compatible with `scoreInfluence` consumers
+ * (`rankingConfidence`, etc.).
+ *
+ * @throws when an evidence id is duplicated (same contract as `scoreInfluence`).
+ */
+export declare function scoreContrastiveInfluence(args: ScoreContrastiveInfluenceArgs): Promise<InfluenceScore[]>;

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

@@ -0,0 +1,34 @@
+/**
+ * influence-core — the ONE embedding-based scoring engine
+ * (RFC-002/003 block D6).
+ *
+ * Extracted from the Visible Reasoning paper's FDL influence pipeline
+ * (Eq. 1–6: four signals + adaptive weighted composite) so that three
+ * consumers share one engine and one embedding cache:
+ *
+ *   a) RFC-002 — tool-catalog lint (C1 ← `pairwiseSimilarity`) and the
+ *      margin recorder (C4/C5 ← `scoreMargin`),
+ *   b) RFC-003 Part B — the LLM-edge weigher (D7 ← `scoreInfluence` /
+ *      the signal scorers),
+ *   c) the FDL paper pipeline itself (stages 4–6 ← `EmbeddingCache` +
+ *      `scoreInfluence`).
+ *
+ * Leaf module: zero agent/runtime imports — the only dependency is the
+ * `Embedder` interface (re-exported from memory/embedding, the one
+ * existing contract) and the shared `cosineSimilarity`.
+ *
+ * Plug-and-play: the frame and formulas are the library's; the
+ * embedder, weights, and thresholds are consumer-injected.
+ *
+ * Honest claim (RFC-002 §2): every score here is a deterministic
+ * embedding-geometry PROXY — semantic alignment, never model internals
+ * and never causal attribution.
+ */
+export type { CandidateScore, ConfidenceStrategy, EmbedArgs, EmbedBatchArgs, Embedder, EvidenceInput, InfluenceScore, InfluenceWeights, MarginCandidate, MarginResult, PairwiseSimilarityResult, RankingConfidence, SignalScores, SimilarityItem, SimilarityPair, } from './types.js';
+export { DEFAULT_CLEAR_WINNER_MARGIN, DEFAULT_CLEAR_WINNER_RATIO, DEFAULT_INFLUENCE_WEIGHTS, DEFAULT_MARGIN_THRESHOLD, DEFAULT_PERSISTENCE_THRESHOLD, DEFAULT_SHORTLIST_BAND, } from './types.js';
+export { marginStrategy, rankingConfidence, ratioStrategy, type RankingConfidenceOptions, } from './attributability.js';
+export { scoreContrastiveInfluence, type ScoreContrastiveInfluenceArgs } from './contrastive.js';
+export { contentHash, EmbeddingCache, embeddingCache, type EmbeddingCacheOptions, type EmbeddingCacheStats, } from './cache.js';
+export { adaptWeights, averageRelevancy, compositeScore, finalAnswerSimilarity, persistence, scoreInfluence, structuralProximity, type InfluenceScorer, type ScoreInfluenceArgs, } from './signals.js';
+export { pairwiseSimilarity, type PairwiseSimilarityArgs } from './similarity.js';
+export { scoreMargin, type ScoreMarginArgs } from './margin.js';

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

@@ -0,0 +1,33 @@
+import type { Embedder, MarginCandidate, MarginResult } from './types.js';
+export interface ScoreMarginArgs {
+    /** The offered candidates (e.g. the tool catalog on `llm_start`). */
+    readonly candidates: readonly MarginCandidate[];
+    /** The choice context — the text the chooser ranked against. */
+    readonly contextText: string;
+    /** Names of the chosen candidate(s). Must exist in `candidates`. */
+    readonly chosen: readonly string[];
+    /**
+     * Injected embedder. Wrap in an `EmbeddingCache` so descriptions
+     * embed once across calls (RFC-002 §3 — the same cache the catalog
+     * lint already filled).
+     */
+    readonly embedder: Embedder;
+    /** Margins below this flag `narrow`. Default 0.05 (RFC-002 §4). */
+    readonly marginThreshold?: number;
+    /** Abort signal threaded to the embedder (network backends). */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Rank candidates by cosine similarity to the choice context and
+ * measure how decisively the chosen one(s) won.
+ *
+ * Returns ranked `scores` (descending; ties keep candidate input
+ * order), the `topScored` name, the `margin` (undefined when every
+ * candidate was chosen — no competition to measure; `narrow` is false
+ * in that case), and the two flags.
+ *
+ * Fail-loud validation: empty candidates/chosen, duplicate candidate
+ * names, or a chosen name missing from the candidates throw — those
+ * are wiring bugs in the caller, not runtime conditions.
+ */
+export declare function scoreMargin(args: ScoreMarginArgs): Promise<MarginResult>;

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

@@ -0,0 +1,128 @@
+import type { Embedder, EvidenceInput, InfluenceScore, InfluenceWeights, SignalScores } from './types.js';
+/**
+ * FA — Final Answer Similarity (paper Eq. 1).
+ *
+ * `FA(d) = sim(e_d, e_f)` — cosine between the evidence embedding and
+ * the final-answer embedding. The strongest prior: verbatim or
+ * paraphrased reuse of a tool result scores high. Proxy: semantic
+ * overlap, not provenance.
+ */
+export declare function finalAnswerSimilarity(evidenceVec: readonly number[], finalAnswerVec: readonly number[]): number;
+/**
+ * AVG — Average Relevancy (paper Eq. 2).
+ *
+ * Mean cosine between the evidence and each LLM reasoning ancestor;
+ * 0 when there are no ancestors (structurally zero — see
+ * `adaptWeights`). Proxy: consistent semantic closeness across the
+ * chain, not actual consultation.
+ */
+export declare function averageRelevancy(evidenceVec: readonly number[], ancestorVecs: ReadonlyArray<readonly number[]>): number;
+/**
+ * PERSIST — Persistence (paper Eq. 3).
+ *
+ * Fraction of ancestors whose similarity to the evidence EXCEEDS the
+ * threshold T (strict `>`, default 0.30); 0 when there are no
+ * ancestors. Unlike AVG it measures BREADTH: referenced in 4 of 5
+ * steps (0.8) beats referenced intensely in 1. Proxy: similarity
+ * above a tunable bar, not counted citations.
+ */
+export declare function persistence(evidenceVec: readonly number[], ancestorVecs: ReadonlyArray<readonly number[]>, threshold?: number): number;
+/**
+ * DEPTH — Structural Proximity (paper Eq. 4).
+ *
+ * `DEPTH(d) = 1 / (1 + n)` where n counts LLM reasoning ancestors
+ * ONLY (not pipeline plumbing — callers decide what counts as an
+ * ancestor when building `EvidenceInput.ancestorTexts`). Direct
+ * evidence with no intermediaries gets exactly 1.0. The only
+ * content-blind signal: pure trace structure.
+ */
+export declare function structuralProximity(ancestorCount: number): number;
+/**
+ * Adaptive weight redistribution (paper Eq. 6, §5.3).
+ *
+ * When an item has NO LLM ancestors, AVG and PERSIST are structurally
+ * zero — not because the evidence was uninfluential, but because there
+ * is nothing to measure against. Without adaptation its score is
+ * capped at α+δ (≈0.50 under defaults). Eq. 6 moves the β+γ mass onto
+ * FA and DEPTH preserving their ratio:
+ *
+ *   α′ = α + (β+γ)·α/(α+δ),  δ′ = δ + (β+γ)·δ/(α+δ),  β′ = γ′ = 0
+ *
+ * Defaults → α′=0.80, δ′=0.20 (the 4:1 FA:DEPTH ratio kept).
+ * Per-evidence-item: in a multi-tool pipeline some items adapt while
+ * others keep standard weights; `adapted` says which (surface it — the
+ * paper's UI marks adapted items).
+ *
+ * Degenerate guard: if α+δ = 0 there is no defined ratio to preserve —
+ * weights return unchanged with `adapted: false`, and the composite is
+ * honestly 0 for a no-ancestor item.
+ */
+export declare function adaptWeights(weights: InfluenceWeights, ancestorCount: number): {
+    weights: InfluenceWeights;
+    adapted: boolean;
+};
+/**
+ * Composite score S(d) (paper Eq. 5).
+ *
+ * `S = α·FA + β·AVG + γ·PERSIST + δ·DEPTH` under the given weights —
+ * pass the EFFECTIVE weights from `adaptWeights` for no-ancestor
+ * items. With weights summing to 1, S ∈ [−(α+β), 1] (FA/AVG are
+ * cosines and may go negative; PERSIST/DEPTH are non-negative).
+ */
+export declare function compositeScore(signals: SignalScores, weights: InfluenceWeights): number;
+export interface ScoreInfluenceArgs {
+    /** Evidence items (tool results / context sources) with ancestors. */
+    readonly evidence: readonly EvidenceInput[];
+    /** The final answer text the evidence is scored against. */
+    readonly finalAnswerText: string;
+    /**
+     * Injected embedder. Wrap in an `EmbeddingCache` to share embeddings
+     * with the catalog lint / margin scorer (RFC-002 §3 — one cache
+     * serves all three consumers).
+     */
+    readonly embedder: Embedder;
+    /** Composite weights. Default: paper priors 0.40/0.30/0.20/0.10. */
+    readonly weights?: InfluenceWeights;
+    /** PERSIST threshold T. Default 0.30. */
+    readonly persistenceThreshold?: number;
+    /** Abort signal threaded to the embedder (network backends). */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Score every evidence item on the four FDL signals and rank by
+ * composite, descending (paper pipeline stages 4–6 in one call:
+ * embed → score → rank). Ties keep input order (stable sort).
+ *
+ * Deterministic for a deterministic embedder: same inputs → same
+ * scores. All texts are embedded in ONE deduplicated batch — with an
+ * `EmbeddingCache` injected, repeat calls embed nothing.
+ *
+ * Honest claim: ranked semantic-alignment proxies. NOT causal
+ * attribution — see module docs.
+ */
+export declare function scoreInfluence(args: ScoreInfluenceArgs): Promise<InfluenceScore[]>;
+/**
+ * A pluggable influence scorer — the RANK stage's extension point.
+ *
+ * It takes the same `ScoreInfluenceArgs` the localizer assembles for a
+ * slice (the evidence items, the wrong-output text, an embedder) and
+ * returns one `InfluenceScore` per item, ranked descending. The shipped
+ * default is `scoreInfluence` (the FDL four-signal composite); pass your
+ * own to `localizeContextBug({ scorer })` to change the ranking ORDER —
+ * e.g. `scoreContrastiveInfluence` (wrap it to supply a `referenceText`),
+ * or a non-embedding scorer of your own that ignores `args.embedder`.
+ *
+ * Claim-ladder guarantee: a scorer only reorders suspects (how FAST
+ * ablation finds a culprit), never whether a claim counts as causal —
+ * ablation alone convicts. So any scorer is safe to swap in; the worst a
+ * bad one does is make confirmation slower, never wrong.
+ */
+export type InfluenceScorer = (args: ScoreInfluenceArgs) => Promise<InfluenceScore[]>;
+/** Embed distinct texts via batch API when available, else sequentially. */
+export declare function embedAll(embedder: Embedder, texts: readonly string[], signal?: AbortSignal): Promise<Map<string, readonly number[]>>;
+/**
+ * Validate composite weights: every weight finite & non-negative, and not all
+ * zero. Shared by `scoreInfluence` and `scoreContrastiveInfluence` — `fnName`
+ * attributes the error to the actual caller.
+ */
+export declare function assertValidWeights(weights: InfluenceWeights, fnName?: string): void;

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

@@ -0,0 +1,25 @@
+import type { Embedder, PairwiseSimilarityResult, SimilarityItem } from './types.js';
+export interface PairwiseSimilarityArgs {
+    /** The texts to compare — e.g. `{ id: toolName, text: description }`. */
+    readonly items: readonly SimilarityItem[];
+    /**
+     * Injected embedder. Wrap in an `EmbeddingCache` so catalog
+     * descriptions embed once across lint runs (RFC-002 §3).
+     */
+    readonly embedder: Embedder;
+    /** Abort signal threaded to the embedder (network backends). */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Embed every item once (deduplicated batch) and compute the full
+ * cosine matrix plus ranked upper-triangle pairs (descending; ties
+ * keep input pair order).
+ *
+ * Invariants (pinned by property tests):
+ *  - `matrix[i][j] === matrix[j][i]` — computed once, mirrored.
+ *  - `matrix[i][i] === 1` EXACTLY — set by definition, so
+ *    self-similarity is an invariant rather than a float artifact
+ *    (and duplicate texts at different ids still compare via cosine).
+ *  - N items → N·(N−1)/2 pairs.
+ */
+export declare function pairwiseSimilarity(args: PairwiseSimilarityArgs): Promise<PairwiseSimilarityResult>;

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

@@ -0,0 +1,252 @@
+/**
+ * influence-core types — the ONE embedding-based scoring contract.
+ *
+ * Pattern: Strategy seam (plug-and-play meta-pattern) — the frame and
+ *          rule engine are the library's; the `Embedder` is consumer-
+ *          injected, exactly like NarrativeFormatter / reliability /
+ *          permission / commentary strategies.
+ * Role:    `src/lib/` leaf module. Shared by the FDL paper pipeline
+ *          (Visible Reasoning, Eq. 1–6), RFC-002's tool-catalog lint +
+ *          margin recorder (C1/C4/C5), and RFC-003 Part B's LLM-edge
+ *          weigher (D7). Extracted as RFC-003 block D6 so all three
+ *          consumers share one scoring engine and one embedding cache.
+ *
+ * ## Honest claim (RFC-002 §2, the FDL discipline)
+ *
+ * Every score produced under these types is a PROXY computed from
+ * embedding geometry — cosine similarity over consumer-injected
+ * embeddings. None of it reads model internals. Scores mean "high
+ * semantic alignment", never "the model chose/answered BECAUSE".
+ * Scores are not additive across items and are not causal attribution
+ * — counterfactual ablation (RFC-003 stage 4) is where causal claims
+ * live.
+ */
+export type { Embedder, EmbedArgs, EmbedBatchArgs } from '../../memory/embedding/types.js';
+/**
+ * Weights for the four-signal composite (paper Eq. 5).
+ *
+ * Configurable PRIORS, not learned parameters (paper §8). Defaults
+ * encode: direct semantic similarity (fa) strongest, then consistency
+ * across reasoning (avg), breadth of reference (persist), structural
+ * proximity (depth).
+ */
+export interface InfluenceWeights {
+    /** α — Final Answer Similarity weight. */
+    readonly fa: number;
+    /** β — Average Relevancy weight. */
+    readonly avg: number;
+    /** γ — Persistence weight. */
+    readonly persist: number;
+    /** δ — Structural Proximity weight. */
+    readonly depth: number;
+}
+/** Paper defaults: α=0.40, β=0.30, γ=0.20, δ=0.10 (sum to 1.0). */
+export declare const DEFAULT_INFLUENCE_WEIGHTS: InfluenceWeights;
+/** Paper default for the PERSIST threshold T (Eq. 3). */
+export declare const DEFAULT_PERSISTENCE_THRESHOLD = 0.3;
+/** RFC-002 §4 default: margins below this flag the choice as `narrow`. */
+export declare const DEFAULT_MARGIN_THRESHOLD = 0.05;
+/**
+ * RFC-003 default: an influence ranking whose top-1 vs top-2 score margin is
+ * below this has NO clear winner — a shortlist, not a verdict. Escalate to
+ * ablation.
+ *
+ * UNCALIBRATED proxy starting point, chosen for interpretability. `margin`
+ * is an ABSOLUTE difference on the same scale as `scoreInfluence`'s composite
+ * (S ∈ ≈[−0.7, 1]), so this threshold is EMBEDDER-RELATIVE — recalibrate by
+ * sweeping clear-winner vs flat rankings on your embedder. The numeric
+ * coincidence with `DEFAULT_MARGIN_THRESHOLD` is NOT a shared derivation: that
+ * one measures `scoreMargin`'s chosen-vs-not-chosen distribution, a different
+ * statistic.
+ */
+export declare const DEFAULT_CLEAR_WINNER_MARGIN = 0.05;
+/**
+ * RFC-003 default: when there is no clear winner, suspects scoring within this
+ * band of the top form the shortlist ablation should COVER (the culprit may be
+ * any of them — or, for absence bugs, none). UNCALIBRATED proxy; embedder-
+ * relative (see `DEFAULT_CLEAR_WINNER_MARGIN`).
+ */
+export declare const DEFAULT_SHORTLIST_BAND = 0.1;
+/**
+ * RFC-003 default for `ratioStrategy`: the top-2 gap as a FRACTION of the top
+ * score `(s0 − s1) / |s0|`. Unlike the absolute margin this is scale-invariant,
+ * so it transfers across embedders / answer lengths. UNCALIBRATED proxy.
+ */
+export declare const DEFAULT_CLEAR_WINNER_RATIO = 0.05;
+/**
+ * Pluggable rule for "does one source clearly win this ranking?" — the
+ * decisiveness test inside `rankingConfidence`. The library ships
+ * `marginStrategy` (default, absolute gap) and `ratioStrategy` (scale-
+ * invariant); consumers may bring their own (e.g. entropy / dispersion). The
+ * framework around it — always shortlisting the lead, covering the runner-up
+ * when there is no clear winner, malformed-score robustness — is NOT the
+ * strategy's concern; the strategy only judges the clean, all-finite case.
+ */
+export interface ConfidenceStrategy {
+    /** Identifies the rule — shown in `reason`, and the key on a benchmark
+     *  leaderboard of strategies. */
+    readonly name: string;
+    /**
+     * Given the FINITE scores sorted DESCENDING (length >= 2), decide whether
+     * one source clearly dominates. Pure and deterministic.
+     */
+    isClearWinner(rankedScores: readonly number[]): boolean;
+}
+/**
+ * Confidence in an influence ranking (`scoreInfluence` output) — the honesty
+ * companion to the scorer.
+ *
+ * Output-similarity influence is a PROXY: it ranks sources by how much they
+ * resemble the final answer. It 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 at all, so it can
+ * rank low or off the top. This result makes that honesty explicit: when no
+ * source clearly dominates, the ranking is a SHORTLIST to confirm by ablation,
+ * never a verdict. Mirrors the causal slice's incompleteness markers — the
+ * library says what its proxy cannot see.
+ */
+export interface RankingConfidence {
+    /**
+     * True when one source clearly dominates (`margin >= clearWinnerMargin`),
+     * so the ranking can be trusted as a LEAD. False = treat as shortlist +
+     * ablate. (A single suspect is trivially a clear winner — by absence of
+     * alternatives, not strength of signal.) NOTE: this is the inverse of the
+     * sibling `MarginResult.flags.narrow`. Honesty: a clear winner means the
+     * proxy has a clear top, NOT that the top is the cause — a high-similarity
+     * innocent the answer rationalizes over can win; ablation is the only causal
+     * confirmation in either branch.
+     */
+    readonly clearWinner: boolean;
+    /**
+     * `score(#1) − score(#2)`, an ABSOLUTE difference on the composite-score
+     * scale (embedder-relative). `undefined` when fewer than 2 suspects, when
+     * all scores are malformed, or when the runner-up score is unavailable
+     * (a clean top over a malformed #2). Read `clearWinner` to disambiguate.
+     */
+    readonly margin: number | undefined;
+    /** Id of the top-ranked suspect (the lead). `undefined` only when there are
+     *  none. Under an exact top tie this is the input-order first and not
+     *  meaningful (there is no clear winner anyway). */
+    readonly lead: string | undefined;
+    /**
+     * Suspects within the band of the top score — the set ablation should COVER.
+     * CONSUME ONLY WHEN `clearWinner` IS FALSE; when there is a clear winner this
+     * is informational (the band near the top), not an ablation worklist. Always
+     * includes `lead` when present, and — when no clear winner with ≥2 suspects —
+     * the runner-up too. De-duplicated.
+     */
+    readonly shortlist: readonly string[];
+    /** Human-readable explanation for narratives / reports. PRESENTATION ONLY —
+     *  read `clearWinner` / `margin` / `shortlist` as data, never parse this
+     *  string. */
+    readonly reason: string;
+}
+/** The four signal values for one evidence item (paper Eq. 1–4). */
+export interface SignalScores {
+    /** FA — cosine(evidence, finalAnswer). Range [-1, 1]. */
+    readonly fa: number;
+    /** AVG — mean cosine(evidence, ancestor_i); 0 when no ancestors. */
+    readonly avg: number;
+    /** PERSIST — fraction of ancestors with similarity > T; 0 when none. */
+    readonly persist: number;
+    /** DEPTH — 1 / (1 + ancestorCount). Range (0, 1]. */
+    readonly depth: number;
+}
+/** One evidence item to score: a tool result (or any context source)
+ *  plus the texts of the LLM reasoning steps that referenced it. */
+export interface EvidenceInput {
+    /** Stable identifier — e.g. a runtimeStageId or tool-call id. */
+    readonly id: string;
+    /** The evidence text (tool result content). */
+    readonly text: string;
+    /**
+     * Texts of the item's LLM reasoning ANCESTORS — only stages with
+     * model text output, not pipeline plumbing (paper §5.1, DEPTH).
+     * Empty array = direct evidence with no intermediaries.
+     */
+    readonly ancestorTexts: readonly string[];
+}
+/** Scored evidence item — the per-item output of `scoreInfluence`. */
+export interface InfluenceScore {
+    readonly id: string;
+    /** The four raw signals (proxies — see module honest claim). */
+    readonly signals: SignalScores;
+    /**
+     * The EFFECTIVE weights used for this item — equals the configured
+     * weights normally; the Eq. 6 redistribution when `adapted` is true.
+     */
+    readonly weights: InfluenceWeights;
+    /**
+     * True when adaptive weight redistribution (paper Eq. 6) applied —
+     * the item had no LLM ancestors, so AVG/PERSIST were structurally
+     * zero and their weight mass moved onto FA/DEPTH. Per-item: a
+     * multi-tool pipeline may mix adapted and standard items.
+     */
+    readonly adapted: boolean;
+    /** Composite S(d) (Eq. 5) under the effective weights. */
+    readonly score: number;
+}
+/** A text item for pairwise comparison (e.g. a tool description). */
+export interface SimilarityItem {
+    /** Stable identifier — e.g. the tool name. Must be unique. */
+    readonly id: string;
+    readonly text: string;
+}
+/** One ranked pair from `pairwiseSimilarity`. */
+export interface SimilarityPair {
+    /** id of the first item (lower input index). */
+    readonly a: string;
+    /** id of the second item (higher input index). */
+    readonly b: string;
+    /** cosine(embed(a.text), embed(b.text)). */
+    readonly similarity: number;
+}
+export interface PairwiseSimilarityResult {
+    /** Item ids in input order — the matrix axes. */
+    readonly ids: readonly string[];
+    /**
+     * Full similarity matrix, `matrix[i][j] = cosine(item_i, item_j)`.
+     * Symmetric by construction; the diagonal is EXACTLY 1 by definition
+     * (self-similarity is an invariant, not a float approximation).
+     */
+    readonly matrix: ReadonlyArray<readonly number[]>;
+    /** Upper-triangle pairs ranked by similarity, descending. */
+    readonly pairs: readonly SimilarityPair[];
+}
+/** A candidate in a choice competition (e.g. an offered tool). */
+export interface MarginCandidate {
+    /** Unique name — the identifier the chooser used. */
+    readonly name: string;
+    /** The text the chooser saw (the tool description). */
+    readonly text: string;
+}
+/** One candidate's proximity to the choice context, ranked. */
+export interface CandidateScore {
+    readonly name: string;
+    /** cosine(embed(contextText), embed(candidate.text)). */
+    readonly score: number;
+}
+export interface MarginResult {
+    /** All candidates ranked by score, descending. */
+    readonly scores: readonly CandidateScore[];
+    /** The chosen candidate names, echoed from the input. */
+    readonly chosen: readonly string[];
+    /** Name of the highest-scoring candidate (by the proxy). */
+    readonly topScored: string;
+    /**
+     * score(best chosen) − score(best non-chosen). Small margin =
+     * fragile choice. `undefined` when every candidate was chosen
+     * (no competition to measure).
+     */
+    readonly margin: number | undefined;
+    readonly flags: {
+        /** margin < marginThreshold — the choice was a close call. */
+        readonly narrow: boolean;
+        /**
+         * The top-scored candidate was NOT among the chosen. Either a
+         * proxy miss or a genuinely surprising choice — both are exactly
+         * what a debugger wants surfaced (RFC-002 §4).
+         */
+        readonly proxyDisagreement: boolean;
+    };
+}