Compress

Pre-split: a single auto_compress_enabled toggle covered everything — system prompt, user turns, assistant turns. Workloads with stable expensive system prompts that benefited from compression there but with sensitive variable user content had no way to enable one without the other.

Post-split (migration 0076): two independent toggles — compress_system_enabled covers messages with role: 'system' AND the top-level Anthropic-shape system field; compress_user_turns_enabled covers messages with role IN (user, assistant). Either-true → stage active. Both-true → both compressed (matches legacy behaviour). Both-false → stage skipped entirely. The legacy master toggle is read-side compatible for KV rollback safety but worker 0.41.0+ no longer consults it.

Pre-detect runs in the worker's Stage-3 candidate-detection block before any route decision so the composition cap can correctly claim M1 off the table when a mutation is pending. M3 eligibility is two filters:

• body_chars >= COMPRESS_MIN_BODY_CHARS (default ~512). Shorter bodies don't accumulate enough redundancy to justify a content mutation.
• redundant_whitespace_ratio >= COMPRESS_MIN_REDUNDANT_PCT. We measure runs of consecutive spaces / repeated newlines / tab blocks as a fraction of total body chars. Tight prompts with no redundancy bypass compression.

Both filters must pass. A body that's long but tight (a single large code block, an embedded JSON payload) skips M3. A body that's redundant but short (boilerplate user-message under 512 chars) also skips. We'd rather miss a tiny win than mutate a request that wasn't going to save much.

The applier (lib/optimization/compress-applier.ts) is conservative by structural inspection, not by heuristic:

• Triple-backtick code fences — content inside ```...``` passes through verbatim. Indentation, blank lines, and duplicate spaces inside code are semantically load-bearing for many languages (Python, YAML).
• JSON payloads — when a message content is structured JSON (detected by leading { or [ with balanced braces), the applier skips it. Compressing JSON whitespace can subtly break downstream consumers that pattern- match on key spacing.
• Tool-call and tool-result blocks — Anthropic tool_use / tool_result content arrays are passed through structurally; only free-text fields inside them are eligible.

What does change: runs of 2+ spaces collapse to 1; runs of 3+ newlines collapse to 2; trailing whitespace on lines is stripped. Leading whitespace on lines is left intact (it's load-bearing for markdown lists and outline structure).

M3 is one of three content-mutating mechanics — M3 compress, M7 context prune, M8 structured output. The proxy enforces at most onemutation per request, with priority M7 > M3 > M8. If M7 already fired, contentMutationApplied = true short-circuits M3. If M3 fires, contentMutationApplied = true short-circuits M8 below.

The composition cap is documented on the parent /how-it-works page. M1 auto-route is also disabled when ANY mutating mechanic is about to fire — cost-reduction stacked on prompt-mutation multiplies quality risk in a way the canary cannot easily decompose.

Migration 0077 (2026-05-26) added two columns to optimize_savings: compress_chars_before and compress_chars_after. Both are JSON-stringify lengths captured immediately before and after the applier ran. NULL on non-M3 requests; integer pair on M3 requests.

Two surfaces consume these values: the per-row chip strip on /portal/audit (shows the delta), and the weekly compress-ratio widget on the operator dashboard (/optimize/quality/[workload_id] drill-down). Workloads with a 7-day rolling SUM(chars_before)/SUM(chars_after) near 1.0 are candidates for M3 disablement — the mechanic is firing but not producing real reduction. We surface that signal to the operator rather than auto-disable: there are cases where consistent small reductions across many requests still aggregate to material savings.

Five explicit non-features:

• No semantic compression. v0.1 is structural normalisation, not paraphrase-and-shorten. We do not invoke a secondary LLM to rewrite the prompt in fewer tokens.
• No LLMLingua-2. ADR-0003 documents the server-side LLMLingua-2 path — selective token removal guided by a small classifier model. Live customer evaluation gates shipping; until then we use only the deterministic heuristic.
• No per-message redaction.M3 does not remove content because it's "unimportant". Every redundancy reduction is whitespace / structural; sentences survive verbatim.
• No streaming-side compression. The applier runs once on the outgoing body. Streaming responses come back from the provider untouched.
• No back-pressure. If the applier throws or takes more than expected, the worker discards the result and forwards the original body. We never let M3 break a request.

• Request log line compress_applied on every M3 fire — carries chars_before, chars_after, chars_saved, pct_saved, compress_system, compress_user_turns flags.
• /portal/audit — the m3 chip in the canonical mechanics_stack. Mutating-mechanic chip colour (warning amber) distinguishes M3 from non-mutating siblings.
• Operator dashboard /optimize/quality/[workload_id] — 7-day rolling compress ratio per workload, plus a per-stack breach timeline.

M3 is opt-in per role, deterministic, structurally conservative, composition-capped to never stack with another mutation, and surfaced on every audit row. We never claim a saving we can't point at — every M3 row carries the byte-exact before/after counts as a database column.

Parent index: How it works. Companion mechanic deep-dives: M1 auto-route · M11 cross-provider failover.