@compaction/cli 0.2.0 → 0.3.0

package/dist/core/output-shaping.js

@@ -0,0 +1,89 @@
+/**
+ * Output-shaping policy family — deterministic, rule-based (PUBLIC CLI/SDK code, engine-free).
+ *
+ * Design: `docs/design/output-shaping-policy-family.md` (accepted; implementation authorized 2026-06-29).
+ * This is **increment 1**: the public/free deterministic policies that produce a CONTENT-FREE
+ * output-shaping **instruction block** to attach to a request **BEFORE generation** (the only mechanism
+ * that can reduce provider output tokens — post-generation processing does NOT).
+ *
+ * HONESTY (binding):
+ * - This module produces INSTRUCTIONS + attribution labels only. It computes **NO output-savings number**
+ *   and makes **NO claim** that output was reduced. An output-savings number requires (separately, in the
+ *   private/proprietary engine) a **measured A/B** (provider-reported output; N≥3/arm, ±2·SE excludes
+ *   zero) **AND** the **eval-gated short-but-sufficient** check. Until both pass, savings are unavailable.
+ * - The short-but-sufficient **eval** (policy #6 in the design) is the **private eval-gated verification**
+ *   — it is NOT in this public module; this module only emits the shaping instructions + their attribution.
+ * - Content-free: instructions are generic shaping text; no prompt/completion/trace content.
+ */
+/**
+ * The deterministic rule-based output-shaping policies (the public/free tier). The learned tier and the
+ * eval-gated verification are private/proprietary (Track A) — not here.
+ */
+export const OUTPUT_SHAPING_POLICIES = [
+    {
+        policy_name: "concise_response",
+        policy_family: "output_shaping",
+        risk_level: "low",
+        defaultOn: true,
+        description: "Ask for a concise answer where the task allows (no padding, no restating the prompt).",
+        instruction: () => "Answer concisely: omit preamble and restatement of the request; give only what the task needs."
+    },
+    {
+        policy_name: "verbosity_budget",
+        policy_family: "output_shaping",
+        risk_level: "low",
+        defaultOn: true,
+        description: "Set a soft target on response length (a budget, not a hard cap).",
+        instruction: (budget) => typeof budget === "number" && budget > 0
+            ? `Aim to stay within roughly ${budget} output tokens; prioritize the most task-relevant content if space is tight.`
+            : "Keep the response as short as is sufficient for the task; do not pad to fill space."
+    },
+    {
+        policy_name: "structured_output_constraints",
+        policy_family: "output_shaping",
+        risk_level: "low",
+        defaultOn: true,
+        description: "Prefer a bounded, structured format (lists/sections) that reduces filler.",
+        instruction: () => "Prefer a tight structured format (short bullets or labeled sections) over long prose where it fits the task."
+    },
+    {
+        policy_name: "redundant_chatter_suppression",
+        policy_family: "output_shaping",
+        risk_level: "low",
+        defaultOn: true,
+        description: "Suppress boilerplate, preamble, apologies, and repetition.",
+        instruction: () => "Skip boilerplate, apologies, and repetition; do not summarize what you just said."
+    },
+    {
+        policy_name: "safe_tool_output_filtering",
+        policy_family: "output_shaping",
+        // Slightly higher risk: trimming tool output can drop detail, so it is OFF by default and only
+        // requests omission of clearly-redundant tool echo — recoverability of task-critical detail first.
+        risk_level: "medium",
+        defaultOn: false,
+        description: "Request omission of clearly-redundant tool-output echo (recoverability preserved first).",
+        instruction: () => "Do not echo large tool outputs verbatim; reference them and include only the task-relevant lines."
+    }
+];
+/** Note attached to every emitted block: this is a request-shaping instruction, not a savings claim. */
+export const OUTPUT_SHAPING_HONESTY_NOTE = "Attach BEFORE generation (post-generation processing does not reduce provider output tokens). " +
+    "No output-token savings are claimed: a savings figure requires a measured before/after (provider-reported) " +
+    "and eval-confirmed sufficiency — neither is asserted here.";
+/**
+ * Build the content-free output-shaping instruction block + attribution from the deterministic family.
+ * Produces instructions only — NO savings number, NO claim of reduction.
+ */
+export function buildOutputShapingPolicy(opts = {}) {
+    const selected = opts.policies && opts.policies.length > 0
+        ? OUTPUT_SHAPING_POLICIES.filter((p) => opts.policies.includes(p.policy_name))
+        : OUTPUT_SHAPING_POLICIES.filter((p) => p.defaultOn);
+    const lines = selected.map((p) => `- ${p.instruction(opts.verbosityBudgetTokens)}`);
+    const instructions = selected.length === 0
+        ? ""
+        : ["Output-shaping policy (apply to your response):", ...lines].join("\n");
+    return {
+        instructions,
+        applied: selected.map((p) => ({ policy_name: p.policy_name, policy_family: p.policy_family, risk_level: p.risk_level }))
+    };
+}
+//# sourceMappingURL=output-shaping.js.map

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

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