agentfootprint 6.22.0 → 6.24.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"margin.js","sourceRoot":"","sources":["../../../../src/lib/influence-core/margin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAqBtD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAqB;IACrD,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAC9C,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,wBAAwB,CAAC;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAE7B,uEAAuE;IACvE,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACpF,MAAM,OAAO,GAAG,QAAQ,CAAC,UAAU;QACjC,CAAC,CAAC,MAAM,QAAQ,CAAC,UAAU,CAAC;YACxB,KAAK,EAAE,QAAQ;YACf,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,CAAC;QACJ,CAAC,CAAC,MAAM,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3D,MAAM,YAAY,GAAG,IAAI,GAAG,EAA6B,CAAC;IAC1D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAEpF,MAAM,UAAU,GAAG,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAsB,CAAC;IAC3E,MAAM,MAAM,GAAqB,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAC9D,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,KAAK,EAAE,gBAAgB,CAAC,UAAU,EAAE,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAsB,CAAC;KAC3F,CAAC,CAAC,CAAC;IACJ,iDAAiD;IACjD,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAEzC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,UAAU,GAAG,CAAC,QAAQ,CAAC;IAC3B,IAAI,SAAS,GAAG,CAAC,QAAQ,CAAC;IAC1B,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,MAAM,EAAE,CAAC;QACrC,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;;YAC7D,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,GAAG,SAAS,CAAC;IAC5E,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEjC,OAAO;QACL,MAAM;QACN,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC;QACnB,SAAS;QACT,MAAM;QACN,KAAK,EAAE;YACL,MAAM,EAAE,MAAM,KAAK,SAAS,IAAI,MAAM,GAAG,eAAe;YACxD,iBAAiB,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC;SAC7C;KACF,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,eAAe,CAC5B,QAAkB,EAClB,KAAwB,EACxB,MAAoB;IAEpB,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,GAAG,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,UAAsC,EAAE,MAAyB;IACjF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACb,0CAA0C,SAAS,CAAC,IAAI,0BAA0B,CACnF,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,+BAA+B,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,232 @@
+/**
+ * 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/lib/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. */
+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;
+}
+function assertValidWeights(weights) {
+    for (const [name, value] of Object.entries(weights)) {
+        if (!Number.isFinite(value) || value < 0) {
+            throw new Error(`scoreInfluence: weight '${name}' must be a finite non-negative number (got ${value})`);
+        }
+    }
+    if (weights.fa + weights.avg + weights.persist + weights.depth === 0) {
+        throw new Error('scoreInfluence: all weights are zero — the composite would always be 0');
+    }
+}
+function assertUniqueIds(evidence) {
+    const seen = new Set();
+    for (const item of evidence) {
+        if (seen.has(item.id)) {
+            throw new Error(`scoreInfluence: duplicate evidence id '${item.id}' — ids must be unique`);
+        }
+        seen.add(item.id);
+    }
+}
+//# sourceMappingURL=signals.js.map

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

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

package/dist/esm/lib/influence-core/similarity.js

@@ -0,0 +1,79 @@
+/**
+ * pairwiseSimilarity — pairwise cosine over a set of texts
+ * (RFC-002 C1's core: tool descriptions → matrix + ranked pairs).
+ *
+ * Pattern: pure async function, embedder-injected. No thresholds, no
+ *          verdicts, no lint rules — those are C1's `analyzeToolCatalog`
+ *          policy layer ON TOP of this geometry. The core stays
+ *          reusable for any "how confusable are these texts" question.
+ * Role:    `src/lib/influence-core/` leaf. No agent/runtime imports.
+ *
+ * Honest claim: similarity is embedding geometry over the DESCRIPTIONS
+ * — a confusability HEURISTIC, not a measurement of the model's actual
+ * selection function (RFC-002 §2; tier 3 validates the proxy via
+ * choice-entropy sampling).
+ */
+import { cosineSimilarity } from '../../memory/embedding/cosine.js';
+/**
+ * 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 async function pairwiseSimilarity(args) {
+    const { items, embedder } = args;
+    assertUniqueIds(items);
+    const ids = items.map((item) => item.id);
+    if (items.length === 0)
+        return { ids, matrix: [], pairs: [] };
+    // Deduplicated embedding pass (identical descriptions embed once).
+    const distinct = [...new Set(items.map((item) => item.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 itemVecs = items.map((item) => vectorByText.get(item.text));
+    // Upper triangle once, mirrored; diagonal exactly 1 by definition.
+    const matrix = items.map(() => new Array(items.length).fill(0));
+    const pairs = [];
+    for (let i = 0; i < items.length; i++) {
+        matrix[i][i] = 1;
+        for (let j = i + 1; j < items.length; j++) {
+            const similarity = cosineSimilarity(itemVecs[i], itemVecs[j]);
+            matrix[i][j] = similarity;
+            matrix[j][i] = similarity;
+            pairs.push({ a: ids[i], b: ids[j], similarity });
+        }
+    }
+    // Stable sort — ties keep (i, j) input order.
+    pairs.sort((p, q) => q.similarity - p.similarity);
+    return { ids, matrix, pairs };
+}
+async function sequentialEmbed(embedder, texts, signal) {
+    const out = [];
+    for (const text of texts) {
+        out.push(await embedder.embed({ text, ...(signal ? { signal } : {}) }));
+    }
+    return out;
+}
+function assertUniqueIds(items) {
+    const seen = new Set();
+    for (const item of items) {
+        if (seen.has(item.id)) {
+            throw new Error(`pairwiseSimilarity: duplicate item id '${item.id}' — ids must be unique`);
+        }
+        seen.add(item.id);
+    }
+}
+//# sourceMappingURL=similarity.js.map

package/dist/esm/lib/influence-core/similarity.js.map

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

package/dist/esm/lib/influence-core/types.js

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+/** Paper defaults: α=0.40, β=0.30, γ=0.20, δ=0.10 (sum to 1.0). */
+export const DEFAULT_INFLUENCE_WEIGHTS = Object.freeze({
+    fa: 0.4,
+    avg: 0.3,
+    persist: 0.2,
+    depth: 0.1,
+});
+/** Paper default for the PERSIST threshold T (Eq. 3). */
+export const DEFAULT_PERSISTENCE_THRESHOLD = 0.3;
+/** RFC-002 §4 default: margins below this flag the choice as `narrow`. */
+export const DEFAULT_MARGIN_THRESHOLD = 0.05;
+//# sourceMappingURL=types.js.map

package/dist/esm/lib/influence-core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/lib/influence-core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA0BH,mEAAmE;AACnE,MAAM,CAAC,MAAM,yBAAyB,GAAqB,MAAM,CAAC,MAAM,CAAC;IACvE,EAAE,EAAE,GAAG;IACP,GAAG,EAAE,GAAG;IACR,OAAO,EAAE,GAAG;IACZ,KAAK,EAAE,GAAG;CACX,CAAC,CAAC;AAEH,yDAAyD;AACzD,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,CAAC;AAEjD,0EAA0E;AAC1E,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC"}

package/dist/esm/lib/trace-toolpack/bounded.js

@@ -0,0 +1,76 @@
+/**
+ * Bounded serialization helpers for the trace toolpack.
+ *
+ * Pattern: pure functions — no state, no events.
+ * Role:    The token-economics layer. EVERY value the toolpack serves goes
+ *          through these: previews are capped, truncation is EXPLICIT
+ *          (never silent), and nested-path keys round-trip between the
+ *          engine's DELIM encoding and LLM-friendly dot notation.
+ */
+/**
+ * footprintjs's canonical nested-path delimiter (ASCII unit separator,
+ * `src/lib/memory/utils.ts`). Internal to the engine — the toolpack
+ * translates it to/from dot notation so the LLM never sees a control char.
+ */
+export const FP_PATH_DELIM = '\u001F';
+/** Engine path → LLM-friendly dotted display form. */
+export function displayKey(path) {
+    return path.includes(FP_PATH_DELIM) ? path.split(FP_PATH_DELIM).join('.') : path;
+}
+/**
+ * LLM-supplied key → engine path. Exact keys pass through; a dotted key
+ * that doesn't exist verbatim but matches a known DELIM-joined path is
+ * translated back. `knownPaths` is the set of every path seen in the
+ * commit log's trace entries.
+ */
+export function normalizeKey(key, knownPaths) {
+    if (knownPaths.has(key))
+        return key;
+    if (key.includes('.')) {
+        const delimForm = key.split('.').join(FP_PATH_DELIM);
+        if (knownPaths.has(delimForm))
+            return delimForm;
+    }
+    return key;
+}
+/** Replace every DELIM in an already-formatted text block with '.' for display. */
+export function displayText(text) {
+    return text.split(FP_PATH_DELIM).join('.');
+}
+/**
+ * Serialize a value to compact JSON, total-function style: cycles, BigInt
+ * and other non-JSON values degrade to a tagged placeholder instead of
+ * throwing — a debugger tool must never crash on the evidence it serves.
+ */
+export function safeStringify(value) {
+    if (value === undefined)
+        return 'undefined';
+    try {
+        const json = JSON.stringify(value);
+        return json === undefined ? String(value) : json;
+    }
+    catch {
+        return '[unserializable value]';
+    }
+}
+/** Serialize + cap at `maxChars`. Truncation is reported, never silent. */
+export function boundedPreview(value, maxChars) {
+    const full = safeStringify(value);
+    if (full.length <= maxChars) {
+        return { text: full, totalChars: full.length, truncated: false };
+    }
+    return { text: `${full.slice(0, maxChars)}…`, totalChars: full.length, truncated: true };
+}
+/** Render a preview with its honesty suffix when truncated. */
+export function renderPreview(preview, fetchHint) {
+    if (!preview.truncated)
+        return preview.text;
+    const hint = fetchHint ? ` — ${fetchHint}` : '';
+    return `${preview.text} (${preview.totalChars} chars total${hint})`;
+}
+/** Clamp an LLM-supplied numeric param into [min, hardCap], with a default. */
+export function clampParam(requested, fallback, min, hardCap) {
+    const value = typeof requested === 'number' && Number.isFinite(requested) ? requested : fallback;
+    return Math.max(min, Math.min(Math.floor(value), hardCap));
+}
+//# sourceMappingURL=bounded.js.map

package/dist/esm/lib/trace-toolpack/bounded.js.map

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

package/dist/esm/lib/trace-toolpack/index.js

@@ -0,0 +1,10 @@
+/**
+ * trace-toolpack — RFC-003 Part C: the introspection toolpack.
+ *
+ * footprintjs trace evidence exposed as TOOLS an LLM calls: a debugging
+ * model navigates a COMPLETED run's evidence by runtimeStageIds instead of
+ * reading dumps. Bounded, honest (⚠ markers), redaction-respecting.
+ */
+export { callTraceTool, traceToolpack } from './traceToolpack.js';
+export { TOOLPACK_HARD_CAPS, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/lib/trace-toolpack/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/trace-toolpack/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EACL,kBAAkB,GAGnB,MAAM,YAAY,CAAC"}