docs+benchmarks: dark-patch verdict — decoder attrs near-fal clean, Metal texel-sampling convicted; regular-grid gather fix designed; parity fixtures complete

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

BENCHMARKS.md

@@ -243,3 +243,30 @@ on M3 Ultra these 2B GEMM-bound models get ~1% from mx.compile fusion;
 the tune's real wins were T4 fused attention (texture stage) + T3
 compile-safety. Branch mlx-tune @ 5a32240; flag HY3D_MLX_COMPILE=1.
 Worth re-benching on M1 Ultra where launch overhead is proportionally larger.
+
+## 10 · DARK-PATCH VERDICT: Metal texel-sampling convicted (2026-07-19)
+
+Decisive experiment: dumped the decoded tex voxels (E2 fixture,
+1,398,769 voxels × 6 PBR attrs) and rendered base_color as a direct
+front-projection — `trellis2-bench/attrs_front.png`. **The attrs are
+near-fal quality** (clean anatomy palette; dark voxels only 5.6%, all
+interior). Both local pipelines (trellis-mac MPS and Jourloy MLX) produce
+the same mottled dark bake from these clean attrs, and both share the
+pedronaugusto mtldiffrast/mtlbvh texel→voxel sampling. ⇒ **the bake's
+attr-sampling is the sole quality gap.** The 3h+ KDTree run is now merely
+confirmatory (left running).
+
+### Designed fix (next session's opening move)
+The attrs live on a REGULAR voxel grid — no BVH/KDTree needed at all:
+texel → (xatlas UV → triangle barycentric → world pos) →
+`grid[(pos-origin)/voxel_size]` direct index (+8-neighbor occupancy
+search). One vectorized gather over all texels; replaces the suspect
+ray-cast sampling entirely; implementable in torch-MPS or MLX in ~a page.
+Validate against `attrs_front.png` colors + the fal render. If it works,
+BOTH local paths get fal-class texture quality at zero bake-speed risk.
+
+### Parity fixture set: COMPLETE
+All 8 fixtures captured at `trellis2-bench/parity_fixtures/` (cond_512/
+1024, ss_coords, shape_slat, shape_dec, tex_slat, tex_voxels, mesh_final;
+seed 42, 1024-cascade). Hook env needed: PYTORCH_ENABLE_MPS_FALLBACK=1
+ATTN_BACKEND=sdpa SPARSE_ATTN_BACKEND=sdpa SPARSE_CONV_BACKEND=flex_gemm.

docs/FABLE_STARTUP_PACKET.md

@@ -383,3 +383,30 @@ Done this session (all committed; BENCHMARKS.md has the rows):
 5. **Dark-patch culprit narrowed**: reproduces on BOTH independent pipelines (trellis-mac MPS + Jourloy MLX) → shared pedronaugusto Metal texel-sampling (mtldiffrast/BVH) or decoded attrs. fal is clean on the same weights → attrs likely fine → **Metal sampling = prime suspect**. KDTree pure-Python bake control still grinding (2h+, alive, 300% CPU) — its render decides.
 
 NEXT (in order): read KDTree verdict when it lands → Hunyuan e2e A/B number → wire prep_local into MESHGOD behind a flag → Target 2 (whole-DiT compile now that T3 unblocked it) → promote mlx-experimental into MODELBEAST as a `trellis2_mlx` operator behind a flag once the bake-quality question is settled.
+
+## 10 · DARK-PATCH VERDICT: Metal texel-sampling convicted (2026-07-19)
+
+Decisive experiment: dumped the decoded tex voxels (E2 fixture,
+1,398,769 voxels × 6 PBR attrs) and rendered base_color as a direct
+front-projection — `trellis2-bench/attrs_front.png`. **The attrs are
+near-fal quality** (clean anatomy palette; dark voxels only 5.6%, all
+interior). Both local pipelines (trellis-mac MPS and Jourloy MLX) produce
+the same mottled dark bake from these clean attrs, and both share the
+pedronaugusto mtldiffrast/mtlbvh texel→voxel sampling. ⇒ **the bake's
+attr-sampling is the sole quality gap.** The 3h+ KDTree run is now merely
+confirmatory (left running).
+
+### Designed fix (next session's opening move)
+The attrs live on a REGULAR voxel grid — no BVH/KDTree needed at all:
+texel → (xatlas UV → triangle barycentric → world pos) →
+`grid[(pos-origin)/voxel_size]` direct index (+8-neighbor occupancy
+search). One vectorized gather over all texels; replaces the suspect
+ray-cast sampling entirely; implementable in torch-MPS or MLX in ~a page.
+Validate against `attrs_front.png` colors + the fal render. If it works,
+BOTH local paths get fal-class texture quality at zero bake-speed risk.
+
+### Parity fixture set: COMPLETE
+All 8 fixtures captured at `trellis2-bench/parity_fixtures/` (cond_512/
+1024, ss_coords, shape_slat, shape_dec, tex_slat, tex_voxels, mesh_final;
+seed 42, 1024-cascade). Hook env needed: PYTORCH_ENABLE_MPS_FALLBACK=1
+ATTN_BACKEND=sdpa SPARSE_ATTN_BACKEND=sdpa SPARSE_CONV_BACKEND=flex_gemm.