feat(bgz-tensor): SharedPaletteGroup × SlotL group-level integration

[AdaWorldAPI]

Summary

Step 3 of the universal_hhtld_encode plan. SVD basis for Slot L now lives at group granularity — one basis amortised across all same-role same-shape tensors.

Single file: crates/bgz-tensor/src/shared_palette.rs (+260 LOC, all additive).

Changes (additive, backwards-compat)

pub struct SharedPaletteGroup {
    // ... existing fields preserved ...
    pub tensor_slot_l: Vec<(String, Vec<SlotL>, f32)>,  // per-tensor leaves
    pub svd_basis:     Option<SvdBasis>,                 // shared basis
}

pub fn should_use_leaf(role: &str) -> bool;
pub fn build_group_with_leaf(key, names, rows_f32, k) -> SharedPaletteGroup;

impl SharedPaletteGroup {
    pub fn slot_l_byte_size(&self) -> usize;
    pub fn svd_basis_byte_size(&self) -> usize;
    pub fn slot_l_for(&self, tensor_name: &str) -> Option<(&[SlotL], f32)>;
}

The existing build_group_with_fisher_z constructor defaults the new fields to empty / None. No caller needs to change.

Dispatch table (mirrors the mindset-shift regime split)

role	should_use_leaf	Wire cost	Quality target
embed / lm_head	true (index regime)	12 B/row (Slot D + Slot V + Slot L)	ρ ≳ 0.98 per row
qko, v, gate, up, down, projection, other	false (argmax regime)	4 B/row	ρ ≳ 0.95 per row is sufficient

build_group_with_leaf does this dispatch internally — argmax-regime calls delegate to the existing build_group_with_fisher_z path unchanged; index-regime calls build one SvdBasis from the first tensor's rows (capped at 4096 samples for speed on 151K-vocab) and feed every tensor through encode_with_leaf with that shared basis.

Tests (all new pass)

Test	Verifies
should_use_leaf_classification	2 true (embed, lm_head) / 7 false
build_group_with_leaf_falls_back_for_argmax_regime	role="qko" → no basis, no Slot L, same 4 B/row as before
build_group_with_leaf_populates_slot_l_for_index_regime	role="embed", 2 tensors × 64 rows × 128 cols → Slot L populated at 8 B/row, basis shared
svd_basis_shared_across_group_not_per_tensor	Basis size constant regardless of tensor count — amortisation confirmed

Full bgz-tensor suite: 154 passing (150 + 4 new). Pre-existing failures on main (gamma_calibration, hhtl_d_entry_roundtrip, matryoshka, hhtl_cache) unchanged.

Storage amortisation

For Qwen3-TTS-0.6B's text embedding as a one-tensor group:

• Before: each tensor would own a full copy of its SVD basis
• After: one SvdBasis shared across all tensors in the (talker, embed, [151936, 2048]) group

For multi-tensor groups (e.g. 15 lm_heads under (talker, lm_head, [2048, 1024])):

• Basis cost flat (≈ 32 KB for 8 × 2048 × 2 B)
• Entries cost scales linearly (15 × n_rows × 8 B)

Session PR stack (three sibling PRs land together cleanly)

PR	Status	What
#178	open	Passthrough fix + Lance roadmap + WAV test (from tts_rvq_e2e.rs path)
#180	merged	SlotL foundation module
#181	merged	HhtlDTensor × SlotL per-tensor integration
#182	this PR	SharedPaletteGroup × SlotL group-level integration

Follow-ups (next PRs in the chain)

1. universal_hhtld_encode.rs example — iterate over tensors in a safetensors model, bucket by (classify_component, classify_role, effective_shape), feed each bucket to build_group_with_leaf (which internally dispatches on role).
2. .hhtld container format — single-file pack with magic byte header, palette + SVD basis + per-tensor entries + Slot L.
3. Inference wiring — swap tts_full_inference's custom RVQ codebook sum for HhtlDTensor::reconstruct_row on index-regime tensors; argmax-parity validation against raw inference.

Test plan

• cargo build --manifest-path crates/bgz-tensor/Cargo.toml — clean
• cargo test shared_palette — 8/8 pass (4 new)
• Full cargo test bgz-tensor — 154 pass, 5 pre-existing failures (not mine)
• universal_hhtld_encode.rs example (next PR)
• .hhtld container format (next PR)
• Inference wiring (next PR)

https://claude.ai/code/session_01NYGrxVopyszZYgLBxe4hgj

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2f9dced855

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Return early for empty group input

The empty-input guard currently still panics: when tensor_rows_f32.is_empty() this branch delegates to build_group_with_fisher_z, which immediately indexes tensor_rows_f32[0] and aborts. Any caller that passes an empty bucket (for example, after filtering/grouping) will crash instead of getting a safe fallback, so this helper does not actually handle the case it checks for.

Useful? React with 👍 / 👎.