@compaction/cli 0.1.4 → 0.3.0

package/dist/core/policy-preferences.d.ts

@@ -0,0 +1,99 @@
+/** Default local preference file (under the gitignored `.compaction/`). */
+export declare const DEFAULT_POLICY_PREFERENCES_DIRECTORY = ".compaction";
+export declare const POLICY_PREFERENCES_FILENAME = "policy-preferences.json";
+/** The binary preference (mirror of `AUTO_APPLY_PREFERENCES` in activity-event.ts). Default = ask. */
+export declare const POLICY_PREFERENCE_VALUES: readonly ["ask-each-time", "auto-when-gates-pass"];
+export type PolicyPreferenceValue = (typeof POLICY_PREFERENCE_VALUES)[number];
+/** Tool values that are NEVER an allowed scope — a preference is never global or cross-tool. */
+export declare const REJECTED_GLOBAL_TOOL_VALUES: readonly string[];
+/**
+ * The safety gates a preference's auto-apply WOULD require (founder decision: "explicit opt-in +
+ * matching scope + original retained + capsule provenance + recoverability pass + threshold + risk
+ * checks + evidence label emitted + rollback path"). POPULATED for provenance/explanation; NOT
+ * EVALUATED this cycle — no gate engine exists, so no preference can drive an application.
+ */
+export declare const DEFAULT_GATES_REQUIRED: readonly string[];
+/** The inferred safest scope of a preference: one tool/workflow, optionally one repo, one policy type. */
+export interface PolicyPreferenceScope {
+    /** REQUIRED. The workflow/tool this preference is scoped to (never "global"/"all"/cross-tool). */
+    tool: string;
+    /** OPTIONAL. The repo the preference is scoped to, when detectable (content-free identifier). */
+    repo?: string;
+    /** REQUIRED. Which policy type this preference concerns (content-free identifier). */
+    policy_type: string;
+}
+/** One stored preference record. Content-free; no wall-clock; id is deterministic over the scope. */
+export interface PolicyPreference {
+    /** Deterministic content-free id: `pref-` + 24 hex of sha-256 over the canonical scope. */
+    id: string;
+    scope: PolicyPreferenceScope;
+    preference: PolicyPreferenceValue;
+    /** Whether this preference is live. `disable` sets this false; there is NO enable in the CLI. */
+    enabled: boolean;
+    /** Safety gates the (future) gated auto-apply slice would require. POPULATED, NOT EVALUATED here. */
+    gates_required: string[];
+}
+/** Input to save a preference — id, enabled default, and gates_required are derived when absent. */
+export interface SavePolicyPreferenceInput {
+    scope: PolicyPreferenceScope;
+    preference: PolicyPreferenceValue;
+    /** Defaults to true (the record is stored so the future live ask can honor it); disable turns it off. */
+    enabled?: boolean;
+    /** Defaults to `DEFAULT_GATES_REQUIRED`; a caller may pass a narrower list (never evaluated here). */
+    gates_required?: string[];
+}
+export interface PolicyPreferenceValidation {
+    problems: string[];
+}
+/** The longest a content-free scope/gate identifier may be — anything longer looks like content. */
+export declare const POLICY_PREFERENCE_MAX_STRING_LENGTH = 200;
+/**
+ * Validate a scope: `tool` and `policy_type` REQUIRED and content-free; `repo` optional; the tool
+ * is NEVER a global/all/cross-tool value (case-insensitive). Report-only (never throws).
+ */
+export declare function validatePolicyPreferenceScope(scope: unknown): PolicyPreferenceValidation;
+/** Deterministic content-free id over the scope only (so a scope has ONE preference record). */
+export declare function computePolicyPreferenceId(scope: PolicyPreferenceScope): string;
+export declare const POLICY_PREFERENCE_ID_PATTERN: RegExp;
+/** Read all stored preferences. A missing file means "none saved yet" (empty, not an error). */
+export declare function readPolicyPreferences(directory?: string): Promise<{
+    preferences: PolicyPreference[];
+}>;
+export type SavePolicyPreferenceResult = {
+    saved: true;
+    preference: PolicyPreference;
+    path: string;
+    replacedExisting: boolean;
+} | {
+    saved: false;
+    problems: string[];
+};
+/**
+ * Save (upsert by deterministic scope id) ONE preference to the local store. Fail-closed: an
+ * invalid scope saves NOTHING. THIS DOES NOT APPLY ANYTHING — it writes one JSON file and returns;
+ * there is no application path here (proven by the fail-closed test).
+ */
+export declare function savePolicyPreference(input: SavePolicyPreferenceInput, directory?: string): Promise<SavePolicyPreferenceResult>;
+export type DisablePolicyPreferenceResult = {
+    disabled: true;
+    preference: PolicyPreference;
+    path: string;
+    alreadyDisabled: boolean;
+} | {
+    disabled: false;
+    reason: string;
+};
+/**
+ * Disable a preference by id (set enabled=false). The safe management verb — disabling can only
+ * ever REDUCE what could apply, so it is always safe. Unknown id → a clear error, nothing changed.
+ * Idempotent: disabling an already-disabled preference is a reported no-op (no throw).
+ */
+export declare function disablePolicyPreference(id: string, directory?: string): Promise<DisablePolicyPreferenceResult>;
+/** Look up one preference by id (read-only). */
+export declare function findPolicyPreference(id: string, directory?: string): Promise<PolicyPreference | undefined>;
+/**
+ * Plain-language explanation of what a preference MEANS — honest that auto-apply is NOT YET ACTIVE
+ * (the preference is stored; application is pending the gated auto-apply slice, which does not
+ * exist yet). No wall-clock, no content — scope, policy, gates, recovery, and how to disable.
+ */
+export declare function explainPolicyPreference(preference: PolicyPreference): string;

package/dist/core/policy-preferences.js

@@ -0,0 +1,232 @@
+/**
+ * LOCAL auto-apply PREFERENCE store (charter 2026-07-04-run-7, lane 4: "compaction policies
+ * list/disable/explain" + "auto-apply preference model: binary ask-after-approve, inferred safest
+ * scope, fail-closed gates scaffold, tests proving OFF by default").
+ *
+ * WHAT THIS IS — and, more importantly, WHAT IT IS NOT:
+ * This module STORES and READS a user's binary auto-apply *preference* (the one the founder's live
+ * post-approval ask would save: "Apply this automatically next time for this workflow when safety
+ * gates pass? [yes/no, default no]"). It is a PREFERENCE record only. It is NOT an application
+ * engine:
+ *
+ *   FAIL-CLOSED INVARIANT: a preference EXISTING (even enabled=true, even
+ *   preference="auto-when-gates-pass") does NOT cause anything to be applied anywhere. There is no
+ *   apply path in this module — it imports nothing that mutates a user session, trace, run record,
+ *   or context, and it exports no apply function. `gates_required` is POPULATED but NEVER EVALUATED
+ *   this cycle (no gate engine exists). Proven by `tests/core/policy-preferences.test.ts`
+ *   (the fail-closed proof: saving/enabling a preference mutates ONLY this store's JSON file and
+ *   invokes no application).
+ *
+ * SCOPE IS NEVER GLOBAL AND NEVER CROSS-TOOL (founder decision): `tool` is REQUIRED, and a
+ * "global"/"all"/"*" tool value is REJECTED at validation. A preference is always scoped to one
+ * workflow/tool (+ repo where detectable + policy type).
+ *
+ * NO WALL-CLOCK: the record carries no `created_at` — the id is DETERMINISTIC over the scope, so
+ * the same scope always maps to the same preference record (an upsert key, content-free).
+ *
+ * LOCAL FILE I/O ONLY: one JSON file under `.compaction/` (already gitignored). No network, no new
+ * dependencies.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/** Default local preference file (under the gitignored `.compaction/`). */
+export const DEFAULT_POLICY_PREFERENCES_DIRECTORY = ".compaction";
+export const POLICY_PREFERENCES_FILENAME = "policy-preferences.json";
+/** The binary preference (mirror of `AUTO_APPLY_PREFERENCES` in activity-event.ts). Default = ask. */
+export const POLICY_PREFERENCE_VALUES = ["ask-each-time", "auto-when-gates-pass"];
+/** Tool values that are NEVER an allowed scope — a preference is never global or cross-tool. */
+export const REJECTED_GLOBAL_TOOL_VALUES = ["global", "all", "*", "any", "cross-tool"];
+/**
+ * The safety gates a preference's auto-apply WOULD require (founder decision: "explicit opt-in +
+ * matching scope + original retained + capsule provenance + recoverability pass + threshold + risk
+ * checks + evidence label emitted + rollback path"). POPULATED for provenance/explanation; NOT
+ * EVALUATED this cycle — no gate engine exists, so no preference can drive an application.
+ */
+export const DEFAULT_GATES_REQUIRED = [
+    "scope-match",
+    "original-retained",
+    "capsule-provenance",
+    "recoverability-pass",
+    "reduction-threshold",
+    "risk-checks",
+    "evidence-label-emitted",
+    "rollback-path"
+];
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+/** The longest a content-free scope/gate identifier may be — anything longer looks like content. */
+export const POLICY_PREFERENCE_MAX_STRING_LENGTH = 200;
+/**
+ * Validate a scope: `tool` and `policy_type` REQUIRED and content-free; `repo` optional; the tool
+ * is NEVER a global/all/cross-tool value (case-insensitive). Report-only (never throws).
+ */
+export function validatePolicyPreferenceScope(scope) {
+    const problems = [];
+    if (typeof scope !== "object" || scope === null || Array.isArray(scope)) {
+        return { problems: ["scope: must be an object ({ tool, repo?, policy_type })"] };
+    }
+    const record = scope;
+    if (!isNonEmptyString(record.tool)) {
+        problems.push("scope.tool: required — a preference is always scoped to one workflow/tool (never global)");
+    }
+    else if (REJECTED_GLOBAL_TOOL_VALUES.includes(record.tool.trim().toLowerCase())) {
+        problems.push(`scope.tool: "${record.tool}" is rejected — a preference is NEVER global and NEVER cross-tool (founder rule); scope it to one tool`);
+    }
+    if (!isNonEmptyString(record.policy_type)) {
+        problems.push("scope.policy_type: required — which policy this preference concerns (content-free identifier)");
+    }
+    if (record.repo !== undefined && !isNonEmptyString(record.repo)) {
+        problems.push("scope.repo: when present, must be a non-empty content-free repo identifier");
+    }
+    for (const [key, value] of Object.entries(record)) {
+        if (!["tool", "repo", "policy_type"].includes(key)) {
+            problems.push(`scope.${key}: not an allowed scope field (only tool, repo, policy_type)`);
+            continue;
+        }
+        if (typeof value === "string" && value.length > POLICY_PREFERENCE_MAX_STRING_LENGTH) {
+            problems.push(`scope.${key}: string exceeds the content-free bound (${value.length} chars) — that is content-sized`);
+        }
+    }
+    return { problems };
+}
+/** Deterministic content-free id over the scope only (so a scope has ONE preference record). */
+export function computePolicyPreferenceId(scope) {
+    const canonical = JSON.stringify({
+        policy_type: scope.policy_type,
+        repo: scope.repo ?? null,
+        tool: scope.tool
+    });
+    const digest = createHash("sha256").update(canonical).digest("hex");
+    return `pref-${digest.slice(0, 24)}`;
+}
+export const POLICY_PREFERENCE_ID_PATTERN = /^pref-[0-9a-f]{24}$/;
+function preferencesPath(directory) {
+    return join(directory, POLICY_PREFERENCES_FILENAME);
+}
+/** Read all stored preferences. A missing file means "none saved yet" (empty, not an error). */
+export async function readPolicyPreferences(directory = DEFAULT_POLICY_PREFERENCES_DIRECTORY) {
+    let raw;
+    try {
+        raw = await readFile(preferencesPath(directory), "utf8");
+    }
+    catch (error) {
+        const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "unknown";
+        if (code === "ENOENT")
+            return { preferences: [] };
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${preferencesPath(directory)} is not valid JSON — refusing to guess (fail-closed)`);
+    }
+    const list = Array.isArray(parsed)
+        ? parsed
+        : typeof parsed === "object" && parsed !== null && Array.isArray(parsed.preferences)
+            ? parsed.preferences
+            : [];
+    const preferences = list.filter((entry) => {
+        if (typeof entry !== "object" || entry === null)
+            return false;
+        const candidate = entry;
+        return (typeof candidate.id === "string" &&
+            typeof candidate.enabled === "boolean" &&
+            POLICY_PREFERENCE_VALUES.includes(candidate.preference) &&
+            validatePolicyPreferenceScope(candidate.scope).problems.length === 0);
+    });
+    return { preferences };
+}
+/**
+ * Save (upsert by deterministic scope id) ONE preference to the local store. Fail-closed: an
+ * invalid scope saves NOTHING. THIS DOES NOT APPLY ANYTHING — it writes one JSON file and returns;
+ * there is no application path here (proven by the fail-closed test).
+ */
+export async function savePolicyPreference(input, directory = DEFAULT_POLICY_PREFERENCES_DIRECTORY) {
+    const problems = validatePolicyPreferenceScope(input.scope).problems;
+    if (!POLICY_PREFERENCE_VALUES.includes(input.preference)) {
+        problems.push(`preference: must be one of ${POLICY_PREFERENCE_VALUES.join(" | ")} (exact)`);
+    }
+    if (problems.length > 0)
+        return { saved: false, problems };
+    const scope = {
+        tool: input.scope.tool,
+        policy_type: input.scope.policy_type,
+        ...(input.scope.repo !== undefined ? { repo: input.scope.repo } : {})
+    };
+    const record = {
+        id: computePolicyPreferenceId(scope),
+        scope,
+        preference: input.preference,
+        enabled: input.enabled ?? true,
+        gates_required: input.gates_required ? [...input.gates_required] : [...DEFAULT_GATES_REQUIRED]
+    };
+    const { preferences } = await readPolicyPreferences(directory);
+    const existingIndex = preferences.findIndex((entry) => entry.id === record.id);
+    const replacedExisting = existingIndex >= 0;
+    const next = replacedExisting
+        ? preferences.map((entry, index) => (index === existingIndex ? record : entry))
+        : [...preferences, record];
+    const path = preferencesPath(directory);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify({ preferences: next }, null, 2)}\n`, "utf8");
+    return { saved: true, preference: record, path, replacedExisting };
+}
+/**
+ * Disable a preference by id (set enabled=false). The safe management verb — disabling can only
+ * ever REDUCE what could apply, so it is always safe. Unknown id → a clear error, nothing changed.
+ * Idempotent: disabling an already-disabled preference is a reported no-op (no throw).
+ */
+export async function disablePolicyPreference(id, directory = DEFAULT_POLICY_PREFERENCES_DIRECTORY) {
+    const { preferences } = await readPolicyPreferences(directory);
+    const index = preferences.findIndex((entry) => entry.id === id);
+    if (index < 0) {
+        return { disabled: false, reason: `no preference with id "${id}" — nothing changed (run "compaction policies list")` };
+    }
+    const target = preferences[index];
+    if (target.enabled === false) {
+        return { disabled: true, preference: target, path: preferencesPath(directory), alreadyDisabled: true };
+    }
+    const updated = { ...target, enabled: false };
+    const next = preferences.map((entry, i) => (i === index ? updated : entry));
+    const path = preferencesPath(directory);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify({ preferences: next }, null, 2)}\n`, "utf8");
+    return { disabled: true, preference: updated, path, alreadyDisabled: false };
+}
+/** Look up one preference by id (read-only). */
+export async function findPolicyPreference(id, directory = DEFAULT_POLICY_PREFERENCES_DIRECTORY) {
+    const { preferences } = await readPolicyPreferences(directory);
+    return preferences.find((entry) => entry.id === id);
+}
+/**
+ * Plain-language explanation of what a preference MEANS — honest that auto-apply is NOT YET ACTIVE
+ * (the preference is stored; application is pending the gated auto-apply slice, which does not
+ * exist yet). No wall-clock, no content — scope, policy, gates, recovery, and how to disable.
+ */
+export function explainPolicyPreference(preference) {
+    const scopeLine = preference.scope.repo
+        ? `the "${preference.scope.tool}" workflow in repo "${preference.scope.repo}"`
+        : `the "${preference.scope.tool}" workflow`;
+    const lines = [
+        `Preference ${preference.id}`,
+        ``,
+        `Scope:      ${scopeLine}`,
+        `Policy:     ${preference.scope.policy_type}`,
+        `Preference: ${preference.preference}`,
+        `Enabled:    ${preference.enabled ? "yes" : "no (disabled)"}`,
+        ``
+    ];
+    if (preference.preference === "auto-when-gates-pass") {
+        lines.push(`What it would mean: for ${scopeLine}, you chose "apply automatically next time WHEN ALL`, `safety gates pass". Auto-apply would happen ONLY if every one of these gates passes:`, ...preference.gates_required.map((gate) => `  - ${gate}`), ``, `NOT YET ACTIVE: no auto-apply engine exists yet. This preference is STORED only; nothing is`, `applied automatically today. When the gated auto-apply slice ships, an application will run`, `ONLY inside these gates, the original will be retained, and every application will be`, `recoverable and logged with an evidence label.`);
+    }
+    else {
+        lines.push(`What it means: for ${scopeLine}, Compaction ASKS every time before applying anything`, `(the default). Nothing is ever applied automatically under this preference.`);
+    }
+    lines.push(``, `Originals are always retained; every application (once the gated slice exists) is reversible.`, `To turn this preference off:  compaction policies disable ${preference.id}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=policy-preferences.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

@@ -1,3 +1,4 @@
+import { type PerToolRunRecordRollup } from "./local-run-record.js";
 import type { CompactionReport, WasteFinding } from "./types.js";
 /**
  * Duplicate-safety summary for the `summary` rollup, by content fingerprint. A count of DISTINCT
@@ -35,8 +36,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[];
@@ -47,6 +84,15 @@ export interface RunSummary extends RunSummaryBucket {
      * are never inflated. Runs without a fingerprint are each counted as distinct.
      */
     distinctness: RunDistinctnessSummary;
+    /**
+     * ADDITIVE (unified-run-flow LOCAL layer, 2026-07-02): per-tool rollup of the locally accumulated
+     * per-run token_source records (`.compaction/run-records/*.json`). Observed token COUNTS + their
+     * honest per-axis `token_source` tiers ONLY (mirrors docs/ops/app-source-status-contract.md) —
+     * no cost figures, and `output_savings` is the LITERAL "unavailable" for every tool (gated).
+     */
+    per_tool_token_records: PerToolRunRecordRollup[];
+    run_records_source_glob: string;
+    run_record_skipped_files: SkippedReportFile[];
     generated_at: string;
     source_glob: string;
 }
@@ -54,6 +100,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;
@@ -63,7 +118,7 @@ export declare function readCompactionRunReports(runsDirectory?: string): Promis
     skippedFiles: SkippedReportFile[];
 }>;
 export declare function aggregateCompactionReports(reports: LoadedReport[], skippedFiles?: SkippedReportFile[], generatedAt?: string, sourceGlob?: string): RunSummary;
-export declare function createRunSummary(runsDirectory?: string): Promise<RunSummary>;
+export declare function createRunSummary(runsDirectory?: string, recordsDirectory?: string): Promise<RunSummary>;
 export declare function formatRunSummary(summary: RunSummary): string;
 export declare function formatRunSummaryMarkdown(summary: RunSummary): string;
 export {};