@compaction/cli 0.1.4 → 0.3.0

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;

package/dist/core/output-shaping.js

@@ -0,0 +1,89 @@
+/**
+ * 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.
+ */
+/**
+ * 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 const OUTPUT_SHAPING_POLICIES = [
+    {
+        policy_name: "concise_response",
+        policy_family: "output_shaping",
+        risk_level: "low",
+        defaultOn: true,
+        description: "Ask for a concise answer where the task allows (no padding, no restating the prompt).",
+        instruction: () => "Answer concisely: omit preamble and restatement of the request; give only what the task needs."
+    },
+    {
+        policy_name: "verbosity_budget",
+        policy_family: "output_shaping",
+        risk_level: "low",
+        defaultOn: true,
+        description: "Set a soft target on response length (a budget, not a hard cap).",
+        instruction: (budget) => typeof budget === "number" && budget > 0
+            ? `Aim to stay within roughly ${budget} output tokens; prioritize the most task-relevant content if space is tight.`
+            : "Keep the response as short as is sufficient for the task; do not pad to fill space."
+    },
+    {
+        policy_name: "structured_output_constraints",
+        policy_family: "output_shaping",
+        risk_level: "low",
+        defaultOn: true,
+        description: "Prefer a bounded, structured format (lists/sections) that reduces filler.",
+        instruction: () => "Prefer a tight structured format (short bullets or labeled sections) over long prose where it fits the task."
+    },
+    {
+        policy_name: "redundant_chatter_suppression",
+        policy_family: "output_shaping",
+        risk_level: "low",
+        defaultOn: true,
+        description: "Suppress boilerplate, preamble, apologies, and repetition.",
+        instruction: () => "Skip boilerplate, apologies, and repetition; do not summarize what you just said."
+    },
+    {
+        policy_name: "safe_tool_output_filtering",
+        policy_family: "output_shaping",
+        // Slightly higher risk: trimming tool output can drop detail, so it is OFF by default and only
+        // requests omission of clearly-redundant tool echo — recoverability of task-critical detail first.
+        risk_level: "medium",
+        defaultOn: false,
+        description: "Request omission of clearly-redundant tool-output echo (recoverability preserved first).",
+        instruction: () => "Do not echo large tool outputs verbatim; reference them and include only the task-relevant lines."
+    }
+];
+/** Note attached to every emitted block: this is a request-shaping instruction, not a savings claim. */
+export const OUTPUT_SHAPING_HONESTY_NOTE = "Attach BEFORE generation (post-generation processing does not reduce provider output tokens). " +
+    "No output-token savings are claimed: a savings figure requires a measured before/after (provider-reported) " +
+    "and eval-confirmed sufficiency — neither is asserted here.";
+/**
+ * Build the content-free output-shaping instruction block + attribution from the deterministic family.
+ * Produces instructions only — NO savings number, NO claim of reduction.
+ */
+export function buildOutputShapingPolicy(opts = {}) {
+    const selected = opts.policies && opts.policies.length > 0
+        ? OUTPUT_SHAPING_POLICIES.filter((p) => opts.policies.includes(p.policy_name))
+        : OUTPUT_SHAPING_POLICIES.filter((p) => p.defaultOn);
+    const lines = selected.map((p) => `- ${p.instruction(opts.verbosityBudgetTokens)}`);
+    const instructions = selected.length === 0
+        ? ""
+        : ["Output-shaping policy (apply to your response):", ...lines].join("\n");
+    return {
+        instructions,
+        applied: selected.map((p) => ({ policy_name: p.policy_name, policy_family: p.policy_family, risk_level: p.risk_level }))
+    };
+}
+//# sourceMappingURL=output-shaping.js.map

package/dist/core/policy-middleware.d.ts

@@ -0,0 +1,121 @@
+import { COMPACTION_POLICY_NAME, SKILL_INJECTION_POLICY_NAME, SUPPORTED_COMPACTION_POLICY_NAMES, isSupportedCompactionPolicyName } from "./policy-types.js";
+import type { PolicyMiddlewareStateCapsule, ReplacedRange, ReplacementMode, SkillInjectionProvenance, SourcePointer, SupportedCompactionPolicyName } from "./policy-types.js";
+import type { AgentTrace, CostEstimate, TokenEstimate, TraceMessage } from "./types.js";
+export { COMPACTION_POLICY_NAME, SKILL_INJECTION_POLICY_NAME, SUPPORTED_COMPACTION_POLICY_NAMES, isSupportedCompactionPolicyName };
+export type { PolicyMiddlewareStateCapsule, ReplacedRange, ReplacementMode, SkillInjectionProvenance, SourcePointer, SupportedCompactionPolicyName };
+export interface CompactionPolicyThresholds {
+    minDuplicateTokens?: number;
+    minDuplicateCharacters?: number;
+}
+export interface CompactionPolicyConfig {
+    policyName?: typeof COMPACTION_POLICY_NAME;
+}
+export interface PolicyMiddlewareInput {
+    trace?: AgentTrace;
+    messages?: TraceMessage[];
+    model?: string;
+    policy?: CompactionPolicyConfig;
+    thresholds?: CompactionPolicyThresholds;
+    /**
+     * APPROVAL-GATED (design §4). When true, ALSO apply the second policy
+     * `repeated_skill_injection_to_state_capsule`, compacting byte-identical same-skill later
+     * role:user skill injections into state capsules pointing at the first copy. DEFAULT false:
+     * with no approval this run compacts NO skill injections. This flag is set ONLY on explicit
+     * approval in optimization-approval.ts. There is NO auto-apply path that sets it unattended.
+     */
+    compactSkillInjections?: boolean;
+}
+export interface PolicyMiddlewareResult {
+    compactedTrace?: AgentTrace;
+    compactedMessages: TraceMessage[];
+    stateCapsules: PolicyMiddlewareStateCapsule[];
+    compactedMessageIds: string[];
+    tokenEstimateBefore: TokenEstimate;
+    tokenEstimateAfter: TokenEstimate;
+    tokensSaved: number;
+    costEstimateBefore: CostEstimate;
+    costEstimateAfter: CostEstimate;
+    savingsEstimate: number;
+    appliedPolicyName: typeof COMPACTION_POLICY_NAME;
+    /**
+     * Names of every policy that compacted at least one message in this run (design §Q1
+     * sequential composition). Always includes the tool-output policy name; additionally
+     * includes the skill-injection policy name when `compactSkillInjections` was enabled
+     * AND it compacted ≥1 byte-identical injection. Used by the safety report's
+     * supported-policy-set checks. Default (no approval) runs contain only the tool-output name.
+     */
+    appliedPolicyNames: SupportedCompactionPolicyName[];
+    /** State capsules produced by the skill-injection policy only (disjoint from tool-output). */
+    skillInjectionCapsules: PolicyMiddlewareStateCapsule[];
+    safetyNotes: string[];
+}
+/**
+ * Error thrown when the provenance-completeness write-time invariant is violated.
+ * See `docs/ops/provenance-completeness-invariant.md`.
+ */
+export declare class ProvenanceCompletenessError extends Error {
+    constructor(message: string);
+}
+/**
+ * Provenance-completeness write-boundary guard (design: docs/ops/provenance-completeness-invariant.md).
+ *
+ * Invariant: `compaction_changed_content ⟹ provenance_present`. The "content actually
+ * changed" trigger is derived by comparing each original message's payload against the final
+ * compacted payload (`diffMessagesByContent`) — NOT from `compactedMessageIds` collected
+ * from the capsules. Deriving the trigger from the capsules is tautological: if a regressed
+ * path drops/empties the capsule provenance while STILL replacing message content, the
+ * capsule-derived id set goes empty and the guard would no-op, missing exactly the
+ * changed-but-zero-provenance case it exists to reject. Comparing real content instead means a
+ * replaced message is "changed" regardless of whether any capsule exists for it.
+ *
+ * When content changed (by either real content change OR a capsule-claimed compacted id — the
+ * union, so no existing check is weakened), EVERY changed message id MUST have a covering state
+ * capsule, AND EVERY changed message MUST carry `metadata.compaction` with a resolvable
+ * `rawSourcePointer` + content hash (mirrors the required recoverability checks in
+ * safety-report.ts). On violation, FAIL CLOSED: throw, so a changed-but-zero/incomplete-provenance
+ * result can never be emitted as a silent no-op the eval harness cannot distinguish from a true no-op.
+ *
+ * The content-change comparison runs over `max(original.length, compacted.length)` positions
+ * (`diffMessagesByContent`) and enforces the COMPLETE honest-writer invariant: a 1:1 id-preserving
+ * positional map of original→compacted. A position with the SAME id whose content was replaced is a
+ * coverable change; ANYTHING that is not 1:1 id-preserving is a STRUCTURAL divergence that can carry
+ * no covering provenance and fails the guard closed — a DROPPED position (original present, compacted
+ * absent), an ADDED position (compacted present, original absent), AND a same-length position whose
+ * compacted id differs from the original id at that slot (a swap/substitution/duplication, i.e. one
+ * original dropped and a different id inserted at equal length). The last case is rejected BEFORE the
+ * id-based checks precisely because a capsule/metadata that exists for the DISPLACING id sources from
+ * a different original and can never make the displaced original recoverable. This closes the
+ * previously-missed cases where a regressed writer silently DROPS a message, or keeps the array length
+ * while substituting/duplicating an id, and the surviving capsules/ids happen to cover the wrong id.
+ *
+ * This is a NO-OP for every honest run: the shipped writer co-produces a covering capsule and
+ * `metadata.compaction` (with rawSourcePointer + contentSha256) for every compacted span, so
+ * every content-changed id is fully covered. The guard only fires on a regressed/malformed/
+ * hand-constructed path. `originalMessages` is optional for backward compatibility; when omitted,
+ * the guard falls back to the capsule-derived ids alone (the pre-hardening behavior).
+ *
+ * OCCURRENCE-AWARE COVERAGE — HASH BINDING (closes the shared-id residual, 2026-06-15). Message
+ * ids are NON-UNIQUE (a Claude turn's text + tool_use blocks share one id). A malformed
+ * same-length output can DROP one shared-id position and DUPLICATE the other into its slot: every
+ * position still has a matching id (the structural check passes, since both share the id), and the
+ * displaced position carries the duplicate's valid metadata, so an id-keyed coverage check is
+ * satisfied by a capsule belonging to a DIFFERENT occurrence while the displaced original stays
+ * unrecoverable. Merely COUNTING distinct covering capsules per id is ALSO insufficient (Codex P2,
+ * PR #280): a malformed output can keep BOTH shared-id capsules present (count satisfied) yet
+ * duplicate one occurrence's compacted message + metadata into the other's slot. To close this,
+ * when `originalMessages` is provided the coverage is matched per OCCURRENCE BY ORIGINAL-CONTENT
+ * HASH: each changed POSITION p (index + id, original payload P_orig) is bound to a DISTINCT,
+ * not-yet-consumed capsule whose `sourcePointer.contentSha256` hashes to the content that capsule
+ * replaced at p (whole P_orig for a whole-message capsule, a replaced sub-range of P_orig for an
+ * embedded one), AND p's OWN `metadata.compaction` pointer must hash to that same original. A
+ * shared-id duplication fails because the displaced slot's pointer hashes to a DIFFERENT
+ * occurrence's payload, not to its own original, so it FAILS CLOSED; an honest duplicate-id
+ * compaction (two messages sharing an id, each its own hash-correct capsule) still PASSES. The
+ * honest writer emits, per compacted target, exactly one capsule + metadata whose contentSha256 is
+ * that target's original payload hash, so every changed position binds 1:1 — a true no-op. (Binding
+ * is by original-content HASH, not by `sourcePointer.messageIndex`, which records the SOURCE payload
+ * index, not the changed/target position — an index match would break honest whole-message/embedded
+ * runs.)
+ */
+export declare function assertProvenanceCompleteness(compactedMessages: TraceMessage[], stateCapsules: PolicyMiddlewareStateCapsule[], compactedMessageIds: string[], originalMessages?: TraceMessage[]): void;
+export declare function applyCompactionPolicy(input: PolicyMiddlewareInput): PolicyMiddlewareResult;