@compaction/cli 0.1.1 → 0.1.4

package/dist/core/run-aggregator.js

@@ -1,5 +1,6 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { classifyDistinctness } from "./trace-fingerprint.js";
 const REQUIRED_STRING_FIELDS = ["run_id", "trace_title", "policy_name"];
 const REQUIRED_NUMBER_FIELDS = [
     "original_input_tokens",
@@ -25,6 +26,51 @@ function roundTo(value, digits) {
     const factor = 10 ** digits;
     return Math.round((value + Number.EPSILON) * factor) / factor;
 }
+/** Read the OPTIONAL content fingerprint digest from a report (older reports have none). */
+function fingerprintDigestOf(report) {
+    const fp = report.trace_fingerprint;
+    return fp && typeof fp.content_sha256 === "string" && fp.content_sha256.length > 0 ? fp.content_sha256 : null;
+}
+/**
+ * De-duplicate loaded reports by content fingerprint for a duplicate-safe headline.
+ *
+ * Keeps the FIRST report per distinct fingerprint; later same-fingerprint reports are duplicates
+ * and are dropped from the totals so a re-captured run never double-counts its savings. Reports
+ * without a fingerprint are each kept (cannot dedup what cannot be identified). PURE; never
+ * inflates savings.
+ */
+function dedupeReportsByFingerprint(reports) {
+    const seen = new Set();
+    const distinctReports = [];
+    let withFingerprint = 0;
+    let withoutFingerprint = 0;
+    for (const loaded of reports) {
+        const fp = fingerprintDigestOf(loaded.report);
+        if (fp !== null) {
+            withFingerprint += 1;
+            if (seen.has(fp))
+                continue;
+            seen.add(fp);
+            distinctReports.push(loaded);
+        }
+        else {
+            withoutFingerprint += 1;
+            distinctReports.push(loaded);
+        }
+    }
+    const classified = classifyDistinctness(reports.map((loaded) => ({ runId: loaded.report.run_id, content_sha256: fingerprintDigestOf(loaded.report) })));
+    const distinctRunCount = classified.distinct_verified_count + withoutFingerprint;
+    return {
+        distinctReports,
+        distinctness: {
+            total_runs: reports.length,
+            distinct_runs: distinctRunCount,
+            duplicate_runs: reports.length - distinctRunCount,
+            runs_with_fingerprint: withFingerprint,
+            runs_without_fingerprint: withoutFingerprint
+        }
+    };
+}
 function addReportToBucket(bucket, report) {
     bucket.total_runs += 1;
     bucket.total_original_input_tokens += report.original_input_tokens;
@@ -101,6 +147,9 @@ export async function readCompactionRunReports(runsDirectory = ".compaction/runs
     return { reports, skippedFiles };
 }
 export function aggregateCompactionReports(reports, skippedFiles = [], generatedAt = new Date().toISOString(), sourceGlob = ".compaction/runs/*/report.json") {
+    // Duplicate-safe headline: fold totals over DISTINCT reports only (a run captured/aggregated
+    // twice with the same content fingerprint is counted once). Never inflates summed savings.
+    const { distinctReports, distinctness } = dedupeReportsByFingerprint(reports);
     const summary = {
         ...emptyBucket(),
         average_percent_reduction: 0,
@@ -108,11 +157,12 @@ export function aggregateCompactionReports(reports, skippedFiles = [], generated
         savings_by_waste_pattern: {},
         top_savings_runs: [],
         skipped_files: skippedFiles,
+        distinctness,
         generated_at: generatedAt,
         source_glob: sourceGlob
     };
     let percentReductionTotal = 0;
-    for (const { path, report } of reports) {
+    for (const { path, report } of distinctReports) {
         addReportToBucket(summary, report);
         percentReductionTotal += report.percent_reduction;
         const policyBucket = (summary.savings_by_policy[report.policy_name] ??= emptyBucket());
@@ -131,7 +181,8 @@ export function aggregateCompactionReports(reports, skippedFiles = [], generated
             waste_pattern: report.waste_pattern
         });
     }
-    summary.average_percent_reduction = reports.length === 0 ? 0 : roundTo(percentReductionTotal / reports.length, 2);
+    summary.average_percent_reduction =
+        distinctReports.length === 0 ? 0 : roundTo(percentReductionTotal / distinctReports.length, 2);
     normalizeBucket(summary);
     for (const bucket of Object.values(summary.savings_by_policy)) {
         normalizeBucket(bucket);
@@ -156,6 +207,18 @@ export async function createRunSummary(runsDirectory = ".compaction/runs") {
 function formatCurrency(value) {
     return `$${value.toFixed(6)}`;
 }
+/**
+ * "distinct runs N of M (K duplicates detected)" — a count of distinct captured runs by content
+ * fingerprint. The totals above are summed over the distinct set, so a re-captured run never
+ * double-counts. NOT a billing/provider/semantic claim.
+ */
+function distinctnessLine(d) {
+    const noFp = d.runs_without_fingerprint > 0
+        ? `; ${d.runs_without_fingerprint} run(s) without a fingerprint counted as distinct (cannot de-duplicate)`
+        : "";
+    return (`distinct runs ${d.distinct_runs} of ${d.total_runs} (${d.duplicate_runs} duplicate(s) detected by content fingerprint, ` +
+        `excluded from the headline so savings are not double-counted)${noFp}`);
+}
 function formatBucketLines(bucket) {
     return [
         `runs: ${bucket.total_runs}`,
@@ -184,6 +247,7 @@ export function formatRunSummary(summary) {
         `Generated at: ${summary.generated_at}`,
         "",
         "Totals",
+        `- ${distinctnessLine(summary.distinctness)}`,
         ...formatBucketLines(summary).map((line) => `- ${line}`),
         `- average percent reduction: ${summary.average_percent_reduction.toFixed(2)}%`,
         "",
@@ -213,6 +277,7 @@ export function formatRunSummaryMarkdown(summary) {
         "",
         "## Totals",
         "",
+        `- Distinct runs: ${distinctnessLine(summary.distinctness)}`,
         `- Total runs: ${summary.total_runs}`,
         `- Total original input tokens: ${summary.total_original_input_tokens}`,
         `- Total compacted input tokens: ${summary.total_compacted_input_tokens}`,
@@ -221,7 +286,7 @@ export function formatRunSummaryMarkdown(summary) {
         `- Total cost before per run: ${formatCurrency(summary.total_cost_before_per_run)}`,
         `- Total cost after per run: ${formatCurrency(summary.total_cost_after_per_run)}`,
         `- Total saving per run: ${formatCurrency(summary.total_saving_per_run)}`,
-        `- Saving figures are estimated and summed over the ${summary.total_runs} recorded run${summary.total_runs === 1 ? "" : "s"}.`,
+        `- Saving figures are estimated and summed over the ${summary.distinctness.distinct_runs} distinct recorded run${summary.distinctness.distinct_runs === 1 ? "" : "s"} (${summary.distinctness.duplicate_runs} duplicate(s) detected by content fingerprint and excluded).`,
         "",
         "## Savings by policy",
         "",

package/dist/core/session-aggregate.d.ts

@@ -46,6 +46,14 @@ export interface RunRecord {
     run_directory: string;
     report_path: string;
     model: string;
+    /**
+     * Content-addressed distinctness fingerprint digest of the source trace, when the run's
+     * report.json carried one (`trace_fingerprint.content_sha256`). Used to de-duplicate a
+     * run captured/aggregated twice (same digest → counted once) so headline savings are never
+     * inflated. `null` for older reports without a fingerprint — those are treated as distinct
+     * (cannot dedup what cannot be identified) and noted honestly, never collapsed.
+     */
+    trace_fingerprint: string | null;
     /** Token evidence tier for this run (drives the provider-reported vs local-estimate split). */
     token_evidence: RunTokenEvidence;
     input_tokens_before: number;
@@ -73,6 +81,32 @@ export interface SkippedRunDirectory {
     run_directory: string;
     reason: string;
 }
+/**
+ * Distinctness (duplicate-safety) summary over a set of runs, by content fingerprint.
+ *
+ * This is a count of DISTINCT captured runs by one-way content fingerprint — NOT a billing,
+ * provider, or semantic claim. A run captured/aggregated twice with the SAME fingerprint is a
+ * duplicate and is counted once; a run WITHOUT a fingerprint cannot be de-duplicated and is
+ * treated as distinct (and reported in `runs_without_fingerprint`), never collapsed.
+ *
+ * The headline token/cost/savings totals in `AggregateTotals` are computed over the
+ * duplicate-safe set (each distinct run once), so a re-captured run never double-counts.
+ */
+export interface DistinctnessSummary {
+    /** Total runs considered before de-duplication (M in "distinct N of M"). */
+    total_runs: number;
+    /**
+     * Distinct runs after de-duplication (N): distinct verified fingerprints + every run without
+     * a fingerprint (each unidentifiable run is its own distinct contribution).
+     */
+    distinct_runs: number;
+    /** Duplicate runs detected and excluded from the headline double-count (K = total - distinct). */
+    duplicate_runs: number;
+    /** Runs whose fingerprint was present and verifiable (contributed to `distinct_runs`, de-duplicated). */
+    runs_with_fingerprint: number;
+    /** Runs with NO fingerprint (older reports): each counted as distinct; cannot be de-duplicated. */
+    runs_without_fingerprint: number;
+}
 /** Aggregated token/cost/savings totals over a set of runs, with the evidence split. */
 export interface AggregateTotals {
     run_count: number;
@@ -134,6 +168,8 @@ export interface SessionSummary {
     };
     totals: AggregateTotals;
     verification: VerificationCounts;
+    /** Duplicate-safety summary for this session's runs (distinct N of M by content fingerprint). */
+    distinctness: DistinctnessSummary;
 }
 export interface AggregateReport {
     aggregate_id: string;
@@ -146,6 +182,12 @@ export interface AggregateReport {
     session_count: number;
     totals: AggregateTotals;
     verification: VerificationCounts;
+    /**
+     * Cross-session duplicate-safety summary (distinct N of M captured runs by content fingerprint).
+     * The headline `totals` above are computed over the duplicate-safe set, so a run captured/
+     * aggregated twice with the same fingerprint is counted once and never inflates savings.
+     */
+    distinctness: DistinctnessSummary;
     sessions: SessionSummary[];
     /** Provider/runtime breakdown (operator-asserted provider label; unlabeled when absent). */
     by_provider: BreakdownBucket[];
@@ -166,6 +208,7 @@ export interface AggregateEvidenceLabels {
     compactions: string;
     verification: string;
     provider_runtime: string;
+    distinctness: string;
 }
 export declare const AGGREGATE_EVIDENCE_LABELS: AggregateEvidenceLabels;
 /** True when a run passes every supplied local-label filter (case-sensitive exact match). */

package/dist/core/session-aggregate.js

@@ -33,6 +33,7 @@ import { randomUUID } from "node:crypto";
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { NO_LABEL, parseRunLabels } from "./run-labels.js";
+import { classifyDistinctness } from "./trace-fingerprint.js";
 export const AGGREGATE_ARTIFACT_DIRECTORY = ".compaction/aggregates";
 export const AGGREGATE_EVIDENCE_LABELS = {
     input_tokens: "input tokens: provider-reported where the run's token accounting was measured (provider usage " +
@@ -50,7 +51,12 @@ export const AGGREGATE_EVIDENCE_LABELS = {
         "task-check outcomes copied from each run's strong-eval; runs without a strong-eval are not_evaluated, " +
         "never counted as a pass. These are DETERMINISTIC recoverability checks, NOT semantic guarantees.",
     provider_runtime: "provider/runtime: operator-ASSERTED local label (never provider-verified); runs without a provider " +
-        "label are grouped under 'unlabeled'. This label is distinct from the token-evidence tier."
+        "label are grouped under 'unlabeled'. This label is distinct from the token-evidence tier.",
+    distinctness: "distinct runs: a count of DISTINCT captured runs by one-way content fingerprint (SHA-256 over the " +
+        "normalized trace). A run captured/aggregated twice with the SAME fingerprint is a duplicate and is " +
+        "counted once, so headline savings are never inflated; runs without a fingerprint cannot be " +
+        "de-duplicated and are each counted as distinct. This is a local content-distinctness count — NOT a " +
+        "billing, provider, or semantic claim."
 };
 const STANDARD_LIMITATIONS = [
     "Aggregated from LOCAL artifacts only (.compaction/runs/*/{report.json,strong-eval.json,run-labels.json}); no provider calls, no upload, no telemetry.",
@@ -59,11 +65,66 @@ const STANDARD_LIMITATIONS = [
     "Output tokens are summed only over runs that recorded them; runs without a strong-eval contribute unknown output tokens and are counted separately, never inferred.",
     "Verification outcomes are deterministic recoverability checks copied from each run's strong-eval; they are NOT semantic or meaning-preservation guarantees. Runs without a strong-eval are not_evaluated, never a pass.",
     "Labels (project/workflow/provider/user-label/session) are operator-supplied local tags with no evidence weight; provider here is operator-asserted, not provider-verified.",
+    "Headline savings are duplicate-safe: runs sharing a content fingerprint (a re-captured/re-aggregated run) are counted once; runs without a fingerprint cannot be de-duplicated and are each counted as distinct. This is a local content-distinctness count, not a billing/provider/semantic claim.",
     "This is a LOCAL, file-based rollup. There is no hosted dashboard, database, auth, billing, model routing, or provider integration."
 ];
 function round6(value) {
     return Number((value + Number.EPSILON).toFixed(6));
 }
+/**
+ * De-duplicate a set of runs by content fingerprint for duplicate-safe headline totals.
+ *
+ * Keeps the FIRST run per distinct verified fingerprint; later runs with the same fingerprint
+ * are duplicates and are dropped from the headline (so a re-captured run never double-counts its
+ * savings). Runs WITHOUT a fingerprint are kept as-is — each is its own distinct contribution,
+ * because distinctness that cannot be verified is never collapsed (the anti-overcount contract in
+ * `classifyDistinctness`). Returns the duplicate-safe run set plus an honest distinctness summary.
+ *
+ * PURE: order-stable for the kept runs; makes savings MORE conservative, never larger.
+ */
+function dedupeRunsByFingerprint(runs) {
+    const seenFingerprints = new Set();
+    const distinctRuns = [];
+    let runsWithFingerprint = 0;
+    let runsWithoutFingerprint = 0;
+    for (const run of runs) {
+        const fp = run.trace_fingerprint;
+        if (typeof fp === "string" && fp.length > 0) {
+            runsWithFingerprint += 1;
+            if (seenFingerprints.has(fp))
+                continue; // duplicate fingerprint: excluded from headline.
+            seenFingerprints.add(fp);
+            distinctRuns.push(run);
+        }
+        else {
+            runsWithoutFingerprint += 1;
+            distinctRuns.push(run); // unidentifiable: always its own distinct contribution.
+        }
+    }
+    // classifyDistinctness gives the verified-distinct count over the SAME records; distinct_runs is
+    // that verified-distinct count plus every unidentifiable run (each distinct by construction).
+    const classified = classifyDistinctness(runs.map((run) => ({ runId: run.run_id, content_sha256: run.trace_fingerprint })));
+    const distinctRunCount = classified.distinct_verified_count + runsWithoutFingerprint;
+    return {
+        distinctRuns,
+        distinctness: {
+            total_runs: runs.length,
+            distinct_runs: distinctRunCount,
+            duplicate_runs: runs.length - distinctRunCount,
+            runs_with_fingerprint: runsWithFingerprint,
+            runs_without_fingerprint: runsWithoutFingerprint
+        }
+    };
+}
+function emptyDistinctness() {
+    return {
+        total_runs: 0,
+        distinct_runs: 0,
+        duplicate_runs: 0,
+        runs_with_fingerprint: 0,
+        runs_without_fingerprint: 0
+    };
+}
 function emptyTotals() {
     return {
         run_count: 0,
@@ -209,9 +270,12 @@ function buildSessions(runs) {
     }
     return [...sessions.entries()]
         .map(([sessionId, { explicit, runs: sessionRuns }]) => {
+        // Duplicate-safe: fold totals/verification over distinct runs only (re-captured runs with
+        // the same fingerprint are excluded from the double-count). run_ids still lists every run.
+        const { distinctRuns, distinctness } = dedupeRunsByFingerprint(sessionRuns);
         const totals = emptyTotals();
         const verification = emptyVerification();
-        for (const run of sessionRuns) {
+        for (const run of distinctRuns) {
             addRunToTotals(totals, run);
             addRunToVerification(verification, run);
         }
@@ -227,7 +291,8 @@ function buildSessions(runs) {
                 user_labels: distinct(sessionRuns.map((r) => r.labels.user_label))
             },
             totals,
-            verification
+            verification,
+            distinctness
         };
     })
         .sort((a, b) => b.totals.total_input_tokens_saved - a.totals.total_input_tokens_saved ||
@@ -258,9 +323,13 @@ export function buildAggregateReport(runs, options = {}) {
     const generatedAt = options.generatedAt ?? new Date().toISOString();
     const filters = options.filters ?? {};
     const matched = runs.filter((run) => runMatchesFilters(run, filters));
+    // Duplicate-safe headline: fold cross-session totals/verification over the distinct run set only.
+    // A run captured/aggregated twice with the same content fingerprint is counted once; runs without
+    // a fingerprint are each distinct (cannot dedup what cannot be identified). Never inflates savings.
+    const { distinctRuns, distinctness } = dedupeRunsByFingerprint(matched);
     const totals = emptyTotals();
     const verification = emptyVerification();
-    for (const run of matched) {
+    for (const run of distinctRuns) {
         addRunToTotals(totals, run);
         addRunToVerification(verification, run);
     }
@@ -275,10 +344,13 @@ export function buildAggregateReport(runs, options = {}) {
         session_count: sessions.length,
         totals,
         verification,
+        distinctness,
         sessions,
-        by_provider: buildBreakdown(matched, (run) => run.labels.provider ?? NO_LABEL),
-        by_project: buildBreakdown(matched, (run) => run.labels.project ?? NO_LABEL),
-        by_workflow: buildBreakdown(matched, (run) => run.labels.workflow ?? NO_LABEL),
+        // Breakdowns also fold over the duplicate-safe distinct run set so per-bucket savings match the
+        // duplicate-safe headline (a re-captured run never double-counts inside its label bucket either).
+        by_provider: buildBreakdown(distinctRuns, (run) => run.labels.provider ?? NO_LABEL),
+        by_project: buildBreakdown(distinctRuns, (run) => run.labels.project ?? NO_LABEL),
+        by_workflow: buildBreakdown(distinctRuns, (run) => run.labels.workflow ?? NO_LABEL),
         skipped_run_directories: options.skippedRunDirectories ?? [],
         evidence_labels: AGGREGATE_EVIDENCE_LABELS,
         limitations: STANDARD_LIMITATIONS
@@ -320,6 +392,15 @@ function readinessFrom(status) {
 export function assembleRunRecord(input) {
     const { report, strongEval } = input;
     const notes = [];
+    // Content-addressed run identity: read the OPTIONAL trace_fingerprint digest if the report
+    // carried one. Older reports omit it; such a run cannot be de-duplicated and is treated as
+    // distinct (noted), never collapsed. Read defensively (digest string only; no content).
+    const fingerprintDigest = isRecord(report.trace_fingerprint) && typeof report.trace_fingerprint.content_sha256 === "string"
+        ? report.trace_fingerprint.content_sha256
+        : null;
+    if (fingerprintDigest === null) {
+        notes.push("No trace_fingerprint on report.json: this run is treated as distinct (cannot de-duplicate an unidentifiable run).");
+    }
     let tokenEvidence = "local_estimate";
     let inputBefore = report.original_input_tokens;
     let inputAfter = report.compacted_input_tokens;
@@ -389,6 +470,7 @@ export function assembleRunRecord(input) {
         run_directory: input.runDirectory,
         report_path: input.reportPath,
         model,
+        trace_fingerprint: fingerprintDigest,
         token_evidence: tokenEvidence,
         input_tokens_before: inputBefore,
         input_tokens_after: inputAfter,

package/dist/core/types.d.ts

@@ -225,6 +225,28 @@ export interface CompactionReport {
      * price-table), NOT billing-confirmed and NOT realized savings.
      */
     spend_by_source?: SpendBySourceSummary;
+    /**
+     * Content-addressed per-run distinctness fingerprint of the source trace (additive,
+     * OPTIONAL, backward-compatible). When present, it lets the aggregate attribute this
+     * run's savings to a verifiable run identity and de-duplicate a run captured/aggregated
+     * twice (same fingerprint → counted once) so the headline savings are never inflated.
+     *
+     * Older reports omit this field; a run WITHOUT a fingerprint cannot be de-duplicated and
+     * is treated as distinct (you cannot dedup what you cannot identify) and noted honestly.
+     *
+     * Privacy: this is a one-way SHA-256 digest plus non-sensitive structural counts — NO
+     * message/prompt/tool-output text. Structurally matches `TraceFingerprint` from
+     * `src/core/trace-fingerprint.ts` (kept inline here so `types.ts` stays import-free).
+     * This is an attribution/integrity signal, NOT a billing, provider, or semantic claim.
+     */
+    trace_fingerprint?: {
+        /** Algorithm + canonicalization version (e.g. `sha256-canonical-content-v1`). */
+        algorithm: string;
+        /** Hex SHA-256 digest over the canonical normalized trace content (one-way; never raw content). */
+        content_sha256: string;
+        /** Non-sensitive structural count: number of messages hashed. */
+        message_count: number;
+    };
 }
 export interface CompactionPolicy {
     policy_name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compaction/cli",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "publishConfig": {
     "access": "public"
   },
@@ -79,10 +79,14 @@
   "dependencies": {
     "chalk": "^5.4.1",
     "commander": "^12.1.0",
+    "ink": "^5.2.1",
+    "react": "^18.3.1",
     "zod": "^3.24.1"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
+    "@types/react": "^18.3.31",
+    "ink-testing-library": "^4.0.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^4.1.8"