@compaction/cli 0.1.2 → 0.2.0

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/trace-adapters.d.ts

@@ -19,6 +19,14 @@ export interface TraceAdapter {
     displayName: string;
     description: string;
     supportedSource: TraceAdapterSource;
+    /**
+     * Honest integration-readiness label for this source (AGENTS.md Level 0–6 +
+     * validation status). All import sources are Level 1 (local export/import — no live
+     * integration); this string also discloses how PROVEN the source is (e.g. validated
+     * on a synthetic fixture vs real-artifact validation still open), so `--list-sources`
+     * never reads as a stronger integration claim than the evidence supports.
+     */
+    readiness: string;
     limitations: string[];
     canHandle(input: unknown): boolean;
     normalize(input: unknown, options: TraceAdapterOptions): TraceAdapterResult;

package/dist/core/trace-adapters.js

@@ -504,6 +504,7 @@ export const agentTraceAdapter = {
     displayName: "Internal AgentTrace",
     description: "Validates a local file that already matches the internal AgentTrace JSON shape.",
     supportedSource: "agent-trace",
+    readiness: "Level 1 (local import) · canonical internal format, schema-validated",
     limitations: [
         "Only local JSON files are supported.",
         "Live provider/runtime capture is future work.",
@@ -519,6 +520,7 @@ export const messagesAdapter = {
     displayName: "Simple messages",
     description: "Normalizes a local array of role/content messages, or an object with a messages array, into AgentTrace.",
     supportedSource: "messages",
+    readiness: "Level 1 (local import) · generic role/content messages shape",
     limitations: [
         "Only local JSON files are supported.",
         "Messages need supported roles and string content.",
@@ -535,6 +537,7 @@ export const codexExecJsonlAdapter = {
     displayName: "Codex exec JSONL",
     description: "Normalizes a local JSONL stream produced by Codex exec --json into AgentTrace without launching Codex or calling provider APIs.",
     supportedSource: "codex-exec-jsonl",
+    readiness: "Level 1 (local export import) · validated end-to-end on a synthetic fixture; real-artifact validation OPEN (a real `codex exec --json` export has not yet been walked)",
     limitations: [
         "Only local user-supplied JSONL files are supported.",
         "This adapter does not launch Codex, call OpenAI APIs, scrape private data, or upload artifacts.",
@@ -564,6 +567,7 @@ export const unknownAdapter = {
     displayName: "Unknown local trace source",
     description: "Detects supported local AgentTrace and simple messages shapes before normalizing with the matching adapter.",
     supportedSource: "unknown",
+    readiness: "Level 1 (local import) · best-effort shape detection (AgentTrace / messages / Codex JSONL)",
     limitations: [
         "Detection is shape-based and local-file only.",
         "AgentTrace, simple messages, and Codex exec JSONL shapes are detected in v0.",

package/dist/core/types.d.ts

@@ -225,6 +225,61 @@ 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;
+    };
+    /**
+     * Composed per-run SAVINGS EVIDENCE record (additive, OPTIONAL, backward-compatible) —
+     * the V0.2 "evidence labels per result" surface. Older reports omit it. See
+     * `SavingsEvidence`. Composes EXISTING report numbers; makes no new/stronger claim.
+     */
+    savings_evidence?: SavingsEvidence;
+}
+/**
+ * Composed, per-run savings-evidence record (V0.2 "evidence labels per result"). Ties the
+ * evidence chain into ONE place and states, per run, the cost-source label, the
+ * recoverability/semantic status, and exactly which `claims-and-evidence-ladder` rung the
+ * figure stands on — so no consumer reads a stronger claim than the evidence supports.
+ *
+ * A single run is rung 1 (local estimate). The measured rung 1.5
+ * (`measured_caveated_estimate_delta`) is produced ONLY by the aggregate increment across
+ * N≥3 distinct runs, NEVER here. `billing_confirmed` is ALWAYS false; `semantic_preservation`
+ * is ALWAYS `not_evaluated` (never auto-certified).
+ */
+export interface SavingsEvidence {
+    /** Is the run attributable to a verifiable identity (trace fingerprint present)? */
+    trace_identity: "fingerprinted" | "unidentified";
+    /** Honest cost-source label for this run's figures (mirrors `CostSource`). */
+    cost_source: "provider_reported" | "price_table_estimate" | "local_estimate" | "missing" | "unknown";
+    /** Deterministic recoverability status when an eval ran (`compact --eval`); else `not_evaluated`. */
+    recoverability: "passed" | "failed" | "not_computed" | "not_evaluated";
+    /** Semantic / meaning preservation is NEVER auto-certified — always `not_evaluated`. */
+    semantic_preservation: "not_evaluated";
+    /** Which claims-and-evidence-ladder rung this single-run figure stands on. */
+    evidence_rung: "local_estimate_single_run";
+    /** No v0 per-run figure is billing-confirmed. Always `false`. */
+    billing_confirmed: false;
+    /** One-line honest label (never asserts a stronger claim than the rung). */
+    label: string;
 }
 export interface CompactionPolicy {
     policy_name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compaction/cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "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"