Commit Graph
5 Commits
Author SHA1 Message Date
b1f340e0b3 fix(ccr): keep proactive expansion out of the cached prefix (#4300)
## Description

CCR proactive expansion used to append retrieved originals into the
newest
user turn. That turn sits inside the cached prefix when the client's
trailing system message holds the cache breakpoint. The extra text
existed
only in the forwarded body and in the prefix-tracker snapshot; the
client
never resent it.

On the next turn, cache continuity depended on overlay replaying that
injection. When the tracker was gone (proxy restart) or
`confirmed_frozen_count` was 0, overlay declined the larger replay and
rewrote the conversation from the expanded message, from message 0 if
that was the first turn.

This change places the expansion in a new text block immediately after
the
last message-level `cache_control` block and omits that block from the
prefix-tracker snapshot. Existing prefix bytes stay identical, role
alternation is unchanged, and a restart or declined replay costs only
that
turn's uncached injection.

Closes #4287

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- Inject CCR expansion after the last cache breakpoint instead of into
the latest user turn.
- Strip expansion blocks before
`PrefixCacheTracker.update_from_response` on the Anthropic HTTP,
Bedrock, and streaming paths.
- Keep cache-mode skip of the append as-is.
- When the breakpoint block is one of several parallel `tool_result`
blocks, insert the expansion after the whole consecutive `tool_result`
group, so the turn stays `[tool_result, tool_result, text]` instead of
`[tool_result, text, tool_result]`.
- Mark the block the proxy inserts and strip only that exact block from
the tracker snapshot. Client-authored text that happens to use the
expansion tags is no longer removed.
- Raise the `aiohttp` constraint to `>=3.14.4` (CVE-2026-111063,
CVE-2026-111064, GHSA-2g87-pp6c-29x5) and relock; uv resolves aiohttp
3.14.5 and yarl 1.25.1.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy`) on the changed handler
- [x] New tests added for new functionality
- [x] Tests fail on current `main` and pass on this branch

### Test Output

```text
pytest tests/test_proxy_handler_helpers.py tests/test_ccr_expansion_conversation_scope.py \
  tests/test_cache_prefix_overlay.py tests/test_ccr_context_tracker.py \
  tests/test_bedrock_prefix_tracker_wiring.py tests/test_backend_streaming_cache_metrics.py \
  tests/test_proxy_streaming_request_logger.py tests/test_proxy_anthropic_cache_stability.py \
  tests/test_cache_breakpoint_diagnostics.py tests/test_cross_turn_cache_safety.py \
  tests/test_anthropic_ccr_workspace_unbound.py -q
225 passed, 1 skipped

pytest tests scripts/tests -q   (local macOS, offline)
41 failed, 16689 passed, 627 skipped, 2 errors
The same failing set fails identically on unmodified main in this environment
(missing langchain_anthropic / PIL, live-API and UDS/network tests); none are in
the CCR or Anthropic handler suites.

ruff check .            All checks passed!
ruff format --check .   1802 files already formatted
mypy headroom/proxy/handlers/anthropic.py --ignore-missing-imports   Success
uv lock --check         Resolved 251 packages
pip-audit (uv export --extra all): aiohttp findings cleared; newer advisories
  on certifi 2026.1.4 (fix 2026.10.19) and pillow 12.3.0 (fix 13.0.0) also
  fail on main and are not addressed here
```

## Real Behavior Proof

- Environment: Linux, Python 3.12, token mode, CCR proactive expansion
on, FastAPI TestClient against `/v1/messages`.
- Exact command / steps: `pytest
tests/test_ccr_expansion_conversation_scope.py::test_expansion_stays_out_of_the_cached_prefix_and_tracker_snapshot
tests/test_cache_prefix_overlay.py` (TestClient request to
`/v1/messages` with the trailing system message holding `cache_control`,
then overlay with `confirmed_frozen_count=0` as a stand-in for the
restart path).
- Observed result: the client user turn is forwarded unexpanded;
expansion sits after the trailing system's `cache_control`; the tracker
snapshot has no expansion; overlay with `confirmed_frozen_count=0`
replays the unexpanded prefix.
- Not tested: live Anthropic cache_read/cache_creation after a real
proxy restart. Redacted real-restart runtime evidence is still to come
from the author and will be added to this PR; nothing above is from a
live upstream.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: none (not rollout-managed)
- Stable/default behavior changed: expansion placement and tracker
snapshot
- Kill switch / disable path: `HEADROOM_NO_CCR_PROACTIVE_EXPANSION=1` /
`--no-ccr-proactive-expansion`
- Unsafe override required: no
- Qualification impact: none expected; the cached prefix bytes are
unchanged and only the uncached tail gains the expansion block
- Rollback path: revert the commits

## Review Readiness

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

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4300"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

## Demo


![demo](https://raw.githubusercontent.com/mvanhorn/pr-demo-assets/main/headroom/ccr-transient-expansion/demo.gif)

<video
src="https://raw.githubusercontent.com/mvanhorn/pr-demo-assets/main/headroom/ccr-transient-expansion/demo.mp4"
controls width="720"></video>

---------

Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-03 22:46:56 -06:00
gglucassandClaude Fable 5 aebe98954e fix(cache): keep cached-prefix replay after background recompression (#3380)
## Description

Since the non-inflation size bound added in #3052 (shipped 0.36.x), the
Anthropic proxy token path repeatedly busts the provider prompt cache:
the bound declines the cached-prefix replay exactly when background
compression lands a SMALLER form of an already-forwarded message, so the
forwarded bytes change mid-history and the provider cache misses from
the first changed byte. Steady state on a busy session is a
160-210k-token cache re-write every 1-2 requests (measured across a
0.35.0 -> 0.37.0 swap on identical workload: dollar cache-hit rate 90%
-> 52%, billable input $/M up 2.2x; full data in #3379).

Reworked per review (thanks @chopratejas - the direction is yours):
rather than disabling the size bound wholesale, `overlay_cached_prefix`
now takes `confirmed_frozen_count` and splits at that floor.

- Inside the provider-confirmed prefix: replay is unconditional. The
replay source is exactly what the provider hashed, so changing those
bytes can only bust the cache; an "inflating" replay there bills at the
~0.1x cache-read rate and is still the cheaper request.
- Beyond the floor: the size bound arbitrates each turn exactly as on
main - a shrinking replay repairs freeze drift (#1850), an inflating one
is declined so a fresh compression improvement reaches the wire.
- When the provider count collapses (cold cache, TTL lapse) the floor
collapses with it and every accumulated improvement lands at once: the
natural re-baselining that bounds long-session growth (the #3026
direction of travel) by the TTL-lapse cadence instead of pinning
forever.

The #3052 alignment/append-only guards stay enforced unconditionally.

The OpenAI chat path now carries the same floor (reviewer question: is
the root cause live there too?). It is: the tracker is provider-generic
and is fed OpenAI's own `prompt_tokens_details.cached_tokens`, the
forwarded-bytes feedback loop is identical, both handlers compress
through the same ContentRouter, and OpenAI's automatic prompt caching
busts on the first changed byte exactly like Anthropic's. Exposure is
narrower - the token path's `FREEZE_POLICY_REPLAYABLE` already stops
most recompression of already-forwarded messages - but not zero: an
entry evicted from the local byte-replay cache drops out of that freeze,
and cache mode freezes from the tracker only. Remaining callers with no
provider-confirmed count in scope (sidecar, `openai.py:9940`) pass
nothing and keep today's fully size-bounded behavior; `bedrock.py` /
`gemini.py` never call `finalize_turn` at all, tracked in #3391.

Closes #3379

## Type of Change

- [x] 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)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `overlay_cached_prefix` gains keyword-only `confirmed_frozen_count:
int | None = None`: an unconditional-replay floor for the
provider-confirmed prefix; the size bound still governs everything
beyond it, and alignment guards are untouched.
- `finalize_turn` forwards the floor (default `None`, so all existing
callers are unchanged).
- The OpenAI chat call site passes the same floor, snapshotted before
`prepare_turn`'s replayable clamp (that count runs over the LOCAL
byte-replay cache and can exceed what the provider confirmed; a cold
prefix zeroes it, so cold re-baselining matches Anthropic's).
- The Anthropic confirmed-clamp call site stashes the pre-clamp tracker
count (the post-`prepare_turn` min under-floors when the local
byte-replay cache evicted entries) and passes it; the stash defaults to
0 on paths that never compute a tracker count (backpressure).
- Tests: floor replays a recompressed confirmed prefix; improvement
beyond the floor lands while the confirmed region replays;
originals-drift beyond the floor is still repaired when the replay
shrinks; alignment guards unaffected by the floor; block-append within
the floor; `finalize_turn` pass-through; the reviewer-requested
multi-turn harness test - a background improvement to an
already-forwarded message never busts the warm cache across 8 turns and
lands on the first cold turn; the reviewer-requested growth bound -
forwarded size grows by only its own delta each warm turn and the first
cold turn re-baselines to exactly the fresh pipeline's output; and an
end-to-end OpenAI chat test asserting the provider-confirmed prefix is
replayed even when the replay inflates (fails without the new argument).

## Testing

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

### Test Output

```text
$ uv run --frozen --extra dev pytest tests/test_cache_prefix_overlay.py tests/test_session_engine.py tests/test_cross_turn_cache_safety.py tests/test_cache_control_move_bust.py -q
============================== 58 passed in 0.44s ==============================
$ uvx ruff check headroom/cache/prefix_tracker.py headroom/proxy/session_engine.py headroom/proxy/handlers/anthropic.py tests/test_cache_prefix_overlay.py tests/test_session_engine.py tests/test_cross_turn_cache_safety.py
All checks passed!
$ uv run --frozen --extra dev mypy headroom/cache/prefix_tracker.py headroom/proxy/session_engine.py
Success: no issues found in 2 source files
```

## Real Behavior Proof

- Environment: macOS 15 (arm64), Python 3.12; regression measured on the
released headroom-ai 0.37.0 under real Claude Code traffic through
`headroom proxy` (token mode); this branch validated with the repo test
suite.
- Exact command / steps: diffed per-request PERF logs across a 0.35.0 ->
0.37.0 swap on the same machine and workload (sequences and aggregates
in #3379); then ran the pytest/ruff/mypy commands above on this branch.
A deployment carrying the unconditional-replay behavior on the confirmed
prefix restored the healthy pattern live: the broken wheel capped cached
reads at 157k across 32 large requests (prefix perpetually re-written)
while the patched deployment accumulated to 305k cached reads within 15
minutes.
- Observed result: 58 passed including the new multi-turn harness test;
on stock 0.37.0 every background-compression completion produced a
cache_read collapse to the ~7.7k tools+system head plus a 160-210k
cache_write.
- Not tested: a live OpenAI `cached_tokens` comparison for the OpenAI
half (the Anthropic measurement is what #3379 carries; the OpenAI change
is argued from shared mechanism plus an end-to-end handler test, not
from its own dollar data). A live provider run of this exact branch (the
wheel comparison plus the live patched-deployment measurement isolate
the bound as the trigger; the unit and multi-turn regressions reproduce
decline and fix deterministically). `mypy headroom` was run only on the
two touched modules, not the whole package.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: Stable.
- Stable/default behavior changed: On the Anthropic proxy
confirmed-clamp path and the OpenAI chat path, both of which now replay
the provider-confirmed prefix unconditionally (the pre-0.36 posture)
while keeping the size bound beyond the confirmed floor. The overlay's
default and every other caller keep the fully size-bounded behavior.
- Kill switch / disable path: remove the `confirmed_frozen_count=`
argument at the two call sites (anthropic.py, openai.py chat); the
parameter defaults to `None`.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert the commits; the parameter is additive and
default-preserving.

## 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
- [x] 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)

Not applicable.

## Additional Notes

Lineage for review: #1850 made freeze forward the cached prefix
byte-identical, #3052 added alignment guards plus the size bound after
#3026's misalignment blowup, #3271 unified both modes on the session
engine. The first cut of this PR disabled the bound on the
confirmed-clamp path wholesale; the reviewed rework scopes unconditional
replay to the provider-confirmed prefix, which additionally gives
cold-lapse re-baselining (improvements land whenever the floor
collapses), addressing the growth analysis raised in review. Economics
discussion in the review thread.

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

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-09-02 16:50:58 +05:30
Rod Boev c16be9bbbe fix(proxy/anthropic): don't replay recorded prefix over live history (#3026) (#3052)
## Description

A Claude Code session that reads a large tool result through `headroom
proxy` can fail on turn 2 with Anthropic's `400 prompt_too_long`. The
reporter's controlled comparison completed eight turns through 0.33.0
with 187,986 input tokens, while 0.35.0 failed after five requests with
753,077 input tokens. The local regression uses an actual prior
optimized request to populate tracker state, then a decision-false
bypass turn with Claude-shaped tool-result content. The old
unconditional replay path substitutes the compressed prefix; the
eligibility gate preserves the client's outbound body without claiming a
live provider reproduction.

The Anthropic `/v1/messages` route computes whether a request should be
compressed, but cached-prefix replay currently runs outside that
decision. The replay helper also derives its prefix length from the
original message list and applies that index to the optimized list
without proving the two lists still align. A stale forwarded prefix can
therefore be grafted onto the wrong positions and enlarge later
requests.

This change limits replay to requests whose existing compression
decision permits it and whose pre-upstream backpressure path is
inactive. It also makes `overlay_cached_prefix()` decline misaligned or
inflating candidates while preserving normal append-only replay.

Reported by @itsumonotakumi, whose controlled comparison isolated the
failure from compression, headers, one-request serialization, memory,
code graph, and CCR.

Closes #3026

## Type of Change

- [x] 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)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Gate Anthropic cached-prefix replay on the existing
`CompressionDecision.should_compress` result and the existing
pre-upstream backpressure state.
- Require positional alignment between optimized and original message
arrays before replay.
- Reject replay candidates that would serialize larger than the current
optimized messages.
- Add focused handler coverage for the decision-false tool-result
regression, bypass and backpressure paths, and outbound optimize-on
preservation.
- Add direct unit coverage for positional mismatch, no-inflation, and
JSON sizing-failure bailouts.
- Update the moved-cache-control and pure-block-append regression
fixtures to keep the no-inflation contract explicit.
- Run the unchanged OpenAI cache-stability preservation proof; no OpenAI
production code was edited.

## Testing

- [x] Unit tests pass (153 focused proxy, helper, cache-control,
block-append, cross-turn, byte-faithful, Anthropic, OpenAI, and
backpressure tests)
- [x] Linting passes (Ruff check and format validation on the seven
changed repository files)
- [ ] Type checking passes (`uv run mypy headroom`)
- [x] New tests added for new functionality when applicable
- [x] Manual testing performed with the in-process proxy and local stub
upstream

### Test Output

```text
python -m pytest tests/test_proxy/test_anthropic_no_optimize_history_passthrough.py tests/test_cache_prefix_overlay.py tests/test_cross_turn_cache_safety.py tests/test_cache_control_move_bust.py tests/test_proxy_byte_faithful_forwarding.py tests/test_proxy_anthropic_cache_stability.py tests/test_anthropic_pre_upstream_backpressure.py -q
python -m pytest tests/test_proxy_openai_cache_stability.py -q
python -m pytest tests/test_issue_2671_block_growth_cache.py::test_pure_append_replays_forwarded_blocks_and_advances_breakpoint -q
153 passed across focused invocations, exit code 0
optimize_off turn2_message_count=3 marker_count=1 outbound_compact_utf8_bytes=2293 client_compact_utf8_bytes=2293
optimize_on turn2_message_count=3 client_message_count=3 marker_count=0 outbound_compact_utf8_bytes=171 client_compact_utf8_bytes=182
python -m ruff check headroom/proxy/handlers/anthropic.py headroom/cache/prefix_tracker.py tests/test_proxy/test_anthropic_no_optimize_history_passthrough.py tests/test_cache_prefix_overlay.py tests/test_cache_control_move_bust.py tests/test_issue_2671_block_growth_cache.py tests/test_proxy_openai_cache_stability.py
All checks passed!, exit code 0

python -m ruff format headroom/proxy/handlers/anthropic.py headroom/cache/prefix_tracker.py tests/test_proxy/test_anthropic_no_optimize_history_passthrough.py tests/test_cache_prefix_overlay.py tests/test_cache_control_move_bust.py tests/test_issue_2671_block_growth_cache.py tests/test_proxy_openai_cache_stability.py --check
7 files already formatted, exit code 0

git diff --check
clean, exit code 0
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12 via `uv`, real Headroom proxy app
with a local stub Anthropic upstream
- Exact command / steps: send an actual optimize-on first request
through the in-process proxy with a deterministic production-pipeline
seam, then send a decision-false bypass turn containing a large
Claude-shaped `tool_result` with moved `cache_control`; separately send
an aligned optimize-on turn with a new suffix
- Observed result: the exact base checkout fails with `AssertionError:
assert 'compressed-tool-result' == 'large-tool-result-marker ...'`; the
guarded path passes with the client marker present once and outbound
compact JSON no larger than the client body. The optimize-on
preservation run records `optimize_on turn2_message_count=3
client_message_count=3 marker_count=0 outbound_compact_utf8_bytes=171
client_compact_utf8_bytes=182`, proving the actual compressed prefix is
outbound before the new suffix without turn-2 growth.
- Not tested: live Claude Code session against api.anthropic.com on this
host

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: cached-prefix replay now follows the
existing compression and backpressure decision and rejects misaligned or
inflating candidates.
- Kill switch / disable path: no new switch; the existing optimize and
bypass controls remain available.
- Unsafe override required: none.
- Qualification impact: none.
- Rollback path: revert the implementation commit.

## 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
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [x] 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

## Additional Notes

`CHANGELOG.md` is not modified because Headroom's release automation
generates it from conventional commits.

This change does not add a context-limit guard or alter compression,
streaming tracker provenance, outbound-body selection, OpenAI behavior,
or provider limits. Local tests prove request-body ownership and replay
bounds. The reporter's live Claude Code completion and Anthropic token
acceptance remain external to this local proof.
2026-08-17 15:02:18 -07:00
Tejas Chopra 7c2f0ea079 feat(cache): provider-agnostic cache-mode delta + cc-agnostic prefix comparison (#1868)
## Description

<!-- Briefly explain the change and why it is needed. -->

Closes #

## 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)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- 

## Testing

<!-- Check what you actually ran, then paste the real command output
below. -->

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

### Test Output

```text
# Paste relevant command output or artifact links here
```

## Real Behavior Proof

- Environment:
- Exact command / steps:
- Observed result:
- Not tested:

## Review Readiness

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

## Checklist

- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

## Screenshots (if applicable)

Add screenshots to help explain your changes.

## Additional Notes

<!-- Mention any N/A checklist items, tradeoffs, follow-ups, or
maintainer context. -->
2026-07-08 13:29:35 -07:00
Tejas Chopra 248ae0f3e0 fix(proxy): freeze must forward cached (compressed) prefix byte-identical — stop token-mode cache busting (#1850)
The freeze path (both providers) emits the agent's ORIGINAL bytes for a
frozen message, but the provider cached whatever we FORWARDED last turn
(the compressed form). Forwarding original then mismatches the cached
prefix and busts it from that point — re-creating the whole suffix.
Measured on a real SWE-bench run: 100% of attributed misses were
prefix_change, ~56% of ALL cache-writes were bust-induced (2.8M tokens),
driving cache_create +150% and cost +41% vs baseline.

Cache mode already avoided this via _extract_cache_stable_delta (replay
the previously-forwarded prefix, compress only the delta). Token mode
called apply(frozen_count) directly, which forwards original for the
frozen region.

Fix: add a shared, provider-agnostic overlay_cached_prefix() that
replays the previously-forwarded (cached, compressed) prefix
byte-identical, append-only guarded and idempotent, and apply it in BOTH
the Anthropic and OpenAI handlers right before forwarding. This makes
freezing byte-identical in every mode, so the only remaining difference
between "token" and "cache" mode is how large a mutable
(still-compressible) tail each leaves — not whether the frozen prefix
busts the cache.

Tests:
- test_cache_prefix_overlay.py: the helper (replay, append-only guard,
idempotence).
- test_cross_turn_cache_safety.py: the invariant that was missing —
drive the REAL tracker + freeze + overlay over multiple append-only
turns against a simulated provider prefix cache and assert the forwarded
prefix stays byte-identical turn-over-turn. Load-bearing: it fails
(detects the bust) without the overlay.

## Description

<!-- Briefly explain the change and why it is needed. -->

Closes #

## 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)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- 

## Testing

<!-- Check what you actually ran, then paste the real command output
below. -->

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

### Test Output

```text
# Paste relevant command output or artifact links here
```

## Real Behavior Proof

- Environment:
- Exact command / steps:
- Observed result:
- Not tested:

## Review Readiness

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

## Checklist

- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

## Screenshots (if applicable)

Add screenshots to help explain your changes.

## Additional Notes

<!-- Mention any N/A checklist items, tradeoffs, follow-ups, or
maintainer context. -->
2026-07-06 14:54:39 -07:00