@compaction/cli 0.1.4 → 0.2.0

package/dist/core/context-store-sufficiency.js

@@ -0,0 +1,135 @@
+import { evaluateContextStoreFixture } from "./context-store-eval.js";
+/**
+ * V0.4 context-store INTERNAL sufficiency report (rung-1).
+ *
+ * Applies the founder-accepted threshold defaults
+ * (`docs/design/v0.4-context-store-thresholds.md`) to the eval fixtures, purely as an
+ * INTERNAL regression/confidence gate. It is consumed only by the eval harness/tests — it is
+ * NOT wired to any CLI command and produces NO user-facing output.
+ *
+ * WHAT THIS IS NOT (load-bearing):
+ * - NOT a public claim. Passing means the deterministic retriever still behaves on SYNTHETIC
+ *   fixtures — it is NOT evidence of retrieval correctness for users, savings, semantic
+ *   preservation, or any large-memory / 300M readiness. Those remain gated.
+ * - NO model replay, NO embeddings, NO network.
+ *
+ * Model:
+ * - `sufficiency` fixtures are GATED against the thresholds below (hard axes fail; soft axes
+ *   warn; latency is recorded only).
+ * - `adversarial` fixtures are NOT gated — their low/partial scores are correct. They are
+ *   regression ANCHORS: the measured score must keep matching the fixture's `expected`.
+ */
+export const CONTEXT_STORE_SUFFICIENCY_VERSION = "context-store-sufficiency-v1";
+/**
+ * Founder-accepted defaults (2026-06-24): hard recall / source coverage / recoverability
+ * (= 1.0 on sufficiency fixtures); soft continuation (advisory ≥ 0.9 — it is a marker proxy,
+ * not model replay); latency report-only. INTERNAL thresholds, not public claims.
+ */
+export const CONTEXT_STORE_SUFFICIENCY_THRESHOLDS = {
+    recall: { kind: "hard", min: 1 },
+    source_coverage: { kind: "hard", min: 1 },
+    recoverability: { kind: "hard", min: 1 },
+    continuation_success: { kind: "soft", min: 0.9 },
+    latency_ms: { kind: "report" }
+};
+/** Float tolerance for threshold/anchor comparisons (e.g. recall = 2/3). */
+const TOLERANCE = 1e-9;
+/** The quality axes a fixture is gated/anchored on (latency is handled separately). */
+const QUALITY_AXES = ["recall", "source_coverage", "recoverability", "continuation_success"];
+/**
+ * Run every fixture and build the internal sufficiency report. Deterministic apart from the
+ * recorded latency (use an injected clock for reproducible reports).
+ */
+export function evaluateSufficiency(fixtures, thresholds = CONTEXT_STORE_SUFFICIENCY_THRESHOLDS, options = {}) {
+    const hard_failures = [];
+    const warnings = [];
+    const anchor_failures = [];
+    const latency = [];
+    let sufficiencyCount = 0;
+    let adversarialCount = 0;
+    for (const fixture of fixtures) {
+        const result = evaluateContextStoreFixture(fixture, { clock: options.clock });
+        latency.push({ fixture: fixture.name, latency_ms: result.latency_ms }); // report-only
+        const scores = {
+            recall: result.recall,
+            source_coverage: result.source_coverage,
+            recoverability: result.recoverability,
+            continuation_success: result.continuation_success
+        };
+        if ((fixture.role ?? "sufficiency") === "adversarial") {
+            adversarialCount += 1;
+            const expected = fixture.expected ?? {};
+            for (const axis of QUALITY_AXES) {
+                const exp = expected[axis];
+                if (exp !== undefined && Math.abs(scores[axis] - exp) > TOLERANCE) {
+                    anchor_failures.push({ fixture: fixture.name, axis, measured: scores[axis], expected: exp });
+                }
+            }
+        }
+        else {
+            sufficiencyCount += 1;
+            for (const axis of QUALITY_AXES) {
+                const gate = thresholds[axis];
+                if (gate.kind === "report")
+                    continue;
+                if (scores[axis] + TOLERANCE < gate.min) {
+                    if (gate.kind === "hard") {
+                        hard_failures.push({ fixture: fixture.name, axis, measured: scores[axis], min: gate.min });
+                    }
+                    else {
+                        warnings.push({ fixture: fixture.name, axis, measured: scores[axis], min: gate.min });
+                    }
+                }
+            }
+        }
+    }
+    return {
+        version: CONTEXT_STORE_SUFFICIENCY_VERSION,
+        passed: hard_failures.length === 0 && anchor_failures.length === 0,
+        sufficiency_fixtures: sufficiencyCount,
+        adversarial_fixtures: adversarialCount,
+        hard_failures,
+        warnings,
+        anchor_failures,
+        latency
+    };
+}
+function pct(value) {
+    return `${(value * 100).toFixed(1)}%`;
+}
+/**
+ * Internal markdown rendering of the sufficiency report. For local/CI inspection only —
+ * not a user-facing surface and not a claim.
+ */
+export function formatSufficiencyReportMarkdown(report) {
+    const lines = [
+        "## Context-store sufficiency report (INTERNAL — not a claim)",
+        "",
+        `Result: ${report.passed ? "PASS" : "FAIL"} · sufficiency fixtures: ${report.sufficiency_fixtures} · adversarial anchors: ${report.adversarial_fixtures}`,
+        ""
+    ];
+    if (report.hard_failures.length > 0) {
+        lines.push("### Hard-axis failures (FAIL)");
+        for (const f of report.hard_failures) {
+            lines.push(`- ${f.fixture} · ${f.axis}: ${pct(f.measured)} < required ${pct(f.min)}`);
+        }
+        lines.push("");
+    }
+    if (report.anchor_failures.length > 0) {
+        lines.push("### Adversarial anchor drift (FAIL)");
+        for (const f of report.anchor_failures) {
+            lines.push(`- ${f.fixture} · ${f.axis}: measured ${pct(f.measured)} ≠ expected ${pct(f.expected)}`);
+        }
+        lines.push("");
+    }
+    if (report.warnings.length > 0) {
+        lines.push("### Soft warnings (advisory — do not fail)");
+        for (const w of report.warnings) {
+            lines.push(`- ${w.fixture} · ${w.axis}: ${pct(w.measured)} < advisory ${pct(w.min)}`);
+        }
+        lines.push("");
+    }
+    lines.push("_Internal regression gate over synthetic fixtures. Hard axes: recall, source coverage,", "recoverability. Soft (advisory): continuation success (a marker proxy, NOT model replay).", "Latency: recorded only. Passing is NOT evidence of user-facing retrieval correctness,", "savings, semantic preservation, or any large-memory / 300M readiness._");
+    return lines.join("\n");
+}
+//# sourceMappingURL=context-store-sufficiency.js.map

package/dist/core/context-store.d.ts

@@ -0,0 +1,155 @@
+import type { AgentTrace, StateCapsule, StateCapsuleProvenanceEntry } from "./types.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 declare const CONTEXT_STORE_ITEM_VERSION = "context-store-item-v1";
+/**
+ * A single source-pointed context item accumulated in the store.
+ *
+ * `content` is local-only (like a captured trace) and is NEVER uploaded; the store
+ * lives under the gitignored `.compaction/` tree. `content_sha256` is the dedup key.
+ */
+export interface ContextStoreItem {
+    /** Schema version for forward-compatible reads. */
+    version: string;
+    /** SHA-256 of `content` — the dedup key (reuses the fingerprint discipline). */
+    content_sha256: string;
+    /** The retained context text (local-only; never uploaded). */
+    content: string;
+    /** Local token estimate (chars/4) for assembly budgeting. NOT provider-reported. */
+    estimated_tokens: number;
+    /** Recoverable pointer back to the source (kept so assembly stays recoverable). */
+    source_pointer?: string;
+    /** Source recoverability, carried straight from the substrate. */
+    recoverability: boolean | "unknown";
+    /** Per-run distinctness digest (from `computeTraceFingerprint`), if known. */
+    trace_fingerprint?: string;
+    /** The originating trace id, when known (a deterministic retrieval signal). */
+    source_trace_id?: string;
+    /** Provenance entry carried from the state-capsule, when available. */
+    provenance?: StateCapsuleProvenanceEntry;
+    /** Free-form deterministic labels (e.g. "retained_fact", "open_question"). */
+    labels: string[];
+    /** ISO-8601 creation timestamp (recency signal). Stamped at append time. */
+    created_at: string;
+}
+/** Input to `makeContextItem` — everything except the derived hash/token fields. */
+export interface ContextItemInput {
+    content: string;
+    source_pointer?: string;
+    recoverability?: boolean | "unknown";
+    trace_fingerprint?: string;
+    source_trace_id?: string;
+    provenance?: StateCapsuleProvenanceEntry;
+    labels?: string[];
+    created_at: string;
+}
+/**
+ * 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 declare function makeContextItem(input: ContextItemInput): ContextStoreItem;
+/**
+ * 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 declare function contextItemsFromCapsule(capsule: StateCapsule, opts: {
+    created_at: string;
+    trace_fingerprint?: string;
+}): ContextStoreItem[];
+/**
+ * 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 declare function contextItemsFromTrace(trace: AgentTrace, opts: {
+    created_at: string;
+}): ContextStoreItem[];
+/**
+ * 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 declare function dedupeContextItems(items: ContextStoreItem[]): ContextStoreItem[];
+/** A retrieval query: the current step's context + optional source/trace hints. */
+export interface RetrievalQuery {
+    /** Free text describing the current step (task, recent messages, etc.). */
+    text: string;
+    /** Source pointers known to be relevant to the current step (exact-match boost). */
+    source_pointers?: string[];
+    /** Trace ids known to be relevant to the current step (exact-match boost). */
+    trace_ids?: string[];
+}
+export interface RetrievalOptions {
+    /** Max items to return (after ranking). Default: all candidates with score > 0. */
+    limit?: number;
+    /** Weight on exact source-pointer / trace-id match. Default 1. */
+    sourceMatchWeight?: number;
+    /** Weight on lexical overlap (overlap coefficient in [0,1]). Default 1. */
+    lexicalWeight?: number;
+}
+export interface RankedContextItem {
+    item: ContextStoreItem;
+    score: number;
+    source_match: boolean;
+    lexical_overlap: number;
+}
+/**
+ * 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 declare function retrieveContextItems(items: ContextStoreItem[], query: RetrievalQuery, options?: RetrievalOptions): RankedContextItem[];
+export interface AssembleOptions {
+    /** Token budget for the assembled context (local estimate). */
+    tokenBudget: number;
+}
+export interface AssembledContext {
+    /** The assembled context text (included items joined, in ranked order). */
+    text: string;
+    /** Items that fit within the budget (provenance preserved on each). */
+    included: ContextStoreItem[];
+    /** Items dropped because the budget was exhausted (still recoverable from source). */
+    dropped: ContextStoreItem[];
+    /** Local token estimate of the assembled context. */
+    estimated_tokens: number;
+    /** Whether everything offered fit within the budget. */
+    within_budget: boolean;
+}
+/**
+ * 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 declare function assembleContext(ranked: Array<RankedContextItem | ContextStoreItem>, options: AssembleOptions): AssembledContext;

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,5 +1,5 @@
 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,
@@ -14,6 +14,24 @@ import type { UsageMetadata } from "./usage-metadata.js";
  * 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

@@ -16,6 +16,56 @@ import { computeTraceFingerprint } from "./trace-fingerprint.js";
 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)`;
 }
@@ -217,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

@@ -35,8 +35,44 @@ 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[];
@@ -54,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;