Skip to content

docs(compression): align guide claims with source - #15596

Merged
diegosouzapw merged 7 commits into
diegosouzapw:release/v3.8.52from
woodsonl:docs/compression-guide-source-check
Oct 6, 2026
Merged

diegosouzapw merged 7 commits into
diegosouzapw:release/v3.8.52from
woodsonl:docs/compression-guide-source-check

Conversation

@woodsonl

@woodsonl woodsonl commented Oct 5, 2026

Copy link
Copy Markdown
Contributor

Summary

  • A source check of docs/compression/COMPRESSION_GUIDE.md found statements the code does not bear out. This PR corrects the Caveman Output Mode, Output Styles, Tool Result Compression and language-selection passages against the current sources, and fixes the contradictions a verification sweep found in the surrounding sections (Ultra, Aggressive, Cache-Aware, Progressive Aging, Stacked Pipeline, Combo Overrides, RTK filter count, routing-combo override list).

Main corrections:

  • Caveman Output Mode: requests get the instructions through applyOutputStyles() after chatCore.ts resolves the selection with the back-compat shim; outputMode.ts holds the texts, the bypass and the placement helper, and its applyCavemanOutputMode() has no production caller. The example prompt that matches no instruction text is replaced with the actual English full text. The shim maps cavemanOutputMode to terse-prose only while outputStyles is empty, and input compression still runs after injection.
  • How injection works: the idempotency check runs before the content bypass; the order-sensitive bypass is a step word followed within 240 characters by an action word, not a keyword list; the no-messages path consults neither the bypass nor the top-level system field, skips an already-marked instructions field as already_applied, and overwrites only non-string instructions/input values.
  • Language selection: autoDetect samples only the messages array, so Responses bodies (input) fall back to defaultLanguage; the detector returns a fixed language set and never defaultLanguage on zero hits; vi is never detected; a compression combo forces languageConfig.enabled on and derives defaultLanguage from the combo's language packs.
  • Tool Result Compression: the five strategies are listed with their actual triggers (indentation-tolerant code keywords, the path:line: shape a timestamp line also matches, ANSI CSI or $ + whitespace, JSON start/parse conditions, case-insensitive error substrings), plus the {…N keys} placeholder, the error-elision marker's 14-line floor, and the callers' saved <= 0 guard.
  • Ultra Mode: an independent score-based prose pruner with structure preservation and an optional SLM tier. It does not include Aggressive mode's features, thin code blocks, or binary-search truncate (no such code exists).
  • Aggressive Mode: tool outputs are truncated or elided, not summarized.
  • Cache-Aware: a caching provider alone triggers the downgrade (no cache_control markers required, and markers alone never trigger it); the never-consumed deterministic-transformations step is dropped.
  • Progressive Aging: documents the shipped thresholds (last 2 turns verbatim, caveman at distance 3, summarized from distance 4, nothing dropped), the exemptions (system prompts, already-aged messages, the latest user message), and that it runs in aggressive mode only, not ultra.
  • Stacked Pipeline: numbers composed from the guide's own math (46% Caveman step, ~89% average); configuration points at the stackedPipeline setting or a named compression combo, not an auto-combo modePack.
  • Combo Overrides: compressionOverride is a plain mode string; caching providers are handled by the always-on cache-aware adjustment (there is no selectable cache-aware mode); weights/modePack sit at the top level of combo config.
  • RTK: 55 built-in filters, not 49. Configuration: the routing-combo override dropdown also offers Codex Responses.

Related Issues

Validation

  • Change type: other (docs-only)
  • Focused checks from the golden path: npm run check:docs-all (includes the fabricated-docs gate) — passes
  • npm run lint not applicable to a markdown-only diff; prettier applied
  • Reconciled with the current active release base release/v3.8.52

Every changed passage was verified claim-by-claim against the source, with evidence recorded per claim (file, line, quote).

⚠️ base-red inherited: #15306 (release/v3.8.52 was red before this branch; the inherited failures are not from this change)

Note: the 66 i18n mirrors of this guide wait for the next refresh.

Tests Added Or Updated

  • No production code changed. Docs-only diff, so no tests added.

Coverage Notes

  • No code touched; coverage unaffected.

Reviewer Notes

  • Each bullet above names the source file that pins the new wording, if you want to spot-check.
  • The i18n mirrors under src/i18n (66 locales) are refreshed in bulk and intentionally not touched here.

The Compression Guide's caveman output mode and output-styles passages
described behavior the code does not have. Correct them against the
current sources:

- When to use: the legacy mode is switched by cavemanOutputMode.enabled,
  which replaces the routing-combo config.auto.outputMode example. A
  compression combo's Output Mode toggle and the
  omniroute_set_compression_engine MCP tool's outputMode argument set the
  same switch.
- Back-compat: the mapping to terse-prose applies while outputStyles is
  empty. The block starts with the [OmniRoute Output Styles] marker; the
  text matches the legacy injector in en, pt-BR, es, de, fr, it, ru, id
  and vi, carries one extra space before the boundaries clause in ja and
  zh, and is English for hu, which terse-prose does not translate.
- Boundaries: SHARED_BOUNDARIES keeps code blocks, file paths, commands,
  errors and URLs exact; terse-prose and terse-cjk add identifiers, and
  less-code and ponytail add the SAFETY_BOUNDARIES clause.
- Auto-Clarity: the content bypass runs while the Auto-Clarity Bypass
  toggle is on (the default) and is skipped when it is off. The toggle
  is on the Caveman page's Output Mode card.
- How to enable: the dashboard path uses the sidebar labels (Compression
  Context, Compression Settings).
An accuracy review of the previous commit against the sources found four
sentences that were imprecise:

- The legacy switch takes effect only while compression itself is on
  (the master `enabled` flag, off by default), and a non-empty
  outputStyles selection overrides it. The example now sets both flags,
  and How to enable states the master-switch requirement for all styles.
- "The Terse prose output style injects the same text" read as a
  comparison with the legacy injector; it now says the same block.
- The safety clause less-code and ponytail add can be its translation.
- Turning the Auto-Clarity Bypass toggle off skips the keyword check; it
  does not force injection, which other conditions can still prevent.
A source check of the Compression Guide found statements the code does
not bear out. Correct them against the current sources:

- Caveman Output Mode: requests get the instructions through
  applyOutputStyles(), after chatCore.ts resolves the selection with the
  back-compat shim; outputMode.ts holds the texts, the content bypass and
  the placement helper, and applyCavemanOutputMode() has no production
  caller.
- How it works: quote the English full level ("Respond terse like smart
  caveman. ...") in place of an example sentence found in no
  instruction.
- terse-cjk: the dashboard lists the row by UI locale (zh-CN, zh-TW);
  the injector gates it on the resolved request language.
- How injection works: the instructions/input path also covers an empty
  messages array, and the content bypass runs on a non-empty one.
- Language selection: autoDetect reads the latest user message with text
  and falls back to defaultLanguage, then English.
- Matrix test: locale-gated styles skip the pt-BR requirement, and the
  loss check covers the languages BASELINE_LANGUAGES lists.
- Tool Result Compression: list the five strategies compressToolResult()
  implements (fileContent, grepSearch, shellOutput, json, errorMessage)
  in first-match order, and state that they run as step 1 of the
  aggressive engine with a switch each under aggressive.toolStrategies,
  all on by default.
- Advanced Compression Systems: drop "that work automatically based on
  context"; caveman output mode is opt-in and tool-result compression
  runs only in the aggressive engine.
A claim-by-claim verification of the reworked passages against the sources
surfaced statements the code supports only with qualifiers, and a sweep of
the surrounding sections found contradictions the guide had accumulated.
Correct them:

- Advanced intro: name the codex-responses/omniglyph modes the guide does
  not cover and tie each section to where it actually runs (tool-result
  compression and progressive aging are steps of the aggressive engine,
  cache-aware downgrades aggressive/ultra for caching providers, caveman
  output mode and output styles are opt-in instructions).
- Caveman Output Mode: instructions ask for terse output, they cannot
  guarantee it; the back-compat shim only maps cavemanOutputMode while
  outputStyles is empty; input compression still runs after injection.
- Injection: the idempotency check runs before the content bypass; the
  order-sensitive bypass is a step word followed within 240 characters by
  an action word, not a keyword list; the no-messages path consults
  neither the bypass nor the top-level system field, skips an
  already-marked instructions field as already_applied, and overwrites
  only non-string instructions/input values; a selection that resolves to
  no style is skipped as no_styles.
- Terse CJK: only full/ultra answer in Classical Chinese; hiding the
  settings row does not clear a saved selection.
- Language selection: autoDetect samples only the messages array, so
  Responses bodies fall back to defaultLanguage; the detector returns a
  fixed language set and never defaultLanguage on zero hits; vi is never
  detected; compression combos force languageConfig on and derive
  defaultLanguage from the combo's language packs.
- Style x language matrix: terse-cjk is the only locale-gated style, and
  KNOWN_ENGLISH_ONLY may hold only styles with no translations at all.
- Tool Result Compression: spell out each strategy's trigger (the
  indentation-tolerant code keywords, the path:line: shape that a
  timestamp line also matches, ANSI CSI or "$" + whitespace, the JSON
  start/parse conditions, the case-insensitive error substrings), the
  {...N keys} placeholder for nested arrays, the 14-line floor of the
  error elision marker, and the callers' saved <= 0 guard that keeps the
  original while the fallback summarizer still shortens long tool
  messages.
- Ultra Mode: it is an independent score-based prose pruner with
  structure preservation and an optional SLM tier - it does not include
  Aggressive mode's features, thin code blocks, or binary-search
  truncate.
- Aggressive Mode: tool outputs are truncated or elided, not summarized.
- Cache-Aware: a caching provider alone triggers the downgrade, no
  cache_control markers required; drop the never-consumed
  deterministic-transformations step and add the targetFormat field to
  the example.
- Progressive Aging: document the shipped thresholds (last 2 turns
  verbatim, caveman at distance 3, summarized from distance 4, nothing
  dropped) and that it runs in aggressive mode only, not ultra.
- Stacked Pipeline: compose the numbers from the guide's own math (46%
  Caveman step, ~89% average) and point configuration at the
  stackedPipeline setting or a named compression combo, not an
  auto-combo modePack.
- Combo Overrides: compressionOverride is a plain mode string, and
  caching providers are handled by the always-on cache-aware adjustment
  (there is no selectable cache-aware mode); weights and modePack sit at
  the top level of combo config.
- RTK: 55 built-in filters, not 49. Configuration: the routing-combo
  override dropdown also offers Codex Responses.
@woodsonl
woodsonl requested a review from diegosouzapw as a code owner October 5, 2026 22:10
@diegosouzapw
diegosouzapw merged commit 5a4b681 into diegosouzapw:release/v3.8.52 Oct 6, 2026
44 of 51 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants