@compaction/cli 0.1.4 → 0.3.0

package/dist/core/cursor-preflight-probe.js

@@ -0,0 +1,88 @@
+/**
+ * SAFE real probe adapter for the Cursor live-prep preflight (`cursor-preflight.ts`).
+ *
+ * This is the ONLY place the preflight spawns a child process, and it spawns ONLY a `--help`/`-v`-style
+ * capability probe. Defense-in-depth: it hard-rejects any arg set that is not a recognized safe help
+ * probe, so it can NEVER be coaxed into a real `-p` prompt, `cursor agent login`, or a credential read.
+ *
+ * - No stdin (closed): a probe never waits for input.
+ * - stdout/stderr captured only to inspect for the headless flags in --help text (content-free).
+ * - CURSOR_API_KEY is never read, set, or forwarded specially — the probe inherits the caller's env
+ *   unchanged (we never touch the key), and never prints env values.
+ * - Fail-friendly: an ENOENT / spawn error resolves to `resolved:false`, never a throw.
+ */
+import { spawn } from "node:child_process";
+/** Only these tokens may appear in a probe arg list. Anything else is refused (never spawned). */
+const SAFE_PROBE_TOKENS = new Set(["agent", "--help", "-h", "--version", "-v"]);
+/** True when EVERY arg is a recognized safe help/version token (no prompt, no `-p`, no `login`). */
+export function isSafeProbeArgs(args) {
+    if (args.length === 0)
+        return false;
+    return args.every((a) => SAFE_PROBE_TOKENS.has(a));
+}
+/**
+ * Create the real SAFE probe. The returned probe spawns `<candidate> <args>` ONLY when `args` is a
+ * recognized safe help probe; otherwise it refuses (returns `resolved:false` without spawning).
+ */
+export function createSafeCursorProbe(timeoutMs = 5000) {
+    return (candidate, args) => {
+        return new Promise((resolve) => {
+            const notRun = (helpText) => ({ candidate, resolved: false, helpText, exitCode: null });
+            // Defense-in-depth: refuse anything that is not a pure help/version probe.
+            if (!isSafeProbeArgs(args)) {
+                resolve(notRun("refused: non-help probe args (safety guard)"));
+                return;
+            }
+            let helpText = "";
+            let settled = false;
+            let child;
+            try {
+                child = spawn(candidate, args, {
+                    shell: false,
+                    windowsHide: true,
+                    // Closed stdin so a probe never blocks waiting for input; capture stdout/stderr to read --help.
+                    stdio: ["ignore", "pipe", "pipe"]
+                });
+            }
+            catch {
+                resolve(notRun(""));
+                return;
+            }
+            const finish = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(result);
+            };
+            const timer = setTimeout(() => {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* ignore */
+                }
+                // A hung help probe: treat as resolved (it spawned) but with whatever text we saw.
+                finish({ candidate, resolved: true, helpText, exitCode: null });
+            }, timeoutMs);
+            timer.unref?.();
+            child.stdout?.setEncoding("utf8");
+            child.stderr?.setEncoding("utf8");
+            child.stdout?.on("data", (c) => {
+                helpText += c;
+            });
+            child.stderr?.on("data", (c) => {
+                helpText += c;
+            });
+            child.on("error", () => {
+                // ENOENT / not executable → the binary is not resolvable. Fail-friendly, never throw.
+                clearTimeout(timer);
+                finish(notRun(""));
+            });
+            child.on("close", (exitCode) => {
+                clearTimeout(timer);
+                finish({ candidate, resolved: true, helpText, exitCode: exitCode ?? null });
+            });
+        });
+    };
+}
+//# sourceMappingURL=cursor-preflight-probe.js.map

package/dist/core/cursor-preflight.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Cursor LIVE-PREP preflight/diagnostics (PUBLIC CLI code — engine-free, ships in the npm package).
+ *
+ * A content-free readiness check surfaced when a LIVE `run cursor` / `capture cursor` is requested
+ * (no `--export`). It answers two questions and prints exact actionable guidance so a live Cursor run
+ * validates cleanly once the operator authenticates — WITHOUT this tool ever authenticating or spending:
+ *
+ *   1. **CLI resolvable?**  Is a Cursor headless CLI binary on PATH (`cursor` / `cursor-agent`) or at a
+ *      known macOS app path (`/Applications/Cursor.app/Contents/Resources/app/bin/cursor`)?
+ *   2. **Capability present?**  Does `<cli> agent --help` (or `--help`) advertise the headless flags we
+ *      need (`-p`/`--print` + `--output-format`)?
+ *
+ * HARD SAFETY RAILS (the defining constraints of this module):
+ * - **SAFE probes only.** Probing is limited to `--help` / `-v` / `--version` style invocations. This
+ *   module NEVER runs a real `-p` prompt, NEVER runs `cursor agent login`, and NEVER reads, sets, or
+ *   prints `CURSOR_API_KEY`.
+ * - **Auth-state is NOT detected.** Cursor's auth state cannot be observed without a real (spending)
+ *   call, so this module detects **CLI-presence + capability only** and tells the operator to run
+ *   `cursor agent login` (or set `CURSOR_API_KEY`) and retry. It never guesses "authenticated".
+ * - **Fail friendly.** A probe that errors/crashes is treated as "not detectable", never a thrown
+ *   exception — the pure logic here is total over its synthetic inputs.
+ * - **Content-free.** No prompt, no output, no credential value is ever read or emitted.
+ *
+ * Honesty binding (unchanged): Cursor = LOCAL-ESTIMATE only; provider-reported UNAVAILABLE; never a
+ * savings claim. This module surfaces none of those figures — it is a readiness check + guidance only.
+ *
+ * Design: `docs/design/cursor-live-wrapper.md` (Verify-first precondition V) + the honesty rails in
+ * `docs/ops/cursor-support-matrix.md`.
+ */
+/** Candidate CLI locations, in probe order. Kept as data so the pure logic is fully testable. */
+export declare const CURSOR_CLI_PATH_CANDIDATES: readonly ["cursor-agent", "cursor"];
+export declare const CURSOR_CLI_KNOWN_MACOS_PATH = "/Applications/Cursor.app/Contents/Resources/app/bin/cursor";
+/** The exact command an operator runs once authed (surfaced verbatim in the guidance). */
+export declare const CURSOR_EXAMPLE_RUN_COMMAND = "compaction run cursor --out <dir> -- cursor agent -p \"<your prompt>\" --output-format json";
+/**
+ * Result of a single SAFE probe of one candidate binary. `helpText` comes from a `--help`/`-v`-style
+ * invocation only. `resolved` is false when the binary could not be spawned at all (ENOENT / not
+ * executable). This is the ONLY input the pure classifier consumes — so tests can feed synthetic probe
+ * outputs with no live `cursor agent` call.
+ */
+export interface CursorProbeResult {
+    /** The candidate that was probed (a PATH name or an absolute path). */
+    candidate: string;
+    /** True when the binary spawned (even if it exited non-zero); false on ENOENT / spawn failure. */
+    resolved: boolean;
+    /** Combined help/version text observed from the SAFE probe (stdout + stderr). Content-free (help text). */
+    helpText: string;
+    /** Exit code of the SAFE probe, or null if it never ran. */
+    exitCode: number | null;
+}
+/**
+ * A probe function: given a candidate + safe args, returns what the SAFE probe observed. Injected so
+ * the classifier is pure/testable; the real adapter (`createSafeCursorProbe`) spawns `--help`/`-v` only.
+ */
+export type CursorProbe = (candidate: string, args: string[]) => Promise<CursorProbeResult>;
+export interface CursorPreflightReport {
+    /** Whether a Cursor CLI binary could be resolved (PATH or known macOS app path). */
+    cliResolvable: boolean;
+    /** The resolved binary path/name, if any. */
+    resolvedCli?: string;
+    /** Whether the resolved CLI advertises the headless capability (`-p`/`--print` + `--output-format`). */
+    capabilityPresent: boolean;
+    /**
+     * Auth is intentionally NEVER probed (would require a real, spending call). Always "not-checked" so
+     * no caller can mistake this for an "authenticated" signal.
+     */
+    authState: "not-checked";
+    /** Overall readiness of the LOCAL PREP surface: ready = CLI resolvable AND capability present. */
+    ready: boolean;
+    /** Human-readable, content-free diagnostic + guidance lines (safe to print to stdout). */
+    guidance: string[];
+}
+/**
+ * PURE classifier: given the SAFE probe results for the CLI candidates, decide resolvable/capable and
+ * build the exact guidance. No I/O, no spawning, no env reads — this is what the tests target directly.
+ *
+ * A candidate is "capable" when its help text advertises BOTH `-p`/`--print` AND `--output-format`.
+ */
+export declare function classifyCursorPreflight(probes: CursorProbeResult[]): CursorPreflightReport;
+/**
+ * Run the preflight using an injectable probe. Tries each candidate with a SAFE capability probe
+ * (`agent --help`), then classifies. Pure over `probe` — the default real adapter
+ * (`createSafeCursorProbe`) is the only place a child process is spawned, and only with `--help`-style
+ * args. The candidate order puts the known macOS app path LAST as a fallback when PATH names miss.
+ */
+export declare function runCursorPreflight(probe: CursorProbe, candidates?: readonly string[]): Promise<CursorPreflightReport>;

package/dist/core/cursor-preflight.js

@@ -0,0 +1,126 @@
+/**
+ * Cursor LIVE-PREP preflight/diagnostics (PUBLIC CLI code — engine-free, ships in the npm package).
+ *
+ * A content-free readiness check surfaced when a LIVE `run cursor` / `capture cursor` is requested
+ * (no `--export`). It answers two questions and prints exact actionable guidance so a live Cursor run
+ * validates cleanly once the operator authenticates — WITHOUT this tool ever authenticating or spending:
+ *
+ *   1. **CLI resolvable?**  Is a Cursor headless CLI binary on PATH (`cursor` / `cursor-agent`) or at a
+ *      known macOS app path (`/Applications/Cursor.app/Contents/Resources/app/bin/cursor`)?
+ *   2. **Capability present?**  Does `<cli> agent --help` (or `--help`) advertise the headless flags we
+ *      need (`-p`/`--print` + `--output-format`)?
+ *
+ * HARD SAFETY RAILS (the defining constraints of this module):
+ * - **SAFE probes only.** Probing is limited to `--help` / `-v` / `--version` style invocations. This
+ *   module NEVER runs a real `-p` prompt, NEVER runs `cursor agent login`, and NEVER reads, sets, or
+ *   prints `CURSOR_API_KEY`.
+ * - **Auth-state is NOT detected.** Cursor's auth state cannot be observed without a real (spending)
+ *   call, so this module detects **CLI-presence + capability only** and tells the operator to run
+ *   `cursor agent login` (or set `CURSOR_API_KEY`) and retry. It never guesses "authenticated".
+ * - **Fail friendly.** A probe that errors/crashes is treated as "not detectable", never a thrown
+ *   exception — the pure logic here is total over its synthetic inputs.
+ * - **Content-free.** No prompt, no output, no credential value is ever read or emitted.
+ *
+ * Honesty binding (unchanged): Cursor = LOCAL-ESTIMATE only; provider-reported UNAVAILABLE; never a
+ * savings claim. This module surfaces none of those figures — it is a readiness check + guidance only.
+ *
+ * Design: `docs/design/cursor-live-wrapper.md` (Verify-first precondition V) + the honesty rails in
+ * `docs/ops/cursor-support-matrix.md`.
+ */
+/** Candidate CLI locations, in probe order. Kept as data so the pure logic is fully testable. */
+export const CURSOR_CLI_PATH_CANDIDATES = ["cursor-agent", "cursor"];
+export const CURSOR_CLI_KNOWN_MACOS_PATH = "/Applications/Cursor.app/Contents/Resources/app/bin/cursor";
+/** The exact command an operator runs once authed (surfaced verbatim in the guidance). */
+export const CURSOR_EXAMPLE_RUN_COMMAND = 'compaction run cursor --out <dir> -- cursor agent -p "<your prompt>" --output-format json';
+/** True when help text advertises the headless print flag (`-p` or `--print`). */
+function hasPrintFlag(helpText) {
+    return /(^|\s)-p(\s|,|$)/.test(helpText) || /--print\b/.test(helpText);
+}
+/** True when help text advertises `--output-format` (the flag that makes output separable). */
+function hasOutputFormatFlag(helpText) {
+    return /--output-format\b/.test(helpText);
+}
+/**
+ * PURE classifier: given the SAFE probe results for the CLI candidates, decide resolvable/capable and
+ * build the exact guidance. No I/O, no spawning, no env reads — this is what the tests target directly.
+ *
+ * A candidate is "capable" when its help text advertises BOTH `-p`/`--print` AND `--output-format`.
+ */
+export function classifyCursorPreflight(probes) {
+    const resolvedProbes = probes.filter((p) => p.resolved);
+    const cliResolvable = resolvedProbes.length > 0;
+    // Prefer a resolved candidate that ALSO shows the capability; else the first resolved one.
+    const capableProbe = resolvedProbes.find((p) => hasPrintFlag(p.helpText) && hasOutputFormatFlag(p.helpText));
+    const resolvedCli = capableProbe?.candidate ?? resolvedProbes[0]?.candidate;
+    const capabilityPresent = capableProbe !== undefined;
+    const ready = cliResolvable && capabilityPresent;
+    const guidance = [];
+    guidance.push("Cursor live-run preflight (content-free; no prompt run, no login, no API key read):");
+    guidance.push(`  - CLI resolvable: ${cliResolvable ? `yes (${resolvedCli})` : "no"}`);
+    guidance.push(`  - Headless capability (-p/--print + --output-format): ${capabilityPresent ? "yes" : cliResolvable ? "not detected in --help" : "n/a (CLI not resolved)"}`);
+    // Auth is deliberately NOT probed — say so explicitly so nobody reads readiness as "authenticated".
+    guidance.push("  - Auth: NOT checked here (detecting it needs a real, spending call). After the steps below, run `cursor agent login` (or set CURSOR_API_KEY) and retry.");
+    if (!cliResolvable) {
+        guidance.push("");
+        guidance.push("Next steps — the Cursor headless CLI was not found:");
+        guidance.push("  1. Install / locate it: install the Cursor CLI (see cursor.com docs), or if the Cursor app is installed on macOS it ships at:");
+        guidance.push(`       ${CURSOR_CLI_KNOWN_MACOS_PATH}`);
+        guidance.push("     Ensure `cursor` or `cursor-agent` is on your PATH (the `agent` subcommand provides `-p`/`--output-format`).");
+        guidance.push("  2. Authenticate (does NOT happen automatically here): run `cursor agent login`, OR export CURSOR_API_KEY in your shell.");
+        guidance.push("  3. Then run the live flow:");
+        guidance.push(`       ${CURSOR_EXAMPLE_RUN_COMMAND}`);
+    }
+    else if (!capabilityPresent) {
+        guidance.push("");
+        guidance.push(`Next steps — a Cursor CLI was found (${resolvedCli}) but its --help did not advertise the headless flags (-p/--print + --output-format):`);
+        guidance.push("  - This may be the Cursor editor launcher rather than the headless agent CLI. Install/verify the headless `cursor agent` CLI, then retry.");
+        guidance.push("  - Authenticate first (not done here): `cursor agent login`, OR set CURSOR_API_KEY.");
+        guidance.push("  - Then run the live flow:");
+        guidance.push(`       ${CURSOR_EXAMPLE_RUN_COMMAND}`);
+    }
+    else {
+        guidance.push("");
+        guidance.push("The Cursor headless CLI is present and capable. Auth is the only remaining prerequisite (not checked here):");
+        guidance.push("  1. Authenticate: run `cursor agent login`, OR export CURSOR_API_KEY.");
+        guidance.push("  2. Then run the live flow:");
+        guidance.push(`       ${CURSOR_EXAMPLE_RUN_COMMAND}`);
+        guidance.push("  Note: Cursor tokens are LOCAL-ESTIMATE only (Cursor emits no provider usage) — provider-reported tokens are unavailable and no savings is claimed.");
+    }
+    return {
+        cliResolvable,
+        ...(resolvedCli !== undefined ? { resolvedCli } : {}),
+        capabilityPresent,
+        authState: "not-checked",
+        ready,
+        guidance
+    };
+}
+/**
+ * Run the preflight using an injectable probe. Tries each candidate with a SAFE capability probe
+ * (`agent --help`), then classifies. Pure over `probe` — the default real adapter
+ * (`createSafeCursorProbe`) is the only place a child process is spawned, and only with `--help`-style
+ * args. The candidate order puts the known macOS app path LAST as a fallback when PATH names miss.
+ */
+export async function runCursorPreflight(probe, candidates = [...CURSOR_CLI_PATH_CANDIDATES, CURSOR_CLI_KNOWN_MACOS_PATH]) {
+    const probes = [];
+    for (const candidate of candidates) {
+        // SAFE capability probes ONLY. Never a real prompt, never `login`. We try BOTH help forms because
+        // the flags live under different help surfaces across shapes: the standalone `cursor-agent` binary
+        // IS the agent (headless flags on its top-level `--help`), while the editor `cursor` launcher
+        // exposes them under the `agent` subcommand (`cursor agent --help`). A candidate that resolves in
+        // EITHER probe counts as resolved; its help text is the one that best advertises the capability.
+        const subcommandHelp = await probe(candidate, ["agent", "--help"]);
+        const topLevelHelp = await probe(candidate, ["--help"]);
+        probes.push(mergeCandidateProbes(candidate, [subcommandHelp, topLevelHelp]));
+    }
+    return classifyCursorPreflight(probes);
+}
+/** Merge the help forms tried for one candidate: resolved if EITHER spawned; keep the help text that
+ *  advertises the capability (so a candidate is judged capable if ANY safe help form shows the flags). */
+function mergeCandidateProbes(candidate, forms) {
+    const resolved = forms.some((f) => f.resolved);
+    const capableForm = forms.find((f) => f.resolved && hasPrintFlag(f.helpText) && hasOutputFormatFlag(f.helpText));
+    const chosen = capableForm ?? forms.find((f) => f.resolved) ?? forms[0];
+    return { candidate, resolved, helpText: chosen?.helpText ?? "", exitCode: chosen?.exitCode ?? null };
+}
+//# sourceMappingURL=cursor-preflight.js.map

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

@@ -0,0 +1,39 @@
+/**
+ * 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 { type ApplyPolicyName } from "./apply-policy.js";
+export type GatewayEffectiveMode = "record" | "apply" | "dry-run";
+export interface ApplyActivation {
+    /** The mode the server will actually execute. Forced to "record" whenever we fail closed. */
+    mode: GatewayEffectiveMode;
+    /** True when apply OR dry-run was requested (by server config or header) — even if we fail closed. */
+    requested: boolean;
+    /** The resolved policy (only `deterministic-dedupe` is known). */
+    policy?: ApplyPolicyName;
+    /** Content-free label for the receipt's approval_status / activation source. */
+    activation: "record" | "explicit-mode" | "explicit-header" | "dry-run-mode" | "dry-run-header" | "fail-closed";
+    /** Set when apply/dry-run was requested but we fell back to record (conflict / unknown policy). */
+    failClosedReason?: string;
+}
+/**
+ * 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 declare function resolveApplyActivation(params: {
+    serverMode: string;
+    serverPolicy?: string;
+    headerMode?: string;
+    headerPolicy?: string;
+}): ApplyActivation;

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;