agentfootprint 10.2.0 → 10.3.1

package/dist/esm/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/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/influence-core/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/influence-core/cache.ts"],"names":[],"mappings":"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"}

package/dist/esm/influence-core/contrastive.js

@@ -0,0 +1,89 @@
+/**
+ * contrastive — influence scoring against a REFERENCE output (RFC-003).
+ *
+ * Pattern: a SEPARATE, opt-in second stage over the four-signal scorer — not a
+ *          modification of `scoreInfluence`. Same `InfluenceScore[]` return, so
+ *          `rankingConfidence` and the rest compose on it unchanged.
+ * Role:    `src/influence-core/` leaf, sibling to `scoreInfluence`.
+ *
+ * ## Why this exists (the topical-innocent confound)
+ *
+ * Plain output-similarity (`scoreInfluence`'s FA) ranks a source by how much it
+ * resembles the actual answer. That is confounded by **topically-central
+ * innocents**: the policy a refund decision is *about* resembles ANY refund
+ * output — right or wrong — so it can out-rank the source that actually caused
+ * the wrong one. The fix: score by CONTRAST against a reference output (a
+ * known-good / expected / prior-good run). A topical innocent is similar to
+ * BOTH outputs, so it cancels (~0 contrast); the real culprit is similar to the
+ * WRONG output specifically, so it stands out.
+ *
+ *   contrastive FA(e) = sim(e, answer) − sim(e, reference)
+ *
+ * Everything else (the AVG / PERSIST / DEPTH reasoning-trace signals, the
+ * composite, adaptive weights) is shared with `scoreInfluence` verbatim — only
+ * the FA term is contrastive.
+ *
+ * Honest claim (RFC-002 §2): still an embedding-geometry PROXY, never causal —
+ * the contrast removes a confound, it does not prove causation. Ablation is the
+ * causal tier. And it is OPT-IN: it needs a reference output, so it is for
+ * regression / eval debugging (you have a prior-good or expected output), not
+ * cold localization — without a reference, use `scoreInfluence`.
+ */
+import { cosineSimilarity } from '../memory/embedding/cosine.js';
+import { adaptWeights, assertValidWeights, averageRelevancy, compositeScore, embedAll, persistence, structuralProximity, } from './signals.js';
+import { DEFAULT_INFLUENCE_WEIGHTS, DEFAULT_PERSISTENCE_THRESHOLD } from './types.js';
+/**
+ * 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 async function scoreContrastiveInfluence(args) {
+    const weights = args.weights ?? DEFAULT_INFLUENCE_WEIGHTS;
+    const threshold = args.persistenceThreshold ?? DEFAULT_PERSISTENCE_THRESHOLD;
+    assertUniqueIds(args.evidence);
+    assertValidWeights(weights, 'scoreContrastiveInfluence');
+    // ONE deduplicated embedding pass over every distinct text (answer + reference
+    // + evidence + ancestors).
+    const texts = new Set([args.answerText, args.referenceText]);
+    for (const item of args.evidence) {
+        texts.add(item.text);
+        for (const ancestor of item.ancestorTexts)
+            texts.add(ancestor);
+    }
+    const vectorByText = await embedAll(args.embedder, [...texts], args.signal);
+    const answerVec = vectorByText.get(args.answerText);
+    const referenceVec = vectorByText.get(args.referenceText);
+    const scored = args.evidence.map((item) => {
+        const evidenceVec = vectorByText.get(item.text);
+        const ancestorVecs = item.ancestorTexts.map((t) => vectorByText.get(t));
+        // The only contrastive term: answer-similarity MINUS reference-similarity.
+        const faContrast = cosineSimilarity(evidenceVec, answerVec) - cosineSimilarity(evidenceVec, referenceVec);
+        const signals = {
+            fa: faContrast,
+            avg: averageRelevancy(evidenceVec, ancestorVecs),
+            persist: persistence(evidenceVec, ancestorVecs, threshold),
+            depth: structuralProximity(ancestorVecs.length),
+        };
+        const effective = adaptWeights(weights, ancestorVecs.length);
+        return {
+            id: item.id,
+            signals,
+            weights: effective.weights,
+            adapted: effective.adapted,
+            score: compositeScore(signals, effective.weights),
+        };
+    });
+    return scored.sort((a, b) => b.score - a.score);
+}
+function assertUniqueIds(evidence) {
+    const seen = new Set();
+    for (const e of evidence) {
+        if (seen.has(e.id))
+            throw new Error(`scoreContrastiveInfluence: duplicate evidence id "${e.id}"`);
+        seen.add(e.id);
+    }
+}
+//# sourceMappingURL=contrastive.js.map

package/dist/esm/influence-core/contrastive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contrastive.js","sourceRoot":"","sources":["../../../src/influence-core/contrastive.ts"],"names":[],"mappings":"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"}

package/dist/esm/influence-core/explain.js

@@ -0,0 +1,80 @@
+/**
+ * explainChoice — a UI-ready VERDICT for one tool pick: which context
+ * CHANNEL (system rules / user task / data from earlier tool results)
+ * best explains it, with the exact unit text to quote.
+ *
+ * Thin composite over `attributeChoice` — same math, zero duplication:
+ * the ranking, the top unit, and the per-channel share of positive
+ * similarity mass all come from the one existing engine. What this adds
+ * is presentation shape: the unit TEXT carried through (so a UI can
+ * quote the citation verbatim), a per-channel top unit, and a channels
+ * array sorted by share that lists EVERY channel present in the units —
+ * including zero-share ones, so "the data channel contributed nothing"
+ * is a visible verdict, not a missing key.
+ *
+ * Pattern: pure async function, embedder-injected. No agent/runtime
+ *          imports — `src/influence-core/` leaf, same as
+ *          `attributeChoice` / `scoreMargin`.
+ *
+ * Honest claim (RFC-002 §2): every score and share here is embedding
+ * geometry between the tool text and each unit — a PROXY for which
+ * context the pick ALIGNS with, never proof the model used that unit.
+ * This is Tier 1 (similarity); counterfactual ablation (Tier 3) is the
+ * ground truth that would validate it.
+ */
+import { attributeChoice } from './attribute.js';
+/**
+ * Run `attributeChoice` and reshape the result for a UI: join each unit's
+ * text back by id, pick the best unit per channel, and rank the channels
+ * by their share of positive similarity mass.
+ *
+ * Fail-loud validation is inherited from `attributeChoice`: empty units
+ * or duplicate unit ids throw — caller wiring bugs, not runtime conditions.
+ */
+export async function explainChoice(args) {
+    const attribution = await attributeChoice({
+        tool: args.tool,
+        units: args.units,
+        embedder: args.embedder,
+        ...(args.signal ? { signal: args.signal } : {}),
+    });
+    // Join the unit text back by id (ids are unique — attributeChoice validated).
+    const textById = new Map();
+    for (const u of args.units)
+        textById.set(u.id, u.text);
+    const withText = (score) => ({
+        ...score,
+        text: textById.get(score.id),
+    });
+    const ranked = attribution.units.map(withText);
+    // One verdict per channel, in first-appearance order (stable tiebreak),
+    // then sorted by share descending. `ranked` is already descending, so
+    // the first unit seen per channel is that channel's top.
+    const channelOrder = [];
+    const topByChannel = new Map();
+    for (const u of args.units) {
+        if (!channelOrder.includes(u.channel))
+            channelOrder.push(u.channel);
+    }
+    for (const unit of ranked) {
+        if (!topByChannel.has(unit.channel))
+            topByChannel.set(unit.channel, unit);
+    }
+    const channels = channelOrder.map((channel) => {
+        const top = topByChannel.get(channel);
+        return {
+            channel,
+            share: attribution.byChannel[channel] ?? 0,
+            ...(top ? { top } : {}),
+        };
+    });
+    // Stable sort — zero-share channels sink to the end, ties keep order.
+    channels.sort((a, b) => b.share - a.share);
+    return {
+        tool: attribution.tool,
+        channels,
+        top: withText(attribution.top),
+        units: ranked,
+    };
+}
+//# sourceMappingURL=explain.js.map

package/dist/esm/influence-core/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../src/influence-core/explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAsDjD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAuB;IACzD,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC;QACxC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC,CAAC;IAEH,8EAA8E;IAC9E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK;QAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,CAAC,KAAgB,EAAyC,EAAE,CAAC,CAAC;QAC7E,GAAG,KAAK;QACR,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAW;KACvC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAE/C,wEAAwE;IACxE,sEAAsE;IACtE,yDAAyD;IACzD,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAiD,CAAC;IAC9E,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;YAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACtE,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,QAAQ,GAAqB,YAAY,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QAC9D,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACtC,OAAO;YACL,OAAO;YACP,KAAK,EAAE,WAAW,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;YAC1C,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxB,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAE3C,OAAO;QACL,IAAI,EAAE,WAAW,CAAC,IAAI;QACtB,QAAQ;QACR,GAAG,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC;QAC9B,KAAK,EAAE,MAAM;KACd,CAAC;AACJ,CAAC"}

package/dist/esm/influence-core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/influence-core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAsBH,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,aAAa,GAEd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,yBAAyB,EAAsC,MAAM,kBAAkB,CAAC;AAEjG,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,GAGf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,cAAc,EACd,mBAAmB,GAGpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,qBAAqB,EAAkC,MAAM,cAAc,CAAC;AACrF,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,yBAAyB,GAG1B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,kBAAkB,EAA+B,MAAM,iBAAiB,CAAC;AAElF,OAAO,EAAE,WAAW,EAAwB,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAE,eAAe,EAA4B,MAAM,gBAAgB,CAAC;AAE3E,OAAO,EACL,aAAa,GAId,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,YAAY,EAA4B,MAAM,eAAe,CAAC"}

package/dist/esm/influence-core/lexical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical.js","sourceRoot":"","sources":["../../../src/influence-core/lexical.ts"],"names":[],"mappings":"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"}

package/dist/esm/influence-core/margin.js

@@ -0,0 +1,110 @@
+/**
+ * scoreMargin — choice-margin scoring over a candidate set
+ * (RFC-002 C4's core: (candidates, contextText, chosen) → scores +
+ * margin + flags).
+ *
+ * Pattern: pure async function, embedder-injected. NO recorder wiring
+ *          — `toolChoiceRecorder` (C5) owns event ingestion and a
+ *          KeyedStore, and calls this for the math.
+ * Role:    `src/influence-core/` leaf. No agent/runtime imports.
+ *
+ * The competition model (RFC-002 §4): embed the choice context (what
+ * the model saw — user message + latest reasoning), embed each offered
+ * candidate's text, rank candidates by similarity to the context.
+ *   margin = score(best chosen) − score(best non-chosen)
+ * Small margin = fragile choice (`narrow`); top-scored candidate not
+ * among the chosen = `proxyDisagreement` (always worth surfacing:
+ * either a proxy miss or a genuinely surprising model choice).
+ *
+ * Honest claim: the scores are embedding geometry between context and
+ * descriptions — a proxy for the model's selection function, never
+ * "the model chose because". Margin is EVIDENCE of decisiveness, not
+ * proof; tier 3 (choice-entropy sampling) validates the proxy.
+ */
+import { cosineSimilarity } from '../memory/embedding/cosine.js';
+import { DEFAULT_MARGIN_THRESHOLD } from './types.js';
+/**
+ * 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 async function scoreMargin(args) {
+    const { candidates, chosen, embedder } = args;
+    const marginThreshold = args.marginThreshold ?? DEFAULT_MARGIN_THRESHOLD;
+    validate(candidates, chosen);
+    // One deduplicated embedding pass: context + distinct candidate texts.
+    const distinct = [...new Set([args.contextText, ...candidates.map((c) => c.text)])];
+    const vectors = embedder.embedBatch
+        ? await embedder.embedBatch({
+            texts: distinct,
+            ...(args.signal ? { signal: args.signal } : {}),
+        })
+        : await sequentialEmbed(embedder, distinct, args.signal);
+    const vectorByText = new Map();
+    for (let i = 0; i < distinct.length; i++)
+        vectorByText.set(distinct[i], vectors[i]);
+    const contextVec = vectorByText.get(args.contextText);
+    const scores = candidates.map((candidate) => ({
+        name: candidate.name,
+        score: cosineSimilarity(contextVec, vectorByText.get(candidate.text)),
+    }));
+    // Stable sort — ties keep candidate input order.
+    scores.sort((a, b) => b.score - a.score);
+    const chosenSet = new Set(chosen);
+    let bestChosen = -Infinity;
+    let bestOther = -Infinity;
+    for (const { name, score } of scores) {
+        if (chosenSet.has(name))
+            bestChosen = Math.max(bestChosen, score);
+        else
+            bestOther = Math.max(bestOther, score);
+    }
+    const margin = bestOther === -Infinity ? undefined : bestChosen - bestOther;
+    const topScored = scores[0].name;
+    return {
+        scores,
+        chosen: [...chosen],
+        topScored,
+        margin,
+        flags: {
+            narrow: margin !== undefined && margin < marginThreshold,
+            proxyDisagreement: !chosenSet.has(topScored),
+        },
+    };
+}
+async function sequentialEmbed(embedder, texts, signal) {
+    const out = [];
+    for (const text of texts) {
+        out.push(await embedder.embed({ text, ...(signal ? { signal } : {}) }));
+    }
+    return out;
+}
+function validate(candidates, chosen) {
+    if (candidates.length === 0) {
+        throw new Error('scoreMargin: candidates must be non-empty');
+    }
+    const names = new Set();
+    for (const candidate of candidates) {
+        if (names.has(candidate.name)) {
+            throw new Error(`scoreMargin: duplicate candidate name '${candidate.name}' — names must be unique`);
+        }
+        names.add(candidate.name);
+    }
+    if (chosen.length === 0) {
+        throw new Error('scoreMargin: chosen must be non-empty — calls that chose nothing have no margin to score');
+    }
+    for (const name of chosen) {
+        if (!names.has(name)) {
+            throw new Error(`scoreMargin: chosen '${name}' is not among the candidates`);
+        }
+    }
+}
+//# sourceMappingURL=margin.js.map

package/dist/esm/influence-core/margin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"margin.js","sourceRoot":"","sources":["../../../src/influence-core/margin.ts"],"names":[],"mappings":"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"}

package/dist/esm/influence-core/signals.js

@@ -0,0 +1,241 @@
+/**
+ * FDL influence signals — the four-signal composite from the Visible
+ * Reasoning paper (Eq. 1–6), extracted verbatim as RFC-003 block D6.
+ *
+ * Pattern: pure scorer functions + one async orchestrator. Vector-level
+ *          functions are deterministic and embedder-free; only
+ *          `scoreInfluence` touches the injected `Embedder`.
+ * Role:    `src/influence-core/` leaf. Consumers: the FDL paper
+ *          pipeline (stage 5, computeInfluenceScores), RFC-003 D7's
+ *          LLM-edge weigher, and — one level up — RFC-002's margin
+ *          scoring shares the same geometry via `margin.ts`.
+ *
+ * ## Honest claim per signal (RFC-002 §2 discipline)
+ *
+ * Every signal is embedding GEOMETRY — a deterministic proxy, not a
+ * window into the model:
+ *
+ *  - FA      "the tool's output is semantically close to the final
+ *            answer" — NOT "the answer was derived from it".
+ *  - AVG     "the tool's output stayed semantically close to the
+ *            reasoning steps" — NOT "the model kept consulting it".
+ *  - PERSIST "many reasoning steps are similar to it above T" — breadth
+ *            of apparent reference, NOT counted citations.
+ *  - DEPTH   pure structure (1/(1+ancestors)) — directness of position
+ *            in the trace, knows nothing about content at all.
+ *
+ * The composite S(d) means "high semantic alignment with the answer",
+ * never "this source contributed X% of the answer" (paper §5.2: scores
+ * are per-item, not additive, not causal attribution). Same inputs →
+ * same scores, unlike LLM-as-judge.
+ */
+import { cosineSimilarity } from '../memory/embedding/cosine.js';
+import { DEFAULT_INFLUENCE_WEIGHTS, DEFAULT_PERSISTENCE_THRESHOLD } 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 function finalAnswerSimilarity(evidenceVec, finalAnswerVec) {
+    return cosineSimilarity(evidenceVec, finalAnswerVec);
+}
+/**
+ * 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 function averageRelevancy(evidenceVec, ancestorVecs) {
+    const n = ancestorVecs.length;
+    if (n === 0)
+        return 0;
+    let sum = 0;
+    for (const ancestorVec of ancestorVecs) {
+        sum += cosineSimilarity(evidenceVec, ancestorVec);
+    }
+    return sum / n;
+}
+/**
+ * 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 function persistence(evidenceVec, ancestorVecs, threshold = DEFAULT_PERSISTENCE_THRESHOLD) {
+    const n = ancestorVecs.length;
+    if (n === 0)
+        return 0;
+    let above = 0;
+    for (const ancestorVec of ancestorVecs) {
+        if (cosineSimilarity(evidenceVec, ancestorVec) > threshold)
+            above += 1;
+    }
+    return above / n;
+}
+/**
+ * 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 function structuralProximity(ancestorCount) {
+    if (!Number.isInteger(ancestorCount) || ancestorCount < 0) {
+        throw new Error(`structuralProximity: ancestorCount must be a non-negative integer (got ${ancestorCount})`);
+    }
+    return 1 / (1 + ancestorCount);
+}
+/**
+ * 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 function adaptWeights(weights, ancestorCount) {
+    if (ancestorCount > 0)
+        return { weights, adapted: false };
+    const base = weights.fa + weights.depth;
+    if (base === 0)
+        return { weights, adapted: false };
+    const mass = weights.avg + weights.persist;
+    return {
+        weights: {
+            fa: weights.fa + (mass * weights.fa) / base,
+            avg: 0,
+            persist: 0,
+            depth: weights.depth + (mass * weights.depth) / base,
+        },
+        adapted: mass > 0,
+    };
+}
+/**
+ * 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 function compositeScore(signals, weights) {
+    return (weights.fa * signals.fa +
+        weights.avg * signals.avg +
+        weights.persist * signals.persist +
+        weights.depth * signals.depth);
+}
+/**
+ * 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 async function scoreInfluence(args) {
+    const weights = args.weights ?? DEFAULT_INFLUENCE_WEIGHTS;
+    assertValidWeights(weights);
+    const threshold = args.persistenceThreshold ?? DEFAULT_PERSISTENCE_THRESHOLD;
+    assertUniqueIds(args.evidence);
+    // ONE deduplicated embedding pass over every distinct text.
+    const texts = new Set([args.finalAnswerText]);
+    for (const item of args.evidence) {
+        texts.add(item.text);
+        for (const ancestor of item.ancestorTexts)
+            texts.add(ancestor);
+    }
+    const vectorByText = await embedAll(args.embedder, [...texts], args.signal);
+    const finalVec = vectorByText.get(args.finalAnswerText);
+    const scored = args.evidence.map((item) => {
+        const evidenceVec = vectorByText.get(item.text);
+        const ancestorVecs = item.ancestorTexts.map((t) => vectorByText.get(t));
+        const signals = {
+            fa: finalAnswerSimilarity(evidenceVec, finalVec),
+            avg: averageRelevancy(evidenceVec, ancestorVecs),
+            persist: persistence(evidenceVec, ancestorVecs, threshold),
+            depth: structuralProximity(ancestorVecs.length),
+        };
+        const effective = adaptWeights(weights, ancestorVecs.length);
+        return {
+            id: item.id,
+            signals,
+            weights: effective.weights,
+            adapted: effective.adapted,
+            score: compositeScore(signals, effective.weights),
+        };
+    });
+    // Stable sort — equal scores keep evidence input order.
+    return scored.sort((a, b) => b.score - a.score);
+}
+/** Embed distinct texts via batch API when available, else sequentially. */
+export async function embedAll(embedder, texts, signal) {
+    const vectors = embedder.embedBatch
+        ? await embedder.embedBatch({ texts, ...(signal ? { signal } : {}) })
+        : await sequentialEmbed(embedder, texts, signal);
+    const byText = new Map();
+    for (let i = 0; i < texts.length; i++)
+        byText.set(texts[i], vectors[i]);
+    return byText;
+}
+async function sequentialEmbed(embedder, texts, signal) {
+    const out = [];
+    for (const text of texts) {
+        out.push(await embedder.embed({ text, ...(signal ? { signal } : {}) }));
+    }
+    return out;
+}
+/**
+ * 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 function assertValidWeights(weights, fnName = 'scoreInfluence') {
+    for (const [name, value] of Object.entries(weights)) {
+        if (!Number.isFinite(value) || value < 0) {
+            throw new Error(`${fnName}: weight '${name}' must be a finite non-negative number (got ${value})`);
+        }
+    }
+    if (weights.fa + weights.avg + weights.persist + weights.depth === 0) {
+        throw new Error(`${fnName}: all weights are zero — the composite would always be 0`);
+    }
+}
+/**
+ * Validate that every evidence id is unique. Shared by `scoreInfluence` and
+ * `scoreLexicalInfluence` — `fnName` attributes the error to the actual caller.
+ */
+export function assertUniqueIds(evidence, fnName = 'scoreInfluence') {
+    const seen = new Set();
+    for (const item of evidence) {
+        if (seen.has(item.id)) {
+            throw new Error(`${fnName}: duplicate evidence id '${item.id}' — ids must be unique`);
+        }
+        seen.add(item.id);
+    }
+}
+//# sourceMappingURL=signals.js.map