kakeyaturbo: monomorphic Rust implementation of the KakeyaTurbo RDO codec with ≥99.76% UT coverage

[FluffyAIcode]

Summary

Rust crate at kakeyaturbo/ implementing the KakeyaTurbo codec designed in the earlier conversation rounds: a single monomorphic encode_block / decode_block kernel parametrised by

• a compile-time type parameter R: Distortion (the loss ρ)
• a runtime &[f32] weights array w
• a runtime CodecParams struct (variance_ratio, K, bit_width, rotation_seed)

No plugins, no dyn, no extension points. Every (R, n, d, d_eff, K, B) combination compiles to its own specialised machine-code function.

Modules

File	Responsibility	LOC
src/lib.rs	entry + design-contract doc + re-exports	54
src/distortion.rs	Distortion trait + MSE, InnerProduct, LInf ZSTs	280
src/wht.rs	Walsh-Hadamard transform + seeded sign flips	307
src/quantize.rs	Lloyd-Max codebooks for N(0,1) + LSB-first bit packing	355
src/pca.rs	weighted PCA truncated at d_eff	371
src/kmeans.rs	weighted spherical K-means with sign-aware update	436
src/skeleton.rs	block-level metadata container	97
src/codec.rs	the single encode_block / decode_block kernel	495
Total library code		~2 400

Quality gates

gate	status
cargo build	✅ clean
cargo test	✅ 136 passing (125 unit + 5 integration + 6 proptest)
cargo clippy --all-targets	✅ 0 errors, remaining warnings are style preferences in numerical loops
cargo llvm-cov line coverage	99.76 % — see table below
cargo llvm-cov function coverage	100.00 %
#![forbid(unsafe_code)]	✅ enforced at crate root
grep -rn "dyn " src/	✅ zero occurrences (comments/test-names aside)
grep -rn "Box<" src/	✅ zero occurrences

Per-module coverage (cargo llvm-cov --summary-only)

Filename      Regions  Missed    Cover | Functions Missed Executed | Lines Missed   Cover
-----------------------------------------------------------------------------------------------
codec.rs          180       8   95.56% |      45       0  100.00% |   445      2   99.55%
distortion.rs      87       2   97.70% |      24       0  100.00% |   113      0  100.00%
kmeans.rs         189       5   97.35% |      35       0  100.00% |   356      0  100.00%
pca.rs            150       7   95.33% |      26       0  100.00% |   300      1   99.67%
quantize.rs       150       8   94.67% |      36       0  100.00% |   239      1   99.58%
skeleton.rs        15       0  100.00% |       7       0  100.00% |    49      0  100.00%
wht.rs            115       2   98.26% |      33       0  100.00% |   181      0  100.00%
-----------------------------------------------------------------------------------------------
TOTAL             886      32   96.39% |     206       0  100.00% |  1683      4   99.76%

The only uncovered source lines are 2 assert!(cond, "...") format-string messages inside test code (by definition unreachable while tests pass):

• src/pca.rs:338 — "captured variance not monotone: prev={prev} new={}"
• src/quantize.rs:228 — "MSE must decrease with more bits: prev={prev} new={mse}..."

Together with continuation lines, these account for the 4 uncovered line slots. Every line of production code is covered.

Test inventory

Unit tests (125)

• distortion (17): closed-form values, symmetry, non-negativity, numerical-gradient match, Huber-continuity at the breakpoint, NORM_MODE correctness, zero-size verification.
• wht (17): size-1 identity, explicit H₂/H₄ comparison, WHT² = N·I, power-of-2 panic paths, deterministic sign patterns, seed-determinism, zero-input, linearity, rotate/inverse round-trip, seed mismatch detection.
• quantize (25): centroid count/symmetry/ordering for each bit-width, nearest-centroid selection, out-of-range clamping, MSE monotonicity in bits, metric-agreement (MSE vs IP on the scalar level), bit-pack round-trip, byte layout check, error paths.
• pca (19): weighted mean with uniform/zero/skewed weights, 2D-ellipse major-axis recovery, variance-ratio truncation, round-trip under full rank, constant-data handling, variance-monotonicity, weighted emphasis, zero-weight-row skip, NaN/out-of-range ratio clipping, dimension mismatch panics.
• kmeans (21): k = n identity, unit-norm centres, seed determinism, two-cluster recovery, zero-norm row skip, zero-weight-row skip, misshaped input panics, assign_and_project correctness (including anti-aligned input), residual subtraction, centre view helpers.
• skeleton (3): byte-size accounting, dim accessors, clone equivalence.
• codec (23): MSE / InnerProduct / LInf round-trips, 4-bit vs 1-bit MSE ordering, weight-driven PCA rotation, shape preservation, byte accounting, determinism, seed-variation, 7 panic paths, zero-coefficient edge case, all-zero-block handling, next_pow2/pad_zero/l2_norm helpers.

Integration tests (5)

Real end-to-end blocks: 64×32 MSE reconstruction, compression-ratio bound, weighted-row priority, inner-product preservation, multi-shape robustness.

Property tests (6, via proptest)

Random blocks + weights: shape invariance, determinism, finite reconstruction, all-bit-width handling, all-K handling, uniform-weight-scale invariance.

Design contract verification

The philosophy "one kernel, one code path, no dispatch" is grep-verifiable:

grep -rn "dyn "  src/     # → 0 matches
grep -rn "Box<"  src/     # → 0 matches
grep -rn "unsafe" src/    # → 0 matches

The design-contract block in src/lib.rs makes this explicit, and #![forbid(unsafe_code)] at the crate root compiles unsafe out.

Example

use kakeyaturbo::{encode_block, decode_block, CodecParams, MSE, InnerProduct, LInf};

let params = CodecParams {
    variance_ratio: 0.95, k: 8, bit_width: 3,
    rotation_seed: 0xCAFE_BABE, kmeans_max_iter: 32,
};

// Same function, three different specialised machine-code emissions:
let (sk, codes) = encode_block::<MSE>(&block, &weights, d, &params);          // V cache, time series
let (sk, codes) = encode_block::<InnerProduct>(&block, &weights, d, &params); // K cache, retrieval
let (sk, codes) = encode_block::<LInf>(&block, &weights, d, &params);         // scientific data

// Boundary-V / sparse-V / attention-weighted: just pass different weights,
// no codec changes needed — this is the L1–L5 unification under RDO.

Repro

cd kakeyaturbo
cargo test                          # 136 tests
cargo llvm-cov --summary-only       # the coverage table above
cargo llvm-cov --html --output-dir coverage && open coverage/html/index.html
cargo clippy --all-targets
grep -rn "dyn \|Box<dyn\|unsafe " src/

Environment

Rust 1.83.0 stable. Dependencies: nalgebra 0.33 (for weighted SVD), half 2.4 (fp16 scalars in Codes), rand 0.8 (SmallRng seeded sign patterns). Dev deps: approx 0.5, proptest 1.5.0.