Curated subset of #90 + K-side norm accounting fix

[TheTom]

Selectively merging from @brosequist's #90 — keeping the actual fixes, deferring API surface, plus an additional K-side fix that #90 missed.

Thanks @brosequist for the bundle — review surface was much easier this way. Re-bundling further per the curation below.

What's included

commit	author	what
b75813b	@brosequist	fix: V-norm in memory_stats, SeedSequence PRNG, TurboQuantMSE.compressed_size_bits
1074625	@brosequist	test: QJL regression-guard in test_turboquant_improves_over_polarquant
f23570e	@brosequist	test: correctness + round-trip tests for fast rotation functions
3e37572	@brosequist	chore: ruff config in pyproject.toml
0ca5bcc	@brosequist	ci: drop lint workflow (kept ruff config only)
8afc4bf	@TheTom	fix: K-side norm accounting — count vector_norm AND residual_norm

Brett's first commit was split — credit preserved

The original 0fd5de9 bundle (5 changes) was cherry-picked with the streaming + serialization API deferred. What's kept:

• ✅ V-norm fix in KVCacheCompressor.memory_stats()
• ✅ TurboQuantMSE.compressed_size_bits() (was missing; TurboQuant already had it)
• ✅ SeedSequence.spawn(2) replacing seed + 1000 magic offset

What's deferred (no caller yet, want to design for the production integration):

• KVCacheCompressor.compress_token() / get_compressed_cache() streaming API
• CompressedVector.to_bytes() / from_bytes() binary serialization
• CompressedKVCache.save() / load() npz serialization

The split commit retains @brosequist as author.

What's added

8afc4bf is a parallel fix to the V-norm fix in b75813b. TurboQuant.CompressedVector stores two float32 norms (vector_norms = ||x||_2 and residual_norms = ||residual||_2), but TurboQuant.compressed_size_bits and KVCacheCompressor.memory_stats only counted one. V uses TurboQuantMSE (single norm — 32 is correct). K uses full TurboQuant (two norms — 64 is correct).

Numerical effect (verified live):

• TurboQuant(d=128, b=3).compression_ratio(): 4.92× → 4.57× (true)
• KVCacheCompressor(d=128, k=3, v=3).memory_stats(...)['compression_ratio']: ~2.46× → 2.37× (true)

No quantization-output changes — accounting only.

What's not included from #90

• feat: add calibrate() to OutlierTurboQuant — OutlierTurboQuant is a deprecated path per docs/turboquant-plus-experiments.md ("Outlier channeling doesn't work… kurtosis stays 8-50… WHT rotation gets it to 2.9"). Calibrate code is well-written, just on a dead module.
• docs: HIP/AMD NaN warning — root-cause story ("large K norms → NaN") contradicts docs/papers/asymmetric-kv-compression.md:218, which finds extreme K norms compress better (more Gaussian after normalization). Real cause is HIP-kernel-specific. Will revisit after kernel triage.

Consistency with docs/papers/why-mse-fails-for-kv-quantization.md

The new MSE paper argues MSE is a broken proxy for K cache quantization in deployment because attention is non-linear and sparse. Brett's QJL regression-guard test (1074625) measures inner-product distortion on synthetic Gaussian pairs (d=256) — the linear-operator regime where the new paper explicitly says IP/MSE does proxy quality (alongside RaBitQ-style top-k IP search). The test is a regression-guard for IP distortion only; the production decision to drop QJL is justified separately by docs/papers/turbo4-resurrection.md's PPL ablation. No conflict.

Test plan

• pytest tests/ refract/tests/ — 982 passed, 1 skipped (7 fewer than Bundled fixes & tests: V-norm accounting, OutlierTurboQuant.calibrate, rotation tests, ruff CI, HIP/AMD NaN docs #90 baseline because streaming/serialization tests deferred with their code)
• Smoke-tested TurboQuant.compression_ratio() and KVCacheCompressor.memory_stats() numerics against expected values

🤖 Generated with Claude Code