@woosh/meep-engine 3.14.2 → 3.14.3

package/src/shade/renderer/geometry/bvh/BLAS_REFIT_BATCH_PLAN.md

@@ -0,0 +1,606 @@
+# Batched BLAS refit — one refit per frame, not one per tree
+
+> Status: **LANDED, VERIFIED ON DEVICE, REVIEWED TWICE** — 2026-09-02. `490907338` (this plan),
+> `c52ef1691` (P1, the climb chunk), `f42851a62` (P2, residency version and guard), `36d4796df`
+> (P3, the batch), `46ba62862` (P4, the switch and the deletions), `1c04040bd`, `d62a17ffe`,
+> `8377a3de0`, `40066161b` and `f5d343f40` (what the device session turned up, §7). P5: `verify()`
+> and `verify_leaves()` pass on an NVIDIA RTX 4090 at 256 dancers, the batch running as two
+> dispatch pages — §4. An adversarial review against the code preceded the work (twelve findings,
+> none blocking) and a second one followed the landing (thirteen, none blocking); both are folded
+> in below, with §7 as the ledger. §8 is the risk register. Deviations while landing are marked
+> **[deviation]**.
+>
+> Goal: the per-frame refit of every skinned clone's BLAS records a fixed number of commands, whatever
+> the number of skinned meshes — one transient buffer, one clear, one to three dispatches — and the
+> host does no per-tree work in steady state. Today it records two passes and a clear *per tree*, from
+> a CPU loop, which is the opposite of what the engine's GPU-driven frame is meant to look like and
+> becomes the frame's bottleneck somewhere in the low hundreds of characters.
+>
+> Scope: the skinned-clone refit that phase 3a of `GPU_BVH_BUILD_PLAN.md` landed. Full builds, the
+> TLAS, and non-skinning deformers are out of scope, though §3 keeps the door open for the last.
+
+---
+
+## 1. The problem
+
+`GPUMeshSkinningContext#record_blas_refits` (`animation/skinning/GPUMeshSkinningContext.js`) walks
+its binding list and calls `record_blas_refit` (`geometry/bvh/record_blas_refit.js`) once per bound
+mesh. Each call:
+
+1. asks the manager where the tree lives (`GPUGeometryBVHManager#get_refit_target`),
+2. dispatches `shader_blas_refit_leaf_bounds` over the tree's leaves,
+3. allocates a transient counters buffer sized to the tree's node count and clears it,
+4. dispatches `shader_bvh_refit` over the same leaves to climb.
+
+Every `ComputeShader#dispatch` in this engine is its own compute pass — `constructComputePass`
+begins a pass, sets the pipeline, resolves and sets the bind group, writes immediates, dispatches,
+ends: eight encoder calls per dispatch, one more for the clear, seventeen per tree, plus the
+bind-group descriptor hashing behind them and the transient allocation, which is host work rather
+than an encoder call. On the GPU it is two pass boundaries per tree, each of which orders every
+earlier write to the shared node arena before anything later can start.
+
+| per frame, `N` skinned meshes | today |
+|---|---|
+| compute passes | `2N` |
+| buffer clears | `N` |
+| transient allocations | `N` |
+| encoder calls, `N = 300` | ~5,100 |
+| host work | `O(N)`, every frame |
+
+The GPU side is the worse half. The trees are independent but never overlap: pass boundaries
+serialise them, and each boundary drains the pipeline. The leaf pass over the playground character
+(28,106 leaves, 440 workgroups of 64) fills a large GPU for a moment; the climb does not. It is a
+chain of dependent atomics as long as the tree is deep, and half the live threads exit at every
+level, so most of a climb is a long tail with the machine nearly idle. Serialising `N` of those
+tails is what a loop of per-tree dispatches costs, and the cost grows linearly in `N` no matter how
+small each tree is.
+
+"GPU-driven" here has a precise meaning, and it is not indirect dispatch. The workgroup count is a
+host-known function of the trees in the batch, so an indirect argument would buy nothing. What
+matters is that the command count is independent of `N`, that the host touches the per-tree data
+only when the set of trees changes or a tree's residency changes, and that the GPU sees one flat
+workload with every tree's leaves in it, so a small tree's climb overlaps the next tree's instead of
+waiting on a barrier.
+
+## 2. What already exists
+
+Everything the batch needs is in the tree; this is a rearrangement, not new machinery.
+
+- **The climb.** `gpu_primitive/bvh/shader_bvh_refit.js` — the arrival-counter climb, all
+  communicated words through `array<atomic<u32>>`, losers exit, no spin. Pass 4 of the LBVH build
+  and the second half of today's refit. Its per-tree offsets (`node_word_offset`,
+  `parents_offset`, `leaf_nodes_offset`) already exist precisely so that one kernel can serve a
+  tree that owns its buffer and a tree that is a tenant in an arena.
+- **The leaf box.** `chunk_geometry_read_triangle_bounds` reads the triangle a leaf's `child_2`
+  names and returns its AABB; it has its own emulator tests in `blas_refit_leaf_bounds.spec.js`.
+  The leaf kernel around it is a read, a call, and six stores.
+- **The arenas.** `GPUGeometryBVHManager` keeps every tree's nodes in one buffer and every distinct
+  shape's parents and leaf list in two more, and `get_refit_target(owner)` returns all five numbers
+  a refit needs for one tree, or `undefined` while it is not resident.
+- **The flat-dispatch idiom.** The skinning pass dispatches one workgroup per `(binding, meshlet)`
+  pair through a host-built `dispatch_lookup` table, and paginates past
+  `maxComputeWorkgroupsPerDimension` with a `dispatch_offset` immediate. The bounds-refresh chain
+  reuses the same table for its scatter and reduce passes. This is the shape the refit takes.
+- **Immediates.** `ShaderResourceSetDescriptor#setImmediate` carries a small per-dispatch struct or
+  a single `u32` without a buffer, capped at 64 bytes, which is how both refit kernels already take
+  their settings.
+- **The tiers.** The emulator runs the climb's atomics sequentially (`blas_refit_containment.spec.js`
+  drives both current kernels through it, one invocation at a time, and checks the bytes against
+  CPU oracles in `bvh2_check_bounds.js`); entry parameters arrive in declaration order, so a
+  kernel on `workgroup_id` and `local_invocation_id` is driven as `dispatch([wg,0,0], [lane,0,0])`;
+  an immediate is supplied as a binding of the same name; a struct array is an array of objects.
+  `SoftwareGPUDevice` records passes, dispatches, bind groups, group counts, immediates and
+  host-written bytes. It takes `requiredLimits` — lowered only: it refuses to report a limit above
+  the spec default — and it enforces neither the storage-buffer budget nor the workgroup cap, so a
+  spec can set `maxComputeWorkgroupsPerDimension: 4` and watch the pagination happen, and must
+  assert the budget and the cap itself. `src/shade/playground/skinned_blas_refit/` is the device
+  tier, with `verify()` holding the refit's root box bit-equal to the bounds chain's independent
+  box, and `verify_leaves()` holding every leaf's box to its triangle.
+
+## 3. Design
+
+### 3.1 Data
+
+Three tables, two of them persistent and rebuilt only when the batch changes, one transient.
+
+**Target rows** — one per tree in the batch, `BLAS_REFIT_TARGET_STRUCT`, 24 bytes:
+
+```js
+export const BLAS_REFIT_TARGET_STRUCT = WebGPUStruct.from({
+    // u32 word this tree's node 0 starts at in the node arena — what `get_refit_target` returns
+    node_word_offset: u32,
+    // this tree's parents in the parents arena, its leaf list in the leaf-node arena
+    parents_offset: u32,
+    leaf_nodes_offset: u32,
+    leaf_count: u32,
+    // this tree's arrival counters, in the batch's counters buffer — a prefix sum of node counts
+    counters_offset: u32,
+    // geometry row whose meshlets the leaf payloads index; for a clone, the clone's own row
+    geometry_index: u32,
+}, "BlasRefitTarget");
+```
+
+**Workgroup lookup** — one `(target_index, leaf_base)` pair of `u32` per workgroup, across every
+tree in the batch. Tree `t` contributes `ceil(leaf_count_t / 64)` consecutive entries with
+`leaf_base = 0, 64, 128, …`. A workgroup serves one tree and one aligned run of its leaves, so the
+target row is a workgroup-uniform read and the leaf-list read is coalesced. The tail workgroup of a
+tree idles at most 63 lanes; at 440 workgroups per tree that is nothing.
+
+**Counters** — one transient `array<atomic<u32>>`, `Σ node_count` words, each tree at its
+`counters_offset`. Sized by node rather than by leaf for the reason today's single-tree buffer is:
+counters are indexed by node id, and a tree read off an arena numbers its nodes with the free
+list's holes in. One `clearBuffer` covers all of them.
+
+### 3.2 The kernel
+
+One fused kernel, `shader_blas_refit_batch` (`geometry/bvh/shader_blas_refit_batch.js`, label
+`BLAS/RefitBatch`), workgroup size 64. Each lane finds its tree and leaf through the lookup, writes
+that leaf's box, then climbs:
+
+```wgsl
+@compute @workgroup_size(64, 1, 1)
+fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    // `dispatch_offset` is the immediate: workgroups already covered by earlier sub-dispatches
+    let pair = (wg.x + dispatch_offset) * 2u;
+    let target = targets[lookup[pair]];
+    let leaf = lookup[pair + 1u] + lid.x;
+
+    if (leaf >= target.leaf_count) {
+        return;
+    }
+
+    let leaf_node = leaf_nodes[target.leaf_nodes_offset + leaf];
+    let leaf_word = target.node_word_offset + leaf_node * BVH_NODE_STRIDE;
+
+    // the leaf already says which triangle it holds
+    let payload = atomicLoad(&nodes[leaf_word + BVH_NODE_CHILD_2]);
+    let box = geometry_read_triangle_bounds(geometries[target.geometry_index], payload);
+
+    bvh_node_store_bounds(leaf_word, box.min, box.max);
+    bvh_refit_climb(target.node_word_offset, target.parents_offset, target.counters_offset, leaf_node);
+}
+```
+
+The climb is not a second copy of `shader_bvh_refit`'s loop. It is lifted first, as its own
+no-behaviour-change commit (§6, P1), into `chunk_bvh_refit_climb` beside that kernel:
+
+```wgsl
+// Assumes module-scope bindings named `parents` (u32), `counters` and `nodes` (atomic<u32>) —
+// the same convention by which read_meshlet_triangle_bounds assumes `meshlet_metadata`.
+fn bvh_node_store_bounds(node_word: u32, low: vec3<f32>, high: vec3<f32>) { /* six atomicStore */ }
+
+fn bvh_refit_climb(node_word_offset: u32, parents_offset: u32, counters_offset: u32, leaf_node: u32) {
+    var node = parents[parents_offset + leaf_node];
+    loop {
+        if (node == BVH_NULL_NODE) { break; }                                  // past the root
+        let arrivals = atomicAdd(&counters[counters_offset + node], 1u);
+        if (arrivals == 0u) { break; }                                         // first arrival exits
+        // second arrival: both children are written; fit this node from them and continue
+        ...
+        node = parents[parents_offset + node];
+    }
+}
+```
+
+`shader_bvh_refit` then becomes a guard and a call — `bvh_refit_climb(settings.node_word_offset,
+settings.parents_offset, 0u, leaf_nodes[settings.leaf_nodes_offset + i])` — and the LBVH build is
+untouched in behaviour. The node-layout constants the chunk needs (`BVH_NODE_STRIDE`,
+`BVH_NODE_BOUNDS`, `BVH_NODE_CHILD_1`, `BVH_NODE_CHILD_2`) move into a `BVH_NODE_LAYOUT_DEFINITION`
+chunk in `gpu_primitive/bvh/`, beside `BVH_BUFFER_LAYOUT.js` it is generated from and the climb
+chunk that needs it, in the style of `BVH_NULL_NODE_DEFINITION`. The `BVH_` prefix is what keeps
+them clear of the unprefixed `NODE_*` copies in `shader_bvh_refit`, `shader_bvh_emit_hierarchy`
+and the playground's audit kernels; the kernels that import the climb drop their local copies,
+because a module-scope `const` declared twice is a WGSL error, and tier 1 is what catches it.
+
+Resources, all storage: `targets`, `lookup`, `leaf_nodes`, `parents` read-only; `counters` and
+`nodes` read-write and atomic; `geometries`, `meshlet_metadata`, `meshlet_data` read-only. That is
+**nine storage buffers in one stage**. The engine requests ten (`Renderer.js`,
+`maxStorageBuffersPerShaderStage: 10`) and `gpu_primitive/test/gpu_test.js` refuses an adapter with
+fewer, so the budget holds with one to spare. No device-free tier can see it — the software device
+neither counts storage buffers per stage nor accepts a limit above the spec default of eight — so
+the batch kernel's spec asserts the count its descriptor declares against the engine's floor (§5).
+If the budget ever tightens, the row can carry `meshlets_address` instead of `geometry_index` (it
+is `metadata.meshlets.metadata.offset`, the same number the skinning binding already caches) and
+`geometries` drops out; not done now, because reading through the geometry row is what keeps
+`chunk_geometry_read_triangle_bounds` and its tests untouched.
+
+No barriers, no workgroup memory. Subgroup ops are baseline in this engine and are used where they
+pay; the one place in a refit where they might is the bottom of the climb. `bvh2_derive_topology`
+lists leaves in pre-order, so two sibling leaves sit in adjacent lanes, and their parent — roughly
+half of all the handshakes — could be fitted from a shuffle without the counter round trip. That is
+a measured optimisation, not a design input: §9 records it behind P5's profile.
+
+### 3.3 The recorder
+
+`GPUBLASRefitBatch` (`geometry/bvh/GPUBLASRefitBatch.js`) owns the two persistent tables and
+records the frame's commands. It keeps `record_blas_refit`'s seam: an entry is an `owner` and a
+`geometry_index`, and nothing in the recorder knows what a clone is or why vertices moved.
+
+```js
+const batch = new GPUBLASRefitBatch(device);
+
+// whenever the set of trees changes — for skinning, whenever #bindings_dirty
+batch.set_entries([{ owner: binding.clone_metadata, geometry_index: binding.clone_geometry_index }, ...]);
+
+// every frame, in place of the loop
+const recorded = batch.record(cmd, { blas, geometries });   // boolean, as record_blas_refit's
+```
+
+`set_entries` copies the list, asserts no owner appears twice (two rows for one tree would race on
+its nodes), and marks the batch dirty.
+
+`record` first decides whether the tables are current: they are stale if the batch is dirty or if
+`blas.residency_version` (§3.4) has moved since they were built. Rebuilding is one host pass over
+the entries: `get_refit_target(owner)` per entry, entries that answer `undefined` or have no leaves
+are left out (the version bump brings them in when they become resident), `counters_offset` is the
+running sum of `node_count`, and the lookup gets one pair per 64 leaves. Both tables go up through
+`queue.writeBuffer`, into buffers grown by doubling, exactly as the skinning context's tables do.
+Then, every frame:
+
+1. if the batch has no workgroups, return `false`;
+2. `counters = cmd.allocateTransientBuffer(STORAGE, counter_words * 4)`, `cmd.clearBuffer(counters)`;
+3. for `offset` from 0 to `workgroup_count` in steps of `device.limits.maxComputeWorkgroupsPerDimension`,
+   `shader_blas_refit_batch.dispatch({ group_count_x: min(step, remaining), bindings: { dispatch_offset: offset, targets, lookup, leaf_nodes: blas.buffer_leaf_nodes, parents: blas.buffer_parents, counters, nodes: blas.buffer_data, geometries: geometries.buffer_metadata, meshlet_metadata, meshlet_data } })`.
+
+The manager's buffers are read off `blas` at record time because `ensure_buffer_capacity` replaces
+the `GPUBuffer` objects when an arena grows (it copies the old bytes across, so the arena *offsets*
+in the rows survive growth). What makes binding them *safe* is call order, not freshness: every
+place that replaces or destroys those buffers — `GPUGeometryBVHManager.update`, which grows all
+three arenas and submits its own copy, and `GPUGeometryManager.build`, which recreates the geometry
+metadata buffer — runs in `Renderer.#begin_frame` through `graphics.update()`, and in
+`GPUViewContext.update → GPUSceneContext.update`, both before the frame's command context is
+created; the refit is recorded into that context through `scene.tick`, and the context is finished
+after. The meshlet arenas the batch also binds are the one exception: a clone allocated during
+`tick` can rebuild them after the context exists, which is safe because nothing recorded earlier in
+that context binds them and the batch reads them at record time — and is why the refit stays after
+the skinning pass, whose own flush of pending clones comes first. `GPUMeshSkinningContext.update`
+already documents the hazard for the metadata buffer. A refit recorded anywhere else would not have
+that guarantee, the recorder's doc says so, and the software device could not catch a violation,
+since it executes nothing at submit.
+
+### 3.4 Two additions to the manager: `residency_version` and a residency guard
+
+The rows depend on what `get_refit_target` answers, and that answer changes in three places, all
+host-side: a topology is uploaded (`#upload_pending_topology`), a tree's nodes are uploaded
+(`update`), a tree is removed (`remove`). `GPUGeometryBVHManager` gains a monotonic
+`residency_version`. Both uploads report whether anything became resident, and `update` bumps the
+version once when either did — the node upload is a method of its own, so a frame that uploads only
+a shape counts; `remove` bumps when it actually removed something. The batch compares. No queue, no
+dirty set of owners: a version is the smallest thing that says "ask again".
+
+The version is coarse on purpose. Any tree's residency change makes the batch rebuild both tables,
+so a frame that streams in an unrelated geometry costs one host pass over the entries and a lookup
+upload — a megabyte at 300 characters. That is the trade for never asking per entry per frame, and
+§5 pins it, so nobody later narrows the trigger into a stale-row bug.
+
+The guard closed a hole the batch would otherwise have inherited and trusted. As landed at P2,
+`#register` snapshotted `source.bvh` at `obtain` time, `update` uploaded that snapshot, and
+`MeshletGeometry.bvh` defaults to an empty buffer — so an owner obtained before its bytes existed was
+marked resident over a zero-length region at the arena's end, and once the bytes arrived and the
+shape was derived from them live, `get_refit_target` answered with the shape's counts at an address
+whichever tree was appended next now occupied. P2 made `get_refit_target` refuse a record whose
+uploaded byte length disagrees with the shape. The landing review found the same address still
+went into the ray lookup (§7, R5), and the fix went one level down: the upload now reads the
+geometry's tree when it runs, a record whose geometry has none stays queued until it has one, and
+the lookup names an empty tree at node 0 of the arena meanwhile. The guard remains, as a second
+check that costs nothing.
+
+### 3.5 The skinning context
+
+`#record_blas_refits` becomes a call into a `#refit_batch` the context owns; `set_entries` runs in
+the `#bindings_dirty` branch of `update`, beside the other table uploads that depend only on the
+binding list; `destroy` destroys the batch. The `geometries.blas === undefined` guard stays — with
+BVH support off there is nothing to refit. The refit stays where it is in the frame, after the
+bounds-refresh chain, for the reason the comment there gives and for the ordering §3.3 relies on.
+
+### 3.6 What gets deleted or moved
+
+- `record_blas_refit.js` and `record_blas_refit.spec.js` — the batch of one is the recorder now.
+- `shader_blas_refit_leaf_bounds.js` — its body is four lines of the fused kernel. The playground's
+  `shader_blas_audit_leaf_triangles.js` imports its `BLAS_LEAF_BOUNDS_SETTINGS_STRUCT` as the audit's
+  own immediate and gets a struct of its own; `verify_leaf_triangles.js` imports the same struct
+  and never uses it, so that import simply goes.
+- `blas_refit_leaf_bounds.spec.js` splits: its validity test is replaced by the batch kernel's, and
+  its `geometry_read_triangle_bounds` block moves next to the chunk it tests, unchanged.
+- `blas_refit_containment.spec.js` is reworked to drive the fused kernel over two trees (§5).
+- `verify_skinned_blas_refit.js` records a batch of one where it recorded `record_blas_refit`.
+- `playground/skinned_blas_refit/README.md` names `record_blas_refit` and `GPU_BVH_BUILD_PLAN.md`
+  §5.2 names `shader_blas_refit_leaf_bounds`; both move to the new names in P4 and P5.
+
+No other importer exists; the review grepped the repository.
+
+### 3.7 What fusing the two passes does to R1
+
+Today the leaf boxes are made visible to the climb by a dispatch boundary, which WebGPU guarantees,
+and only the *internal* boxes ride on the builder plan's R1 assumption: a node's six words are
+written through `atomicStore` by the thread that fitted it, before that thread's `atomicAdd` on the
+parent's counter; the second arrival reads them through `atomicLoad` after its own `atomicAdd`
+returned 1. That is the whole handshake, and AR3 in `GPU_BVH_BUILD_PLAN.md` is the argument for it.
+
+In the fused kernel a leaf's box is written the same way, by the leaf's own lane, before that lane's
+first `atomicAdd`. The assumption is the same and it is made in the same place, but its surface
+grows: today `N − 1` internal boxes ride on R1 and `N` leaf boxes do not; fused, all `2N − 1` do,
+and the bottom level of the climb — roughly half the handshakes, the ones that read two leaves —
+moves from a guaranteed boundary onto relaxed atomics. What that buys is a pass boundary, a
+barrier, and the re-read of every leaf box.
+
+What it costs in mitigation is stated exactly. If tier 4 ever shows a leaf-level failure, splitting
+the leaf store back into its own batched pass is a mechanical change that restores today's surface
+precisely — and no more than that. It is *not* the per-level fallback R1 sketches: that fallback
+dispatches one tree level at a time, and for a batch of trees of differing depths it needs
+per-level node lists per tree that none of the three tables carry. That is a separate design,
+noted in §9, not a step this plan can claim.
+
+### 3.8 Alternatives considered
+
+- **One workgroup per tree, lanes striding over its leaves.** `N` workgroups for `N` trees; at 300
+  that is a sixth of a large GPU's slots, and the climb — the part that needs parallelism most —
+  gets 64 lanes per tree. Rejected.
+- **A 2D dispatch, x over leaf blocks, y over trees.** Wastes `max − actual` blocks on every tree
+  smaller than the largest, which LODs and props guarantee, and each axis has the 65,535 cap
+  anyway. Rejected.
+- **A binary search over the target rows instead of a lookup table.** Removes the per-workgroup
+  table at the cost of `log₂ N` dependent uniform loads per workgroup. Sound, but the lookup is the
+  idiom the skinning pass already uses, is `O(1)` per workgroup, and is trivially checkable at
+  tier 3. Not taken; noted in case the table's rebuild ever shows up.
+- **Extending `SKINNING_BINDING_STRUCT` with the refit fields.** Ties BLAS residency to the skinning
+  upload triggers and closes the door to non-skinning deformers using the same batch. Rejected.
+- **Counters indexed by arena node, one persistent buffer.** No per-tree offset, but the clear covers
+  every static geometry's nodes every frame, or becomes `N` range clears again. Rejected.
+- **Parity counters, never cleared.** Each refit adds exactly two to every internal node's counter,
+  so `arrivals & 1` distinguishes first from second without a clear. Real, and it removes the one
+  bandwidth item that scales with node count — but it makes "every leaf climbs every frame" a
+  load-bearing invariant that no device-free tier can see broken. Kept as a follow-up behind a
+  measurement (§9), not in the design.
+- **Two batched kernels (leaf store, then climb).** The conservative form of §3.7: one more pass and
+  a re-read of every leaf, in exchange for keeping the R1 surface where it is today. Not taken; it
+  is the first thing the fused kernel splits back into if tier 4 ever says so.
+- **Indirect dispatch.** The count is host-known. Nothing to buy until a GPU-side skip exists (§9).
+
+### 3.9 What else touches the trees
+
+- **The TLAS never reads a BLAS root box.** `GPUInstancesAccelerationStructure` builds from
+  instance world bounds, and the GPU path reads them off the `meshes` table, which the
+  bounds-refresh chain writes. Batching the refit changes nothing there.
+- **`shader_build_sdf` reads BLAS root bounds** through `blas_lookup`. Out of scope, but it is a
+  consumer of the boxes this pass writes, and it does not run between the refit and the frame graph.
+- **Ordering.** Nothing reads the node arena between the refit's position (`scene.tick`) and the
+  frame graph in the same command context, so pass order is what puts the refit before every ray.
+- **Immediates.** The kernel takes `dispatch_offset` as an immediate, as today's kernels take their
+  settings, so the batch stays off any device reporting `maxImmediateSize` 0. No new dependency,
+  but tier 4 needs a real browser rather than the in-app pane.
+
+## 4. Cost model
+
+Sizes use the playground character: 28,106 leaves, and 56,211 node slots if its buffer has no
+free-list holes — `topology.node_count` counts slots, so P0 reads the real figure off
+`get_refit_target`. Measured numbers land here at P0 and P5 (§6); the structural claims do not
+depend on them.
+
+| `N` skinned meshes | 1 | 64 | 300 |
+|---|---|---|---|
+| passes today / proposed | 2 / 1 | 128 / 1 | 600 / 3 |
+| clears today / proposed | 1 / 1 | 64 / 1 | 300 / 1 |
+| workgroups in the batch | 440 | 28,160 | 132,000 |
+| counters cleared per frame | 225 KB | 14.4 MB | 67.5 MB |
+| lookup table (rebuilt on change only) | 3.5 KB | 225 KB | 1.06 MB |
+| encoder calls today / proposed | 17 / 9 | 1,088 / 9 | 5,100 / 25 |
+
+The second sub-dispatch starts at 149 characters of this size. The counters clear is the one cost
+that still scales with node count: 4 bytes per node against the climb's own ~64 bytes per node of
+traffic, so under a tenth of the refit's bandwidth, and one command regardless of `N`. §9 has the
+lever if a profile ever shows it. Past a few hundred characters the wall is not the clear but the
+node arena itself — 1.8 MB per tree, 1.8 GB at a thousand — against `maxStorageBufferBindingSize`
+and `maxBufferSize`, which `#ensure_data_capacity` does not check today (§9).
+
+**Device tier, 2026-09-02, NVIDIA RTX 4090, 256 dancers, path traced.** The batch ran as two
+dispatches — 112,640 workgroups, the second page from workgroup 65,535. `verify()`: pass, the tree
+bounds the deformed mesh and follows it, and all 28,105 internal nodes are exactly their children's
+union. `verify_leaves()`: pass, all 28,106 leaf boxes are the builder's. Getting there took two
+fixes outside this plan (§7, L1 and L2).
+
+Frame time before and after: _not recorded_. **[deviation]** P0's baseline was not taken ahead of
+the work, the session went to correctness, and a before number needs the pre-switch commit
+(`f42851a62`) at a count the old animation ceiling allows — 128 or fewer. The profile-capture port
+landed after the session (`f5d343f40`), so the next one can read the refit's own span. This table
+takes the numbers whenever a session records them.
+
+## 5. Validation
+
+Every artefact is assigned to the tiers that can actually see it. Nothing here compares kernel A
+to kernel B, and nothing matches a string in the source.
+
+**Tier 1 — WGSL validity.** `shader_blas_refit_batch` and the lifted `shader_bvh_refit` parse and
+validate as assembled (`validate_wgsl_source`). Pins the constants move (§3.2) and the binding set.
+The same spec counts the storage-buffer bindings the batch kernel's descriptor declares and asserts
+they fit the engine's floor of ten — an invariant, and the only device-free place it can live. It
+earned its keep at P3: the row variable's first name was `target`, a WGSL reserved word, and the
+validator refused it while the emulator, which does not care, had already passed every test.
+
+**Tier 2 — emulator.** `shader_blas_refit_batch.spec.js`: three trees in one batch — two six-leaf
+trees of different shapes over the same six triangles, and a seventy-two-leaf tree whose leaves
+span two workgroups, which is the only way a lookup pair's `leaf_base` half gets exercised — each at
+its own position in the shared `nodes`, `parents` and `leaf_nodes` arrays with junk words between
+them, `nodes` and `counters` marshalled as `{value}` cells, every `(workgroup, lane)` driven as
+`dispatch([wg,0,0], [lane,0,0])`. The checker it asserts with has a spec of its own,
+`bvh2_check_bounds.spec.js`, that mutates a hand-fitted tree and requires each check to go red; and
+the build's own refit pass keeps an executing tier in `shader_bvh_refit.spec.js`, over a tenant tree
+at non-zero offsets. Asserted on the bytes:
+
+- every leaf's box covers the triangle it names (`bvh2_check_leaf_bounds`), per tree, against the
+  vertex table the spec wrote;
+- every node's box is exactly its children's union (`bvh2_check_containment`), per tree;
+- every word outside the two trees' bounds words is the sentinel it started as — one tree's lanes
+  never touch the other's nodes, and a 64-lane workgroup over a six-leaf tree writes nothing from
+  its idle lanes;
+- every internal node's counter is exactly 2 and every other counter word is 0, at each tree's own
+  `counters_offset` — the ranges are disjoint and the handshake fired once per node;
+- the wide tree's second run starts where the first ended: after one workgroup leaves 0 to 63 have
+  boxes and 64 to 71 do not, after both the tree is fitted and every internal counter reads 2.
+
+The emulator runs invocations one at a time, so the arrival protocol always completes; that is the
+same limitation the old spec had, and it is why tier 4 exists.
+
+**Tier 3 — `SoftwareGPUDevice`** (`requiredFeatures: ['subgroups']`). A `GPUBLASRefitBatch.spec.js`
+against a real `GPUGeometryBVHManager` with synthetic trees, reading host bytes through the
+dispatch's bind-group entry as `record_blas_refit.spec.js` does, and clears through a spy on the
+command context, since clears do not appear in the recorded pass log:
+
+- three trees of 8, 3 and 200 leaves record exactly one clear and one dispatch, with
+  `group_count_x = 1 + 1 + 4`, and nothing else;
+- the target rows equal `get_refit_target(owner)` for each tree, with `counters_offset` the prefix
+  sum of node counts, and the clear covers `Σ node_count` words;
+- the lookup names, for every workgroup, the right tree and a leaf base that is a multiple of 64
+  and below that tree's leaf count;
+- an owner obtained *with* its bytes but before `blas.update()` contributes no row and no
+  workgroups; after `blas.update()`, with no `set_entries` in between, the next `record` includes it
+  — the `residency_version` handshake, pinned by the dispatch size changing;
+- an upload of an *unrelated* geometry between two frames makes the next `record` rebuild both
+  tables, and a frame with no change does not (`writeBuffer` spied on the mock queue after the
+  manager's own uploads, or filtered by destination);
+- with `maxComputeWorkgroupsPerDimension: 4` the six workgroups record as two dispatches of 4 and 2
+  whose `dispatch_offset` immediates read 0 and 4, and every dispatch's group count is at or under
+  the limit — the mock does not enforce the cap itself;
+- a clone entry refits its own nodes, leaving the source's alone — today's last spec, carried over.
+
+A new `GPUGeometryBVHManager.spec.js` pins the manager's two additions. `residency_version`:
+unchanged across an idle `update`; moved by a node upload; moved by a topology-only `update`, the
+one that takes the early return; moved by `remove` of a registered owner; unmoved by `remove` of an
+unknown one. The guard: an owner obtained while its geometry's `bvh` is empty, then given bytes and
+updated again, gets `undefined` from `get_refit_target` rather than a row aimed at the next tree's
+nodes — red against today's manager.
+
+`GPUMeshSkinningContext.spec.js` gains one test: two bound meshes produce a single refit pass sized
+for both clones' trees. Its fixture geometry has no tree today, so the test needs one — a one-leaf
+tree (`child_1 = BVH_NULL_NODE`, payload 0; `bvh2_derive_topology` accepts a single node) — and
+`GPUSceneContext.build()` runs the geometry update, which is what makes the clones resident before
+the frame. It filters the
+recorded passes by the batch kernel's label, asserts one dispatch of `Σ ceil(leaf_count / 64)` over
+both clones, and asserts both target rows' `node_word_offset` differ from the source's. Red against
+the loop for the right reason: with resident trees the loop records two passes per mesh.
+
+**Tier 4 — browser.** `src/shade/playground/skinned_blas_refit/`: `verify()` and `verify_leaves()`
+at 1, 64 and 256 dancers, path traced, on the NVIDIA device the phase-3a record names; the rasterized
+against traced silhouette check by eye at 256. The character count cap in `main.js` (64) is lifted
+for this. Frame times and, with `timestamp-query`, the per-pass spans from a profile capture, before
+and after, into §4. This tier is the only detector for §3.7's enlarged R1 surface.
+
+Not tested, on purpose: fused versus two kernels (settled by §3.7), lookup versus binary search
+(settled by §3.8), and any assertion on shader-written bytes from the software device, which
+executes no shaders.
+
+## 6. Deliverable sequence
+
+Each item is its own commit on `master`, tests red against the tree before it and green after, in
+the order the plan's dependencies force. Nothing is staged with `git add`; new files are `-N` then
+`--only`.
+
+| # | item | red-then-green pin |
+|---|---|---|
+| P0 | **Baseline.** Lift the 64-dancer cap in the playground and add the profile-capture idiom from `volumetrics_froxel/main.js`. Read the character's real `node_count` off `get_refit_target`. Record frame time at 16, 64 and 256 with the refit, and with `#record_blas_refits` commented out locally — the ceiling of what P4 can win. Numbers into §4. **[deviation]** Only the cap was lifted (to 512); the rest folds into P5's one session, see §4. | none — measurement, no engine code |
+| P1 | **Lift the climb.** `chunk_bvh_refit_climb` + `BVH_NODE_LAYOUT_DEFINITION` in `gpu_primitive/bvh/`; `shader_bvh_refit` calls the chunk. No behaviour change. **Landed** `c52ef1691`. | the existing containment spec and `graph_bvh_build_lbvh.spec.js` stayed green; tier-1 validity of the reassembled kernel |
+| P2 | **The manager.** `residency_version` bumped once per `update` in which a shape or nodes became resident, and in `remove`; the uploaded byte length on the record and the `get_refit_target` guard. **Landed** `f42851a62`. | the new manager spec of §5: five version cases and the empty-snapshot guard, 5 red then green |
+| P3 | **The batch.** `BLAS_REFIT_TARGET_STRUCT`, `shader_blas_refit_batch`, `GPUBLASRefitBatch`, and the tier 1–3 specs of §5, the descriptor budget assertion included. Nothing calls it yet. **Landed** `36d4796df`. | every case red on the missing modules, then green; the two-tree emulator spec |
+| P4 | **Switch and delete.** The skinning context records the batch; `record_blas_refit`, the single leaf kernel and their specs go; the playground's verify functions, audit kernel and README move over. **Landed** `46ba62862`. | the skinning-context test in §5, red against the loop (no batch pass recorded) |
+| P5 | **Device tier and record.** §5's tier 4, run on an NVIDIA RTX 4090 at 256 dancers; the **[deviation]** note in `GPU_BVH_BUILD_PLAN.md` §5.2 is in. **Done**, with the findings of §7's second table. | `verify()` and `verify_leaves()` pass at 256: the tree bounds the deformed mesh and follows it, 28,105 internal nodes exactly their children's union, all 28,106 leaves the builder's |
+
+P1 and P2 are independent of each other and of P0; P3 needs P1 and P2; P4 needs P3; P5 needs P4.
+
+## 7. Review
+
+An adversarial pass was run against the code on 2026-09-02, after the plan was drafted, beside
+the author's own check of the tier mechanics. Twelve findings, none blocking. Every one is folded
+into the sections above; this is the ledger, so a later reader can see what changed and why.
+
+| # | severity | finding | disposition |
+|---|---|---|---|
+| F1 | should-fix | The residency handshake, as first written, described obtaining an owner before its bytes exist. The manager snapshots `source.bvh` at `obtain`, marks such an owner resident over a zero-length region, then answers `get_refit_target` with a live topology and a `node_word_offset` aimed at the next tree appended — a row the batch would ingest faithfully. Pre-existing; today's recorder does the same. | **Accepted.** §3.4 adds the uploaded-byte-length guard, P2 pins it red-then-green, §5's handshake case is reworded to obtain-with-bytes-then-update, B9 added, late-byte upload recorded in §9. |
+| F2 | should-fix | The tier-3 device cannot be built with `maxStorageBuffersPerShaderStage: 10`: the mock refuses any limit above the spec default and never counts storage buffers per stage, so nothing device-free checked the nine-buffer budget. | **Accepted.** The `requiredLimits` line is gone; the batch kernel's tier-1 spec asserts the descriptor's storage-buffer count against the engine's floor (§5); B2 reworded. |
+| F3 | should-fix | §3.7 understated the change to R1's surface (from `N − 1` boxes to `2N − 1`, the bottom level moving onto relaxed atomics) and overclaimed the fallback: the per-level fallback R1 sketches is single-tree, and a batch of mixed depths needs per-level lists the tables do not carry. | **Accepted.** §3.7 rewritten with the counts; the two-kernel split is named as restoring today's surface and nothing more; the batch fallback is a separate design in §9; B1 reworded. |
+| F4 | should-fix | Binding the manager's buffers is safe because of frame call order, not because they are "read fresh": growth between `record` and `finish` would destroy a bound buffer, and the mock could not catch it. | **Accepted.** §3.3 and B4 state the invariant with the call sites; the recorder's doc will say `record` belongs inside the skinning update. |
+| F5 | should-fix | The skinning-context test could neither go red nor green: the spec's fixture geometry has no tree, so both the loop and the batch record nothing. Found independently by the author. | **Accepted.** §5 gives the fixture recipe (a one-leaf tree, `graphics.update()` before the frame) and the assertions. |
+| F6 | should-fix | `residency_version` "bumped at the end of `update`" misses the early return on an empty node queue, which a topology-only frame takes; and the rebuild trigger is broader than §1's wording — any tree's residency change, not only the batch's own. | **Accepted.** §3.4 bumps at both exits and says why the trigger is coarse; §1 reworded; §5 pins the topology-only bump and the unrelated-upload rebuild. |
+| F7 | nit | §3.6 misdescribed the playground imports (the audit kernel takes only the settings struct; `verify_leaf_triangles.js` has a dead import) and missed the README and the build plan's mention of the leaf kernel. | **Accepted.** §3.6 lists all of them; P4 and P5 carry the doc moves. |
+| F8 | nit | Units mixed MB and MiB; the proposed encoder-call counts included the transient allocation while today's did not; 56,211 node slots assumes no holes; the 1,000-character line in B3 is moot because the node arena hits the buffer limits first. | **Accepted.** §4 in decimal MB, 9 / 25, "if no holes" with P0 reading the real count; B3 reworded, `#ensure_data_capacity`'s missing check noted in §9. |
+| F9 | nit | Tier-3 mechanics: clears are visible only through a spy on the context; the `writeBuffer` spy must be scoped past the manager's own uploads; the mock does not enforce the workgroup cap; the idle-lane check restates the sentinel check; the manager spec file does not exist yet. | **Accepted.** §5 says how each assertion is made; the idle-lane bullet is folded into the sentinel one; the manager spec is "new". |
+| F10 | nit | Names fit their neighbours; `BVH_NODE_LAYOUT_DEFINITION` sits better beside `BVH_BUFFER_LAYOUT.js` than in `shader/chunk/bvh/`; the `BVH_` prefix avoids every existing `NODE_*` copy. | **Accepted.** §3.2 places it in `gpu_primitive/bvh/`. |
+| F11 | nit | Scope statements the plan should carry: the TLAS does not read root boxes; `shader_build_sdf` does; nothing reads the arena between the refit and the frame graph; immediates keep the batch off `maxImmediateSize` 0 devices; the `blas === undefined` guard must survive. | **Accepted.** §3.9 added; §3.5 keeps the guard. |
+| F12 | nit, plausible | "Nothing for subgroups to do" was too strong: pre-order leaf lists put sibling leaves in adjacent lanes, so the bottom level of the climb could be a shuffle rather than a counter round trip. | **Accepted as a note.** §3.2 states it; §9 keeps it behind P5's profile, per the measure-first rule. No design change. |
+
+Verified correct by the review, so nobody needs to check them again: the §1 step list and encoder
+counts; `get_refit_target`'s contract and the per-source topology sharing; arena offsets surviving
+growth; the skinning lookup and pagination idiom and its `queue.writeBuffer` uploads; immediates
+capped at 64 bytes; the emulator's positional builtins, immediates supplied as bindings, struct
+arrays and `{value}` atomics; the mock's recording surface and its acceptance of lowered limits;
+the nine-buffer count against the ten the engine requests; the arithmetic in §4 (440 workgroups,
+the 149th character, three sub-dispatches at 132,000, the 4 / 2 split); and the edge cases of
+§3.3 — zero entries, zero-leaf and single-leaf trees, remove-then-obtain in one frame,
+source-geometry owners, more than 65,535 workgroups, and geometry indices never being reassigned.
+
+What the device session turned up, in the order it did:
+
+| # | finding | disposition |
+|---|---|---|
+| L1 | At 256 dancers the load failed in the animation manager: curve uploads were shared by `AnimationCurve` instance, every dancer is a fresh parse, and 256 copies of the dance's ~22,000 keyframe blocks exhausted the block table's 4,096 pages of 128 KB near 170 dancers. | **Fixed**, `d62a17ffe`: curves are interned by content — hash, then key-by-key equality, tangents included — pinned by a new `GPUAnimationManager.spec.js`. Not this plan's subsystem, but it stood between the playground and hundreds of animated characters. |
+| L2 | `verify()` reported a consistent interior and a root box a few frames off, growing with time. The harness reads the root box and the bounds chain's box in two readbacks, and each await lets the frame loop advance the dance; on a 256-dancer path-traced frame the two reads straddle several frames of motion. | **Fixed**, `8377a3de0`: the checks hold the dance still while they measure, and drive their own frames for the "follows it" half. With that, `verify()` passes. A clone-side leaf audit, `verify_clone_leaves()`, was added for the case it had been the kernel; it was not needed. |
+| L3 | A 256-dancer load is a minute of sequential parses behind one status line, and `verify()` called before it finished failed on a list that did not exist yet. | **Fixed**, `1c04040bd`: the status counts dancers and names the two stages after. |
+| L4 | The manager uploaded 512 trees for 256 dancers: each parse registers its own source geometry beside its clone, so the node arena is 921 MB where 462 MB would do. | **Fixed**: `GPUGeometryManager` registers by content — an equal geometry under a tree of the same size becomes another name for the existing record, reference-counted — pinned by a new `GPUGeometryManager.spec.js`. The same story as L1, in the geometry manager. |
+| L5 | Frame times were not recorded. | **Open**: §4 takes the numbers whenever a session records them; the before number needs `f42851a62` at 128 dancers or fewer. |
+
+A second adversarial pass ran after the landing, over all of the above — thirteen findings, none
+blocking. Nine were worked, each red-then-green in its own commit; four were left as not worth the
+change, and are recorded so nobody re-finds them.
+
+| # | severity | finding | disposition |
+|---|---|---|---|
+| R1 | should-fix | Deleting the two-kernel containment spec also deleted the three tests that proved `bvh2_check_bounds` — the oracle for the emulator spec and the browser tier's `verify()` — can go red. | **Fixed**, `5593ebded`: `bvh2_check_bounds.spec.js`, over a tree fitted by hand, with the three mutation cases and a fourth for a loose parent. |
+| R2 | should-fix | Both emulator trees had six leaves, so `leaf_base` was always zero and the one line where a batch's addressing differs from a single workgroup's never executed; only the device session had. | **Fixed**, `e4115b9fa`: a seventy-two-leaf tree spanning two workgroups, run whole and one run at a time. Shown to bite: the kernel taking `lid.x` alone turns three tests red. |
+| R3 | should-fix | `shader_bvh_refit`, the build's pass 4, ran in no device-free tier after the deletion; the climb was covered through the batch kernel, its framing was not. | **Fixed**, `57a19c7f4`: `shader_bvh_refit.spec.js` over a tenant tree at non-zero offsets. Shown to bite: swapping the two offsets in the call turns all four tests red. |
+| R4 | should-fix | `add_clone` recorded the alias object as the clone's geometry, and the BLAS manager keys shapes by object: 256 parsed dancers shared one source record but derived and uploaded 255 shapes. | **Fixed**, `6becb6e8d`: the clone records the record's geometry; clones of two equal geometries share one parents offset. |
+| R5 | should-fix | A record registered before its bytes existed was resident over nothing at the arena's end; P2's guard kept the refit off it, but `get_address` still published that address into the ray lookup, and late bytes were never uploaded. | **Fixed**, `3f24d9fde`: no record resident over nothing, uploads read the geometry's tree when they run, an empty tree at node 0 for the lookup meanwhile, and the geometry manager runs the BLAS update every call. |
+| R6 | should-fix | Alias matching compared tree sizes read live off the first object while the BLAS snapshot was taken at registration, so a geometry that gained its tree late could lend an equal one its empty region. | **Resolved by R5**: there is no empty region, and a pending record uploads the bytes the live comparison saw; pinned as its own case in `GPUGeometryManager.spec.js`. |
+| R7 | nit | The content key covers meshlets only; bounds and primitive count come from the first object, and the meshlet hash omits vertex data where equality includes it. | **Left**: no path mutates a registered geometry, two parses of one file agree on every field, and equality still covers the data. |
+| R8 | nit | The curve intern bucket holds live curve instances, so a curve mutated after upload could lend a later equal parse its stale blocks. | **Left**: no engine path mutates a curve after `register_clip`. |
+| R9 | nit | This document had drifted from the code in five places, and stated the buffer-lifetime invariant too broadly. | **Fixed** in this revision. |
+| R10 | nit | A node queue holding only released records still bumped the residency version, and built a zero-byte staging buffer to copy nothing. | **Fixed**, `8e5644c82`. |
+| R11 | nit | The geometry table's debug inspector counted names, not rows, and would read past the buffer with aliases present. | **Fixed**: one row per geometry id. |
+| R12 | nit | Three weak assertions — an integer check on the version, batch rows compared against the call the recorder copies from, a default sort on numbers. | **Left**: the row comparison still pins the upload path's field order and offsets, the sort sees two values, and the integer check is a smoke test that costs nothing. |
+| R13 | nit | The playground's pause wrapper restores the previous animation state in `finally`, undoing a Freeze click made during a check. | **Left**: a check takes a second, and the button reads the state when clicked next. |
+
+## 8. Risk register
+
+| # | risk | mitigation |
+|---|---|---|
+| B1 | R1 of the builder plan now covers every box, leaves included: `2N − 1` instead of `N − 1`, with the bottom level of the climb on relaxed atomics (§3.7) | Same handshake, same all-atomic discipline. Tier 4's `verify_leaves()` and containment check are the only detector. If they ever fail, the two-kernel batched split restores today's surface mechanically; a per-level fallback for a batch is a separate design (§9). |
+| B2 | Nine storage buffers in one stage | The engine requires ten and refuses adapters with fewer; the batch kernel's spec asserts the descriptor's count against that floor, since the mock can neither enforce nor raise the limit; `meshlets_address` in the row is the lever if it ever tightens. |
+| B3 | The counters clear scales with total node count: 67.5 MB at 300 characters | One command, under a tenth of the refit's own traffic; parity counters (§3.8, §9) remove it entirely if a profile says so. Past a few hundred characters the node arena's own size is the wall, not the clear. |
+| B4 | A manager buffer bound by the batch is destroyed before the frame is submitted | Safe by call order: `GPUGeometryBVHManager.update` and `GPUGeometryManager.build` run in `Renderer.#begin_frame` and `GPUViewContext.update`, before the main command context exists; the refit is recorded into that context through `scene.tick`. The recorder is documented as belonging inside `GPUMeshSkinningContext.update`, and nowhere else. The mock cannot detect a violation. |
+| B5 | Pagination: `dispatch_offset` off by a page silently refits the wrong trees; the mock does not enforce the workgroup cap | Pinned at tier 3 with a four-workgroup limit, and every dispatch's group count asserted under the limit; the same idiom the skinning pass has shipped with. |
+| B6 | A device-free tier cannot see a real race; the emulator serialises invocations | Known and unchanged from today; tier 4 on the named device, both verify functions, at 256. |
+| B7 | Two entries for one owner would race on one tree | `set_entries` asserts uniqueness. |
+| B8 | An owner removed from the manager while still in the entries | `remove` bumps the version; the next `record` drops the row, as `get_refit_target` answers `undefined`. Pinned at tier 3. |
+| B9 | An owner obtained before its bytes exist is resident over nothing and later answers with a stranger's address (§3.4) | **Closed** (§7, R5): no record is resident over nothing, late bytes upload on the next update, and the lookup names the empty tree meanwhile. The uploaded-byte-length guard stays as a second check. |
+| B11 | Every traversal starts walking from whatever the lookup names, with no null check, so "no tree" has to be a valid tree | Node 0 of the arena is an internal node whose box is +inf below and -inf above: rays miss it, point queries prune it, nothing fetches a triangle for it. Pinned in `GPUGeometryBVHManager.spec.js`, and the first real tree lands after it. |
+| B10 | Rebuilds happen on any tree's residency change, not only the batch's own | Accepted cost: one host pass and a lookup upload on streaming frames; pinned at tier 3 so it is not "optimised" into a stale-row bug. |
+
+## 9. Follow-ups, deliberately outside this plan
+
+- **A GPU-written skip.** A per-target word the skin-matrix prep writes when a skin's matrices did
+  not change; a workgroup whose target is clean exits before touching memory. Keeps the command
+  count fixed and makes an idle character free in bandwidth. Only after a profile shows idle
+  characters matter.
+- **Compaction and indirect dispatch**, once the skip exists and most trees are idle: a small pass
+  compacts live targets into a work list and `dispatchIndirect` runs exactly those.
+- **Parity counters** (§3.8) if the clear shows in a profile.
+- **Bottom-level sibling pairing with subgroup shuffles** (§3.2), behind P5's profile of the climb.
+- **A per-level fallback for a batch**, should tier 4 ever fail R1: host-derived per-level node
+  lists per tree, rebuilt with the tables, and `max_depth` dispatches. Designed only if needed.
+- **`#ensure_data_capacity` has no `maxBufferSize` check**, unlike `GPUDatabase`; at a thousand
+  characters of this size the node arena would exceed the binding limit silently.
+- **One parse per file.** Source geometries now share by content (§7, L4), so an instanced cast
+  costs one tree in the arena — but it still costs one parse per instance, a minute of them for
+  256 dancers. A loader that hands back one parse and instantiates the node hierarchy per copy
+  would make the second dancer free.
+- **Other deformers.** Morph targets, cloth, procedural vertex motion enqueue into the same batch;
+  the seam is an owner and a geometry index, on purpose.
+- **A source geometry that is itself edited** is a full build (phase 3b), not a refit.

package/src/shade/renderer/geometry/bvh/BLAS_REFIT_TARGET_STRUCT.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One tree in a batched refit: where it lives, and where its arrival counters live.
+ *
+ * The first four fields are what {@link GPUGeometryBVHManager#get_refit_target} answers, copied
+ * out at the frame the batch's tables are built. The other two are the batch's own: a tree's
+ * counters sit at `counters_offset` in one buffer that holds the counters of every tree in the
+ * batch — a prefix sum of node counts — and `geometry_index` is the row whose meshlets the leaf
+ * payloads index, which for a skinned clone is the clone's own row, the one skinning deformed.
+ *
+ * Read by {@link shader_blas_refit_batch} once per workgroup, through the workgroup lookup;
+ * written by {@link GPUBLASRefitBatch} when the set of trees or their residency changes.
+ *
+ * @type {WebGPUStruct}
+ */
+export const BLAS_REFIT_TARGET_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=BLAS_REFIT_TARGET_STRUCT.d.ts.map