@compaction/cli 0.1.0

package/dist/core/report-generator.js

@@ -0,0 +1,275 @@
+import { calculateCost } from "./cost-calculator.js";
+import { isKnownModel } from "./pricing.js";
+function formatTokenBreakdown(tokens) {
+    return `${tokens.totalTokens} total (${tokens.inputTokens} input, ${tokens.outputTokens} output)`;
+}
+function formatFindings(findings) {
+    if (findings.length === 0) {
+        return ["Waste findings: none detected by the conservative v0 rules."];
+    }
+    return [
+        `Waste findings: ${findings.length}`,
+        ...findings.map((finding, index) => `${index + 1}. ${finding.category}: ${finding.summary} (${finding.estimatedTokens} estimated tokens; messages ${finding.messageIds.join(", ")})`)
+    ];
+}
+function placeholderPricingWarning(model) {
+    return isKnownModel(model) ? null : "Note: cost figures use placeholder pricing — model not in local price table.";
+}
+function sumWastedInputTokens(findings) {
+    return findings.reduce((total, f) => total + f.estimatedTokens, 0);
+}
+function formatPostCompactionCostLines(model, tokens, cost, findings, cache) {
+    if (findings.length === 0) {
+        return [];
+    }
+    const wastedInputTokens = sumWastedInputTokens(findings);
+    const postCompactionTokens = {
+        inputTokens: Math.max(0, tokens.inputTokens - wastedInputTokens),
+        outputTokens: tokens.outputTokens,
+        totalTokens: Math.max(0, tokens.totalTokens - wastedInputTokens)
+    };
+    const postCompactionCost = calculateCost(model, postCompactionTokens, cache);
+    const savingPerRun = cost.totalCostUsd - postCompactionCost.totalCostUsd;
+    return [
+        `Estimated cost after compaction: $${postCompactionCost.totalCostUsd.toFixed(6)} (estimated)`,
+        `  Saving per run: $${savingPerRun.toFixed(6)} (estimated)`
+    ];
+}
+function formatCacheAwareCostLines(cost, tokens, usage) {
+    const hasCacheRead = (usage?.cache_read_input_tokens ?? 0) > 0;
+    const hasCacheCreation = (usage?.cache_creation_input_tokens ?? 0) > 0;
+    const hasCacheData = hasCacheRead || hasCacheCreation;
+    if (!hasCacheData) {
+        return [`Estimated cost: $${cost.totalCostUsd.toFixed(6)} ($${cost.inputCostUsd.toFixed(6)} input, $${cost.outputCostUsd.toFixed(6)} output)`];
+    }
+    const lines = [];
+    lines.push(`Estimated cost (cache-adjusted estimate): $${cost.totalCostUsd.toFixed(6)}`);
+    // Use estimated input tokens from TokenEstimate — these match the cost figure.
+    // usage.input_tokens is the provider-reported count (different from the estimated count used for cost).
+    lines.push(`  Standard input: $${cost.inputCostUsd.toFixed(6)} (${tokens.inputTokens} estimated tokens at standard rate)`);
+    lines.push(`  Output: $${cost.outputCostUsd.toFixed(6)}`);
+    if (hasCacheRead && cost.cacheReadCostUsd !== undefined) {
+        lines.push(`  Cache read: $${cost.cacheReadCostUsd.toFixed(6)} (${usage.cache_read_input_tokens} tokens at ~10% of input rate — estimated)`);
+    }
+    if (hasCacheCreation && cost.cacheCreationCostUsd !== undefined) {
+        lines.push(`  Cache creation: $${cost.cacheCreationCostUsd.toFixed(6)} (${usage.cache_creation_input_tokens} tokens at ~125% of input rate — estimated)`);
+    }
+    return lines;
+}
+/**
+ * Render the report-only skill-injection advisory section. This is ADVISORY: it is
+ * distinct from the actual compaction summary and nothing is compacted. All token
+ * figures are estimated (chars/4), not billing-confirmed, not realized, not applied.
+ */
+function formatSkillInjectionAdvisory(advisory) {
+    if (!advisory) {
+        return [];
+    }
+    const lines = [
+        "",
+        "Skill-injection repetition (ADVISORY — report-only; nothing compacted)",
+        `  Label: ${advisory.estimate_label}`
+    ];
+    if (advisory.skills.length === 0) {
+        lines.push("  No repeated byte-identical same-skill role:user injections detected.");
+        return lines;
+    }
+    lines.push(`  Retained first copies: ${advisory.first_copy_count}`, `  Redundant byte-identical copies: ${advisory.total_redundant_byte_identical_copies}`, `  Total addressable (est, chars/4): ${advisory.total_addressable_estimated_tokens} tokens`, "  Per-skill attribution (redundant byte-identical copies / est tokens):");
+    for (const skill of advisory.skills) {
+        lines.push(`    - ${skill.skill_name}: ${skill.redundant_byte_identical_copies} copies, ${skill.estimated_tokens} est tokens`);
+    }
+    lines.push(`  Recommendation: ${advisory.recommendation}`);
+    return lines;
+}
+export function formatAnalyzeReport(trace, tokens, cost, findings = [], usage, skillInjectionAdvisory) {
+    return [
+        `Trace: ${trace.title} (${trace.id})`,
+        `Model: ${trace.model}`,
+        `Source: ${trace.source}`,
+        trace.command ? `Command: ${trace.command.command} ${trace.command.args.join(" ")}`.trim() : null,
+        trace.durationMs === undefined ? null : `Duration: ${trace.durationMs} ms`,
+        trace.exitCode === undefined ? null : `Exit code: ${trace.exitCode}`,
+        `Messages: ${trace.messages.length}`,
+        `Estimated tokens: ${formatTokenBreakdown(tokens)}`,
+        placeholderPricingWarning(trace.model),
+        ...formatCacheAwareCostLines(cost, tokens, usage),
+        ...formatPostCompactionCostLines(trace.model, tokens, cost, findings, {
+            cacheReadTokens: usage?.cache_read_input_tokens,
+            cacheCreationTokens: usage?.cache_creation_input_tokens
+        }),
+        ...formatFindings(findings),
+        "Suggested compaction: remove duplicate tool outputs only when an earlier identical copy remains in the trace.",
+        ...formatSkillInjectionAdvisory(skillInjectionAdvisory)
+    ].filter((line) => line !== null).join("\n");
+}
+export function formatCompactionReport(report) {
+    return [
+        `Run: ${report.run_id}`,
+        `Trace: ${report.trace_title}`,
+        `Model: ${report.model}`,
+        placeholderPricingWarning(report.model),
+        `Original input tokens: ${report.original_input_tokens}`,
+        `Compacted input tokens: ${report.compacted_input_tokens}`,
+        `${report.savings_scope === "policy_level" ? "Policy-level tokens saved" : "Tokens saved"}: ${report.tokens_saved} (${report.percent_reduction.toFixed(2)}% reduction)`,
+        `Cost before per run: $${report.cost_before_per_run.toFixed(6)} (estimated)`,
+        `Cost after per run: $${report.cost_after_per_run.toFixed(6)} (estimated)`,
+        `Savings per run: $${report.saving_per_run.toFixed(6)} (estimated)`,
+        `Policy: ${report.policy_name}`,
+        `Waste pattern: ${report.waste_pattern ?? "none"}`,
+        `Compacted messages: ${report.compacted_message_ids.length === 0 ? "none" : report.compacted_message_ids.join(", ")}`
+    ].filter((line) => line !== null).join("\n");
+}
+/**
+ * Render the value-proof tier classification for the human-facing report. This
+ * classifies the already-reported token/cost deltas against the four ROADMAP
+ * "MVP value path" claims (strongest last, never conflated). It adds no new
+ * numbers and makes no new/stronger claim — it states plainly that tier 3
+ * (billing-confirmed) is NOT claimed and tier 4 (fixed-plan) is NOT quantified.
+ */
+function formatValueProofLines(report) {
+    const vp = report.value_proof;
+    if (!vp) {
+        return [];
+    }
+    return [
+        "",
+        "## Value Proof (ROADMAP tiers — strongest last, not conflated)",
+        "",
+        `- Tier 1 — ${vp.trace_token_reduction.claim}: ${vp.trace_token_reduction.tokens_saved} tokens (${vp.trace_token_reduction.percent_reduction.toFixed(2)}% reduction).`,
+        `- Tier 2 — ${vp.estimated_provider_cost_reduction.claim}: $${vp.estimated_provider_cost_reduction.saving_per_run_usd.toFixed(6)}/run (estimated).`,
+        `- Tier 3 — ${vp.billing_confirmed_savings.claim}: ${vp.billing_confirmed_savings.note}`,
+        `- Tier 4 — ${vp.fixed_plan_workflow_extension_value.claim}: ${vp.fixed_plan_workflow_extension_value.note}`
+    ];
+}
+/**
+ * Render the concise "Where spend came from (estimated)" section for report.md. This
+ * reuses the spend_by_source summary already computed via the spend-attribution module.
+ * Figures are LOCAL ESTIMATES (chars/4 trace tokens / price-table cost) — clearly NOT
+ * billing-confirmed and NOT realized savings. Consistent with the value-proof tiers
+ * (tier-1 trace-token estimates / tier-2 price-table cost estimates).
+ */
+function formatSpendBySourceLines(report) {
+    const spend = report.spend_by_source;
+    if (!spend) {
+        return [];
+    }
+    const roleRows = spend.top_roles.length === 0
+        ? ["- No role/category spend attributed."]
+        : spend.top_roles.map((role) => `- ${role.name}: ${role.estimated_tokens} est tokens ($${role.estimated_cost_usd.toFixed(6)} est)`);
+    const toolRows = spend.top_tool_outputs.length === 0
+        ? ["- No repeated tool-output spend attributed."]
+        : spend.top_tool_outputs.map((tool) => `- ${tool.tool_name}: ${tool.estimated_tokens} est tokens across ${tool.repeated_count} output(s) ($${tool.estimated_cost_usd.toFixed(6)} est)`);
+    return [
+        "",
+        "## Where Spend Came From (estimated)",
+        "",
+        "> ESTIMATED: chars/4 trace-token heuristic and price-table cost. These show where estimated context spend comes from — NOT billing-confirmed, NOT realized savings.",
+        "",
+        "Top sources by est tokens — roles/categories:",
+        ...roleRows,
+        "",
+        "Top sources by est tokens — repeated tool outputs:",
+        ...toolRows,
+        "",
+        spend.top_policy_candidate
+            ? `Top policy candidate: ${spend.top_policy_candidate.policy_name} (${spend.top_policy_candidate.estimated_tokens_saved} est tokens saved, $${spend.top_policy_candidate.estimated_saving_per_run_usd.toFixed(6)} est/run)`
+            : "Top policy candidate: none"
+    ];
+}
+export function formatCompactionMarkdownReport(report, policy) {
+    const pricingNote = placeholderPricingWarning(report.model);
+    return [
+        `# Compaction Report: ${report.trace_title}`,
+        "",
+        "## Summary",
+        "",
+        `- Run ID: ${report.run_id}`,
+        `- Model: ${report.model}`,
+        `- Artifact version: ${report.artifact_version}`,
+        `- Created at: ${report.created_at}`,
+        `- Generated at: ${report.generated_at}`,
+        pricingNote ? `\n> ${pricingNote}` : null,
+        "",
+        "## Savings",
+        "",
+        `- Original input tokens: ${report.original_input_tokens}`,
+        `- Compacted input tokens: ${report.compacted_input_tokens}`,
+        `${report.savings_scope === "policy_level" ? "- Policy-level tokens saved" : "- Tokens saved"}: ${report.tokens_saved}`,
+        `- Percent reduction: ${report.percent_reduction.toFixed(2)}%`,
+        `- Cost before per run: $${report.cost_before_per_run.toFixed(6)} (estimated)`,
+        `- Cost after per run: $${report.cost_after_per_run.toFixed(6)} (estimated)`,
+        `- Saving per run: $${report.saving_per_run.toFixed(6)} (estimated)`,
+        ...formatValueProofLines(report),
+        ...formatSpendBySourceLines(report),
+        "",
+        "## Waste Pattern",
+        "",
+        `- Policy: ${report.policy_name}`,
+        `- Pattern: ${report.waste_pattern ?? "none"}`,
+        `- Source message: ${report.source_message_id ?? "none"}`,
+        `- Repeated finding message count: ${report.repeated_count}`,
+        `- Compacted messages: ${report.compacted_message_ids.length === 0 ? "none" : report.compacted_message_ids.join(", ")}`,
+        "",
+        "## Policy",
+        "",
+        `- Version: ${policy.policy_version}`,
+        `- Trigger: ${policy.trigger}`,
+        `- Condition: ${policy.condition}`,
+        `- Action: ${policy.action}`,
+        `- Expected savings: ${policy.expected_savings}`,
+        "",
+        "## Safety Guarantees",
+        "",
+        ...policy.safety_guarantees.map((guarantee) => `- ${guarantee}`),
+        "",
+        "## Risk Notes",
+        "",
+        ...policy.risk_notes.map((note) => `- ${note}`)
+    ].filter((line) => line !== null).join("\n");
+}
+export function formatPrCommentReport(report, policy, artifactNames) {
+    const riskOrSafetyNote = policy.risk_notes[0] ?? policy.safety_guarantees[0] ?? "Review the compacted trace before applying this policy.";
+    const pricingNote = placeholderPricingWarning(report.model);
+    return [
+        "## compaction.dev summary",
+        "",
+        `Trace title: ${report.trace_title}`,
+        `Model: ${report.model}`,
+        pricingNote ? `> ${pricingNote}` : null,
+        "",
+        "### Token savings",
+        "",
+        `- Before input tokens: ${report.original_input_tokens}`,
+        `- After input tokens: ${report.compacted_input_tokens}`,
+        `${report.savings_scope === "policy_level" ? "- Policy-level tokens saved" : "- Tokens saved"}: ${report.tokens_saved}`,
+        `- Percent reduction: ${report.percent_reduction.toFixed(2)}%`,
+        "",
+        "### Cost impact",
+        "",
+        `- Cost before per run: $${report.cost_before_per_run.toFixed(6)} (estimated)`,
+        `- Cost after per run: $${report.cost_after_per_run.toFixed(6)} (estimated)`,
+        `- Saving per run: $${report.saving_per_run.toFixed(6)} (estimated)`,
+        ...(report.value_proof
+            ? [
+                "",
+                "### Value-proof tiers (strongest last, not conflated)",
+                "",
+                `- Tier 1 — ${report.value_proof.trace_token_reduction.claim}.`,
+                `- Tier 2 — ${report.value_proof.estimated_provider_cost_reduction.claim}.`,
+                `- Tier 3 — billing-confirmed savings: NOT claimed (no provider usage/billing delta measured).`,
+                `- Tier 4 — fixed-plan workflow-extension value: NOT quantified here.`
+            ]
+            : []),
+        "",
+        "### Policy and safety",
+        "",
+        `- Policy applied: ${policy.policy_name}`,
+        `- Waste pattern: ${report.waste_pattern ?? "none"}`,
+        `- Risk level or safety note: ${riskOrSafetyNote}`,
+        "",
+        "### Generated artifacts",
+        "",
+        ...artifactNames.map((artifactName) => `- ${artifactName}`)
+    ].filter((line) => line !== null).join("\n");
+}
+//# sourceMappingURL=report-generator.js.map

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

@@ -0,0 +1,50 @@
+import type { CompactionReport, WasteFinding } from "./types.js";
+export interface RunSummaryBucket {
+    total_runs: number;
+    total_original_input_tokens: number;
+    total_compacted_input_tokens: number;
+    total_tokens_saved: number;
+    total_cost_before_per_run: number;
+    total_cost_after_per_run: number;
+    total_saving_per_run: number;
+}
+export interface TopSavingsRun {
+    run_id: string;
+    trace_title: string;
+    report_path: string;
+    tokens_saved: number;
+    percent_reduction: number;
+    saving_per_run: number;
+    policy_name: string;
+    waste_pattern: WasteFinding["category"] | null;
+}
+export interface SkippedReportFile {
+    path: string;
+    reason: string;
+}
+export interface RunSummary extends RunSummaryBucket {
+    average_percent_reduction: number;
+    savings_by_policy: Record<string, RunSummaryBucket>;
+    savings_by_waste_pattern: Record<string, RunSummaryBucket>;
+    top_savings_runs: TopSavingsRun[];
+    skipped_files: SkippedReportFile[];
+    generated_at: string;
+    source_glob: string;
+}
+interface LoadedReport {
+    path: string;
+    report: CompactionReport;
+}
+export declare function validateCompactionReport(value: unknown): {
+    report?: CompactionReport;
+    reason?: string;
+};
+export declare function readCompactionRunReports(runsDirectory?: string): Promise<{
+    reports: LoadedReport[];
+    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 formatRunSummary(summary: RunSummary): string;
+export declare function formatRunSummaryMarkdown(summary: RunSummary): string;
+export {};

package/dist/core/run-aggregator.js

@@ -0,0 +1,251 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+const REQUIRED_STRING_FIELDS = ["run_id", "trace_title", "policy_name"];
+const REQUIRED_NUMBER_FIELDS = [
+    "original_input_tokens",
+    "compacted_input_tokens",
+    "tokens_saved",
+    "percent_reduction",
+    "cost_before_per_run",
+    "cost_after_per_run",
+    "saving_per_run"
+];
+function emptyBucket() {
+    return {
+        total_runs: 0,
+        total_original_input_tokens: 0,
+        total_compacted_input_tokens: 0,
+        total_tokens_saved: 0,
+        total_cost_before_per_run: 0,
+        total_cost_after_per_run: 0,
+        total_saving_per_run: 0
+    };
+}
+function roundTo(value, digits) {
+    const factor = 10 ** digits;
+    return Math.round((value + Number.EPSILON) * factor) / factor;
+}
+function addReportToBucket(bucket, report) {
+    bucket.total_runs += 1;
+    bucket.total_original_input_tokens += report.original_input_tokens;
+    bucket.total_compacted_input_tokens += report.compacted_input_tokens;
+    bucket.total_tokens_saved += report.tokens_saved;
+    bucket.total_cost_before_per_run += report.cost_before_per_run;
+    bucket.total_cost_after_per_run += report.cost_after_per_run;
+    bucket.total_saving_per_run += report.saving_per_run;
+}
+function normalizeBucket(bucket) {
+    bucket.total_cost_before_per_run = roundTo(bucket.total_cost_before_per_run, 6);
+    bucket.total_cost_after_per_run = roundTo(bucket.total_cost_after_per_run, 6);
+    bucket.total_saving_per_run = roundTo(bucket.total_saving_per_run, 6);
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+export function validateCompactionReport(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { reason: "report is not a JSON object" };
+    }
+    const report = value;
+    for (const field of REQUIRED_STRING_FIELDS) {
+        if (typeof report[field] !== "string" || report[field].trim() === "") {
+            return { reason: `missing or invalid ${field}` };
+        }
+    }
+    for (const field of REQUIRED_NUMBER_FIELDS) {
+        if (!isFiniteNumber(report[field])) {
+            return { reason: `missing or invalid ${field}` };
+        }
+    }
+    if (report.waste_pattern !== null && report.waste_pattern !== undefined && typeof report.waste_pattern !== "string") {
+        return { reason: "missing or invalid waste_pattern" };
+    }
+    return { report: report };
+}
+async function findReportPaths(runsDirectory) {
+    try {
+        const entries = await readdir(runsDirectory, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => join(runsDirectory, entry.name, "report.json"))
+            .sort();
+    }
+    catch (error) {
+        const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "unknown";
+        if (code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+}
+export async function readCompactionRunReports(runsDirectory = ".compaction/runs") {
+    const reportPaths = await findReportPaths(runsDirectory);
+    const reports = [];
+    const skippedFiles = [];
+    for (const reportPath of reportPaths) {
+        try {
+            const parsed = JSON.parse(await readFile(reportPath, "utf8"));
+            const validation = validateCompactionReport(parsed);
+            if (validation.report === undefined) {
+                skippedFiles.push({ path: reportPath, reason: validation.reason ?? "invalid report" });
+                continue;
+            }
+            reports.push({ path: reportPath, report: validation.report });
+        }
+        catch (error) {
+            const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : null;
+            const reason = code === "ENOENT" ? "report.json not found" : error instanceof SyntaxError ? "invalid JSON" : "could not read report";
+            skippedFiles.push({ path: reportPath, reason });
+        }
+    }
+    return { reports, skippedFiles };
+}
+export function aggregateCompactionReports(reports, skippedFiles = [], generatedAt = new Date().toISOString(), sourceGlob = ".compaction/runs/*/report.json") {
+    const summary = {
+        ...emptyBucket(),
+        average_percent_reduction: 0,
+        savings_by_policy: {},
+        savings_by_waste_pattern: {},
+        top_savings_runs: [],
+        skipped_files: skippedFiles,
+        generated_at: generatedAt,
+        source_glob: sourceGlob
+    };
+    let percentReductionTotal = 0;
+    for (const { path, report } of reports) {
+        addReportToBucket(summary, report);
+        percentReductionTotal += report.percent_reduction;
+        const policyBucket = (summary.savings_by_policy[report.policy_name] ??= emptyBucket());
+        addReportToBucket(policyBucket, report);
+        const wastePattern = report.waste_pattern ?? "none";
+        const wasteBucket = (summary.savings_by_waste_pattern[wastePattern] ??= emptyBucket());
+        addReportToBucket(wasteBucket, report);
+        summary.top_savings_runs.push({
+            run_id: report.run_id,
+            trace_title: report.trace_title,
+            report_path: path,
+            tokens_saved: report.tokens_saved,
+            percent_reduction: report.percent_reduction,
+            saving_per_run: report.saving_per_run,
+            policy_name: report.policy_name,
+            waste_pattern: report.waste_pattern
+        });
+    }
+    summary.average_percent_reduction = reports.length === 0 ? 0 : roundTo(percentReductionTotal / reports.length, 2);
+    normalizeBucket(summary);
+    for (const bucket of Object.values(summary.savings_by_policy)) {
+        normalizeBucket(bucket);
+    }
+    for (const bucket of Object.values(summary.savings_by_waste_pattern)) {
+        normalizeBucket(bucket);
+    }
+    summary.top_savings_runs = summary.top_savings_runs
+        .sort((left, right) => {
+        if (right.tokens_saved !== left.tokens_saved) {
+            return right.tokens_saved - left.tokens_saved;
+        }
+        return right.saving_per_run - left.saving_per_run;
+    })
+        .slice(0, 5);
+    return summary;
+}
+export async function createRunSummary(runsDirectory = ".compaction/runs") {
+    const { reports, skippedFiles } = await readCompactionRunReports(runsDirectory);
+    return aggregateCompactionReports(reports, skippedFiles, new Date().toISOString(), `${runsDirectory}/*/report.json`);
+}
+function formatCurrency(value) {
+    return `$${value.toFixed(6)}`;
+}
+function formatBucketLines(bucket) {
+    return [
+        `runs: ${bucket.total_runs}`,
+        `original input tokens: ${bucket.total_original_input_tokens}`,
+        `compacted input tokens: ${bucket.total_compacted_input_tokens}`,
+        `tokens saved: ${bucket.total_tokens_saved}`,
+        `cost before per run: ${formatCurrency(bucket.total_cost_before_per_run)}`,
+        `cost after per run: ${formatCurrency(bucket.total_cost_after_per_run)}`,
+        `saving per run: ${formatCurrency(bucket.total_saving_per_run)}`
+    ];
+}
+export function formatRunSummary(summary) {
+    const policyLines = Object.entries(summary.savings_by_policy).flatMap(([policyName, bucket]) => [
+        `- ${policyName}`,
+        ...formatBucketLines(bucket).map((line) => `  - ${line}`)
+    ]);
+    const wastePatternLines = Object.entries(summary.savings_by_waste_pattern).flatMap(([wastePattern, bucket]) => [
+        `- ${wastePattern}`,
+        ...formatBucketLines(bucket).map((line) => `  - ${line}`)
+    ]);
+    const topRunLines = summary.top_savings_runs.map((run, index) => `${index + 1}. ${run.run_id} (${run.trace_title}) — ${run.tokens_saved} tokens saved, ${run.percent_reduction.toFixed(2)}% reduction, ${formatCurrency(run.saving_per_run)} estimated saving per run`);
+    const skippedLines = summary.skipped_files.map((file) => `- ${file.path}: ${file.reason}`);
+    return [
+        "compaction summary",
+        `Source: ${summary.source_glob}`,
+        `Generated at: ${summary.generated_at}`,
+        "",
+        "Totals",
+        ...formatBucketLines(summary).map((line) => `- ${line}`),
+        `- average percent reduction: ${summary.average_percent_reduction.toFixed(2)}%`,
+        "",
+        "Savings by policy",
+        ...(policyLines.length === 0 ? ["- none"] : policyLines),
+        "",
+        "Savings by waste pattern",
+        ...(wastePatternLines.length === 0 ? ["- none"] : wastePatternLines),
+        "",
+        "Top savings runs",
+        ...(topRunLines.length === 0 ? ["- none"] : topRunLines),
+        "",
+        "Skipped files",
+        ...(skippedLines.length === 0 ? ["- none"] : skippedLines)
+    ].join("\n");
+}
+export function formatRunSummaryMarkdown(summary) {
+    const policyRows = Object.entries(summary.savings_by_policy).map(([policyName, bucket]) => `| ${policyName} | ${bucket.total_runs} | ${bucket.total_tokens_saved} | ${formatCurrency(bucket.total_saving_per_run)} |`);
+    const wastePatternRows = Object.entries(summary.savings_by_waste_pattern).map(([wastePattern, bucket]) => `| ${wastePattern} | ${bucket.total_runs} | ${bucket.total_tokens_saved} | ${formatCurrency(bucket.total_saving_per_run)} |`);
+    const topRunRows = summary.top_savings_runs.map((run) => `| ${run.run_id} | ${run.trace_title} | ${run.tokens_saved} | ${run.percent_reduction.toFixed(2)}% | ${formatCurrency(run.saving_per_run)} |`);
+    const skippedRows = summary.skipped_files.map((file) => `| ${file.path} | ${file.reason} |`);
+    return [
+        "# Compaction Run Summary",
+        "",
+        `- Source: ${summary.source_glob}`,
+        `- Generated at: ${summary.generated_at}`,
+        "",
+        "## Totals",
+        "",
+        `- Total runs: ${summary.total_runs}`,
+        `- Total original input tokens: ${summary.total_original_input_tokens}`,
+        `- Total compacted input tokens: ${summary.total_compacted_input_tokens}`,
+        `- Total tokens saved: ${summary.total_tokens_saved}`,
+        `- Average percent reduction: ${summary.average_percent_reduction.toFixed(2)}%`,
+        `- 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"}.`,
+        "",
+        "## Savings by policy",
+        "",
+        "| Policy | Runs | Tokens saved | Saving per run |",
+        "| --- | ---: | ---: | ---: |",
+        ...(policyRows.length === 0 ? ["| none | 0 | 0 | $0.000000 |"] : policyRows),
+        "",
+        "## Savings by waste pattern",
+        "",
+        "| Waste pattern | Runs | Tokens saved | Saving per run |",
+        "| --- | ---: | ---: | ---: |",
+        ...(wastePatternRows.length === 0 ? ["| none | 0 | 0 | $0.000000 |"] : wastePatternRows),
+        "",
+        "## Top savings runs",
+        "",
+        "| Run ID | Trace title | Tokens saved | Percent reduction | Saving per run |",
+        "| --- | --- | ---: | ---: | ---: |",
+        ...(topRunRows.length === 0 ? ["| none | none | 0 | 0.00% | $0.000000 |"] : topRunRows),
+        "",
+        "## Skipped files",
+        "",
+        "| Path | Reason |",
+        "| --- | --- |",
+        ...(skippedRows.length === 0 ? ["| none | none |"] : skippedRows)
+    ].join("\n");
+}
+//# sourceMappingURL=run-aggregator.js.map

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

@@ -0,0 +1,52 @@
+/**
+ * Local-only run labels (Strong-MVP Track E, task 3).
+ *
+ * A tiny, OPTIONAL, file-based tag a developer can attach to a recorded run so the
+ * multi-session aggregate can group / filter / attribute it. These labels are written
+ * to `.compaction/runs/<run>/run-labels.json` — they are LOCAL ONLY and are NEVER
+ * uploaded. They carry no trace content: only short operator-supplied strings
+ * (project / workflow / provider-runtime / a free-form user label / an explicit
+ * session id).
+ *
+ * Honesty: a label is metadata the operator typed. It does NOT change any token, cost,
+ * savings, or verification figure, and it carries no evidence weight — it is purely an
+ * organizing tag for the local rollup. Provider/runtime supplied as a LABEL is operator-
+ * asserted, never provider-verified, and is kept distinct from the token-source evidence
+ * label (provider-reported vs local-estimate) that the token accounting carries.
+ */
+/** Marker used wherever a label was not supplied rather than guessed. */
+export declare const NO_LABEL: "unlabeled";
+/** Schema version for the run-labels file (additive changes bump the minor). */
+export declare const RUN_LABELS_VERSION = "1.0.0";
+/** The exact, bounded set of label fields. No free-form map — only these keys exist. */
+export interface RunLabels {
+    /** Local-only optional label fields. Absent ≡ unlabeled; never inferred. */
+    project?: string;
+    workflow?: string;
+    /** Operator-ASSERTED provider/runtime (NOT provider-verified). */
+    provider?: string;
+    /** Free-form local user label. */
+    user_label?: string;
+    /**
+     * Session id used to group multiple runs into one session. When absent, the run is
+     * grouped into its own single-run session keyed by run id (every run is at least its
+     * own session). Never inferred from content.
+     */
+    session?: string;
+}
+/** The on-disk run-labels artifact (local file only). */
+export interface RunLabelsFile extends RunLabels {
+    labels_version: string;
+    written_at: string;
+    /** Constant honesty note persisted into the file. */
+    note: string;
+}
+export declare const RUN_LABELS_NOTE: string;
+/** Normalize a supplied label set to the bounded, trimmed shape (drops empty/invalid fields). */
+export declare function normalizeRunLabels(labels: RunLabels): RunLabels;
+/** True when at least one label field is present after normalization. */
+export declare function hasAnyLabel(labels: RunLabels): boolean;
+/** Build the on-disk artifact from a supplied (already-normalizable) label set. */
+export declare function buildRunLabelsFile(labels: RunLabels, writtenAt?: string): RunLabelsFile;
+/** Parse a value read from a run-labels.json into the bounded label set (tolerant; drops junk). */
+export declare function parseRunLabels(value: unknown): RunLabels;