@woosh/meep-engine 3.25.0 → 3.27.0

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

@@ -0,0 +1,637 @@
+# Virtual Geometry — the cut becomes state
+
+**2026-09-14, revision 2** after an adversarial pass over revision 1 (ten findings; the ones that
+changed the design are marked *(rev 2)*, and §6.1 — which rev 1 called the blocking question — is
+answered against the builder and the container validator).
+
+A design, not yet a commitment: nothing here is built. It supersedes nothing until it does, and what
+it proposes to change in `RUNTIME_PLAN.md` is §4 — not the cut *rule*, whose proofs stand unchanged,
+but the claim that the rule is evaluated from the root every frame.
+
+It also asks for one **format** change (§2.1). That is deliberate and it is the reason this is
+written before any code: `.vgeo` has no upward edge, and whether it gets one decides which of two
+very different runtimes we build.
+
+## 0. Why — measured, not argued
+
+A `.sgpt` capture of `playground/vgeo_runtime/` (4090, torus 12,288 faces, τ=1, one instance) and a
+sweep driven through CDP against the live page. **Read medians**: this machine throws ~400 µs stalls
+that land on unrelated passes too — `mesh frustum cull` has median 3.07 µs and max 468.99 µs in the
+same capture — so a mean over frames is mostly environment.
+
+The frame runs **16 traverse dispatches** — two expansion sites, `max_iterations` 8 each. Their cost
+is not spread across them:
+
+| ordinal | 3 | 5 | 7 | 9 | 11 | 13 | 15 | 17 |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|
+| median, µs | **40.96** | 2.05 | 2.05 | 2.05 | 2.05 | 2.05 | 2.05 | 2.05 |
+
+One pass carries it and the rest are at the 1.02 µs timestamp tick. And that pass is **not the
+geometry**. Holding the scene still and sweeping `descent_steps`, with `items` fixed at 78 and
+`drawn` fixed at 31:
+
+| `descent_steps` | 4 | 8 | 16 | 32 | 64 | 128 |
+|---|---:|---:|---:|---:|---:|---:|
+| first traverse, 1 instance | 11.3 | 18.4 | — | 36.9 | 52.2 | — |
+| first traverse, 256 instances | 13.3 | 25.6 | 38.9 | 46.1 | 62.5 | 94.2 |
+
+**A dispatch costs ≈ 9 µs + ~0.5 µs × `descent_steps` + work.** The slope is the same at one
+instance and at 256, so it is neither memory latency nor an occupancy problem: it is the serial
+dependent chain of ~16 subgroup operations every step executes whether or not the wave still holds
+anything — two full scans to pack what the wave keeps, two more for the spill, the five-shuffle
+owner search, six payload shuffles, elect and broadcast. A dispatch lasts one wave's step loop and
+every wave runs that loop concurrently, so idle steps are paid at full price, once.
+
+The other half of the measurement is the one that changes the target. At `descent_steps` 8, adding
+instances of the same geometry:
+
+| instances | 1 | 16 | 64 | 256 | 1024 |
+|---|---:|---:|---:|---:|---:|
+| items descended | 78 | 1,248 | 4,992 | 19,968 | 79,872 |
+| clusters drawn | 31 | 496 | 1,984 | 7,936 | 31,744 |
+| cut, µs/frame | 97.2 | 131.0 | 156.8 | 159.7 | **160.7** |
+
+`QUEUE_REMAINING` 0 and nothing dropped throughout. **1024 instances cost what 64 do.** The cut is
+not a per-instance cost and the 100s-to-1000s target is already met; what it is, is a *constant*,
+and the constant is the depth of the DAG — which grows like log2(triangles) and is a property of
+the asset rather than of the scene. Deeper asset, bigger constant: the same kernel on a Zorah
+container runs 62.5 µs a dispatch where the torus runs 41.
+
+**What that table does not say *(rev 2)*.** Every instance sat at the same transform, so all 1024
+were at the same distance, selected the same level, and read the same rows — best-case L2 and a
+single working set. The item counts are honest (79,872 items really were descended) but the memory
+behaviour is not representative of 1024 instances spread through a scene at different depths.
+
+**Redone with spread transforms *(§7.2)*.** Same torus, instances on a grid three radii apart, the
+camera pulled back each time to frame the whole grid:
+
+| instances | 1 | 16 | 64 | 256 | 1024 |
+|---|---:|---:|---:|---:|---:|
+| items, stacked | 65 | 1,040 | 4,160 | 16,640 | 66,560 |
+| items, spread | 65 | 512 | 1,664 | 1,222 | 1,968 |
+| pages visited, spread | 6 | 80 | 265 | 348 | 984 |
+| cut µs/frame, spread | 116.6 | 162.7 | 158.7 | 146.3 | **100.2** |
+
+The flatness survives, and it is not the L2 that saves it: spreading instances over a scene and
+framing them all puts each one further away, so each selects a **coarser** level and the descent is
+shorter. 1024 spread instances descend 1,968 items where 1024 stacked ones descend 66,560, and the
+cut halves rather than growing. The two tables are therefore not the same workload — the stacked one
+is the pathological case where every instance is near — and neither of them is a per-instance cost.
+That is the claim §0 needed, and it now rests on both.
+
+**The free part first — and it is a quarter, not a third.** `drawn` is bit-identical at every
+`descent_steps` that drains, so the knob slices the descent and cannot change the selected set: the
+default is a pure schedule choice. What bounds it is **not** `descent_steps × max_iterations`
+exceeding the DAG depth. A wave keeps one child per lane and spills the rest, so a dispatch advances
+what it held by `descent_steps` levels and hands everything else to the next dispatch, and the
+dispatches a cut needs are
+
+> `ceil(depth / descent_steps)` **plus its spill generations**
+
+which is a breadth term the depth model has no room for. Measured over a full orbit of the deepest
+converted Zorah container — 27.9M faces, 17,172 pages, the 39 levels — at τ=1, `max_iterations` 8:
+
+| `descent_steps` | 32 | 24 | 20 | 16 | 12 | 10 | 8 |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| dispatches needed | 6 | 6 | 7 | 8 | 8 | >8 | >8 |
+| worst `QUEUE_REMAINING` | 0 | 0 | 0 | 0 | 0 | 14 | 208 |
+
+So **8 is not available at `max_iterations` 8** — it leaves the descent holding work, which §4.5
+makes a hole rather than coarseness — and 24 is the most the default can be lowered for no dispatch
+margin at all: the same six dispatches 32 needs, with a quarter fewer idle steps inside each. That
+is what §7.1 took.
+
+The ~3× was the torus, and the torus does no work: at 12,288 faces the cut *is* the per-step
+constant. On the container the second traverse alone is 309 µs of real descent, so the eight steps
+saved move the frame by **3.3%** — 591.8 → 572.4 µs over the close orbit, three repeats each and the
+two sets do not overlap. At the far orbit the same pair does not separate at all: repeats of one
+setting span 340–549 µs, because residency keeps growing across a session and a later run is simply
+holding more pages. That is why the table above is dispatch counts. Dispatch counts are integers,
+they are what the safety question is actually asked in, and they do not drift.
+
+It does not fix the shape either: a still camera still re-derives the same answer from node 0 every
+frame, 39 levels deep, once per active bucket per view (§3).
+
+## 1. What is kept between frames
+
+**The frontier**: per (view, instance), the set of **groups** the cut has descended to.
+
+Groups, not clusters, because that is the granularity the rule itself has. A cluster is drawn iff
+
+> `own group selectable AND project(parent) > tau AND (project(self) <= tau OR child group not selectable)`
+
+and of those, the first two terms are **group-uniform** — every cluster of a group is consumed by
+one step and carries that step's sphere and error (§2, verified) — while only the third varies per
+cluster. So a group is uniformly *reached*, and within it each cluster independently draws or
+refines. The frontier is the reached set; the per-cluster test over it is the cheap half, and the
+profile says so: 78 items descended to find 31 drawn clusters cost 41 µs. **Finding the pages is the
+entire cost. Testing the clusters is free.**
+
+**It reseeds the descent; it does not replace it.** The seed pass today emits one item per instance
+naming its root page's node 0. Seeded from the frontier instead, every other pass stays exactly as
+it is — the subgroup descent, the spill, the claim, the draw, the wants. What changes is that
+`descent_steps` then has to cover the *delta* between frames, one or two levels, rather than the
+depth of the DAG. The measured law stops working against us: 0.5 µs × 2 instead of × 32.
+
+**A stale frontier is never wrong.** Any consistent cut of the DAG is watertight — the same argument
+the clamp rests on. Too coarse costs detail, too fine costs triangles; neither costs a hole, as long
+as a group moves as a unit, which the group-uniform terms guarantee. Three consequences, and they
+are what make this buildable:
+
+- the per-frame update can be **budgeted** — N moves per view per frame, with no correctness cliff
+  when the budget binds;
+- validation can be **conservative** — when in doubt, fall back, never repair;
+- **hysteresis is free** (refine at τ, coarsen at ~0.85τ), which removes the flip-flop a per-frame
+  cut cannot avoid. Note that TAA jitter is *not* a source of that churn here: `vg_project` reads
+  the eye position and `projection_k`, and a sub-pixel clip-space offset changes neither. The churn
+  is camera motion, and it is two-directional — pan around a house and near walls refine while the
+  far side coarsens, in one geometry, in the same frame.
+
+**Only refinement is budgeted *(rev 2)*.** Coarsening strictly shrinks the cut and the draw that
+follows it, and its destinations are resident by §2's invariant, so refusing it is the expensive
+direction: a camera pulling back against a bound coarsen budget would hold the finest level on
+screen for as many frames as the budget takes to drain, which is a sustained frame-time spike rather
+than a transient. Coarsen every entry that asks; budget only the descent.
+
+### 1.1 Keying — what a frontier entry belongs to *(rev 2)*
+
+`instance_slot` is **not** an identity. `shader_vgeo_cut_collect` assigns it with
+`atomicAdd(&claim_widths.count, 1u)`, so it is a compaction index whose order is decided by GPU
+scheduling: an identical scene can hand the same instance a different slot on the next frame. A
+frontier stored against a slot would attach itself to a different instance, silently, and draw one
+object's cut through another's transform.
+
+The frontier is therefore keyed by the instance's **mesh row** — stable, already in the instance
+record as `VGEO_INSTANCE_OFFSET.MESH_INDEX`, and the same "entity is the row" identity the rest of
+the scene state uses. The per-frame instance list maps slot → mesh row in one read, so a reseeded
+seed pass resolves its frontier without a second structure. The store itself is a dense table
+indexed by mesh row, like every other GPU-managed component.
+
+That also answers where the frontier *lives*: not in a frame-graph transient, which is recycled, but
+in a runtime-owned buffer with the pool and the tables.
+
+## 2. Walking up
+
+Coarsening is half of every camera movement, and mixed with refinement inside a single instance.
+A design that can only descend would have to answer every coarsen by re-descending from the root —
+the cost this whole document is trying to remove, paid on the common case. **So either the runtime
+can walk up, or keeping a cut is not worth doing.**
+
+**How often it actually moves the frontier, measured *(§7.2)*.** Less than "half of every movement"
+suggests, and the reason is worth knowing before the kernel is written. When the camera pulls back,
+a frontier group's clusters stop being drawn and their parents' clusters must be drawn instead — but
+**47% of frontier entries already draw some clusters and refine others** (measured below), so the
+parent group is usually *already in the frontier* and the coarsen changes which of its clusters draw
+rather than adding an entry. Only the coarsen whose destination is not already there needs the
+upward edge, and that is 0.0–0.8 entries a frame at a walking camera.
+
+So §2.1 stays: when the edge is needed there is no other way to find the destination, and a
+re-descent from the root is the alternative. But the coarsen path is not a hot path, which is a
+reason to write it for clarity rather than for throughput.
+
+Today it cannot, and not merely when a page is missing. The cluster record is
+`self_sphere, parent_sphere, self_error, parent_error, child_ref, child_group, …`: the parent fields
+are *metrics of the consuming step*, not a reference to what consumes it. The group record carries
+`parent_cluster_count` — a count, deliberately. Every edge in `.vgeo` points down.
+
+Three things are already in place, and they are what make the addition small.
+
+**One step per group, and the decision is local — verified *(rev 2)*.** `vgeo_build_levels` builds a
+group from exactly one step (`group.clusters = step.child_clusters`), writes that step's error and
+sphere into every child's `parent_error`/`parent_sphere`, and writes the *same* values into every
+parent's `self_error`/`self_sphere` while pointing each parent's `child_group` at that group. The
+container validator then enforces it per (parent, child) pair with exact equality — "one group step
+writes one value on both sides" — and separately that `parent_error ≥ self_error` per cluster.
+Monotonicity is imposed at construction rather than hoped for: the step's error is floored by
+`max_child_error(child_clusters)`, and its sphere is built to contain both what it consumed and what
+it produced.
+
+So the coarsen test a cluster reads is **bit-identical** to its parents' own draw test — the same
+floats, so the same IEEE result, with no tolerance argument and no vote. Every cluster of a group
+agrees, every parent of that group agrees, and none of them has to communicate to find out. That is
+the Nanite locality property, and here it is a validated invariant rather than an aspiration.
+
+**Tested, not only argued *(§7.5)*.** A CPU oracle that starts at the pages nothing refines into and
+walks up through §6.3's table selects the *same multiset of clusters* as `vgeo_select_cut` descending
+from the root, over 7 camera positions × 4 thresholds on a 160×80 torus. It never compares two
+floats for nearness: it reads `parent_error`/`parent_sphere` off the child and
+`self_error`/`self_sphere` off the parent and requires the same IEEE answer. That is the whole design
+resting on one property, and the property holds on real build output.
+
+**The predicate for "may I walk up" exists and is maintained.** `VGEO_GROUP_FLAG_SELECTABLE` is
+"every parent reference is live", kept incrementally by `VGeoRuntimeTables` — an install counts the
+references a resident parent page's selectable groups make into the arriving page, an eviction takes
+them back out (`RUNTIME_PLAN_2026_09_14` §3). A group in the cut is selectable by construction, so
+**its parents are resident, and selectable in turn, all the way up**. Coarsening a drawn group is
+therefore always legal; a cascade of several levels is legal. The kernel still checks — the check is
+one lookup — but the check is not expected to fail, and when it does the answer is §4's fallback.
+
+**The coarsen decision needs no new data.** Per the verified identity above, `project(parent) ≤ τ` on
+a cluster of G *is* the parents' `project(self) ≤ τ`. The format change is one edge, not a new
+metric.
+
+### 2.1 The format change — **landed**, as `format_version` 4 (§7.3)
+
+What follows is the proposal as written; the shipped shape matches it, with the offsets settled and
+the width question answered below. `VGEO_FORMAT.md` §6.3, §6.4 and §11.15–16 are now the reference.
+
+One thing the plan did not anticipate: the parent tables are not optional per page, so they are part
+of what a page *costs*, and `vgeo_assemble_pages` lays pages out against `nominal_page_size` before
+the writer ever sees them. The assembler therefore has to budget for a group's parent entries while
+deciding which page the group lands in — bounded by one parent page per entry, since the exact
+parent-page count depends on the placement being decided. Without that, a build simply refuses
+itself: the first attempt put a 16 KB-bounded page at 16,396 bytes.
+
+The other is that nothing has to be rebuilt. `parent_table_offset` reads zero on every container
+written before this, which is exactly "no upward edge", so a version-4 reader takes old files and a
+version-3 reader takes new ones. `min_reader_version` did not move. **The 2,975 converted Zorah
+containers are all version 3**, so the coarsen path of §7.5 and the frontier of §7.6 meet assets
+with no parent tables and have to fall back rather than assume — the same fallback §4 already
+defines, reached for a different reason.
+
+Mirror the child table, minus everything a parent does not need. A child reference must carry a
+fetch range because the child may be absent; a parent reference never does, because a parent of a
+drawn group is resident by the invariant above. So this is 4 bytes an entry, not 48.
+
+**Group record (§6, 8 B — no growth).** The `reserved u16` at offset 6 becomes `parent_first`, an
+index into the page's group-parent table. `parent_cluster_count` at offset 4 is already the length.
+
+| offset | type | field | |
+|---:|---|---|---|
+| 0 | u16 | cluster_first | unchanged |
+| 2 | u16 | cluster_count | unchanged |
+| 4 | u16 | parent_cluster_count | unchanged — now also the length of the list below |
+| 6 | u16 | **parent_first** | was `reserved` |
+
+**Group-parent table (new, in the decoded page).** `parent_entry_count` × 4 B:
+
+| offset | type | field | |
+|---:|---|---|---|
+| 0 | u16 | parent_ref | index into the page's parent-page table, or `SAME_PAGE` |
+| 2 | u16 | parent_cluster | cluster index within that page |
+
+**Parent-page table (new, in the decoded page).** `parent_page_count` × 4 B, deduplicated, one entry
+per distinct page holding a parent: just `page_index u32`, resolved through `vg_lookup` exactly as
+the cut already resolves a child. It lives in the *decoded* page rather than beside the plaintext
+child table, because nothing needs it before decode — no fetch range is computed from it — and in
+the blob it compresses with the other tables (§5: tables are 7% of page bytes at 1.6×). It is not
+optional per page, so it also raises `decoded_size` and therefore the RAM tier's budget by the same
+fraction *(rev 2)*.
+
+**PageHeader (§6, 56 B — no growth).** Two of the eight reserved bytes at offset 24 become
+`parent_table_offset u32`; two more `parent_entry_count u16` and `parent_page_count u16`.
+
+**`parent_first` is capped, not widened — answered *(§7.3)*.** The concern was real:
+`parent_entry_count` is Σ `parent_cluster_count` over a page's groups and `group_count` is itself a
+u16, so the arithmetic does not forbid overflow the way `child_ref` does. The measurement says the
+distance is not close. Across **8,899 pages of 30 converted Zorah containers**, from 1 MB to 120 MB:
+
+| | mean | worst |
+|---|---:|---:|
+| parent entries per page | 17.4 | **26** |
+| parent pages per page | 4.9 | 18 |
+| parents of one group | — | 5 |
+
+The u16 bound stands **2,521× above the worst real page**, and 40 of 8,899 pages carry no parent
+entry at all. So the cap is `VGEO_MAX_PARENT_ENTRY_COUNT` and the group record keeps its 8 bytes.
+The cost is also smaller than §2.1 estimated: 17.4 + 4.9 entries at 4 B is about 90 bytes against a
+56–256 KB page, a tenth of a percent rather than "well under 1%".
+
+**Cost.** Sum over groups of `parent_cluster_count` × 4 B, plus 4 B per distinct parent page. At the
+converted assets' shape — a few parents per group — that is single-digit bytes per group against
+56–256 KB pages: well under 1%, and compressible.
+
+**Arena (runtime).** The page slot gains a fourth section:
+`[header][node rows][group rows][cluster rows][parent rows]`, addressed by a `vg_parent_base` that
+follows the existing pattern, with `PARENT_ENTRY_COUNT` in the page header row and `PARENT_FIRST` in
+the group row. The slot stride is already a uniform (`page_slot_words`), so nothing else moves.
+
+**Build invariants to add (§11).** Every parent reference resolves to a cluster whose `child_group`
+is this group; `parent_cluster_count` equals the list length; the list is deduplicated and sorted by
+(page_index, cluster), so the election in §3 is deterministic on the GPU.
+
+## 3. The frame
+
+Per view, one dispatch over the frontier, replacing the seed:
+
+1. **Validate** (§4). An entry that fails takes its instance out of the incremental path for this
+   frame.
+2. **Test.** For each cluster of each frontier group, the existing rule, unchanged — draw, clamp,
+   want.
+3. **Move.** `project(self) > τ` and the child group selectable → the child group enters the
+   frontier, under the refine budget. `project(parent) ≤ τ` → its parents' groups enter,
+   unbudgeted (§1). Both are the existing descent code, seeded differently.
+
+   **G leaves only when every one of its clusters has moved *(§7.2)*.** Rev 2 wrote "and G leaves
+   it", which is wrong: `project(self)` is per cluster, not group-uniform — §1's own list says so —
+   and a group whose clusters disagree has to stay in the frontier for the ones still drawing while
+   its child groups enter for the ones refining. That is not an edge case. Measured on a converted
+   container at a walking camera, **47% of frontier entries draw some clusters and refine others**
+   (34.6% on a smaller one), so removing G on the first cluster that refines would drop about half
+   the frontier's drawn surface every frame. An entry's departure is therefore a count reaching
+   zero, not a flag being set, and that is one more word per entry rather than a different design.
+
+   The budget is **one bound per view per frame**, streaming: entries are taken in frontier order
+   from a persistent cursor, so a frame that runs out resumes where it stopped rather than starving
+   whatever sorts last. One frontier serves **every expansion site of a view** — it describes where
+   the camera is, not what the depth prepass concluded — and no site can move an entry another
+   already moved, because their instance sets are disjoint. See §6.3 for what "disjoint" was
+   verified to mean, and for the two things rev 2 got wrong about those sites.
+4. **Draw** is unchanged, and so is everything downstream of `out_meshlets`.
+
+**Dedup is a refine-side problem only *(rev 2)*.** A cluster names exactly one `child_group`, so
+distinct groups have disjoint parent sets and coarsening can never append the same group twice — no
+claim, no election. Refinement can: `parent_cluster_count > 1` is precisely several clusters naming
+one child group. Because §2 makes their decisions bit-identical, the append can be elected rather
+than deduplicated — a refining cluster appends the child group only if it is the **first entry of
+that group's parent list**, which §2.1's sorted, deduplicated table makes a single comparison. No
+bitmask, and nothing sized by instances × groups.
+
+A camera cut is the one case where a bounded number of refine steps is not enough. It is also the
+case the view already detects — `indicate_view_change` exists, and per-view previous-camera state is
+already kept — so the answer is to drop the frontier and take today's root descent for that frame,
+at today's cost, which is exactly what §4's fallback already does for a different reason. That
+signal is a TAA hint rather than a statement about the cut, so the durable form is a counter: an
+instance whose frontier wants to move more than K entries in one frame is cheaper to re-descend
+than to walk *(rev 2)*.
+
+## 4. Validation, without coupling pages to cuts
+
+Do not maintain page → cut back-references. The entry names a `page_row`; let the row say whether it
+still holds the occupant the entry was written against.
+
+**Use the generation, not `visible_from` *(rev 2)*.** Rev 1 proposed mirroring
+`GPUVirtualGeometryPool#visible_from[page_row]` — "the frame whose flush publishes the row's current
+occupant" — and comparing `visible_from[r] ≤ F`. That works for the *feedback* path, where F is the
+frame the cut ran and the record is read on the CPU, but on the GPU it makes every entry carry a
+frame number and every check an ordering argument, including the case of a row installed twice
+within one frame. `VGeoRuntimeTables#generations[page_row]` is a plain counter bumped on install:
+the entry stores the generation it saw, validity is one equality, and there is no clock. Mirror that
+word into the arena page header at install — one `u32`, written where every other page field is.
+
+Together with `VGEO_GROUP_FLAG_SELECTABLE` for the parent side, it covers both failure modes: the
+row was refilled, or the way up was evicted.
+
+**The fallback is not repair, and it cannot be deferred.** An invalid entry disqualifies its
+*instance* for the frame, which then seeds from the root — today's path, today's cost, already
+correct. It must happen in the **same frame**: a dropped entry's surface is not covered by anything
+else, because the stale cut had already descended past its ancestors, so postponing the re-descent
+is a hole rather than a coarse stand-in *(rev 2)*. Steady state is incremental; residency churn
+degrades to what we have now, which is also exactly when the cut is changing anyway.
+
+**What that costs, stated honestly *(rev 2)*.** Because the fallback is same-frame, the graph must
+keep encoding a ladder deep enough for a worst-case root descent every frame, even on frames where
+no instance uses it. The frontier removes the ~41 µs first traverse; it does **not** remove the ~50
+µs of empty prepare/traverse pairs that the ladder costs when every dispatch is empty. So the
+expected win is roughly half of today's cut, not all of it, and the next lever after this is the
+ladder itself — fusing prepare into traverse, or finding a bound that lets the encode shrink. Rev 1
+claimed the ladder could collapse to a single pair; it cannot, and §6.5 is struck.
+
+## 5. Per view, and CSM
+
+Frontier entries are groups, and the measured shape is **4.0 clusters per group, 3.2 of them
+selected** (§7.2, converted container) rather than the ~8 rev 2 assumed — so a scene drawing 31,744
+clusters is ~10,000 entries, not ~4,000. An entry is `(page_row, group, generation)` plus the mesh
+row it belongs to and the departure count §3 now needs — 16 B packed, or 12 B if the table is
+segmented per mesh row rather than carrying it — so that scene is **120–160 KB per view**, and a
+scene drawing a million clusters is ~5 MB per view. Five views (main plus four cascades) is tens of
+MB rather than single-digit. Still a fraction of what storing the cut per *cluster* would cost, and
+still affordable, but it is the number to size the buffer from.
+
+Note that "per view" is the frontier's granularity and **not** the granularity the runtime can
+express today: §6.3 found the params buffer is frame-global, collapsed across sites with a `Math.min`,
+and `projection_k` is set once in `begin_frame` from one view's screen height. Per-view anything is
+work §7.6 has to do first, and it is not small.
+
+Cascades are the good case: a snapped cascade that did not move needs no update at all, and its
+frontier is stable for many frames. But a cascade that *does* snap changes its projection wholesale,
+which flips many decisions at once — that is the worst case for the budget, and it is exactly when
+the counter in §3 should give up and re-descend rather than walk *(rev 2)*.
+
+Per-view state is not novel here — the HZB and the previous camera are already per view — but the
+closer precedent is `VGeoRuntimeTables`: selectability is a derived structure over the page DAG that
+is *kept and patched on install and evict* rather than recomputed. This is that pattern applied to
+the view-dependent half, with the same eviction hooks.
+
+## 6. Open — the things still to settle
+
+1. ~~Do all parents of a group come from one consuming step?~~ **Answered *(rev 2)*: yes.** One step
+   builds one group; both sides of the step carry bit-identical error and sphere; the validator
+   enforces it. Parents may still live in several *pages* — that is what
+   `parent_cluster_count`'s "`SAME_PAGE` included" means — which is why §2.1's table carries page
+   references rather than cluster indices alone.
+2. ~~Frontier dedup.~~ **Answered *(rev 2)*: election over the sorted parent list, refine side
+   only** (§3). No bitmask.
+3. ~~Is the frontier per view or per (view, bucket)?~~ **Answered: per view, and the partition is
+   verified — with two corrections *(§7.2)*.**
+
+   The load-bearing half holds. A view's expansion sites receive **disjoint** instance sets, and it
+   is disjoint by construction at every step: `shader_instances_rasterization_bucket_sort` derives
+   `bucket_index` from the mesh's one material and does a single `atomicAdd` and a single write, so
+   a mesh row lands in exactly one bucket; `shader_hzb_mesh_filter_2way` is one `if`/`else` on one
+   predicate with one append in each arm, so within a bucket positive and maybe cannot both hold a
+   row; and phase two consumes only `instances_maybe` through a one-way filter that appends a
+   subset. No instance is cut twice, so one frontier per view is safe and nothing can move an entry
+   another site already moved.
+
+   **There are not two sites — and that is a defect, not a shape to design around.** The
+   phase-one seam call sits *inside* the `ShadeDrawMode × ShadeDrawSide` loop of
+   `graph_rasterize_partial_opaque`, so a standard view records one cut per **active opaque bucket**
+   plus one for phase two. The engine already says so where rev 2 did not read it —
+   `GPUVirtualGeometryRuntime`: "once per bucket per HZB pass per view".
+
+   **Phase two already does it the right way**, which is what makes this a fix rather than a design
+   question. `graph_rasterize_remaining_opaque` filters its instances once, expands statics once,
+   cuts once, filters meshlets once, and only then calls `graph_sort_meshlets_by_bucket_id` and
+   loops the buckets to rasterize each slice with its own primitive state. Phase one is the outlier,
+   and the asymmetry is visible in its own buffers: `instances_maybe` is a single shared collection
+   every bucket iteration appends into, while `instances_positive` is created fresh per bucket.
+
+   What per-bucket costs: a cut is a whole ladder, and an idle prepare/traverse pair measures
+   **3.07 µs** on this machine (§0), so `max_iterations` 8 is ~25 µs of ladder per site before any
+   work, plus collect, seed and remainder. Nine active opaque buckets is nine of those where one
+   would do — and nine static expansions of the same instance set as well. **Decided: one cut per
+   view, bucket the meshlets afterwards**, which is the phase-two shape applied to phase one.
+
+   **The sets are disjoint but do not cover.** An instance reaches zero sites when it is
+   non-opaque, when its bucket is inactive, when phase two's re-test finds it occluded, or when the
+   2-way filter overflows. That is harmless here for the reason §1 gives — an instance not cut this
+   frame simply does not move its entries, and a stale frontier is never wrong — but "partition" was
+   the wrong word and the design should not lean on coverage anywhere else.
+4. ~~Budget shape.~~ **Answered: per view, and streaming.** One bound on entries moved per view per
+   frame, held across instances rather than divided among them, with a persistent cursor into the
+   frontier so that an instance the bound cut off is where the next frame starts. Coarsening is
+   unbudgeted (§1), so the bound is on the descent alone.
+5. ~~What `descent_steps` becomes.~~ Struck *(rev 2)*: §4 shows the ladder has to stay encoded for
+   the fallback, so the knob is a tuning question for the delta path (2–4) and a separate one for
+   the fallback path (8), not a collapse.
+6. ~~**`parent_first` width** — cap or widen.~~ **Answered: cap *(§7.3)*.** The histogram is in
+   §2.1 — worst page 26 entries against a 65,535 bound, so the group record keeps its 8 bytes.
+7. ~~What the probe measures next.~~ **Answered *(§7.2)*.** Spread transforms are in §0. The churn
+   number, measured by running the CPU reference's descent at consecutive camera poses and diffing
+   the reached group sets — a frontier entry being a group with at least one selected cluster — on a
+   converted container of 1.2M faces and 694 pages:
+
+   | motion | radii/frame | frontier | entered refine | entered coarsen | left | moves/frame |
+   |---|---:|---:|---:|---:|---:|---:|
+   | orbit | 0.002 | 168 | 0.1 | 0.0 | 0.1 | 0.08% |
+   | orbit | 0.01 | 176 | 0.7 | 0.0 | 0.4 | 0.44% |
+   | orbit | 0.05 | 196 | 2.6 | 0.8 | 3.1 | 1.71% |
+   | dolly | 0.005 | 26 | 0.2 | 0.0 | 0.1 | 0.78% |
+   | dolly | 0.02 | 37 | 1.1 | 0.0 | 0.4 | 2.93% |
+   | dolly | 0.05 | 136 | 13.5 | 0.1 | 6.6 | 10.02% |
+
+   **The budget is small.** Under 2% of the frontier moves per frame at any orbit speed worth
+   rendering, and a dolly fast enough to cross the object in twenty frames reaches 10%. A bound of
+   ~16 entries a view a frame covers everything but the fastest dolly, and §3's counter is what
+   catches that one. Refinement dominates entries by better than 10:1 for the reason §2 now gives.
+
+   Two caveats on these numbers. The container did not fit the RAM tier — 232 of 694 pages — so a
+   frontier here is smaller than a fully resident one would be; and every entering group was
+   classified as arriving from a neighbour it had in the previous frontier (the "other" column was
+   0.0 throughout), which says the churn measured is the camera and not the stream.
+
+## 7. Order, and what each step leaves green
+
+1. ~~`descent_steps` default 32 → 8~~ — **done as 32 → 24**, because the confirmation failed:
+   8 leaves `QUEUE_REMAINING` at 55–208 on the deepest converted Zorah container, and the model
+   that predicted otherwise is corrected in §0. 24 needs the same six dispatches 32 does at every
+   camera tried, so it costs no margin; the selected set is bit-identical, which is what makes it
+   no behaviour change. Independent of the rest, as planned.
+2. ~~The probe additions in §6.7~~ — **done.** Spread transforms fold into §0, the churn table
+   into §6.7, and the partition verification into §6.3. Three of them changed the design rather
+   than confirming it: mixed groups mean a frontier entry leaves on a count reaching zero and not
+   on one cluster refining (§3); a view has one site per active opaque bucket plus one, not two
+   (§6.3); and "per view" is not a granularity the runtime can express yet (§5).
+3. ~~Format: the parent tables~~ — **done**, as `format_version` 4. `VGEO_FORMAT.md` §6.3, §6.4,
+   §11.15 and §11.16; the cap decision in §2.1; the writer builds the edge, the assembler budgets
+   for it, the reader parses it and the validator holds it to the cluster records. Round-trip
+   coverage both ways: the reader's tables must equal the relation rebuilt from `child_group`, and
+   three corruptions — a parent entry naming the wrong cluster, a run that does not tile, a
+   parent-page table that is not ascending — are each caught. Nothing consumes the tables yet, and
+   the runtime is green at 301.
+4. ~~Arena: the fourth section, `PARENT_FIRST`, and the generation mirror~~ — **done.** The slot
+   is `[header][node rows][group rows][cluster rows][parent rows]`, addressed by `vg_parent_base`;
+   a parent row resolves to a global page index at install exactly as a cluster row does, so a walk
+   up reads the shape the descent already reads. The group row took a fifth word rather than
+   padding to eight, and the page row took `PARENT_ENTRY_COUNT` — which is what a coarsening kernel
+   checks instead of asking an asset its version — and `GENERATION`. `slot_range` learned the
+   section, or the parent rows would never have been uploaded. Still nothing consumes them.
+
+   **A verification surface went away mid-session, and §7.5 needs it.** The `vgeo_runtime`
+   playground draws nothing in headless Chrome: `begin_frame` runs, the feedback resource is open,
+   the adapter is an NVIDIA Lovelace with subgroups, the container builds and its root page installs
+   with a selectable group — and `VGEO_CUT_STAT.PAGES` stays 0, so the seed never reaches its first
+   line and nothing reports an error.
+
+   It is **not** any of steps 1–4. It reproduces in a detached worktree at 5289ade4f, a commit whose
+   only change is Markdown, and the probes in §0 and §6.7 above were taken through this same surface
+   earlier the same day. What changed in between is the browser: Chrome stable installed
+   **153.0.8010.37 at 21:28**, between the last probe that drew (21:07) and the first that did not.
+   Dawn in 153 passes indirect-dispatch validation through immediate data and overwrites the
+   application's, so every `var<immediate>` read by a shader launched with
+   `dispatchWorkgroupsIndirect` reads 65,535 — and `shader_hzb_mesh_filter_2way` reads
+   `bucket_index` that way, emits no survivors, and hands the seam an empty instance list. That is a
+   browser regression with its own investigation; the one thing that does not fit is that Canary
+   155.0.8057.0 reproduced it here too, which is worth handing back to whoever owns that.
+
+   So §7.5's gate is the agreement spec, which is what this plan asked for anyway: a coarsen path
+   can be validated and run against the CPU reference under the emulator, and cannot be compiled by
+   Tint until a browser on this machine draws again.
+5. ~~A `coarsen` path in the traversal kernel~~ — **done**, behind `VGEO_CUT_FLAG_COARSEN`, and
+   the gate holds: a cut seeded at the leaf pages and walked up draws exactly what the CPU oracle
+   walks up to, which is exactly what `vgeo_select_cut` descends to. The same run with the flag off
+   draws **nothing**, so the walk is doing the work and not the seed.
+
+   The path is small because the kernel already had the branch. `vg_visit_cluster` identified
+   "below the cut" and returned nothing; now, under the flag, the group's first member expands into
+   its parent list instead. The election is free — `project(parent)` is group-uniform because every
+   cluster of a group shares one consuming step, so member 0 reaches the same answer as the rest and
+   the rest defer to it with nothing communicated. Each child is one entry of the parent rows, and
+   it claims the page it resolves to when it is *executed* rather than when produced: a group with
+   several parents would otherwise make its producer claim each, count only the ones it won, and
+   hand any lane a rule for building the k-th won page out of five numbers. One extra queue hop
+   costs less, on a path §6.7 measures at under one entry a frame.
+
+   **What it cost, and §7.6 needs to know.** The node metric's `max_parent_error` cull is a
+   **descent-only** accelerator and the flag turns it off. Its premise — a subtree nothing can be
+   drawn in is a subtree worth skipping — is exactly wrong for a walk up, where being below the cut
+   is what sends a group to its parents. With the cull on, a cut seeded at the leaves drew nothing
+   at all: the subtree carrying the whole walk was pruned at its first node, silently. A node has no
+   parent list of its own (the upward edge is per group), so there is nothing to coarsen from at
+   node granularity and entering the subtree is the only way to reach the groups that can.
+
+   So a page walked *up* through is evaluated whole, with no LOD pruning. That is affordable exactly
+   because §1's frontier means the walk is one or two levels rather than the depth of the DAG — it
+   is an argument for the frontier, not against the coarsen path, but it does mean the fallback in
+   §4 must stay a *descent* and never a walk up from below.
+6. The frontier: storage keyed by mesh row (§1.1), the reseeded seed pass, validation, the budget.
+   Behind a flag, with the root descent as the fallback path it already is.
+
+   **6a — per-view state. Done.** A view owns `VGeoViewCut` beside its HZB and its previous camera,
+   and that is where a frontier will live. It carries this view's params buffer, written at the seam
+   where the view is known. One buffer per view rather than offsets into a shared one: views are
+   few, a uniform is tens of bytes, and packing them buys nothing against giving every per-view
+   value a second index to be wrong in. `begin_frame` takes one destructured argument and no
+   projection, because a frame does not have one.
+
+   That fixed a live defect on its own. `projection_k` is screen height over field of view, and one
+   buffer on the runtime made it a property of the frame, written by whichever view opened it — so a
+   shadow cascade selected a level of detail for a screen it is not drawn to. Pinned: two views
+   cutting in one frame must disagree about it, must each get what their own height and lens imply,
+   and must not be reading the same bytes.
+
+   **6b — one cut per view. Not done, and it is the next thing.** §6.3 has the shape and the
+   precedent: phase one restructures into the phase-two order — a shared positive collection, one
+   static expansion, one cut, one meshlet filter, `graph_sort_meshlets_by_bucket_id`, then the
+   bucket loop for rasterization alone. It is a change to the main opaque path for *all* geometry
+   rather than to anything under `virtual/`, and it cannot be looked at: §7.4's note explains why no
+   browser on this machine currently draws. That combination is why it is written down here rather
+   than taken.
+
+   **6c — the frontier. Done, in its simplest form, and that form is not the one §1 describes.**
+
+   A cut records the **page rows it drew from** into a per-view bitmask, and
+   `shader_vgeo_cut_reseed` puts those rows back on the queue the next frame instead of node 0
+   of the root. Measured on the agreement spec's torus with the camera unmoved: **19 wavefront
+   generations become 4**, `DRAWN` identical at 161. The ladder is what a cut is paid in, so
+   that is the whole of why a cut is kept.
+
+   **Pages, not groups.** §1 asks for a set of groups; this is a set of page rows. A page is the
+   unit the claim is built on and the unit a visit evaluates whole, so a reseeded page needs no
+   new item kind, no entry format, no allocator and no dedup beyond the claim the descent
+   already takes — and a 4,096-row tier is 128 words a view against the 120–160 KB §5 sizes a
+   group-level frontier at. Every group of a reseeded page is re-tested by the pure rule, and
+   testing one the cut did not need costs the test.
+
+   **Recorded at the draw, not at the claim.** Recording at the claim names every page the
+   descent passed *through*, and reseeding from that set is more work than the root descent it
+   replaces. That was the first version, and the "fewer pages" test is what caught it. A page
+   that drew something is a page the cut is standing on.
+
+   **Items is not the meter.** The coarsen flag turns off the node metric's LOD cull (§7.5), so
+   a reseeded page is evaluated whole and tests slightly *more* clusters — 463 against 463 → 476
+   — while visiting far fewer pages. Pages are what a fetch and a claim cost; wavefronts are what
+   the ladder costs.
+
+   **It spends the traversal's last storage binding.** The engine requires ten per stage of an
+   adapter and refuses one that offers fewer; the compile spec now pins traverse at exactly ten
+   and says there is no eleventh. Anything that kernel needs next must displace something or be
+   folded into a buffer it already binds.
+
+   What it gives up, and what is left:
+
+   - **Per-instance keying (§1.1) is not there.** Two instances of one geometry share a page
+     set — a superset of each one's own, so correct — and the reseed offers every page to every
+     instance, one lane per (instance, page row). Cheap at a handful of instances; not what a
+     thousand should do. Keying by mesh row is the change that lifts it, and it is where a group
+     frontier and §5's sizing come back.
+   - **The seam captures the frontier and does not yet read it.** Choosing reseed over seed per
+     view, and dropping a frontier whose tier has evicted since it was written — the pool's
+     eviction count against the one it was captured at, which is a host-side integer compare and
+     needs none of §4's per-entry generation — is the next step.
+   - **No budget.** §3's bound on entries moved per frame is not implemented, and §6.7 is why it
+     can wait: under 2% of a frontier moves per frame at any orbit speed worth rendering, and
+     the failure mode of no budget is a frame that does more work, never a wrong cut.
+7. Delete nothing until a capture on the Zorah container shows the incremental path beating the root
+   descent on the same scene.