agentfootprint 6.23.0 → 6.24.0

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

@@ -0,0 +1,149 @@
+/**
+ * Fast, deterministic, browser-safe content hash (FNV-1a, two 32-bit
+ * lanes + length qualifier → "len-xxxxxxxxyyyyyyyy"). Non-cryptographic
+ * — cache keying only.
+ */
+export function contentHash(text) {
+    let h1 = 0x811c9dc5; // FNV offset basis
+    let h2 = 0xcbf29ce4; // second lane, different seed
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        h1 = Math.imul(h1 ^ c, 0x01000193); // FNV prime
+        h2 = Math.imul(h2 ^ c, 0x01000197); // distinct odd prime
+    }
+    const lane1 = (h1 >>> 0).toString(16).padStart(8, '0');
+    const lane2 = (h2 >>> 0).toString(16).padStart(8, '0');
+    return `${text.length.toString(36)}-${lane1}${lane2}`;
+}
+const DEFAULT_MAX_ENTRIES = 1024;
+/**
+ * Wrap an embedder with a bounded, content-hash-keyed LRU cache.
+ * See module docs for keying, bounds, and concurrency semantics.
+ */
+export class EmbeddingCache {
+    dimensions;
+    inner;
+    maxEntries;
+    /** LRU store — Map iteration order is recency (refreshed on hit). */
+    vectors = new Map();
+    /** Single-flight joins — promises live here until settled. */
+    inflight = new Map();
+    hits = 0;
+    misses = 0;
+    evictions = 0;
+    constructor(inner, options = {}) {
+        const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        if (!Number.isInteger(maxEntries) || maxEntries <= 0) {
+            throw new Error(`EmbeddingCache: maxEntries must be a positive integer (got ${maxEntries})`);
+        }
+        this.inner = inner;
+        this.maxEntries = maxEntries;
+        this.dimensions = inner.dimensions;
+    }
+    async embed(args) {
+        const key = contentHash(args.text);
+        const cached = this.vectors.get(key);
+        if (cached !== undefined) {
+            this.hits += 1;
+            this.refresh(key, cached);
+            return cached.slice();
+        }
+        const joined = this.inflight.get(key);
+        if (joined !== undefined) {
+            this.hits += 1; // coalesced — no extra inner call
+            return (await joined).slice();
+        }
+        this.misses += 1;
+        const promise = this.inner.embed(args);
+        this.inflight.set(key, promise);
+        try {
+            const vector = await promise;
+            this.store(key, vector);
+            return vector.slice();
+        }
+        finally {
+            // Settled either way; rejections are never cached.
+            this.inflight.delete(key);
+        }
+    }
+    async embedBatch(args) {
+        const { texts, signal } = args;
+        const out = new Array(texts.length);
+        // Partition into cache hits and misses (deduplicating within the
+        // batch — the same text twice embeds once).
+        const missTexts = [];
+        const missSlots = new Map(); // key → output indices
+        for (let i = 0; i < texts.length; i++) {
+            const key = contentHash(texts[i]);
+            const cached = this.vectors.get(key);
+            if (cached !== undefined) {
+                this.hits += 1;
+                this.refresh(key, cached);
+                out[i] = cached.slice();
+                continue;
+            }
+            const slots = missSlots.get(key);
+            if (slots !== undefined) {
+                this.hits += 1; // in-batch duplicate — one inner embed serves both
+                slots.push(i);
+                continue;
+            }
+            this.misses += 1;
+            missSlots.set(key, [i]);
+            missTexts.push(texts[i]);
+        }
+        if (missTexts.length > 0) {
+            const vectors = this.inner.embedBatch
+                ? await this.inner.embedBatch({ texts: missTexts, ...(signal ? { signal } : {}) })
+                : await this.embedSequential(missTexts, signal);
+            let v = 0;
+            for (const [key, slots] of missSlots) {
+                const vector = vectors[v++];
+                this.store(key, vector);
+                for (const slot of slots)
+                    out[slot] = vector.slice();
+            }
+        }
+        return out;
+    }
+    /** Visible cache health (bounded honesty — see module docs). */
+    stats() {
+        return {
+            size: this.vectors.size,
+            maxEntries: this.maxEntries,
+            hits: this.hits,
+            misses: this.misses,
+            evictions: this.evictions,
+        };
+    }
+    /** Drop all cached vectors. Stats counters are preserved. */
+    clear() {
+        this.vectors.clear();
+    }
+    refresh(key, vector) {
+        // Map insertion order doubles as the LRU order.
+        this.vectors.delete(key);
+        this.vectors.set(key, vector);
+    }
+    store(key, vector) {
+        // Defensive copy in — callers can't mutate the cached vector.
+        this.vectors.set(key, vector.slice());
+        while (this.vectors.size > this.maxEntries) {
+            const oldest = this.vectors.keys().next().value;
+            this.vectors.delete(oldest);
+            this.evictions += 1;
+        }
+    }
+    async embedSequential(texts, signal) {
+        const vectors = [];
+        for (const text of texts) {
+            vectors.push(await this.inner.embed({ text, ...(signal ? { signal } : {}) }));
+        }
+        return vectors;
+    }
+}
+/** Factory sugar — `embeddingCache(embedder)` reads like the built-ins. */
+export function embeddingCache(inner, options = {}) {
+    return new EmbeddingCache(inner, options);
+}
+//# sourceMappingURL=cache.js.map

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

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

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

@@ -0,0 +1,32 @@
+/**
+ * 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 { DEFAULT_INFLUENCE_WEIGHTS, DEFAULT_MARGIN_THRESHOLD, DEFAULT_PERSISTENCE_THRESHOLD, } from './types.js';
+export { contentHash, EmbeddingCache, embeddingCache, } from './cache.js';
+export { adaptWeights, averageRelevancy, compositeScore, finalAnswerSimilarity, persistence, scoreInfluence, structuralProximity, } from './signals.js';
+export { pairwiseSimilarity } from './similarity.js';
+export { scoreMargin } from './margin.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/influence-core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAiBH,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,YAAY,CAAC;AAEpB,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,GAEpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAA+B,MAAM,iBAAiB,CAAC;AAElF,OAAO,EAAE,WAAW,EAAwB,MAAM,aAAa,CAAC"}

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":"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"}

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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"}