@woosh/meep-engine 3.24.0 → 3.26.0

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

@@ -0,0 +1,574 @@
+# 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.
+
+**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 `playground/vgeo_viewer/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) |
+| `playground/vgeo_viewer/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 **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 queue item is `(instance_slot, page_row, node_index)` — one lane each.
+
+```
+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
+```
+
+Enqueueing a *child page* means enqueueing `(instance, child_page_row, 0)` — its node tree's root.
+Uniform items, one kernel, no special cases.
+
+### 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 `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 Group chunks, and the serial loop that is not allowed to be unbounded
+
+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.
+
+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.
+
+### 4.7 Iteration bound
+
+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.
+
+"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.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 `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.