@evomap/evolver-core 2.0.0-beta.0

package/dist/ops/valueLedger.js

@@ -0,0 +1,238 @@
+// Value ledger (#112) — "how many tokens did evolver save you" as a PURE, event-sourced, append-only ledger.
+// The raw material already exists but no code turns it into savings: the proxy captures per-turn LLM usage
+// (route decisions: original_model vs chosen_model) and reuse-before-solve hits land a replayable root_event.
+// This module DERIVES value entries from that material — it never measures, mutates, pays, or settles anything.
+//
+// HARD BOUNDARY (core purity, #112): zero hub / zero economic decision / zero governance. The ledger is a
+// read-only accounting view. Prices are INJECTED as a PriceTable (a data interface) — core hardcodes no model
+// price, so a price update is a data-file change, never a core code change. This file does not import the
+// adapter (the adapter reverse-injects prices) and emits no money movement.
+//
+// HONESTY INVARIANT (the user-trust line,呼应 money-safety): `measured` and `estimated` confidence are tracked
+// and reported on SEPARATE rails. There is no code path that folds an estimated number into a measured total.
+// `valueSummary` exposes them as two distinct buckets so a UI can never present an inflated single figure.
+//
+// Determinism: every function here is pure. No Date.now / Math.random — all timestamps come from the event or
+// trace records themselves, so a golden fixture replays byte-for-byte.
+import { ENTROPY_EVENT_TOKENS_EST } from './savingsCore.js';
+/** Build a PriceTable from a plain {model: ModelPrice} map (the shape a JSON data file deserializes to). */
+export function priceTableFromMap(map) {
+    return { priceOf: (model) => map[model] };
+}
+// ── the reuse root_event the ledger derives source=reuse entries from ─────────────────────────────────────
+/** root_events type appended on a reuse-before-solve HIT — the replayable source for source=reuse entries. */
+export const VALUE_REUSE_HIT_EVENT = 'value.reuse_hit';
+// ── the injected gene-injection record (inject source — recorded, NEVER given a savings number) ───────────
+/** root_events type appended when SessionStart injects genes — recorded for outcome attribution only. */
+export const VALUE_INJECT_EVENT = 'value.inject';
+/** Legacy savings-core E1 coefficient for "one cross-node asset reuse". The value ledger no longer uses this
+ *  as a fallback baseline for live `value.reuse_hit` events: without a measured baseline, reuse savings stay
+ *  zero/unknown. Kept exported so savings-core conformance and older consumers can detect spec drift. */
+export const ESTIMATED_SOLVE_FRESH_TOKENS = ENTROPY_EVENT_TOKENS_EST.fetch_reuse;
+function n(v) {
+    const x = Number(v);
+    return Number.isFinite(x) ? x : 0;
+}
+/** USD cost of a usage block under a price (absent price class → 0, never invented). */
+function costOf(price, usage) {
+    if (!price || !usage)
+        return 0;
+    return (n(usage.input_tokens) * n(price.input) +
+        n(usage.output_tokens) * n(price.output) +
+        n(usage.cache_creation_input_tokens) * n(price.cacheCreation) +
+        n(usage.cache_read_input_tokens) * n(price.cacheRead));
+}
+// ── derivation: route (measured) ──────────────────────────────────────────────────────────────────────────
+/**
+ * Derive route-downgrade savings from trace records. A turn saves COST (not tokens) only when the router
+ * actually rewrote the model (`original_model !== chosen_model`, both present): the saving is the price delta
+ * of the SAME usage between the model the client asked for and the cheaper model that ran. Always `measured`
+ * (the usage is real). A turn whose price delta is ≤0 (no cheaper, or model unpriced) contributes nothing.
+ */
+export function deriveRouteEntries(traces, prices) {
+    const out = [];
+    for (const t of traces) {
+        const orig = t.original_model;
+        const chosen = t.chosen_model;
+        if (!orig || !chosen || orig === chosen)
+            continue;
+        const origCost = costOf(prices.priceOf(orig), t.usage);
+        const chosenCost = costOf(prices.priceOf(chosen), t.usage);
+        const saved = origCost - chosenCost;
+        if (!(saved > 0))
+            continue; // routing to an equal/pricier model saves nothing — never record a negative
+        out.push({
+            at: t.ts,
+            source: 'route',
+            tokensSaved: 0, // routing runs the SAME tokens on a cheaper model — it saves money, not tokens
+            costSavedUsd: saved,
+            confidence: 'measured',
+            refs: { originalModel: orig, chosenModel: chosen },
+        });
+    }
+    return out;
+}
+// ── derivation: reuse (measured when the event carries a baseline, else zero/unknown) ─────────────────────
+/**
+ * Derive reuse savings from `value.reuse_hit` root_events. Saving = (baseline solve-fresh tokens) - (actual
+ * fetch tokens), but only when the event carries `baselineTokens` (a real historical average for the signal
+ * class). Without that measured baseline, the entry still records the reuse but keeps tokensSaved/costSavedUsd
+ * at zero so a small-step reuse inside a large task cannot be promoted into fabricated whole-task ROI.
+ * Each entry's refs point at the real `assetId` + `cycleId` from the hit - the audit anchor.
+ */
+export function deriveReuseEntries(events, prices) {
+    const out = [];
+    for (const e of events) {
+        if (e.type !== VALUE_REUSE_HIT_EVENT)
+            continue;
+        const p = (e.payload ?? {});
+        const assetId = typeof p.assetId === 'string' ? p.assetId : '';
+        const cycleId = typeof p.cycleId === 'string' ? p.cycleId : '';
+        if (!assetId || !cycleId)
+            continue; // a reuse entry without its audit anchors is not accountable
+        const fetchTokens = Math.max(0, n(p.fetchTokens));
+        const hasMeasuredBaseline = typeof p.baselineTokens === 'number' && Number.isFinite(p.baselineTokens) && p.baselineTokens > 0;
+        const tokensSaved = hasMeasuredBaseline ? Math.max(0, n(p.baselineTokens) - fetchTokens) : 0;
+        const price = typeof p.model === 'string' ? prices.priceOf(p.model) : undefined;
+        // Value the saved tokens as input-side cost (a conservative single-rail price for a token bundle). When the
+        // model is unpriced/absent, or when there is no measured baseline, cost is 0.
+        const perToken = price ? n(price.input) : 0;
+        const costSavedUsd = tokensSaved * perToken;
+        out.push({
+            at: e.ts,
+            source: 'reuse',
+            tokensSaved,
+            costSavedUsd,
+            confidence: hasMeasuredBaseline ? 'measured' : 'estimated',
+            refs: { assetId, cycleId },
+        });
+    }
+    return out;
+}
+// ── derivation: inject (recorded, NEVER a savings number) ─────────────────────────────────────────────────
+/**
+ * Derive inject records from `value.inject` root_events. Attribution-only: which genes were injected and the
+ * session outcome. tokensSaved / costSavedUsd are ALWAYS 0 (the issue: inject is a weak signal — record it,
+ * never report a savings number). Marked `estimated` so it can never land on the measured rail, and the
+ * summary excludes inject from both savings totals regardless.
+ */
+export function deriveInjectEntries(events) {
+    const out = [];
+    for (const e of events) {
+        if (e.type !== VALUE_INJECT_EVENT)
+            continue;
+        const p = (e.payload ?? {});
+        const geneIds = Array.isArray(p.geneIds) ? p.geneIds.filter((g) => typeof g === 'string') : [];
+        if (geneIds.length === 0)
+            continue;
+        out.push({
+            at: e.ts,
+            source: 'inject',
+            tokensSaved: 0,
+            costSavedUsd: 0,
+            confidence: 'estimated',
+            refs: {
+                geneIds,
+                ...(typeof p.cycleId === 'string' ? { cycleId: p.cycleId } : {}),
+                ...(typeof p.outcome === 'string' ? { outcome: p.outcome } : {}),
+            },
+        });
+    }
+    return out;
+}
+/**
+ * Derive the full set of value entries from trace + root_events, sorted by `at` (stable, ties broken by source
+ * then assetId/models) so the ledger is a deterministic, replayable timeline. Pure: same input → same output,
+ * byte-for-byte. This is the function a `replay` re-runs after discarding the materialized ledger.
+ */
+export function deriveValueEntries(input) {
+    const traces = input.traces ?? [];
+    const events = input.events ?? [];
+    const entries = [
+        ...deriveRouteEntries(traces, input.prices),
+        ...deriveReuseEntries(events, input.prices),
+        ...deriveInjectEntries(events),
+    ];
+    entries.sort((a, b) => {
+        if (a.at !== b.at)
+            return a.at < b.at ? -1 : 1;
+        if (a.source !== b.source)
+            return a.source < b.source ? -1 : 1;
+        const ka = a.refs.assetId ?? a.refs.chosenModel ?? '';
+        const kb = b.refs.assetId ?? b.refs.chosenModel ?? '';
+        return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+    return entries;
+}
+// ── serialization (append-only JSONL, replayable) ─────────────────────────────────────────────────────────
+/** Serialize entries to append-only JSONL (one entry per line). Deterministic given the entries. */
+export function serializeLedger(entries) {
+    return entries.map((e) => JSON.stringify(e)).join('\n') + (entries.length ? '\n' : '');
+}
+/** Parse a ledger JSONL back into entries (the materialized view; the source of truth is still trace+events). */
+export function parseLedger(jsonl) {
+    const out = [];
+    for (const line of jsonl.split('\n')) {
+        const s = line.trim();
+        if (!s)
+            continue;
+        try {
+            out.push(JSON.parse(s));
+        }
+        catch { /* skip a corrupt tail line — replay rebuilds it */ }
+    }
+    return out;
+}
+function emptyBucket() { return { tokensSaved: 0, costSavedUsd: 0, entries: 0 }; }
+/**
+ * Aggregate entries into a ValueSummary over an optional time window. Pure. Measured and estimated are summed
+ * on separate rails by construction — there is deliberately NO branch that adds an estimated entry into the
+ * measured totals (the honesty invariant; a test asserts no such path exists).
+ */
+export function valueSummary(entries, window = {}) {
+    const inWindow = (at) => (window.since === undefined || at >= window.since) && (window.until === undefined || at < window.until);
+    const scoped = entries.filter((e) => inWindow(e.at));
+    const bySource = { route: emptyBucket(), reuse: emptyBucket(), inject: emptyBucket() };
+    const estimated = { totalTokensSaved: 0, totalCostUsd: 0, entries: 0 };
+    let totalTokensSaved = 0;
+    let totalCostUsd = 0;
+    const geneAgg = new Map();
+    const injectAgg = new Map();
+    for (const e of scoped) {
+        const bucket = bySource[e.source];
+        bucket.entries += 1;
+        if (e.confidence === 'measured') {
+            // MEASURED rail — and ONLY the measured rail feeds the headline totals.
+            bucket.tokensSaved += e.tokensSaved;
+            bucket.costSavedUsd += e.costSavedUsd;
+            totalTokensSaved += e.tokensSaved;
+            totalCostUsd += e.costSavedUsd;
+        }
+        else {
+            // ESTIMATED rail — kept wholly separate; never touches bucket.tokensSaved or the totals above.
+            estimated.totalTokensSaved += e.tokensSaved;
+            estimated.totalCostUsd += e.costSavedUsd;
+            estimated.entries += 1;
+        }
+        if (e.source === 'reuse' && e.refs.assetId) {
+            const g = geneAgg.get(e.refs.assetId) ?? { reuses: 0, measuredTokensSaved: 0, estimatedTokensSaved: 0 };
+            g.reuses += 1;
+            if (e.confidence === 'measured')
+                g.measuredTokensSaved += e.tokensSaved;
+            else
+                g.estimatedTokensSaved += e.tokensSaved;
+            geneAgg.set(e.refs.assetId, g);
+        }
+        if (e.source === 'inject' && e.refs.geneIds) {
+            for (const gid of e.refs.geneIds)
+                injectAgg.set(gid, (injectAgg.get(gid) ?? 0) + 1);
+        }
+    }
+    const topGenes = [...geneAgg.entries()]
+        .map(([assetId, v]) => ({ assetId, ...v }))
+        .sort((a, b) => b.reuses - a.reuses || b.measuredTokensSaved - a.measuredTokensSaved || (a.assetId < b.assetId ? -1 : 1));
+    const injectedGenes = [...injectAgg.entries()]
+        .map(([geneId, injections]) => ({ geneId, injections }))
+        .sort((a, b) => b.injections - a.injections || (a.geneId < b.geneId ? -1 : 1));
+    return { totalTokensSaved, totalCostUsd, bySource, estimated, topGenes, injectedGenes, entries: scoped.length };
+}

package/dist/ops/valueOutreach.d.ts

@@ -0,0 +1,70 @@
+import { type ValueSummary, type TraceRecord, type LedgerRootEvent, type PriceTable, type SummaryWindow } from './valueLedger.js';
+/**
+ * Read all proxy trace day-files in `dir` and return the parsed `llm_turn` records as ledger TraceRecords. A
+ * missing dir / unreadable file degrades to [] (the value layer must never crash a long-running daemon over a
+ * stat). Plain `event: 'llm_turn'` lines and encrypted envelopes with a safe `plaintext_summary` are kept; the
+ * structural fields the ledger reads are passed through.
+ */
+export declare function readTraceRecords(dir: string): TraceRecord[];
+export type ValueWindowSpec = '7d' | '30d' | 'all';
+/** Parse a `--window` spec into a SummaryWindow against `now`. `all` → no bound. An unknown spec → 7d (the safe
+ *  default a CLI offers first). The clock is injected so the report is deterministic under test. */
+export declare function windowFromSpec(spec: string | undefined, now: number): SummaryWindow;
+/** Human label for a window spec (for the report/digest header). */
+export declare function windowLabel(spec: string | undefined): string;
+export interface ValueSources {
+    /** Parsed proxy trace records (route source). Default []. */
+    traces?: readonly TraceRecord[];
+    /** Parsed root_events (reuse + inject source). Default []. */
+    events?: readonly LedgerRootEvent[];
+    prices: PriceTable;
+}
+/**
+ * Derive the full ledger then aggregate it over a window — the SINGLE aggregation seam every outreach surface
+ * goes through, so the CLI, the WebUI card and the digest can never disagree (and none of them re-implements the
+ * ledger). Pure given its inputs + window.
+ */
+export declare function loadValueSummary(sources: ValueSources, window?: SummaryWindow): ValueSummary;
+/** Compact integer with thousands separators (deterministic, locale-independent). */
+export declare function fmtInt(n: number): string;
+/** USD with 4 decimals (savings are often sub-cent; never round a real saving to $0.00 silently). */
+export declare function fmtUsd(n: number): string;
+/** Guidance shown when the ledger is empty — never an empty table (#113 acceptance). */
+export declare const VALUE_EMPTY_GUIDANCE: string;
+/**
+ * Render the three-section value report from a summary: (1) savings — measured and estimated on SEPARATE lines,
+ * never a merged total; (2) top reused genes with their reuse counts; (3) source breakdown. Returns the empty
+ * guidance text (not a blank table) when there is nothing to show. Pure: the window label is passed in.
+ */
+export declare function formatValueReport(summary: ValueSummary, windowSpec: string | undefined): string;
+export interface RecapInput {
+    /** Genes injected this session (N). */
+    injectedCount: number;
+    /** Past successes those genes came from (M) — e.g. distinct solidified cycles. Optional. */
+    successCount?: number;
+    /** The summary for the recap window (defaults to last 7 days at the call site). */
+    summary: ValueSummary;
+}
+/**
+ * Build the quiet SessionStart context line. It is intentionally metadata-shaped, non-branded, and non-second-
+ * person so the agent can use injected-memory/value context without reciting Evolver in routine replies. Measured
+ * tokens (X) stay on the trustworthy rail; estimated is emitted ONLY when there is no measured figure, under a
+ * separate key so the two are never conflated. Returns '' when there is nothing honest to say (no injection AND no
+ * savings) — the caller then injects no recap line at all rather than a hollow "saved 0".
+ */
+export declare function buildValueRecap(input: RecapInput): string;
+/** Prefix a reuse-source note onto an injected candidate so the user sees WHERE a ready-made solution came from
+ *  (the reuse hit short-circuited a fresh solve). Pure string composition; the assetId is the audit anchor. */
+export declare function reuseSourceNote(assetId: string): string;
+/**
+ * A digest is only worth sending in a week that produced REAL (measured) value. This is the frequency/quality
+ * gate the issue makes a first-class requirement: "宁可少触达，不可惹人烦". Estimated-only weeks do NOT pass —
+ * an estimate is too weak to justify an unsolicited push.
+ */
+export declare function digestShouldSend(summary: ValueSummary): boolean;
+/**
+ * Build the weekly digest markdown from a summary. Returns null when the zero-measured-value gate fails (the
+ * caller then delivers nothing — no empty digest, ever). measured and estimated stay on separate lines. Pure:
+ * the window label + the period string are passed in so the digest is deterministic.
+ */
+export declare function buildValueDigest(summary: ValueSummary, period: string): string | null;

package/dist/ops/valueOutreach.js

@@ -0,0 +1,244 @@
+// Value outreach (#113) — turn the value ledger's `valueSummary` into something a user actually SEES, layered
+// by intrusiveness: a pull-only report (`evolver value` / WebUI card), a quiet session-start context line, and a
+// frequency-capped weekly digest (the observer bus's first built-in observer).
+//
+// HARD BOUNDARY (core purity, mirrors the ledger): this module reads trace day-files + root_events off disk and
+// FORMATS the already-derived summary — it never re-derives savings, never prices anything (prices are injected
+// as a PriceTable, same as the ledger), never touches the hub / money / governance. It is a presentation layer
+// over `valueSummary`, nothing more.
+//
+// HONESTY INVARIANT (inherited, non-negotiable): measured and estimated savings are presented on SEPARATE rails
+// in every surface here. There is no code path that folds an estimated number into a measured one — the report,
+// the recap and the digest each print two distinct figures. A test pins that no surface ever merges them.
+//
+// Determinism: the FORMATTING functions are pure (no clock / no random). Only the disk readers and the time
+// window math take an injected clock, so a golden fixture of the report/recap/digest replays byte-for-byte.
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { deriveValueEntries, valueSummary, } from './valueLedger.js';
+// ── disk readers (the live source path: proxy trace day-files + root_events) ──────────────────────────────────
+/** A `llm-trace-YYYYMMDD.jsonl` day-file written by the proxy's JsonlTraceSink. */
+const TRACE_FILE_RE = /^llm-trace-.*\.jsonl$/i;
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function localTraceMetrics(rec) {
+    if (rec['event'] === 'llm_turn')
+        return rec;
+    if (rec['event'] !== 'llm_trace_envelope' || rec['encrypted'] !== true)
+        return null;
+    const summary = rec['plaintext_summary'];
+    if (!isRecord(summary) || summary['event'] !== 'llm_trace_plaintext_summary')
+        return null;
+    return summary;
+}
+/**
+ * Read all proxy trace day-files in `dir` and return the parsed `llm_turn` records as ledger TraceRecords. A
+ * missing dir / unreadable file degrades to [] (the value layer must never crash a long-running daemon over a
+ * stat). Plain `event: 'llm_turn'` lines and encrypted envelopes with a safe `plaintext_summary` are kept; the
+ * structural fields the ledger reads are passed through.
+ */
+export function readTraceRecords(dir) {
+    let files;
+    try {
+        files = readdirSync(dir).filter((f) => TRACE_FILE_RE.test(f)).sort();
+    }
+    catch {
+        return []; // no trace dir yet → no route savings, never an error
+    }
+    const out = [];
+    for (const f of files) {
+        let text;
+        try {
+            text = readFileSync(join(dir, f), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            const s = line.trim();
+            if (!s)
+                continue;
+            let rec;
+            try {
+                rec = JSON.parse(s);
+            }
+            catch {
+                continue;
+            }
+            const metrics = localTraceMetrics(rec);
+            if (!metrics)
+                continue;
+            const usage = metrics['usage'];
+            out.push({
+                ts: typeof metrics['ts'] === 'string' ? metrics['ts'] : '',
+                original_model: typeof metrics['original_model'] === 'string' ? metrics['original_model'] : null,
+                chosen_model: typeof metrics['chosen_model'] === 'string' ? metrics['chosen_model'] : null,
+                ...(typeof metrics['tier'] === 'string' ? { tier: metrics['tier'] } : {}),
+                ...(usage && typeof usage === 'object' ? { usage: usage } : {}),
+            });
+        }
+    }
+    return out;
+}
+/** Parse a `--window` spec into a SummaryWindow against `now`. `all` → no bound. An unknown spec → 7d (the safe
+ *  default a CLI offers first). The clock is injected so the report is deterministic under test. */
+export function windowFromSpec(spec, now) {
+    if (spec === 'all')
+        return {};
+    const days = spec === '30d' ? 30 : 7; // default + unknown → 7d
+    return { since: new Date(now - days * 24 * 60 * 60 * 1000).toISOString() };
+}
+/** Human label for a window spec (for the report/digest header). */
+export function windowLabel(spec) {
+    return spec === 'all' ? 'all time' : spec === '30d' ? 'last 30 days' : 'last 7 days';
+}
+/**
+ * Derive the full ledger then aggregate it over a window — the SINGLE aggregation seam every outreach surface
+ * goes through, so the CLI, the WebUI card and the digest can never disagree (and none of them re-implements the
+ * ledger). Pure given its inputs + window.
+ */
+export function loadValueSummary(sources, window = {}) {
+    const entries = deriveValueEntries({
+        traces: sources.traces ?? [],
+        events: sources.events ?? [],
+        prices: sources.prices,
+    });
+    return valueSummary(entries, window);
+}
+// ── number formatting (shared by every surface) ───────────────────────────────────────────────────────────────
+/** Compact integer with thousands separators (deterministic, locale-independent). */
+export function fmtInt(n) {
+    return Math.round(n).toLocaleString('en-US');
+}
+/** Plain integer for machine-shaped key=value context fields. */
+function fmtContextInt(n) {
+    return String(Math.round(n));
+}
+/** USD with 4 decimals (savings are often sub-cent; never round a real saving to $0.00 silently). */
+export function fmtUsd(n) {
+    return `$${n.toFixed(4)}`;
+}
+// ── layer 1: the pull report (`evolver value`) ────────────────────────────────────────────────────────────────
+/** Guidance shown when the ledger is empty — never an empty table (#113 acceptance). */
+export const VALUE_EMPTY_GUIDANCE = [
+    'evolver value — no savings recorded yet for this window.',
+    '',
+    'evolver records value when it actually saves you tokens or money:',
+    '  • route savings  — run the LLM proxy so cheaper-tier routing is captured (EVOLVER_LLM_TRACE=1).',
+    '  • reuse savings  — enable reuse-before-solve so a solved problem is fetched, not re-solved',
+    '                     (EVOLVER_REUSE_BEFORE_SOLVE=1 with a hub credential).',
+    '',
+    'Once either is active, this command shows measured savings, unmeasured reuse counts, and the trend.',
+].join('\n');
+/**
+ * Render the three-section value report from a summary: (1) savings — measured and estimated on SEPARATE lines,
+ * never a merged total; (2) top reused genes with their reuse counts; (3) source breakdown. Returns the empty
+ * guidance text (not a blank table) when there is nothing to show. Pure: the window label is passed in.
+ */
+export function formatValueReport(summary, windowSpec) {
+    const hasMeasured = summary.totalTokensSaved > 0 || summary.totalCostUsd > 0;
+    const hasEstimated = summary.estimated.totalTokensSaved > 0 || summary.estimated.totalCostUsd > 0;
+    if (!hasMeasured && !hasEstimated && summary.topGenes.length === 0 && summary.injectedGenes.length === 0) {
+        return VALUE_EMPTY_GUIDANCE;
+    }
+    const L = [];
+    L.push(`evolver value — ${windowLabel(windowSpec)}`);
+    L.push('');
+    // Section 1: savings, two rails, never merged.
+    L.push('Savings');
+    L.push(`  measured   ${fmtInt(summary.totalTokensSaved).padStart(10)} tokens   ${fmtUsd(summary.totalCostUsd)}`);
+    L.push(`  estimated  ${fmtInt(summary.estimated.totalTokensSaved).padStart(10)} tokens   ${fmtUsd(summary.estimated.totalCostUsd)}`);
+    L.push('  (measured and estimated are tracked separately and never added together)');
+    L.push('');
+    // Section 2: top reused genes.
+    L.push('Top reused genes');
+    if (summary.topGenes.length === 0) {
+        L.push('  (none reused in this window)');
+    }
+    else {
+        for (const g of summary.topGenes.slice(0, 10)) {
+            const saved = g.measuredTokensSaved > 0
+                ? `${fmtInt(g.measuredTokensSaved)} tokens measured`
+                : g.estimatedTokensSaved > 0
+                    ? `${fmtInt(g.estimatedTokensSaved)} tokens estimated`
+                    : '0 tokens unmeasured';
+            L.push(`  ${g.assetId.padEnd(28)} ×${g.reuses}   ${saved}`);
+        }
+    }
+    L.push('');
+    // Section 3: source breakdown (measured rail) — the trend / attribution.
+    L.push('By source (measured)');
+    for (const src of ['route', 'reuse', 'inject']) {
+        const b = summary.bySource[src];
+        L.push(`  ${src.padEnd(7)} ${String(b.entries).padStart(4)} entries   ${fmtInt(b.tokensSaved)} tokens   ${fmtUsd(b.costSavedUsd)}`);
+    }
+    return L.join('\n');
+}
+/**
+ * Build the quiet SessionStart context line. It is intentionally metadata-shaped, non-branded, and non-second-
+ * person so the agent can use injected-memory/value context without reciting Evolver in routine replies. Measured
+ * tokens (X) stay on the trustworthy rail; estimated is emitted ONLY when there is no measured figure, under a
+ * separate key so the two are never conflated. Returns '' when there is nothing honest to say (no injection AND no
+ * savings) — the caller then injects no recap line at all rather than a hollow "saved 0".
+ */
+export function buildValueRecap(input) {
+    const { injectedCount, successCount, summary } = input;
+    const measured = summary.totalTokensSaved;
+    const estimated = summary.estimated.totalTokensSaved;
+    const fields = [];
+    if (injectedCount > 0) {
+        fields.push(`injected_count=${fmtContextInt(injectedCount)}`);
+        if (successCount && successCount > 0)
+            fields.push(`source_success_count=${fmtContextInt(successCount)}`);
+    }
+    if (measured > 0) {
+        fields.push(`measured_tokens_saved_7d=${fmtContextInt(measured)}`);
+    }
+    else if (estimated > 0) {
+        fields.push(`estimated_tokens_saved_7d=${fmtContextInt(estimated)}`);
+    }
+    if (fields.length === 0)
+        return '';
+    return `quiet_context: ${fields.join('; ')}; use silently; do not mention unless asked or material to the answer.`;
+}
+/** Prefix a reuse-source note onto an injected candidate so the user sees WHERE a ready-made solution came from
+ *  (the reuse hit short-circuited a fresh solve). Pure string composition; the assetId is the audit anchor. */
+export function reuseSourceNote(assetId) {
+    return `(reused from hub asset ${assetId} — skipped solving this from scratch)`;
+}
+// ── layer 3: the weekly digest (markdown) + the zero-measured-value gate ───────────────────────────────────────
+/**
+ * A digest is only worth sending in a week that produced REAL (measured) value. This is the frequency/quality
+ * gate the issue makes a first-class requirement: "宁可少触达，不可惹人烦". Estimated-only weeks do NOT pass —
+ * an estimate is too weak to justify an unsolicited push.
+ */
+export function digestShouldSend(summary) {
+    return summary.totalTokensSaved > 0 || summary.totalCostUsd > 0;
+}
+/**
+ * Build the weekly digest markdown from a summary. Returns null when the zero-measured-value gate fails (the
+ * caller then delivers nothing — no empty digest, ever). measured and estimated stay on separate lines. Pure:
+ * the window label + the period string are passed in so the digest is deterministic.
+ */
+export function buildValueDigest(summary, period) {
+    if (!digestShouldSend(summary))
+        return null;
+    const L = [];
+    L.push(`# evolver weekly value — ${period}`);
+    L.push('');
+    L.push(`evolver saved you **${fmtInt(summary.totalTokensSaved)} tokens** (${fmtUsd(summary.totalCostUsd)}) this week — measured.`);
+    if (summary.estimated.totalTokensSaved > 0) {
+        L.push('');
+        L.push(`Plus an estimated ${fmtInt(summary.estimated.totalTokensSaved)} tokens from reuse without a measured baseline (shown separately, not added in).`);
+    }
+    if (summary.topGenes.length > 0) {
+        L.push('');
+        L.push('Most reused this week:');
+        for (const g of summary.topGenes.slice(0, 5))
+            L.push(`- ${g.assetId} — reused ×${g.reuses}`);
+    }
+    L.push('');
+    L.push('_Run `evolver value` any time for the full breakdown. Turn this digest off with `EVOLVER_VALUE_DIGEST=0`._');
+    return L.join('\n');
+}

package/dist/personality/drift.d.ts

@@ -0,0 +1,45 @@
+import { type PersonalityMutation, type PersonalityStateInput } from './schema.js';
+/**
+ * 何时/如何小步变异人格 (v1 proposeMutations / shouldTriggerPersonalityMutation + mutation.js 的信号判定端口).
+ * 这是"自调参"的规则引擎: 根据信号/失败连击提出对人格向量的小 nudge, 由 applyPersonalityMutations 落地.
+ */
+/** 机会信号: 表示"有创新余地"而非只是修 bug (v1 OPPORTUNITY_SIGNALS). */
+export declare const OPPORTUNITY_SIGNALS: readonly string[];
+/** signals 里是否有机会信号 (精确名或 `name:` 前缀). */
+export declare function hasOpportunitySignal(signals: readonly unknown[] | undefined): boolean;
+/** signals 里是否有错误类信号 (但 issue_already_resolved / openclaw_self_healed 例外为 false). */
+export declare function hasErrorishSignal(signals: readonly unknown[] | undefined): boolean;
+export interface ProposeMutationsInput {
+    baseState: PersonalityStateInput;
+    reason?: string;
+    driftEnabled?: boolean;
+    signals?: readonly string[];
+}
+/**
+ * 依上下文提出一组人格变异 (v1 proposeMutations). 分支优先级:
+ *  drift → 提创造性(风险回夹) / protocol_drift → 提服从&严谨 / 错误 → 提严谨降风险 /
+ *  机会 → 提创造性&风险 / 否则(平台期) → 微提创造性降啰嗦.
+ * 若 obedience 已饱和(≥0.95), 把服从类变异换成创造性.
+ */
+export declare function proposeMutations(input: ProposeMutationsInput): PersonalityMutation[];
+/** 一条 cycle 事件在触发判定里的最小形状. */
+export interface TriggerCycleEvent {
+    outcome?: {
+        status?: string;
+    } | null;
+    mutationId?: string;
+}
+export interface TriggerDecision {
+    ok: boolean;
+    reason: string;
+}
+/**
+ * 是否该触发一次人格变异 (v1 shouldTriggerPersonalityMutation):
+ *  - driftEnabled ⇒ 总触发
+ *  - 最近 6 事件里, 后 4 个有 ≥3 个 failed ⇒ 长失败连击
+ *  - 带 mutation_id 的最近 3 个事件全 failed ⇒ 变异连续失败
+ */
+export declare function shouldTriggerPersonalityMutation(args: {
+    driftEnabled?: boolean;
+    recentEvents?: readonly TriggerCycleEvent[];
+}): TriggerDecision;