@compaction/cli 0.2.0 → 0.3.0

package/dist/core/hook-usage-aggregate.js

@@ -0,0 +1,161 @@
+/**
+ * Aggregate the content-free Claude Code hook usage records (PUBLIC CLI/SDK code, engine-free).
+ * Rolls up the records written by `capture claude-code --from-hook`
+ * (`.compaction/hooks/**​/records/*.json`) into a CONTENT-FREE source-status view — by tool, by session,
+ * and over a time window — mirroring the `/app` source-status model (events / input / output / token
+ * sources / providers / models / provider-reported-vs-unavailable). Local-first; no network.
+ *
+ * Honesty rails (binding):
+ *  - Content-free in / content-free out: counts, honest source, ids, providers, models, timestamps only.
+ *    No prompt/completion/message content, no transcript content, no `last_assistant_message`.
+ *  - Missing usage stays **null / unavailable**, never 0. A tool with no recorded input tokens reports
+ *    `inputTokens: null`, not 0.
+ *  - Token source labels are preserved exactly (provider-reported / local-estimate / unknown).
+ *  - Idempotent: records are deduped by `dedupKey` so the same Stop/session state is counted once.
+ *  - NO savings claim — this surfaces usage only.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { CLAUDE_CODE_HOOK_RECORD_SCHEMA } from "./claude-code-hook-record.js";
+export const HOOK_USAGE_AGGREGATE_SCHEMA = "compaction.hook-usage-aggregate.v1";
+/** A loaded record plus nothing else — we only ever read the content-free fields. */
+function isHookRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return v.schema === CLAUDE_CODE_HOOK_RECORD_SCHEMA && typeof v.dedupKey === "string" && typeof v.tool === "string";
+}
+/** Recursively find `*.json` files under any `records/` directory below baseDir. */
+async function findRecordFiles(baseDir) {
+    const out = [];
+    async function walk(dir) {
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch {
+            return; // missing dir → no records (not an error)
+        }
+        for (const name of names) {
+            const full = path.join(dir, name);
+            let isDir = false;
+            try {
+                isDir = (await stat(full)).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (isDir) {
+                await walk(full);
+            }
+            else if (name.endsWith(".json") && path.basename(dir) === "records") {
+                out.push(full);
+            }
+        }
+    }
+    await walk(baseDir);
+    return out;
+}
+/** Load + validate all hook usage records under baseDir (default `.compaction/hooks`). Invalid files skipped. */
+export async function loadHookUsageRecords(baseDir = ".compaction/hooks") {
+    const files = await findRecordFiles(baseDir);
+    const records = [];
+    for (const file of files) {
+        try {
+            const parsed = JSON.parse(await readFile(file, "utf8"));
+            if (isHookRecord(parsed))
+                records.push(parsed);
+        }
+        catch {
+            // skip unreadable/invalid record file (never throw — local-first, best-effort)
+        }
+    }
+    return records;
+}
+function addToken(acc, value) {
+    if (value === null)
+        return acc; // missing contributes nothing and never coerces to 0
+    return (acc ?? 0) + value;
+}
+/**
+ * Aggregate hook records into a content-free source-status view. Dedups by `dedupKey`. Missing token
+ * counts stay null. Token source labels preserved exactly. No savings, no content.
+ */
+export function aggregateHookUsageRecords(records, options = {}) {
+    const since = options.since ?? null;
+    // Apply the time-window filter first, then dedup by dedupKey (records are already deduped at write time;
+    // this is defensive). `totalRecords` counts records IN the window so "deduped from N" reads accurately
+    // under --since. When `since` is set, a record with a missing/non-string recordedAt is EXCLUDED (a record
+    // with no timestamp cannot be proven to fall inside the window).
+    let totalRecords = 0;
+    const deduped = new Map();
+    for (const r of records) {
+        if (since !== null && (typeof r.recordedAt !== "string" || r.recordedAt < since))
+            continue;
+        totalRecords += 1;
+        if (!deduped.has(r.dedupKey))
+            deduped.set(r.dedupKey, r);
+    }
+    const byTool = new Map();
+    const sessionsByTool = new Map();
+    for (const r of deduped.values()) {
+        let agg = byTool.get(r.tool);
+        if (!agg) {
+            agg = {
+                tool: r.tool,
+                events: 0,
+                inputTokens: null,
+                outputTokens: null,
+                reasoningTokens: null,
+                tokenSources: [],
+                providers: [],
+                models: [],
+                outputRecorded: 0,
+                providerReportedEvents: 0,
+                unavailableEvents: 0,
+                sessions: 0,
+                firstRecordedAt: null,
+                lastRecordedAt: null
+            };
+            byTool.set(r.tool, agg);
+            sessionsByTool.set(r.tool, new Set());
+        }
+        agg.events += 1;
+        agg.inputTokens = addToken(agg.inputTokens, r.inputTokens ?? null);
+        agg.outputTokens = addToken(agg.outputTokens, r.outputTokens ?? null);
+        if (typeof r.outputTokens === "number")
+            agg.outputRecorded += 1;
+        if (r.providerReported === true)
+            agg.providerReportedEvents += 1;
+        if ((r.inputTokens ?? null) === null && (r.outputTokens ?? null) === null)
+            agg.unavailableEvents += 1;
+        if (r.tokenSource && !agg.tokenSources.includes(r.tokenSource))
+            agg.tokenSources.push(r.tokenSource);
+        if (r.provider && !agg.providers.includes(r.provider))
+            agg.providers.push(r.provider);
+        if (r.model && !agg.models.includes(r.model))
+            agg.models.push(r.model);
+        if (r.sessionId)
+            sessionsByTool.get(r.tool).add(r.sessionId);
+        if (typeof r.recordedAt === "string") {
+            if (agg.firstRecordedAt === null || r.recordedAt < agg.firstRecordedAt)
+                agg.firstRecordedAt = r.recordedAt;
+            if (agg.lastRecordedAt === null || r.recordedAt > agg.lastRecordedAt)
+                agg.lastRecordedAt = r.recordedAt;
+        }
+    }
+    for (const [tool, agg] of byTool) {
+        agg.sessions = sessionsByTool.get(tool).size;
+        agg.tokenSources.sort();
+        agg.providers.sort();
+        agg.models.sort();
+    }
+    return {
+        schema: HOOK_USAGE_AGGREGATE_SCHEMA,
+        totalRecords,
+        dedupedRecords: deduped.size,
+        since,
+        tools: Array.from(byTool.values()).sort((a, b) => a.tool.localeCompare(b.tool))
+    };
+}
+//# sourceMappingURL=hook-usage-aggregate.js.map

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[];