@compaction/cli 0.2.0 → 0.3.1

package/dist/core/gateway/apply-activation.js

@@ -0,0 +1,84 @@
+/**
+ * Compaction Gateway APPLY activation resolver (PUBLIC CLI/SDK core — engine-free). Charter run-17.2.
+ *
+ * Apply mode is OPT-IN and EXPLICIT. It activates only through explicit user intent — the gateway's
+ * `--mode apply --policy deterministic-dedupe` OR the per-request headers `x-compaction-mode: apply` +
+ * `x-compaction-policy: deterministic-dedupe`. When the server's configured intent and the request
+ * headers CONFLICT, this resolver FAILS CLOSED (falls back to record, records the reason). Default is
+ * always record (byte-safe, no mutation).
+ */
+import { DEDUPE_POLICY } from "./apply-policy.js";
+/** Normalize a mode string to a known effective mode, or undefined when unset/unknown. */
+function normalizeMode(v) {
+    if (v === undefined)
+        return undefined;
+    const s = v.trim().toLowerCase();
+    if (s === "")
+        return undefined;
+    if (s === "record" || s === "apply" || s === "dry-run")
+        return s;
+    return "unknown";
+}
+/** A mutating intent is apply or dry-run; record is the non-mutating default. */
+function isMutating(m) {
+    return m === "apply" || m === "dry-run";
+}
+function record() {
+    return { mode: "record", requested: false, activation: "record" };
+}
+function failClosed(reason) {
+    return { mode: "record", requested: true, activation: "fail-closed", failClosedReason: reason };
+}
+/**
+ * Resolve the effective apply activation from the server config + request headers. PURE.
+ *
+ * Precedence + conflict rules (fail closed on any disagreement):
+ *  - Default server mode `record` carries no mutating intent → a header alone may activate apply/dry-run.
+ *  - If BOTH the server AND a header express a mutating intent and they DIFFER (mode or policy) → conflict.
+ *  - An explicit header `record` is an opt-OUT → record (never a conflict).
+ *  - Apply/dry-run requires the known policy `deterministic-dedupe`; anything else fails closed.
+ *  - An unknown mode value fails closed.
+ */
+export function resolveApplyActivation(params) {
+    const serverMode = normalizeMode(params.serverMode);
+    const headerMode = normalizeMode(params.headerMode);
+    if (serverMode === "unknown")
+        return failClosed(`unknown gateway --mode '${params.serverMode}'`);
+    if (headerMode === "unknown")
+        return failClosed(`unknown x-compaction-mode header '${params.headerMode}'`);
+    // Explicit header opt-out → record, no matter the server mode.
+    if (headerMode === "record")
+        return record();
+    const serverIntent = isMutating(serverMode) ? serverMode : undefined; // record server → no intent
+    const headerIntent = isMutating(headerMode) ? headerMode : undefined;
+    // No mutating intent anywhere → plain record.
+    if (!serverIntent && !headerIntent)
+        return record();
+    const serverPolicy = params.serverPolicy?.trim() || undefined;
+    const headerPolicy = params.headerPolicy?.trim() || undefined;
+    // Conflict: both sides express a mutating intent and disagree on mode or policy.
+    if (serverIntent && headerIntent) {
+        if (serverIntent !== headerIntent) {
+            return failClosed(`gateway --mode '${serverIntent}' conflicts with x-compaction-mode '${headerIntent}' — fail closed`);
+        }
+        if (serverPolicy && headerPolicy && serverPolicy !== headerPolicy) {
+            return failClosed(`gateway --policy '${serverPolicy}' conflicts with x-compaction-policy '${headerPolicy}' — fail closed`);
+        }
+    }
+    const mode = (headerIntent ?? serverIntent);
+    const policy = headerPolicy ?? serverPolicy;
+    if (policy !== DEDUPE_POLICY) {
+        return failClosed(policy === undefined
+            ? `${mode} requested without a policy — apply requires policy '${DEDUPE_POLICY}'`
+            : `unknown policy '${policy}' — apply requires policy '${DEDUPE_POLICY}'`);
+    }
+    const bySource = mode === "apply"
+        ? headerIntent
+            ? "explicit-header"
+            : "explicit-mode"
+        : headerIntent
+            ? "dry-run-header"
+            : "dry-run-mode";
+    return { mode, requested: true, policy: DEDUPE_POLICY, activation: bySource };
+}
+//# sourceMappingURL=apply-activation.js.map

package/dist/core/gateway/apply-policy.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Compaction Gateway DETERMINISTIC APPLY policy (PUBLIC CLI/SDK core — engine-free). Charter run-17.2.
+ *
+ * The FIRST real Compaction apply layer. It is **deterministic only** — NO model call, NO paraphrase, NO
+ * semantic summary, NO LCM. The single policy is `deterministic-dedupe`: within a known-safe text field,
+ * remove EXACT-duplicate LARGE blocks (preserve the first occurrence, never reorder). It fails CLOSED on
+ * any request shape it does not explicitly understand, and it never touches system/developer instructions,
+ * tool schemas, auth/config fields, or short strings.
+ *
+ * This module is PURE (no I/O): it takes the request endpoint + body text and returns a plan describing
+ * whether a safe mutation is possible, the mutated body (only when something actually changed), and a
+ * LOCAL-ESTIMATE model-visible-input reduction. The server decides what to do with the plan.
+ */
+/** The only policy implemented in run-17.2. */
+export declare const DEDUPE_POLICY = "deterministic-dedupe";
+export type ApplyPolicyName = typeof DEDUPE_POLICY;
+/** Blocks shorter than this are NEVER dedupe candidates (short strings are never touched). */
+export declare const DEFAULT_MIN_BLOCK_CHARS = 512;
+export type RequestShape = "responses-string" | "chat-messages" | "unsupported";
+export interface DedupePlan {
+    policy: ApplyPolicyName;
+    shape: RequestShape;
+    /** The shape is one we handle. */
+    supported: boolean;
+    /** A safe mutation was actually produced (duplicates removed). Only then is `mutatedBody` set. */
+    changed: boolean;
+    /** Why we will NOT apply (present whenever `supported` is false, or parsing failed). */
+    failClosedReason?: string;
+    /** Serialized JSON of the mutated request — present ONLY when `changed` is true. */
+    mutatedBody?: string;
+    /** How many exact-duplicate large blocks were removed. */
+    removedBlocks: number;
+    /** Model-visible input size over the SAFE text fields only (chars) — the honest before/after basis. */
+    charsBefore: number;
+    charsAfter: number;
+    /** LOCAL-ESTIMATE token counts (chars/4) — never provider-reported, never a billing figure. */
+    estTokensBefore: number;
+    estTokensAfter: number;
+    /** Estimated model-visible input reduction percent over the safe fields (0 when nothing changed). */
+    reductionPercent: number;
+}
+/** chars/4 — the repo's local-estimate token convention. NEVER provider-reported. */
+export declare function estimateTokens(chars: number): number;
+/**
+ * Remove EXACT-duplicate large blocks from a single text field. Blocks are paragraphs split on runs of
+ * 2+ newlines. A block is a candidate only when it is >= `minBlockChars`; the FIRST occurrence is always
+ * kept, later byte-identical occurrences are dropped. Order is never changed; nothing is paraphrased.
+ *
+ * When nothing is removed the ORIGINAL string is returned unchanged (byte-exact). When blocks are removed
+ * the kept blocks are re-joined with a normalized `\n\n` separator (only ever in the mutated path).
+ */
+export declare function dedupeTextField(text: string, minBlockChars: number): {
+    text: string;
+    removed: number;
+};
+/**
+ * Plan a deterministic-dedupe apply for one request. PURE — no I/O. Fails CLOSED (supported:false) on any
+ * shape not explicitly handled: non-JSON, unknown endpoint, multimodal/array content, tool-bearing
+ * requests, unknown roles, or missing safe fields. The caller forwards the ORIGINAL body whenever this
+ * plan is not `changed` (fail-closed or nothing-to-remove both mean byte-identical passthrough).
+ */
+export declare function planDeterministicDedupe(endpoint: string, bodyText: string, opts?: {
+    minBlockChars?: number;
+}): DedupePlan;

package/dist/core/gateway/apply-policy.js

@@ -0,0 +1,221 @@
+/**
+ * Compaction Gateway DETERMINISTIC APPLY policy (PUBLIC CLI/SDK core — engine-free). Charter run-17.2.
+ *
+ * The FIRST real Compaction apply layer. It is **deterministic only** — NO model call, NO paraphrase, NO
+ * semantic summary, NO LCM. The single policy is `deterministic-dedupe`: within a known-safe text field,
+ * remove EXACT-duplicate LARGE blocks (preserve the first occurrence, never reorder). It fails CLOSED on
+ * any request shape it does not explicitly understand, and it never touches system/developer instructions,
+ * tool schemas, auth/config fields, or short strings.
+ *
+ * This module is PURE (no I/O): it takes the request endpoint + body text and returns a plan describing
+ * whether a safe mutation is possible, the mutated body (only when something actually changed), and a
+ * LOCAL-ESTIMATE model-visible-input reduction. The server decides what to do with the plan.
+ */
+/** The only policy implemented in run-17.2. */
+export const DEDUPE_POLICY = "deterministic-dedupe";
+/** Blocks shorter than this are NEVER dedupe candidates (short strings are never touched). */
+export const DEFAULT_MIN_BLOCK_CHARS = 512;
+/** Chat roles we recognize. An unrecognized role → fail closed (role/order semantics uncertain). */
+const KNOWN_ROLES = new Set(["system", "developer", "user", "assistant", "tool"]);
+/** Only these roles' text is EVER a dedupe candidate. System/developer/assistant/tool are never touched. */
+const DEDUPE_ROLES = new Set(["user"]);
+/** Presence of any of these top-level fields makes the request a more complex shape → fail closed. */
+const COMPLEX_FIELDS = ["tools", "functions", "tool_choice", "function_call", "response_format"];
+/** chars/4 — the repo's local-estimate token convention. NEVER provider-reported. */
+export function estimateTokens(chars) {
+    return Math.round(chars / 4);
+}
+/**
+ * Remove EXACT-duplicate large blocks from a single text field. Blocks are paragraphs split on runs of
+ * 2+ newlines. A block is a candidate only when it is >= `minBlockChars`; the FIRST occurrence is always
+ * kept, later byte-identical occurrences are dropped. Order is never changed; nothing is paraphrased.
+ *
+ * When nothing is removed the ORIGINAL string is returned unchanged (byte-exact). When blocks are removed
+ * the kept blocks are re-joined with a normalized `\n\n` separator (only ever in the mutated path).
+ */
+export function dedupeTextField(text, minBlockChars) {
+    if (typeof text !== "string" || text.length === 0)
+        return { text, removed: 0 };
+    const parts = text.split(/(\n{2,})/); // even indices = blocks, odd = separators
+    const blocks = [];
+    for (let i = 0; i < parts.length; i += 2)
+        blocks.push(parts[i]);
+    const seen = new Set();
+    const kept = [];
+    let removed = 0;
+    for (const block of blocks) {
+        if (block.length >= minBlockChars) {
+            if (seen.has(block)) {
+                removed++;
+                continue; // drop later exact duplicate; first occurrence already kept
+            }
+            seen.add(block);
+        }
+        kept.push(block);
+    }
+    if (removed === 0)
+        return { text, removed: 0 }; // byte-exact: never mutate when nothing to remove
+    return { text: kept.join("\n\n"), removed };
+}
+function failClosed(shape, reason) {
+    return {
+        policy: DEDUPE_POLICY,
+        shape,
+        supported: false,
+        changed: false,
+        failClosedReason: reason,
+        removedBlocks: 0,
+        charsBefore: 0,
+        charsAfter: 0,
+        estTokensBefore: 0,
+        estTokensAfter: 0,
+        reductionPercent: 0
+    };
+}
+/** endpoint family from the request path (e.g. `/v1/responses`, `/responses`). */
+function endpointFamily(endpoint) {
+    const p = endpoint.split("?")[0];
+    if (p.endsWith("/responses"))
+        return "responses";
+    if (p.endsWith("/chat/completions"))
+        return "chat";
+    return "other";
+}
+function reductionPercent(before, after) {
+    if (before <= 0)
+        return 0;
+    return Math.round((1 - after / before) * 1000) / 10;
+}
+/**
+ * Plan a deterministic-dedupe apply for one request. PURE — no I/O. Fails CLOSED (supported:false) on any
+ * shape not explicitly handled: non-JSON, unknown endpoint, multimodal/array content, tool-bearing
+ * requests, unknown roles, or missing safe fields. The caller forwards the ORIGINAL body whenever this
+ * plan is not `changed` (fail-closed or nothing-to-remove both mean byte-identical passthrough).
+ */
+export function planDeterministicDedupe(endpoint, bodyText, opts = {}) {
+    const minBlockChars = opts.minBlockChars ?? DEFAULT_MIN_BLOCK_CHARS;
+    let obj;
+    try {
+        const parsed = JSON.parse(bodyText);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return failClosed("unsupported", "request body is not a JSON object");
+        }
+        obj = parsed;
+    }
+    catch {
+        return failClosed("unsupported", "request body is not valid JSON — fail closed (never mutate an unknown shape)");
+    }
+    const family = endpointFamily(endpoint);
+    if (family === "other") {
+        return failClosed("unsupported", `endpoint '${endpoint}' is not a supported apply shape (only /v1/responses and /v1/chat/completions)`);
+    }
+    // Any tool/function schema or structured-output field → a more complex shape we deliberately do not
+    // touch in run-17.2 (never modify tool schemas; fail closed rather than guess).
+    for (const f of COMPLEX_FIELDS) {
+        if (obj[f] !== undefined) {
+            return failClosed(family === "responses" ? "responses-string" : "chat-messages", `request contains '${f}' (tool/function/structured-output shape) — fail closed (never touch tool schemas)`);
+        }
+    }
+    if (family === "responses") {
+        const input = obj.input;
+        if (typeof input !== "string") {
+            return failClosed("unsupported", "responses.input is not a simple string (arrays/multimodal/other shapes fail closed)");
+        }
+        const before = input.length;
+        const { text: newInput, removed } = dedupeTextField(input, minBlockChars);
+        const after = newInput.length;
+        if (removed === 0) {
+            return {
+                policy: DEDUPE_POLICY,
+                shape: "responses-string",
+                supported: true,
+                changed: false,
+                removedBlocks: 0,
+                charsBefore: before,
+                charsAfter: before,
+                estTokensBefore: estimateTokens(before),
+                estTokensAfter: estimateTokens(before),
+                reductionPercent: 0
+            };
+        }
+        const mutated = { ...obj, input: newInput };
+        return {
+            policy: DEDUPE_POLICY,
+            shape: "responses-string",
+            supported: true,
+            changed: true,
+            mutatedBody: JSON.stringify(mutated),
+            removedBlocks: removed,
+            charsBefore: before,
+            charsAfter: after,
+            estTokensBefore: estimateTokens(before),
+            estTokensAfter: estimateTokens(after),
+            reductionPercent: reductionPercent(before, after)
+        };
+    }
+    // family === "chat": messages[].content string, user role only.
+    const messages = obj.messages;
+    if (!Array.isArray(messages) || messages.length === 0) {
+        return failClosed("unsupported", "chat.completions.messages is missing or not a non-empty array");
+    }
+    // Validate EVERY message first — any non-string content or unknown role → fail closed (never guess).
+    for (const m of messages) {
+        if (typeof m !== "object" || m === null || Array.isArray(m)) {
+            return failClosed("chat-messages", "a message is not an object — fail closed");
+        }
+        const role = m.role;
+        const content = m.content;
+        if (typeof role !== "string" || !KNOWN_ROLES.has(role)) {
+            return failClosed("chat-messages", `a message has an unknown/missing role — fail closed (role/order semantics uncertain)`);
+        }
+        if (typeof content !== "string") {
+            // multimodal content array / null / object → fail closed (never touch non-string content)
+            return failClosed("chat-messages", "a message has non-string content (multimodal/array) — fail closed");
+        }
+    }
+    let before = 0;
+    let after = 0;
+    let removedTotal = 0;
+    const newMessages = messages.map((m) => {
+        const msg = m;
+        if (!DEDUPE_ROLES.has(msg.role)) {
+            before += msg.content.length;
+            after += msg.content.length;
+            return m; // system/developer/assistant/tool text is NEVER touched
+        }
+        before += msg.content.length;
+        const { text: newContent, removed } = dedupeTextField(msg.content, minBlockChars);
+        after += newContent.length;
+        removedTotal += removed;
+        return removed === 0 ? m : { ...msg, content: newContent };
+    });
+    if (removedTotal === 0) {
+        return {
+            policy: DEDUPE_POLICY,
+            shape: "chat-messages",
+            supported: true,
+            changed: false,
+            removedBlocks: 0,
+            charsBefore: before,
+            charsAfter: before,
+            estTokensBefore: estimateTokens(before),
+            estTokensAfter: estimateTokens(before),
+            reductionPercent: 0
+        };
+    }
+    const mutated = { ...obj, messages: newMessages };
+    return {
+        policy: DEDUPE_POLICY,
+        shape: "chat-messages",
+        supported: true,
+        changed: true,
+        mutatedBody: JSON.stringify(mutated),
+        removedBlocks: removedTotal,
+        charsBefore: before,
+        charsAfter: after,
+        estTokensBefore: estimateTokens(before),
+        estTokensAfter: estimateTokens(after),
+        reductionPercent: reductionPercent(before, after)
+    };
+}
+//# sourceMappingURL=apply-policy.js.map

package/dist/core/gateway/apply-receipt.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Compaction Gateway APPLY receipt builder (PUBLIC CLI/SDK core — engine-free). Charter run-17.2.
+ *
+ * Builds the content-free before/after receipt for an apply / dry-run pass. It REUSES the record receipt
+ * builder for the provider's after-call usage (provider-reported token/cache axis) and overlays the apply
+ * axis: request_mutated, the LOCAL-ESTIMATE model-visible input before/after, the recovery pointer, and a
+ * fail_closed_reason when nothing was applied. The model-visible-input reduction is claimed ONLY when the
+ * request body was actually changed; otherwise no reduction is asserted. The response is NEVER changed.
+ */
+import { type GatewayReceipt } from "./receipt.js";
+import type { OpenAiUsageBreakdown } from "./openai-usage.js";
+import type { DedupePlan } from "./apply-policy.js";
+import type { ApplyActivation } from "./apply-activation.js";
+export declare const applyLabelMutated: (pct: number) => string;
+export declare const APPLY_LABEL_NOOP = "apply requested but the request was forwarded UNCHANGED (no safe duplicate to remove / fail closed). No model-visible input reduction is claimed.";
+export declare const dryRunLabelCandidate: (pct: number) => string;
+export declare const DRYRUN_LABEL_NONE = "dry-run (deterministic-dedupe): no safe deterministic mutation is available for this request; the original was forwarded unchanged.";
+/**
+ * Build ONE content-free apply/dry-run receipt. `applied` is true only when the body was actually changed
+ * (apply path); dry-run always forwards the original (applied=false, candidate flagged from the plan).
+ */
+export declare function buildApplyReceipt(params: {
+    provider: string;
+    endpoint: string;
+    upstreamStatus: number;
+    usage: OpenAiUsageBreakdown;
+    requestModel?: string;
+    proofRunId?: string;
+    activation: ApplyActivation;
+    plan?: DedupePlan;
+    applied: boolean;
+    recoveryId?: string;
+    failClosedReason?: string;
+    now?: () => string;
+    id?: () => string;
+}): GatewayReceipt;

package/dist/core/gateway/apply-receipt.js

@@ -0,0 +1,75 @@
+/**
+ * Compaction Gateway APPLY receipt builder (PUBLIC CLI/SDK core — engine-free). Charter run-17.2.
+ *
+ * Builds the content-free before/after receipt for an apply / dry-run pass. It REUSES the record receipt
+ * builder for the provider's after-call usage (provider-reported token/cache axis) and overlays the apply
+ * axis: request_mutated, the LOCAL-ESTIMATE model-visible input before/after, the recovery pointer, and a
+ * fail_closed_reason when nothing was applied. The model-visible-input reduction is claimed ONLY when the
+ * request body was actually changed; otherwise no reduction is asserted. The response is NEVER changed.
+ */
+import { buildGatewayReceipt } from "./receipt.js";
+export const applyLabelMutated = (pct) => `apply (deterministic-dedupe): model-visible input reduced by ${pct}% by a deterministic policy (exact-duplicate large blocks removed); the original request is retained locally. No output-token, cost, provider-billing, or semantic-compaction claim.`;
+export const APPLY_LABEL_NOOP = "apply requested but the request was forwarded UNCHANGED (no safe duplicate to remove / fail closed). No model-visible input reduction is claimed.";
+export const dryRunLabelCandidate = (pct) => `dry-run (deterministic-dedupe): a deterministic mutation is AVAILABLE (estimated -${pct}% model-visible input, local-estimate); the ORIGINAL request was forwarded unchanged. No applied-reduction claim is made.`;
+export const DRYRUN_LABEL_NONE = "dry-run (deterministic-dedupe): no safe deterministic mutation is available for this request; the original was forwarded unchanged.";
+/**
+ * Build ONE content-free apply/dry-run receipt. `applied` is true only when the body was actually changed
+ * (apply path); dry-run always forwards the original (applied=false, candidate flagged from the plan).
+ */
+export function buildApplyReceipt(params) {
+    const base = buildGatewayReceipt({
+        provider: params.provider,
+        endpoint: params.endpoint,
+        mode: "apply",
+        upstreamStatus: params.upstreamStatus,
+        usage: params.usage,
+        ...(params.requestModel ? { requestModel: params.requestModel } : {}),
+        ...(params.proofRunId ? { proofRunId: params.proofRunId } : {}),
+        ...(params.now ? { now: params.now } : {}),
+        ...(params.id ? { id: params.id } : {})
+    });
+    const isDryRun = params.activation.mode === "dry-run";
+    const plan = params.plan;
+    const hasEstimate = Boolean(plan && plan.supported);
+    // approval_status: reflects an ACTUAL apply + its explicit source; dry-run is its own label; when nothing
+    // was applied nothing was approved/executed → not-required (the fail_closed_reason carries the detail).
+    let approval = "not-required";
+    if (params.applied)
+        approval = params.activation.activation === "explicit-header" ? "explicit-header" : "explicit-mode";
+    else if (isDryRun)
+        approval = "explicit-dry-run";
+    // apply label — a model-visible reduction is asserted ONLY when the body actually changed.
+    let applyLabel;
+    if (params.applied && plan)
+        applyLabel = applyLabelMutated(plan.reductionPercent);
+    else if (isDryRun)
+        applyLabel = plan?.changed ? dryRunLabelCandidate(plan.reductionPercent) : DRYRUN_LABEL_NONE;
+    else
+        applyLabel = APPLY_LABEL_NOOP;
+    const failReason = params.failClosedReason ?? plan?.failClosedReason;
+    return {
+        ...base,
+        // Override the inherited record label: an apply receipt must NOT claim "forwarded byte-for-byte /
+        // model-visible bytes unchanged" when it actually mutated. The apply label is the honest one here.
+        label: applyLabel,
+        model_visible_bytes_changed: params.applied, // TRUE only when the request body was actually changed
+        approval_status: approval,
+        policy: params.activation.policy ?? plan?.policy ?? "deterministic-dedupe",
+        request_mutated: params.applied,
+        response_mutated: false,
+        ...(isDryRun ? { candidate_available: Boolean(plan?.changed) } : {}),
+        ...(hasEstimate
+            ? {
+                estimated_input_tokens_before: plan.estTokensBefore,
+                estimated_input_tokens_after: params.applied ? plan.estTokensAfter : plan.estTokensBefore,
+                estimated_model_visible_input_reduction_percent: params.applied || isDryRun ? plan.reductionPercent : 0,
+                token_source_before: "local-estimate",
+                token_source_after: base.token_source
+            }
+            : {}),
+        ...(params.recoveryId ? { recovery_id: params.recoveryId } : {}),
+        ...(failReason ? { fail_closed_reason: failReason } : {}),
+        apply_label: applyLabel
+    };
+}
+//# sourceMappingURL=apply-receipt.js.map

package/dist/core/gateway/cache-proof.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Compaction Gateway CACHE PROOF pairing/summary (PUBLIC CLI/SDK code — engine-free). Charter run-16.
+ *
+ * Run-16 is a PROOF run using record mode (NOT cache mode). It pairs two or more content-free gateway
+ * receipts from one manual proof run and surfaces the wedge:
+ *   "Same model-visible bytes, provider-backed cached input tokens, lower fresh/billed input tokens."
+ *
+ * CONTENT-FREE by construction: it operates ONLY on receipts (which already carry counts/labels, never
+ * content). It computes the provider-backed fresh/billed input reduction from the provider's own reported
+ * cached-input accounting. It makes NO cost-savings, NO model-visible input reduction, and NO output-token
+ * reduction claim. When no receipt reports cached tokens → the reduction is UNAVAILABLE (never a zero
+ * "savings"). No proxy-side cache injection happens anywhere here — this only reads receipts.
+ */
+import type { GatewayReceipt } from "./receipt.js";
+import { type FreshBilledInputReduction } from "./receipt.js";
+/** One request's content-free view for the proof table. */
+export interface CacheProofRequest {
+    promptInput?: number;
+    cachedInput?: number;
+    /** Fresh/billed input = prompt - cached (the receipt's billed_fresh_input). */
+    freshInput?: number;
+    output?: number;
+    tokenSource: string;
+    modelVisibleBytesChanged: boolean;
+}
+export interface CacheProofSummary {
+    requests: CacheProofRequest[];
+    /** True only when EVERY paired receipt left model-visible bytes unchanged (record mode always does). */
+    modelVisibleBytesUnchanged: boolean;
+    /** The BEST provider-backed fresh/billed input reduction across the requests, or unavailable. */
+    bestReduction: FreshBilledInputReduction;
+}
+/** Filter receipts to one proof run (by the client-set `proof_run_id`). */
+export declare function receiptsForProofRun(receipts: GatewayReceipt[], proofRunId: string): GatewayReceipt[];
+/**
+ * Summarize a set of receipts into a cache proof. The best reduction is the largest provider-backed
+ * fresh/billed input reduction among the requests (typically the cached request beats the cold one).
+ */
+export declare function summarizeCacheProof(receipts: GatewayReceipt[]): CacheProofSummary;
+/**
+ * Render the content-free proof table (charter run-16 §B). Shows each request's provider-reported
+ * breakdown, then the honest claim line. When cached tokens are absent the reduction line reads
+ * "unavailable" with the reason — NEVER a zero "savings" presented as proof.
+ */
+export declare function formatCacheProof(summary: CacheProofSummary): string;

package/dist/core/gateway/cache-proof.js

@@ -0,0 +1,65 @@
+import { freshBilledInputReduction } from "./receipt.js";
+/** Filter receipts to one proof run (by the client-set `proof_run_id`). */
+export function receiptsForProofRun(receipts, proofRunId) {
+    return receipts.filter((r) => r.proof_run_id === proofRunId);
+}
+/**
+ * Summarize a set of receipts into a cache proof. The best reduction is the largest provider-backed
+ * fresh/billed input reduction among the requests (typically the cached request beats the cold one).
+ */
+export function summarizeCacheProof(receipts) {
+    const requests = receipts.map((r) => ({
+        ...(r.tokens.prompt_input !== undefined ? { promptInput: r.tokens.prompt_input } : {}),
+        ...(r.tokens.cached_input !== undefined ? { cachedInput: r.tokens.cached_input } : {}),
+        ...(r.tokens.billed_fresh_input !== undefined ? { freshInput: r.tokens.billed_fresh_input } : {}),
+        ...(r.tokens.output !== undefined ? { output: r.tokens.output } : {}),
+        tokenSource: r.token_source,
+        modelVisibleBytesChanged: r.model_visible_bytes_changed
+    }));
+    const modelVisibleBytesUnchanged = receipts.length > 0 && receipts.every((r) => r.model_visible_bytes_changed === false);
+    // Best = the highest available fresh/billed reduction across the receipts.
+    let bestReduction = {
+        available: false,
+        note: "no receipt reported provider cached input tokens — fresh/billed input reduction unavailable"
+    };
+    for (const r of receipts) {
+        const red = freshBilledInputReduction({
+            ...(r.tokens.prompt_input !== undefined ? { promptInputTokens: r.tokens.prompt_input } : {}),
+            ...(r.tokens.cached_input !== undefined ? { cachedInputTokens: r.tokens.cached_input } : {})
+        });
+        if (red.available && (!bestReduction.available || (red.pct ?? 0) > (bestReduction.pct ?? 0))) {
+            bestReduction = red;
+        }
+    }
+    return { requests, modelVisibleBytesUnchanged, bestReduction };
+}
+function n(value) {
+    return value === undefined ? "unavailable" : value.toLocaleString("en-US");
+}
+/**
+ * Render the content-free proof table (charter run-16 §B). Shows each request's provider-reported
+ * breakdown, then the honest claim line. When cached tokens are absent the reduction line reads
+ * "unavailable" with the reason — NEVER a zero "savings" presented as proof.
+ */
+export function formatCacheProof(summary) {
+    const lines = ["COMPACTION CACHE PROOF", ""];
+    summary.requests.forEach((req, i) => {
+        lines.push(`request ${i + 1}`);
+        lines.push(`  prompt input tokens   ${n(req.promptInput).padStart(12)}`);
+        lines.push(`  cached input tokens   ${n(req.cachedInput).padStart(12)}`);
+        lines.push(`  fresh input tokens    ${n(req.freshInput).padStart(12)}`);
+        lines.push(`  output tokens         ${n(req.output).padStart(12)}`);
+        lines.push("");
+    });
+    lines.push(summary.modelVisibleBytesUnchanged ? "model-visible bytes unchanged" : "model-visible bytes: (mixed — check receipts)");
+    if (summary.bestReduction.available) {
+        lines.push(`fresh/billed input reduction: -${summary.bestReduction.pct}%`);
+        lines.push("claim: provider-backed cached-input accounting");
+    }
+    else {
+        lines.push("fresh/billed input reduction: unavailable");
+        lines.push("reason: provider did not report cached input tokens");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=cache-proof.js.map

package/dist/core/gateway/configure.d.ts

@@ -0,0 +1,50 @@
+/** The env var we set to route an OpenAI-compatible client through the gateway. */
+export declare const CONFIGURE_ENV_VAR = "OPENAI_BASE_URL";
+export interface ProjectDetection {
+    /** `.env` / `.env.local` files that exist in the project root. */
+    envFiles: string[];
+    hasPackageJson: boolean;
+    /** True when package.json lists the `openai` SDK as a dependency. */
+    usesOpenAiSdk: boolean;
+    /** An already-configured base URL, if any (OPENAI_BASE_URL or OPENAI_API_BASE), and where. */
+    existingBaseUrl?: {
+        file: string;
+        var: string;
+        value: string;
+    };
+}
+/** Detect the project's OpenAI-config surface WITHOUT modifying anything. */
+export declare function detectProject(cwd: string): ProjectDetection;
+export type ConfigureAction = "create" | "append" | "conflict";
+export interface ConfigurePlan {
+    /** The file (relative) we would write. */
+    targetFile: string;
+    action: ConfigureAction;
+    /** The base URL we would set (already includes /v1). */
+    baseUrl: string;
+    /** Unified-ish diff preview (content-free — env var + gateway URL only). */
+    diff: string;
+    /** Where the `.bak` backup would go, when the target already exists. */
+    backupFile?: string;
+    detection: ProjectDetection;
+    /** Human-readable note about why apply is/should be gated. */
+    note: string;
+}
+/**
+ * Build a configure plan for pointing this project's OpenAI client at `baseUrl` (the gateway `/v1` URL).
+ * Never writes. If a base URL is already configured, the plan action is "conflict" and apply requires force.
+ */
+export declare function planGatewayConfigure(cwd: string, baseUrl: string): ConfigurePlan;
+export interface ApplyResult {
+    wrote: boolean;
+    targetFile: string;
+    backupFile?: string;
+    reason?: string;
+}
+/**
+ * Apply a configure plan: write a `.bak` backup (when the target exists), then create/append the base-URL
+ * line. Refuses a "conflict" plan unless `force` is set. This is the ONLY function here that writes.
+ */
+export declare function applyGatewayConfigure(cwd: string, plan: ConfigurePlan, force?: boolean): ApplyResult;
+/** Render a configure plan as plain content-free lines (for the CLI preview). */
+export declare function formatConfigurePlan(plan: ConfigurePlan): string[];