@compaction/cli 0.1.4 → 0.3.0

package/dist/core/gateway/openai-usage.d.ts

@@ -0,0 +1,56 @@
+/**
+ * OpenAI usage parsing for the Compaction Gateway record mode (PUBLIC CLI/SDK code — engine-free,
+ * ships in the npm package). Charter 2026-07-04-run-15 — the first gateway implementation.
+ *
+ * This module is PURE and CONTENT-FREE by construction: it takes a response body (a non-streaming JSON
+ * body, or the tail of an SSE stream) and extracts ONLY the token-usage COUNTS + the model label. It
+ * never returns, stores, or logs any message / completion / tool text — only the numbers the provider
+ * itself reports in its `usage` object, plus the model name (metadata, not content).
+ *
+ * OpenAI usage shape (Chat Completions / Responses):
+ *   usage.prompt_tokens                              — total input tokens the provider billed for
+ *   usage.prompt_tokens_details.cached_tokens        — the portion served from the provider prompt cache
+ *   usage.completion_tokens                          — output tokens
+ *   usage.completion_tokens_details.reasoning_tokens — reasoning/output-detail tokens (o-series), where present
+ *
+ * Honesty: a field is reported ONLY when the provider actually returned it. A missing axis is
+ * `unavailable` with a reason — NEVER a silent zero. `billed_fresh_input_tokens = prompt - cached`
+ * (the input the provider billed at full rate) is computed ONLY when BOTH prompt and cached are present.
+ */
+/** A normalized, content-free token breakdown from a provider `usage` object. */
+export interface OpenAiUsageBreakdown {
+    /** True when a `usage` object with a numeric `prompt_tokens` (or output) was found. */
+    present: boolean;
+    /** Total input tokens the provider reports (usage.prompt_tokens), when present. */
+    promptInputTokens?: number;
+    /** Input tokens served from the provider prompt cache (prompt_tokens_details.cached_tokens), when present. */
+    cachedInputTokens?: number;
+    /** Fresh/billed-at-full-rate input tokens = prompt - cached (only when BOTH are present). */
+    billedFreshInputTokens?: number;
+    /** Output tokens (usage.completion_tokens), when present. */
+    outputTokens?: number;
+    /** Reasoning/output-detail tokens (completion_tokens_details.reasoning_tokens), when present. */
+    reasoningTokens?: number;
+    /** The model label the provider echoed (metadata, NOT content), when present. */
+    model?: string;
+    /** Honest reason the usage is unavailable, when `present` is false. */
+    unavailableReason?: string;
+}
+/**
+ * Extract the content-free usage breakdown from an already-parsed OpenAI response object. Handles BOTH
+ * OpenAI APIs (their usage field names differ):
+ *  - Chat Completions: `usage.prompt_tokens` / `completion_tokens` / `prompt_tokens_details.cached_tokens`
+ *    / `completion_tokens_details.reasoning_tokens`.
+ *  - Responses API: `usage.input_tokens` / `output_tokens` / `input_tokens_details.cached_tokens`
+ *    / `output_tokens_details.reasoning_tokens`. Its SSE events wrap the payload under `response`
+ *    (`{"type":"response.completed","response":{usage,model}}`), so we also look one level down.
+ */
+export declare function usageFromResponseObject(obj: unknown): OpenAiUsageBreakdown;
+/**
+ * Extract usage from a raw response body string. Handles BOTH shapes byte-safely (it only READS a copy):
+ *  - non-streaming JSON: `JSON.parse(body).usage`.
+ *  - streaming SSE: the LAST `data:` line carrying a `usage` object (present only when the caller sent
+ *    `stream_options.include_usage: true`). The `[DONE]` sentinel is ignored.
+ * Any parse failure → `present: false` with an honest reason (never throws; the proxy stays byte-safe).
+ */
+export declare function usageFromResponseBody(body: string): OpenAiUsageBreakdown;

package/dist/core/gateway/openai-usage.js

@@ -0,0 +1,128 @@
+/**
+ * OpenAI usage parsing for the Compaction Gateway record mode (PUBLIC CLI/SDK code — engine-free,
+ * ships in the npm package). Charter 2026-07-04-run-15 — the first gateway implementation.
+ *
+ * This module is PURE and CONTENT-FREE by construction: it takes a response body (a non-streaming JSON
+ * body, or the tail of an SSE stream) and extracts ONLY the token-usage COUNTS + the model label. It
+ * never returns, stores, or logs any message / completion / tool text — only the numbers the provider
+ * itself reports in its `usage` object, plus the model name (metadata, not content).
+ *
+ * OpenAI usage shape (Chat Completions / Responses):
+ *   usage.prompt_tokens                              — total input tokens the provider billed for
+ *   usage.prompt_tokens_details.cached_tokens        — the portion served from the provider prompt cache
+ *   usage.completion_tokens                          — output tokens
+ *   usage.completion_tokens_details.reasoning_tokens — reasoning/output-detail tokens (o-series), where present
+ *
+ * Honesty: a field is reported ONLY when the provider actually returned it. A missing axis is
+ * `unavailable` with a reason — NEVER a silent zero. `billed_fresh_input_tokens = prompt - cached`
+ * (the input the provider billed at full rate) is computed ONLY when BOTH prompt and cached are present.
+ */
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function obj_(value) {
+    return value && typeof value === "object" ? value : undefined;
+}
+/**
+ * Extract the content-free usage breakdown from an already-parsed OpenAI response object. Handles BOTH
+ * OpenAI APIs (their usage field names differ):
+ *  - Chat Completions: `usage.prompt_tokens` / `completion_tokens` / `prompt_tokens_details.cached_tokens`
+ *    / `completion_tokens_details.reasoning_tokens`.
+ *  - Responses API: `usage.input_tokens` / `output_tokens` / `input_tokens_details.cached_tokens`
+ *    / `output_tokens_details.reasoning_tokens`. Its SSE events wrap the payload under `response`
+ *    (`{"type":"response.completed","response":{usage,model}}`), so we also look one level down.
+ */
+export function usageFromResponseObject(obj) {
+    if (!obj || typeof obj !== "object") {
+        return { present: false, unavailableReason: "response body was not a JSON object" };
+    }
+    const root = obj;
+    // The Responses API SSE stream nests the completed response under `response`.
+    const nested = obj_(root.response);
+    const usage = obj_(root.usage) ?? obj_(nested?.usage);
+    const model = typeof root.model === "string" ? root.model : typeof nested?.model === "string" ? nested.model : undefined;
+    if (!usage) {
+        return {
+            present: false,
+            ...(model ? { model } : {}),
+            unavailableReason: "the provider response carried no usage object (e.g. a streamed response without usage/include_usage)"
+        };
+    }
+    // Accept both APIs' field names (Chat Completions ?? Responses API).
+    const promptInputTokens = num(usage.prompt_tokens) ?? num(usage.input_tokens);
+    const outputTokens = num(usage.completion_tokens) ?? num(usage.output_tokens);
+    const cachedInputTokens = num(obj_(usage.prompt_tokens_details)?.cached_tokens) ?? num(obj_(usage.input_tokens_details)?.cached_tokens);
+    const reasoningTokens = num(obj_(usage.completion_tokens_details)?.reasoning_tokens) ?? num(obj_(usage.output_tokens_details)?.reasoning_tokens);
+    if (promptInputTokens === undefined && outputTokens === undefined) {
+        return {
+            present: false,
+            ...(model ? { model } : {}),
+            unavailableReason: "the usage object carried no numeric input/prompt or output/completion tokens"
+        };
+    }
+    const billedFreshInputTokens = promptInputTokens !== undefined && cachedInputTokens !== undefined
+        ? Math.max(0, promptInputTokens - cachedInputTokens)
+        : undefined;
+    return {
+        present: true,
+        ...(promptInputTokens !== undefined ? { promptInputTokens } : {}),
+        ...(cachedInputTokens !== undefined ? { cachedInputTokens } : {}),
+        ...(billedFreshInputTokens !== undefined ? { billedFreshInputTokens } : {}),
+        ...(outputTokens !== undefined ? { outputTokens } : {}),
+        ...(reasoningTokens !== undefined ? { reasoningTokens } : {}),
+        ...(model ? { model } : {})
+    };
+}
+/**
+ * Extract usage from a raw response body string. Handles BOTH shapes byte-safely (it only READS a copy):
+ *  - non-streaming JSON: `JSON.parse(body).usage`.
+ *  - streaming SSE: the LAST `data:` line carrying a `usage` object (present only when the caller sent
+ *    `stream_options.include_usage: true`). The `[DONE]` sentinel is ignored.
+ * Any parse failure → `present: false` with an honest reason (never throws; the proxy stays byte-safe).
+ */
+export function usageFromResponseBody(body) {
+    const trimmed = body.trim();
+    if (trimmed === "")
+        return { present: false, unavailableReason: "empty response body" };
+    // Non-streaming JSON first.
+    if (trimmed.startsWith("{")) {
+        try {
+            return usageFromResponseObject(JSON.parse(trimmed));
+        }
+        catch {
+            return { present: false, unavailableReason: "response body was not parseable JSON (may be truncated)" };
+        }
+    }
+    // Streaming SSE: scan for the LAST `data:` payload that parses and carries a usage object.
+    let best;
+    let lastModel;
+    for (const line of trimmed.split(/\r?\n/)) {
+        const s = line.trim();
+        if (!s.startsWith("data:"))
+            continue;
+        const payload = s.slice("data:".length).trim();
+        if (payload === "" || payload === "[DONE]")
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(payload);
+        }
+        catch {
+            continue; // a partial/truncated SSE line — skip it
+        }
+        if (obj && typeof obj === "object" && typeof obj.model === "string") {
+            lastModel = obj.model;
+        }
+        const b = usageFromResponseObject(obj);
+        if (b.present)
+            best = b; // keep the latest present usage (OpenAI emits it in the final chunk)
+    }
+    if (best)
+        return best;
+    return {
+        present: false,
+        ...(lastModel ? { model: lastModel } : {}),
+        unavailableReason: "streamed response carried no usage chunk (send stream_options.include_usage:true to get one)"
+    };
+}
+//# sourceMappingURL=openai-usage.js.map

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

@@ -0,0 +1,138 @@
+import type { OpenAiUsageBreakdown } from "./openai-usage.js";
+/** The gateway modes (run-15 implements ONLY `record`). */
+export type GatewayMode = "record" | "cache" | "apply";
+/** Per-axis honesty label — mirrors the cross-surface `token_source` discipline. */
+export type SourceLabel = "provider-reported" | "local-estimate" | "unavailable";
+/** The default local-only receipts location (gitignored — never committed, never uploaded). */
+export declare const DEFAULT_GATEWAY_RECEIPTS_DIR = ".compaction/gateway";
+export declare const GATEWAY_RECEIPTS_FILE = "receipts.jsonl";
+/**
+ * The honest, content-free claim-boundary label carried on every record-mode receipt.
+ *
+ * CLAIM BOUNDARY (founder-set, run-15): a provider-backed **fresh/billed input-token reduction** MAY be
+ * displayed when the provider reports cached input tokens (the provider served part of the input from its
+ * prompt cache, so fewer input tokens were billed fresh — with model-visible bytes unchanged). What is
+ * NOT claimed on this path: any model-visible input reduction, any output-token reduction, or any
+ * cost-savings figure (cost is unavailable — the provider reports tokens, not billing).
+ */
+export declare const GATEWAY_RECORD_LABEL: string;
+/** A provider-backed fresh/billed input-token reduction, or an honest unavailable (never a zero savings). */
+export interface FreshBilledInputReduction {
+    available: boolean;
+    /** Percent of input tokens the provider served from cache (= cached / prompt · 100), when available. */
+    pct?: number;
+    /** Honest basis (available) or reason (unavailable). */
+    note: string;
+}
+/**
+ * Compute the provider-backed fresh/billed input reduction. Available ONLY when the provider reported
+ * BOTH prompt input tokens (> 0) and cached input tokens (> 0): the cached portion was NOT billed as
+ * fresh input, so fresh/billed input is reduced by `cached / prompt`. Otherwise unavailable-with-reason —
+ * NEVER a zero "savings".
+ */
+export declare function freshBilledInputReduction(usage: {
+    promptInputTokens?: number;
+    cachedInputTokens?: number;
+}): FreshBilledInputReduction;
+/** The compact display string per the claim boundary (allowed forms only). */
+export declare function formatFreshBilledInputReduction(r: FreshBilledInputReduction): string;
+export interface GatewayReceipt {
+    /** Content-free unique id (random UUID — never derived from content). */
+    receipt_id: string;
+    /** ISO timestamp the receipt was recorded. */
+    captured_at: string;
+    provider: string;
+    /** Model label the provider echoed, or "unknown" (never inferred). */
+    model: string;
+    /** The request path (e.g. `/v1/chat/completions`) — an endpoint label, not content. */
+    endpoint: string;
+    mode: GatewayMode;
+    /** The upstream HTTP status code. */
+    upstream_status: number;
+    /** record mode NEVER changes model-visible bytes. Always false in run-15. */
+    model_visible_bytes_changed: boolean;
+    /** Per-axis token COUNTS (only present axes ride here — never a silent zero). */
+    tokens: {
+        prompt_input?: number;
+        cached_input?: number;
+        billed_fresh_input?: number;
+        output?: number;
+        reasoning?: number;
+    };
+    /**
+     * Provider-backed fresh/billed input-token reduction (allowed claim): available ONLY when the provider
+     * reported cached input tokens; otherwise unavailable-with-reason (never a zero savings). This is the
+     * ONLY reduction this record-mode receipt asserts — never model-visible input, output, or cost.
+     */
+    fresh_billed_input_reduction: FreshBilledInputReduction;
+    /** Where the token counts came from. */
+    token_source: SourceLabel;
+    /** Where the cache-token count came from (provider-reported only when the response exposed cached_tokens). */
+    cache_source: SourceLabel;
+    /** Cost is always unavailable on this path (provider reports tokens, not billing). */
+    cost_source: "unavailable";
+    /** Honest per-axis reasons for any unavailable axis (never a bare "unavailable"). */
+    reasons: {
+        token?: string;
+        cache?: string;
+        cost: string;
+    };
+    /** Single request → run-scoped, never generalized. */
+    claim_scope: "run-scoped";
+    /** record mode applies nothing → nothing to approve. Apply/dry-run receipts carry the explicit source. */
+    approval_status: "not-required" | "explicit-mode" | "explicit-header" | "explicit-dry-run";
+    /** Local-only by default; nothing is uploaded. */
+    sync_status: "local-only";
+    content_uploaded: false;
+    /**
+     * Optional CLIENT-SET proof-run id (an opaque grouping label, NOT content) — present only when the
+     * client sent an `x-compaction-proof-run` header. The gateway only READS it (never injects/mutates the
+     * request), and it is used purely to pair receipts of a manual proof run. Content-free by construction.
+     */
+    proof_run_id?: string;
+    /** The honest content-free label (never upgraded to a saving/cost claim). */
+    label: string;
+    /** The deterministic policy that ran (e.g. `deterministic-dedupe`). */
+    policy?: string;
+    /** True ONLY when apply actually changed the request body (before/after evidence exists via recovery). */
+    request_mutated?: boolean;
+    /** The gateway NEVER changes the response. Always false when present. */
+    response_mutated?: boolean;
+    /** dry-run: a safe mutation was possible but NOT applied (the original was forwarded unchanged). */
+    candidate_available?: boolean;
+    /** LOCAL-ESTIMATE (chars/4) model-visible input over the safe text fields — never provider-reported. */
+    estimated_input_tokens_before?: number;
+    estimated_input_tokens_after?: number;
+    /** Estimated model-visible input reduction percent over the safe fields (apply/dry-run candidate). */
+    estimated_model_visible_input_reduction_percent?: number;
+    /** Where the before/after ESTIMATES came from (always local-estimate — chars/4). */
+    token_source_before?: SourceLabel;
+    /** Where the AFTER token counts came from (provider-reported when the call returned usage, else local). */
+    token_source_after?: SourceLabel;
+    /** Pointer to the locally-retained original request body (content lives in the recovery store, not here). */
+    recovery_id?: string;
+    /** Why apply did NOT change the request (fail-closed shape, conflict, or no safe duplicate found). */
+    fail_closed_reason?: string;
+    /** The honest apply claim string (only asserts a model-visible reduction when request_mutated is true). */
+    apply_label?: string;
+}
+/**
+ * Build ONE content-free gateway receipt from the request metadata + the provider's reported usage.
+ * `now`/`id` are injectable for deterministic tests. CONTENT-FREE: only `usage`'s numeric fields, the
+ * model label, the endpoint path, and the status ride on the receipt.
+ */
+export declare function buildGatewayReceipt(params: {
+    provider: string;
+    endpoint: string;
+    mode: GatewayMode;
+    upstreamStatus: number;
+    usage: OpenAiUsageBreakdown;
+    /** Model from the request (content-free metadata), used only if the response did not echo one. */
+    requestModel?: string;
+    /** Optional client-set proof-run id (from an `x-compaction-proof-run` header) — an opaque grouping label. */
+    proofRunId?: string;
+    now?: () => string;
+    id?: () => string;
+}): GatewayReceipt;
+/** Append a receipt to the local-only JSONL store under `<cwd>/.compaction/gateway/`. Content-free. */
+export declare function appendGatewayReceipt(receipt: GatewayReceipt, cwd?: string): Promise<string>;

package/dist/core/gateway/receipt.js

@@ -0,0 +1,120 @@
+/**
+ * Compaction Gateway RECEIPT — the content-free ground-truth record of one gateway pass (PUBLIC CLI/SDK
+ * code — engine-free). Charter 2026-07-04-run-15. Per the canonical architecture
+ * (`docs/design/compaction-gateway-architecture.md` §C.2), a receipt carries ONLY counts / structure /
+ * labels — never messages, completions, tool outputs, or any request/response content.
+ *
+ * Run-15 ships **record mode** only: the gateway forwards the request and response byte-for-byte and
+ * records this receipt. So `mode: "record"` and `model_visible_bytes_changed: false` always. There is NO
+ * optimization and therefore NO savings claim on this receipt — it DESCRIBES the provider's own reported
+ * token/cache usage honestly; it never asserts a reduction. Cost is always `unavailable` on this path
+ * (the provider reports tokens, not a billing figure).
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, appendFile } from "node:fs/promises";
+import path from "node:path";
+/** The default local-only receipts location (gitignored — never committed, never uploaded). */
+export const DEFAULT_GATEWAY_RECEIPTS_DIR = ".compaction/gateway";
+export const GATEWAY_RECEIPTS_FILE = "receipts.jsonl";
+/**
+ * The honest, content-free claim-boundary label carried on every record-mode receipt.
+ *
+ * CLAIM BOUNDARY (founder-set, run-15): a provider-backed **fresh/billed input-token reduction** MAY be
+ * displayed when the provider reports cached input tokens (the provider served part of the input from its
+ * prompt cache, so fewer input tokens were billed fresh — with model-visible bytes unchanged). What is
+ * NOT claimed on this path: any model-visible input reduction, any output-token reduction, or any
+ * cost-savings figure (cost is unavailable — the provider reports tokens, not billing).
+ */
+export const GATEWAY_RECORD_LABEL = "record mode: request and response forwarded BYTE-FOR-BYTE (model-visible bytes unchanged). Provider-backed " +
+    "fresh/billed input reduction may be displayed when the provider reports cached input tokens; no model-visible " +
+    "input reduction, output-token reduction, or cost-savings claim is made (cost is unavailable on this path).";
+/**
+ * Compute the provider-backed fresh/billed input reduction. Available ONLY when the provider reported
+ * BOTH prompt input tokens (> 0) and cached input tokens (> 0): the cached portion was NOT billed as
+ * fresh input, so fresh/billed input is reduced by `cached / prompt`. Otherwise unavailable-with-reason —
+ * NEVER a zero "savings".
+ */
+export function freshBilledInputReduction(usage) {
+    const prompt = usage.promptInputTokens;
+    const cached = usage.cachedInputTokens;
+    if (prompt !== undefined && prompt > 0 && cached !== undefined && cached > 0) {
+        const pct = Math.round((cached / prompt) * 1000) / 10; // one decimal place
+        return {
+            available: true,
+            pct,
+            note: "provider-reported cached input tokens → fresh/billed input reduced; model-visible bytes unchanged"
+        };
+    }
+    return {
+        available: false,
+        note: cached === undefined || cached === 0
+            ? "the provider reported no cached input tokens for this request — fresh/billed input reduction unavailable"
+            : "the provider reported no prompt input tokens — fresh/billed input reduction unavailable"
+    };
+}
+/** The compact display string per the claim boundary (allowed forms only). */
+export function formatFreshBilledInputReduction(r) {
+    return r.available ? `-${r.pct}% fresh/billed input` : "fresh/billed input reduction: unavailable";
+}
+const COST_UNAVAILABLE_REASON = "the OpenAI response reports token usage but no cost or billing figure; no cost data exists on the gateway record path";
+/**
+ * Build ONE content-free gateway receipt from the request metadata + the provider's reported usage.
+ * `now`/`id` are injectable for deterministic tests. CONTENT-FREE: only `usage`'s numeric fields, the
+ * model label, the endpoint path, and the status ride on the receipt.
+ */
+export function buildGatewayReceipt(params) {
+    const now = params.now ?? (() => new Date().toISOString());
+    const id = params.id ?? (() => randomUUID());
+    const u = params.usage;
+    const model = u.model ?? params.requestModel ?? "unknown";
+    const tokens = {
+        ...(u.promptInputTokens !== undefined ? { prompt_input: u.promptInputTokens } : {}),
+        ...(u.cachedInputTokens !== undefined ? { cached_input: u.cachedInputTokens } : {}),
+        ...(u.billedFreshInputTokens !== undefined ? { billed_fresh_input: u.billedFreshInputTokens } : {}),
+        ...(u.outputTokens !== undefined ? { output: u.outputTokens } : {}),
+        ...(u.reasoningTokens !== undefined ? { reasoning: u.reasoningTokens } : {})
+    };
+    const tokenSource = u.present ? "provider-reported" : "unavailable";
+    const cacheSource = u.cachedInputTokens !== undefined ? "provider-reported" : "unavailable";
+    const reduction = freshBilledInputReduction({
+        ...(u.promptInputTokens !== undefined ? { promptInputTokens: u.promptInputTokens } : {}),
+        ...(u.cachedInputTokens !== undefined ? { cachedInputTokens: u.cachedInputTokens } : {})
+    });
+    return {
+        receipt_id: id(),
+        captured_at: now(),
+        provider: params.provider,
+        model,
+        endpoint: params.endpoint,
+        mode: params.mode,
+        upstream_status: params.upstreamStatus,
+        model_visible_bytes_changed: false,
+        tokens,
+        fresh_billed_input_reduction: reduction,
+        token_source: tokenSource,
+        cache_source: cacheSource,
+        cost_source: "unavailable",
+        reasons: {
+            ...(u.present ? {} : { token: u.unavailableReason ?? "no usage reported by the provider" }),
+            ...(cacheSource === "unavailable"
+                ? { cache: "the provider response did not report cached input tokens (prompt_tokens_details.cached_tokens) for this request" }
+                : {}),
+            cost: COST_UNAVAILABLE_REASON
+        },
+        claim_scope: "run-scoped",
+        approval_status: "not-required",
+        sync_status: "local-only",
+        content_uploaded: false,
+        ...(params.proofRunId ? { proof_run_id: params.proofRunId } : {}),
+        label: GATEWAY_RECORD_LABEL
+    };
+}
+/** Append a receipt to the local-only JSONL store under `<cwd>/.compaction/gateway/`. Content-free. */
+export async function appendGatewayReceipt(receipt, cwd = process.cwd()) {
+    const dir = path.join(cwd, DEFAULT_GATEWAY_RECEIPTS_DIR);
+    await mkdir(dir, { recursive: true });
+    const file = path.join(dir, GATEWAY_RECEIPTS_FILE);
+    await appendFile(file, `${JSON.stringify(receipt)}\n`, "utf8");
+    return file;
+}
+//# sourceMappingURL=receipt.js.map

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

@@ -0,0 +1,23 @@
+export declare const GATEWAY_RECOVERY_DIR = ".compaction/gateway/recovery";
+export interface RecoveryRecord {
+    recovery_id: string;
+    captured_at: string;
+    endpoint: string;
+    policy: string;
+    /** The EXACT original request body (pre-mutation). Local-only; the receipt never carries this. */
+    original_body: string;
+}
+/**
+ * Persist the original request body for recovery and return a fresh `recovery_id`. Best-effort restrictive
+ * permissions (0700 dir, 0600 file). Synchronous + fail-safe: throws only if the write genuinely fails
+ * (the caller treats a failure as "do NOT mutate" — apply must never proceed without a saved original).
+ */
+export declare function saveOriginalForRecovery(cwd: string, params: {
+    endpoint: string;
+    policy: string;
+    originalBody: string;
+    now?: () => string;
+    id?: () => string;
+}): string;
+/** Read a recovery record back by id, or null when it does not exist / cannot be parsed. */
+export declare function readRecovery(cwd: string, recoveryId: string): RecoveryRecord | null;

package/dist/core/gateway/recovery.js

@@ -0,0 +1,68 @@
+/**
+ * Compaction Gateway APPLY recovery store (PUBLIC CLI/SDK core — engine-free). Charter run-17.2.
+ *
+ * When apply mode changes a request body, the ORIGINAL body is retained LOCALLY here so the exact
+ * pre-mutation request is always recoverable. This is the ONE place gateway request content is persisted
+ * — deliberately, for recovery — and it is:
+ *   - local-only under `<cwd>/.compaction/gateway/recovery/` (gitignored; NEVER uploaded),
+ *   - written with restrictive `0600` permissions where the OS supports it,
+ *   - referenced from receipts by `recovery_id` ONLY (the content-free receipt never carries the body).
+ *
+ * `compaction gateway recover <recovery_id>` reads it back. Nothing here ever leaves the machine.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync } from "node:fs";
+import path from "node:path";
+export const GATEWAY_RECOVERY_DIR = ".compaction/gateway/recovery";
+function recoveryDir(cwd) {
+    return path.join(cwd, GATEWAY_RECOVERY_DIR);
+}
+function recoveryPath(cwd, recoveryId) {
+    return path.join(recoveryDir(cwd), `${recoveryId}.json`);
+}
+/**
+ * Persist the original request body for recovery and return a fresh `recovery_id`. Best-effort restrictive
+ * permissions (0700 dir, 0600 file). Synchronous + fail-safe: throws only if the write genuinely fails
+ * (the caller treats a failure as "do NOT mutate" — apply must never proceed without a saved original).
+ */
+export function saveOriginalForRecovery(cwd, params) {
+    const recoveryId = (params.id ?? (() => randomUUID()))();
+    const dir = recoveryDir(cwd);
+    mkdirSync(dir, { recursive: true });
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        /* best-effort — some filesystems (e.g. Windows) ignore POSIX modes */
+    }
+    const record = {
+        recovery_id: recoveryId,
+        captured_at: (params.now ?? (() => new Date().toISOString()))(),
+        endpoint: params.endpoint,
+        policy: params.policy,
+        original_body: params.originalBody
+    };
+    const file = recoveryPath(cwd, recoveryId);
+    writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        /* best-effort */
+    }
+    return recoveryId;
+}
+/** Read a recovery record back by id, or null when it does not exist / cannot be parsed. */
+export function readRecovery(cwd, recoveryId) {
+    const file = recoveryPath(cwd, recoveryId);
+    if (!existsSync(file))
+        return null;
+    try {
+        const rec = JSON.parse(readFileSync(file, "utf8"));
+        return rec && typeof rec.original_body === "string" ? rec : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=recovery.js.map

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

@@ -0,0 +1,51 @@
+/**
+ * Compaction Gateway server — RECORD MODE (PUBLIC CLI/SDK code — engine-free). Charter run-15.
+ *
+ * A LOCAL, byte-safe, OpenAI-compatible reverse proxy: a developer points their OpenAI client's base URL
+ * at this gateway; the gateway forwards the request to the real provider BYTE-FOR-BYTE, streams the
+ * response back BYTE-FOR-BYTE, and records ONE content-free receipt (`receipt.ts`) with the provider's
+ * reported token/cache usage. It NEVER mutates the request or the response (model-visible bytes
+ * unchanged), NEVER stores content, and NEVER persists the client's API key.
+ *
+ * Run-15 implements ONLY `record` mode (no cache-optimization, no apply, no LCM). Built on `node:http`
+ * (the repo's server style — see `apps/api/src/server.ts`); zero new dependency.
+ */
+import http from "node:http";
+import type { GatewayReceipt } from "./receipt.js";
+/** The server's configured gateway mode. Default `record`; `apply`/`dry-run` require explicit opt-in. */
+export type GatewayServerMode = "record" | "apply" | "dry-run";
+export interface GatewayServerOptions {
+    provider: string;
+    /** The upstream provider base (only its ORIGIN is used; the client's request path is authoritative). */
+    upstream: string;
+    /** `record` (default, byte-safe), or the explicit `apply`/`dry-run` deterministic modes (run-17.2). */
+    mode: GatewayServerMode;
+    /** Deterministic apply policy (run-17.2). Only `deterministic-dedupe` is implemented. */
+    policy?: string;
+    /** Where receipts are written (defaults to process.cwd()). */
+    cwd?: string;
+    /** Test/observability hook fired after each receipt is built (before/independent of the file append). */
+    onReceipt?: (receipt: GatewayReceipt) => void;
+    /** Best-effort logger for content-free operational lines (defaults to no-op). */
+    log?: (line: string) => void;
+}
+/**
+ * Create (but do not start) the gateway record-mode server. `createGatewayServer` is exported so tests
+ * can bind an ephemeral port. Every request is forwarded byte-for-byte; the receipt append is
+ * best-effort and NEVER alters or delays the client's response bytes.
+ */
+export declare function createGatewayServer(options: GatewayServerOptions): http.Server;
+export interface StartedGateway {
+    server: http.Server;
+    /** The bound address (host + port). */
+    address: {
+        host: string;
+        port: number;
+    };
+    close: () => Promise<void>;
+}
+/** Start the gateway on `host:port`. Resolves once it is listening. */
+export declare function startGatewayServer(options: GatewayServerOptions & {
+    host: string;
+    port: number;
+}): Promise<StartedGateway>;