@compaction/cli 0.2.0 → 0.3.1

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

package/dist/core/output-shaping-ab.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Output-shaping A/B experiment record + summary (PUBLIC CLI/SDK code — engine-free, ships in the npm CLI).
+ * Increment 4 of the output-shaping policy family (`docs/design/output-shaping-policy-family.md`): the
+ * smallest reliable OPERATOR-RUN path to produce + ingest a real provider-reported A/B comparison between
+ * a control arm (Codex live wrapper without output-shaping) and a treatment arm (with `--output-shaping`).
+ *
+ * Boundary / honesty (binding):
+ *  - This PUBLIC module links the two arms and computes the **observed** measurement (means, delta,
+ *    reduction %, N per arm) for operator visibility. It is **descriptive, NOT a savings claim.**
+ *  - It NEVER produces a CONFIRMED output-savings number. `confirmedSavingsEligible` is the literal `false`
+ *    here; a confirmed number can only ever be produced by the PRIVATE engine gate
+ *    (`src/engine/output-shaping-verification.ts` — provider-reported A/B meeting the billing-delta
+ *    criterion AND short-but-sufficient eval AND a reduction).
+ *  - Output tokens that are not provider-reported (e.g. Cursor — local-estimate only) yield
+ *    `confidence: "unavailable"` and can never be eligible. Missing output tokens stay unavailable, not 0.
+ *  - The record is content-free: it stores token counts, the honest source, policy NAMES, operator eval
+ *    outcome, and truncation/refusal flags — no prompt/response/trace content. Local artifact paths are
+ *    operator-side references only.
+ */
+import type { TokenSource, ToolName } from "./api-client/index.js";
+export declare const OUTPUT_SHAPING_AB_SCHEMA: "output-shaping.ab-experiment.v1";
+export declare const CAPTURE_USAGE_SIDECAR_SCHEMA: "compaction.capture-usage.v1";
+export declare const OUTPUT_SHAPING_POLICY_FAMILY: "output_shaping";
+/**
+ * Written next to a capture artifact so a later A/B `add` can ingest the **provider-reported** tokens +
+ * (treatment) policy attribution without re-running anything. Content-free: counts + source + policy names.
+ */
+export interface CaptureUsageSidecar {
+    schema: typeof CAPTURE_USAGE_SIDECAR_SCHEMA;
+    tool: ToolName;
+    provider?: string;
+    model?: string;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    /** True ONLY when the counts are provider-reported (never local-estimate / unavailable). */
+    providerReported: boolean;
+    tokenSource: TokenSource;
+    /** "present" when the provider emitted a usage block; "missing" when usage was absent (never invented). */
+    tokenMetadataStatus: "present" | "missing";
+    /** Present on the treatment arm when an output-shaping policy was attached BEFORE generation. */
+    outputShaping?: {
+        policyFamily: typeof OUTPUT_SHAPING_POLICY_FAMILY;
+        policyNames: string[];
+    };
+    generatedAt: string;
+}
+export interface BuildCaptureUsageSidecarInput {
+    tool: ToolName;
+    provider?: string;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    providerReported: boolean;
+    tokenSource: TokenSource;
+    tokenMetadataStatus: "present" | "missing";
+    policyNames?: string[];
+    generatedAt?: string;
+}
+export declare function buildCaptureUsageSidecar(input: BuildCaptureUsageSidecarInput): CaptureUsageSidecar;
+export type OutputShapingAbArm = "control" | "treatment";
+export interface OutputShapingAbRun {
+    arm: OutputShapingAbArm;
+    /** Provider-reported output tokens; null when unavailable (never invented as 0). */
+    outputTokens: number | null;
+    inputTokens: number | null;
+    /** True ONLY when the output tokens are provider-reported. */
+    providerReported: boolean;
+    tokenSource: TokenSource;
+    /** Treatment arm: the output-shaping policy family/names attached BEFORE generation. */
+    policyFamily?: typeof OUTPUT_SHAPING_POLICY_FAMILY;
+    policyNames?: string[];
+    /**
+     * Operator/eval-recorded short-but-sufficient outcome for a TREATMENT run: did the shaped (shorter)
+     * output preserve all required task-outcome markers? `null`/absent ⇒ not yet evaluated (review required).
+     * The rigorous marker check is the engine eval; this is the recorded outcome.
+     */
+    evalMarkersPreserved?: boolean | null;
+    /** Observed truncation of the answer (an incomplete answer is not a saving). */
+    truncated?: boolean;
+    /** Observed refusal (a refusal is not a saving). */
+    refused?: boolean;
+    /** Local artifact path — operator-side evidence only, never content. */
+    reference?: string;
+}
+export interface OutputShapingAbExperiment {
+    schema: typeof OUTPUT_SHAPING_AB_SCHEMA;
+    experimentId: string;
+    /** A short generic label of the shared task/prompt SHAPE (operator-supplied; not prompt content). */
+    taskShape: string;
+    createdAt: string;
+    runs: OutputShapingAbRun[];
+}
+export interface InitOutputShapingAbInput {
+    experimentId: string;
+    taskShape: string;
+    createdAt?: string;
+}
+export declare function initOutputShapingAbExperiment(input: InitOutputShapingAbInput): OutputShapingAbExperiment;
+export declare function addOutputShapingAbRun(experiment: OutputShapingAbExperiment, run: OutputShapingAbRun): OutputShapingAbExperiment;
+/**
+ * Public confidence ladder. NONE of these is a confirmed savings claim.
+ *  - `unavailable`                       — an arm's output tokens are not provider-reported / are missing.
+ *  - `review_required`                   — truncation/refusal observed, or treatment sufficiency not a clean pass.
+ *  - `observed_not_confirmed`            — provider-reported both arms, sufficiency passed, but N < 3 per arm.
+ *  - `eligible_for_engine_confirmation`  — all public preconditions met; the CONFIRMED verdict is an engine step.
+ */
+export type OutputShapingAbConfidence = "unavailable" | "review_required" | "observed_not_confirmed" | "eligible_for_engine_confirmation";
+export type OutputShapingAbEvalStatus = "pass" | "fail" | "not_evaluated" | "mixed";
+export interface OutputShapingAbSummary {
+    experimentId: string;
+    nControl: number;
+    nTreatment: number;
+    /** Mean control (no-shaping) output tokens — provider-reported; null when unavailable. */
+    outputTokensBefore: number | null;
+    /** Mean treatment (shaped) output tokens — provider-reported; null when unavailable. */
+    outputTokensAfter: number | null;
+    /** before − after: positive ⇒ treatment used FEWER output tokens. OBSERVED, not a confirmed saving. */
+    outputTokenDelta: number | null;
+    outputTokenReductionPct: number | null;
+    tokenSource: "provider-reported" | "mixed" | "local-estimate" | "unavailable";
+    policyFamily: string | null;
+    policyNames: string[];
+    evalStatus: OutputShapingAbEvalStatus;
+    confidence: OutputShapingAbConfidence;
+    /** ALWAYS false in the public CLI — a confirmed savings number is produced only by the engine gate. */
+    confirmedSavingsEligible: false;
+    reasons: string[];
+}
+/**
+ * Compute the OBSERVED A/B measurement + a conservative confidence. Never confirms a saving (that is the
+ * engine gate). The decision order is fail-safe: unavailable → review_required → observed_not_confirmed →
+ * eligible_for_engine_confirmation. Means/delta/pct are computed only from provider-reported output tokens.
+ */
+export declare function summarizeOutputShapingAb(experiment: OutputShapingAbExperiment): OutputShapingAbSummary;
+/** Provider-reported output-token arrays per arm — the only honest input to the engine confirmation gate. */
+export declare function providerReportedOutputArms(experiment: OutputShapingAbExperiment): {
+    controlOutputTokens: number[];
+    treatmentOutputTokens: number[];
+    bothProviderReported: boolean;
+};

package/dist/core/output-shaping-ab.js

@@ -0,0 +1,146 @@
+export const OUTPUT_SHAPING_AB_SCHEMA = "output-shaping.ab-experiment.v1";
+export const CAPTURE_USAGE_SIDECAR_SCHEMA = "compaction.capture-usage.v1";
+export const OUTPUT_SHAPING_POLICY_FAMILY = "output_shaping";
+export function buildCaptureUsageSidecar(input) {
+    return {
+        schema: CAPTURE_USAGE_SIDECAR_SCHEMA,
+        tool: input.tool,
+        ...(input.provider ? { provider: input.provider } : {}),
+        ...(input.model ? { model: input.model } : {}),
+        inputTokens: typeof input.inputTokens === "number" ? input.inputTokens : null,
+        outputTokens: typeof input.outputTokens === "number" ? input.outputTokens : null,
+        providerReported: input.providerReported,
+        tokenSource: input.tokenSource,
+        tokenMetadataStatus: input.tokenMetadataStatus,
+        ...(input.policyNames && input.policyNames.length > 0
+            ? { outputShaping: { policyFamily: OUTPUT_SHAPING_POLICY_FAMILY, policyNames: input.policyNames } }
+            : {}),
+        generatedAt: input.generatedAt ?? new Date().toISOString()
+    };
+}
+export function initOutputShapingAbExperiment(input) {
+    return {
+        schema: OUTPUT_SHAPING_AB_SCHEMA,
+        experimentId: input.experimentId,
+        taskShape: input.taskShape,
+        createdAt: input.createdAt ?? new Date().toISOString(),
+        runs: []
+    };
+}
+export function addOutputShapingAbRun(experiment, run) {
+    return { ...experiment, runs: [...experiment.runs, run] };
+}
+const MIN_RUNS_PER_ARM = 3;
+function mean(xs) {
+    return xs.reduce((s, x) => s + x, 0) / xs.length;
+}
+function summarizeArmSource(runs) {
+    if (runs.length === 0)
+        return "unavailable";
+    const allProvider = runs.every((r) => r.providerReported && typeof r.outputTokens === "number");
+    if (allProvider)
+        return "provider-reported";
+    const anyProvider = runs.some((r) => r.providerReported && typeof r.outputTokens === "number");
+    if (anyProvider)
+        return "mixed";
+    const anyEstimate = runs.some((r) => r.tokenSource === "local-estimate");
+    return anyEstimate ? "local-estimate" : "unavailable";
+}
+function treatmentEvalStatus(treatment) {
+    if (treatment.length === 0)
+        return "not_evaluated";
+    const outcomes = treatment.map((r) => r.evalMarkersPreserved);
+    if (outcomes.some((o) => o === undefined || o === null)) {
+        return outcomes.some((o) => o === true || o === false) ? "mixed" : "not_evaluated";
+    }
+    if (outcomes.every((o) => o === true))
+        return "pass";
+    if (outcomes.every((o) => o === false))
+        return "fail";
+    return "mixed";
+}
+/**
+ * Compute the OBSERVED A/B measurement + a conservative confidence. Never confirms a saving (that is the
+ * engine gate). The decision order is fail-safe: unavailable → review_required → observed_not_confirmed →
+ * eligible_for_engine_confirmation. Means/delta/pct are computed only from provider-reported output tokens.
+ */
+export function summarizeOutputShapingAb(experiment) {
+    const control = experiment.runs.filter((r) => r.arm === "control");
+    const treatment = experiment.runs.filter((r) => r.arm === "treatment");
+    const reasons = [];
+    const controlOut = control.filter((r) => r.providerReported && typeof r.outputTokens === "number").map((r) => r.outputTokens);
+    const treatmentOut = treatment.filter((r) => r.providerReported && typeof r.outputTokens === "number").map((r) => r.outputTokens);
+    const bothProviderReported = control.length > 0 &&
+        treatment.length > 0 &&
+        control.every((r) => r.providerReported && typeof r.outputTokens === "number") &&
+        treatment.every((r) => r.providerReported && typeof r.outputTokens === "number");
+    const outputTokensBefore = controlOut.length > 0 ? mean(controlOut) : null;
+    const outputTokensAfter = treatmentOut.length > 0 ? mean(treatmentOut) : null;
+    const outputTokenDelta = outputTokensBefore !== null && outputTokensAfter !== null ? outputTokensBefore - outputTokensAfter : null;
+    const outputTokenReductionPct = outputTokenDelta !== null && outputTokensBefore !== null && outputTokensBefore > 0
+        ? (outputTokenDelta / outputTokensBefore) * 100
+        : null;
+    const controlSource = summarizeArmSource(control);
+    const treatmentSource = summarizeArmSource(treatment);
+    const tokenSource = bothProviderReported
+        ? "provider-reported"
+        : controlSource === "local-estimate" || treatmentSource === "local-estimate"
+            ? "local-estimate"
+            : controlSource === "mixed" || treatmentSource === "mixed"
+                ? "mixed"
+                : "unavailable";
+    const policyNames = Array.from(new Set(treatment.flatMap((r) => r.policyNames ?? []))).sort();
+    const policyFamily = treatment.some((r) => r.policyFamily) ? OUTPUT_SHAPING_POLICY_FAMILY : null;
+    const evalStatus = treatmentEvalStatus(treatment);
+    const anyTruncatedOrRefused = treatment.some((r) => r.truncated || r.refused) || control.some((r) => r.truncated || r.refused);
+    let confidence;
+    if (!bothProviderReported) {
+        confidence = "unavailable";
+        reasons.push("output savings unavailable: both arms must have provider-reported output tokens (local-estimate / missing output can never produce an output-savings number).");
+    }
+    else if (anyTruncatedOrRefused) {
+        confidence = "review_required";
+        reasons.push("review required: a run was marked truncated or refused — an incomplete answer is not a saving.");
+    }
+    else if (evalStatus !== "pass") {
+        confidence = "review_required";
+        reasons.push(`review required: treatment short-but-sufficient eval status is "${evalStatus}" (a shorter-but-lossy output is not a saving; record --eval-pass/--eval-fail 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}). A single A/B pair is an anecdote.`);
+    }
+    else {
+        confidence = "eligible_for_engine_confirmation";
+        reasons.push("eligible for engine confirmation: provider-reported both arms, N ≥ 3 per arm, sufficiency passed, no truncation/refusal. The CONFIRMED verdict is the engine gate (measured ±2·SE criterion + reduction).");
+    }
+    return {
+        experimentId: experiment.experimentId,
+        nControl: control.length,
+        nTreatment: treatment.length,
+        outputTokensBefore,
+        outputTokensAfter,
+        outputTokenDelta,
+        outputTokenReductionPct,
+        tokenSource,
+        policyFamily,
+        policyNames,
+        evalStatus,
+        confidence,
+        confirmedSavingsEligible: false,
+        reasons
+    };
+}
+/** Provider-reported output-token arrays per arm — the only honest input to the engine confirmation gate. */
+export function providerReportedOutputArms(experiment) {
+    const control = experiment.runs.filter((r) => r.arm === "control");
+    const treatment = experiment.runs.filter((r) => r.arm === "treatment");
+    const controlOutputTokens = control.filter((r) => r.providerReported && typeof r.outputTokens === "number").map((r) => r.outputTokens);
+    const treatmentOutputTokens = treatment.filter((r) => r.providerReported && typeof r.outputTokens === "number").map((r) => r.outputTokens);
+    const bothProviderReported = control.length > 0 &&
+        treatment.length > 0 &&
+        controlOutputTokens.length === control.length &&
+        treatmentOutputTokens.length === treatment.length;
+    return { controlOutputTokens, treatmentOutputTokens, bothProviderReported };
+}
+//# sourceMappingURL=output-shaping-ab.js.map

package/dist/core/output-shaping-attach.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Attach the output-shaping instruction block to a wrapped CLI command's prompt BEFORE generation
+ * (PUBLIC CLI/SDK code, engine-free). Increment 3 of the output-shaping policy family — wiring the
+ * deterministic policies (`output-shaping.ts`) into the live wrappers (`capture codex`/`capture cursor`).
+ *
+ * Mechanism honesty: output-token reduction requires shaping the request BEFORE generation. This prepends
+ * the instruction block to the prompt argument the wrapper is about to run. It is OPT-IN, the original
+ * command is preserved by the caller, and it surfaces NO output-savings number (a savings figure requires
+ * the private measured-A/B + short-but-sufficient eval gate — `src/engine/output-shaping-verification.ts`).
+ */
+import { type BuildOutputShapingOptions, type OutputShapingAttribution } from "./output-shaping.js";
+/**
+ * Index of the last positional (prompt) argument in a wrapped command — skipping the executable, flags,
+ * value-taking flags' values, and known subcommand keywords. Returns -1 when no prompt arg is found.
+ */
+export declare function findPromptArgIndex(commandParts: string[]): number;
+export interface AttachOutputShapingResult {
+    /** The command to run (a COPY; the original is untouched). When not attached, equals the input. */
+    commandParts: string[];
+    /** The output-shaping policies applied (content-free attribution); empty when not attached. */
+    applied: OutputShapingAttribution[];
+    attached: boolean;
+    /** Why attachment did not happen (e.g. no prompt arg, no matching policies). */
+    reason?: string;
+}
+/**
+ * Prepend the output-shaping instruction block to the prompt argument of `commandParts`. Returns a COPY
+ * (never mutates the input). When no prompt arg is found, or no policies match, returns `attached: false`
+ * with the original command + a reason — never silently shapes the wrong argument.
+ */
+export declare function attachOutputShapingToCommand(commandParts: string[], opts?: BuildOutputShapingOptions): AttachOutputShapingResult;

package/dist/core/output-shaping-attach.js

@@ -0,0 +1,57 @@
+/**
+ * Attach the output-shaping instruction block to a wrapped CLI command's prompt BEFORE generation
+ * (PUBLIC CLI/SDK code, engine-free). Increment 3 of the output-shaping policy family — wiring the
+ * deterministic policies (`output-shaping.ts`) into the live wrappers (`capture codex`/`capture cursor`).
+ *
+ * Mechanism honesty: output-token reduction requires shaping the request BEFORE generation. This prepends
+ * the instruction block to the prompt argument the wrapper is about to run. It is OPT-IN, the original
+ * command is preserved by the caller, and it surfaces NO output-savings number (a savings figure requires
+ * the private measured-A/B + short-but-sufficient eval gate — `src/engine/output-shaping-verification.ts`).
+ */
+import { buildOutputShapingPolicy } from "./output-shaping.js";
+// Boolean flags take no value, so the token after them is still a positional (the prompt).
+const BOOLEAN_FLAGS = new Set(["-p", "--print", "--force", "--json", "--quiet", "-q", "--yes", "-y"]);
+const SUBCOMMAND_KEYWORDS = new Set(["cursor", "cursor-agent", "codex", "agent", "chat", "exec", "run"]);
+/**
+ * Index of the last positional (prompt) argument in a wrapped command — skipping the executable, flags,
+ * value-taking flags' values, and known subcommand keywords. Returns -1 when no prompt arg is found.
+ */
+export function findPromptArgIndex(commandParts) {
+    let last = -1;
+    let skipNext = false;
+    for (let i = 1; i < commandParts.length; i++) {
+        const part = commandParts[i];
+        if (skipNext) {
+            skipNext = false; // value of a preceding value-taking flag (e.g. `--output-format json`)
+            continue;
+        }
+        if (part.startsWith("-")) {
+            if (!BOOLEAN_FLAGS.has(part) && !part.includes("="))
+                skipNext = true;
+            continue;
+        }
+        if (SUBCOMMAND_KEYWORDS.has(part))
+            continue;
+        last = i;
+    }
+    return last;
+}
+/**
+ * Prepend the output-shaping instruction block to the prompt argument of `commandParts`. Returns a COPY
+ * (never mutates the input). When no prompt arg is found, or no policies match, returns `attached: false`
+ * with the original command + a reason — never silently shapes the wrong argument.
+ */
+export function attachOutputShapingToCommand(commandParts, opts = {}) {
+    const { instructions, applied } = buildOutputShapingPolicy(opts);
+    if (instructions === "" || applied.length === 0) {
+        return { commandParts: [...commandParts], applied: [], attached: false, reason: "no matching output-shaping policies" };
+    }
+    const idx = findPromptArgIndex(commandParts);
+    if (idx === -1) {
+        return { commandParts: [...commandParts], applied: [], attached: false, reason: "no prompt argument found to attach the output-shaping policy to" };
+    }
+    const next = [...commandParts];
+    next[idx] = `${instructions}\n\n${next[idx]}`;
+    return { commandParts: next, applied, attached: true };
+}
+//# sourceMappingURL=output-shaping-attach.js.map

package/dist/core/output-shaping.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Output-shaping policy family — deterministic, rule-based (PUBLIC CLI/SDK code, engine-free).
+ *
+ * Design: `docs/design/output-shaping-policy-family.md` (accepted; implementation authorized 2026-06-29).
+ * This is **increment 1**: the public/free deterministic policies that produce a CONTENT-FREE
+ * output-shaping **instruction block** to attach to a request **BEFORE generation** (the only mechanism
+ * that can reduce provider output tokens — post-generation processing does NOT).
+ *
+ * HONESTY (binding):
+ * - This module produces INSTRUCTIONS + attribution labels only. It computes **NO output-savings number**
+ *   and makes **NO claim** that output was reduced. An output-savings number requires (separately, in the
+ *   private/proprietary engine) a **measured A/B** (provider-reported output; N≥3/arm, ±2·SE excludes
+ *   zero) **AND** the **eval-gated short-but-sufficient** check. Until both pass, savings are unavailable.
+ * - The short-but-sufficient **eval** (policy #6 in the design) is the **private eval-gated verification**
+ *   — it is NOT in this public module; this module only emits the shaping instructions + their attribution.
+ * - Content-free: instructions are generic shaping text; no prompt/completion/trace content.
+ */
+export type RiskLevel = "low" | "medium" | "high";
+/** Content-free attribution for a recorded run (matches the control-plane policy_* columns). */
+export interface OutputShapingAttribution {
+    policy_name: string;
+    policy_family: "output_shaping";
+    risk_level: RiskLevel;
+}
+export interface OutputShapingPolicy extends OutputShapingAttribution {
+    /** Human-readable description (what the policy instructs — never content). */
+    description: string;
+    /** Whether the policy is part of the default rule-based set. */
+    defaultOn: boolean;
+    /** Builds the instruction line(s). `verbosityBudgetTokens` is used only by the verbosity-budget policy. */
+    instruction(verbosityBudgetTokens?: number): string;
+}
+/**
+ * The deterministic rule-based output-shaping policies (the public/free tier). The learned tier and the
+ * eval-gated verification are private/proprietary (Track A) — not here.
+ */
+export declare const OUTPUT_SHAPING_POLICIES: readonly OutputShapingPolicy[];
+/** Note attached to every emitted block: this is a request-shaping instruction, not a savings claim. */
+export declare const OUTPUT_SHAPING_HONESTY_NOTE: string;
+export interface OutputShapingResult {
+    /** The content-free instruction block to prepend to the request/system prompt BEFORE generation. */
+    instructions: string;
+    /** Attribution for the applied policies (content-free; for recording / reporting). */
+    applied: OutputShapingAttribution[];
+}
+export interface BuildOutputShapingOptions {
+    /** Policy names to apply; defaults to the `defaultOn` set. Unknown names are ignored (never invented). */
+    policies?: string[];
+    /** Soft verbosity budget in output tokens (used by the verbosity-budget policy). */
+    verbosityBudgetTokens?: number;
+}
+/**
+ * Build the content-free output-shaping instruction block + attribution from the deterministic family.
+ * Produces instructions only — NO savings number, NO claim of reduction.
+ */
+export declare function buildOutputShapingPolicy(opts?: BuildOutputShapingOptions): OutputShapingResult;