@woosh/meep-engine 3.60.4 → 3.60.5

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

@@ -1,657 +0,0 @@
-# Virtual Geometry — the GPU runtime
-
-> **Two sections are rewritten, and the rest stands.** An adversarial review on 2026-09-11 found
-> ~35 distinct defects in what this document described; they were worked to closure on 2026-09-12
-> and [REVIEW_LEDGER.md](./REVIEW_LEDGER.md) records each one against its commit. What that campaign
-> changed *here* is **§3.1**, where the variable `OffsetAllocator` became fixed-stride page slots
-> with the page header inside the slot, and **§4.9**, whose binding list named a buffer the kernel
-> does not bind and omitted one it does. §4's proofs, §4.2–§4.8 and §5 are as they were, and §8 —
-> the author's own review — is kept for the record with the ledger's corrections noted in it.
->
-> 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
-compute cut pass, the VRAM page pool, the wants/touches loop, and the seam through which a VG
-instance enters the meshlet pipeline — and it is kept as written plus §8, the adversarial review,
-because the review is where most of the design actually came from.
-
-What it describes now exists: `cut/` is the kernels, `layout/` the record formats,
-`VGeoRuntimeTables` the layout with no device in it, `GPUVirtualGeometryPool` the VRAM tier,
-`VGeoFeedbackLoop` the readback, and `graph_vgeo_expand_instances_to_meshlets` the seam. The cut is
-held to `vgeo_select_cut` exactly, and `playground/vgeo_runtime/` runs it on a device.
-
-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 `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.
-
-## 0. The shape of the answer, in one paragraph
-
-A cluster is drawn iff `project(parent) > τ AND (project(self) ≤ τ OR child group not selectable)`.
-That is **a pure function of one cluster record**. Design §4 pins it, and every hard problem in a
-GPU cut comes from noticing which half of that sentence you are leaning on. Lean on the
-*traversal* (descend the DAG, stop when fine enough) and you must dedup visits, because the DAG is
-many-parented and a group reached twice is drawn twice. Lean on the *predicate* (evaluate it
-everywhere) and you need no dedup at all, but you pay the resident set every frame, which is what
-§4 rejects. The runtime does both, in the only combination that has neither cost:
-
-> **Traverse the hierarchy to decide which clusters to look at; evaluate the predicate to decide
-> whether to draw them.**
-
-Visiting a cluster twice then costs a duplicate *record*, so the traversal dedups at **page**
-granularity only — one bit per (instance, resident page), which is affordable — and never at
-cluster or group granularity, which would not be. Visiting a cluster the traversal "should not"
-have reached costs nothing but the test, because the predicate is local and gives the same answer
-from every direction. §4 below proves the two halves that matter: no cluster is drawn twice, and
-no cluster the flat rule would draw is missed.
-
-## 1. What is already there, and what each piece is worth
-
-| piece | state | what the runtime does with it |
-|---|---|---|
-| `format/read/VGeoPage` | reads the page header, group table, cluster table | extended (§2) — `parent_sphere`, `aabb`, `payload_size`, the node table and every metric are in the file and unread |
-| page node tree (format §6.1) | written, validated, **no reader** | the sub-page cull; plan §2.3's open item half-closes here |
-| child-table traversal metric (format §5, §6.2) | written, validated, **no reader** | **still no reader, and the review below says why** (§4.8) — it is a prefetch structure, not a cut structure |
-| `VGeoContainerReader` | residency, activation, quarantine, cancel | the RAM tier; the runtime never fetches, it *wants* |
-| `VGeoResidencyManager` | byte budget, touch-LRU, shared fetch gate | the runtime hands it wants and touches and nothing else |
-| `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) |
-| `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
-
-`vgeo_read_page` reads two thirds of a cluster record and none of the node table. Everything it
-skips is something the GPU runtime needs:
-
-- `parent_sphere` (offset 24) and `parent_error` — `parent_error` is read, `parent_sphere` is not.
-  Half the cut rule is `project(parent_sphere, parent_error) > τ`. The CPU traversal never needed
-  it because arriving through a parent *is* that test; a predicate evaluated per cluster needs the
-  sphere.
-- `aabb` (offset 56) — this is the meshlet metadata's `bounds_box`, which the HZB filter and the
-  small-primitive cull read. Without it a VG meshlet cannot be culled.
-- `payload_size` (offset 96) — the number of bytes to copy into the data pool.
-- the **node table** (§6.1) and the page's own **metric** (§6) — the sub-page hierarchy. The page's
-  own metric arrives for free: format §11.10 makes it equal to node 0's, and the traversal always
-  starts a page at node 0.
-- the **child-table metrics** (§5) are read too, because a reader that decodes two thirds of a
-  structure is worse than one that decodes all of it — but see §4.8: the cut does not use them.
-
-Phase 1 is a pure addition to `VGeoPage` and `vgeo_read_page`, with the existing reader spec
-extended to hold the new columns against the bytes the writer emitted. Nothing that reads the page
-today changes.
-
-**Cost check — measured, 2026-09-12.** Per resident page this adds `4·4 + 6·4 + 4` bytes per cluster
-and `32` per node of CPU-side typed arrays. The gate this paragraph set was never discharged, so
-here it is: summing every typed array a decoded `VGeoPage` holds that is not a view over the page's
-own bytes, on a 240×120 torus,
-
-| page size | pages | overhead per page | mean | of the decoded bytes |
-|---:|---:|---:|---:|---:|
-| 64 KB | 44 | 0.2–4.1 KB | 2.9 KB | 6.1% |
-| 128 KB | 26 | 0.2–8.4 KB | 4.8 KB | 6.0% |
-| 544 KB | 13 | 0.2–33.9 KB | 9.4 KB | 5.9% |
-
-It is a **fraction** — six per cent, flat across page size — rather than a per-page constant, which
-is the more useful shape to know: the overhead is per cluster and per node, and a page's cluster
-count is what its size buys. The residency audit's "6.4–11.9 KB against a 544 KB page" is the mean
-of the same distribution and not its range; the widest page here is 33.9 KB, and a document quoting
-the narrow band as a bound would be wrong by 2.8× at the top.
-
-## 3. Phase 2 — the VRAM tier
-
-### 3.1 What a resident page costs on the GPU
-
-One `GPUMeshletManager.add_batch` (payload bytes → data pool, synthesized 40-byte metadata rows →
-metadata pool) **plus one fixed-stride slot** of the arena:
-
-```
-[ page header ][ node rows ][ group rows ][ cluster rows ]
-```
-
-A page's slot is at `page_row × slot_words`. There is no allocator, no growth path, no ceiling, and
-no page table: the header is the first eight words of the page's own slot, so the traversal reads it
-out of a buffer it already binds.
-
-**This is design §6's "fixed-size page-slot allocation", and it took a format change to be
-available.** The first draft here used a variable `OffsetAllocator`, on the argument that pages
-carry whole groups and a group may be oversized, so a hard slot size would refuse a legal file —
-format §11.5's escape. §11.14 closed that: `nominal_page_size` is a bound every page is within,
-announced by a feature bit, and the builder refuses a page size no group fits rather than writing a
-page over it. `GPUVirtualGeometryPool.register` refuses a container that does not carry the
-guarantee or carries it at a different size than the pool holds.
-
-**The stride is a choice, and the numbers behind it are worth carrying.** The provable worst case —
-a page of many minimal clusters — puts the runtime rows at about half the page size, which would
-over-provision the arena by fifteen times. The measured maximum, over a 160×80 torus built at 16,
-32, 64 and 128 KB pages, is **3.9%**. `vgeo_runtime_page_slot_words` takes an eighth, and an install
-that does not fit is refused and counted rather than overrunning its slot — the same direction
-`register` takes for a container built at the wrong page size, and for the same reason.
-
-The page header, in its slot:
-
-| field | why |
-|---|---|
-| `node_count`, `group_count`, `cluster_count` | sub-table extents; each sub-table is a count away from the one before it |
-| `meshlet_base` | the metadata-pool row of this page's cluster 0 — `meshlet_index = meshlet_base + local`. The one field that moves without the page moving: the shared meshlet pool relocates batches when it compacts, and the pool follows its `changed` signal |
-| `geometry_row`, `ordinal` | the claim index (§4.3) and the page-lookup base |
-| `page_index` | the container's global page index — what a touch reports |
-| `decoded_size` | what this page cost the tier, so an eviction refunds what the install charged rather than re-deriving it from a RAM tier that may have dropped the page |
-
-The group row carries its `parent_count` for the same reason: **this tier answers its own activation
-question**. Selectability is "every parent reference is live", and which references are live depends
-on which pages are resident *in the tier asking* — so the RAM tier's answer is not this one's, and
-publishing it here is what drew a group under a coarse stand-in on the ordinary streaming path.
-
-And a per-geometry **page lookup**: `total_pages` words mapping a container page index to a page
-table row, or `VGEO_PAGE_ROW_NONE`. 80 KB for a 20,000-page asset, one word written per install
-and per evict, and it is what removes every scatter from the install path: nothing else in the
-runtime has to be patched when a page arrives.
-
-> **Why a lookup and not a pointer.** The obvious alternative is to store the child page's *row*
-> in each referring cluster row. That makes an install a scatter over every cluster that refers
-> into the arriving page — across pages, unbounded, and re-done on every eviction. One indirection
-> in the shader is cheaper than that every time.
-
-### 3.2 Selectability
-
-The cut rule's clamp reads *selectable*, not *resident*, and `VGeoContainerReader.is_selectable`
-already computes it. The group row carries the bit; after an install or evict the reader's
-activation cascade is reflected into the group rows of the affected reader. The CPU keeps the
-bits in a shadow `Uint32Array` and uploads the dirty span — a page has a handful of groups, and a
-thousand resident pages is a few kilobytes.
-
-### 3.3 Budgets and eviction
-
-`GPUVirtualGeometryPool` holds a VRAM byte budget, a touch stamp per page row, and evicts on
-design §6's rule — LRU on last-touched under a protect window no shorter than feedback latency,
-and never a page with resident children *in this tier*. The tier's child check is the pool's own,
-not the reader's: VRAM residency is a subset of RAM residency, so `resident_child_count` answers a
-different question.
-
-Uploads are budgeted per frame in bytes. The root page is pinned.
-
-**The binding limit is `maxStorageBufferBindingSize`, not `maxBufferSize`** — design §6 says so and
-names `GPUMeshletManager` as clamping against the wrong one. The VG arena clamps against the
-binding limit, and the failure policy is a refused install with telemetry, never a silently
-invalid buffer.
-
-## 4. Phase 3 — the cut pass
-
-### 4.1 Shape
-
-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, 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)
-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, 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
-
-1. Read the node metric — sphere and `max_parent_error` — in object space, against the instance's
-   object-space eye and frustum (design §3.1: one matrix per instance, never one per cluster).
-
-   *Object space costs one correction.* Error and distance are both object-space, so a **uniform**
-   instance scale cancels out of `r_e · k / d` exactly and the projection needs no scale term at
-   all. A non-uniform one does not cancel, and the runtime inflates `r_e` by
-   `max axis scale / min axis scale` — conservative, so it over-refines rather than under-refines,
-   and it is exactly 1 for every instance that is not stretched.
-2. **Frustum-cull** the sphere. A node's sphere contains every `parent_sphere` under it, and
-   monotonicity makes `parent_sphere ⊇ self_sphere ⊇ the cluster's vertices`, so a node outside
-   the frustum discards a region.
-3. **LOD-cull**: if `project(sphere, max_parent_error) ≤ τ`, nothing under this node can satisfy
-   `project(parent) > τ`, so the entire subtree is skippable (format §6.2 — this is the field's
-   whole purpose).
-4. Interior → enqueue the `child_count` children. Leaf → enqueue a **group-chunk item** per group
-   per `VGEO_CUT_CLUSTER_CHUNK` clusters (§4.6).
-5. A group-chunk item first asks whether **its own group is selectable**, and stops if it is not.
-   This is not decoration — see §4.4, where leaving it out double-draws.
-6. Per cluster, the predicate:
-   - `project(parent_sphere, parent_error) ≤ τ` → not drawn, and no descent.
-   - `project(self_sphere, self_error) ≤ τ`, or `child_ref == NO_CHILD` → **draw**.
-   - resolve the child page: `SAME_PAGE` → this row; otherwise
-     `lookup[geometry.lookup_base + child_page_index]`.
-   - not resident → **draw** (clamp) and **want**.
-   - resident but the child group not selectable → **draw** (clamp), no want: there is nothing to
-     fetch, the group is waiting on a page holding another of its parents, and some other cluster
-     in this same cut is clamped directly against that page.
-   - otherwise → do not draw; claim the child page and enqueue its node 0.
-
-### 4.3 Dedup, and why page granularity is enough
-
-The page DAG is many-parented — 82 of 91 pages on a 98k sphere have more than one parent — so a
-descent that did not dedup would enqueue a page once per parent and draw its whole cut several
-times over. The claim is **one bit per (instance, resident page)**, set with `atomicOr` at
-enqueue, indexed `claim_base[instance] + page_row.ordinal`, where `ordinal` is the page's dense
-index *within its geometry* and `claim_base` comes from a prefix scan over visible VG instances of
-their geometry's ordinal capacity. `graph_prefix_scan_csdldf` already does this scan for
-mesh→meshlet expansion; this is the same pattern.
-
-Cluster-granular dedup is what this avoids, and it is worth being explicit about why it would not
-do: the resident cluster count is the number the design is trying not to pay per frame.
-
-### 4.4 The correctness proofs, and the hole the first draft had
-
-Everything above only works if three things hold. All three go in the kernel's own doc comment,
-because they are the reason its shape is what it is.
-
-**The predicate is not the one design §4 writes down.** §4's per-cluster form is
-
-> `project(parent) > τ AND (project(self) ≤ τ OR child group non-selectable)`
-
-and evaluating exactly that, per cluster, **double-draws**. Take a cluster `C` whose own group `G`
-is resident but not selectable — its clusters' parents are split across pages and one of those
-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 `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:
-
-> `own group selectable AND project(parent) > τ AND (project(self) ≤ τ OR child group
-> non-selectable)`
-
-Design §6 states the fact — "resident-but-inactive groups draw nothing" — without stating it as a
-term of the rule, because §4 was written for a traversal. The runtime evaluates the rule, so the
-runtime carries the term. This is the single most important line in the kernel.
-
-**No cluster is drawn twice.** A cluster is evaluated exactly once per (instance, page visit), and
-a page is visited at most once per instance by the claim. It is drawn only from its own page.
-Therefore at most one record per (instance, cluster). ∎
-
-**No cluster the flat rule would draw is missed.** Let `C` satisfy `project(C.parent) > τ`. Take
-any parent cluster `P` of `C`'s group. Every cluster of a group shares the consuming step's sphere
-and error, so `project(P.self) = project(C.parent) > τ`. Monotonicity gives
-`project(P.parent) ≥ project(P.self) > τ`, so `P` satisfies the predicate's first half, and by
-induction on the level (the root page is always visited) `P`'s page is visited and `P` is
-evaluated. `P` is not drawn — it fails `project(self) ≤ τ` — so it either enqueues `C`'s page or
-clamps, and it clamps only when `C`'s group is not selectable, in which case `C` must not be drawn.
-Neither cull can intervene: a node's sphere contains `P`'s `parent_sphere` and its
-`max_parent_error` is at least `P.parent_error`, so `project(node) ≥ project(P.parent) > τ` and
-the LOD cull does not fire; the frustum cull fires only when `C` is off-screen too. ∎
-
-The second proof is why *over*-visiting is harmless and *under*-visiting is not, which is the
-asymmetry the whole design leans on.
-
-One qualifier on the frustum cull, since the proof waves at it: a culled node can leave a genuine
-hole, because the parent that would have stood in is not drawn either (it fails
-`project(self) ≤ τ`) and the child is never reached. Everything involved is inside the culled
-sphere, so the hole is in geometry the frustum rejected. The agreement spec (§6) therefore runs
-with culling **off**, which is also how `vgeo_select_cut` defaults, and the culls are held against
-a separate claim: turning them on removes only clusters whose `self_sphere` is outside the
-frustum.
-
-### 4.5 Outputs
-
-- **Draw records** — `MESHLET_DEFINITION_STRUCT(meshlet_base + local, mesh_index)`, appended by
-  `atomicAdd` into the same meshlet collection the static expansion writes. Bounds-checked; an
-  overflow increments a stat rather than corrupting the count.
-- **Wants** — `(source_page_row, child_ref, child_page_index, priority)`, deduped by an atomic frame
-  stamp indexed the same way as the page lookup. Naming the page the want was *discovered through*
-  as well as the page wanted is what **unblocks** format §10's in-flight-pin item: §10 had it open
-  for want of anybody able to name the parent, because the format stores parent counts rather than
-  parent references. The record names it. Nothing pins anything yet, and §10 is still open — this
-  document claimed it closed, which it is not (REVIEW_LEDGER D4). Priority is the clamped cluster's
-  projected error, taken from the first writer — documented as a v1 heuristic; the residency manager
-  maxes across frames.
-- **Touches** — page rows, deduped by an atomic frame stamp per page row.
-- **Stats** — the fourteen of `VGEO_CUT_STAT`. These are what `M1`'s "selection cost measured" means
-  and what the playground asserts on.
-
-Every append is bounded, and every bound degrades in the same direction: **coarser or missing, never
-doubled**. A meshlet collection that fills drops records and counts them; a claim allocation that
-does not fit drops the *instance* rather than running it unclaimed, because an unclaimed instance
-is the one failure that draws twice. τ is the dial that makes the first case go away and the
-scene's VG instance count is the dial for the second.
-
-**The one exception, and it is now visible.** A queue item that does not fit, or a descent that runs
-out of iterations with work still queued, is a subtree never descended — and the parent that would
-have stood in over it was not drawn either, because it failed `project(self) ≤ τ`. That is a hole,
-not a coarser surface, and it was the one degradation nothing counted: §4.7 below promised the
-kernel recorded it and no such counter existed (REVIEW_LEDGER M8, D1). `QUEUE_DROPPED` is the items
-lost at the append; `QUEUE_REMAINING` is what was outstanding when the descent stopped, left behind
-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 One lane per cluster
-
-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.
-
-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.
-
-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.
-
-### 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
-with no reading (REVIEW_LEDGER M8). `VGEO_CUT_STAT.QUEUE_REMAINING` is that number now, left behind
-by one extra prepare pass after the loop, and `WAVEFRONTS` says how many iterations actually ran.
-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
-what plan §2.3 and format §6.2 both predict. Held against the kernel above, it buys **nothing**,
-and the reason is worth writing down so nobody adds it back:
-
-A want is emitted from a cluster that has already passed `project(parent) > τ` and
-`project(self) > τ`. The child page's metric covers that cluster's child group among others, so
-its `max_parent_error` is at least that group's `parent_error` and its sphere contains that
-group's `parent_sphere` — and the projection is monotone in both. So `project(child page metric)`
-is **always** greater than τ at exactly the moment the question is asked. The page-level test
-cannot reject what a per-cluster test has just accepted, because the per-cluster test is strictly
-tighter. The same argument kills the frustum half: the cluster's own `self_sphere` is a tighter
-frustum test than the child page's union sphere, available locally, for free.
-
-Where the metric copy *is* load-bearing is **prefetch** — walking a resident page's child table to
-rank pages nobody has asked for yet, which by definition has no cluster-level evidence to be
-tighter than. That is plan §3's territory and not this campaign's. `min_self_error` is in the same
-position: it ranks a want, and the cut never asks it anything.
-
-So plan §2.3 half-closes. The node tree gets its consumer; the child-table metric keeps waiting,
-for a named reason rather than for want of anyone to build it.
-
-### 4.9 Binding budget
-
-The engine requires a device to offer 10 storage buffers per stage and refuses one with fewer, so
-a kernel that declares more cannot run anywhere. The traversal declares **eight**:
-
-`vg_lookup`, `vg_arena`, `instances`, `queue_in`, `queue_out`, `claim`, `feedback`, `out_meshlets`
-— plus one uniform.
-
-This list was wrong in two directions when it was written, which is why
-`vgeo_cut_shaders.compile.spec.js` now asserts the exact count of every kernel rather than only the
-bound. It named `stamps`, which is not a buffer — the touch and want stamps are *regions of*
-`feedback`, which is what makes them per-frame and shared across every view and bucket — and it
-omitted `vg_lookup`, which the descent is gated on. And `vg_pages` is gone: a page's header is the
-first words of its own arena slot (§3.1), so the table that used to hold it is not a binding any
-more. That is the headroom this kernel did not otherwise have.
-
-It remains the reason the node/group/cluster tables share one arena rather than being three buffers,
-which is worth recording because "a table each" is the obvious first draft.
-
-`claim` and `stamps` are separate because their lifetimes are: the claim is per *invocation* and
-cleared, since each expansion site sees a different instance set; the touch and want stamps are
-per *frame* and shared across every view and bucket, so they are a persistent buffer compared
-against a monotonic frame counter and never cleared at all. Merging them would either clear the
-stamps (duplicating every touch and want across buckets) or stop clearing the claim (drawing every
-VG instance's cut once per bucket).
-
-## 5. Phase 4 — the seam
-
-```js
-const gr_bucket_meshlets = graph_expand_meshes_to_meshlets({ graph, input_meshes, ... });
-
-graph_vgeo_expand_instances_to_meshlets({
-    graph, input_meshes, output_meshlets: gr_bucket_meshlets, view, vg, limits
-});
-```
-
-One call beside each of the **three opaque** expansion sites, appending into the same collection.
-Everything downstream — the HZB meshlet filter, the material bucket, the indirect draw, the
-G-buffer — is untouched, because the record type and the metadata pool are the ones it already
-reads.
-
-Three, not the four `graph_expand_meshes_to_meshlets` has (REVIEW_LEDGER D3). The fourth is
-`prepare_meshlet_draw_commands_by_material`, which serves the transparent and alpha-tested buckets
-and is handed a scene and an optional camera *resource* rather than a view context — where a cut
-needs the camera's uniform buffer to put each instance into object space. DESIGN §9 scopes non-opaque
-VG instances out of v1, and `GPUSceneRows.attach_mesh` says so out loud when one is attached, because
-a VG instance in that path expands to zero meshlets and draws nothing at all.
-
-And one thing the seam has to refuse: a rasterization path recording on a **different**
-`FrameGraph`. `GPUSceneShadowmapContext` reaches `graph_rasterize_scene_fast_raw`, which carries the
-seam, on a graph of its own — so a cube face inside an open frame would run a whole cut at the main
-camera's projection scale into a resource handle belonging to a graph that has never heard of it.
-`graph_vgeo_expand_if_enabled` checks the graph against the one the frame was opened on and skips.
-
-Three things make that a one-line seam rather than a new pipeline:
-
-- **The instance list is already the right one.** Each expansion site is handed a set of visible
-  mesh instances for one bucket and one HZB pass. Those sets are disjoint (the two-way filter
-  splits positive from maybe), so running the cut over each of them costs one cut per view in
-  total, and a VG instance cannot be cut twice.
-- **VG meshes expand to zero static meshlets.** `geometry.meshlets_count` is 0 for a VG geometry,
-  so `shader_meshes_to_meshlet_counts` already contributes nothing for them.
-- **`GEOMETRY_METADATA_STRUCT` gains one field**, `vg_row`, `0xFFFFFFFF` for everything that is not
-  virtual. That is how a shader tells a VG instance from a static one.
-
-## 6. Phase 5 — proof
-
-Four tiers, in the order they catch things.
-
-1. **WGSL parse + validate + binding budget**, as every shader module in this tree has.
-2. **The agreement spec — the one that matters.** Build a torus with `vgeo_build`, install it into
-   a real `VGeoContainerReader`, mirror it into a CPU model of the arena, and run the cut kernels
-   under `ComputeShaderEmulator`. Assert the **drawn cluster multiset is exactly** what
-   `vgeo_select_cut` returns, over a sweep of camera positions and τ, both fully resident and with
-   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 `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
-   group is a blocked page, no page is ever mixed, and the cut's own-group term is unreachable.
-   At 64 KB the median page holds eight groups and the state is ordinary.
-
-   What the spec withholds matters as much as what it builds. Withholding from the **reader** makes
-   a page missing from both tiers, which is the easy case; withholding from the **tables** alone
-   makes VRAM a strict subset of RAM, which is the ordinary streaming state and the one every test
-   here used to skip. See C1.
-3. **`SoftwareGPUDevice`** for the pool's orchestration — install, evict, budget, page-row reuse
-   and the meshlet manager's allocations — where no shader has to run. Not the arena's growth:
-   there is none, and has not been since the fixed-stride conversion (REVIEW_LEDGER C3). The
-   same tier is what holds the **seam**, which records passes rather than running them:
-   `graph_vgeo_expand.spec.js` compiles the cut onto a real `FrameGraph` and asserts what came out
-   of the recording, and `VGeoFeedbackLoop.spec.js` runs a readback that really lands.
-4. **The playground**, `playground/vgeo_runtime/`, drawing a streaming container through the real
-   meshlet pipeline with a `__state()` a headless Chrome session can assert on: drawn triangles
-   track τ and resolution and not source triangle count; clamped falls to zero as pages arrive;
-   the same τ sweep is watertight.
-
-## 7. Order, and what each step leaves green
-
-| step | landed | proved by |
-|---|---|---|
-| 1 | page decode: metrics, node table, `parent_sphere`, `aabb`, `payload_size` | `vgeo_read_page.spec.js`, against the writer's bytes and the payload's own positions |
-| 2 | record structs + the arena + the pool | `GPUVirtualGeometryPool.spec.js` on a `SoftwareGPUDevice` — whole-buffer comparison against the tables, since a dirty range that was not marked leaves a page pointing at another page's clusters |
-| 3 | the cut kernels | `vgeo_cut_agreement.spec.js`, against `vgeo_select_cut`, multisets, seven cameras × four thresholds, resident, RAM-withheld and **VRAM-withheld**, one geometry and two, culling on and off, and the collect pass's own record rather than a fabricated one |
-| 4 | the seam + `vg_row` + `VirtualGeometry` | `graph_vgeo_expand.spec.js`, on what the seam records onto a real `FrameGraph`: the passes, the resource each is bound to, the feedback version it publishes, and a graph that is not the frame's getting nothing. It says three opaque call sites — and **nothing else**; see below |
-| 5 | feedback readback → residency | `VGeoFeedbackLoop.spec.js` on a real frame graph, plus the playground: 13 pages, one resident, streamed to 9 by the cut's own wants |
-| 6 | playground + headless drive | an nvidia/lovelace adapter; the τ sweep in `playground/vgeo_runtime/README.md` |
-
-**Step 4's row said "4,667 engine specs green", and that was not evidence** (REVIEW_LEDGER P7). Not
-one of those specs executed a line of the seam: they were green before it existed and green after,
-which is a statement about the seam not breaking anything rather than about the seam working. A row
-of a proof table has to name a test that would go red.
-
-Replacing it with "step 6, the headless drive" was closer and still not enough. The drive is a
-whole-system check on one adapter and it cannot be run per commit; a seam defect that the drive's
-six numbers happen not to move — the tail pass bound to the wrong queue at an odd `max_iterations`,
-say — is invisible to it. The row above names `graph_vgeo_expand.spec.js`, which is the tier that
-can go red on one line of the seam, and the drive stays what it is: the only tier that has ever
-noticed the playground failing to boot at all (REVIEW_LEDGER, re-review 2026-09-12).
-
-One thing that step 6 found and no earlier tier could: the feedback resource is **versioned**, and a
-second expansion site that wrote version 0 again after the first had produced version 65 is reading
-stale contents while claiming not to. The FrameGraph refuses to compile a graph that does it, which
-is why `GPUVirtualGeometryRuntime.publish_feedback` exists at all.
-
-## 8. What the adversarial review changed
-
-Kept here rather than silently folded in, because three of these are things a reader would
-otherwise re-derive — and the first one is a bug the plan shipped with.
-
-1. **The predicate double-draws as design §4 writes it.** A resident-but-not-selectable group's
-   clusters satisfy it while their coarse stand-in is also drawn. The rule needs an *own group
-   selectable* term that a traversal gets for free and an evaluator does not. §4.4.
-2. **The child-table metric is not a cut structure.** The per-cluster test is strictly tighter at
-   the moment the want is emitted, so the page-level test can never reject anything. Its consumer
-   is prefetch. §4.8. Plan §2.3 predicted the cut would read both accelerators; it reads one.
-3. **A node leaf's cluster loop was unbounded** — 4 groups × 4096 clusters in one lane, on legal
-   input. Group-chunk queue items bound it and widen the common case. §4.6.
-4. **`claim` and `stamps` cannot share a buffer**, because one is per-invocation-and-cleared and
-   the other is per-frame-and-not. Merging them either duplicates every want across buckets or
-   draws every instance once per bucket. §4.9.
-5. **Object space needs a scale correction** for non-uniform instance scale, and *only* for
-   non-uniform: the uniform case cancels exactly, which is worth knowing before adding a term that
-   does nothing. §4.2.
-6. **Overflow must degrade in one direction.** A full meshlet collection drops records; a claim
-   allocation that does not fit drops the instance rather than running it unclaimed. §4.5.
-7. **A frustum cull can leave a real hole**, in geometry the frustum rejected. Named, and the
-   agreement spec runs with culling off for that reason rather than by accident. §4.4. What the
-   review did not say is that culling is **on** by default and therefore had no oracle at all, which
-   is how a near plane extracted with the wrong sign shipped (REVIEW_LEDGER M1, M2). It has one now:
-   turning culling on removes only clusters whose own sphere is outside the frustum.
-
-### 8.1 What §8 got wrong, and the sweep that found it
-
-The adversarial review above is the author's own, and a second one on 2026-09-11 — twelve reviewers
-over disjoint dimensions, every finding attacked by three verifiers — contradicted it in three
-places and found ~35 distinct defects it had not. [REVIEW_LEDGER.md](./REVIEW_LEDGER.md) is that
-sweep, what it cost to close, and what it itself got wrong.
-
-Three of its findings are worth carrying here rather than only there, because they are about the
-shape of the thing rather than about a line of it:
-
-- **A tier has to answer its own residency questions.** Selectability, the bytes an eviction
-  refunds, and eviction's child rule were all taken from the RAM tier by the VRAM tier, and each of
-  them is a different answer over a different set. The VRAM tier holds what it needs to answer them
-  now (§3.1).
-- **A readback is about a frame that has gone.** The layout it is decoded with, and the identity of
-  every page row it names, belong to that frame and not to this one. Both are snapshotted when the
-  reading is scheduled.
-- **Proof tiers are not interchangeable.** Nothing below the headless drive exercises the
-  engine-integration path, and the suite being green says nothing about it. §6's fourth tier is a
-  required check.
-
-## 9. What this does **not** do, deliberately
-
-- **No proxy geometry, no shadow-view cuts** (plan §3.2, §3.3). One cut per view is what §4 pins;
-  a view that does not justify a cut taking a proxy instead is the next campaign, not this one. The
-  seam enforces it rather than assuming it: a rasterization path recording on a `FrameGraph` other
-  than the one the frame was opened on is skipped (§5).
-- **No position quantization** (plan §4.2). It is a `payload_encoding` id and a decode-shader
-  change, and it is orthogonal to every line here.
-- **No GPU-driven allocation** (plan §3.4). The arena is CPU-allocated, one fixed-stride slot per
-  page, which is the shape that makes a device-side allocator a later swap rather than a rewrite —
-  and slots make it a smaller swap than variable blocks would have.
-- **No slot-size classes.** One page size per pool, checked at `register` and refused otherwise
-  (§3.1). A tier that reconciled two page sizes would need a table of slot sizes, and that is a
-  later change than this one.
-- **No non-opaque VG instances** (design §9). The cut runs beside the opaque expansions only, and a
-  VG instance with a transparent or alpha-tested material draws nothing — said out loud at
-  attachment rather than discovered on screen.
-- **No compaction of `GPUMeshletManager` under VG churn.** Growth appends and moves nothing;
-  compaction is still a CPU-side rebuild and still has the unhandled address-migration TODO
-  downstream. VG pages are near-uniform in size, so the holes an eviction leaves are re-usable by
-  the next install, and the campaign to fix compaction properly is plan §3.4's.
-- **No disk tier** (design §6). CDN + RAM + VRAM.