docs(r12): v1.2 §6.1 kv_cache_compression_ratio semantics clarification + doc-consistency sweep

[synapticode-ai]

Summary

R12 v1.2 amendment clarifying §6.1 kv_cache_compression_ratio field semantics for two hook architectures (round-trip vs propagation), folding in a doc-consistency sweep parallel to yesterday's R7-B v1.2 precedent. Companion to PR #34 (which already emits the v1.2-conformant theoretical ratio); PR #34 amendment to bump its SPEC_VERSION constant lands next.

Why

PR #34's A'' R12 sweep wrapper implementation surfaced that §6.1's kv_cache_compression_ratio field — described as "computed by tern_kv_ppl_bench.py from pre/post past_key_values byte sizes" — was vacuous under β1a make_b_mse_hook_uniform's round-trip hook architecture:

• Input FP16 K/V → encode → quantize → decode → output FP16 K/V at identical shape and dtype
• Output bytes equal input bytes → measured ratio = 1.0 always
• The operating point's actual compression (4×, 8×, 16× depending on b_mse) lives in the codebook-encoded intermediate representation that never propagates outside the hook

PR #34 already emitted the theoretical ratio (16 / b_mse) with explanatory notes field; v1.2 spec catches up with the implementation reality.

Changes

Primary amendment (briefing scope)

• §6.1 v1.2 clarification block appended after the per-point schema example — disambiguates field semantics for round-trip hooks (theoretical 16 / b_mse) vs propagation hooks (pre/post bytes, not yet implemented in tern-core)
• §11 new ### v1.1 → v1.2 cascade (2026-05-18) entry at top — full cascade narrative + cross-references

Doc-consistency sweep (Phase B dispositions, ratified)

#	Item	Action
1	Front-matter title + Document status stamps at v1.0 (hygiene gap from v1.0 → v1.1 cascade)	Bump v1.0 → v1.2 directly (parallel to R7-B v1.2 PR #33 precedent)
2	§7 schema example spec_version and methodology_consumed lagged at v1.0	Bump to v1.2 each
3	§11 heading baked-in cascade pattern (## §11 Change log — v0.1 → v0.2 (2026-05-15)) inconsistent with R7-B convention	Refactor to clean ## §11 Change log; demote v0.1 → v0.2 cascade body to ### v0.1 → v0.2 cascade (2026-05-15) sub-entry with #### sub-sub-sections
4	Tool-name divergence: 5 live spec references to anticipated tern_kv_ppl_bench.py vs actual PR #34 artifact tern_r12_sweep.py	Update §4 / §6.1 / §10 live references to tern_r12_sweep.py; preserve §11 historical mentions verbatim (they quote what v0.2 spec actually said)

Footer

Rewritten to v1.2 ratification (2026-05-18) with §6.1 clarification + doc-consistency sweep mention; preserves v1.1 lessons-learned phrasing.

§11 ordering note (transparency)

### v1.1 → v1.2 cascade (2026-05-18) is at top per Rob's explicit Phase B instruction ("prepend the new ... cascade ... at top"). Existing historical sub-entries (v0.1 → v0.2, v0.2 → v1.0, v1.0 → v1.1) left in their original chronological-forward order — strict newest-first reordering across all sub-entries would be a 3-line follow-up edit if desired, but went beyond explicit Phase B disposition.

Methodology version note

• Spec version: v1.1 → v1.2 (field semantics clarification + doc-consistency)
• Schema versions: ppl_headroom_kv_cache_point/1.0 and ppl_headroom_kv_cache_sweep/1.0 — both unchanged (data format identical; clarification is methodology, not data)
• PR feat(r12): sweep wrapper for KV-cache compression PPL headroom diagnostic (A'') #34 amendment (companion, lands separately): bumps SPEC_VERSION constant in tools/tern_r12_sweep.py from v1.1 to v1.2 so post-amendment sweep runs emit v1.2 in their JSON metadata

Background sweep note

The full A'' sweep launched 2026-05-17 (PID 8767, still running unattended) was started under v1.1 SPEC_VERSION. Its emitted JSONs will say spec_version: kv_cache_compression_ppl_headroom_diagnostic v1.1 — methodologically correct (the sweep WAS executed under v1.1 understanding; PR #34's implementation already emitted the v1.2-conformant theoretical ratio + explanatory notes). Sweeps launched after PR #34's amendment will emit v1.2.

Test plan

• §6.1 v1.2 clarification block landed between schema example and §6.2 header
• §7 schema example spec_version + methodology_consumed bumped to v1.2
• §11 refactored to clean ## §11 Change log heading; ### v1.1 → v1.2 cascade at top; ### v0.1 → v0.2 cascade sub-entry with #### Substantive/Documentary/Unchanged sub-sub-sections
• Tool-name audit: 5 live references updated to tern_r12_sweep.py; 2 historical mentions preserved as tern_kv_ppl_bench.py
• Front matter at v1.2; footer at v1.2 (2026-05-18)
• Diff: only doc changes (+58/−15)

Cross-references

• A'' workstream: PR feat(r12): sweep wrapper for KV-cache compression PPL headroom diagnostic (A'') #34 (sweep wrapper implementation)
• β1a factory: PR make_b_mse_hook_uniform: batched-uniform R12 factory (β1a) #27 (make_b_mse_hook_uniform)
• Cache-shape contract: PR fix(tern_infer): factories return DynamicCache natively per R7-B §5.2 #32 (DynamicCache return)
• R7-B v1.2 doc-consistency precedent: PR docs(r7-b): v1.2 calibration gate widening per D1 factor decomposition #33

🤖 Generated with Claude Code