@woosh/meep-engine 3.26.0 → 3.28.0

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

@@ -239,3 +239,40 @@ Two things this pass could not prove below the drive, written down rather than c
   implemented as a per-reader one.** `VGeoResidencyManager`'s own doc records the first being
   measured at 48 concurrent range requests against a cap of six, and that is why its gate is shared.
   Worth a grep the next time a limit is added: the reader-shaped one is the easy one to write.
+
+## 2026-09-14 — the remainder counter never worked
+
+`QUEUE_REMAINING` read zero at every iteration budget, including the ones where the descent drew
+nothing at all. M8 added the counter and a spec for it, and both were right about a frame with one
+cut in it; the engine has never recorded a frame with one cut in it.
+
+Measured on `zorah-2026-13-09/bdf6f9615ae672d54bfb70cde904f5c2.vgeo` (28M faces, 17,172 pages)
+through the playground on a 4090, sweeping `max_iterations` at tau = 1:
+
+| `max_iterations` | pages | drawn | remaining, before | after |
+| --- | --- | --- | --- | --- |
+| 40 | 1593 | 10177 | 0 | 0 |
+| 39 | 1593 | 10177 | 0 | 0 |
+| 38 | 1593 | 10170 | 0 | 7 |
+| 32 | 1315 | 2115 | 0 | 4556 |
+| 20 | 25 | 0 | 0 | 75 |
+
+Two causes, and they cancelled into a plausible number:
+
+- **The prepare pass wrote it, and the prepare pass runs between wavefronts.** What it could report
+  is the frontier of an iteration, not a remainder, and the next iteration overwrote it. Only a pass
+  after the last wavefront is looking at the right thing.
+- **It was a plain store, and a frame has more than one cut.** The two-way HZB filter gives every
+  view two expansion sites and a scene routinely has all of its virtual geometry in one of them, so
+  the *empty* bucket ran last and stored its own zero over the other's truncation. Every other stat
+  in `VGEO_CUT_STAT` is an add across the frame's cuts; this one was not.
+
+`shader_vgeo_cut_queue_remainder` is the tail now — three bindings, one workgroup, an `atomicAdd` —
+and the prepare pass no longer binds the feedback buffer at all. The spec that missed it ran one
+cut against one feedback buffer, which is the only arrangement in which a last-writer-wins race has
+no second writer; the new one runs a truncated cut and an empty cut against the buffer
+`begin_frame` would have given them both.
+
+**What this unblocks.** `max_iterations` defaults to 64 and the descent on this asset converges at
+39, so 89 of the 128 traverse dispatches a frame records are empty — and until now nothing could
+say whether a smaller budget was safe. It can now: 39 is exact and 40 is free.

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
@@ -24,7 +39,7 @@ held to `vgeo_select_cut` exactly, and `playground/vgeo_runtime/` runs it on a d
 
 Everything below the runtime was already built when this was written. The builder produces a DAG,
 the container holds it, the reader streams it a page at a time with residency and activation,
-`VGeoResidencyManager` owns the RAM budget, and `playground/vgeo_viewer/select_cut.js` selects a
+`VGeoResidencyManager` owns the RAM budget, and `runtime/cut/__fixtures__/vgeo_select_cut.js` selects a
 correct cut on the CPU against a partially resident container. What had never run was any of it on
 the GPU, and the one piece of M0 that is engine-facing — the expansion seam — had never been built
 at all.
@@ -61,7 +76,7 @@ no cluster the flat rule would draw is missed.
 | `GPUMeshletManager` | data + metadata pools, `add_batch`/`remove_batch` | the VRAM tier's storage; format §8 makes a page payload a **copy** into the data pool |
 | `MESHLET_DEFINITION_STRUCT` | `(meshlet index, mesh index)` | the cut's output record type — unchanged, which is what makes the seam one call |
 | `graph_expand_meshes_to_meshlets` | four call sites, three of them opaque | the seam: a VG expansion runs beside each opaque one and appends into the same collection (§5) |
-| `playground/vgeo_viewer/select_cut.js` | the rule on the CPU | **the oracle**. The GPU cut is held to agreeing with it exactly |
+| `cut/__fixtures__/vgeo_select_cut.js` | the rule on the CPU | **the oracle**. The GPU cut is held to agreeing with it exactly |
 
 ## 2. Phase 1 — the page decode has holes, and they are load-bearing
 
@@ -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
 
@@ -257,7 +287,7 @@ is resident but not selectable — its clusters' parents are split across pages
 pages has not arrived. The clamp draws `C`'s parent `P`, correctly, standing in over that surface.
 But `C` itself satisfies §4's form — `project(C.parent) > τ` and `project(C.self) ≤ τ` — so a
 flat evaluation draws it as well, underneath `P`, and the depth buffer picks between two surfaces
-a few microns apart. This is exactly the failure `select_cut.spec.js` was written to catch, and
+a few microns apart. This is exactly the failure `vgeo_select_cut.spec.js` was written to catch, and
 the CPU traversal never meets it because *not entering a non-selectable group* is how it descends.
 A predicate has to say so out loud:
 
@@ -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
@@ -452,7 +535,7 @@ Four tiers, in the order they catch things.
    pages withheld. Multiset, not set: a duplicate is the failure mode that reads as corrupt
    geometry rather than as a missing page, and a set comparison cannot see it.
 
-   **At 64 KB pages, not the 8 KB `select_cut.spec.js` uses** (REVIEW_LEDGER D2). The 8 KB fixture
+   **At 64 KB pages, not the 8 KB `vgeo_select_cut.spec.js` uses** (REVIEW_LEDGER D2). The 8 KB fixture
    is the one that puts a group's parents on either side of a page boundary thirteen times over,
    which is what *that* spec is for — and it is the one fixture in which this spec's headline case
    cannot occur: measured, 8 KB puts exactly one group in every page of this torus, so a blocked