@compaction/cli 0.1.4 → 0.3.0

package/dist/core/input-compaction-ab.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Input-compaction A/B experiment record + summary (PUBLIC CLI/SDK code — engine-free, ships in the npm CLI).
+ * Design: `docs/design/input-compaction-ab.md` (accepted 2026-06-30). The INPUT-side twin of
+ * `output-shaping-ab.ts`: links a control arm (full input context) and a treatment arm (Compaction-compacted
+ * input context) of Codex runs and reports the **observed provider-reported INPUT-token delta**, gated for a
+ * confirmed claim on a **context-preservation** eval — NOT the output short-but-sufficient eval.
+ *
+ * Boundary / honesty (binding):
+ *  - This PUBLIC module computes the **observed** input-token measurement for operator visibility. It NEVER
+ *    produces a CONFIRMED input-savings number — `confirmedSavingsEligible` is the literal `false`. A confirmed
+ *    number is produced solely by the PRIVATE engine gate (`src/engine/input-compaction-verification.ts`).
+ *  - **Input eval ≠ output eval.** Input requires context-preservation: task-critical context preserved,
+ *    source recoverability, instruction/commitment preservation, no material loss, and the treatment output
+ *    still solves the same task. Reusing the output short-but-sufficient eval here would be a bug.
+ *  - Input tokens that are not provider-reported (e.g. Cursor) → `unavailable`; can never be eligible.
+ *  - Missing usage stays null, never 0. Token source preserved exactly. Content-free (counts + flags + ids).
+ *  - Output-token delta is kept **observable but secondary** — never the primary claim for this input gate.
+ */
+import type { TokenSource } from "./api-client/index.js";
+import type { CaptureUsageSidecar } from "./output-shaping-ab.js";
+export declare const INPUT_COMPACTION_AB_SCHEMA: "input-compaction.ab-experiment.v1";
+export type InputCompactionAbArm = "control" | "treatment";
+/** Tri-state per-treatment outcome: true = passed, false = failed, null/undefined = not evaluated. */
+export type EvalOutcome = boolean | null;
+export interface InputCompactionAbRun {
+    arm: InputCompactionAbArm;
+    /** Provider-reported INPUT tokens; null when unavailable (never invented as 0). */
+    inputTokens: number | null;
+    /** Provider-reported OUTPUT tokens (observed, secondary — not the input claim). */
+    outputTokens: number | null;
+    providerReported: boolean;
+    tokenSource: TokenSource;
+    /** Task-critical context preserved (overall operator/eval judgment). */
+    contextPreserved?: EvalOutcome;
+    /** The treatment output still solves the same task. */
+    taskSolved?: EvalOutcome;
+    /** Source recoverability preserved (from `compact --eval` recoverability). */
+    sourceRecoverability?: EvalOutcome;
+    /** Instruction/commitment preservation (from `compact --eval` commitment-preservation). */
+    commitmentPreservation?: EvalOutcome;
+    /** No material context loss. */
+    noMaterialLoss?: EvalOutcome;
+    /** Semantic/meaning preservation is NOT scored in v1 (D4) — always `not_evaluated`. */
+    semanticEval: "not_evaluated";
+    reference?: string;
+}
+export interface InputCompactionAbExperiment {
+    schema: typeof INPUT_COMPACTION_AB_SCHEMA;
+    experimentId: string;
+    /** Short generic label of the shared task/context SHAPE (not prompt content). */
+    taskShape: string;
+    createdAt: string;
+    runs: InputCompactionAbRun[];
+}
+export interface InitInputCompactionAbInput {
+    experimentId: string;
+    taskShape: string;
+    createdAt?: string;
+}
+export declare function initInputCompactionAbExperiment(input: InitInputCompactionAbInput): InputCompactionAbExperiment;
+export declare function addInputCompactionAbRun(experiment: InputCompactionAbExperiment, run: InputCompactionAbRun): InputCompactionAbExperiment;
+/** Build a treatment run from a capture-usage sidecar + the recorded context-preservation outcome. */
+export interface TreatmentOutcomeInput {
+    contextPreserved?: EvalOutcome;
+    taskSolved?: EvalOutcome;
+    sourceRecoverability?: EvalOutcome;
+    commitmentPreservation?: EvalOutcome;
+    noMaterialLoss?: EvalOutcome;
+}
+export declare function runFromSidecar(arm: InputCompactionAbArm, sidecar: CaptureUsageSidecar, outcome?: TreatmentOutcomeInput, reference?: string): InputCompactionAbRun;
+export type InputCompactionAbConfidence = "unavailable" | "review_required" | "observed_not_confirmed" | "eligible_for_engine_confirmation";
+/** Context-preservation rollup for the treatment arm. `pass` only if ALL required checks passed. */
+export type ContextPreservationStatus = "pass" | "fail" | "not_evaluated" | "mixed";
+export interface InputCompactionAbSummary {
+    experimentId: string;
+    nControl: number;
+    nTreatment: number;
+    /** Mean control (full-context) INPUT tokens — provider-reported; null when unavailable. */
+    inputTokensBefore: number | null;
+    /** Mean treatment (compacted-context) INPUT tokens — provider-reported; null when unavailable. */
+    inputTokensAfter: number | null;
+    /** before − after: positive ⇒ treatment used FEWER input tokens. OBSERVED, not confirmed. */
+    inputTokenDelta: number | null;
+    inputTokenReductionPct: number | null;
+    /** OBSERVED output-token delta (secondary; never the input claim). */
+    outputTokensBefore: number | null;
+    outputTokensAfter: number | null;
+    outputTokenDelta: number | null;
+    tokenSource: "provider-reported" | "mixed" | "local-estimate" | "unavailable";
+    /** Context-preservation rollup across treatment runs (the INPUT eval — NOT short-but-sufficient). */
+    contextPreservation: ContextPreservationStatus;
+    semanticEval: "not_evaluated";
+    confidence: InputCompactionAbConfidence;
+    /** ALWAYS false in the public CLI — a confirmed input-savings number is produced only by the engine gate. */
+    confirmedSavingsEligible: false;
+    reasons: string[];
+}
+/** Roll up the treatment arm's context-preservation checks. `pass` only if every required check is true. */
+export declare function treatmentContextPreservation(treatment: InputCompactionAbRun[]): ContextPreservationStatus;
+/**
+ * Observed input-compaction A/B + a conservative confidence. NEVER confirms a saving (engine gate does).
+ * Decision order is fail-safe: unavailable → review_required → observed_not_confirmed →
+ * eligible_for_engine_confirmation. Input means/delta come ONLY from provider-reported input tokens.
+ */
+export declare function summarizeInputCompactionAb(experiment: InputCompactionAbExperiment): InputCompactionAbSummary;
+/** Provider-reported INPUT-token arrays per arm — the only honest input to the engine confirmation gate. */
+export declare function providerReportedInputArms(experiment: InputCompactionAbExperiment): {
+    controlInputTokens: number[];
+    treatmentInputTokens: number[];
+    bothProviderReported: boolean;
+};

package/dist/core/input-compaction-ab.js

@@ -0,0 +1,158 @@
+export const INPUT_COMPACTION_AB_SCHEMA = "input-compaction.ab-experiment.v1";
+export function initInputCompactionAbExperiment(input) {
+    return {
+        schema: INPUT_COMPACTION_AB_SCHEMA,
+        experimentId: input.experimentId,
+        taskShape: input.taskShape,
+        createdAt: input.createdAt ?? new Date().toISOString(),
+        runs: []
+    };
+}
+export function addInputCompactionAbRun(experiment, run) {
+    return { ...experiment, runs: [...experiment.runs, run] };
+}
+export function runFromSidecar(arm, sidecar, outcome = {}, reference) {
+    const base = {
+        arm,
+        inputTokens: sidecar.inputTokens,
+        outputTokens: sidecar.outputTokens,
+        providerReported: sidecar.providerReported === true,
+        tokenSource: sidecar.tokenSource,
+        semanticEval: "not_evaluated",
+        ...(reference ? { reference } : {})
+    };
+    if (arm !== "treatment")
+        return base;
+    return {
+        ...base,
+        contextPreserved: outcome.contextPreserved ?? null,
+        taskSolved: outcome.taskSolved ?? null,
+        sourceRecoverability: outcome.sourceRecoverability ?? null,
+        commitmentPreservation: outcome.commitmentPreservation ?? null,
+        noMaterialLoss: outcome.noMaterialLoss ?? null
+    };
+}
+const MIN_RUNS_PER_ARM = 3;
+const REQUIRED_CHECKS = [
+    "contextPreserved",
+    "taskSolved",
+    "sourceRecoverability",
+    "commitmentPreservation",
+    "noMaterialLoss"
+];
+function mean(xs) {
+    return xs.reduce((s, x) => s + x, 0) / xs.length;
+}
+function meanOrNull(xs) {
+    return xs.length > 0 ? mean(xs) : null;
+}
+function armSource(runs) {
+    if (runs.length === 0)
+        return "unavailable";
+    if (runs.every((r) => r.providerReported && typeof r.inputTokens === "number"))
+        return "provider-reported";
+    if (runs.some((r) => r.providerReported && typeof r.inputTokens === "number"))
+        return "mixed";
+    return runs.some((r) => r.tokenSource === "local-estimate") ? "local-estimate" : "unavailable";
+}
+/** Roll up the treatment arm's context-preservation checks. `pass` only if every required check is true. */
+export function treatmentContextPreservation(treatment) {
+    if (treatment.length === 0)
+        return "not_evaluated";
+    const values = [];
+    for (const r of treatment)
+        for (const k of REQUIRED_CHECKS)
+            values.push(r[k] ?? null);
+    if (values.some((v) => v === undefined || v === null)) {
+        return values.some((v) => v === true || v === false) ? "mixed" : "not_evaluated";
+    }
+    if (values.every((v) => v === true))
+        return "pass";
+    if (values.every((v) => v === false))
+        return "fail";
+    return "mixed";
+}
+/**
+ * Observed input-compaction A/B + a conservative confidence. NEVER confirms a saving (engine gate does).
+ * Decision order is fail-safe: unavailable → review_required → observed_not_confirmed →
+ * eligible_for_engine_confirmation. Input means/delta come ONLY from provider-reported input tokens.
+ */
+export function summarizeInputCompactionAb(experiment) {
+    const control = experiment.runs.filter((r) => r.arm === "control");
+    const treatment = experiment.runs.filter((r) => r.arm === "treatment");
+    const reasons = [];
+    const controlIn = control.filter((r) => r.providerReported && typeof r.inputTokens === "number").map((r) => r.inputTokens);
+    const treatmentIn = treatment.filter((r) => r.providerReported && typeof r.inputTokens === "number").map((r) => r.inputTokens);
+    const controlOut = control.filter((r) => typeof r.outputTokens === "number").map((r) => r.outputTokens);
+    const treatmentOut = treatment.filter((r) => typeof r.outputTokens === "number").map((r) => r.outputTokens);
+    const bothProviderReported = control.length > 0 &&
+        treatment.length > 0 &&
+        control.every((r) => r.providerReported && typeof r.inputTokens === "number") &&
+        treatment.every((r) => r.providerReported && typeof r.inputTokens === "number");
+    const inputTokensBefore = meanOrNull(controlIn);
+    const inputTokensAfter = meanOrNull(treatmentIn);
+    const inputTokenDelta = inputTokensBefore !== null && inputTokensAfter !== null ? inputTokensBefore - inputTokensAfter : null;
+    const inputTokenReductionPct = inputTokenDelta !== null && inputTokensBefore !== null && inputTokensBefore > 0 ? (inputTokenDelta / inputTokensBefore) * 100 : null;
+    const outputTokensBefore = meanOrNull(controlOut);
+    const outputTokensAfter = meanOrNull(treatmentOut);
+    const outputTokenDelta = outputTokensBefore !== null && outputTokensAfter !== null ? outputTokensBefore - outputTokensAfter : null;
+    const cSrc = armSource(control);
+    const tSrc = armSource(treatment);
+    const tokenSource = bothProviderReported
+        ? "provider-reported"
+        : cSrc === "local-estimate" || tSrc === "local-estimate"
+            ? "local-estimate"
+            : cSrc === "mixed" || tSrc === "mixed"
+                ? "mixed"
+                : "unavailable";
+    const contextPreservation = treatmentContextPreservation(treatment);
+    let confidence;
+    if (!bothProviderReported) {
+        confidence = "unavailable";
+        reasons.push("input savings unavailable: both arms must have provider-reported INPUT tokens (local-estimate / missing input can never produce an input-savings number).");
+    }
+    else if (contextPreservation !== "pass") {
+        confidence = "review_required";
+        reasons.push(`review required: treatment context-preservation status is "${contextPreservation}" — confirmation requires task-critical context preserved + source recoverability + commitment preservation + no material loss + treatment-solves-task (record each per treatment run).`);
+    }
+    else if (control.length < MIN_RUNS_PER_ARM || treatment.length < MIN_RUNS_PER_ARM) {
+        confidence = "observed_not_confirmed";
+        reasons.push(`observed, not confirmed: N ≥ ${MIN_RUNS_PER_ARM} per arm is required (have control=${control.length}, treatment=${treatment.length}).`);
+    }
+    else {
+        confidence = "eligible_for_engine_confirmation";
+        reasons.push("eligible for engine confirmation: provider-reported both arms, N ≥ 3 per arm, context-preservation passed (incl. task-solved). The CONFIRMED verdict is the engine gate (measured ±2·SE criterion + reduction).");
+    }
+    reasons.push("note: semantic/meaning preservation is not_evaluated (v1); output-token delta is observed-only, not the input claim.");
+    return {
+        experimentId: experiment.experimentId,
+        nControl: control.length,
+        nTreatment: treatment.length,
+        inputTokensBefore,
+        inputTokensAfter,
+        inputTokenDelta,
+        inputTokenReductionPct,
+        outputTokensBefore,
+        outputTokensAfter,
+        outputTokenDelta,
+        tokenSource,
+        contextPreservation,
+        semanticEval: "not_evaluated",
+        confidence,
+        confirmedSavingsEligible: false,
+        reasons
+    };
+}
+/** Provider-reported INPUT-token arrays per arm — the only honest input to the engine confirmation gate. */
+export function providerReportedInputArms(experiment) {
+    const control = experiment.runs.filter((r) => r.arm === "control");
+    const treatment = experiment.runs.filter((r) => r.arm === "treatment");
+    const controlInputTokens = control.filter((r) => r.providerReported && typeof r.inputTokens === "number").map((r) => r.inputTokens);
+    const treatmentInputTokens = treatment.filter((r) => r.providerReported && typeof r.inputTokens === "number").map((r) => r.inputTokens);
+    const bothProviderReported = control.length > 0 &&
+        treatment.length > 0 &&
+        controlInputTokens.length === control.length &&
+        treatmentInputTokens.length === treatment.length;
+    return { controlInputTokens, treatmentInputTokens, bothProviderReported };
+}
+//# sourceMappingURL=input-compaction-ab.js.map

package/dist/core/local-run-record.d.ts

@@ -0,0 +1,109 @@
+import type { CrossSurfaceEvent } from "./cross-surface-event.js";
+import type { RunFlowTokenReport } from "./run-flow-report.js";
+/** Default local accumulation directory (sibling of `.compaction/runs`; flat, one file per run). */
+export declare const DEFAULT_RUN_RECORDS_DIRECTORY = ".compaction/run-records";
+/** File name of the per-run copy written next to the run's other artifacts. */
+export declare const RUN_TOKEN_RECORD_FILENAME = "run-token-record.json";
+/** Contract copy (docs/ops/app-source-status-contract.md) — tier labels, verbatim. */
+export declare const TIER_LIVE_LABEL = "live (provider-reported)";
+export declare const TIER_ESTIMATED_LABEL = "estimated (local-estimate)";
+/** Contract copy — the literal output-savings line every tool renders in v1 (no tool has passed the gate). */
+export declare const OUTPUT_SAVINGS_UNAVAILABLE_LINE = "output-token savings: unavailable \u2014 needs a provider-reported A/B that passes the measured criterion + the short-but-sufficient eval.";
+/**
+ * One persisted local run record. `token_report` is the EXISTING `RunFlowTokenReport` shape, embedded
+ * unchanged (no schema migration — additive file, reused record shape).
+ */
+export interface LocalRunTokenRecord {
+    record_version: 1;
+    run_id: string;
+    recorded_at: string;
+    token_report: RunFlowTokenReport;
+    /**
+     * ADDITIVE, OPTIONAL cross-surface event per `docs/ops/cross-surface-evidence-contract.md`
+     * (typed in `src/core/cross-surface-event.ts`). `run cursor` populates it (the first writer —
+     * D3 alignment via `buildCursorRunCrossSurfaceEvent`); other tools remain contract §7 named
+     * follow-ups. When present it rides through write/read/rollup untouched. Validation of this
+     * field is the REPORT-ONLY `validateCrossSurfaceEvent` — an imperfect event here never causes
+     * the record to be skipped (record-level validation is unchanged).
+     */
+    cross_surface_event?: CrossSurfaceEvent;
+}
+export declare function buildLocalRunTokenRecord(params: {
+    runId: string;
+    tokenReport: RunFlowTokenReport;
+    recordedAt?: string;
+    /** Optional additive cross-surface event (see `LocalRunTokenRecord.cross_surface_event`). */
+    crossSurfaceEvent?: CrossSurfaceEvent;
+}): LocalRunTokenRecord;
+/** Validate a parsed record. Invalid records are SKIPPED with a reason — never guessed at. */
+export declare function validateLocalRunTokenRecord(value: unknown): {
+    record?: LocalRunTokenRecord;
+    reason?: string;
+};
+export interface WrittenRunRecordPaths {
+    /** The copy next to the run's other artifacts (self-contained artifact set). */
+    artifactPath: string;
+    /** The accumulated copy `compaction summary` rolls up. */
+    accumulatedPath: string;
+}
+/**
+ * Persist the record LOCALLY, twice: once next to the run's artifacts (`run-token-record.json` in the
+ * run's output directory) and once in the flat accumulation directory so `summary` can roll runs up
+ * without scanning arbitrary --out locations. Local file writes only — never a network call.
+ */
+export declare function writeLocalRunTokenRecord(record: LocalRunTokenRecord, artifactDirectory: string, recordsDirectory?: string): Promise<WrittenRunRecordPaths>;
+export interface SkippedRunRecordFile {
+    path: string;
+    reason: string;
+}
+export interface LoadedRunRecord {
+    path: string;
+    record: LocalRunTokenRecord;
+}
+/** Read all accumulated records. A missing directory means "no records yet" (empty, not an error). */
+export declare function readLocalRunTokenRecords(recordsDirectory?: string): Promise<{
+    records: LoadedRunRecord[];
+    skipped: SkippedRunRecordFile[];
+}>;
+/** Per-axis tier buckets (mirrors the contract tiers). Tokens are summed ONLY within their own tier. */
+export interface PerToolAxisRollup {
+    provider_reported: {
+        runs: number;
+        tokens: number;
+    };
+    local_estimate: {
+        runs: number;
+        tokens: number;
+    };
+    /** Runs where this axis could not be counted honestly — with the honest reasons (never a 0). */
+    unavailable: {
+        runs: number;
+        reasons: string[];
+    };
+}
+export interface PerToolRunRecordRollup {
+    tool: string;
+    runs: number;
+    input: PerToolAxisRollup;
+    output: PerToolAxisRollup;
+    /** LITERAL contract value: no tool has passed the measured + eval-confirmed output-shaping gate. */
+    output_savings: "unavailable";
+    /** Distinct honest notes carried from the runs' capture limitations (content-free, capped). */
+    notes: string[];
+}
+/**
+ * Roll accumulated records up PER TOOL (PURE). Counts + sources only — no cost, no savings math, no
+ * content. Tools are sorted for deterministic output. `output_savings` is always the literal
+ * "unavailable" (contract v1: no tool has measured + eval-confirmed output-shaping evidence).
+ */
+export declare function summarizePerToolRunRecords(records: LocalRunTokenRecord[]): PerToolRunRecordRollup[];
+/** Header stating exactly what this section is (and is not) — printed above the per-tool lines. */
+export declare const PER_TOOL_RECORDS_HEADER: string;
+/** The honest empty state — never fabricated rows for tools that have no records. */
+export declare const PER_TOOL_RECORDS_EMPTY_LINE = "- none yet \u2014 `compaction run \u2026` / `run codex` / `run cursor` accumulate per-run token_source records locally";
+/**
+ * Render the per-tool rollup as indented list lines (shared by the console summary and summary.md).
+ * Copy mirrors the `/app` source-status contract: live (provider-reported) / estimated (local-estimate) /
+ * unavailable — <reason>; plus the literal output-savings unavailable line for EVERY tool.
+ */
+export declare function formatPerToolRunRecordLines(rollups: PerToolRunRecordRollup[]): string[];

package/dist/core/local-run-record.js

@@ -0,0 +1,223 @@
+/**
+ * LOCAL per-run token_source records for the unified `compaction run` flow (PUBLIC CLI/SDK — engine-free).
+ * Design: `docs/design/unified-run-flow.md` (ACCEPTED 2026-06-28) — this is the LOCAL half of the record
+ * step (founder lane-splitting ruling 2026-07-02: local run/reporting work is ungated; hosted-record
+ * wiring stays gated). No network, no hosted config, no schema/trace-format change: each record is an
+ * ADDITIVE local JSON file that embeds the existing `RunFlowTokenReport` shape unchanged.
+ *
+ * What a record is: the SAME honest per-run token report the `run` front-ends already print (input and
+ * output SEPARATE, per-field `token_source` provider-reported | local-estimate | unavailable, honest
+ * notes) — persisted content-free so runs ACCUMULATE locally and `compaction summary` can roll them up
+ * per tool. Counts + sources only: no prompt/output text, no filenames from the wrapped command, no
+ * cost figures, and NEVER a savings figure for output (observed output tokens are tokens, not savings —
+ * founder D2; output-token savings stay gated on measured + eval-confirmed output-shaping).
+ *
+ * The per-tool rollup mirrors the `/app` source-status contract tiers EXACTLY
+ * (`docs/ops/app-source-status-contract.md`): live (provider-reported) / estimated (local-estimate) /
+ * unavailable — <reason> / no records yet. `output_savings` is the LITERAL string "unavailable".
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { writeJsonArtifact } from "./artifact-writer.js";
+/** Default local accumulation directory (sibling of `.compaction/runs`; flat, one file per run). */
+export const DEFAULT_RUN_RECORDS_DIRECTORY = ".compaction/run-records";
+/** File name of the per-run copy written next to the run's other artifacts. */
+export const RUN_TOKEN_RECORD_FILENAME = "run-token-record.json";
+/** Contract copy (docs/ops/app-source-status-contract.md) — tier labels, verbatim. */
+export const TIER_LIVE_LABEL = "live (provider-reported)";
+export const TIER_ESTIMATED_LABEL = "estimated (local-estimate)";
+/** Contract copy — the literal output-savings line every tool renders in v1 (no tool has passed the gate). */
+export const OUTPUT_SAVINGS_UNAVAILABLE_LINE = "output-token savings: unavailable — needs a provider-reported A/B that passes the measured criterion + the short-but-sufficient eval.";
+export function buildLocalRunTokenRecord(params) {
+    return {
+        record_version: 1,
+        run_id: params.runId,
+        recorded_at: params.recordedAt ?? new Date().toISOString(),
+        token_report: params.tokenReport,
+        ...(params.crossSurfaceEvent !== undefined ? { cross_surface_event: params.crossSurfaceEvent } : {})
+    };
+}
+const TOKEN_SOURCES = ["provider-reported", "local-estimate", "unavailable"];
+function isTokenSource(value) {
+    return typeof value === "string" && TOKEN_SOURCES.includes(value);
+}
+function isOptionalCount(value) {
+    return value === undefined || (typeof value === "number" && Number.isFinite(value) && value >= 0);
+}
+/** Validate a parsed record. Invalid records are SKIPPED with a reason — never guessed at. */
+export function validateLocalRunTokenRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { reason: "record is not a JSON object" };
+    }
+    const record = value;
+    if (record.record_version !== 1)
+        return { reason: "unsupported record_version" };
+    if (typeof record.run_id !== "string" || record.run_id.trim() === "")
+        return { reason: "missing or invalid run_id" };
+    if (typeof record.recorded_at !== "string" || record.recorded_at.trim() === "") {
+        return { reason: "missing or invalid recorded_at" };
+    }
+    const report = record.token_report;
+    if (typeof report !== "object" || report === null || Array.isArray(report)) {
+        return { reason: "missing or invalid token_report" };
+    }
+    if (typeof report.tool !== "string" || report.tool.trim() === "")
+        return { reason: "missing or invalid token_report.tool" };
+    if (!isTokenSource(report.input_token_source))
+        return { reason: "invalid token_report.input_token_source" };
+    if (!isTokenSource(report.output_token_source))
+        return { reason: "invalid token_report.output_token_source" };
+    if (!isOptionalCount(report.input_tokens))
+        return { reason: "invalid token_report.input_tokens" };
+    if (!isOptionalCount(report.output_tokens))
+        return { reason: "invalid token_report.output_tokens" };
+    if (report.input_reduction_label !== "measured" && report.input_reduction_label !== "estimated") {
+        return { reason: "invalid token_report.input_reduction_label" };
+    }
+    if (!Array.isArray(report.notes) || report.notes.some((note) => typeof note !== "string")) {
+        return { reason: "invalid token_report.notes" };
+    }
+    return { record: record };
+}
+function accumulationFileName(runId) {
+    return `${runId.replace(/[^A-Za-z0-9._-]/g, "-")}.json`;
+}
+/**
+ * Persist the record LOCALLY, twice: once next to the run's artifacts (`run-token-record.json` in the
+ * run's output directory) and once in the flat accumulation directory so `summary` can roll runs up
+ * without scanning arbitrary --out locations. Local file writes only — never a network call.
+ */
+export async function writeLocalRunTokenRecord(record, artifactDirectory, recordsDirectory = DEFAULT_RUN_RECORDS_DIRECTORY) {
+    const artifactPath = await writeJsonArtifact(artifactDirectory, RUN_TOKEN_RECORD_FILENAME, record);
+    const accumulatedPath = await writeJsonArtifact(recordsDirectory, accumulationFileName(record.run_id), record);
+    return { artifactPath, accumulatedPath };
+}
+/** Read all accumulated records. A missing directory means "no records yet" (empty, not an error). */
+export async function readLocalRunTokenRecords(recordsDirectory = DEFAULT_RUN_RECORDS_DIRECTORY) {
+    let fileNames;
+    try {
+        const entries = await readdir(recordsDirectory, { withFileTypes: true });
+        fileNames = entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "unknown";
+        if (code === "ENOENT")
+            return { records: [], skipped: [] };
+        throw error;
+    }
+    const records = [];
+    const skipped = [];
+    for (const fileName of fileNames) {
+        const path = join(recordsDirectory, fileName);
+        try {
+            const validation = validateLocalRunTokenRecord(JSON.parse(await readFile(path, "utf8")));
+            if (validation.record === undefined) {
+                skipped.push({ path, reason: validation.reason ?? "invalid record" });
+                continue;
+            }
+            records.push({ path, record: validation.record });
+        }
+        catch (error) {
+            skipped.push({ path, reason: error instanceof SyntaxError ? "invalid JSON" : "could not read record" });
+        }
+    }
+    return { records, skipped };
+}
+const MAX_ROLLUP_NOTES = 8;
+const AXIS_UNAVAILABLE_FALLBACK_REASON = "not safely separable / not reported";
+function emptyAxis() {
+    return {
+        provider_reported: { runs: 0, tokens: 0 },
+        local_estimate: { runs: 0, tokens: 0 },
+        unavailable: { runs: 0, reasons: [] }
+    };
+}
+function addDistinctCapped(list, value, cap) {
+    if (list.length < cap && !list.includes(value))
+        list.push(value);
+}
+function addToAxis(axis, axisName, source, tokens, notes) {
+    // Honesty rail: a count lands in a tier ONLY when the source is that tier AND a real count exists.
+    // A missing count — whatever the claimed source — is `unavailable`, never a silent zero.
+    if (source === "provider-reported" && tokens !== undefined) {
+        axis.provider_reported.runs += 1;
+        axis.provider_reported.tokens += tokens;
+        return;
+    }
+    if (source === "local-estimate" && tokens !== undefined) {
+        axis.local_estimate.runs += 1;
+        axis.local_estimate.tokens += tokens;
+        return;
+    }
+    axis.unavailable.runs += 1;
+    // Prefer the notes that actually talk about THIS axis (e.g. the output-unavailable reason for the
+    // output axis) so the displayed reason is the honest one; fall back to all notes, then the generic.
+    const axisNotes = notes.filter((note) => note.toLowerCase().includes(axisName));
+    const reasons = axisNotes.length > 0 ? axisNotes : notes.length > 0 ? notes : [AXIS_UNAVAILABLE_FALLBACK_REASON];
+    for (const reason of reasons)
+        addDistinctCapped(axis.unavailable.reasons, reason, MAX_ROLLUP_NOTES);
+}
+/**
+ * Roll accumulated records up PER TOOL (PURE). Counts + sources only — no cost, no savings math, no
+ * content. Tools are sorted for deterministic output. `output_savings` is always the literal
+ * "unavailable" (contract v1: no tool has measured + eval-confirmed output-shaping evidence).
+ */
+export function summarizePerToolRunRecords(records) {
+    const byTool = new Map();
+    for (const record of records) {
+        const report = record.token_report;
+        let rollup = byTool.get(report.tool);
+        if (rollup === undefined) {
+            rollup = { tool: report.tool, runs: 0, input: emptyAxis(), output: emptyAxis(), output_savings: "unavailable", notes: [] };
+            byTool.set(report.tool, rollup);
+        }
+        rollup.runs += 1;
+        addToAxis(rollup.input, "input", report.input_token_source, report.input_tokens, report.notes);
+        addToAxis(rollup.output, "output", report.output_token_source, report.output_tokens, report.notes);
+        for (const note of report.notes)
+            addDistinctCapped(rollup.notes, note, MAX_ROLLUP_NOTES);
+    }
+    return [...byTool.values()].sort((a, b) => a.tool.localeCompare(b.tool));
+}
+function axisParts(axis) {
+    const parts = [];
+    if (axis.provider_reported.runs > 0) {
+        parts.push(`${axis.provider_reported.tokens} tokens ${TIER_LIVE_LABEL} across ${axis.provider_reported.runs} run(s)`);
+    }
+    if (axis.local_estimate.runs > 0) {
+        parts.push(`${axis.local_estimate.tokens} tokens ${TIER_ESTIMATED_LABEL} across ${axis.local_estimate.runs} run(s)`);
+    }
+    if (axis.unavailable.runs > 0) {
+        const reason = axis.unavailable.reasons[0] ?? AXIS_UNAVAILABLE_FALLBACK_REASON;
+        parts.push(`unavailable for ${axis.unavailable.runs} run(s) — ${reason}`);
+    }
+    return parts.length > 0 ? parts : [`unavailable — ${AXIS_UNAVAILABLE_FALLBACK_REASON}`];
+}
+/** Header stating exactly what this section is (and is not) — printed above the per-tool lines. */
+export const PER_TOOL_RECORDS_HEADER = "Per-tool run records (local, content-free): observed token counts + their token_source per axis; " +
+    "input and output separate; output shown as tokens, never as a savings figure.";
+/** The honest empty state — never fabricated rows for tools that have no records. */
+export const PER_TOOL_RECORDS_EMPTY_LINE = "- none yet — `compaction run …` / `run codex` / `run cursor` accumulate per-run token_source records locally";
+/**
+ * Render the per-tool rollup as indented list lines (shared by the console summary and summary.md).
+ * Copy mirrors the `/app` source-status contract: live (provider-reported) / estimated (local-estimate) /
+ * unavailable — <reason>; plus the literal output-savings unavailable line for EVERY tool.
+ */
+export function formatPerToolRunRecordLines(rollups) {
+    if (rollups.length === 0)
+        return [PER_TOOL_RECORDS_EMPTY_LINE];
+    const lines = [];
+    for (const rollup of rollups) {
+        lines.push(`- ${rollup.tool}: ${rollup.runs} run(s)`);
+        lines.push(`  - input: ${axisParts(rollup.input).join("; ")}`);
+        lines.push(`  - output: ${axisParts(rollup.output).join("; ")}`);
+        lines.push(`  - ${OUTPUT_SAVINGS_UNAVAILABLE_LINE}`);
+        for (const note of rollup.notes)
+            lines.push(`  - note: ${note}`);
+    }
+    return lines;
+}
+//# sourceMappingURL=local-run-record.js.map