@compaction/cli 0.1.2 → 0.2.0

package/dist/core/context-store.js

@@ -0,0 +1,228 @@
+import { contentHash } from "./content-hash.js";
+import { estimateTextTokens } from "./token-estimator.js";
+import { computeTraceFingerprint } from "./trace-fingerprint.js";
+/**
+ * V0.4 context store — rung-1 (local, deterministic, source-grounded).
+ *
+ * SCOPE (accepted design doc `docs/design/v0.4-context-store-retrieval.md`,
+ * 2026-06-24): a durable, local, file-based store of source-pointed context items
+ * accumulated across runs, plus DETERMINISTIC local retrieval and assembly under a
+ * token budget. This module is the rung-1 core.
+ *
+ * HARD NON-GOALS (load-bearing — do not add here):
+ * - NO semantic / embedding retrieval. Retrieval ranks by deterministic signals only
+ *   (source-pointer match, lexical overlap, recency). Semantic retrieval needs a model
+ *   → not free-CLI local-first → deferred to the gated private engine/API.
+ * - NO network call, credential, upload, or model invocation. This module is pure +
+ *   local-file I/O only (see `loadContextStore` / `appendContextItems`).
+ * - NO hosted DB / vector store / auth.
+ * - NO large-memory / 300M-token / retrieval-correctness claim. Those are gated on the
+ *   four-axis eval harness (a follow-up increment) and rung-6 evidence.
+ *
+ * HONESTY: token figures here are `local_estimate` (chars/4), never provider-reported.
+ * Every stored item retains its `source_pointer` + recoverability so the assembled
+ * context stays recoverable to its sources (the substrate invariant).
+ */
+/** Algorithm + schema version, so a persisted store is self-describing. */
+export const CONTEXT_STORE_ITEM_VERSION = "context-store-item-v1";
+function normalizeContent(content) {
+    return content.trim().replace(/\s+/g, " ");
+}
+/**
+ * Build a single context item, deriving the dedup hash + local token estimate.
+ * Pure — no I/O, no clock (the caller supplies `created_at` so this stays
+ * deterministic and testable).
+ */
+export function makeContextItem(input) {
+    const content = normalizeContent(input.content);
+    return {
+        version: CONTEXT_STORE_ITEM_VERSION,
+        content_sha256: contentHash(content),
+        content,
+        estimated_tokens: estimateTextTokens(content),
+        source_pointer: input.source_pointer,
+        recoverability: input.recoverability ?? "unknown",
+        trace_fingerprint: input.trace_fingerprint,
+        source_trace_id: input.source_trace_id,
+        provenance: input.provenance,
+        labels: input.labels ? [...input.labels] : [],
+        created_at: input.created_at
+    };
+}
+/**
+ * Derive context items from a `StateCapsule`. Each retained fact / open question /
+ * safety note becomes a source-pointed item, inheriting the capsule's source pointer +
+ * recoverability + the originating trace id (and the supplied per-run fingerprint).
+ * Pure — `created_at` is supplied by the caller.
+ */
+export function contextItemsFromCapsule(capsule, opts) {
+    const primaryProvenance = capsule.provenance_entries?.[0];
+    const base = {
+        source_pointer: capsule.source_pointer ?? primaryProvenance?.source_pointer,
+        recoverability: capsule.source_recoverable ?? primaryProvenance?.source_recoverable ?? "unknown",
+        source_trace_id: capsule.source_trace_id ?? capsule.traceId,
+        provenance: primaryProvenance,
+        trace_fingerprint: opts.trace_fingerprint,
+        created_at: opts.created_at
+    };
+    const items = [];
+    for (const fact of capsule.retainedFacts) {
+        if (fact.trim().length === 0)
+            continue;
+        items.push(makeContextItem({ ...base, content: fact, labels: ["retained_fact"] }));
+    }
+    for (const question of capsule.openQuestions) {
+        if (question.trim().length === 0)
+            continue;
+        items.push(makeContextItem({ ...base, content: question, labels: ["open_question"] }));
+    }
+    for (const note of capsule.safetyNotes) {
+        if (note.trim().length === 0)
+            continue;
+        items.push(makeContextItem({ ...base, content: note, labels: ["safety_note"] }));
+    }
+    return dedupeContextItems(items);
+}
+/**
+ * Derive context items from a normalized `AgentTrace` (the local artifact `compaction capture`
+ * / `import` produces). Each non-empty message becomes a source-pointed item recoverable to its
+ * `trace=<id> message=<id>` origin, tagged with the run's distinctness fingerprint. This is the
+ * free-CLI populate path (state-capsules require the gated engine; trace messages do not). Pure —
+ * `created_at` is supplied by the caller.
+ */
+export function contextItemsFromTrace(trace, opts) {
+    const trace_fingerprint = computeTraceFingerprint(trace).content_sha256;
+    const items = [];
+    for (const message of trace.messages) {
+        if (message.content.trim().length === 0)
+            continue;
+        const labels = [message.role];
+        if (message.toolName)
+            labels.push(message.toolName);
+        items.push(makeContextItem({
+            content: message.content,
+            source_pointer: `trace=${trace.id} message=${message.id}`,
+            source_trace_id: trace.id,
+            recoverability: true,
+            trace_fingerprint,
+            labels,
+            created_at: opts.created_at
+        }));
+    }
+    return dedupeContextItems(items);
+}
+/**
+ * Dedup by `content_sha256`, keeping the EARLIEST item deterministically (ties broken
+ * by `created_at`, then by the existing order). Reuses the fingerprint discipline:
+ * byte-identical content is one item, not many. Output order follows the
+ * first-occurrence order of each distinct hash in the input array.
+ */
+export function dedupeContextItems(items) {
+    const byHash = new Map();
+    for (const item of items) {
+        const existing = byHash.get(item.content_sha256);
+        if (!existing || item.created_at < existing.created_at) {
+            // Merge labels so a later duplicate's labels are not lost.
+            if (existing) {
+                const labels = Array.from(new Set([...item.labels, ...existing.labels])).sort();
+                byHash.set(item.content_sha256, { ...item, labels });
+            }
+            else {
+                byHash.set(item.content_sha256, item);
+            }
+        }
+        else {
+            const labels = Array.from(new Set([...existing.labels, ...item.labels])).sort();
+            byHash.set(item.content_sha256, { ...existing, labels });
+        }
+    }
+    return Array.from(byHash.values());
+}
+const WORD_RE = /[a-z0-9]+/g;
+function tokenSet(text) {
+    const set = new Set();
+    const matches = text.toLowerCase().match(WORD_RE);
+    if (matches) {
+        for (const word of matches)
+            set.add(word);
+    }
+    return set;
+}
+/**
+ * Deterministic, local retrieval. Ranks items by:
+ *   score = sourceMatchWeight * (exact source/trace match ? 1 : 0)
+ *         + lexicalWeight     * lexical overlap coefficient in [0,1]
+ *
+ * Ties are broken deterministically by recency (newer first) then `content_sha256`
+ * ascending, so the same store + query always yields the same order. No model, no
+ * embeddings, no network — overlap is a pure word-set intersection.
+ */
+export function retrieveContextItems(items, query, options = {}) {
+    const sourceWeight = options.sourceMatchWeight ?? 1;
+    const lexicalWeight = options.lexicalWeight ?? 1;
+    const queryWords = tokenSet(query.text);
+    const wantedPointers = new Set(query.source_pointers ?? []);
+    const wantedTraces = new Set(query.trace_ids ?? []);
+    const ranked = items.map((item) => {
+        const sourceMatch = (item.source_pointer !== undefined && wantedPointers.has(item.source_pointer)) ||
+            (item.source_trace_id !== undefined && wantedTraces.has(item.source_trace_id));
+        let overlap = 0;
+        if (queryWords.size > 0) {
+            const itemWords = tokenSet(item.content);
+            if (itemWords.size > 0) {
+                let intersection = 0;
+                const [small, large] = queryWords.size <= itemWords.size ? [queryWords, itemWords] : [itemWords, queryWords];
+                for (const word of small) {
+                    if (large.has(word))
+                        intersection += 1;
+                }
+                // Overlap coefficient: intersection / min(|q|, |item|) — in [0, 1].
+                overlap = intersection / Math.min(queryWords.size, itemWords.size);
+            }
+        }
+        const score = sourceWeight * (sourceMatch ? 1 : 0) + lexicalWeight * overlap;
+        return { item, score, source_match: sourceMatch, lexical_overlap: overlap };
+    });
+    ranked.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        if (a.item.created_at !== b.item.created_at)
+            return a.item.created_at < b.item.created_at ? 1 : -1;
+        return a.item.content_sha256 < b.item.content_sha256 ? -1 : 1;
+    });
+    const withSignal = ranked.filter((entry) => entry.score > 0);
+    return options.limit !== undefined ? withSignal.slice(0, options.limit) : withSignal;
+}
+/**
+ * Assemble ranked items into the sufficient active context under a token budget.
+ * Greedy in ranked order; dedups by `content_sha256`; PRESERVES the source pointer +
+ * provenance on every included item (so the assembled context stays recoverable).
+ * Token figures are local estimates.
+ */
+export function assembleContext(ranked, options) {
+    const items = ranked.map((entry) => ("item" in entry ? entry.item : entry));
+    const included = [];
+    const dropped = [];
+    const seen = new Set();
+    let total = 0;
+    for (const item of items) {
+        if (seen.has(item.content_sha256))
+            continue;
+        seen.add(item.content_sha256);
+        if (total + item.estimated_tokens <= options.tokenBudget) {
+            included.push(item);
+            total += item.estimated_tokens;
+        }
+        else {
+            dropped.push(item);
+        }
+    }
+    return {
+        text: included.map((item) => item.content).join("\n"),
+        included,
+        dropped,
+        estimated_tokens: total,
+        within_budget: dropped.length === 0
+    };
+}
+//# sourceMappingURL=context-store.js.map

package/dist/core/report-generator.d.ts

@@ -1,6 +1,37 @@
 import type { SkillInjectionAdvisory } from "./skill-injection-detector.js";
-import type { AgentTrace, CompactionPolicy, CompactionReport, CostEstimate, TokenEstimate, WasteFinding } from "./types.js";
+import type { AgentTrace, CompactionPolicy, CompactionReport, CostEstimate, SavingsEvidence, TokenEstimate, WasteFinding } from "./types.js";
 import type { UsageMetadata } from "./usage-metadata.js";
+/**
+ * Attach the content-addressed per-run trace fingerprint to a compaction report (PURE,
+ * additive, backward-compatible). This is the report-generation attachment point that
+ * threads trace identity into the savings-evidence pipeline so each per-run saving is
+ * attributable to a verifiable run identity and a re-captured run can be de-duplicated in
+ * the aggregate.
+ *
+ * It changes NO existing report field/label — it only sets the OPTIONAL `trace_fingerprint`
+ * from `computeTraceFingerprint(trace)` (a one-way SHA-256 digest + structural counts; no
+ * message content). Returns a new object; the input report is not mutated. This is an
+ * attribution/integrity signal, NOT a billing, provider, or semantic-preservation claim.
+ */
+export declare function withTraceFingerprint(report: CompactionReport, trace: AgentTrace): CompactionReport;
+/**
+ * Attach the composed per-run SAVINGS EVIDENCE record to a compaction report (PURE,
+ * additive, backward-compatible). V0.2 "evidence labels per result": it composes the
+ * report's EXISTING numbers into ONE explicitly-labeled record and asserts the weakest
+ * honest rung — a single run is rung 1 (local estimate). It makes NO new/stronger claim:
+ * `billing_confirmed` is always false, `semantic_preservation` always `not_evaluated`, and
+ * the measured rung 1.5 (`measured_caveated_estimate_delta`) is NEVER produced here (only by
+ * the aggregate increment across N≥3 distinct runs).
+ *
+ * `costSource` defaults to the weakest honest label (`local_estimate`); pass a stronger
+ * source ONLY when the run genuinely carries it. `recoverability` defaults to
+ * `not_evaluated` (the eval is the separate `compact --eval` path); pass the eval result
+ * when one ran. Returns a new object; the input report is not mutated.
+ */
+export declare function withSavingsEvidence(report: CompactionReport, opts?: {
+    costSource?: SavingsEvidence["cost_source"];
+    recoverability?: SavingsEvidence["recoverability"];
+}): CompactionReport;
 export declare function formatAnalyzeReport(trace: AgentTrace, tokens: TokenEstimate, cost: CostEstimate, findings?: WasteFinding[], usage?: UsageMetadata, skillInjectionAdvisory?: SkillInjectionAdvisory): string;
 export declare function formatCompactionReport(report: CompactionReport): string;
 export declare function formatCompactionMarkdownReport(report: CompactionReport, policy: CompactionPolicy): string;

package/dist/core/report-generator.js

@@ -1,5 +1,71 @@
 import { calculateCost } from "./cost-calculator.js";
 import { isKnownModel } from "./pricing.js";
+import { computeTraceFingerprint } from "./trace-fingerprint.js";
+/**
+ * Attach the content-addressed per-run trace fingerprint to a compaction report (PURE,
+ * additive, backward-compatible). This is the report-generation attachment point that
+ * threads trace identity into the savings-evidence pipeline so each per-run saving is
+ * attributable to a verifiable run identity and a re-captured run can be de-duplicated in
+ * the aggregate.
+ *
+ * It changes NO existing report field/label — it only sets the OPTIONAL `trace_fingerprint`
+ * from `computeTraceFingerprint(trace)` (a one-way SHA-256 digest + structural counts; no
+ * message content). Returns a new object; the input report is not mutated. This is an
+ * attribution/integrity signal, NOT a billing, provider, or semantic-preservation claim.
+ */
+export function withTraceFingerprint(report, trace) {
+    return { ...report, trace_fingerprint: computeTraceFingerprint(trace) };
+}
+/**
+ * Attach the composed per-run SAVINGS EVIDENCE record to a compaction report (PURE,
+ * additive, backward-compatible). V0.2 "evidence labels per result": it composes the
+ * report's EXISTING numbers into ONE explicitly-labeled record and asserts the weakest
+ * honest rung — a single run is rung 1 (local estimate). It makes NO new/stronger claim:
+ * `billing_confirmed` is always false, `semantic_preservation` always `not_evaluated`, and
+ * the measured rung 1.5 (`measured_caveated_estimate_delta`) is NEVER produced here (only by
+ * the aggregate increment across N≥3 distinct runs).
+ *
+ * `costSource` defaults to the weakest honest label (`local_estimate`); pass a stronger
+ * source ONLY when the run genuinely carries it. `recoverability` defaults to
+ * `not_evaluated` (the eval is the separate `compact --eval` path); pass the eval result
+ * when one ran. Returns a new object; the input report is not mutated.
+ */
+export function withSavingsEvidence(report, opts = {}) {
+    const cost_source = opts.costSource ?? "local_estimate";
+    const recoverability = opts.recoverability ?? "not_evaluated";
+    const savings_evidence = {
+        trace_identity: report.trace_fingerprint ? "fingerprinted" : "unidentified",
+        cost_source,
+        recoverability,
+        semantic_preservation: "not_evaluated",
+        evidence_rung: "local_estimate_single_run",
+        billing_confirmed: false,
+        label: `Per-run ${cost_source.replace(/_/g, " ")} delta (single run → local-estimate rung). ` +
+            `Recoverability: ${recoverability}` +
+            (recoverability === "not_evaluated" ? " (run `compact --eval`)" : "") +
+            ". Semantic preservation: not_evaluated. NOT billing-confirmed, NOT realized savings, NOT extrapolated."
+    };
+    return { ...report, savings_evidence };
+}
+/** Render the composed per-run savings-evidence record for the markdown report. */
+function formatSavingsEvidenceLines(report) {
+    const se = report.savings_evidence;
+    if (!se) {
+        return [];
+    }
+    return [
+        "",
+        "## Savings Evidence (per-run, labeled)",
+        "",
+        `- Trace identity: ${se.trace_identity}`,
+        `- Cost source: ${se.cost_source}`,
+        `- Recoverability: ${se.recoverability}`,
+        `- Semantic preservation: ${se.semantic_preservation}`,
+        `- Evidence rung: ${se.evidence_rung}`,
+        `- Billing-confirmed: ${se.billing_confirmed}`,
+        `- ${se.label}`
+    ];
+}
 function formatTokenBreakdown(tokens) {
     return `${tokens.totalTokens} total (${tokens.inputTokens} input, ${tokens.outputTokens} output)`;
 }
@@ -201,6 +267,7 @@ export function formatCompactionMarkdownReport(report, policy) {
         `- Saving per run: $${report.saving_per_run.toFixed(6)} (estimated)`,
         ...formatValueProofLines(report),
         ...formatSpendBySourceLines(report),
+        ...formatSavingsEvidenceLines(report),
         "",
         "## Waste Pattern",
         "",

package/dist/core/run-aggregator.d.ts

@@ -1,4 +1,17 @@
 import type { CompactionReport, WasteFinding } from "./types.js";
+/**
+ * Duplicate-safety summary for the `summary` rollup, by content fingerprint. A count of DISTINCT
+ * captured runs — NOT a billing/provider/semantic claim. A run captured/aggregated twice with the
+ * SAME fingerprint is counted once in the headline so summed savings are never inflated; a run
+ * WITHOUT a fingerprint cannot be de-duplicated and is counted as distinct.
+ */
+export interface RunDistinctnessSummary {
+    total_runs: number;
+    distinct_runs: number;
+    duplicate_runs: number;
+    runs_with_fingerprint: number;
+    runs_without_fingerprint: number;
+}
 export interface RunSummaryBucket {
     total_runs: number;
     total_original_input_tokens: number;
@@ -22,12 +35,54 @@ export interface SkippedReportFile {
     path: string;
     reason: string;
 }
+/**
+ * V0.2 Increment 2 — the MEASURED-across-distinct-runs estimate delta. Aggregates the per-run
+ * estimate reductions over N DISTINCT runs (dedup by content fingerprint) into a mean + dispersion,
+ * and applies the accepted criterion (`docs/design/billing-delta-loop.md`): **N ≥ 3 distinct runs
+ * AND the mean ±2·SE interval excludes zero**. When BOTH hold, the figure earns the
+ * `measured_caveated_estimate_delta` rung (claims-and-evidence-ladder rung 1.5) — a measured
+ * estimate, NOT a single anecdote. Below the bar it stays rung 1 (`local_estimate_single_run`).
+ *
+ * It is STILL an estimate (chars/4 + price-table): explicitly NOT `provider-reported`, NOT
+ * eval-backed (rung 3), and NEVER `billing-confirmed` (rung 5). No time-period extrapolation.
+ */
+export interface MeasuredEstimateDelta {
+    /** N distinct runs used (≥3 required to qualify). */
+    distinct_run_count: number;
+    /** Mean per-run percent reduction across the distinct runs (estimate). */
+    mean_percent_reduction: number;
+    /** Standard error of the mean percent reduction (0 when N<2 — no dispersion). */
+    std_error: number;
+    /** Lower / upper bound of the mean ±2·SE interval. */
+    ci_low: number;
+    ci_high: number;
+    /** Does the ±2·SE interval exclude zero (lower bound > 0)? */
+    excludes_zero: boolean;
+    /** Criterion met: N≥3 AND the ±2·SE interval excludes zero. */
+    qualifies: boolean;
+    /** The claims-ladder rung this aggregate stands on. */
+    evidence_rung: "measured_caveated_estimate_delta" | "local_estimate_single_run";
+    /** One-line honest label — estimate-class, never billing-confirmed, never eval-backed. */
+    label: string;
+}
 export interface RunSummary extends RunSummaryBucket {
     average_percent_reduction: number;
+    /**
+     * V0.2 measured-across-distinct-runs estimate delta (the "measured" rung). Mean ±2·SE over the
+     * distinct runs' estimate reductions; `qualifies` only when N≥3 AND the interval excludes zero.
+     * Estimate-class — never billing-confirmed, never eval-backed.
+     */
+    measured_estimate_delta: MeasuredEstimateDelta;
     savings_by_policy: Record<string, RunSummaryBucket>;
     savings_by_waste_pattern: Record<string, RunSummaryBucket>;
     top_savings_runs: TopSavingsRun[];
     skipped_files: SkippedReportFile[];
+    /**
+     * Duplicate-safety summary: the headline totals above are summed over DISTINCT runs only (a
+     * run captured/aggregated twice with the same content fingerprint is counted once), so savings
+     * are never inflated. Runs without a fingerprint are each counted as distinct.
+     */
+    distinctness: RunDistinctnessSummary;
     generated_at: string;
     source_glob: string;
 }
@@ -35,6 +90,15 @@ interface LoadedReport {
     path: string;
     report: CompactionReport;
 }
+/** Minimum DISTINCT runs for a measured (not single-anecdote) estimate delta. */
+export declare const MIN_RUNS_FOR_MEASURED_DELTA = 3;
+/**
+ * Compute the measured-across-distinct-runs estimate delta over a set of per-run percent
+ * reductions (PURE). Applies the accepted criterion: N ≥ 3 AND the mean ±2·SE interval excludes
+ * zero. Estimate-class only — the result is NEVER billing-confirmed or eval-backed. Uses the
+ * sample standard deviation (n−1); with n<2 there is no dispersion (SE 0) so it cannot qualify.
+ */
+export declare function computeMeasuredEstimateDelta(percentReductions: number[]): MeasuredEstimateDelta;
 export declare function validateCompactionReport(value: unknown): {
     report?: CompactionReport;
     reason?: string;

package/dist/core/run-aggregator.js

@@ -1,5 +1,6 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { classifyDistinctness } from "./trace-fingerprint.js";
 const REQUIRED_STRING_FIELDS = ["run_id", "trace_title", "policy_name"];
 const REQUIRED_NUMBER_FIELDS = [
     "original_input_tokens",
@@ -25,6 +26,103 @@ function roundTo(value, digits) {
     const factor = 10 ** digits;
     return Math.round((value + Number.EPSILON) * factor) / factor;
 }
+/** Minimum DISTINCT runs for a measured (not single-anecdote) estimate delta. */
+export const MIN_RUNS_FOR_MEASURED_DELTA = 3;
+/**
+ * Compute the measured-across-distinct-runs estimate delta over a set of per-run percent
+ * reductions (PURE). Applies the accepted criterion: N ≥ 3 AND the mean ±2·SE interval excludes
+ * zero. Estimate-class only — the result is NEVER billing-confirmed or eval-backed. Uses the
+ * sample standard deviation (n−1); with n<2 there is no dispersion (SE 0) so it cannot qualify.
+ */
+export function computeMeasuredEstimateDelta(percentReductions) {
+    const n = percentReductions.length;
+    const mean = n === 0 ? 0 : percentReductions.reduce((sum, x) => sum + x, 0) / n;
+    let se = 0;
+    if (n >= 2) {
+        const variance = percentReductions.reduce((sum, x) => sum + (x - mean) ** 2, 0) / (n - 1);
+        se = Math.sqrt(variance) / Math.sqrt(n);
+    }
+    const ciLow = mean - 2 * se;
+    const ciHigh = mean + 2 * se;
+    const excludesZero = ciLow > 0;
+    const qualifies = n >= MIN_RUNS_FOR_MEASURED_DELTA && excludesZero;
+    const meanR = roundTo(mean, 2);
+    const lowR = roundTo(ciLow, 2);
+    const highR = roundTo(ciHigh, 2);
+    let label;
+    if (qualifies) {
+        label =
+            `Measured-caveated ESTIMATE delta across ${n} distinct runs: mean ${meanR}% reduction ` +
+                `(±2·SE [${lowR}%, ${highR}%], excludes zero). Estimate (chars/4 + price-table) — ` +
+                "NOT billing-confirmed, NOT eval-backed, NOT realized savings, NOT extrapolated.";
+    }
+    else if (n < MIN_RUNS_FOR_MEASURED_DELTA) {
+        label =
+            `Single-run/anecdote estimate (${n} distinct run(s); need ≥${MIN_RUNS_FOR_MEASURED_DELTA} ` +
+                "for a measured delta). Local estimate — NOT billing-confirmed.";
+    }
+    else {
+        label =
+            `Estimate delta across ${n} distinct runs does NOT meet the measured bar ` +
+                `(±2·SE [${lowR}%, ${highR}%] includes zero — dispersion too wide). Local estimate — NOT billing-confirmed.`;
+    }
+    return {
+        distinct_run_count: n,
+        mean_percent_reduction: meanR,
+        std_error: roundTo(se, 4),
+        ci_low: lowR,
+        ci_high: highR,
+        excludes_zero: excludesZero,
+        qualifies,
+        evidence_rung: qualifies ? "measured_caveated_estimate_delta" : "local_estimate_single_run",
+        label
+    };
+}
+/** Read the OPTIONAL content fingerprint digest from a report (older reports have none). */
+function fingerprintDigestOf(report) {
+    const fp = report.trace_fingerprint;
+    return fp && typeof fp.content_sha256 === "string" && fp.content_sha256.length > 0 ? fp.content_sha256 : null;
+}
+/**
+ * De-duplicate loaded reports by content fingerprint for a duplicate-safe headline.
+ *
+ * Keeps the FIRST report per distinct fingerprint; later same-fingerprint reports are duplicates
+ * and are dropped from the totals so a re-captured run never double-counts its savings. Reports
+ * without a fingerprint are each kept (cannot dedup what cannot be identified). PURE; never
+ * inflates savings.
+ */
+function dedupeReportsByFingerprint(reports) {
+    const seen = new Set();
+    const distinctReports = [];
+    let withFingerprint = 0;
+    let withoutFingerprint = 0;
+    for (const loaded of reports) {
+        const fp = fingerprintDigestOf(loaded.report);
+        if (fp !== null) {
+            withFingerprint += 1;
+            if (seen.has(fp))
+                continue;
+            seen.add(fp);
+            distinctReports.push(loaded);
+        }
+        else {
+            withoutFingerprint += 1;
+            distinctReports.push(loaded);
+        }
+    }
+    const classified = classifyDistinctness(reports.map((loaded) => ({ runId: loaded.report.run_id, content_sha256: fingerprintDigestOf(loaded.report) })));
+    const distinctRunCount = classified.distinct_verified_count + withoutFingerprint;
+    return {
+        distinctReports,
+        distinctness: {
+            total_runs: reports.length,
+            distinct_runs: distinctRunCount,
+            duplicate_runs: reports.length - distinctRunCount,
+            runs_with_fingerprint: withFingerprint,
+            runs_without_fingerprint: withoutFingerprint
+        }
+    };
+}
 function addReportToBucket(bucket, report) {
     bucket.total_runs += 1;
     bucket.total_original_input_tokens += report.original_input_tokens;
@@ -101,18 +199,23 @@ export async function readCompactionRunReports(runsDirectory = ".compaction/runs
     return { reports, skippedFiles };
 }
 export function aggregateCompactionReports(reports, skippedFiles = [], generatedAt = new Date().toISOString(), sourceGlob = ".compaction/runs/*/report.json") {
+    // Duplicate-safe headline: fold totals over DISTINCT reports only (a run captured/aggregated
+    // twice with the same content fingerprint is counted once). Never inflates summed savings.
+    const { distinctReports, distinctness } = dedupeReportsByFingerprint(reports);
     const summary = {
         ...emptyBucket(),
         average_percent_reduction: 0,
+        measured_estimate_delta: computeMeasuredEstimateDelta([]),
         savings_by_policy: {},
         savings_by_waste_pattern: {},
         top_savings_runs: [],
         skipped_files: skippedFiles,
+        distinctness,
         generated_at: generatedAt,
         source_glob: sourceGlob
     };
     let percentReductionTotal = 0;
-    for (const { path, report } of reports) {
+    for (const { path, report } of distinctReports) {
         addReportToBucket(summary, report);
         percentReductionTotal += report.percent_reduction;
         const policyBucket = (summary.savings_by_policy[report.policy_name] ??= emptyBucket());
@@ -131,7 +234,11 @@ export function aggregateCompactionReports(reports, skippedFiles = [], generated
             waste_pattern: report.waste_pattern
         });
     }
-    summary.average_percent_reduction = reports.length === 0 ? 0 : roundTo(percentReductionTotal / reports.length, 2);
+    summary.average_percent_reduction =
+        distinctReports.length === 0 ? 0 : roundTo(percentReductionTotal / distinctReports.length, 2);
+    // V0.2 Increment 2: the measured-across-distinct-runs estimate delta over the DISTINCT runs'
+    // per-run reductions. Qualifies for rung 1.5 only when N≥3 AND the mean ±2·SE excludes zero.
+    summary.measured_estimate_delta = computeMeasuredEstimateDelta(summary.top_savings_runs.map((run) => run.percent_reduction));
     normalizeBucket(summary);
     for (const bucket of Object.values(summary.savings_by_policy)) {
         normalizeBucket(bucket);
@@ -156,6 +263,18 @@ export async function createRunSummary(runsDirectory = ".compaction/runs") {
 function formatCurrency(value) {
     return `$${value.toFixed(6)}`;
 }
+/**
+ * "distinct runs N of M (K duplicates detected)" — a count of distinct captured runs by content
+ * fingerprint. The totals above are summed over the distinct set, so a re-captured run never
+ * double-counts. NOT a billing/provider/semantic claim.
+ */
+function distinctnessLine(d) {
+    const noFp = d.runs_without_fingerprint > 0
+        ? `; ${d.runs_without_fingerprint} run(s) without a fingerprint counted as distinct (cannot de-duplicate)`
+        : "";
+    return (`distinct runs ${d.distinct_runs} of ${d.total_runs} (${d.duplicate_runs} duplicate(s) detected by content fingerprint, ` +
+        `excluded from the headline so savings are not double-counted)${noFp}`);
+}
 function formatBucketLines(bucket) {
     return [
         `runs: ${bucket.total_runs}`,
@@ -184,8 +303,10 @@ export function formatRunSummary(summary) {
         `Generated at: ${summary.generated_at}`,
         "",
         "Totals",
+        `- ${distinctnessLine(summary.distinctness)}`,
         ...formatBucketLines(summary).map((line) => `- ${line}`),
         `- average percent reduction: ${summary.average_percent_reduction.toFixed(2)}%`,
+        `- measured estimate delta [${summary.measured_estimate_delta.evidence_rung}]: ${summary.measured_estimate_delta.label}`,
         "",
         "Savings by policy",
         ...(policyLines.length === 0 ? ["- none"] : policyLines),
@@ -213,6 +334,7 @@ export function formatRunSummaryMarkdown(summary) {
         "",
         "## Totals",
         "",
+        `- Distinct runs: ${distinctnessLine(summary.distinctness)}`,
         `- Total runs: ${summary.total_runs}`,
         `- Total original input tokens: ${summary.total_original_input_tokens}`,
         `- Total compacted input tokens: ${summary.total_compacted_input_tokens}`,
@@ -221,7 +343,14 @@ export function formatRunSummaryMarkdown(summary) {
         `- Total cost before per run: ${formatCurrency(summary.total_cost_before_per_run)}`,
         `- Total cost after per run: ${formatCurrency(summary.total_cost_after_per_run)}`,
         `- Total saving per run: ${formatCurrency(summary.total_saving_per_run)}`,
-        `- Saving figures are estimated and summed over the ${summary.total_runs} recorded run${summary.total_runs === 1 ? "" : "s"}.`,
+        `- Saving figures are estimated and summed over the ${summary.distinctness.distinct_runs} distinct recorded run${summary.distinctness.distinct_runs === 1 ? "" : "s"} (${summary.distinctness.duplicate_runs} duplicate(s) detected by content fingerprint and excluded).`,
+        "",
+        "## Measured Estimate Delta (across distinct runs)",
+        "",
+        `- Rung: ${summary.measured_estimate_delta.evidence_rung}`,
+        `- Distinct runs: ${summary.measured_estimate_delta.distinct_run_count}`,
+        `- Mean percent reduction: ${summary.measured_estimate_delta.mean_percent_reduction.toFixed(2)}% (±2·SE [${summary.measured_estimate_delta.ci_low.toFixed(2)}%, ${summary.measured_estimate_delta.ci_high.toFixed(2)}%])`,
+        `- ${summary.measured_estimate_delta.label}`,
         "",
         "## Savings by policy",
         "",