@compaction/cli 0.2.0 → 0.3.0

package/dist/core/gateway/configure.js

@@ -0,0 +1,169 @@
+/**
+ * Gateway project configure (PUBLIC CLI core). Charter run-17.1.
+ *
+ * Approval-gated: this module only ever PLANS a change (detect the project, propose adding an
+ * OPENAI_BASE_URL pointing at the local gateway, and render an exact diff). It writes NOTHING unless the
+ * caller explicitly applies the plan, and even then it creates a `.bak` backup first and refuses to
+ * overwrite an existing provider base URL without an explicit force. No auto-write, ever.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** The env var we set to route an OpenAI-compatible client through the gateway. */
+export const CONFIGURE_ENV_VAR = "OPENAI_BASE_URL";
+const ENV_CANDIDATES = [".env", ".env.local"];
+const BASE_URL_VARS = ["OPENAI_BASE_URL", "OPENAI_API_BASE"];
+function readIfExists(p) {
+    try {
+        return fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Find an existing base-URL assignment in a dotenv-style body. Returns the var + value, or null. */
+function findBaseUrlAssignment(body) {
+    for (const line of body.split(/\r?\n/)) {
+        const m = line.match(/^\s*(?:export\s+)?([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+        if (!m)
+            continue;
+        if (BASE_URL_VARS.includes(m[1])) {
+            return { var: m[1], value: m[2].replace(/^["']|["']$/g, "") };
+        }
+    }
+    return null;
+}
+/** Detect the project's OpenAI-config surface WITHOUT modifying anything. */
+export function detectProject(cwd) {
+    const envFiles = [];
+    let existingBaseUrl;
+    for (const name of ENV_CANDIDATES) {
+        const body = readIfExists(path.join(cwd, name));
+        if (body === null)
+            continue;
+        envFiles.push(name);
+        if (!existingBaseUrl) {
+            const found = findBaseUrlAssignment(body);
+            if (found)
+                existingBaseUrl = { file: name, var: found.var, value: found.value };
+        }
+    }
+    let hasPackageJson = false;
+    let usesOpenAiSdk = false;
+    const pkgBody = readIfExists(path.join(cwd, "package.json"));
+    if (pkgBody !== null) {
+        hasPackageJson = true;
+        try {
+            const pkg = JSON.parse(pkgBody);
+            usesOpenAiSdk = Boolean(pkg.dependencies?.openai || pkg.devDependencies?.openai);
+        }
+        catch {
+            /* malformed package.json — leave usesOpenAiSdk false */
+        }
+    }
+    return { envFiles, hasPackageJson, usesOpenAiSdk, ...(existingBaseUrl ? { existingBaseUrl } : {}) };
+}
+/**
+ * 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 function planGatewayConfigure(cwd, baseUrl) {
+    const detection = detectProject(cwd);
+    const targetFile = detection.envFiles.includes(".env.local")
+        ? ".env.local"
+        : detection.envFiles.includes(".env")
+            ? ".env"
+            : ".env";
+    const targetPath = path.join(cwd, targetFile);
+    const existing = readIfExists(targetPath);
+    const newLine = `${CONFIGURE_ENV_VAR}=${baseUrl}`;
+    let action;
+    let diff;
+    let note;
+    if (detection.existingBaseUrl) {
+        action = "conflict";
+        diff =
+            `- ${detection.existingBaseUrl.var}=${detection.existingBaseUrl.value}   (in ${detection.existingBaseUrl.file})\n` +
+                `+ ${newLine}`;
+        note =
+            `${detection.existingBaseUrl.file} already sets ${detection.existingBaseUrl.var}. ` +
+                "Compaction will NOT overwrite an existing provider base URL without explicit confirmation (--force).";
+    }
+    else if (existing === null) {
+        action = "create";
+        diff = `+ ${newLine}`;
+        note = `${targetFile} does not exist yet. Apply would create it with just the gateway base URL line.`;
+    }
+    else {
+        action = "append";
+        diff = `  (existing ${targetFile} unchanged)\n+ ${newLine}`;
+        note = `Apply would append one line to ${targetFile} (a .bak backup is written first).`;
+    }
+    return {
+        targetFile,
+        action,
+        baseUrl,
+        diff,
+        ...(existing !== null ? { backupFile: `${targetFile}.bak` } : {}),
+        detection,
+        note
+    };
+}
+/**
+ * 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 function applyGatewayConfigure(cwd, plan, force = false) {
+    if (plan.action === "conflict" && !force) {
+        return { wrote: false, targetFile: plan.targetFile, reason: "existing provider base URL present; re-run with --force to overwrite" };
+    }
+    const targetPath = path.join(cwd, plan.targetFile);
+    const existing = readIfExists(targetPath);
+    const newLine = `${CONFIGURE_ENV_VAR}=${plan.baseUrl}`;
+    let backupFile;
+    if (existing !== null) {
+        backupFile = `${plan.targetFile}.bak`;
+        fs.writeFileSync(path.join(cwd, backupFile), existing, "utf8");
+    }
+    let next;
+    if (plan.action === "conflict" && existing !== null) {
+        // Replace the existing base-URL assignment line in place.
+        next = existing
+            .split(/\r?\n/)
+            .map((line) => {
+            const m = line.match(/^\s*(?:export\s+)?([A-Z0-9_]+)\s*=/);
+            return m && BASE_URL_VARS.includes(m[1]) ? newLine : line;
+        })
+            .join("\n");
+    }
+    else if (existing !== null) {
+        next = existing.endsWith("\n") ? `${existing}${newLine}\n` : `${existing}\n${newLine}\n`;
+    }
+    else {
+        next = `${newLine}\n`;
+    }
+    fs.writeFileSync(targetPath, next, "utf8");
+    return { wrote: true, targetFile: plan.targetFile, ...(backupFile ? { backupFile } : {}) };
+}
+/** Render a configure plan as plain content-free lines (for the CLI preview). */
+export function formatConfigurePlan(plan) {
+    const lines = [];
+    lines.push("compaction gateway configure — proposed change (nothing is written yet)");
+    lines.push(`  target file:  ${plan.targetFile}   (${plan.action})`);
+    lines.push(`  detected:     ${describeDetection(plan.detection)}`);
+    lines.push("  diff:");
+    for (const d of plan.diff.split("\n"))
+        lines.push(`    ${d}`);
+    lines.push(`  note:         ${plan.note}`);
+    lines.push("");
+    lines.push("  to apply:     compaction gateway configure --apply" + (plan.action === "conflict" ? " --force" : ""));
+    return lines;
+}
+function describeDetection(d) {
+    const bits = [];
+    bits.push(d.envFiles.length ? `env files: ${d.envFiles.join(", ")}` : "no .env files");
+    bits.push(d.hasPackageJson ? (d.usesOpenAiSdk ? "openai SDK in package.json" : "package.json (no openai dep)") : "no package.json");
+    if (d.existingBaseUrl)
+        bits.push(`existing ${d.existingBaseUrl.var} in ${d.existingBaseUrl.file}`);
+    return bits.join("; ");
+}
+//# sourceMappingURL=configure.js.map

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;