akadmin/headroom
1
0
Fork 0
mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
2696 commits 410 branches 169 tags 142 MiB
Commit graph

6 commits

Author SHA1 Message Date
AxelRay
ef7e07e0f5
fix(policy): price net-cost mutations with the 1h cache-write tier (#2780) 
## Description

This fixes the net-cost mutation gate for requests using Anthropic's
1-hour prompt-cache TTL.

The gate previously hardcoded the 5-minute cache-write multiplier of
1.25x. A 1-hour cache write costs 2.0x, so the old calculation
understated the true write penalty and could incorrectly recommend
mutation for 1-hour clients.

Closes #2773

## 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

- Added TTL-aware cache-write multiplier selection for 5-minute and
1-hour tiers.
- Threaded the resolved TTL through the content router and compression
policy helpers.
- Preserved the existing 5-minute behavior as the default.
- Added Python and Rust regression coverage for the 1-hour tier.
- Retuned the netcost gate fixtures so the 1-hour write tier flips the
decision in the full ContentRouter path.
- Did not edit CHANGELOG.md.

## 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
pytest tests/test_compression_policy.py -q
20 passed

cargo test -p headroom-core --lib compression_policy -- --nocapture
14 passed

pytest tests/test_netcost_gate.py -q
27 passed

Ruff checks and formatting passed.
git diff --check passed.
```

## Real Behavior Proof

- Environment: Linux x86_64 contributor checkout with Python and Rust
test environments.
- Exact command / steps:
  - Ran the Python compression policy test suite.
  - Ran the Rust compression policy unit tests.
- Ran the netcost gate suite, including the 1-hour env and
request-marker cases.
- Exercised the new 1-hour TTL golden case alongside the existing
5-minute cases.
- Observed result: The 1-hour case uses the 2.0x write multiplier and
skips the same candidate that still mutates under 5-minute pricing.
Existing 5-minute behavior remains covered and passing.
- Not tested: A live Anthropic request through the proxy and production
traffic.

## 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
- [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 for this backend policy fix.

## Additional Notes

Ready for review. CI is green on the current tip.
 2026-08-16 15:09:50 -07:00
Tejas Chopra
f03cc6d88b
fix(router): stop counting an image's base64 payload as suffix tokens (#2778) 
## Description

`_netcost_message_tokens` walked block-list content itself and fell back
to `str(block)` for anything that wasn't `text` or `tool_result` — on
the stated assumption that such blocks *"rarely dominate a suffix"*. An
`image` block is the exception that breaks it: `str()` embeds the whole
base64 payload.

```text
                     counted     real     over
512x512 PNG           20,034      349      57x
1092x1092 screenshot 100,034    1,589      63x
1568x1568            233,367    1,600     146x
```

**Why this changes behaviour, not just a number.** S is the cache-bust
cost — the tokens re-written if message *j* is mutated. `apply()` builds
it as a running suffix sum:

```python
for j in range(num_messages - 1, -1, -1):
    netcost_suffix_tokens[j] = netcost_suffix_tokens[j + 1] + _netcost_message_tokens(...)
```

So one image inflates S for **every message before it**, and the
break-even gate then declines to compress any of them. A single
screenshot could switch off net-cost-gated compression for the whole
earlier conversation — and screenshots are routine in agent sessions.

## Type of Change

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

## Changes Made

Delegate block-list content to `tokenizers.base.count_content_blocks`,
deleting the local walk. That counter already guards exactly this case —
its comment reads *"1MB image = ~330K fake tokens without this"* — so
this walk simply predated it.

Beyond the raw fix, this removes a **second pricing rule**: the gate now
values images the same way the tokenizer that computes
`tokens_before`/`tokens_after` does (a flat 1600, "max after
auto-resize"). Pricing images one way for the gate and another for the
savings math is the same class of problem as #2761.

Verified byte-identical on the shapes the old walk handled correctly:

```text
                  old walk   canonical
text only              101         101
tool_result str         81          81
tool_result list        61          61
image only         100,034       1,600
mixed              100,036       1,602
```

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check` + `ruff format`)
- [x] Type checking passes (`mypy`)
- [x] New tests added for new functionality

### Test Output

```text
$ pytest tests/test_netcost_suffix_image_tokens.py -q
8 passed

$ git stash push headroom/ && pytest tests/test_netcost_suffix_image_tokens.py -q
4 failed, 4 passed
# the 4 failures are the payload-scaling assertions; the 4 passes are the
# text/tool_result/string shapes, included to prove delegation is behaviour-preserving
```

All netcost + content-router suites:

```text
$ pytest tests/test_netcost_gate.py tests/test_content_router_*.py \
         tests/test_transforms_content_router.py tests/test_netcost_suffix_image_tokens.py -q
126 passed
```

```text
$ ruff check headroom/transforms/content_router.py tests/...   All checks passed!
$ mypy headroom/transforms/content_router.py                   no new errors
```

Deferring the full suite to CI — no maturin/Rust core in this
environment.

## One existing test rewritten — please look at this bit


`test_netcost_gate.py::TestNetCostHelpers::test_message_tokens_block_list_beats_repr`
fails under the fix, and I want to be explicit that I changed a test
rather than bury it.

It built its image block as `{"type": "image", "source": {"data": "x" *
500}}`. A 500-char stub is **cheaper than a single image's real token
cost**, so `str()` over it looked harmless (~130 tokens) and its
assertion `abs(helper - text_only) < text_only * 0.5` held. That
unrepresentative fixture is precisely why the payload-scaling bug
survived — the test named "beats repr" was passing on the one payload
size where repr happens not to be catastrophic.

Rewritten to use a realistic 200KB payload and to assert what actually
matters:

```python
assert helper >= text_only                    # text still counted in full
assert helper - text_only <= 2000             # image cost is bounded, not payload-scaled
assert helper < count_text(str(content)) / 10  # ...and far below repr
```

I checked this both ways, so it is a real test and not a rubber stamp:

```text
old test + fixed code  -> FAILS   (it was pinning the defect)
new test + main        -> FAILS   (it catches the real bug)
new test + fixed code  -> passes
```

## Known limitation

The canonical estimate is a flat 1600 per image regardless of
dimensions, so a small icon is now over-charged (~1600 vs ~13 real)
where repr would have charged ~200. I kept the flat constant
deliberately: it is the value every other counter in the codebase uses,
and introducing a third rule here to shave small-icon cost would
recreate the inconsistency this PR removes. The error is bounded at 1600
tokens and biases the gate conservative, versus an unbounded 100K+ error
before.
 2026-08-04 11:31:52 -07:00
Focused Instability
fe4f9ee478
feat(policy): decay P_alive from idle time near cache TTL (#856 P3b) (#1028) 
## Description

#856 P3b (umbrella #904), the idle-timer-compaction increment after P2
(#905), P2b (#944), and P3a (#1015), all merged.

Anthropic prompt-cache entries live in a ~5-minute TTL tier (the basis
for the 1.25× write multiplier). As a session goes idle the cached
suffix approaches lapse, so **P_alive** — the probability the cache
still survives to the next turn — decays toward 0. When P_alive → 0 the
net-cost penalty term `P_alive·(w−r)·(S+ΔT)` vanishes and a deep edit
near lapse is free to make: the suffix is about to be rebuilt cold
regardless. P2/P3a fed the break-even gate a **static**
`HEADROOM_NET_COST_P_ALIVE` constant; this derives P_alive from an idle
signal when one is available.

Flag-gated under `HEADROOM_NET_COST_POLICY` (the same flag as
P2/P2b/P3a), default **off**.

## Type of Change

- [x] New feature (non-breaking change which adds functionality)
- [ ] Bug fix
- [ ] Breaking change
- [ ] Documentation

## Changes Made

- `ContentRouter.apply`: reads an optional `idle_seconds` kwarg and
derives `P_alive = max(0, 1 − idle_s / ttl)` **once per request** (idle
is a per-request property, like `frozen_message_count`), passing it to
the gate as `p_alive_override`. Absent/malformed `idle_seconds` → `None`
→ the P2 env-constant path is preserved exactly.
- `ContentRouter._net_cost_allows`: new `p_alive_override` param. When
set it replaces the `HEADROOM_NET_COST_P_ALIVE` constant (clamped to
[0,1]); otherwise unchanged. An admit made under a decayed (`< 1.0`)
idle P_alive emits the `router:netcost_idle_compaction` marker and the
`netcost_idle_admitted` counter (independent of the P3a batch marker;
both may apply).
- Cache TTL: module default 300s (Anthropic tier), overridable via
`HEADROOM_NET_COST_CACHE_TTL_SECONDS`, with malformed/non-positive
guards. Explicitly **distinct** from
`PrefixFreezeConfig.session_ttl_seconds` (tracker cleanup, 600s).
- `PrefixCacheTracker.seconds_since_activity()`: exposes the idle signal
for the proxy handlers to plumb (see Additional Notes).

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] New tests added for new functionality

### Test Output

```text
$ pytest tests/test_netcost_gate.py -q
25 passed in 2.03s

$ pytest tests/ -k "content_router or netcost or router or prefix_tracker or prefix" -q
245 passed, 8 skipped, 6252 deselected, 1 warning in 24.47s

$ ruff check headroom/transforms/content_router.py headroom/cache/prefix_tracker.py tests/test_netcost_gate.py
All checks passed!

$ ruff format --check headroom/transforms/content_router.py headroom/cache/prefix_tracker.py tests/test_netcost_gate.py
3 files already formatted

$ mypy headroom/transforms/content_router.py headroom/cache/prefix_tracker.py
Success: no issues found in 2 source files
```

## Real Behavior Proof

- Environment: local macOS, repo .venv, Python 3.11.9, gpt-4o tokenizer
fixture
- Exact command / steps: drive `ContentRouter.apply()` on the P2
"blocked" baseline (a modest tool-dump shave, ΔT≈5K, under a ~120K-token
cached suffix — rejected at the default P_alive=1.0), varying only
`idle_seconds`.
- Observed result: `idle_seconds=295` (TTL 300) → P_alive≈0.017, penalty
collapses, the edit is admitted and `router:netcost_idle_compaction` is
emitted; `idle_seconds=0` → P_alive=1.0, byte-identical to the constant
baseline (still blocked, `netcost:skip:` emitted, no idle marker);
absent/malformed `idle_seconds` → env-constant path (blocked);
`HEADROOM_NET_COST_CACHE_TTL_SECONDS=60` with `idle_seconds=59` → unlock
(custom TTL controls the decay).
- Not tested: live proxy traffic — deferred to the default-on milestone
per #904 (ships default-off to gather telemetry first).

## Review Readiness

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

## Additional Notes

**Proxy wiring is a deliberate follow-up**, mirroring how P2 shipped
P_alive as an unplumbed constant and gathered telemetry before
default-on. The gate already honors `idle_seconds` via kwarg and
`PrefixCacheTracker.seconds_since_activity()` exposes the value; the
remaining step is for the provider handlers (`handlers/anthropic.py`,
`handlers/openai.py`) to pass it alongside the existing
`frozen_message_count` kwarg (`pipeline.apply` already forwards
`**kwargs` to `transform.apply`, so no pipeline change is needed). One
wiring caveat is documented on `seconds_since_activity()`:
`SessionTrackerStore.get_or_create` refreshes `_last_activity` on
access, so the handler must read idle before fetching the tracker for
the current request. Kept out of this PR for reviewability and because
it touches ~10 call sites across both providers.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
 2026-06-18 11:15:40 -05:00
Focused Instability
c2e52fe743
feat(policy): batch deep edits through one cache-bust (#856 P3a) (#1015) 
## Description

#856 P3a (umbrella #904), stacked on the now-merged P2 (#905) and P2b
(#944).

A net-cost mutation at depth K already busts the provider's cached
suffix after K. Every *later* candidate at a deeper slot therefore rides
that same cache invalidation for free — mutating it adds no incremental
cache-bust cost. Today the P2 break-even gate re-charges each candidate
the full invalidated suffix S independently, so a batch of legitimate
deep edits is under-admitted: only the first pays for the bust, yet each
is billed as if it paid alone.

This adds a batch-reclaim floor to the net-cost gate so that once one
net-positive deep edit is admitted at slot K, candidates at slot > K are
admitted on the write/read economics alone (S charged as 0). Flag-gated
under `HEADROOM_NET_COST_POLICY` (the same flag as P2/P2b), default
**off** — telemetry-first before any default-on.

## Type of Change

- [x] New feature (non-breaking change which adds functionality)
- [ ] Bug fix
- [ ] Breaking change
- [ ] Documentation

## Changes Made

- `ContentRouter._net_cost_allows`: new `batch_state` param. When the
candidate sits strictly deeper than `batch_state["floor"]`, S is charged
as 0 via the *same* `net_mutation_gain` formula (conservative — never
admits a mutation the real economics would reject). Full-S admits
open/lower the floor; batch admits never lower it, so a slot only ever
rides free behind a genuinely mutated shallower slot.
- `ContentRouter.apply`: shared per-request `netcost_batch_state` wired
into both gate call sites (cached-result path and parallel-merge path).
- Telemetry: every batch admission emits the
`router:netcost_batch_admit` transform marker and the
`netcost_batch_admitted` route counter; added to the routing summary log
line.
- Tests: 5 new cases in `tests/test_netcost_gate.py`
(`TestNetCostBatchReclaim`).

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] New tests added for new functionality

### Test Output

```text
$ pytest tests/test_netcost_gate.py -q
20 passed in 1.46s

$ pytest tests/ -k "content_router or netcost or router" -q
142 passed, 8 skipped, 6342 deselected, 1 warning in 22.54s

$ ruff check headroom/transforms/content_router.py tests/test_netcost_gate.py
All checks passed!

$ ruff format --check headroom/transforms/content_router.py tests/test_netcost_gate.py
2 files already formatted

$ mypy headroom/transforms/content_router.py
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: local macOS, repo .venv, Python 3.11.9, gpt-4o tokenizer
fixture
- Exact command / steps: drive `ContentRouter.apply()` on a 5-message
conversation — a huge compressible tool dump at slot 1 (ΔT≈34K) and a
modest dump at slot 2 (ΔT≈5K) followed by a ~12K-token suffix, so slot
2's own break-even S blocks it. Run with `HEADROOM_NET_COST_POLICY=1`,
once with a non-compressible slot 1 (no shallower admit, control) and
once with the slot-1 dump intact (opens the floor).
- Observed result: control → `slot2_compressed=False batch_markers=0
skip_markers=1` (slot 2 correctly blocked on its own S, no floor
opened); floor opened → `slot2_compressed=True batch_markers=1
skip_markers=0` (slot 2 rides slot 1's cache-bust for free,
`router:netcost_batch_admit` emitted). Flag absent → no
`router:netcost_batch_admit` marker ever.
- Not tested: live proxy traffic / real dashboard validation — deferred
to the default-on milestone per #904 (ships default-off precisely to
gather telemetry first). Known limitation logged for follow-up: in a
*warm-cache* request a deep cache-hit slot is gated in pass 1 before a
shallower cache-miss slot can lower the floor in pass 3, so the batch
win can no-op there (never a wrong admit — strictly conservative).

## Review Readiness

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

## Additional Notes

Charging S=0 through the existing formula (rather than blanket-admitting
on `ΔT > 0`) keeps the decision conservative under non-default env
tunables (`HEADROOM_NET_COST_EXPECTED_READS`,
`HEADROOM_NET_COST_P_ALIVE`). P3b will be a separate PR after this
review.

Note: the failing `test` / `test-extras` checks are a **pre-existing
regression on `main`** in `tests/test_cache/test_dynamic_detector.py`
(unrelated to this PR, which only touches `content_router.py`). Fix
tracked in a separate PR; this branch will go green once that lands and
this is rebased.
 2026-06-15 23:30:23 -05:00
Focused Instability
90bdc676fa
feat(policy): unlock formula-positive deep edits through the frozen floor (#856 P2b) (#944) 
## Description

Part of #904 — the **P2b (Subscription deep-unlock)** item from #856's
phased plan. Builds directly on the P2 gate (#905, now merged); rebased
onto `main` so the diff below is P2b-only
(`headroom/transforms/content_router.py` +39/−5,
`tests/test_netcost_gate.py` +72).

The P2 net-cost gate only governs mutations the router already considers
— messages **above** the `frozen_message_count` floor. The floor itself
stays a hard binary skip: anything in the provider's prefix cache is
left byte-identical no matter how compressible. That leaves the
deep-edit half of #856 on the table — e.g. a ~60K-token stale tool dump
sitting in the frozen prefix with only a small cached suffix after it,
which pays for its cache-bust many times over.

With `HEADROOM_NET_COST_POLICY=1` (default **off**), a
**string-content** frozen message now falls through to the normal
candidate pipeline instead of being skipped at the floor. The existing
P2 break-even gate then decides per candidate: **S** is the full
invalidated suffix after the slot, so the deep edit proceeds only when
`ΔT·(w+r(R−1))` still beats the cache-bust penalty. Flag off restores
byte-identical current behavior.

## Type of Change

- [x] New feature (non-breaking change which adds functionality)

## Changes Made

- Open the `frozen_message_count` floor in `ContentRouter` under
`HEADROOM_NET_COST_POLICY=1`: string-content frozen messages route to
the existing P2 gate instead of an unconditional skip; the gate's
whole-suffix S already prices the cache-bust correctly for frozen slots.
- **Scope guard:** block-list and non-string frozen content stay frozen
— the gate is wired into the string and parallel-merge paths only, and
the per-block `cache_control` contract in `_process_content_blocks` is
not net-cost aware, so opening them here would mutate cached blocks
ungated.
- Emit a `router:netcost_frozen_unlock` transform marker +
`netcost_frozen_unlocked` route count on actual unlocks, and
`netcost_frozen_considered` for every frozen string slot routed to the
gate — telemetry to validate the flag before any default-on.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] New tests added for new functionality
- [x] New and existing unit tests pass locally with my changes

### Test Output

```text
$ pytest tests/test_netcost_gate.py -q
15 passed in 0.96s

$ pytest tests/ -k "content_router or netcost or router" -q
137 passed, 8 skipped, 6251 deselected in 20.89s

$ ruff check headroom/transforms/content_router.py tests/test_netcost_gate.py
All checks passed!
$ ruff format --check headroom/transforms/content_router.py tests/test_netcost_gate.py
2 files already formatted
```

## Real Behavior Proof

- Environment: local macOS, repo .venv, Python 3.11.9, gpt-4o tokenizer
fixture
- Exact command / steps: drive `ContentRouter.apply()` with a 4-message
conversation whose index-1 `tool` message (61,584 tokens) sits inside
the frozen prefix (`frozen_message_count=2`), tiny suffix after; run
once with the flag absent and once with `HEADROOM_NET_COST_POLICY=1`
- Observed result: flag **off** → frozen tool dump left untouched, no
unlock marker; flag **on** → dump compressed (`router:smart_crusher`)
and `router:netcost_frozen_unlock` emitted, while the surrounding user
messages stay `router:protected:user_message`. The 4 new unit tests also
confirm a modest-shave / 40K-suffix frozen slot is *kept* frozen (gate
runs, `netcost:skip:` emitted, no unlock) and block-list frozen content
stays frozen.
- Not tested: live proxy traffic / real dashboard validation — deferred
to the default-on milestone per #904 (ships default-off precisely to
gather that telemetry first).

## Review Readiness

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

## Additional Notes

Net-cost economics are unchanged from P2 — this only widens *which
slots* the same gate may consider. The Subscription deep-unlock story
from #856 is realized without a mode branch: the floor is mode-agnostic
in `ContentRouter`, and the formula is the correct arbiter regardless of
auth mode. Remaining #904 items: P3a (batch deep edits) and P3b
(idle-timer compaction).
 2026-06-15 11:06:28 -05:00
Focused Instability
553ade4ec6
feat(policy): consume net-cost mutation gate in ContentRouter (#856 P2) (#905) 
## Description

Fixes #907. Part of #904 — the **P2 (consume, flag-gated)** item from
#856's phased plan. (#903, which this was stacked on, has merged; this
is now a clean diff.)

`HEADROOM_NET_COST_POLICY=1` (default **off** — flag absent restores
byte-identical current behavior) routes every ContentRouter mutation
candidate through `CompressionPolicy.net_mutation_gain` before
compression is applied, at both decision sites: the result-cache-hit
path and the fresh-compression merge (pass 3).

v1 estimators (as specced in #856): **ΔT** exact (compressed form
already computed); **S** = token total after the slot, precomputed once
as a reverse cumulative sum (O(1) per candidate); **R / P_alive**
env-tunable (`HEADROOM_NET_COST_EXPECTED_READS`=10,
`HEADROOM_NET_COST_P_ALIVE`=1.0). Every decision logs all inputs at INFO
and increments `netcost_allowed`/`netcost_skipped` counters so the flag
can be validated from telemetry before any default-on.

Closes #907.

## Type of Change

- [x] New feature (non-breaking change which adds functionality)

## Changes Made

- Add flag-gated net-cost mutation gate to `ContentRouter` at both
mutation sites (cache-hit + fresh-compress merge).
- Precompute reverse-cumulative suffix token sums once per request for
O(1) S lookups.
- Emit INFO telemetry, `netcost_allowed`/`netcost_skipped` counters, and
a `netcost:skip:<band>` transform marker on blocked slots.
- **Review-response (4eb2307):** reject non-finite env values
(`math.isfinite` guard), count suffix tokens block-aware via
`_netcost_message_tokens()` (was `str(content)`, which miscounted
Anthropic block lists), and bucket the skip marker via `_gain_bucket()`
to bound dashboard cardinality.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] New tests added for new functionality
- [x] New and existing unit tests pass locally with my changes

### Test Output

```text
$ pytest tests/test_netcost_gate.py -q
11 passed in 0.82s

$ pytest tests/ -k "content_router or netcost or router" -q
133 passed, 8 skipped, 6120 deselected in 23.26s

$ ruff check headroom/transforms/content_router.py
All checks passed!
```

## Real Behavior Proof

- Environment: local macOS, repo .venv, Python 3.11.9, gpt-4o tokenizer
fixture
- Exact command / steps: `pytest tests/test_netcost_gate.py -q` then the
router-suite selector above; gate exercised end-to-end through the real
tokenizer + compression path (flag on via monkeypatch)
- Observed result: with R=10/P=1 defaults, a 300-row tool result
followed by a 40k-word suffix is left uncompressed (gate skips,
`netcost:skip:` marker emitted); a 2000-row result with a 5-word suffix
compresses (gate allows). Non-finite env (`inf`/`nan`) falls back to
defaults and still skips.
- Not tested: live proxy traffic / real dashboard validation — deferred
to the default-on milestone per #904 (this ships default-off precisely
to gather that telemetry first).

## Review Readiness

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

## Additional Notes

Cache-hit re-tokenization (`:2312`) and the large integration fixtures
are tracked as follow-ups in the PR review thread; both are intentional
given the flag is default-off. Known v1 limitations (whole-suffix S, no
batch awareness, static P_alive) are tracked in #904 as P2b/P3a/P3b.

PR body updated to satisfy the new PR-governance template gate (#914-era
governance workflow).

---------

Co-authored-by: integration-check <integration@local>
 2026-06-13 10:46:26 -05:00