@woosh/meep-engine 3.2.0 → 3.4.0

package/src/shade/renderer/gpu_primitive/bvh/GPU_BVH_BUILD_PLAN.md

@@ -0,0 +1,1115 @@
+# GPU BVH Builder — research findings and implementation plan
+
+> Status: **PHASE 1 LANDED (device-free tiers)** — 2026-08-26. The CSDLDF key-value radix sort and
+> the GPU TLAS build are in the tree, the GPU path is the default, and the three device-free
+> validation tiers are green (`npm test`: 13,590 passing, nothing skipped that was not already).
+> **Phase 1 is complete and gated.** The harnesses are green, and the consumer A/B has been run
+> through `src/shade/playground/sponza_path_trace/`: Sponza traced against a CPU-built and a
+> GPU-built tree, images verified equivalent by inspection. §4.6 carries the numbers.
+>
+> The A/B produced one result that changes what phase 2 is for, and §5.1 has been rewritten around
+> it: **at instance scale the GPU LBVH already beats the CPU pipeline on every axis** — SAH, depth,
+> traced frame time and build time — so phase 2's stated premise, that phase 1 ships a quality
+> regression, does not survive measurement. Deviations from this plan are recorded in place below,
+> each marked **[deviation]**.
+>
+> Landed as: `db960d9cb` (sort), `31599c3b9` (morton + emission chunks), `61727d3b8` (builder
+> shaders + recorder), `6b062dbcc` (TLAS integration), `7222f1b35` (format spec + verify harness).
+>
+> Original status: PLANNED — research complete, no code landed. 2026-08-26.
+> Revised same day after review: the sort is a deliverable built around **CSDLDF** (the
+> fallback-less OneSweep port was removed in `b6049214c`; history serves as reference);
+> **subgroups are a baseline engine requirement** and are used wherever they pay; validation
+> explicitly stands on all four device-free/on-device tiers, `SoftwareGPUDevice` and the WGSL
+> emulator included.
+>
+> Goal: move BVH construction to the GPU. First deliverable replaces the CPU-side build that
+> `GPUInstancesAccelerationStructure` (the TLAS) performs today; then treelet optimisation on the
+> GPU; then the geometry side (BLAS); and only after all of that, BVH8. Every phase leaves the
+> existing RT and culling consumers fully working.
+>
+> References studied: Microsoft's D3D12 Raytracing Fallback Layer and AMD's GPURT, plus the
+> construction literature (Karras 2012, Karras & Aila 2013, Apetrei 2014, PLOC/PLOC++/H-PLOC).
+> Both references and the literature survey are summarised in §3; meep's own inventory — which
+> turns out to already contain most of the algorithm — is §2.
+
+---
+
+## 1. Why, and why now
+
+`GPUInstancesAccelerationStructure.push_to_gpu()` currently does, on the CPU, on **every frame in
+which any instance moved**:
+
+1. `ebvh_optimize_treelet(tree)` — a whole-tree treelet restructuring pass (Karras & Aila 2013,
+   treelet size 7, exhaustive 2^7-subset SAH DP per treelet), mutating the dynamic tree;
+2. `bvh_to_gpu_buffer(...)` — flatten `node_capacity` nodes from the 40-byte CPU format to the
+   32-byte GPU format into a fresh mapped staging buffer;
+3. a full-buffer `copyBufferToBuffer` upload.
+
+This is a measured, known frame-budget problem. `TerrainSystem3.spec.js` documents the incident
+(E19): *"the TLAS rebuilds — a whole-tree treelet optimisation and a fresh GPU buffer — whenever
+any instance it holds is told its bounds changed. A terrain standing still was doing all of that
+once a frame, which was a quarter of the frame."* The fix that spec pins (don't bump versions for
+unmoved nodes) treats the trigger; this project treats the cost. In any scene with continuous
+motion — animation, physics, particles-as-instances — the rebuild fires every frame by design, and
+the CPU pays O(N) treelet DP plus an O(capacity) upload each time.
+
+There is a second, structural motivation: **the CPU cannot see GPU-authority transforms.** Rows
+under `TransformAuthority.GPU` (GPU-side animation / hierarchy propagation) move on the GPU;
+`shader_refresh_all_mesh_bounds` recomputes their world bounds into the scene database — and the
+CPU-built TLAS never learns about any of it. A GPU-side build that reads instance bounds from the
+scene database gets correct bounds for both authorities from a single source of truth. The GPU
+build is not just faster; for GPU-animated content it is the only correct option.
+
+Context worth stating: the survey (§3.3) found that essentially every public WebGPU ray tracer
+still builds its BVH on the CPU and only traverses on the GPU — published CPU build times run to
+hundreds of milliseconds per million triangles, while driver-class GPU builders do the same work
+in low single-digit milliseconds. A WGSL GPU builder is near-unoccupied territory; meep has an
+unusually short path to it because the algorithms and the substrate primitives are already in the
+tree (§2).
+
+---
+
+## 2. Research: what meep already has
+
+The striking finding of this research: **meep already contains a complete, tested CPU
+implementation of exactly the algorithm family that both external references run on the GPU**, plus
+almost every GPU primitive the port needs. The builder is a port, not an invention.
+
+### 2.1 The wire format — the compatibility contract
+
+Everything below is what "existing RT code stays compatible" means, verified against every consumer
+in the tree.
+
+**Node** — `src/shade/renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js`, 32 bytes, align 4:
+
+| bytes | field | notes |
+|---|---|---|
+| 0–23 | `bounds: array<f32, 6>` | `[min.x, min.y, min.z, max.x, max.y, max.z]` — block layout, not interleaved (`chunk_aabb3_intersects_ray` reads `bounds[0..2]` / `bounds[3..5]`) |
+| 24–27 | `child_1: u32` | `== 0xFFFFFFFF` (`BVH_NULL_NODE`) ⇔ **leaf** |
+| 28–31 | `child_2: u32` | internal: right-child node index; leaf: **payload** (user data) |
+
+There are no tag bits, no counts, no ranges. One primitive per leaf. Internal nodes always have two
+valid children — and the distance-ordered point queries (`chunk_point_query_blas_nearest`,
+`chunk_scene_point_query_nearest`) dereference **both** children's bounds before descending, so
+both must be real node indices with meaningful AABBs.
+
+**Buffer** — TLAS and the LPV tetrahedral lookup use `BVH_STRUCT`
+(`{root: u32, nodes: array<BVH2_NODE_STRUCT>}`): a `u32` root index at byte 0, nodes from byte 4.
+That is the entire meaning of the `+ 4` in every sizing expression. **BLAS has no header**: root is
+implicitly node 0 (asserted twice in `meshlet_batch_to_bvh.js`, relied on by
+`chunk_ray_query_blas_*` and by `shader_build_sdf.js`, which reads `blas_data[blas_address].bounds`
+as the geometry's bounds). BLAS trees live packed in one arena
+(`GPUGeometryBVHManager`); `blas_lookup[geometry] = address` is a **node index, not a byte
+offset**.
+
+**Leaf payloads**: TLAS leaf `child_2` = row in the scene database `meshes` table, consumed via
+`scene_read_mesh`. BLAS leaf `child_2` = `(meshlet_index << 8) | (triangle_index & 0xFF)` — ≤256
+triangles per meshlet, and this encoding is **serialized to disk** with geometry
+(`MeshletGeometrySerializationAdapter`), so it is a content-format contract, not just a runtime
+one.
+
+**Traversal** (`chunk_ray_query_nearest`, `chunk_ray_query_occluded`, BLAS variants, LPV lookup):
+stack-based, `BVH_TRAVERSAL_STACK_SIZE = 32`, descends `child_1`, pushes `child_2`, no ordered
+descent in the ray paths. Two facts with teeth:
+
+- The 32-entry stack is **shared between TLAS and BLAS** in one query — effective combined depth
+  budget ≈ 31. The occlusion variant's `(pointer & 31) != 0` loop condition silently *truncates*
+  traversal at stack overflow rather than erroring. Tree depth is therefore a real output-quality
+  constraint on the builder, not a nicety (§7, R4).
+- `tlas.root` is read from the header word — the builder must write it (it will be constant 0, see
+  §4.3, but it must be written).
+
+**Who consumes what** (all verified):
+
+- GPU, TLAS: path tracer (`graph_path_trace_scene`, `AccumulatingPathTracer`, `graph_restir_di`),
+  lightmap baker (`GPULightMap`), LPV/probes (`graph_lpv_shade`, `GPUProbeAtlas`,
+  `GPULightProbeVolumeRenderer`, `graph_generate_probe_locations`), brick4 GI bake, RTX shadows
+  (`RTXShadows`, `graph_trace_rays`), SDF passes (`CascadedSceneSDF`, `graph_draw_sdf_shadows`,
+  `shader_sdf_visualize`). All grab `scene_ctx.tlas.buffer` **at pass-execute time** as an external
+  buffer — none of them track it as a frame-graph resource. A build that writes the same
+  (or a replacement) buffer earlier in queue order is invisible to them.
+- CPU: `DirectionalLightShadowmap` runs `compute_tight_near_far_clipping_planes` against
+  **`scene_ctx.tlas.bvh` — the CPU-side tree object** — per cascade per frame. The CPU dynamic tree
+  must therefore stay alive regardless of where the GPU buffer comes from.
+- Culling: **none**. `graph_mesh_frustum_cull`, HZB filtering, and bucket classification are flat
+  sweeps over the `meshes` table; `grep bvh src/shade/renderer/rasterize` is empty. "Culling stays
+  compatible" is satisfied vacuously — and equally, no raster-side test will catch a TLAS
+  regression; RT consumers are the only canaries.
+
+### 2.2 CPU algorithms already in the tree (the semantic reference implementations)
+
+`src/core/bvh2/bvh3/`:
+
+- **`ebvh_build_hierarchy_radix.js` — Karras 2012 binary radix tree, complete and spec-tested.**
+  `delta()` with the index tiebreak for duplicate morton codes
+  (`ci === cj ? 32 + clz32(i ^ j) : clz32(ci ^ cj)`), `determineRange` (exponential probe + binary
+  descent), `find_split` (binary search). The in-source comment pins a real trap: do **not**
+  midpoint-split duplicate-code runs — it desynchronises from `determineRange` and produces a
+  shared-node non-tree. This file is, line for line, the hierarchy-emission kernel of the GPU
+  build; the GPU version is a transliteration with an index-layout change (§4.3).
+- **`ebvh_optimize_treelet.js` — Karras & Aila 2013 treelet restructuring**, treelet size 7,
+  the exhaustive subset-DP with the paper's constants (`C_int = 1.2`, `C_prim = 1.0`), greedy
+  largest-surface-area treelet formation. This is the same algorithm — same constants — that the
+  DXR Fallback runs as its GPU `TreeletReorder` pass. Phase 2 is a port of semantics that already
+  have a CPU oracle and a `.spec.js`.
+- `build_triangle_morton_codes.js` + `v3_morton_encode` (magic-bits): 30-bit morton, 10 bits/axis,
+  `x | y<<1 | z<<2`. The WGSL side already has the matching expander:
+  `shader/chunk/binary/chunk_split_by_3.js`.
+- `ebvh_update_hierarchy_bounds.js` / `refit_radix_tree` (inside the radix builder): sequential
+  forms of the bottom-up refit.
+- `BVH.js`: 10-word AoS nodes (bounds ×6, parent, child_1, child_2/user_data, height),
+  free-list allocation, `allocate_linear` bulk path, SAH-guided `insert_leaf` with
+  `balance_rotate` (Kensler/Box2D-style SAH rotations) — the **dynamic** tree that
+  `GPUInstancesAccelerationStructure` maintains incrementally and that CPU queries walk. It stays.
+
+The CPU→GPU flattening (`bvh2_compress.js` + `bvh_to_gpu_buffer.js`) is a pure 40→32-byte gather
+in slot order — CPU node index i **is** GPU node index i, free-pool holes are uploaded as garbage
+and never referenced, and the buffer is sized by `node_capacity`, not live count. Nothing anywhere
+depends on any particular node *ordering* — only on the format and the root convention. The GPU
+builder is free to choose its own layout (§4.3).
+
+### 2.3 GPU compute infrastructure already in the tree
+
+- **Frame graph** (`engine/graphics/render/frame_graph/FrameGraph.js` + shade's
+  `graph_*` recorder convention): one-shot record → `compile()` → `execute()`; passes run in
+  insertion order; each `ComputeShader.dispatch` opens its own compute pass, so WebGPU's implicit
+  inter-dispatch barriers do the synchronisation. `ShadeGPUCommandContext.create(graphics)` +
+  `cmd.encodeGraph(graph)` + `cmd.finish()` is the standalone idiom
+  (`test_radix_sort.js` is an 8-line template). Transient uniforms via
+  `encoder.allocateTransientValueBuffer(STRUCT, value)`; pooled transient buffers via
+  `BufferResourceDescriptor` (fresh buffers arrive zeroed; reused pool buffers honour the
+  descriptor's clear range).
+- **Sort: none (deliberately).** Commit `b6049214c` ("deleted partial and dead code") removed all
+  four sort variants — the OneSweep port included, because it had **no fallback path** (bare
+  decoupled lookback assumes forward progress). The engine's sorting direction is now: **build
+  around CSDLDF** — chained scan, decoupled lookback, *decoupled fallback*. The key-value radix
+  sort is therefore a deliverable of this project (§4.2.1), not a reuse. The deleted OneSweep port
+  remains reference material in history
+  (`git show 370542c3f:src/shade/renderer/gpu_primitive/sort/one_sweep/...`) — in particular its
+  digit-binning workgroup machinery and its two hard-won WebGPU lessons (the `subgroup_size`
+  private-var propagation fix; manual unrolling for Tint's uniformity analysis).
+- **Prefix scan — the surviving, blessed pattern**
+  (`gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js` + `shader_prefix_scan_csdldf.js`,
+  from the b0nes164 Decoupled-Fallback paper artifact): subgroup-first (shuffle/ballot,
+  `subgroup_size` builtin, `MIN_SUBGROUP_SIZE = 4` handling, the
+  `@diagnostic(off, subgroup_uniformity)` idiom), per-partition **split flag words** (two
+  `atomic<u32>`s carrying READY/INCLUSIVE flags plus 16-bit value halves), bounded spin
+  (`MAX_SPIN_COUNT = 4`, `LOCKED/UNLOCKED`) and then **fallback: the blocked workgroup reduces the
+  missing predecessor tile itself** — progress guaranteed with no scheduling-fairness assumption.
+  Inclusive-only, `{count: u32, elements: array<vec4u>}` layout (16-byte aligned), partition size
+  4096, indirect-dispatched. This shader is the in-repo template the sort's spine and protocol are
+  built from.
+- **Indirect dispatch** (`gpu_primitive/indirect/IndirectComputeCommandBuildPass.js`):
+  count-buffer → `STRUCT_DISPATCH_COMPUTE_COMMAND`, with `graph_build_indirect_dispatch_command`
+  and `ComputeShader.dispatchIndirect`. Available; phase 1 does not need it (the instance count is
+  CPU-known at encode time), the BLAS phase does.
+- **Atomic f32 AABB merge** (`animation/skinning/bounds_refresh/chunk_aabb_atomic_f32.js`):
+  CAS-spin `aabb_atomic_min_f32` / `aabb_atomic_max_f32` over `atomic<u32>` cells holding plain
+  f32 bit patterns, plus `shader_meshlet_bounds_reduce.js` as the proven
+  reduce-then-atomic-merge pattern — this is the scene-AABB pass, essentially verbatim, with one
+  upgrade: that shader predates the subgroups baseline and reduces through workgroup memory only
+  (its own comment concedes subgroup ops would be faster); the builder's variant puts
+  `subgroupMin/Max` in front, workgroup memory only across subgroup boundaries. The same file
+  also demonstrates the "same buffer bound as `array<atomic<u32>>` in one pass and as typed
+  structs in another" idiom the refit pass uses.
+- **Scene database** (`GPUSceneContext` / `SCENE_DATABASE_SPEC`): the `meshes` table row already
+  carries `bounding_box: array<f32,6>` (world-space) and is refreshed GPU-side by
+  `shader_refresh_all_mesh_bounds` for GPU-authority content — the build's input, already resident.
+- **Shader authoring**: `CodeChunk` dependency DAG, `ShaderResourceSetDescriptor`,
+  `WebGPUStruct/Array` with correct WGSL layout math, `ComputeShader.from({...}).dispatch(...)`.
+- **Validation tiers** (the standing rule: a vitest spec may not stand up a real GPU device):
+  (a) tree-sitter WGSL parse + `validate_wgsl_source` (`src/shade/wgsl/`) in vitest;
+  (b) **`ComputeShaderEmulator`** (`src/shade/wgsl/emulator/`) — compiles WGSL to JS and executes
+  it point-wise; not a full implementation (no subgroups, no real barrier scheduling), but exactly
+  right for executing *specific functions and chunks* against CPU oracles, and whole kernels when
+  they are pure per-invocation functions;
+  (c) **`SoftwareGPUDevice`** (`src/shade/device/mock/`) — a recording software `GPUDevice`
+  (encoders, bind groups, buffers, mapping, timestamps, validation) that runs **none** of the
+  shaders: dispatches land on `SoftwareGPUComputePassEncoder.dispatches` for assertion. The tier
+  for host-side orchestration: encode the real frame graph against it and assert the dispatch
+  sequence, bindings, buffer sizes/usages, and host-written bytes;
+  (d) browser playground verify functions (FrameGraph + `graph_import_typed_buffer` +
+  `graph_inspect_gpu_buffer` readback + CPU assertions, registered as lil-gui "review checks");
+  `gpu_test.js` offers a standalone device bootstrap. GPU timing via `GPUTimer` +
+  `encoder.enable_debug_timers` (note: the `timer` argument `graph_compute_pass` forwards is
+  silently dropped by `ComputeShader.dispatch` — use the debug-timers path).
+- **Morton chunks** (`shader/chunk/bvh/morton/`): the fixed 10-bit `chunk_v3_morton_encode`,
+  spec'd bit-exact against `v3_morton_encode_magicbits`, is what the build uses (§4.2) for exact
+  CPU parity, alongside the 2D encode/decode pairs. A WGSL port of the DXR Fallback's
+  *adaptive-bits* `CalculateMortonCodes.hlsli` also lived here (the repo has been absorbing
+  reference #1 for a while) — `chunk_calculate_morton_code` plus its
+  `chunk_get_morton_codes_from_unit_coord` dependency, which never passed WGSL validation
+  (`if (bit)` on a `u32`; an f32/u32 `min` mix upstream). Both were unused and are now deleted (§8).
+
+### 2.4 What does NOT exist yet (the actual gaps)
+
+1. A **key-value radix sort** built around CSDLDF (§4.2.1) — the largest single new piece since
+   commit `b6049214c` removed the fallback-less OneSweep port. A first-class `gpu_primitive/sort`
+   deliverable in its own right, with the builder as its first consumer.
+2. A WGSL **3D morton encode** chunk composing `chunk_split_by_3` (2D variants exist; 3D does not).
+3. A **scene/leaf AABB reduction** pass (pattern exists in `shader_meshlet_bounds_reduce`; the
+   general primitive does not).
+4. The **hierarchy emission** kernel (CPU version exists; WGSL does not).
+5. The **bottom-up refit** kernel (no GPU refit exists anywhere in the tree).
+6. Orchestration: a `graph_bvh_build_*` recorder and the `GPUInstancesAccelerationStructure`
+   integration, including a live-instance-rows input (§4.1).
+7. The **treelet optimisation** kernel (phase 2; CPU version exists).
+8. A BVH2→BVH8 **collapse** pass (phase 4; traversal-side `BVH8_INODE_STRUCT` +
+   `chunk_bvh8_node_intersect` + `chunk_bvh8_ray_query_blas_occlusion` already exist as an
+   unwired experiment).
+
+Scan (with the fallback discipline), reduction idiom, atomic-f32 min/max, indirect dispatch,
+struct/layout codegen, graph plumbing, readback, four validation tiers, CPU oracles: all exist.
+Phase 1's slice is the sort plus five small builder shaders (items 2–5 and an init pass) and one
+integration; items 7–8 belong to later phases.
+
+---
+
+## 3. Research: the references
+
+### 3.1 Microsoft D3D12 Raytracing Fallback Layer (`D3D12RaytracingFallback/src`)
+
+The most directly relevant reference — same output shape (binary BVH, 32-byte nodes, software
+stack traversal with `TRAVERSAL_MAX_STACK_DEPTH 32`), and, remarkably, the same two core
+algorithms meep already has on CPU. ~5,400 LOC total for the GPU build path (~26 compute PSOs);
+the meep port is far smaller because sort, ingestion, and orchestration already exist.
+
+Pipeline (`GpuBvh2Builder::BuildBVH`), identical skeleton for TLAS and BLAS:
+
+1. **Load elements** — per-geometry dispatches decoding VB/IB into a flat `Primitive[]` scratch
+   (BLAS), or one dispatch loading instance descs, dereferencing each BLAS root box, transforming
+   its 8 corners to world space, and pre-inverting the transform (TLAS).
+2. **Scene AABB** — iterative 8:1 ping-pong reduction, O(log₈ n) dispatches.
+3. **Morton codes** — 30-bit, 10 bits/axis, centroid quantised into the scene AABB (an
+   adaptive-bits `SCALED_MORTON_CODES` variant exists but is dead code — meep carried an unused
+   WGSL transcription of that same variant until §8 deleted it).
+4. **Sort** — MiniEngine **bitonic** sort (indirect-dispatched), key=morton, payload=index. Not
+   radix — O(n log²n); the CSDLDF radix sort this plan builds (§4.2.1) is strictly better here.
+5. **Rearrange** — gather elements into sorted order (so leaves need no indirection), optionally
+   persisting the inverse permutation in the AS for later refit-only updates.
+6. **Hierarchy emission** — **Karras 2012**, cited by name in `BuildBVHSplits.hlsli`; one thread
+   per internal node; duplicate keys broken by index (same tiebreak as meep's CPU builder). Node
+   layout: internal nodes `[0, n-2]` (root = 0), leaves `[n-1, 2n-2]`. Children/parents written to
+   a separate 12-byte `HierarchyNode` scratch, not the final format.
+7. **Treelet reordering** (BLAS only, 0/1/3 passes by build flag) — **Karras & Aila 2013**, cited
+   by name; treelet size 7, 128-subset SAH DP in groupshared memory, **one 32-thread group per
+   treelet**, constants `Cbox = 1.2` / `Ctri = 1.0` (the very constants in
+   `ebvh_optimize_treelet.js`). Three dispatches per pass: clear; find-treelets (bottom-up climb
+   with `InterlockedAdd` arrival counters, emitting base-treelet roots once a subtree holds ≥
+   `7·2^pass` primitives); reorder (form treelet by repeatedly expanding the largest-area leaf →
+   subset DP → rewrite links → climb to the parent treelet within the same dispatch).
+8. **AABB fitting** — single-dispatch bottom-up refit: one thread per leaf climbs parent links;
+   `InterlockedAdd` on a per-node arrival counter; first arrival terminates, second proceeds with
+   both children guaranteed written. Buffers declared `globallycoherent`. Also the entire
+   refit-only update path (`PERFORM_UPDATE`): topology frozen, leaves written through the cached
+   sort permutation, only this pass re-runs.
+
+Portability notes that shaped this plan: the builder uses **no wave intrinsics at all**
+(threadgroup size 64 chosen as "safest across vendors") — everything except the sort is portable
+compute; the load-bearing hazard is `globallycoherent` + relaxed-atomic handshakes for the refit
+and treelet climbs, which WGSL can only approximate (§7, R1); the leaf-collapse half of their
+treelet pass (multi-triangle leaves) was never finished (`MAX_TRIS_IN_LEAF 1`), so their shipped
+trees are 1-primitive-per-leaf — same as meep's format; their per-node layout differs (center/
+halfDim, leaf flag in the high bit) but nothing in their pipeline depends on it — the algorithms
+transfer to meep's min/max + `child_1`-sentinel format unchanged.
+
+### 3.2 AMD GPURT (`GPUOpen-Drivers/gpurt`, dev branch, 2026-08 snapshot)
+
+The production reference — the shared BVH library under AMD's D3D12 and Vulkan RT drivers.
+Verified against source (a full snapshot sits in the session scratchpad). What it teaches, sorted
+by relevance to meep:
+
+**Build-mode architecture.** One shared 64-byte scratch-BVH2 node representation; three builders
+over it as a quality dial: `Linear` = **`BuildFastAgglomerativeLbvh.hlsl`** — an *Apetrei-style*
+single-pass LBVH (bottom-up walk from leaves; parent chosen by comparing adjacent-code deltas;
+first arrival does `InterlockedExchange` on a propagation flag and dies, second arrival owns the
+parent and fits its AABB inline — no separate refit dispatch), with **the identical duplicate-key
+index tiebreak meep's CPU builder uses** (`32 + clz(i ^ j)`); `PLOC` (TG = 256, radius ≤ 10,
+LDS-windowed nearest-neighbour merging, phased task queue); `HPLOC` (TG = 32 = one wave, the
+HPG 2024 algorithm of §3.3). Selection: fast-build and small builds → Linear; fast-trace → PLOC;
+HPLOC as the single-dispatch compromise. **No treelet restructuring exists in GPURT, and the
+older top-down/triangle-splitting builders have been removed from current branches** — the
+quality story is entirely "better sort order + PLOC-family clustering + wide-node encode".
+
+**Morton codes.** Default is **variable-bit** morton (axes sorted by extent; leading bits granted
+to dominant axes before regular interleave — the productionised form of the adaptive scheme the
+DXR Fallback left as dead code, and which meep's since-deleted `chunk_calculate_morton_code`
+transcribed), with
+optional surface-area "size bits" interleaved into 64-bit keys. 30-bit codes remain a supported
+end-to-end path. Degenerate/inactive primitives get sentinel codes sorting to the end; identical
+centroids quantise to 0.5.
+
+**Sorting.** 4-bit-digit LSD radix (8 passes for 30-bit keys) with a decoupled-lookback scan *or*
+barrier-based hierarchical scans as the portable fallback — and, notably, batched builds always
+use an LDS **merge sort** instead ("merge sort outperforms radix sort in most cases in the
+batched builder"; radix only wins in their parallel path above 50k primitives). Context for meep:
+their radix is a weaker configuration than the OneSweep/CSDLDF family (the successors to exactly
+this lookback-scan lineage); the datapoint says sort choice is not the quality lever — sort
+*order* (morton scheme) is.
+
+**Orchestration.** Two maintained execution strategies: a **batched multi-dispatch path** (one
+dispatch per phase, real barriers between phases) and **BuildParallel** (the whole build in one
+persistent-threads dispatch, phase-fenced by spin-loop "task loop" barriers on
+`globallycoherent` buffers). Their own structure is the portability verdict: everything
+single-dispatch leans on device-scope coherence plus inter-workgroup forward progress — neither
+guaranteed in WebGPU — while **the multi-dispatch path is the portable template**, which is
+precisely the shape meep's frame-graph pipeline takes. Small-build specialisations exist
+(whole-build-in-one-workgroup for ≤1024 primitives with an in-LDS sort; a 16-thread trivial
+builder for ≤16) — relevant later for per-geometry BLAS batching.
+
+**TLAS specifics.** Instance encode fetches the BLAS root bounds (RDNA4: a tighter KDOP-derived
+bound), transforms by the instance transform, writes scratch leaves, and atomically grows scene
+bounds using the monotonic sign-flip float→u32 mapping + `InterlockedMin/Max` (the cheaper
+alternative to meep's CAS chunk; both are portable WGSL). **Rebraid** runs before morton coding:
+instances are opened into up to `rebraidFactor` (4) leaves pointing at BLAS root children, budget
+distributed by a surface-area-difference priority — the production answer to the
+"huge overlapping instance" quality failure LBVH-family TLAS builds share (§3.3). Updates are
+pure refit via an update stack; topology is never touched — confirming the phase-3a shape.
+
+**Wide-node encode.** BVH2 → BVH4/BVH8 collapse by repeatedly opening the child with the largest
+surface area (`ApplyHeuristic`; 8-lane lane-groups cooperate per BVH8 node on RDNA4), producing
+128-byte quantised 8-wide nodes (12-bit child bounds against a shared per-axis 8-bit exponent,
+children implicitly contiguous). Different final format from CWBVH but the same collapse
+philosophy and the same "BVH2 scratch is canonical, wide is an encode" architecture this plan
+adopts.
+
+**Float16/f32 box nodes, triangle pairing, OBBs, DGF** — BLAS-leaf compression machinery, out of
+scope until phase 3b+, noted as the direction wide-format work eventually goes.
+
+### 3.3 Construction literature and WebGPU state of the art
+
+The field has converged, and the convergence is recent enough to matter:
+
+- **Karras 2012** (binary radix tree from sorted morton codes; one thread per internal node,
+  range/split by longest-common-prefix searches) is the canonical GPU emission kernel — what the
+  DXR Fallback ships and what meep's CPU builder implements. The duplicate-key index tiebreak is
+  mandatory on real content (identical instance positions collide long before 2^30 cells fill).
+- **Apetrei 2014** ("Fast and Simple Agglomerative LBVH Construction") inverts it: one thread per
+  leaf walks *upward*, finding each node's parent in O(1) from adjacent-code deltas; an
+  `atomicExchange` handshake lets the second-arriving thread continue and fit the parent's AABB on
+  the way — **hierarchy emission and refit fuse into one kernel**, no binary searches, same
+  topology as Karras (different internal-node index assignment; arXiv:2402.00665 shows how to
+  recover Karras indexing inside it if wanted). No spinning anywhere → no forward-progress
+  assumption. This is the "speed of light" binary builder in AMD's terminology and the substrate
+  H-PLOC is built on.
+- **PLOC (2018) → PLOC++ (2022, Intel) → H-PLOC (2024, AMD)**: parallel locally-ordered
+  clustering — merge mutually-nearest neighbours within a search window of the morton-sorted
+  cluster list, giving near-agglomerative SAH quality. PLOC++ fuses each iteration into one kernel
+  (chunked shared-memory NN search, encoded-atomicMin pair propagation). **H-PLOC** composes
+  Apetrei's upward walk with wave-cooperative PLOC merging of per-subtree cluster lists (threshold
+  T = wave_size/2, search radius 8), emitting the whole BVH2 in a single kernel: PLOC-class
+  quality at ~15% over raw-LBVH build cost. It is **the production default in AMD's stack** —
+  GPURT, and RADV as of Mesa 26.0 (Jan 2026; measured ~1 ms/frame TLAS savings, 2–5% total fps in
+  shipped titles). Measured TLAS scale: a BVH4 over **1M randomly-sized instances in 2.21 ms** on
+  an RX 7900 XT (LBVH: 1.96 ms); ~0.25 ms extrapolated at 100k. GPU TLAS builds at meep's scale
+  are cheap in absolute terms regardless of algorithm.
+- **Treelet restructuring (TRBVH 2013 / ATRBVH 2015) has been retired as a primary quality
+  mechanism by the field.** The H-PLOC paper's head-to-head: ATRBVH's BVH2 phase is **8.2–13×
+  slower than H-PLOC at indistinguishable SAH quality**, with structural waste (overlapping
+  treelets repeatedly rebuilt during the ascent). Where more quality is wanted, the literature
+  reaches for parallel reinsertion (PRBVH) offline, not treelets. This bears directly on phase 2
+  (§5.1, AR2).
+- **How much quality is actually at stake** (Meister & Bittner, JCGT 2022, GPU, secondary/
+  incoherent rays, normalized to LBVH = 1.00): PLOC 1.25, ATRBVH 1.39, binned SAH 1.43, SBVH 1.86
+  — with per-scene extremes near 2× on mixed-primitive-size content. Coherent primary rays show
+  much smaller spreads, and **widening the BVH compresses the gap** (at width 8: PLOC 1.21, SBVH
+  1.54 vs LBVH 0.98) — i.e. the eventual BVH8 phase partially launders binary-topology quality
+  differences. LBVH's specific failure mode is *highly varying primitive sizes* (morton codes see
+  centroids only); for heavily-overlapping or long-thin instances no bottom-up TLAS builder saves
+  you — production drivers attack that with **rebraiding** (opening a BLAS root so one instance
+  contributes several TLAS entries), a later, orthogonal lever worth remembering.
+- **Refit vs rebuild for TLAS**: NVIDIA's published best practice is to *rebuild* the TLAS per
+  frame rather than refit ("the cost savings to refit likely aren't worth sacrificing quality of
+  TLAS"); refit is for BLAS geometry that "bends but doesn't break". Matches this plan (§4, AR8,
+  phase 3a).
+- **Wide BVH**: everyone builds binary and converts; nobody constructs BVH8 directly. The
+  reference conversion is Ylitie/Karras/Laine 2017 — a bottom-up cost DP deciding each node's role
+  (allowing SAH-decided multi-primitive leaves), then top-down emission of **CWBVH**: 80-byte
+  8-wide nodes with child boxes quantised to 8 bits/axis against a per-node origin/scale, 1.9–2.1×
+  faster incoherent traversal at 35–60% of the memory. meep's dormant `BVH8_INODE_STRUCT` is
+  80 bytes — the experiment already targets this format, and CWBVH traversal in WGSL is proven in
+  the wild (albedo / tinybvh-rs). H-PLOC's single-kernel converter carries a genuine
+  forward-progress hazard (documented in the paper — resident consumers spin on resident
+  producers); the boring per-level-dispatch collapse (~log₈N ≈ 5–7 launches) is formally safe and
+  the right WebGPU answer.
+- **Sorting**: OneSweep (Adinets & Merrill 2022) is the single-pass state of the art and what
+  H-PLOC's own pipeline uses — but its bare decoupled lookback spins across workgroups; b0nes164
+  (whose port meep briefly carried before `b6049214c` removed it for exactly this) states it
+  "tends to run on anything that is not mobile, a software rasterizer, or Apple", and the
+  Linebender GPU-sorting survey reaches the same conclusion. The safe formulations are
+  reduce-then-scan (`DeviceRadixSort`) and — the one meep has standardised on — **CSDLDF**, the
+  decoupled-fallback protocol from b0nes164's Decoupled-Fallback paper, whose scan artifact is
+  already ported in-tree. The engine direction is to build the sort around that protocol
+  (§4.2.1). 32-bit keys are sufficient for TLAS at ≤1M instances; 64-bit keys (for dense BLAS
+  quality) cost ~3× in sort time and, in WGSL (no u64), mean chained two-word sorts — deferred
+  until phase 3b demands it.
+- **WebGPU state of the art: essentially every public WebGPU ray tracer builds its BVH on the CPU**
+  (three-mesh-bvh — GPU traversal only; WebRTX; strahl — whose published *CPU* build times,
+  327–383 ms for 1M triangles, are the cautionary tale; gnikoloff/re-ovo path tracers; tinybvh's
+  WGSL consumers). A WGSL GPU *builder* is near-unoccupied territory. Best porting bases found:
+  MircoWerner/VkLBVH (GLSL Karras LBVH, transliterates to WGSL almost mechanically), NexusBVH
+  (clean CUDA H-PLOC), and Nate Morrical's H-PLOC in Slang (Slang can emit WGSL), which notably
+  expects an external radix sort and recommends OneSweep.
+
+### 3.4 Synthesis — the choice
+
+**Phase 1 builds LBVH: morton → CSDLDF radix sort → Karras emission → arrival-counter refit.
+Phase 2 adds Karras & Aila treelet restructuring on top.** Reasons, in order of weight:
+
+1. **Zero algorithm risk.** Both algorithms exist in-tree as tested CPU implementations
+   (`ebvh_build_hierarchy_radix`, `ebvh_optimize_treelet`) whose semantics — including the
+   duplicate-key tiebreak that is the classic LBVH correctness trap — the GPU kernels
+   transliterate. The DXR Fallback is a complete worked example of the same two algorithms as GPU
+   compute, in the same 32-byte-node, stack-traversal setting.
+2. **Maximum reuse, one deliberate build.** Reduce idiom, atomic AABB merge, graph plumbing,
+   scan-with-fallback, validation tiers: existing meep facilities. The one sizeable new primitive
+   is the key-value radix sort — built around CSDLDF per the engine's sorting direction
+   (§4.2.1), as a first-class `gpu_primitive` whose first consumer is the builder and whose
+   spine/protocol come straight from the in-repo `shader_prefix_scan_csdldf`.
+3. **Subgroups-first; portability through the fallback discipline, not through avoidance.**
+   Subgroups are a baseline requirement of the engine — every kernel here uses them where they
+   pay (wave pre-reduction before atomics in the bounds pass, ballot/prefix machinery in the
+   sort's ranking, wave-aggregated allocation and subset evaluation in the treelet DP), following
+   the csdldf shader's established idioms (`subgroup_size` builtin handling down to
+   `MIN_SUBGROUP_SIZE = 4`, `@diagnostic(off, subgroup_uniformity)` where the analysis
+   over-approximates). What keeps the pipeline safe on weakly-scheduled hardware is the CSDLDF
+   fallback protocol — never spin without a bounded fallback — not renouncing wave ops. (The DXR
+   Fallback's zero-wave-intrinsics posture was *its* portability answer for 2018 D3D12; it is not
+   this engine's.)
+4. **Karras emission + separate refit over the fused Apetrei kernel — for phase 1.** Apetrei's
+   single fused kernel is objectively the leaner LBVH (§3.3) and the same topology. Karras wins
+   the *first* deliverable on de-risking grounds: the emission kernel is a pure, atomic-free
+   function of the sorted keys, which makes it (a) a line-for-line transliteration of the spec'd
+   in-repo oracle and (b) executable on the WGSL emulator in vitest — the strongest device-free
+   test this project can have, covering the classic LBVH correctness trap (duplicate-key
+   handling). The refit kernel it requires is not overhead: refit-only rebuilds (DXR's update
+   mode, phase 3a's skinned BLAS) need it as a standalone pass anyway. Apetrei is recorded as the
+   recognised follow-up optimisation (AR11) and the substrate H-PLOC builds on.
+5. **PLOC/H-PLOC deferred, seam kept swappable — with eyes open.** The PLOC family (which AMD
+   ships; §3.2, §3.3) produces better trees than raw LBVH and H-PLOC does it at near-LBVH cost.
+   It is deferred, not dismissed: it is a genuinely new algorithm with no in-repo oracle, a
+   wave-*width*-dependent structure (its cluster threshold is defined in terms of the runtime
+   subgroup size — a different thing from merely using wave ops, which are baseline here), and
+   real WGSL-uniformity porting friction — while LBVH+treelets reaches today's CPU quality bar
+   with two oracles in hand. The pipeline's seam — "sorted leaf
+   array in, BVH2 topology out" — is exactly where an H-PLOC stage would replace emission + refit
+   + treelets wholesale if the phase-2 gate argues for it (§6, AR2 carries the full argument and
+   the numbers).
+6. **BVH2 stays the canonical intermediate.** All references converge on this: build a binary
+   scratch BVH, then encode wide/compressed formats from it. Phases 3–4 consume the same
+   intermediate this phase produces.
+
+---
+
+## 4. Phase 1 — GPU TLAS build
+
+Replace steps 1–3 of `push_to_gpu()` with a GPU pipeline; keep the CPU dynamic tree for CPU
+queries; keep the CPU upload path as a fallback flag until phase 2 retires it.
+
+### 4.1 Inputs
+
+- **`meshes` table** (scene database buffer) — world AABB per row, already GPU-resident and
+  CPU-written each frame for CPU-authority rows (`GPUSceneContext.build()` runs, and submits,
+  before `tlas.update()` — queue order guarantees visibility), GPU-written for GPU-authority rows.
+- **Live rows list** — `array<u32>` of occupied `meshes` rows. `GPUInstancesAccelerationStructure`
+  already learns exactly this from `instance_add`/`instance_remove`; it keeps a compact
+  `Uint32Array` mirror and re-uploads it (small: 4·N bytes) only when membership churns
+  (`#membership_version`). Dead/reused rows never enter the build — no GPU-side liveness scheme is
+  invented.
+- Uniforms: `element_count = N`.
+
+Input AABBs come from the scene database rather than from the CPU tree's leaves deliberately: it
+is the single source of truth, it is correct for GPU-authority instances (the CPU is not), and it
+removes the per-frame dependency of the GPU build on CPU-side bounds bookkeeping. One-frame
+staleness for GPU-authority bounds (refreshed later in the frame than `tlas.update()` runs) is
+accepted in phase 1 — today's CPU build has *unbounded* staleness for those rows, so this is
+strictly an improvement; the follow-up that moves TLAS encoding after the bounds-refresh point in
+the frame is noted in §8.
+
+### 4.2 Passes
+
+New directory `src/shade/renderer/gpu_primitive/bvh/`, following the `graph_*`/`shader_*`/
+`chunk_*` conventions. The pipeline is one `graph_bvh_build_lbvh({graph, leaf_bounds,
+leaf_payload, element_count, nodes, root})` recorder plus a TLAS-specific extraction pass, so the
+BLAS phase reuses everything downstream of extraction.
+
+| # | pass | threads | what it does |
+|---|---|---|---|
+| 0 | `shader_bvh_extract_instance_leaves` | N | `row = rows[i]`; read `meshes[row].bounding_box`; write `leaf_bounds[i]` (6×f32) + `leaf_payload[i] = row`; merge into the 6-word scene-bounds cell via `subgroupMin/Max` pre-reduction → workgroup reduce → `chunk_aabb_atomic_f32` (the `shader_meshlet_bounds_reduce` pattern, subgroup-accelerated — GPURT's sign-flip monotonic `atomicMin/Max` encoding is the known cheaper alternative if the CAS ever shows up in a profile). Scene bounds seeded ±inf by an init clear. |
+| 1 | `shader_bvh_morton` | N | centroid of `leaf_bounds[i]`, quantised 10 bits/axis into scene bounds, `morton = split_by_3(x) \| split_by_3(y)<<1 \| split_by_3(z)<<2` via a new `chunk_v3_morton_encode` mirroring `v3_morton_encode_magicbits` exactly; `keys[i] = morton`, `values[i] = i`. |
+| 2 | `graph_radix_sort` | — | the rebuilt CSDLDF-based sort (§4.2.1). Keys 32-bit (30 used), values = leaf indices. Stable, ascending. |
+| 3 | `shader_bvh_emit_hierarchy` | N | Transliteration of `ebvh_build_hierarchy_radix` with the DXR index layout: internal node k at node k (k ∈ [0, N-2], root = 0), leaf j at node (N-1)+j. Thread i writes leaf node (N-1)+i (`bounds = leaf_bounds[values[i]]`, `child_1 = BVH_NULL_NODE`, `child_2 = leaf_payload[values[i]]`); threads i < N-1 additionally run `determineRange`/`find_split` (`delta` with the `32 + countLeadingZeros(i^j)` duplicate tiebreak — `clz32` ⇔ `countLeadingZeros`) and write internal node i's children plus `parents[child] = i` into scratch. Pure per-thread function of the sorted keys: no barriers, no atomics, no subgroups. |
+| 4 | `shader_bvh_refit` | N | One thread per leaf climbs `parents[]`; `atomicAdd` on a per-internal-node arrival counter (transient buffer, arrives zeroed); first arrival terminates, second recomputes the parent's AABB from its children and continues. All cross-workgroup-communicated words — node bounds and counters — are accessed through `array<atomic<u32>>` bindings (atomicLoad/atomicStore, f32 via bitcast), per the `shader_meshlet_bounds_reduce` idiom, never as plain loads/stores. **[deviation]** the `root = 0` header word is written by pass 3 instead — emission already writes plain node words and precedes the refit, and nothing reads the header in between. |
+
+Edge cases handled at encode time on the CPU: `N == 0` → skip the graph, write `root =
+BVH_NULL_NODE`. Consumers already handle `root == BVH_NULL_NODE` (empty CPU tree uploads it today).
+
+**[deviation]** `N == 1` gets no special case at all. It falls out of the same four passes: the
+sort has nothing to reorder and returns its input, emission's tail `if` skips the internal node and
+writes leaf 0 at node 0 with `parents[0] = BVH_NULL_NODE`, and the refit's single thread reads that
+terminator and stops. The host-written 36 bytes the plan called for would have had to take the
+bounds from the CPU tree, whose copy for a GPU-authority row can be arbitrarily stale — the whole
+reason this build reads the `meshes` table. The one thing `N == 1` actually needed was a counters
+buffer WebGPU will accept, so it is sized `max(1, N-1)`.
+
+### 4.2.1 The sort — `gpu_primitive/sort/`, rebuilt around CSDLDF
+
+Commit `b6049214c` cleared the ground; this project re-founds the directory with one blessed
+implementation. It keeps the deleted port's interface for continuity —
+`graph_radix_sort({graph, keys, values, element_count}) → {keys, values}`, u32 keys + u32 values,
+ascending, stable, result landing back in the caller's buffers — and is a first-class primitive
+with its own spec and verify harness (the deleted `one_sweep.spec.js` /
+`verify_radix_sort_one_sweep.js` in history are the direct templates for both).
+
+**v1 — reduce-then-scan on the csdldf spine** (the shipping shape). LSD radix, 8-bit digits × 4
+passes; per digit pass three dispatches: (a) per-tile 256-bin histogram (subgroup-accelerated,
+workgroup atomics); (b) spine scan of the `tile × bin` counts, flattened column-major so one scan
+yields global digit offsets and per-tile offsets together — run through
+**`graph_prefix_scan_csdldf` as-is** (its inclusive-only output consumed exclusively by
+subtracting own count; its `{count, elements: vec4u}` 16-byte-aligned layout adopted for the
+spine); (c) rank-and-scatter, with the workgroup ranking machinery adapted from the deleted
+binning shader in history (subgroup multi-split, and its two pinned WebGPU lessons carried over).
+Every dispatch is bounded; the only spin anywhere is csdldf's own bounded-spin-then-fallback.
+
+**[deviation]** the scatter's ranking is not the deleted port's per-wave-histogram multi-split. That
+formulation needs `workgroup_size / subgroup_size * 256` words of workgroup memory, which at the
+minimum subgroup size of 4 is 16 KB — the entire budget, with nothing left to stage keys in — which
+is precisely why the deleted shader carried a whole second `WLT16` code path with bit-packed
+half-radix histograms. What ships instead sorts the tile in workgroup memory with eight stable
+binary splits (256 threads × 4 keys = a 1024-key tile, ~10.3 KB of workgroup memory at any subgroup
+size). That makes a key's rank its sorted position, gets contiguous per-bin device writes for free,
+and lets the tail tile's padding be identified by position alone. Subgroups carry the wide part of
+each split's scan; the barrier-carrying loop over per-subgroup partials runs a *constant* trip count
+rather than one derived from `subgroup_size`, so no barrier sits under a bound a uniformity analysis
+has to reason about. Ballot-based peer aggregation in the histogram pass is the recorded upgrade
+there; v1 uses workgroup atomics.
+Roughly twelve smallish dispatches per sort against the removed port's seven — at TLAS scale
+(≤1M keys) this is tens of microseconds of difference, and it is correct on every scheduler.
+
+**v2 — single-pass digit binning with the fallback protocol** (recorded upgrade, not scheduled).
+OneSweep's chained per-(tile, bin) lookback with the Decoupled-Fallback protocol generalised to
+histogram vectors: split flag words per bin following the csdldf READY/INCLUSIVE rules, fallback
+re-reducing the stuck predecessor tile's histogram from its keys. Pursued only if a measured
+consumer (realistically: BLAS-scale triangle sorts, phase 3b) shows the spine passes matter.
+
+The sort ships before the builder consumes it — its own verify harness green in the playground,
+its shaders through all four validation tiers — so builder bring-up debugging never has to ask
+"is it the sort?".
+
+### 4.3 Output layout
+
+`[u32 root = 0][internal 0 .. N-2][leaf N-1 .. 2N-2]`, `2N-1` nodes exactly. This differs from the
+CPU path's slot-order-with-holes layout — legal, because (§2.1) nothing consumes ordering, only
+format + root word. Root is node 0 by Karras's construction (internal node 0 spans the whole
+range), which also natively satisfies the BLAS "root must be node 0, no header" convention when the
+same pipeline is pointed at geometry in phase 3.
+
+Buffers: the persistent output buffer keeps its `STORAGE | COPY_DST | COPY_SRC` usage and grows
+via `ensure_buffer_capacity` to `4 + 32·(2N-1)`; the staging copy disappears (the refit writes
+final bytes in place). Transients (graph-pooled): `leaf_bounds` 24N, `leaf_payload` 4N, keys/values
+4N each (+ the sort's own internals), `parents` 4·(2N-1), `counters` 4·(N-1), scene bounds 24 B.
+For N = 100k: ~5–6 MB transient, pooled and reused across frames — versus today's freshly
+allocated ~6.4 MB staging buffer plus its full-buffer copy on every rebuild, and versus the CPU
+milliseconds that dominate the current cost.
+
+### 4.4 Integration in `GPUInstancesAccelerationStructure`
+
+- `instance_add/remove/update` unchanged (CPU tree maintenance stays — `DirectionalLightShadowmap`
+  and any future CPU query walk it).
+- `push_to_gpu()` becomes: ensure output capacity → refresh rows buffer if membership churned →
+  `new FrameGraph()` → import rows + scene database + output → record extraction +
+  `graph_bvh_build_lbvh` → `ShadeGPUCommandContext.create` / `encodeGraph` / `finish`. Same frame
+  position (inside `GPUSceneContext.update`, after `build()`), same submit-per-change semantics,
+  same version guard. **`ebvh_optimize_treelet` no longer runs on the CPU tree** — the tree stays
+  a plain SAH-insertion/rotation tree, which is what its CPU consumers actually need.
+- ~~A module-level flag selects GPU vs legacy CPU upload~~ — **the legacy path is gone.** It
+  existed for one A/B; that A/B has been run (§4.6), the GPU build won on every axis at instance
+  scale, and the flag, the treelet call, the flatten and the whole-buffer upload went with it. It
+  was `TLAS_BUILD.use_gpu` — a settable field rather than the `const USE_GPU_TLAS_BUILD` boolean
+  the plan named, so the comparison could be a toggle in front of a running scene rather than an
+  edit and a reload. Anyone needing the comparison again recovers ~40 lines from history at
+  `23ab7bcd2`, the commit before the deletion. Subgroups are a baseline engine requirement, so there
+  is no "no-subgroups device" tier to serve: the legacy path (~40 lines) is deleted outright at
+  the phase-2 gate, flag and all.
+
+**[deviation]** `GPUSceneContext` needs two lines. The TLAS is constructed with `graphics`
+rather than `device` (the build has a frame graph to encode, which needs the buffer allocators), and
+`update()` is handed `scene_database_buffer` — the table the world AABBs live in, which the TLAS has
+no other way to reach. `GPUSceneContext`'s own API is unchanged, and consumers — every reader of
+`tlas.buffer`, and `DirectionalLightShadowmap`'s reader of `tlas.bvh` — need no changes.
+
+### 4.5 Validation
+
+Four tiers, each doing the job only it can do:
+
+1. **WGSL validity, vitest** (`bvh_lbvh.spec.js`, sort specs alongside): every new shader parses
+   (tree-sitter) and passes `validate_wgsl_source` as assembled — subgroup-using shaders
+   included; this is the tier that catches uniformity-adjacent assembly mistakes before a device
+   ever sees them.
+2. **`ComputeShaderEmulator`, vitest — functions and chunks first, whole kernels where pure.**
+   The emulator is not a full device, and that is its value: it executes *specific WGSL
+   functions* against CPU oracles. Chunk-level: `chunk_v3_morton_encode` vs `v3_morton_encode`;
+   the emission kernel's `delta` / `determine_range` / `find_split` chunks vs their counterparts
+   inside `ebvh_build_hierarchy_radix` — each as a directly-invoked function over randomized and
+   adversarial inputs (duplicate-key runs — the historical failure mode — first among them).
+   Kernel-level: `shader_bvh_morton` and `shader_bvh_emit_hierarchy` executed point-wise
+   end-to-end (both are barrier- and atomic-free pure functions of their inputs, which the
+   emulator schedules faithfully); full-tree topology compared against the CPU builder. The
+   refit and sort-scatter kernels are atomics/subgroups-bound and are *not* forced through the
+   emulator — their chunks that are pure (bounds merge math, digit extraction, rank arithmetic)
+   still get chunk-level emulator coverage.
+3. **`SoftwareGPUDevice`, vitest — the orchestration tier.** Encode the real thing against the
+   recording device: `GPUInstancesAccelerationStructure.push_to_gpu()` and
+   `graph_bvh_build_lbvh` run their actual FrameGraph against a `SoftwareGPUDevice`, and the spec
+   asserts what was encoded — dispatch sequence and group counts per pass, bind groups resolving
+   to the intended buffers, transient sizes/usages/clears, the rows-list upload happening only on
+   membership churn, and the `N == 0` / `N == 1` short-circuits (graph skipped, root word written
+   host-side — bytes the host wrote are assertable here; shader-written bytes are not, by the
+   mock's own contract). This tier pins the integration and the graph wiring in CI, where neither
+   the emulator (no host path) nor the browser (no CI) can.
+4. **Browser playground + end-to-end** — **[not run]** this tier is the human's; meep is a
+   library and the playground mounts in the host repo. Both harnesses are in place and registered.
+   (`verify_gpu_bvh_build.js` and `verify_radix_sort.js`, registered under "review checks"): randomized instance sets (duplicate positions, degenerate
+   AABBs, N ∈ {0, 1, 2, 3, powers of two ± 1, ~100k}); readback via `graph_inspect_gpu_buffer`;
+   assert structural validity (every leaf reachable exactly once; both children valid on every
+   internal node; parent AABB ⊇ children; root word correct), payload permutation correctness,
+   **depth histogram** (§7, R4), and SAH cost vs the CPU oracle on the same input — same sorted
+   order fed to both ⇒ topology must match node-for-node modulo the index mapping. Then the real
+   consumers: path tracer + RTX shadows on existing playground scenes, CPU-built vs GPU-built A/B
+   (the flag), image diff + `GPUTimer` numbers for build and trace.
+
+A `bvh_format.spec.js` locking the byte contract of §2.1 (today enforced only by the shaders
+themselves) is added alongside — it pins both the legacy compressor and the GPU layout to the same
+golden bytes.
+
+### 4.6 Acceptance
+
+- All four validation tiers green (sort and builder both); traversal-consumer A/B images
+  identical-or-better.
+- Depth histogram within the traversal stack budget on benchmark scenes — no silent traversal
+  truncation (R4).
+- Build time for 100k instances well under the CPU path's. Calibration from the literature
+  (§3.3): AMD measures a full quality-build TLAS over 1M instances at 2.2 ms on an RX 7900 XT,
+  ~0.25 ms extrapolated at 100k; raw LBVH ~15% cheaper still. WebGPU overheads on top are exactly
+  the novel data point this phase produces — measure with `GPUTimer`, don't assume.
+
+**Measured, 2026-08-26** — `verify_gpu_bvh_build` and `verify_gpu_tlas_build` on one machine, all
+58 builder cases and all 8 TLAS scenes PASS. One machine, one browser, and a harness that makes a
+separate submission per case: treat these as an order-of-magnitude reading, not a benchmark.
+
+- **Topology parity is exact.** Every case's SAH matches the CPU oracle's to the last reported
+  decimal, at every size and every shape — which is the node-for-node claim, since the SAH is
+  summed over the same internal nodes. Including 100k coincident instances.
+- **Build time, 100k scattered instances: ~0.15 ms** of GPU time across all 19 dispatches (morton
+  0.003, sort ~0.082 over four digit passes, emission 0.026, refit 0.040). That sits where §3.3's
+  extrapolation put a driver-class builder (~0.2 ms), which is the answer to "what do WebGPU
+  overheads cost" — apparently not much. Two outliers in the log (a 0.24 ms first scan and a
+  0.58 ms readback copy in one case) do not recur across the other three digit passes of the same
+  build and look like queue bubbles between the harness's per-case submissions; a real number for
+  the frame budget has to come from the in-frame path, not from here.
+- **The duplicate-key tiebreak works at scale.** 100,003 instances at *identical* positions — one
+  Morton code for the entire scene — build to depth 18, not depth 100,003. The depth histogram
+  (`8:1 9:2 12:32 13:128 14:1536 18:98304`, summing to exactly 100,003) is the binary decomposition
+  of the index range showing through, which is what `delta`'s `32 + clz32(i ^ j)` produces when no
+  code carries information. This is the failure mode the whole emission kernel is careful about,
+  now observed on a device.
+- **The ±inf seeding is confirmed.** The `far from origin` TLAS scene (700 instances in a 10-unit
+  cube offset ~9000 units from the origin) builds to a normal depth spread of 8..16. A zeroed
+  scene-bounds cell would have anchored the bounds at the origin, crushed every centroid into one
+  Morton cell, and produced the flat single-depth histogram the coincident case shows.
+- **Depth.** 100k scattered instances build to **depth 22 of the 32-entry stack**, and 20k to
+  depth 20. The stack is shared with the BLAS within one query and the occlusion path truncates
+  silently past it, so this is a real output constraint — but see the A/B below, where the legacy
+  CPU tree turns out to be the *deeper* of the two.
+
+**Consumer A/B, 2026-08-26** — `sponza_path_trace`, path tracer, same camera, same frame, toggling
+`TLAS_BUILD.use_gpu` under the running scene. Images verified equivalent by inspection. Frame times
+are medians of three runs; SAH is the sum of internal-node surface areas, which over a fixed leaf
+set is the term that differs between two trees.
+
+Sponza as it ships — **103 instances**:
+
+| | GPU LBVH | CPU pipeline (insertion + rotations + treelets) |
+|---|---|---|
+| SAH | 43,409 | 22,414 |
+| max depth | 13 | 20 |
+| traced frame | 69.5 ms | 70.6 ms |
+
+Sponza plus **20,000 scattered boxes** at sizes spanning two orders of magnitude — the shape that
+troubles a Morton order most, and enough instances that traversal cost is in the TLAS rather than
+in the per-mesh BLAS:
+
+| | GPU LBVH | CPU pipeline |
+|---|---|---|
+| SAH | 713,765 | 941,015 |
+| max depth | 20 | 27 |
+| traced frame | **132.6 ms** | 176.1 ms |
+| rebuild, wall clock | **21.7 ms** | 161.2 ms |
+
+Read together these say something the plan did not anticipate. At ~100 instances the GPU tree's SAH
+is 1.9× the CPU tree's and the traced frame times are identical — the regression AR1 predicted,
+and invisible, because a TLAS that small is not what traversal spends its time in. At 20k the
+ordering **reverses on every axis**: the GPU tree is 24% better by SAH, seven levels shallower, and
+25% faster to trace.
+
+Why: the CPU tree is built by incremental SAH-guided insertion with local rotations. At a hundred
+instances that is close to optimal. At twenty thousand it is a greedy, order-dependent construction
+whose mistakes rotations only locally repair, while the LBVH's global Morton ordering does not
+degrade. The treelet pass on top buys 2.4% (22,954 → 22,414 over two passes on the 103-instance
+scene) — it repairs neighbourhoods, not a bad global shape.
+
+Note also the depth column: at 20k the *legacy* tree reaches depth 27 of a 32-entry stack shared
+with the BLAS, leaving five. R4's cliff is real, and the GPU build moves away from it rather than
+toward it.
+- Known, documented, temporary quality dip vs the treelet-optimised CPU tree (raw LBVH SAH cost is
+  worse; phase 2 exists to close exactly this). The flag stays available until phase 2's gate.
+
+---
+
+## 5. Phases 2–4
+
+### 5.1 Phase 2 — tree quality optimisation on the GPU
+
+> **Checkpoint, 2026-08-26 — the premise did not survive measurement.** This phase was committed to
+> on the expectation that phase 1 ships a quality regression which treelet restructuring then closes
+> (AR1, AR2, R3). §4.6's A/B says otherwise: at instance scale the GPU LBVH is *better* than the
+> CPU pipeline it replaced — 24% better SAH, seven levels shallower, 25% faster to trace — and at
+> the small end where it is worse by SAH, the difference does not reach the frame. The gate this
+> phase was to be judged against ("SAH cost within noise of the current CPU pipeline, and
+> traversal-heavy consumers at parity or better frame time") is **already met, without treelets**.
+>
+> What follows is therefore no longer a committed plan. It is what phase 2 *would* be, kept because
+> the reasoning is still sound where a case for it exists, and the decision belongs to whoever picks
+> the project up next. The three ways forward, in the order the evidence supports them:
+>
+> 1. **Do nothing here and delete the legacy path.** — **taken.** The legacy CPU upload and
+>    `TLAS_BUILD` are gone; phase 3 is the next work.
+> 2. **Take the quality work to the BLAS instead.** Everything above is a statement about a TLAS —
+>    thousands of leaves, and leaf *boxes* rather than leaf shape dominating. A BLAS is millions of
+>    triangles, where the literature's LBVH-vs-PLOC gap (§3.3) was measured and where it should
+>    actually bite. If PLOC/H-PLOC is worth building, that is where its case is.
+> 3. **Build it anyway, for a workload not yet measured.** Content with far more instances, or with
+>    heavy overlap, could still find the LBVH's weak spot. That case has to be produced and measured
+>    first; `sponza_path_trace`'s box-scatter control is the tool for it.
+>
+> The seam holds whichever of the rest is picked up later: "sorted leaf array in, BVH2 topology out" is where any of this plugs
+> in, and nothing about extract/morton/sort or the output contract has to move.
+
+The treelet port, in the DXR Fallback's GPU formulation (§3.1, step 7), appended to the phase-1
+graph after refit:
+
+- **Pass A — clear**: zero treelet counters/list.
+- **Pass B — find base treelets**: one thread per leaf climbs `parents[]` with arrival counters
+  (the refit trick again), accumulating subtree primitive counts; on crossing the
+  `min_prims_per_treelet` threshold, appends the node to the base-treelet list via an atomic
+  cursor and stops.
+- **Pass C — reorder**: one **32-thread workgroup per base treelet**: form the 7-leaf treelet by
+  greedy largest-area expansion; evaluate all 128 subset AABBs/areas cooperatively; run the
+  subset-partition DP (`partition = (partition - delta) & s` enumeration — identical to the CPU
+  code); rewrite the ≤6 internal nodes' links and bounds; climb to the parent treelet via arrival
+  counters and repeat. Workgroup memory is the correctness layer (the DP must not assume a wave
+  width — subgroup size ranges 4–128 at runtime); subgroup reductions/broadcasts accelerate the
+  subset-area evaluation and argmin steps per the csdldf idioms. All cross-group traffic through
+  `array<atomic<u32>>`, as in refit.
+- Iterations: quality knob, default 1 per build.
+
+Treelets were also the answer to the depth risk (§7, R4). That reading has changed too: the
+measured depths put the GPU build *below* the legacy tree, so shortening chains is no longer a
+reason to reach for them.
+
+### 5.2 Phase 3 — BLAS on the GPU
+
+Two sub-phases, in value order:
+
+- **3a — skinned-clone BLAS refit (per frame). DONE.** Built as planned, refit-only, with the
+  phase-1 refit pass unchanged. Four deviations, all recorded here because the code is what won:
+
+  - **The extraction pass writes node bounds directly, not a `leaf_bounds` array.** A refit has no
+    sort and no emission, so nothing consumes a separate array — `shader_blas_refit_leaf_bounds`
+    puts each triangle's box straight into the leaf node and the climb reads it there. It gets the
+    triangle id by reading the leaf's own `child_2` payload back, so no side table has to agree
+    with the tree about which leaf is which.
+  - **A clone gets its own *nodes*, but shares its source's *shape*.** Parents and leaf-node
+    indices are identical across every copy of a geometry — only bounds are per-instance — so
+    `GPUGeometryBVHManager` derives them once per source into two arenas of their own
+    (`bvh2_derive_topology`, which walks the compressed bytes from the root so the free list's
+    holes are never mistaken for leaves) and every copy points at that.
+  - **The BLAS map is keyed by geometry *id*, not by geometry.** A clone and its source share a
+    `MeshletGeometry` and collided on it. `obtain(owner, source)` now separates the identity a tree
+    is looked up by from the geometry it takes its shape from. This also fixed a live bug in the
+    `blas_lookup` table (`blas_lookup_indexing.spec.js`, commit `f1f247438`).
+  - **Both settings structs carry arena offsets.** `parents_offset` / `leaf_nodes_offset` join
+    `node_word_offset` for the same reason it exists: a build owns its arrays and passes 0, a refit
+    is a tenant in shared ones. Counters are sized by *node*, not by leaf — they are indexed by
+    node id, and a tree read off an arena numbers its nodes with holes in.
+
+  Verified on an NVIDIA Lovelace device by `src/shade/playground/skinned_blas_refit/`, which holds
+  the refit's root box against the bounds-refresh chain's independently computed box over the same
+  deformed vertices — two paths sharing no code, and `min`/`max` do not round, so the bar is bit
+  equality. Result: bit-identical at every sample, moving 0.39–0.80 of its own span between poses,
+  and all 28 105 internal nodes exactly their own children's union, which is what says the interior
+  holds and not merely the root. Four clones, four distinct arena regions on a uniform stride.
+
+  **Still open:** `shader_build_sdf` reads `blas_lookup[slot_index]` with an SDF atlas slot — a
+  third index space over a table that is now unambiguously indexed by geometry id.
+- **3b — full BLAS build (import/procedural).** Same `graph_bvh_build_lbvh` with a triangle
+  extraction pass (`leaf_payload = (meshlet << 8) | tri`, computed at extraction). Root lands at
+  node 0 with no header — the exact BLAS convention — because Karras emission puts it there. The
+  current CPU builder shapes the tree as meshlet-subtrees-under-a-top-tree; **no consumer depends
+  on that internal shape** (only on root-at-0 + the leaf payload encoding), so the GPU build's
+  global-morton tree is format-legal and expected to trace better. Verify `shader_build_sdf`'s
+  root-bounds read and the serialization adapter round-trip (GPU-built BLAS read back once at
+  import time for the on-disk cache) before flipping. Batch small geometries through one graph;
+  use `graph_build_indirect_dispatch_command` where counts live GPU-side.
+
+### 5.3 Phase 4 — BVH8
+
+Traversal-side artifacts already exist (`bvh8/webgpu/BVH8_INODE_STRUCT.js` — 80-byte compressed
+wide node — and `chunk_bvh8_node_intersect`, `chunk_bvh8_ray_query_blas_occlusion`,
+`chunk_ray_get_octant_inv4`, `chunk_sign_extend_s8x4`), currently unwired. The build side follows
+the references' shared design: **BVH2 stays the construction intermediate; BVH8 is an encode.**
+
+- **Collapse pass(es)**: bottom-up cost DP over the BVH2 (arrival-counter climb again) deciding
+  each node's role in the wide tree per Ylitie et al. 2017 (SAH-driven collapse to ≤8 children,
+  which is also where SAH-decided multi-primitive leaves enter, if the leaf format ever grows
+  them), then emission of the 80-byte compressed nodes — meep's dormant `BVH8_INODE_STRUCT` is
+  already CWBVH-shaped, and CWBVH traversal in WGSL is proven in the wild (§3.3). Conversion runs
+  as **per-level dispatches** (~log₈N launches, formally-safe inter-dispatch ordering) rather than
+  H-PLOC's single-kernel polling converter, which the paper itself flags for its forward-progress
+  requirement — the one place this plan deliberately declines a single-kernel formulation.
+  Quantised-box packing needs no `shader-f16` device feature (`pack`-family builtins suffice).
+  GPURT's encoder (§3.2) confirms the collapse heuristic — repeatedly open the child with the
+  largest surface area until the slots fill — and demonstrates the cooperative refinement
+  (8-lane groups per wide node) available if the per-level formulation ever needs the speed.
+- The JCGT data (§3.3) is the planning caveat worth repeating here: widening compresses the
+  quality differences between binary builders — so re-run the phase-2 quality debate's numbers on
+  BVH8 before spending further on binary-topology quality.
+- Ships **additively**: BVH8 buffers alongside BVH2, consumers migrate per-shader (occlusion /
+  RTX shadows first — the existing chunk is the occlusion variant), format compatibility preserved
+  throughout; BVH2 bindings retire only where no consumer remains.
+
+---
+
+## 6. Adversarial review
+
+The plan above already absorbed several rounds of self-challenge; the surviving objections and
+their dispositions, kept honest:
+
+**AR1 — "You're building LBVH in 2026; raw LBVH trees are noticeably worse than SAH trees, and
+phase 1 ships a quality regression."** **Measured, and largely wrong** — see §4.6's A/B: the
+regression appears only at ~100 instances, where it does not reach the frame, and reverses at 20k,
+where the GPU tree beats the CPU pipeline on SAH, depth and traced frame time alike. The objection
+was right that raw LBVH is worse than a *good* SAH tree; what it missed is that incremental
+insertion at scale does not produce one. Original disposition, kept for the record:
+the regression is temporary by design (phase 2 is the same PR series), bounded (TLAS-over-
+instances is the most LBVH-tolerant tier — leaf count is small and leaf AABBs, not leaf shape,
+dominate), measured (SAH + frame-time gates, not vibes), and reversible (flag). The alternative —
+shipping treelets in the same deliverable — was rejected for review size, not difficulty; the
+phases share every buffer.
+
+**AR2 — "The field retired treelets. AMD ships H-PLOC. You researched this and still plan a TRBVH
+port — that's sentimentality about in-repo code, not engineering."** The strongest objection in
+this review, and it gets the full numbers. Against the treelet plan: H-PLOC delivers ATRBVH-class
+quality with its BVH2 phase **8.2–13× faster** than the treelet approach (same codebase, same
+GPU, AMD's own measurements); RADV replaced PLOC with H-PLOC as the shipping default in Mesa 26.0;
+treelets have a documented GPU-stability history (the DXR pass carries "TDRs on AMD" workaround
+flags); overlapping treelets are rebuilt repeatedly during the ascent by construction. For the
+treelet plan: the transliteration-with-oracle argument is not sentiment — `ebvh_optimize_treelet`
+has a spec suite pinning the exact DP, the DXR Fallback is a complete worked GPU example of the
+same pass, the DP's cooperation pattern is workgroup-shaped and indifferent to wave width
+(whereas H-PLOC's cluster-list threshold is defined *in terms of* the wave size, which in WGSL is
+a runtime value ranging 4–128 — dynamic `T = subgroup_size/2` handling, degenerate at the low
+end, plus known uniformity-analysis friction; subgroups being the engine baseline makes wave ops
+free to *use*, but it does not make wave-*width-dependent algorithm structure* free to port), and
+at TLAS scale the 8–13× speed difference is ~0.5 ms vs ~0.06 ms — real but not decision-grade,
+while implementation risk is. Both paths clear
+the actual gate (SAH parity with today's CPU trees — the acceptance test is SAH-based either way,
+so the oracle advantage matters for *debugging*, not for *acceptance*). Disposition: treelet port
+stays the committed phase-2 path per the stated goal sequencing; **phase 2 opens with an explicit
+decision checkpoint** re-weighing H-PLOC (porting bases exist: NexusBVH in CUDA, Morrical's Slang
+implementation that can emit WGSL) now that phase 1 will have produced our own SAH/depth/frame
+numbers on our own scenes; and the seam is pre-committed so that whichever loses can be replaced
+without touching extract/morton/sort or the output contract. If meep had no in-repo treelet
+implementation, H-PLOC would be the phase-2 recommendation outright.
+
+**AR3 — "Cross-workgroup relaxed-atomic handshakes (refit, treelet climbs) are formally racy
+under the WGSL memory model — WGSL atomics are relaxed, there is no `globallycoherent`, no
+device-scope barrier."** Correct, and this is the plan's most serious technical risk (§7, R1).
+Disposition: (a) every production GPU builder ships this pattern (DXR: `InterlockedAdd` +
+`globallycoherent`; GPURT likewise), and D3D's guarantees here are not materially stronger than
+WGSL's; (b) the engine's line, drawn when `b6049214c` removed OneSweep, is precise and this
+design respects it: what was rejected was **unbounded waiting on another workgroup's progress**,
+not cross-workgroup communication through relaxed atomic words — csdldf itself communicates
+exactly that way, with bounded spin and a fallback. The refit/treelet climbs sit on the accepted
+side: arrival-counter handshakes have no spin at all (the losing thread exits; the winner's
+inputs are already written), so they assume atomic-word *visibility*, never scheduling fairness;
+(c) discipline: all cross-group-communicated state (bounds, counters, links during climbs) goes
+through `array<atomic<u32>>` accesses only, never plain loads/stores gated by an atomic — the
+strictest formulation available in WGSL; (d) the browser verify harness asserts structural
+validity per platform, and a formally-clean fallback (iterative per-level dispatches —
+inter-dispatch ordering is guaranteed by WebGPU) is sketched and cheap to add if a platform ever
+misbehaves. Not hand-waved: named, bounded, fallback designed.
+
+**AR4 — "The 32-slot traversal stack is shared TLAS+BLAS and your LBVH can exceed the depth the
+current balanced trees keep. Silent geometry drop-out is the failure mode."** The sharpest finding
+of the consumer audit (§2.1). Worst-case Karras depth over 30-bit keys with index tiebreaks is
+~30 + log₂(duplicate-run), far beyond 31 in adversarial clustering; today's rotation-balanced
+dynamic tree keeps ~1.44·log₂N. Disposition: depth histogram is a first-class assertion in the
+verify harness and an A/B metric on real scenes (phase 1 gate includes "no traversal truncation on
+benchmark scenes"); treelet restructuring (phase 2) actively shortens chains; and if real content
+ever approaches the cliff, `BVH_TRAVERSAL_STACK_SIZE` is a single constant whose 32→64 cost will
+be measured rather than feared. Note the cliff is *pre-existing* (deep TLAS+BLAS combinations can
+overflow today); the builder makes it measurable for the first time.
+
+**AR5 — "Reading instance AABBs from the scene database couples the TLAS to renderer-internal
+tables; the CPU tree's leaves were a clean input."** The coupling already exists — TLAS leaf
+payloads *are* `meshes`-table rows, consumed by `scene_read_mesh` in every traversal; bounds from
+the same row is less coupling, not more (one source of truth instead of two). And CPU-side bounds
+are simply wrong for GPU-authority rows. The builder core stays decoupled regardless: extraction
+is the only scene-aware pass; `graph_bvh_build_lbvh` itself takes flat `leaf_bounds`/
+`leaf_payload` and serves BLAS unchanged.
+
+**AR6 — "Keeping the CPU BVH is duplicated state — kill it."** Rejected: `DirectionalLightShadowmap`
+queries it per cascade per frame on the CPU, and the acoustic/probe systems use the same `BVH`
+class independently. What *does* die: the per-frame CPU treelet pass over it (phase 1), the
+full-tree flatten+upload (phase 1), and the legacy upload path plus its flag (phase 2). The CPU
+tree reverts to what it structurally is — a cheap incremental index for CPU queries.
+
+**AR7 — "The pipeline's backbone is a sort with a forward-progress assumption (tilers, Apple)."**
+This objection **won**, pre-emptively: the engine removed the fallback-less OneSweep port
+(`b6049214c`) and set the direction — build around CSDLDF. The sort is now a deliverable of this
+plan (§4.2.1) whose v1 has no unbounded spin anywhere except inside csdldf's own
+bounded-spin-then-fallback protocol, making it correct on every scheduler b0nes164's warning
+covers ("tends to run on anything that is not mobile, a software rasterizer, or Apple" — §3.3,
+about the removed formulation). The cost is honest: three dispatches per digit instead of one,
+tens of microseconds at TLAS scale, with the single-pass v2 recorded for the day a measurement
+demands it. What remains of the original objection is only schedule risk — the sort is new
+engineering on the critical path — carried as R2.
+
+**AR8 — "Per-frame full rebuild is wasteful; you should refit-update the GPU tree."** Rebuild-
+always is the references' default for TLAS (cheap at instance counts; immune to the
+quality decay that refit-only accumulates under motion) and is dramatically cheaper than what
+ships today. Refit-only (topology frozen, extraction + refit passes alone — both already exist in
+phase 1) is a knob this architecture gets almost for free, and phase 3a *is* that knob applied to
+skinned BLAS, where it matters. Deliberately not a phase-1 deliverable: no measurement yet says
+the rebuild is the bottleneck.
+
+**AR9 — "The emission kernel writes leaves and internals from one dispatch with divergent work
+per thread (thread i does leaf i and maybe internal i) — split it for clarity?"** No: one dispatch
+of N threads with a tail `if` is the canonical LBVH formulation (DXR ships it), avoids a second
+pass over the sorted arrays, and the emulator tier tests it as a pure function either way.
+
+**AR10 — "New directory `gpu_primitive/bvh/` — is that the right home, or is this a scene
+feature?"** `gpu_primitive/` is where engine-level, consumer-agnostic GPU algorithms live (sort,
+prefix_sum, indirect, hash_table); the builder is exactly that (TLAS and BLAS both consume it).
+Scene-specific extraction lives with the scene code. This mirrors how `graph_radix_sort` is a
+primitive while its callers own their data semantics — the "first-class member, not tack-on"
+requirement made structural.
+
+**AR11 — "Apetrei 2014 fuses emission and refit into one kernel with no searches and no spinning —
+you're knowingly shipping the two-kernel 2012 formulation."** Yes, knowingly (§3.4-4). What the
+fused kernel saves at TLAS scale is one small dispatch and some binary searches; what the split
+formulation buys is the project's best test story — the emission kernel is a pure function, so the
+vitest emulator tier executes the actual WGSL against the actual in-repo oracle, duplicate-key
+runs and all — plus a standalone refit pass that phase 3a and refit-only updates require to exist
+regardless. Apetrei changes neither topology nor the output contract, and is the natural
+optimisation to fold in during phase-2 work — note that GPURT's shipping `Linear` builder *is*
+the Apetrei formulation (§3.2), and it is H-PLOC's substrate, so effort spent there compounds
+toward AR2's alternative rather than against it.
+
+---
+
+## 7. Risk register
+
+| # | risk | mitigation |
+|---|---|---|
+| R1 | WGSL relaxed-atomic cross-workgroup visibility (refit/treelet climbs) is beyond formal guarantees | All-atomic access discipline; no unbounded waiting anywhere (arrival-counter losers exit); per-platform structural verification in the harness; per-level-dispatch fallback designed (inter-dispatch ordering is spec-guaranteed); precedent: csdldf ships on the same visibility assumption. See AR3. |
+| R2 | The sort is new engineering on phase 1's critical path (the fallback-less port was removed; nothing shippable exists today) | v1 deliberately assembled from proven parts — `graph_prefix_scan_csdldf` reused as-is for the spine, ranking/scatter machinery adapted from the deleted port in history, interface kept; ships and verifies before the builder consumes it; single-pass v2 deferred behind a measurement. See AR7, §4.2.1. |
+| R3 | ~~Phase-1 quality dip (raw LBVH vs treelet-optimised dynamic tree)~~ | **Retired.** Measured (§4.6): a dip at ~100 instances that does not reach the frame, and an improvement on every axis at 20k. See AR1. |
+| R4 | Tree depth vs the shared 32-slot traversal stack; occlusion path truncates silently | Depth histogram in verify harness + phase gates; treelets shorten chains; `BVH_TRAVERSAL_STACK_SIZE` bump is a measured last resort. Pre-existing cliff, now instrumented — and **measured**: 22/32 at 100k scattered instances, 20/32 at 20k (§4.6). Not a hypothetical any more. See AR4. |
+| R5 | GPU-authority bounds one frame stale at `tlas.update()` encode position | Accepted for phase 1 (strict improvement over CPU build's unbounded staleness); follow-up moves TLAS encoding after the bounds-refresh point in the frame. |
+| R6 | Degenerate inputs: N ∈ {0, 1}, all-identical centroids, zero-extent scene bounds | Explicit encode-time special cases; duplicate-run handling is the transliterated tiebreak, tested at emulator tier; zero-extent axes quantise to 0 like the CPU builder (scale = 0). |
+| R7 | `TerrainSystem3.spec.js` and similar pin current TLAS *trigger* behaviour in comments/asserts | Trigger semantics (`#version` guard) are preserved verbatim in phase 1; only the work done per trigger changes. Spec expectations re-checked at phase-1 PR. |
+| R8 | BLAS serialization round-trip (phase 3b) — GPU-built trees must reach the on-disk cache | Import-time readback path; serialized-BVH adoption is already format-first (bytes are adopted verbatim), so a format-identical GPU build slots in. |
+| R9 | Subgroup size is a runtime value (4–128) across devices; wave-width-baked assumptions break silently | Subgroups are used everywhere they pay, but algorithm *structure* stays workgroup-shaped unless width-guarded — the csdldf idioms (`subgroup_size` builtin, `MIN_SUBGROUP_SIZE` handling, `@diagnostic(off, subgroup_uniformity)` only where the analysis over-approximates) are the house style; wave-width-dependent designs (H-PLOC's `T = wave/2`) get this called out at their decision checkpoint (AR2). |
+
+---
+
+## 8. Cleanup and hardening backlog (folded into the phases)
+
+Doing this as a first-class citizen also means leaving the neighbourhood cleaner:
+
+- ~~Delete the dead/fallback-less sort variants~~ — **done** (`b6049214c` removed all four,
+  OneSweep included). The re-founded sort (§4.2.1) carries a `warn_limited` element-count guard
+  from day one, like the scan.
+- ~~Retire the deprecated pre-fallback scan pair once nothing references it:
+  `prefix_sum/v1/graph_prefix_scan_csdl.js` + `shader_one_sweep_prefix_scan.js`~~ — **done**; both
+  deleted. Nothing referenced either: the graph was the shader's only importer, and none of the
+  symbols the pair exported (`graph_prefix_scan_csdl`, `shader_one_sweep_prefix_scan`,
+  `ONE_SWEEP_UNIFORMS_STRUCT`, `PREFIX_SCAN_NUM_GROUP_THREADS` / `_NUM_ELEMENTS_PER_GROUP`) was
+  named anywhere outside the pair. Same no-fallback class the sort purge removed in `b6049214c` —
+  bare decoupled lookback, which assumes cross-workgroup forward progress. `graph_prefix_scan_csdldf`
+  / `shader_prefix_scan_csdldf` are the survivors and are what the sort's spine (§4.2.1) dispatches.
+- ~~Supersede the buggy, unused adaptive-morton chunks with the validated fixed-bit
+  `chunk_v3_morton_encode`~~ — **done**: the fixed-bit chunk is spec'd bit-exact against
+  `v3_morton_encode_magicbits`, and `chunk_calculate_morton_code` /
+  `chunk_get_morton_codes_from_unit_coord` are deleted. Neither had an importer — the pair only
+  imported each other — and the one textual reference outside it was a sentence in
+  `chunk_v3_morton_encode`'s doc comment, reworded with the deletion. Note that `chunk_split_by_3`
+  turned out to be invalid WGSL too (`x | x << 16` does not parse — WGSL gives `<<` and `|` no
+  relative precedence) and was fixed, since the Morton chunk composes it.
+- ~~Delete `GPUGeometryBVH.js`~~ — **done**. Its header claimed "Currently used"; nothing in the
+  tree named the class. It built a CPU per-geometry BVH over raw triangle indices
+  (`ebvh_build_for_geometry_morton`, then an optional treelet pass) with both of its tuning
+  constants pinned to `0` — so the treelet loop it carried was dead even to itself. The live BLAS
+  path is `meshlet_batch_to_bvh.js` building into `GPUGeometryBVHManager`'s arena, with
+  `GPUGeometryMeshletsBVH` as the per-geometry record.
+- ~~Decide the fate of `shader/chunk/bvh/packed/`~~ — **deleted**, all nine files; nothing imported
+  any of them. *Superseded*: it is a second, competing compaction of BVH2 — a 20-byte node (3 words
+  of packed bounds + 2 child words) beside the live 32-byte one — while §5.3 takes compaction in a
+  different direction, keeping BVH2 as the construction intermediate and making BVH8 an encode into
+  the 80-byte `BVH8_INODE_STRUCT` that already exists with traversal chunks to match. *Broken*:
+  `NOTES.md`'s leaf convention ("MSB is set to 0 in `child_1`") is not merely unimplemented, it is
+  *inverted* relative to §2.1, where a leaf is `child_1 == 0xFFFFFFFF` — MSB set — while an internal
+  node's child index has it clear; `packed_bvh_from_unpacked_node` copies `child_1` through
+  untouched, so nothing reconciles the two. *Correction* to the note this replaces: `shader-f16` was
+  a red herring — the pair is `pack2x16float`/`unpack2x16float`, core builtins needing no device
+  feature (§5.3 says the same of the BVH8 quantised boxes), and both halves validated clean against
+  `validate_wgsl_source`, extension list empty, before deletion. **Carry forward into §5.3**: the
+  one piece of real logic there, `make_f32_interval_f16_safe`, was wrong and carried its own
+  `FIXME` — it widens an interval by an *absolute* `FLT_EPSILON_16` (2⁻¹⁰, the f16 ULP at 1.0), but
+  f16 spacing scales with magnitude, so near 1024 (ULP 1.0) the nudge rounds away entirely and the
+  bound clips *inward*, dropping geometry from traversal. BVH8's quantised boxes need the same
+  conservative outward rounding, and it has to be directed rounding per magnitude — which is what
+  the routine's own TODO was pointing at in the DXR Fallback's `CpuBVH2Builder.cpp`.
+- ~~`prefix_sum/v1/test_prefix_sum.js` passes `element_count`/`timer` args that
+  `graph_prefix_scan_csdldf` does not accept~~ — **done** in the sort commit.
+- Sort v2 (single-pass digit binning with the per-bin fallback protocol, §4.2.1) — recorded
+  upgrade, gated on a measurement from a real consumer.
+- ~~Add `bvh_format.spec.js` locking the §2.1 byte contract~~ — **done**; it holds both producers
+  to the same golden bytes.
+- Extend `ComputeShaderEmulator` with sequential atomics (optional; would lift the refit kernel
+  into the emulator tier). Its bit-counting builtins (`countLeadingZeros` and siblings) were added
+  in phase 1 — `delta` is written in terms of `countLeadingZeros`, so the emission chunks could not
+  be executed at all without them.
+- `SoftwareGPUDevice` now accepts a `subgroups` requirement. It runs no WGSL, so the feature changes
+  nothing it emulates; refusing it left the orchestration of every subgroup-using pass untestable at
+  tier 3. The corollary for future specs: one that stands up a scene and calls
+  `GPUSceneContext.update()` must construct its device with `requiredFeatures: ['subgroups']`.
+- `Renderer` requests `Subgroups` as *optional*, so a device without it starts and then throws at
+  the first subgroup dispatch. That predates this work (the csdldf scan has the same property) and
+  is consistent with subgroups being a stated baseline, but it is the one place where the baseline
+  is not enforced where the device is created.
+
+---
+
+## 9. Deliverable sequence (summary)
+
+| phase | delivers | new shaders | gate |
+|---|---|---|---|
+| 1 | CSDLDF key-value radix sort (`gpu_primitive/sort` re-founded) + GPU TLAS build (LBVH); CPU treelet+flatten+upload retired from the hot path | sort: histogram, spine (csdldf reused), scatter; builder: extract, morton, emit, refit (+ init) | 4-tier validation green for sort and builder; A/B images clean; build-time win measured; depth instrumented |
+| 2 | GPU treelet optimisation; GPU path becomes default | clear, find-treelets, reorder | SAH + frame-time parity with today's CPU pipeline; legacy CPU upload path deleted |
+| 3a | Skinned-clone BLAS refit (per-frame correct animated BLAS) | triangle-leaf extract (refit reused) | deformed-mesh RT correctness on animation scenes |
+| 3b | Full GPU BLAS build (import + procedural) | (extraction variant only) | format + serialization round-trip; trace parity vs CPU-built BLAS |
+| 4 | BVH8 encode + consumer migration, additive | cost/collapse, encode | traversal win measured per consumer before migration |