docs(transforms): correct stale unit-result-cache placeholder comments (#2506)

## Description

Two comments still describe the unit-result cache as an unbuilt
placeholder, but the cache has since been implemented (the OpenAI
Responses handler's `_openai_responses_unit_result_cache`: SHA-256 unit
key, bounded LRU, in-flight dedup, and `cache_hit` marking via
`replace(router_result, cache_hit=True)`).

- `transforms/compression_units.py` — the `UNIT_REASON_CATEGORIES` block
said `cache_hit` was "placeholder; not currently wired into the unit
path — see follow-up". No code path produces a `cache_hit` *reason
category* today; reuse is caller-level and surfaced on
`RouterCompressionResult.cache_hit`. The comment now says exactly that.
- `transforms/content_router.py` — the
`RouterCompressionResult.cache_hit` docstring claimed the flag is "False
in practice — placeholder for the cache-wire-up follow-up". It is set in
practice by the Responses handler on cached-unit reuse; `compress()`
itself still never touches the router-internal two-tier cache (only
`apply()` does). Docstring updated to match.

Found while scoping a "wire the unit result cache" contribution that
turned out to already exist; these notes were what made it look missing.

Closes #N/A (no tracking issue; comments-only correction)

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Rewrote the `cache_hit` entry in the `UNIT_REASON_CATEGORIES` comment
block (`headroom/transforms/compression_units.py`) to state that cached
unit reuse is caller-level and never produces this reason category.
- Rewrote the `cache_hit` attribute docstring on
`RouterCompressionResult` (`headroom/transforms/content_router.py`) to
describe where the flag is actually set.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
$ uv run --frozen --extra dev pytest tests/test_transforms/test_content_router.py
============================= 59 passed in 11.31s ==============================

$ uvx ruff check .
All checks passed!

$ uvx ruff format --check .
1331 files already formatted

$ uv run --frozen --extra dev mypy headroom/transforms/compression_units.py headroom/transforms/content_router.py
Success: no issues found in 2 source files
```

## Real Behavior Proof

- Environment: macOS 15 (arm64), Python 3.12, uv-managed venv from
`uv.lock`
- Exact command / steps: see Test Output above; comments/docstrings
only, no executable statements changed
- Observed result: targeted tests, ruff, and mypy pass; `git diff`
touches only comment/docstring lines
- Not tested: full test suite and full-repo mypy (pytest and mypy were
scoped to the touched modules — no executable code changed)

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A — no user-visible surface.

## Additional Notes

"New tests added" is unchecked because the change is comments/docstrings
only; there is no behavior to test. If a tracking issue for the original
cache-wire-up follow-up exists, happy to reference it in place of the
N/A above.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

headroom/transforms/compression_units.py

@@ -52,8 +52,10 @@ class CompressionUnit:
 # - compressor_noop:   router returned identical bytes (no compression possible)
 # - already_compressed: input already carried a CCR retrieval marker
 # - rejected_not_smaller: compressor produced output >= input tokens
-# - cache_hit:         result returned from result_cache (placeholder; not
-#                      currently wired into the unit path — see follow-up)
+# - cache_hit:         reserved; cached unit reuse is caller-level (the OpenAI
+#                      Responses handler's unit-result cache) and is surfaced
+#                      via RouterCompressionResult.cache_hit, not as a reason
+#                      here — no code path produces this category today
 UNIT_REASON_CATEGORIES = {
     None: "applied",
     "protected_user_message": "protected_role",

headroom/transforms/content_router.py

@@ -1394,11 +1394,12 @@ class RouterCompressionResult:
             LOG fallback chain it's three. Lets log readers see *how*
             we got to the final compressor without parsing the
             decision_reason string.
-        cache_hit: True when this result came from the router's
-            result_cache (no fresh compression ran). Currently the
-            single-content compress() path doesn't populate the cache,
-            so this is False in practice — placeholder for the
-            cache-wire-up follow-up.
+        cache_hit: True when this result was reused from a cache
+            instead of a fresh compression run. compress() itself
+            never sets this (only apply() has the router-internal
+            two-tier cache); it is set by callers that cache unit
+            results — e.g. the OpenAI Responses handler marks reused
+            units via ``replace(router_result, cache_hit=True)``.
     """
 
     compressed: str