@evomap/evolver-core 2.0.0-beta.0

package/dist/ops/recall.d.ts

@@ -0,0 +1,65 @@
+/** A minimal session turn shape (decoupled from the runtime-adapter NormalizedTurn so core needs no adapter import). */
+export interface RecallTurn {
+    /** 'assistant' = the agent's own output — the only place "the agent applied the strategy" can show. */
+    role: string;
+    text: string;
+}
+/** The distinctive content of an injected gene that recall is checked against. */
+export interface GeneRecallInput {
+    geneId: string;
+    /** The gene's learned strategy steps — the strongest recall evidence when their distinctive terms reappear. */
+    strategy?: readonly string[];
+    /** The gene's one-line summary (secondary evidence). */
+    summary?: string;
+}
+export type RecallVerdict = 'used' | 'unused' | 'unknown';
+/** root_events type for an OBSERVED recall verdict (#274): derived from a session transcript (not agent self-report),
+ *  so the experience loop learns which injected/fetched genes were actually applied. Distinct from the reuse-outcome
+ *  events (which record whether a reused gene WORKED) — recall records whether it was USED at all. */
+export declare const VALUE_RECALL_EVENT = "value.recall";
+/** Payload of a `value.recall` root_event: one gene's observed recall verdict for a session. */
+export interface RecallEventPayload {
+    geneId: string;
+    recalled: RecallVerdict;
+    /** Fraction of the gene's distinctive terms found in the agent's output, in [0,1]. */
+    score: number;
+    /** The session this verdict was observed in (transcript-derived), for idempotency + attribution. */
+    sessionId?: string;
+}
+export interface GeneRecallResult {
+    geneId: string;
+    /** used = the agent's output carries the gene's distinctive terms; unused = injected but ~no overlap;
+     *  unknown = the gene has no distinctive content OR the session has no agent turns to judge against. */
+    recalled: RecallVerdict;
+    /** Fraction of the gene's distinctive terms that appear in the agent's output, in [0,1]. */
+    score: number;
+    /** The distinctive terms that were found in the agent's output (for explainability / audit). */
+    matched: string[];
+}
+export interface RecallOptions {
+    /** Minimum score to call a gene `used`. Default 0.3 — a third of the distinctive terms reappearing is a
+     *  deliberate, conservative bar (above incidental single-word coincidence, below demanding verbatim echo). */
+    threshold?: number;
+    /** Drop terms at or below this length before matching (kills articles/operators that overlap by chance). Default 3. */
+    minTermLength?: number;
+}
+/**
+ * Decide whether an injected gene was recalled by the agent in a session. Pure: looks only at the gene's
+ * distinctive terms (strategy + summary) and whether they reappear in the agent's OWN turns. We check assistant
+ * turns specifically — the strategy text was injected into the prompt (user side), so finding it echoed in the
+ * agent's output is the evidence that the agent actually carried it out, not just that we put it there.
+ */
+export declare function verifyGeneRecall(gene: GeneRecallInput, turns: readonly RecallTurn[], opts?: RecallOptions): GeneRecallResult;
+/** Verify a batch of injected genes against one session's turns (the inject-attribution → recall closure). */
+export declare function verifyInjectedGenes(genes: readonly GeneRecallInput[], turns: readonly RecallTurn[], opts?: RecallOptions): GeneRecallResult[];
+/** Operator-facing rollup of a batch recall check. `pruneCandidates` are genes judged 'unused' (injected but the
+ *  agent did not echo their strategy) — the ones that keep paying prompt budget for no observed effect. Never
+ *  includes 'unknown' (no agent output / no distinctive terms — not judgeable, so not a prune signal). */
+export interface RecallSummary {
+    total: number;
+    used: number;
+    unused: number;
+    unknown: number;
+    pruneCandidates: string[];
+}
+export declare function summarizeRecall(results: readonly GeneRecallResult[]): RecallSummary;

package/dist/ops/recall.js

@@ -0,0 +1,152 @@
+// Recall verification (v1 gap: recallVerifier) — the missing other half of the inject attribution rail.
+//
+// The `value.inject` event records WHICH genes were injected into a SessionStart prompt, but the ledger is
+// "attribution-only": it never checks whether the agent ACTUALLY used the injected gene, so an injected-but-
+// ignored gene looks the same as an injected-and-applied one. That makes inject a permanently weak signal and
+// lets dead genes ride along, taxing the prompt budget for nothing.
+//
+// This is the verification primitive: given a gene's distinctive content and the session's turns, decide
+// whether the gene was RECALLED (its strategy shows up in the agent's OWN output, i.e. the agent acted on it).
+// It is PURE and deterministic — no live agent, no fs/clock — so it is fully unit-testable with fixtures, and it
+// reads only data that already exists (the gene record + the session transcript turns). Wiring it onto the
+// experience loop (emit a `value.recall` enrichment, prune never-recalled genes) is a separate, later slice; this
+// module is just the decision function so the heuristic can be reviewed and tested in isolation first.
+/** root_events type for an OBSERVED recall verdict (#274): derived from a session transcript (not agent self-report),
+ *  so the experience loop learns which injected/fetched genes were actually applied. Distinct from the reuse-outcome
+ *  events (which record whether a reused gene WORKED) — recall records whether it was USED at all. */
+export const VALUE_RECALL_EVENT = 'value.recall';
+// Common English + Chinese-pipeline filler that would create spurious overlap. Intentionally small: the goal is
+// to remove obvious noise, not to do real NLP. Anything not filtered is fine — it only raises the matching bar.
+const STOPWORDS = new Set([
+    'the', 'and', 'for', 'with', 'that', 'this', 'then', 'from', 'into', 'your', 'you', 'use', 'using', 'used',
+    'when', 'will', 'should', 'must', 'have', 'has', 'are', 'was', 'were', 'not', 'but', 'all', 'any', 'can',
+    'add', 'set', 'get', 'run', 'fix', 'via', 'per', 'its', 'it', 'a', 'an', 'to', 'of', 'in', 'on', 'or', 'is',
+]);
+// Light suffix stemmer so an inflected paraphrase still counts as recall ("cleared"→"clear", "retried"→"retry",
+// "retrying"→"retry", "cookies"→"cookie"). Deliberately tiny — over-merging only widens matches slightly and the
+// score threshold absorbs it; the alternative (exact match) misses the common case where the agent re-tenses the
+// strategy verbs, which is exactly what "the agent applied it" looks like.
+function stem(t) {
+    if (t.length > 4 && t.endsWith('ied'))
+        return `${t.slice(0, -3)}y`; // tried/retried → try/retry (verb form)
+    if (t.length > 5 && t.endsWith('ing'))
+        return t.slice(0, -3); // retrying → retry
+    if (t.length > 4 && t.endsWith('ed'))
+        return t.slice(0, -2); // cleared → clear
+    // Plural -s: strip only the trailing 's' for a normal plural (cookies → cookie, sessions → session). 'es' is two
+    // real letters ONLY after a sibilant (boxes → box, matches → match); elsewhere stripping 'es' over-strips
+    // (cookies → cooki) and false-marks a plural paraphrase as unused (Bugbot), so gate the -es strip on a sibilant.
+    // NOTE: a y→ies plural (retries → retry) is NOT handled — a tiny stemmer can't tell it from cookie+s; the verb
+    // forms (retried/retrying) cover that gene, and the score threshold absorbs the occasional plural-noun miss.
+    if (t.length > 4 && /(?:s|x|z|ch|sh)es$/.test(t))
+        return t.slice(0, -2);
+    // Plural -s, but NOT a singular lemma ending in 's': -ss (process/class), -us (focus/status/bonus), -is
+    // (analysis/basis/crisis) are singular and must keep their 's', else gene "focus" stems to "focu" while the
+    // agent's "focused" stems to "focus" and a real recall is missed (Bugbot; NB its "process" example was wrong —
+    // process ends -ss, already excluded). Rare -us/-is plurals (menus/skis) lose a strip; acceptably uncommon.
+    if (t.length > 4 && t.endsWith('s') && !/(?:ss|us|is)$/.test(t))
+        return t.slice(0, -1);
+    return t;
+}
+// A doubled-consonant -ing (committing→committ) hides the base verb (commit). We CANNOT destructively undouble in
+// stem() — "calling"→"call" already matches and undoubling would wrongly break it to "cal" (regressing
+// call/press/pass/fall/fill, verified). So instead, ONLY on the agent side, ADD the undoubled form as an EXTRA
+// accepted variant: "committing" contributes {committ, commit} — "committ" is kept and "commit" is gained, nothing
+// is lost (Bugbot -ing finding; note retrying→retry was never wrong). The variant is added by distinctiveTerms only
+// when it clears minLen (so "calling" keeps "call" but the sub-minLen "cal" is dropped — see there).
+function ingUndoubledVariant(raw, stemmed) {
+    if (raw.length <= 5 || !raw.endsWith('ing') || stemmed.length < 3)
+        return null;
+    const last = stemmed[stemmed.length - 1];
+    if (last === stemmed[stemmed.length - 2] && /[bcdfghjklmnpqrstvwxz]/.test(last))
+        return stemmed.slice(0, -1);
+    return null;
+}
+// Undouble an already-stemmed token (committ→commit, wrapp→wrap) for MATCH-TIME comparison only. The agent-side
+// expansion above handles "agent gerund vs gene base"; this handles the mirror — a GENE gerund (committing→committ)
+// vs an agent BASE (commit) — without adding a second gene term (which would inflate the recall denominator).
+// "commit" base stems stay single-consonant so they return null; a genuine doubled base like "call"→"cal" only ever
+// produces a variant the agent never emits, so it cannot create a false match.
+function undoubledStem(s) {
+    if (s.length < 4)
+        return null;
+    const last = s[s.length - 1];
+    if (last === s[s.length - 2] && /[bcdfghjklmnpqrstvwxz]/.test(last))
+        return s.slice(0, -1);
+    return null;
+}
+/**
+ * Lowercase + split on non-word-ish boundaries → distinctive STEMMED terms (stopwords + short tokens dropped,
+ * deduped). With expandIng, also emits the undoubled -ing variant (agent side only) so a doubled-consonant
+ * gerund still matches the base-verb gene term, without the destructive undouble that would regress call/press.
+ */
+function distinctiveTerms(text, minLen, expandIng = false) {
+    const out = new Set();
+    for (const raw of text.toLowerCase().split(/[^a-z0-9_]+/)) {
+        if (raw.length <= minLen)
+            continue;
+        if (STOPWORDS.has(raw))
+            continue;
+        const s = stem(raw);
+        // A stem that collapses onto a stopword (fixing→fix, adding→add) is not distinctive, and the bare stopword
+        // (fix/add) is dropped on the OTHER side (both stopword AND <=minLen), so keeping it here scores a phantom
+        // miss for one side only. Drop stopword stems so the gene and agent sides agree (Bugbot).
+        if (STOPWORDS.has(s))
+            continue;
+        out.add(s);
+        if (expandIng) {
+            const u = ingUndoubledVariant(raw, s);
+            // Keep the undouble variant only when it is itself a distinctive term: length > minLen and not a stopword.
+            // A <=minLen undouble (calling→cal, running→run) is intentionally dropped — gene terms are never that short
+            // for a doubled-consonant base (the gene side yields "commit"/"wrap", not "run"), so it could match nothing.
+            if (u && u.length > minLen && !STOPWORDS.has(u))
+                out.add(u);
+        }
+    }
+    return out;
+}
+/**
+ * Decide whether an injected gene was recalled by the agent in a session. Pure: looks only at the gene's
+ * distinctive terms (strategy + summary) and whether they reappear in the agent's OWN turns. We check assistant
+ * turns specifically — the strategy text was injected into the prompt (user side), so finding it echoed in the
+ * agent's output is the evidence that the agent actually carried it out, not just that we put it there.
+ */
+export function verifyGeneRecall(gene, turns, opts = {}) {
+    const threshold = opts.threshold ?? 0.3;
+    const minLen = opts.minTermLength ?? 3;
+    const geneText = [...(gene.strategy ?? []), gene.summary ?? ''].join(' ');
+    const terms = distinctiveTerms(geneText, minLen);
+    const agentTurns = turns.filter((t) => t.role === 'assistant');
+    // Cannot judge → unknown (never a false 'unused'): EITHER the gene has no distinctive content to look for, OR
+    // there is no agent output at all to judge against. Gate on the PRESENCE of agent turns, not on whether they
+    // yielded distinctive terms (Bugbot): an agent turn that exists but stems to nothing (stopword-only, or only
+    // dropped short tokens like "401 ok") IS judgeable — the agent produced output that does not carry the gene,
+    // i.e. 'unused', not 'unknown'. Conflating the two blurs the signal the downstream value.recall / pruning needs.
+    if (terms.size === 0 || agentTurns.length === 0) {
+        return { geneId: gene.geneId, recalled: 'unknown', score: 0, matched: [] };
+    }
+    const agentTerms = distinctiveTerms(agentTurns.map((t) => t.text).join(' \n '), minLen, true); // expandIng: agent side
+    // A gene term matches when the agent set has it directly, OR has its undoubled base — so a gene gerund
+    // ("committing"→"committ") still matches an agent base ("commit"). One match per gene term, denominator unchanged.
+    const matched = [...terms].filter((t) => {
+        if (agentTerms.has(t))
+            return true;
+        const u = undoubledStem(t);
+        return u !== null && agentTerms.has(u);
+    });
+    const score = matched.length / terms.size;
+    return { geneId: gene.geneId, recalled: score >= threshold ? 'used' : 'unused', score, matched };
+}
+/** Verify a batch of injected genes against one session's turns (the inject-attribution → recall closure). */
+export function verifyInjectedGenes(genes, turns, opts) {
+    return genes.map((g) => verifyGeneRecall(g, turns, opts));
+}
+export function summarizeRecall(results) {
+    return {
+        total: results.length,
+        used: results.filter((r) => r.recalled === 'used').length,
+        unused: results.filter((r) => r.recalled === 'unused').length,
+        unknown: results.filter((r) => r.recalled === 'unknown').length,
+        pruneCandidates: results.filter((r) => r.recalled === 'unused').map((r) => r.geneId),
+    };
+}

package/dist/ops/reuseOutcomes.d.ts

@@ -0,0 +1,68 @@
+/** root_events type appended for a NON-success MCP reuse-result — the negative half of the keep/prune signal. */
+export declare const VALUE_REUSE_OUTCOME_EVENT = "value.reuse_outcome";
+/** The negative reuse outcomes an agent can self-report (success is recorded as `value.reuse_hit`, not here). */
+export type ReuseNegativeOutcome = 'failed' | 'mismatched' | 'stale' | 'unsafe';
+/** Payload of a `value.reuse_outcome` root_event. */
+export interface ReuseOutcomePayload {
+    assetId: string;
+    cycleId: string;
+    outcome: ReuseNegativeOutcome;
+}
+/** A minimal root_event view this module reads (matches the events module's ReportEvent shape; declared locally so
+ *  ops stays decoupled from the events module, mirroring valueLedger's LedgerRootEvent). */
+export interface ReuseOutcomeEvent {
+    type: string;
+    payload?: Record<string, unknown>;
+}
+export interface GeneReuseOutcome {
+    assetId: string;
+    /** Successful reuses (from `value.reuse_hit`). */
+    success: number;
+    /** Non-success reuses (from `value.reuse_outcome`). */
+    negative: number;
+    /** Per-outcome breakdown of the negatives. */
+    byOutcome: Record<ReuseNegativeOutcome, number>;
+}
+export interface ReuseOutcomeSummary {
+    /** Total reuse signals considered (success + negative). */
+    total: number;
+    /** Per-gene rollup, sorted by negative desc then assetId. */
+    perGene: GeneReuseOutcome[];
+    /** Genes reused but NEVER successfully (negative>0 AND success===0) — the strongest cross-runtime prune signal.
+     *  Mirrors summarizeRecall.pruneCandidates, but sourced from reuse outcomes across every runtime. */
+    pruneCandidates: string[];
+}
+/**
+ * Roll reuse signals up per gene from root_events: SUCCESS from `value.reuse_hit`, the negative verdicts from
+ * `value.reuse_outcome`. Pure; deterministic ordering. Unknown/garbled payloads are skipped, never counted.
+ */
+export declare function summarizeReuseOutcomes(events: readonly ReuseOutcomeEvent[]): ReuseOutcomeSummary;
+/** Raw reuse tallies for one gene-id, kept as COUNTS (not a pre-collapsed sentiment) so a consumer that knows a
+ *  gene's multiple ids can COMBINE them before computing sentiment (#268 Bugbot: events for one gene can split
+ *  across its logical id and its content asset_id — averaging two sentiments would skew; summing counts is right). */
+export interface ReuseCounts {
+    success: number;
+    negative: number;
+}
+/**
+ * Map a reuse-outcome summary to per-id reuse COUNTS (#268 phase 1) — the input to a SOFT selection re-order.
+ * Keyed by the id the events recorded (which may be a logical geneId OR a content asset_id), so the store-aware
+ * consumer (candidateAssembly) can fold all of a gene's ids together via `reuseSentiment` before ranking. Only ids
+ * with at least one reuse signal are included. Pure; the cycle injects it via RunCycleOptions.reuseOutcomes.
+ */
+export declare function reuseCountsFromSummary(summary: ReuseOutcomeSummary): Map<string, ReuseCounts>;
+/** Net reuse sentiment in [-1, 1] from combined counts: (success − negative) / (success + negative). all-success
+ *  → +1, all-negative → −1, balanced → 0. Zero total → 0. The WEIGHT/clamping that bounds its selection influence
+ *  lives in geneSelection (it can never override the hard trust/review/ban gates, which run before scoring). */
+export declare function reuseSentiment(counts: ReuseCounts): number;
+/** Weight of an OBSERVED recall verdict (#274 slice 3) relative to a reported reuse outcome. < 1 because a
+ *  transcript-observed `used`/`unused` is weaker evidence than an agent (or daemon) explicitly reporting that a
+ *  reuse WORKED or FAILED — being applied/ignored is softer than working/breaking. */
+export declare const RECALL_WEIGHT = 0.5;
+/**
+ * Per-gene reuse COUNTS contributed by OBSERVED `value.recall` events (#274 slice 3): `used` → success, `unused` →
+ * negative, each weighted RECALL_WEIGHT (weaker than a reported reuse outcome); `unknown` is ignored. Keyed by the
+ * recall payload's geneId. Pure. Merged into the reuse-outcome counts upstream so recall SOFTLY re-orders selection
+ * — it never reaches the quarantine path (summarizeReuseOutcomes reads only the reuse-outcome events, not recall).
+ */
+export declare function recallCountsFromEvents(events: readonly ReuseOutcomeEvent[]): Map<string, ReuseCounts>;

package/dist/ops/reuseOutcomes.js

@@ -0,0 +1,126 @@
+// Reuse-outcome accounting (#268 slice C) — the cross-runtime keep/prune SIGNAL, derived purely from root_events.
+//
+// Slice A/B made `evolver_asset_reuse_result` work in every mode and emit a `value.reuse_hit` on SUCCESS (the $
+// rail). This module records the OTHER outcomes too and rolls the whole distribution up per gene, so the question
+// "is this gene worth keeping?" can be answered from EVERY runtime's reuse (MCP-native agents included), not only
+// from the hook/daemon transcript-recall path. It is the foreign-agent analogue of summarizeRecall.
+//
+// PURE + read-only: a function over already-emitted events. It does NOT actuate (it never mutates gene health,
+// selection weight, or the store) — wiring this signal into selection/health is a separate, explicitly-gated step
+// (it touches the keep/prune actuator). This module only makes the signal visible and accountable.
+//
+// Two event sources (decoupled by design): a SUCCESS reuse credits the $ ledger via `value.reuse_hit` (slice A/B),
+// so success is counted from THAT; the non-success verdicts (failed/mismatched/stale/unsafe) are recorded as
+// `value.reuse_outcome`. Reading both yields the full per-gene success-vs-negative picture without a redundant
+// second event on the success path.
+import { VALUE_REUSE_HIT_EVENT } from './valueLedger.js';
+import { VALUE_RECALL_EVENT } from './recall.js';
+/** root_events type appended for a NON-success MCP reuse-result — the negative half of the keep/prune signal. */
+export const VALUE_REUSE_OUTCOME_EVENT = 'value.reuse_outcome';
+const NEG = ['failed', 'mismatched', 'stale', 'unsafe'];
+function assetIdOf(e) {
+    const id = e.payload?.['assetId'];
+    return typeof id === 'string' && id.length > 0 ? id : null;
+}
+/**
+ * Roll reuse signals up per gene from root_events: SUCCESS from `value.reuse_hit`, the negative verdicts from
+ * `value.reuse_outcome`. Pure; deterministic ordering. Unknown/garbled payloads are skipped, never counted.
+ */
+export function summarizeReuseOutcomes(events) {
+    const agg = new Map();
+    const get = (assetId) => {
+        let g = agg.get(assetId);
+        if (!g) {
+            g = { assetId, success: 0, negative: 0, byOutcome: { failed: 0, mismatched: 0, stale: 0, unsafe: 0 } };
+            agg.set(assetId, g);
+        }
+        return g;
+    };
+    let total = 0;
+    for (const e of events) {
+        if (e.type === VALUE_REUSE_HIT_EVENT) {
+            const assetId = assetIdOf(e);
+            if (!assetId)
+                continue;
+            get(assetId).success += 1;
+            total += 1;
+        }
+        else if (e.type === VALUE_REUSE_OUTCOME_EVENT) {
+            const assetId = assetIdOf(e);
+            const outcome = e.payload?.['outcome'];
+            if (!assetId || typeof outcome !== 'string' || !NEG.includes(outcome))
+                continue;
+            const g = get(assetId);
+            g.negative += 1;
+            g.byOutcome[outcome] += 1;
+            total += 1;
+        }
+    }
+    const perGene = [...agg.values()].sort((a, b) => b.negative - a.negative || (a.assetId < b.assetId ? -1 : a.assetId > b.assetId ? 1 : 0));
+    const pruneCandidates = perGene.filter((g) => g.negative > 0 && g.success === 0).map((g) => g.assetId);
+    return { total, perGene, pruneCandidates };
+}
+/**
+ * Map a reuse-outcome summary to per-id reuse COUNTS (#268 phase 1) — the input to a SOFT selection re-order.
+ * Keyed by the id the events recorded (which may be a logical geneId OR a content asset_id), so the store-aware
+ * consumer (candidateAssembly) can fold all of a gene's ids together via `reuseSentiment` before ranking. Only ids
+ * with at least one reuse signal are included. Pure; the cycle injects it via RunCycleOptions.reuseOutcomes.
+ */
+export function reuseCountsFromSummary(summary) {
+    const out = new Map();
+    for (const g of summary.perGene) {
+        if (g.success + g.negative <= 0)
+            continue;
+        out.set(g.assetId, { success: g.success, negative: g.negative });
+    }
+    return out;
+}
+/** Net reuse sentiment in [-1, 1] from combined counts: (success − negative) / (success + negative). all-success
+ *  → +1, all-negative → −1, balanced → 0. Zero total → 0. The WEIGHT/clamping that bounds its selection influence
+ *  lives in geneSelection (it can never override the hard trust/review/ban gates, which run before scoring). */
+export function reuseSentiment(counts) {
+    const denom = counts.success + counts.negative;
+    return denom > 0 ? (counts.success - counts.negative) / denom : 0;
+}
+/** Weight of an OBSERVED recall verdict (#274 slice 3) relative to a reported reuse outcome. < 1 because a
+ *  transcript-observed `used`/`unused` is weaker evidence than an agent (or daemon) explicitly reporting that a
+ *  reuse WORKED or FAILED — being applied/ignored is softer than working/breaking. */
+export const RECALL_WEIGHT = 0.5;
+/**
+ * Per-gene reuse COUNTS contributed by OBSERVED `value.recall` events (#274 slice 3): `used` → success, `unused` →
+ * negative, each weighted RECALL_WEIGHT (weaker than a reported reuse outcome); `unknown` is ignored. Keyed by the
+ * recall payload's geneId. Pure. Merged into the reuse-outcome counts upstream so recall SOFTLY re-orders selection
+ * — it never reaches the quarantine path (summarizeReuseOutcomes reads only the reuse-outcome events, not recall).
+ */
+export function recallCountsFromEvents(events) {
+    // Collapse to ONE verdict per (session, gene) first: within a session `used` is terminal and WINS over an earlier
+    // provisional `unused`, so a within-session upgrade is not double-counted (it would otherwise cancel to neutral —
+    // #274 Bugbot). Then accumulate ACROSS sessions, so a gene reused (un)successfully in many sessions adds up.
+    const perSession = new Map(); // key: `${sessionId}|${geneId}` (per-session collapse)
+    const geneOf = new Map();
+    for (const e of events) {
+        if (e.type !== VALUE_RECALL_EVENT)
+            continue;
+        const id = e.payload?.['geneId'];
+        const recalled = e.payload?.['recalled'];
+        if (typeof id !== 'string' || (recalled !== 'used' && recalled !== 'unused'))
+            continue;
+        const sid = typeof e.payload?.['sessionId'] === 'string' ? e.payload['sessionId'] : '';
+        const key = `${sid}|${id}`;
+        if (perSession.get(key) === 'used')
+            continue; // terminal for this session
+        perSession.set(key, recalled === 'used' ? 'used' : 'unused');
+        geneOf.set(key, id);
+    }
+    const out = new Map();
+    for (const [key, verdict] of perSession) {
+        const id = geneOf.get(key);
+        const c = out.get(id) ?? { success: 0, negative: 0 };
+        if (verdict === 'used')
+            c.success += RECALL_WEIGHT;
+        else
+            c.negative += RECALL_WEIGHT;
+        out.set(id, c);
+    }
+    return out;
+}

package/dist/ops/savingsCore.d.ts

@@ -0,0 +1,47 @@
+export declare const SAVINGS_SPEC_VERSION = "0.3.0";
+export declare const ENTROPY_EVENT_TOKENS_EST: Readonly<{
+    dedup_quarantine: 12000;
+    dedup_warning: 3600;
+    hub_search_hit: 8000;
+    hub_search_miss: 0;
+    fetch_reuse: 4000;
+}>;
+export declare const FETCH_USAGE_TOKENS_EST: Readonly<{
+    Gene: 1500;
+    Capsule: 3500;
+    EvolutionEvent: 0;
+}>;
+export declare const REUSE_ESTIMATOR: Readonly<{
+    derive_base_tokens: 120000;
+    tokens_per_changed_line: 800;
+    derive_cap_tokens: 600000;
+    typical_changed_lines: 75;
+    reference_saving_fraction: 0.4;
+}>;
+export declare const USD_PER_M_TOKENS_BLENDED = 9;
+export declare const CACHE_READ_SAVED_USD_PER_M_TOKENS: Readonly<{
+    anthropic: 2.7;
+}>;
+export declare const SAVINGS_BASIS_PRECEDENCE: readonly string[];
+export declare function measuredSavings(rawTokens: number, optimizedTokens: number): {
+    tokens_saved: number;
+    savings_pct: number;
+};
+export declare function rolloutFoldPct(nAvgRollouts: number): number;
+export interface EntropyEvent {
+    type: string;
+    count?: number;
+    tokensEstSaved?: number | null;
+}
+export declare function entropyTotal(events: readonly EntropyEvent[]): {
+    total_tokens_saved: number;
+    total_events: number;
+};
+export declare function fetchUsageEstimate(byType: Record<string, number>): number;
+export declare function reuseEstimate(blastRadiusLines: number | null | undefined, mode?: string): {
+    tokens_saved: number;
+    basis: 'estimated_blast_radius' | 'estimated_default';
+};
+export declare function hitRatePct(hits: number, misses: number): number;
+export declare function usdSaved(tokens: number): number;
+export declare function cacheSavedUsd(provider: string, cacheReadTokens: number): number;

package/dist/ops/savingsCore.js

@@ -0,0 +1,112 @@
+// savings-core — token-savings formula, TS implementation for evolver-v2.
+//
+// Single source of truth: EvoMap/savings-core (spec v0.3.0). The constants and formula semantics
+// here MUST match the repo-root vendored copies (conformance/savings-core/constants.json) and
+// reproduce conformance/savings-core/golden-vectors.json bit-for-bit — savingsCore.test.ts is the
+// gate (it reads the vendored files at runtime, so this module stays free of cross-rootDir JSON
+// imports), and savings-core's daily drift-check locks the vendored copies to upstream. To change a
+// coefficient: change savings-core first, regenerate vectors there, bump spec_version, then
+// re-vendor here AND in evomap-hub / evomap-private / evox-online-deck / evomap-desktop / evox /
+// evolver-private-dev / evolver-v2-enterprise-dev.
+//
+// Core purity contract holds: no I/O, no Date.now/Math.random — pure functions over numbers.
+export const SAVINGS_SPEC_VERSION = '0.3.0';
+// E1 — per-event estimated tokens saved.
+export const ENTROPY_EVENT_TOKENS_EST = Object.freeze({
+    dedup_quarantine: 12_000,
+    dedup_warning: 3_600,
+    hub_search_hit: 8_000,
+    hub_search_miss: 0,
+    fetch_reuse: 4_000,
+});
+// E2 — node-level fetch-usage estimates, per asset type.
+export const FETCH_USAGE_TOKENS_EST = Object.freeze({
+    Gene: 1_500,
+    Capsule: 3_500,
+    EvolutionEvent: 0,
+});
+// E3 — blast-radius reuse estimator parameters (anchor: 120000 + 75×800 = the legacy 180k blanket).
+export const REUSE_ESTIMATOR = Object.freeze({
+    derive_base_tokens: 120_000,
+    tokens_per_changed_line: 800,
+    derive_cap_tokens: 600_000,
+    typical_changed_lines: 75,
+    reference_saving_fraction: 0.4,
+});
+// U1 — blended $/1M tokens across input+output.
+export const USD_PER_M_TOKENS_BLENDED = 9.0;
+// C1 — $ saved per 1M prompt-cache-read tokens, per provider.
+export const CACHE_READ_SAVED_USD_PER_M_TOKENS = Object.freeze({
+    anthropic: 2.7,
+});
+export const SAVINGS_BASIS_PRECEDENCE = Object.freeze(['measured', 'cost_index', 'estimator']);
+const round2 = (x) => Math.round((x + Number.EPSILON) * 100) / 100;
+const round4 = (x) => Math.round((x + Number.EPSILON) * 10000) / 10000;
+const coerce = (x) => Math.max(0, Math.round(Number(x) || 0));
+// R1 — measured savings from a raw/optimized token pair (preferred basis).
+export function measuredSavings(rawTokens, optimizedTokens) {
+    const raw = coerce(rawTokens);
+    const optimized = coerce(optimizedTokens);
+    const saved = Math.max(0, raw - optimized);
+    const rate = raw > 0 ? Math.max(0, 1 - optimized / raw) : 0;
+    return { tokens_saved: saved, savings_pct: round2(rate * 100) };
+}
+// R2 — rollout-folding rate.
+export function rolloutFoldPct(nAvgRollouts) {
+    const n = Number(nAvgRollouts) || 0;
+    return n >= 1 ? round2((1 - 1 / n) * 100) : 0;
+}
+// E1 — aggregate estimated savings over entropy events (unknown types skipped).
+export function entropyTotal(events) {
+    let tokens = 0;
+    let count = 0;
+    for (const e of events ?? []) {
+        let per;
+        if (e.tokensEstSaved !== undefined && e.tokensEstSaved !== null) {
+            per = coerce(e.tokensEstSaved);
+        }
+        else {
+            const coeff = ENTROPY_EVENT_TOKENS_EST[e.type];
+            if (coeff === undefined)
+                continue;
+            per = coeff;
+        }
+        const n = coerce(e.count ?? 1);
+        tokens += per * n;
+        count += n;
+    }
+    return { total_tokens_saved: tokens, total_events: count };
+}
+// E2 — node fetch-usage estimate; unknown asset types contribute 0.
+export function fetchUsageEstimate(byType) {
+    let sum = 0;
+    for (const [type, n] of Object.entries(byType ?? {})) {
+        sum += (FETCH_USAGE_TOKENS_EST[type] ?? 0) * coerce(n);
+    }
+    return sum;
+}
+// E3 — blast-radius reuse estimator (the `estimator` basis fallback).
+export function reuseEstimate(blastRadiusLines, mode) {
+    const n = Number(blastRadiusLines);
+    const valid = Number.isFinite(n) && n > 0;
+    const basis = valid ? 'estimated_blast_radius' : 'estimated_default';
+    const lines = valid ? n : REUSE_ESTIMATOR.typical_changed_lines;
+    const full = Math.min(REUSE_ESTIMATOR.derive_base_tokens + lines * REUSE_ESTIMATOR.tokens_per_changed_line, REUSE_ESTIMATOR.derive_cap_tokens);
+    const tokens = Math.round(mode === 'reference' ? full * REUSE_ESTIMATOR.reference_saving_fraction : full);
+    return { tokens_saved: tokens, basis };
+}
+// H1 — search hit rate as a 2-dp percentage.
+export function hitRatePct(hits, misses) {
+    const h = coerce(hits);
+    const m = coerce(misses);
+    return h + m > 0 ? round2((h / (h + m)) * 100) : 0;
+}
+// U1 — USD value of saved tokens at the blended rate.
+export function usdSaved(tokens) {
+    return round2((coerce(tokens) / 1_000_000) * USD_PER_M_TOKENS_BLENDED);
+}
+// C1 — prompt-cache savings in USD (4 dp); unknown providers contribute 0.
+export function cacheSavedUsd(provider, cacheReadTokens) {
+    const rate = CACHE_READ_SAVED_USD_PER_M_TOKENS[provider] ?? 0;
+    return round4((coerce(cacheReadTokens) / 1_000_000) * rate);
+}