fix(bgz-tensor): reject HhtlF32Tensor palette sizes >= 256 (codex #184 P1)

[AdaWorldAPI]

Summary

Follow-up to merged #184. Addresses codex P1 comment on that PR: "Reject palette sizes that exceed 255 centroids."

Single file: crates/bgz-tensor/src/hhtl_f32.rs (+59 LOC).

The bug codex caught

HhtlF32Entry.twig is u8 so valid centroid IDs are 0..=255. Before this fix:

• encode(role, rows, k) accepted any k.
• clam_furthest_point_f32 capped k at rows.len() but not at 256.
• assign_nearest_f32 returned ci as u8, silently wrapping (e.g. 300 → 44).

Result: passing k = 1024 would silently assign centroid-300's rows to centroid-44's slot, corrupting every downstream ρ / argmax measurement — but producing a "working" run.

This was actively dangerous because #184's follow-up plan explicitly proposed k = 1024 or 2048 as the quality-improvement fallback (per the reviewer's E5 suggestion). If someone ran the Path A encoder with k = 1024 they'd get a clean exit and bogus numbers.

Fix

pub const MAX_PALETTE_K: usize = 256;

impl HhtlF32Tensor {
    pub fn encode(role: &str, rows_f32: &[Vec<f32>], k: usize) -> Self {
        assert!(k > 0, "HhtlF32Tensor::encode requires k > 0, got {}", k);
        assert!(k <= MAX_PALETTE_K,
            "HhtlF32Tensor::encode requires k <= {} (u8 twig limit), got {}",
            MAX_PALETTE_K, k);
        // ...
    }

    pub fn encode_with_leaf(...) -> Self {
        // same bounds checks
    }
}

Future-work note baked into the doc: larger palettes need a codec with a wider twig-index (u16 would lift the cap to 65536, but it's a wire format change). That lands in a separate PR if/when the quality probe demonstrates k ≥ 512 earns its keep over k=256 + deeper SlotL basis.

Tests

encode_rejects_zero_k ............................... ok  (#[should_panic = "k > 0"])
encode_rejects_k_above_256 .......................... ok  (#[should_panic = "u8 twig limit"])
encode_with_leaf_rejects_k_above_256 ................ ok  (same)
encode_accepts_k_at_max_palette ..................... ok  (k=256 still succeeds)
5 existing tests ...................................... ok
───────────────────────────────────────────────────
9 passed; 0 failed

Stack

• #180/181/182/183/184 merged
• #185 (this PR) — P1 codex fix for HhtlF32Tensor palette bounds

https://claude.ai/code/session_01NYGrxVopyszZYgLBxe4hgj