@compaction/cli 0.1.4 → 0.2.0

package/dist/core/run-aggregator.js

@@ -26,6 +26,58 @@ function roundTo(value, digits) {
     const factor = 10 ** digits;
     return Math.round((value + Number.EPSILON) * factor) / factor;
 }
+/** Minimum DISTINCT runs for a measured (not single-anecdote) estimate delta. */
+export 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 function computeMeasuredEstimateDelta(percentReductions) {
+    const n = percentReductions.length;
+    const mean = n === 0 ? 0 : percentReductions.reduce((sum, x) => sum + x, 0) / n;
+    let se = 0;
+    if (n >= 2) {
+        const variance = percentReductions.reduce((sum, x) => sum + (x - mean) ** 2, 0) / (n - 1);
+        se = Math.sqrt(variance) / Math.sqrt(n);
+    }
+    const ciLow = mean - 2 * se;
+    const ciHigh = mean + 2 * se;
+    const excludesZero = ciLow > 0;
+    const qualifies = n >= MIN_RUNS_FOR_MEASURED_DELTA && excludesZero;
+    const meanR = roundTo(mean, 2);
+    const lowR = roundTo(ciLow, 2);
+    const highR = roundTo(ciHigh, 2);
+    let label;
+    if (qualifies) {
+        label =
+            `Measured-caveated ESTIMATE delta across ${n} distinct runs: mean ${meanR}% reduction ` +
+                `(±2·SE [${lowR}%, ${highR}%], excludes zero). Estimate (chars/4 + price-table) — ` +
+                "NOT billing-confirmed, NOT eval-backed, NOT realized savings, NOT extrapolated.";
+    }
+    else if (n < MIN_RUNS_FOR_MEASURED_DELTA) {
+        label =
+            `Single-run/anecdote estimate (${n} distinct run(s); need ≥${MIN_RUNS_FOR_MEASURED_DELTA} ` +
+                "for a measured delta). Local estimate — NOT billing-confirmed.";
+    }
+    else {
+        label =
+            `Estimate delta across ${n} distinct runs does NOT meet the measured bar ` +
+                `(±2·SE [${lowR}%, ${highR}%] includes zero — dispersion too wide). Local estimate — NOT billing-confirmed.`;
+    }
+    return {
+        distinct_run_count: n,
+        mean_percent_reduction: meanR,
+        std_error: roundTo(se, 4),
+        ci_low: lowR,
+        ci_high: highR,
+        excludes_zero: excludesZero,
+        qualifies,
+        evidence_rung: qualifies ? "measured_caveated_estimate_delta" : "local_estimate_single_run",
+        label
+    };
+}
 /** Read the OPTIONAL content fingerprint digest from a report (older reports have none). */
 function fingerprintDigestOf(report) {
     const fp = report.trace_fingerprint;
@@ -153,6 +205,7 @@ export function aggregateCompactionReports(reports, skippedFiles = [], generated
     const summary = {
         ...emptyBucket(),
         average_percent_reduction: 0,
+        measured_estimate_delta: computeMeasuredEstimateDelta([]),
         savings_by_policy: {},
         savings_by_waste_pattern: {},
         top_savings_runs: [],
@@ -183,6 +236,9 @@ export function aggregateCompactionReports(reports, skippedFiles = [], generated
     }
     summary.average_percent_reduction =
         distinctReports.length === 0 ? 0 : roundTo(percentReductionTotal / distinctReports.length, 2);
+    // V0.2 Increment 2: the measured-across-distinct-runs estimate delta over the DISTINCT runs'
+    // per-run reductions. Qualifies for rung 1.5 only when N≥3 AND the mean ±2·SE excludes zero.
+    summary.measured_estimate_delta = computeMeasuredEstimateDelta(summary.top_savings_runs.map((run) => run.percent_reduction));
     normalizeBucket(summary);
     for (const bucket of Object.values(summary.savings_by_policy)) {
         normalizeBucket(bucket);
@@ -250,6 +306,7 @@ export function formatRunSummary(summary) {
         `- ${distinctnessLine(summary.distinctness)}`,
         ...formatBucketLines(summary).map((line) => `- ${line}`),
         `- average percent reduction: ${summary.average_percent_reduction.toFixed(2)}%`,
+        `- measured estimate delta [${summary.measured_estimate_delta.evidence_rung}]: ${summary.measured_estimate_delta.label}`,
         "",
         "Savings by policy",
         ...(policyLines.length === 0 ? ["- none"] : policyLines),
@@ -288,6 +345,13 @@ export function formatRunSummaryMarkdown(summary) {
         `- Total saving per run: ${formatCurrency(summary.total_saving_per_run)}`,
         `- 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).`,
         "",
+        "## Measured Estimate Delta (across distinct runs)",
+        "",
+        `- Rung: ${summary.measured_estimate_delta.evidence_rung}`,
+        `- Distinct runs: ${summary.measured_estimate_delta.distinct_run_count}`,
+        `- Mean percent reduction: ${summary.measured_estimate_delta.mean_percent_reduction.toFixed(2)}% (±2·SE [${summary.measured_estimate_delta.ci_low.toFixed(2)}%, ${summary.measured_estimate_delta.ci_high.toFixed(2)}%])`,
+        `- ${summary.measured_estimate_delta.label}`,
+        "",
         "## Savings by policy",
         "",
         "| Policy | Runs | Tokens saved | Saving per run |",

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

@@ -247,6 +247,39 @@ export interface CompactionReport {
         /** 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.4",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },