@woosh/meep-engine 3.26.0 → 3.27.0

package/src/shade/renderer/geometry/virtual/runtime/RUNTIME_PLAN.md

@@ -10,6 +10,21 @@
 >
 > The ledger is still the place to start for what was wrong and how it was found. It is no longer a
 > list of open defects.
+>
+> **And the cut is under review, 2026-09-14.** §4's rule and its proofs stand, but the claim
+> that it is evaluated from the root every frame is what
+> [CUT_PLAN_2026_09_14.md](./CUT_PLAN_2026_09_14.md) proposes to replace, with a per-view cut kept
+> between frames and a `.vgeo` change to make walking up possible. Nothing of it is built: its §0
+> measures what a cut dispatch costs in the runtime as it stands here.
+>
+> **And residency is rewritten, 2026-09-14.** §3.2, §3.3, the touch half of §4.5 and everything
+> `VGeoResidencyManager` did are superseded by
+> [RUNTIME_PLAN_2026_09_14.md](./RUNTIME_PLAN_2026_09_14.md): selectability is kept by a counter in
+> the group row rather than recomputed per install, a touch is one bit, the want stamps are a
+> persistent frame-tagged buffer, both tiers live in one flat `VGeoResidency` with CLOCK eviction
+> under a per-reading test budget, and pages are fetched, verified and decoded on workers. The cut
+> also frustum-tests a cluster before it claims its child page. What is left of this document is
+> still right about the slot layout, the claim, the cut rule and its proofs, and the seam.
 
 **Status: built.** This was the plan for what
 [VIRTUAL_GEOMETRY_DESIGN.md](../VIRTUAL_GEOMETRY_DESIGN.md) §7 describes — the selection buffer, the
@@ -184,20 +199,35 @@ invalid buffer.
 
 ### 4.1 Shape
 
-A **wavefront BFS over node visits**, ping-ponged through two queues with an indirect dispatch per
-iteration. Not persistent threads: WebGPU gives no forward-progress guarantee across workgroups,
-and an MPMC queue serviced by persistent threads is unbounded cross-workgroup waiting.
+A descent that **lives inside one dispatch**, redistributing its own work across the lanes of a
+subgroup. Not persistent threads: WebGPU gives no forward-progress guarantee across workgroups, and
+an MPMC queue serviced by persistent threads is unbounded cross-workgroup waiting. But a lane may
+wait on the other lanes of *its own* subgroup, and that is enough.
 
-A queue item is `(instance_slot, page_row, node_index)` — one lane each.
+A queue item is `(instance_slot, page_row, visit, aux)` — one lane each, a node index or, above bit
+31, a group index with `aux` naming one cluster inside it.
 
 ```
 seed:      one item per visible VG instance = (instance, root page row, node 0)
-iteration: node test → interior: enqueue children
-                     → leaf:     for each group, for each cluster: the predicate
+step:      every lane executes its item and returns a production *count*
+           subgroupExclusiveAdd numbers the wave's whole production densely
+           the first subgroup_size of them are taken back into the wave's own lanes
+           the rest spill to the global queue under one atomicAdd
+dispatch:  descent_steps of those, then whatever is still held goes back to the queue
 ```
 
-Enqueueing a *child page* means enqueueing `(instance, child_page_row, 0)` — its node tree's root.
-Uniform items, one kernel, no special cases.
+Enqueueing a *child page* means enqueueing `(instance, child_page_row, 0, 0)` — its node tree's
+root. Uniform items, one kernel, no special cases.
+
+**This replaces a level-synchronous wavefront**, which ping-ponged through global memory once per
+level of the descent. What killed it was depth rather than geometry: measured on a 28M-face
+container at τ = 1 on a 4090, the descent converged at **39 levels** carrying 15,027 items — an
+average frontier of 385 items, six workgroups of 64 on a 128-SM part — while an empty
+prepare/traverse pair costs 3.9 µs whatever it contains. Page depth grows like log2(triangles), so
+the dispatch count got worse with better assets and never better with a faster GPU.
+
+The redistribution is Karis' "Variable sized work" (graphicrants, 2026-03) with its groupshared
+scatter removed; §4.10 records why that half does not port and what replaces it.
 
 ### 4.2 What one node visit does
 
@@ -326,24 +356,39 @@ lost at the append; `QUEUE_REMAINING` is what was outstanding when the descent s
 by one extra prepare pass the seam records after the wavefront loop for exactly this; and
 `WAVEFRONTS` is how deep it went, so reaching `max_iterations` is legible rather than inferred.
 
-### 4.6 Group chunks, and the serial loop that is not allowed to be unbounded
+### 4.6 One lane per cluster
 
-A node leaf covers at most 4 groups, and the obvious kernel walks their clusters in the lane that
-popped the leaf. A group may hold up to 4096 clusters (format §11.5), so that lane can be handed
-16,384 clusters — legal input, and a loop nothing bounds. So a leaf does not walk clusters at all:
-it enqueues one **group-chunk item** per group per `VGEO_CUT_CLUSTER_CHUNK` clusters, all through
-a single `atomicAdd`. A typical group is 4–32 clusters and produces exactly one, so the common
-case pays one extra queue item and gains a factor of four in width at the bottom of the descent;
-the pathological case is bounded instead of unbounded.
+A node leaf covers at most 4 groups and a group may hold up to 4096 clusters (format §11.5), so a
+kernel that walks a leaf's clusters in the lane that popped it can be handed 16,384 of them — legal
+input, and a loop nothing bounds. The answer used to be a **group-chunk item** per
+`VGEO_CUT_CLUSTER_CHUNK` clusters, which bounded the loop at 8 and paid for it in the memory
+pattern: lane *i* walking clusters `8i..8i+8` puts 32 lanes on 32 separate cache lines at every
+step, over rows that are contiguous.
 
-An item is therefore `(instance, page_row, target, first_cluster)`, with bit 31 of `target`
-distinguishing a node index from a group index. One kernel, one queue, two shapes.
+There is no chunk any more, because the bound now comes from the redistribution. A leaf's
+production is **every cluster its groups hold**, the wave packs them one per lane, and consecutive
+lanes read consecutive cluster rows. `cluster_chunk` is gone from the params.
 
-### 4.7 Iteration bound
+An item is `(instance, page_row, visit, aux)`, with bit 31 of `visit` distinguishing a node index
+from a group index and `aux` naming the cluster inside that group. One kernel, one queue, two
+shapes.
 
-Depth along a path is page depth × (node depth + one group step) — 12 and 1–3 measured, so about
-48. The kernel runs a configurable `max_iterations` (default 64) of indirect dispatch. A dispatch of
-an empty queue is an indirect dispatch of zero workgroups.
+### 4.7 Two bounds, and what each one costs
+
+Depth along a path is page depth × (node depth + one group step) — 12 and 1–3 when this was
+written, 39 levels measured on the 28M-face container. That depth is now paid **inside** a dispatch:
+`descent_steps` (default 32) steps of the loop above, and `max_iterations` (default 8) dispatches
+for the breadth that spills out of it. Measured on that container, the descent converges in **five**
+dispatches with work, against 39 before.
+
+WGSL is what makes `descent_steps` a tuning knob rather than a safety bound. A loop around a
+subgroup operation needs a uniform trip count and nothing launders one — not `subgroupAdd`, not
+`subgroupMax`, not `subgroupBroadcastFirst`, which launders a value for a use but not for control
+flow — and it may not carry a non-uniform `break`, `continue` or `return`. So the descent cannot
+stop when the wave runs dry: it runs the full count and masks, at roughly ten instructions a step
+for a wave with nothing left. Both numbers trade idle steps against dispatches, and neither is safe
+by construction. `VGEO_CUT_STAT.QUEUE_REMAINING` is what says a pair was set too low — measured, it
+reads 207 outstanding at 64×4 and 8,332 at 96×3, where `DRAWN` falls short by the same shape.
 
 "Records whether the queue was non-empty at the end" is what this paragraph promised and what it did
 not do: nothing anywhere recorded it, which made the descent's one hole-shaped failure the only one
@@ -352,6 +397,44 @@ by one extra prepare pass after the loop, and `WAVEFRONTS` says how many iterati
 Measured on the playground's 13-page torus through a real adapter: fourteen wavefronts at τ = 0.5,
 eight at τ = 16, and nothing outstanding at any threshold.
 
+### 4.10 What WGSL would not let the redistribution be
+
+Karis' `DistributeWork` scatters each producer's packed state into a groupshared slot and has every
+consumer ballot for the nearest preceding one. That needs the scatter's writes visible across the
+wave before the gather, and HLSL spells it `GroupMemoryBarrier()` — memory ordering with no
+execution sync, sound because a wave is in lockstep.
+
+WGSL has no memory-only workgroup barrier. `workgroupBarrier()` is an execution barrier, the batch
+loop's trip count is per-subgroup, and two subgroups of one workgroup entering it a different number
+of times is a deadlock. Tint refuses it: *"'workgroupBarrier' must only be called from uniform
+control flow"*.
+
+So the kernel finds each item's producer by **binary search over the same prefix sums** instead of
+scattering to it — the owner is the largest lane whose base is at or below the index, which stays
+correct when empty lanes repeat a base because a repeat sits at the start of the next producer's run
+rather than the end of the previous one. `log2(subgroup_size)` shuffles, no workgroup memory and no
+barrier anywhere in the file.
+
+Probed on Chrome against a real adapter, because two of the rules are not what they look like:
+
+| | |
+| --- | --- |
+| a non-uniform `if` that opens and closes | fine — Tint models reconvergence |
+| `workgroupBarrier` after one | fine |
+| `subgroupShuffle` with a non-uniform lane id | fine |
+| a non-uniform-bounded loop with no subgroup op inside | fine, and taints nothing after it |
+| loop bound: literal, `subgroup_size`, uniform buffer field | fine |
+| loop bound through `subgroupAdd` / `subgroupMax` / `subgroupBroadcastFirst` | rejected |
+| non-uniform `break` / `continue` / `return` in a loop with a subgroup op | rejected |
+
+The emulator is the other half of this. It runs one invocation at a time and refused the reductions
+and shuffles on the argument that "a reduction over one lane would pass tests a real wave fails" —
+right about what they cover, wrong that there was an alternative. A subgroup kernel must be correct
+at *every* width, WGSL promising nothing about which one a device hands it, so one is a
+configuration rather than a stand-in, and refusing to model it left the kernel with no CPU-tier
+coverage at all. It has them now, at width one, and `vgeo_cut_agreement.spec.js` drives the real
+`main` through them. What that tier cannot see is the redistribution itself; that is a device test.
+
 ### 4.8 What the review took out: the child-table metric is not a cut structure
 
 The plan's first draft claimed the child-table metric copy as the cut's pre-fetch cull, which is