@woosh/meep-engine 3.60.3 → 3.60.5

package/src/shade/renderer/geometry/virtual/VIRTUAL_GEOMETRY_DESIGN.md

@@ -1,787 +0,0 @@
-# Virtual Geometry — Design
-
-Status: **builder, container, reader and GPU runtime implemented; the runtime is under review and
-not shippable** — see [runtime/REVIEW_LEDGER.md](./runtime/REVIEW_LEDGER.md), which found seven
-critical defects including one that breaks §4's no-double-draw guarantee on the ordinary streaming
-path. §10's M1 is written below as closed; treat it as *built and not yet trustworthy*. This document pins only what
-is certain; everything else is listed explicitly under *Open*. Runtime home is this directory
-(`shade/renderer/geometry/virtual/`, mirroring `texture/virtual/`); builder lives with
-`core/geom/3d/topology/struct/binary/` and `core/graph/metis/`.
-
-What exists, in the order a newcomer meets it: `build/` turns a `Geometry` into a cluster DAG,
-`format/` writes and validates the `.vgeo` container ([VGEO_FORMAT.md](./VGEO_FORMAT.md)),
-`format/read/` reads one back a page at a time with residency and activation, `residency/` owns the
-RAM tier's budget, and `runtime/` is everything §7 describes — the selection buffer, the compute cut
-pass, the VRAM page pool, the feedback loop, and the seam through which VG instances enter the
-meshlet pipeline ([runtime/RUNTIME_PLAN.md](./runtime/RUNTIME_PLAN.md)).
-
-`shade/playground/vgeo_runtime/` puts an ordinary `Mesh` in an ordinary `Scene` and draws it
-entirely from a **GPU** cut through the meshlet pipeline — it proves the engine seam, and
-`shade/playground/vgeo_scene/` opens a whole converted set at once, where the claim about a *scene*
-is measured. What proves the DAG, the format and the clamp is not a page at all: it is
-`runtime/cut/__fixtures__/vgeo_select_cut.js`, a CPU traversal of the same rule that every cut
-spec is held to. A third playground once drew that traversal on screen through Shade's direct
-geometry path, with its own renderer and its own streaming loop; once the GPU page could show
-everything it showed, it was a second runtime for no gain, and it was retired. §10 says which milestone that leaves us
-in, and the order the work actually arrived in.
-
-## 1. What and why
-
-Cluster-DAG continuous LOD (Nanite-family): the builder turns a source mesh into a DAG of
-fixed-size clusters at halving detail levels; the runtime selects a *cut* through that DAG
-each frame so that geometric error stays below a pixel threshold. Rendering cost becomes a
-function of resolution, not of source triangle count, and the asset streams — only a
-fraction is ever resident in RAM, and a smaller fraction in VRAM.
-
-VG is an **enabler and scaler**, not a replacement for good art practice. The stress cases
-that motivate it: CAD / digital-twin data (inconsistent density, no authored LODs, e.g.
-thousands of unique fasteners), large scans, and film-quality assets — up to billions of
-source triangles per scene. Instant first pixel on cold load is a hard goal.
-
-## 2. Fixed points
-
-What exists today, with its real contract: **shader-visible record formats and the
-algorithmic primitives are the fixed points; the managers and render-graph seams were
-built for whole-mesh static residency and need a VG-specific layer on top** — which the
-hands-off principle argues for anyway.
-
-- **Mesh structure**: `BinaryTopology` (BMesh-style, binary pools, float32 coordinates),
-  with `bt_mesh_validate`, `bt_merge_vertices_by_distance` (float32 weld quantum floor;
-  its contract requires a short-edge kill/collapse pre-pass — §8), boundary queries.
-- **Simplifier**: `bt_mesh_simplify(mesh, target_face_count, restricted_vertices,
-  protected_faces)` — greedy quadric edge collapse, optimal placement, pinned vertices neither
-  moved nor removed, protected faces never destroyed. Required extensions (all builder-side;
-  three of the four have since landed, and the list is kept because the reasoning is what makes
-  the fourth findable):
-  1. ~~report the max/accumulated quadric residual of a pass (§4)~~ **done**. It returns the
-     object-space distance the surface moved, measured *before* the cleanup pass — see item 2,
-     where that ordering turned out to be most of the fix;
-  2. ~~boundary constraint quadrics~~ **done**. Open and non-manifold edges now carry a
-     constraint plane through the edge perpendicular to its face, so a border can no
-     longer retreat at a recorded cost of zero — which it could, and which the round loop
-     leaned on, since converging a mesh of open shells means eroding them. Measured
-     before: 400 loose triangles built a root of 25 carrying `self_error = 0`, selected at
-     every distance and never refined. A second hole went with it: the error was taken
-     over *surviving* vertices, and geometry deleted outright leaves no survivor to carry
-     it, so `bt_mesh_simplify` now measures before its cleanup pass and returns an
-     object-space distance rather than a raw residual. A flat sheet still reports exactly
-     zero, which is the other half of the contract. The same mechanism later serves UV
-     seams (§9);
-  3. triangle-inversion (flip) rejection — **still open, and the only one of the four that
-     is**. Pin-forced placement along locked group perimeters is exactly where greedy QEM folds
-     over. Nothing in `bt_mesh_simplify` tests the sign of a face normal before or after a
-     collapse, and no build validation catches a fold, so this is a real gap rather than a
-     latent one;
-  4. ~~group-boundary **polyline** preservation~~ **done**. Pinning vertices does not by itself
-     protect the boundary *edges* between them: a collapse elsewhere in the fan can take away
-     the only face holding one, and the cleanup pass then removes it. `protected_faces` names
-     the faces carrying a group's boundary polyline, and `vgeo_build_levels` re-walks every
-     boundary edge after the call and throws if one is gone — a missing boundary edge is a crack
-     between two LODs that never closes, so the build stops rather than shipping it.
-- **Partitioner**: the ported METIS — `metis_partition_kway` (CSR in, deterministic via
-  fixed seed, single balance constraint, **unit vertex weights, no contiguity
-  guarantee**) and `cluster_mesh_metis(result, mesh, patch_size)` (face clustering with a
-  hard size ceiling, minimized edge cut, dense renumbering). Disconnected parts are
-  possible and matter (§3).
-- **Bounds**: `Miniball` (minimal bounding sphere, iteration-capped). That is the whole list —
-  **normal cones are not part of this design**. Backface cone culling is declined outright (§9,
-  plan §5), so `cone_reserved` was reclaimed by `format_version` 5 (format §7), and
-  `bt_face_cluster_compute_normal_bounding_cone` — the `BinaryTopology` port of the old
-  `TopoMesh` cone builder — has no consumer and no prospect of one.
-- **Renderer formats (the real seam)**: meshlets capped at 128 triangles / 128 vertices
-  (8-bit local indices); `MESHLET_METADATA_STRUCT`; the draw record
-  (`MESHLET_DEFINITION_STRUCT` = meshlet index + mesh); bucket pipeline issuing one
-  `drawIndirect` per material with instanceCount = meshlet count (no multi-draw needed);
-  HZB two-pass filters keyed on projected bounds against the previous-frame HZB (no
-  stale-ID interaction with a per-frame-changing cut); attribute encoding for
-  normals/tangents/colors (oct/packed). **Positions and UV0 are raw float32 today** —
-  cluster-local position quantization is new work spanning encode, metadata struct, and
-  every decode shader, not a finished capability.
-- **Renderer managers (need a VG layer, not reuse as-is)**: `GPUMeshletManager` pools
-  metadata+data via OffsetAllocator. **Growth no longer re-packs**: it appends, files the new
-  tail as free space through `OffsetAllocator#grow`, copies each old buffer into the larger one
-  at offset 0, and moves no record — so no address is patched and no `changed` fires.
-  **Compaction still is a CPU-side rebuild** — new buffer pair (transient ~2× VRAM),
-  CPU-retained metadata mirrors, full re-upload — and it is what closes the holes growth leaves
-  behind, which under VG's churn is the case that matters rather than the one that got cheaper.
-  Downstream, meshlet-address migration is still an acknowledged unhandled TODO in
-  `GPUGeometryManager` (it logs a warning and continues); it is now reachable only through
-  compaction, which narrows the hole without closing it.
-  Mesh→meshlet expansion is one shared FrameGraph helper — `graph_expand_meshes_to_meshlets`,
-  called from four rasterization paths — and it reads a geometry's `meshlets_address` and
-  `meshlets_count` as one contiguous static range. VG's scattered, dynamic residency does not
-  fit that (§6, §7 state what replaces them).
-- **Readback**: `graph_read_buffer` (MAP_READ scratch from the general buffer pool,
-  `mapAsync`, ≥1 frame latency). The virtual-texture system is the shipped precedent for
-  the whole feedback loop and pins its contract: in-flight readbacks capped, feedback
-  skipped entirely when saturated, occlusion-aware by construction (§6).
-
-## 3. Structure: the cluster DAG
-
-Pinned:
-
-- **Leaf clusters = meshlets** (≤ 128 triangles), from `cluster_mesh_metis` on the source
-  mesh, followed by a **connected-components split** (metis parts can be disconnected;
-  disconnected clusters/groups inflate spheres and force the exact LOD-lockstep
-  over-rendering this design criticizes fixed-32 grouping for).
-- **The round loop** (not a level sweep): hold a *frontier* of every cluster nothing has
-  merged yet; select a **band** of it by error; partition the band's *cluster adjacency
-  graph* (`metis_partition_kway`; edge weight = shared boundary size;
-  connected-components post-pass) into **groups**; lock every vertex on a group's outer
-  boundary (`restricted_vertices`); `bt_mesh_simplify` the group interior to ~50% of its
-  triangles; re-split the simplified group into ~half as many new clusters; those are the
-  *parents* of every cluster in the group. Parents go back into the frontier; clusters the
-  round did not use stay in it, untouched. Repeat until the frontier is one cluster — the
-  root. It is a DAG, not a tree: a parent spans a whole group of children.
-- **The band is an error octave**, `[e, e · growth]` from the frontier's minimum, widened
-  until it covers at least a fixed share of the frontier. Every cluster in a group shares
-  the group's error, so a sweep that merges whatever happens to be on a level writes off
-  nearly-exact geometry at its cruder neighbour's error, and hands the runtime page bands
-  spanning an order of magnitude of error when the cut it takes is a *threshold* on error.
-  The minimum share is not optional: on error spread thinly and continuously — a UV
-  sphere, poles against equator — an octave alone holds a handful of clusters, and the
-  round count then scales with the cluster count rather than its logarithm, which no
-  `level_count` can survive and which a build refuses outright past
-  `VGeoLevelOptions.max_levels`. Measured on a 98k-triangle sphere against a sweep: growth
-  4 cuts clusters-dragged-up by 38% for one extra level; growth 2 cuts it 60% for seven.
-  On geometry of uniform error the band is the whole frontier and this *is* the sweep.
-- **A level is an ordinal, not a generation.** A group's band ordinal is what orders pages;
-  its clusters may come from any level at or below it, because a cluster no round could use
-  waits. What the ordinal guarantees is the only thing the format needs: every group sits
-  strictly below the group holding its parents, so page order by descending level is a
-  topological order and every child reference points forward in the file.
-- **The group is the atomic LOD decision unit.** Locked boundaries plus the group-uniform
-  cut rule (§4) is what makes independent per-cluster decisions crack-free.
-- **Clusters own their payloads.** No vertex sharing across levels or clusters; each
-  cluster is an independently uploadable, contiguous, quantized meshlet. Duplication
-  along cluster borders is an accepted cost (cache coherency, page independence).
-- **Group size is adaptive.** Fixed 4 (Nanite) starves the simplifier on small groups
-  (locked perimeter dominates); fixed 32 (Virtuos) locks a large spatial footprint into
-  LOD lockstep and over-renders under a conservative group error. Proven approach from
-  the prior WebGL implementation: start small, grow the group when decimation quality or
-  re-clustering quality is poor.
-- **Termination is convergence to a single root, not a stall.** A round is accepted only
-  if it *strictly* shrinks the frontier; failing that it widens the band, then grows the
-  group. A build that cannot reach one root **throws** — the runtime starts its cut at the
-  root, and several parentless clusters is not a shape it can start from. The validator
-  enforces it from the bytes: exactly one cluster with `parent_error = +∞`, in page 0.
-- **A step aims at a cluster count, and a cluster is bounded by two numbers.** What the
-  simplifier is handed is a triangle target, but a cluster is capped at 128 triangles *and*
-  128 vertices, and on geometry that has come apart — seams, small separate parts, the
-  patches a collapse leaves behind once it has eaten the connective tissue — there are two
-  or three vertices per triangle rather than a half. Halving the triangles then does not
-  halve the vertices, the re-cut needs as many clusters as the group consumed, and the step
-  is worth nothing to the round. So the re-cut is *measured* and the target tightened on
-  whichever of the two ceilings the attempt broke, until the step strictly shrinks its
-  group — tightened by the overshoot rather than by the cluster ratio, because what it
-  costs is fidelity and the overshoot is the least it can pay. Measured on the Zorah
-  sample: 187 of its 3,163 primitives reached a frontier no grouping could shrink, every
-  one of them this, and a 188th ran out of `VGeoLevelOptions.max_levels` inching forward a
-  merge a round — the same refusal to merge, spent on depth rather than on a stall.
-- **Islands merge by proximity, once adjacency has nothing left to offer.** A cluster alone
-  in its connected component can never be coarsened — halving its triangles leaves one
-  cluster where there was one — so a mesh of separate shells has no root at all under
-  adjacency alone. Such clusters are bundled along a Morton curve. It is strictly the
-  fallback: a cluster the partitioner shredded off is folded back into the adjacent piece
-  it shares the most boundary with, never into the proximity pool, or a lone shell sixty
-  metres away ends up merged with a fragment of something else.
-- **Leaves are re-packed, never merged losslessly.** Where a group is all leaves and fits
-  inside one cluster, the union *replaces* them rather than becoming their parent. A step
-  of zero error is a step the cut rule can never take — `project((s, 0)) ≡ 0`, so the
-  parent never satisfies `project(parent) > τ` and the leaves under it would be stored,
-  paged, and never selected. This is what makes a scene of small separate parts tractable:
-  a thousand twelve-triangle bolts need cutting up differently, not simplifying. Above the
-  leaves the same union is refused, because a coarser cluster cannot simply be deleted —
-  a subtree hangs off it.
-- **The leaf cut does not pack across components; a group's re-split does.** Packing asks
-  "what is near what", and over the whole mesh the answer from a space-filling curve can be
-  sixty metres away. A group has already been chosen for proximity, so packing inside one
-  cannot reach further than the group does.
-- **Build validation must check**: group-boundary polylines survive their group's
-  simplification byte-exact; locked boundaries do not persist across consecutive rounds
-  (a band's seam with the rest of the frontier is locked for as long as its neighbours
-  stay out of the band — self-limiting, since the band's own error rises to meet them, but
-  unproven); the frontier converges to one root; no inverted triangles; error monotonicity
-  (§4); page-ancestry acyclicity (§5); sampled-Hausdorff spot checks against `r_e` (§4).
-- **Content addressing**: the asset's identity is `hash(output bytes)` — that is all
-  immutability and CDN caching require. Bit-reproducible builds (same input ⇒ same
-  output) are a *goal* scoped to a pinned toolchain (node major, deterministic seeds,
-  single-threaded or order-independent reductions), not a correctness requirement:
-  transcendental libm drift and parallel float reduction order make an unconditional
-  cross-platform pin unsafe.
-
-Open: exact group-size policy and its quality signals; simplification execution model
-(shared level topology with per-group restricted sets vs extracted group submeshes — the
-polyline guarantee above is the constraint either must satisfy); vertex-weighted
-partition balance (triangle-count balance instead of cluster-count balance).
-
-## 4. Refinement metric
-
-Distilled from the pixel-error musings
-([share.gemini.google/AfYiNvAB2kt0](https://share.gemini.google/AfYiNvAB2kt0)).
-
-Pinned:
-
-- **Error is an upper bound on the object-space distance from the *source* surface** — not an
-  estimate of it, and not a density heuristic. The threshold is a threshold, so wherever the
-  number reads low the cut draws a cluster it should have refined and nothing downstream can
-  tell it did.
-
-  **The quadric cannot be that number, and it is not a tuning question.** Evaluating a carried
-  quadric at a vertex's position gives the *mean* squared distance to the planes it stands for,
-  and a mean is never a bound: a vertex that destroyed one feature and stands for a thousand
-  planes it sits exactly on reports the feature divided by all of them. Measured against the
-  distance the surface had actually moved, sampled at the source vertices, the quadric reading
-  came back at `0.34` of it on a closed pyramid, `0.58` on an octahedron, `0.62` on a spike
-  standing off a plane, and `0.03`–`0.62` across a cone swept in height. Reading it at the
-  collapses rather than after the pass, and per endpoint rather than summed, narrows *when* it
-  is diluted and not *that* it is.
-
-  So the quadrics stay, and they decide **where** a collapse puts the vertex, which is what they
-  are good at. What it **cost** is a separate scalar carried per vertex, composed by the triangle
-  inequality at every collapse:
-
-  ```
-  bound[survivor] = max( bound[v1], bound[v2] ) + how far this collapse moved the surface
-  ```
-
-  Zero at the source, carried across levels beside the quadrics, combined across steps by
-  `max` — two steps sharing a pinned boundary vertex each produce a valid bound on what that
-  step folded into it, so it carries the larger. No gains-minus-results, which is a quadric
-  problem.
-
-- **The increment is how far the *surface* moved, not how far the vertices went.** A vertex
-  sliding within its own plane moves and the surface does not, and flat geometry is mostly
-  that — charging movement makes a flat wall refine forever, which is the one thing this metric
-  is not allowed to do (the flat-wall test below, that density heuristics were rejected on).
-  Measured, charging movement reported `15.9` where the surface had moved `0.98`, and `41.6`
-  on the same shape with a larger plane around it: the old dilution's mirror image, growing
-  with surface that never moved. So the increment is the distance from each endpoint's former
-  position to the survivor's one-ring — the geometry now standing where that surface was —
-  which the sliding case leaves sitting exactly on. With no one-ring left the patch was
-  consumed whole, there is nothing to measure against, and the movement is the only evidence
-  there is.
-
-  **Exactly zero, where it is zero.** A point nearer a triangle than the `float32` coordinates
-  can express is on it, and is reported as `0` rather than as the `1.6e-14` the closest-point
-  solve returns. Not pedantry: `project((s, 0)) === 0` is an explicit case and the
-  camera-inside-sphere `+∞` rule is conditioned on `r_e > 0`, so a flat cluster carrying
-  `1.6e-14` becomes undrawable at close range.
-
-  Measured against the surface's own movement: `1.00` on a closed pyramid and an octahedron,
-  `1.08` and `1.10` on a spike standing off a 13- and a 25-vertex plane — conservative
-  everywhere and within ten per cent of tight, and **not growing with the plane around it**.
-  Still sampled at vertices rather than over triangle interiors, so the sampled-Hausdorff gate
-  in §3 still earns its place.
-
-  **It costs nothing at a fixed budget.** The numbers rise — the arch primitive's root goes from
-  `3.786e-2` to `2.031e-1`, which is the old one having been that optimistic — so a given τ
-  buys a finer cut, and a caller who wants the old cluster count asks for a larger τ. At *equal
-  drawn cluster count* the picture is the same or better: `-9.3%`, `-6.7%`, `-6.4%`, `-3.1%`
-  of mean luminance against the old metric over a 16x range of cut depth. The ordering the cut
-  descends is preserved; what changed is what the number on it means.
-
-  Superseded: "a calibrated measure rather than a proven Hausdorff bound", and the whole of the
-  carried-quadric reading as the reported error. The carrying was right and stays; reading the
-  error off it was the mistake.
-- **Each pass reports what its own collapses cost**, and a caller carrying the bound across
-  passes carries it across them too (`vgeo_build_group_step` across its attempts, the frontier
-  across levels, the child-error floor below as a backstop). A vertex that arrives already
-  deviating needs no re-reading: it arrives carrying its own bound.
-
-  Superseded: sweeping the surviving vertices after the pass, "before faceless vertices are
-  cleaned away, so that a patch consumed whole still costs what it cost". The measurement point
-  was right about the faceless vertex — it is read at the collapse that consumed it now — and
-  the sweep threw away every sharper reading to get there.
-
-  **Open.** Whether τ converts *accurately* to conservative pixels is still not measured, only
-  the object-space half of it is. `container_diff` measures how different the picture looks,
-  which has no unit relationship to a pixel threshold; what would answer it is a readback of
-  world position at the cut and at LOD 0, projected, worst case in pixels against τ. Until that
-  exists, "conservative" here means the object-space bound above.
-- **A plane weighs the surface behind it, as a multiple of the mesh's mean triangle.** The
-  mean the error is read as has to be an average over the *surface*; over a plane count it is
-  an average over how the surface was cut, and a finely tessellated patch outvotes a coarse
-  one many times its size. Cutting one face in two along its own plane is the clean statement
-  of the defect — it adds no surface, and the metric heard the same plane twice. Weights are
-  ratios rather than areas because everything they are stated against is a ratio (the boundary
-  constraint is three *faces*; the attribute quadric summed with these weighs one per
-  triangle), and a slot holding square metres would make all of it depend on whether the asset
-  was authored in millimetres or kilometres. The reported error is a mean, which divides the
-  weights out again, so normalizing costs nothing there; it buys back every calibration.
-
-  This changes the quadric **matrix**, so it changes the placement solve and not only the
-  number — a behavioural change to simplification, landed on its own so it can be attributed.
-  `VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS` was calibrated against the diluted reading and is
-  **not** re-tuned here; it needs re-tuning against this one, separately.
-
-- **Composition across levels does not happen**, and that is the point of carrying quadrics.
-  The measured value is already deviation from the source; a step takes `max(measured, max(e
-  of child groups))`, where the floor exists only to impose monotonicity — the accumulated
-  quadric is not forced to rise when the vertex carrying the previous maximum is the one
-  collapsed away, and a parent claiming to be closer to the source than its own child would
-  make the cut oscillate.
-
-  Superseded: composing additively (`e_step + max(e of children)`) is what this replaced. The
-  triangle inequality justifies it as an upper bound and nothing else does — it loosens every
-  round and scales with the round count rather than with the geometry. Measured on a unit
-  sphere, the same ninety-triangle root read `0.36` built from 3k source triangles and `13.3`
-  built from 24k; carrying quadrics it reads `0.0315` either way, which is the same
-  approximation reporting the same number.
-- **Units guard**: if vertex placement ever moves to higher-dimensional quadrics
-  (position + UV + normal), errors are still evaluated by plugging the resulting
-  *position* into the pure 3-D geometric quadric ("dual bookkeeping": solve in high-D,
-  evaluate in 3-D), so `r_e` stays in meters. Never take a root of a mixed-unit residual.
-- **Per-cluster record stores two (sphere, error) pairs**, from *group* steps so all
-  siblings compute identical values:
-  - `self`: the step that created this cluster. Leaves store (own cluster sphere, 0).
-  - `parent`: the step that consumed it (roots: +∞).
-- **Monotonicity is enforced at build**: `parent.error ≥ self.error` and `parent.sphere ⊇
-  self.sphere`, transitively. Without it the cut oscillates and flat evaluation is invalid.
-- **Cut rule with residency clamp** — the per-cluster form, which the traversal reaches the
-  same answer as by stopping its descent rather than by evaluating it everywhere: draw a
-  cluster iff
-
-  `own group selectable AND project(parent) > τ AND (project(self) ≤ τ OR child group
-  non-selectable)`
-
-  The first term is not decoration: a group that is resident but not yet selectable satisfies
-  the rest of the rule while the coarser stand-in still covers the same surface, and both are
-  drawn a few microns apart — which reads as corrupt geometry rather than as a missing page.
-  The clamp is what makes "no holes, ever" (§6) true: without it, when the τ-selected
-  level lies below the streaming frontier, *no* resident cluster on that path satisfies
-  the pure rule and the guaranteed stand-in is never selected. The child-group
-  *selectable* bit flips **group-atomically** (a group never spans pages — §5 — and
-  becomes selectable only through activation — §6 — so page install/evict flips whole
-  groups; sibling disagreement would crack the frontier).
-- **Projection**: `err_px = r_e · screen_height_px / (2 · tan(fov_y / 2) · d)` with `d` =
-  distance from camera to the *closest point* of the pair's sphere (conservative).
-  `project((s, 0)) ≡ 0` unconditionally; the camera-inside-sphere ⇒ +∞ convention applies
-  only when `r_e > 0` (otherwise leaves become undrawable exactly at close range).
-- **The cut is a traversal, and there is one per view.**
-
-  *Traversal.* Descent from the root, testing a node or cluster and stopping when it is fine
-  enough, rather than a flat pass evaluating every resident cluster. Flat evaluation is
-  data-parallel and simple, and it does not scale: its cost is the resident set, which at the
-  scale this design targets is millions of clusters every frame, most of them off-screen. A
-  traversal costs the cut. It also gets two things for free that the flat rule pays for
-  separately — a missing page simply stops the descent, which *is* the residency clamp, and
-  culling at an interior node discards a whole region rather than one cluster. WebGPU guarantees no
-  forward progress across workgroups, so the persistent-thread answer (nvpro, vk_lod_clusters
-  comparison §2.4) is unbounded waiting and is not available; a wave redistributes its own
-  production among its lanes instead, and the descent's depth runs inside one dispatch. The
-  hierarchy it descends exists at two granularities. Pages form a rooted, acyclic,
-  fully-reachable DAG (§11.3–11.4 of the format), measurably
-  many-parented on any asset large enough to have more than one page per band, and every
-  child-table entry and page header now carries a **traversal metric** so a page can be tested
-  *before* it is fetched. Below page granularity, each page carries a tree over its own groups
-  (format §6.1–6.2). Cost, measured: 0.3%–1.6% of asset size.
-
-  *What exists.* `runtime/cut/__fixtures__/vgeo_select_cut.js` is this rule on the CPU, against a
-  partially resident container: descend from the root's parentless groups, refine where
-  `project(parent) > τ`, take the cluster where it does not, and stop where the child group is
-  not selectable — recording the want that would unblock it. It is the reference the GPU pass
-  has to agree with, and it is where the clamp was found to need *selectable* rather than
-  *resident* (§6). What it does **not** do is use either accelerator this section just
-  described: it descends group by group, and reads neither the child-table traversal metric nor
-  the page node tree. Both are written by the builder and checked by the validator, and nothing
-  reads either — the largest piece of built-and-unused machinery in the system, and the cut pass
-  is what it was built for.
-
-  *Per view.* **Virtual geometry is view-dependent by construction.** A cut is selected at one
-  camera's distances and pixel budget; it is the wrong cut for a shadow view, whose light may
-  sit a hundred metres behind the camera, and wrong again for each cascade. What is shared
-  between views is the *setup* — the traversal kernel, the residency state, the resident page
-  working set — not the result. Where a view does not justify a cut at all, it should take a
-  proxy mesh instead (plan §3.2, §3.3).
-
-  Superseded: this section previously claimed the cut was "view-agnostic in *coverage*" and
-  that shadow views could reuse the camera's. They cannot, and the claim is withdrawn.
-- **Threshold `τ` defaults to 1 px and is a runtime dial** — the single quality/perf
-  lever. Empirically (prior implementation), pops stay invisible well above 1 px:
-  headroom for weak GPUs and dynamic resolution integration. **Read that number with care**:
-  the prior implementation shipped `1 / face_count` as its group error, a density heuristic
-  this section rejects below, so the observation is about a threshold dial under a different
-  metric and is not calibration for `r_e`.
-- **Rejected**: pixels-per-triangle density heuristics — they fail the flat-wall test
-  (flat *closed-interior* geometry is exact at any triangle size; `r_e = 0` encodes that;
-  the qualifier matters — at *open boundaries* zero-residual erosion is real, which is
-  why §2 requires boundary constraint quadrics). And geomorphing — double residency and
-  bandwidth for a transition a tight metric already makes invisible; Epic disabled
-  theirs too.
-
-Open: separate UV/attribute error term (CAD rarely; textured game art maybe — §9); τ
-semantics under dynamic resolution scaling (native vs render pixels).
-
-## 5. Binary format
-
-A new container, designed for streaming: `.vgeo`. Requirements are pinned here; the
-concrete layout is specified in [VGEO_FORMAT.md](./VGEO_FORMAT.md).
-
-Pinned:
-
-- **Scale**: billions of source triangles per asset ⇒ 64-bit byte offsets everywhere.
-  Little-endian, versioned, magic-tagged header. All counts below are **lower bounds**
-  (cluster fill < 128 under the hard ceiling; per-level reduction < 50% happens): 1 G
-  tris ⇒ ≥ ~8 M leaves, ≥ ~16 M DAG clusters, tens of GB of payload at today's raw-f32
-  positions (~4 KB per 128/128 cluster). Budgets and page sizing are set from measured
-  fill in M2, never from these nominals.
-- **Immutable and content-addressed** (`hash(output bytes)` in header and filename):
-  perfect HTTP caching, CDN-friendly, no invalidation protocol.
-- **Fetch unit = size-bounded page** (64 KiB, `VGEO_DEFAULT_PAGE_SIZE` — **one** page size, against
-  Nanite's two, traded off between hiding fetch latency and both response time and VRAM per
-  resident page on a low-end device; this section's "order hundreds of KB" was a first-principles
-  guess and is superseded, see the constant's own note), fetched by
-  HTTP **single-range** requests and **independently decodable**: a group never spans
-  pages; a page carries whole groups with payloads in (near-)upload-ready encoded form.
-- **Pages carry the DAG, fetchably**: each cluster record stores its two (sphere, error)
-  pairs (§4) and a child reference (leaves: sentinel), and the page carries a
-  deduplicated **child table** with each referenced child page's exact byte range.
-  Page-to-page traversal is self-sufficient: an installed page fetches everything one
-  level down without consulting any global index. Wants (§6) are page indices resolved
-  entirely from the want-emitting page.
-- **The hierarchy itself is paged.** Per-cluster metadata alone reaches GBs at the stated
-  scale and cannot be unconditionally resident. Only the root page — the topmost
-  level(s), cluster records and payloads together, at minimum a complete drawable cut —
-  is always resident; deeper pages stream on demand.
-- **Time-to-first-pixel is O(1) by construction**: the fixed-size header directly carries
-  `(offset, size)` of the root page — first pixel needs header + root page only. The page
-  directory is **auxiliary**: fully derivable from the pages themselves, range-fetched
-  only for tooling and special tasks, never a runtime prerequisite (at billions scale it
-  is MBs).
-- **Page-ancestry is acyclic by construction**: child references point strictly forward
-  in the file (coarse-first order is topological); non-root pages hold clusters of a
-  single level band. Build-validated.
-- **Compression must not break random access.** Transparent HTTP compression does not
-  compose with range requests, so compression is per-page *inside* the container. Three codecs
-  are defined and all three shipped — `raw`, a bare LZ4 block, and a bare DEFLATE stream through
-  the platform's own zlib — chosen **per frame** rather than per file, so a page that would not
-  shrink is stored verbatim and says so. Measured, LZ4 is worth 1.12x–1.18x on the Stanford
-  models and deflate about seven points more for four and a half times the decode; deflate is what
-  the builder writes, because a build happens once and a fetch happens forever. The reason neither
-  is worth more is the reason to stop here: the payload is float32 positions and packed attribute
-  words, and it does not compress. Quantization (§2) is the lever, not the codec.
-- **Coarse-first layout**: pages ordered so a plain prefix read of the file yields a
-  complete coarse asset — progressive load without a feedback loop.
-
-Open: a page codec that knows what it is compressing — meshopt-style over the payload rather
-than an LZ matcher over its bytes — if quantization leaves one worth having;
-per-attribute quantization widths (cluster-local grids); relationship to
-`MeshletGeometrySerializationAdapter` (extend vs parallel).
-
-## 6. Streaming and residency
-
-Pinned:
-
-- **Three tiers with independent budgets**: CDN/network (whole asset) ⊇ RAM (page cache)
-  ⊇ VRAM (resident cluster pool). Residency is a small fraction of the asset in RAM and a
-  smaller one in VRAM. Instances of the same asset share pages and residency.
-- **The VRAM pool's hard ceiling is the adapter's `maxStorageBufferBindingSize`**, not
-  free configuration — pools bind as single storage buffers (spec default 128 MiB; Shade
-  requests adapter max, but low-end adapters stay low). Growth must clamp against device
-  limits with a defined failure policy; the low-limit fallback is a smaller pool + higher τ.
-  Multi-buffer sharding is explicit future work.
-  `GPUMeshletManager.grow` clamps now, having not before — but against **`maxBufferSize`**,
-  which is the wrong limit for an arena that binds as one storage buffer. Spec defaults are
-  256 MiB and 128 MiB respectively, so a buffer between the two is creatable and not bindable.
-  `GPUDatabase` clamps against the binding limit; `GPUMeshletManager` and
-  `GPUGeometrySDFManager` clamp against `maxBufferSize`. A VG pool has to pick deliberately,
-  and the reason this is worth stating rather than assuming is that `createBuffer` answers an
-  over-limit size with an *invalid buffer* rather than an exception — the failure is silent at
-  the point it happens and loud several frames later.
-- **The VRAM paging mechanism is new work**, not `GPUMeshletManager` as-is (§2): v1
-  intent is **fixed-size page-slot allocation** (no compaction, no CPU metadata mirror,
-  no transient 2× rebuild), plus propagation of address migration to every consumer —
-  the existing `GPUGeometryManager` TODO becomes load-bearing under churn.
-
-  What that rests on is the container, and it now holds: FORMAT §11.14 makes
-  `nominal_page_size` a bound no page exceeds, announced by a feature bit a pool can require.
-  Before that it was an advisory number the builder itself broke — 13 of 40 pages over it on a
-  measured build — and a fixed stride sized against it would have been a slot overrun. A pool
-  taking the guarantee is entitled to one slot size and nothing else: it refuses a container
-  built at a different page size rather than carrying a size-class table for it.
-- **Activation invariant (closure without dependency metadata)**: a group is
-  *selectable* iff **all** of its parent-cluster references are live — each referencing
-  cluster's page installed and that cluster's own group selectable (per-group reference
-  counter against the format's `parent_cluster_count`; root-level groups have count 0
-  and activate at install; activation cascades and flips whole groups). A selectable
-  cluster's entire ancestor cone is therefore installed and selectable — the closure
-  the cut rule needs, carried by a counter instead of dependency lists. The runtime
-  keeps a reverse-reference index for not-yet-installed pages (the same structure that
-  carries wants); a want targeting an already-installed page resolves as an activation
-  recheck, never a fetch. With the §4 clamped rule, any miss (or resident-but-inactive
-  group) has a coarser stand-in that *is selected* — streaming latency degrades
-  quality, never correctness. No holes, no double-draw, in any arrival order.
-  **Implemented**, in `VGeoContainerReader`: a live-reference counter per resident group, a
-  reverse index for pages not yet installed, cascades on both install and evict, and
-  `is_selectable(page, group)`. The double-draw half of that guarantee is not theoretical —
-  clamping on residency instead drew two levels over the same surface on 355 of 576 camera
-  positions of a 19-page bunny, up to 10.7% of drawn triangles in a doubly-covered region, and
-  it reads as corrupt geometry rather than as a missing page, which is what makes it hard to
-  attribute. 21 of that asset's 362 non-root groups have parents in more than one page, which
-  is all it takes.
-- **Feedback carries touches as well as wants.** Wants = pages whose refinement was
-  blocked; touches = pages actually selected this frame. Eviction is LRU on
-  **last-touched** with a protect window ≥ feedback latency — LRU on last-*wanted* would
-  freeze stamps at fetch time and evict exactly what is on screen (the classic
-  fallback-chain bug; the VT system already keys on touch for this reason).
-  **Implemented**, in `virtual/residency/`: `VGeoResidencyManager` holds the RAM tier's byte budget
-  across every registered reader, `touch(reader, page)` takes the stamp, `advance_frame()` moves the
-  protect window, and `evict_to_budget()` drops on the format §10 rule ordered by coldest touch.
-  It is a sibling of `format/` and not part of it, because a container cannot answer a question
-  about a scene. The reader stayed mechanics: it reports `resident_bytes` and enforces nothing, and
-  the manager is written entirely against its public surface.
-  The parenthetical above is load-bearing and should be followed rather than taken on trust:
-  `VTPhysicalCache` is the working implementation of this same rule, with a `#last_touch`
-  `Uint32Array` per slot, `touch`/`last_touch`, a lock flag for slots that may never be evicted,
-  and `find_eviction_candidate(current_frame, protect_window)` whose doc gives the window the
-  identical justification. The similarity is therefore convergent *by instruction* — this bullet
-  told the implementation to key on touch because VT does — and the only real difference is that
-  VT budgets a count of fixed-size slots, which is what lets it pick by linear scan at ≤ ~1k
-  slots. Budgeting **bytes** across **several** readers, and admitting a page against that budget
-  before the fetch out of the `decoded_size` its parent already carries, is the part with no
-  precedent in this tree; so are per-page retry-into-quarantine and per-fetch `AbortSignal`.
-- **The fetch cap has to be shared, and per-reader caps do not compose.**
-  `VGeoReadOptions.max_concurrent_fetches` bounds one reader, which is all a reader can see: four
-  readers at a cap of four each were measured issuing sixteen concurrent range requests, eight at
-  the default six issuing forty-eight. `VGeoResidencyManager` holds one total across every reader
-  as one priority queue, so a want's priority — pixels of projected error, comparable across assets
-  by construction — decides globally rather than within whichever reader asked first.
-  A shared cap is not itself a new idea here: `AssetManager.load_concurrency` bounds concurrent
-  top-level loads for the same reason and orders its queue through a negated priority into a
-  `BinaryHeap`, and `VirtualTextureManager` bounds `max_concurrent_loads` at 32. Writing that
-  negation a second time is what moved the queue out of this directory: it is
-  `core/process/ConcurrencyGate.js` now — a free-standing "run at most N of these at a time,
-  highest priority first" — and the `VGeoFetchScheduler` that shipped first was folded into it.
-  The other callers kept their own queues, each recording why where its cap is declared. What none
-  of them can do is compare two containers' wants — VT sorts its queue coarse-mip first, a proxy
-  that only orders within one texture, and `AssetRequestScope.final_priority` is hierarchical
-  rather than a common scale. The cut hands this one, so the global order is the half that is
-  actually new.
-- **Wants are occlusion-aware in v1** (HZB test in the want path, or previous-frame
-  feedback à la VT — which is occlusion-aware by construction). Frustum-only wants plus
-  error-priority would page in and pin entire occluded interiors, breaking both budgets.
-- **The wants loop tolerates its transport**: multi-frame `mapAsync` latency, a small
-  in-flight readback cap, and frames where feedback is skipped entirely (saturation) —
-  the VT contract. Priority = projected error reduction; requests dedup across frames
-  and instances; scoring/hysteresis details open.
-- **In-flight protection**: a fetch pins the page it was discovered through until the
-  child installs — known at queue time, purely local. Arrivals verify the
-  identity-seeded frame checksum; activation makes any arrival order safe beyond that.
-- **Network**: batched = adjacent wanted pages coalesced into **contiguous single-range**
-  requests over H2/H3 multiplexing (multipart ranges fail on real CDNs — S3 returns 200
-  + full body); responses are verified `206`, with immediate abort on `200`.
-- **Disk tier is an explicit per-page store or nothing.** The implicit browser HTTP cache
-  cannot serve as one: the Cache API rejects 206 responses and browsers do not usefully
-  cache/serve partial ranges at this scale. v1 may ship CDN + RAM only; the page store
-  (OPFS vs IndexedDB) is the open disk-tier design.
-- **Uploads are budgeted per frame** (bytes/frame cap) into the VG residency pool; the
-  root page is pinned; within each tier, a page is evictable only while none of its
-  child pages are resident in that tier (checked against its own child table —
-  leaves-first order emerges from the rule).
-
-Open: page store API choice; prefetch heuristics (camera velocity); priority scoring and hysteresis
-constants; the in-flight pin, which is now blocked on a `VGeoPageWant` that names the page it was
-discovered *through* rather than on nobody owning the budget (format §10 — it is an efficiency item,
-because activation is safe at every arrival order). RAM eviction is no longer open; the numbers in
-`VGeoResidencyOptions` are defaults to be overridden by whoever knows the device, not measurements.
-
-## 7. Runtime pipeline (per frame)
-
-1. Instance-level culling — existing.
-2. **VG cut pass (new, compute)**: a §4 traversal, one per view. It descends the page DAG
-   and, inside a page, that page's node tree, from a queue seeded with the root cluster of
-   each visible instance; a node or cluster fine enough for τ terminates the descent, and so
-   does one whose child group is not selectable — which emits a want. It emits meshlet draw
-   records (existing record type) and wants/touches. VG carries geometry only — materials are
-   orthogonal and engine-side: a VG instance binds one geometry to one material through its
-   mesh exactly like any other geometry (a multi-material source splits into one geometry per
-   material upstream of the builder), so the mesh-keyed material buckets downstream stay
-   unchanged.
-
-   What it reads is the **page arena** — one fixed-stride slot per resident page, holding that
-   page's header, node rows, group rows and cluster rows — and the per-geometry lookup that
-   resolves a child page index to a slot (RUNTIME_PLAN §3.1). There is no selection buffer and
-   no page table: a page's header is the first words of its own slot, and the two (sphere,
-   error) pairs are in its cluster rows.
-
-   Superseded: this step previously specified a **flat** evaluation of the rule over every
-   row of that buffer, at a cost of `O(Σ over visible instances of resident(geometry))`. §4
-   replaced it, and the reason is worth keeping: that cost is the resident set rather than the
-   cut, and it is the resident set that grows without bound at the scale this design targets.
-   The buffer survives the change; the sweep over it does not.
-3. Existing pipeline: HZB meshlet filtering (two-pass, per view — this is where frustum
-   and occlusion happen), material bucket sort, indirect draws, G-buffer, deferred
-   shading. The *record formats* flow unchanged; the *injection point* is new work — the
-   current mesh→meshlet expansion (`graph_expand_meshes_to_meshlets`, one helper shared by
-   four rasterization paths) reads one contiguous static meshlet range per geometry, so VG
-   instances enter through their own expansion step. M0 was where that seam was to be fixed
-   and it was not (§10); it is the first thing M1 has to do.
-
-The traversal's GPU shape is settled and built: one indirect dispatch per spill generation, the
-descent's depth inside the kernel, work redistributed across a subgroup's lanes by prefix sum. A
-step costs about 0.5 µs whatever the wave holds, so a light asset pays for the shape of its descent
-rather than for its geometry, while a container with real work in the frontier pays mostly for the
-work. How many dispatches a cut needs is a queue-drain quantity rather than depth divided by the
-step count: a wave keeps `subgroup_size` children and spills the rest to the next dispatch.
-CUT_PLAN_2026_09_14 proposes to stop re-walking from the root by keeping the cut between frames.
-
-Open: shadow views (v1 takes the one cut per view of §4, sharing setup rather than results, and a
-proxy where a view does not justify a cut); DRS τ semantics.
-
-Settled since: **flat evaluation versus a hierarchy is no longer a measurement to take.** §4
-pins the traversal, and the hierarchy it descends is already written into every built asset
-(plan §2.3). The prior-implementation data that made flat evaluation look adequate — selection
-cheap, triangle throughput and screen-size uniformity dominant — was taken at that
-implementation's scale, and is not evidence about millions of resident clusters.
-
-## 8. Builder pipeline (offline)
-
-Pinned:
-
-- Stages: load → short-edge pre-pass (`bt_mesh_kill_short_edges` on soups / edge collapse
-  on closed surfaces — required by the weld contract) → weld
-  (`bt_merge_vertices_by_distance`; float32 quantum floor constrains tolerance) →
-  `bt_mesh_validate` → level-0 clustering (+ CC split) → the §3 round loop → per-cluster
-  encode → page assignment (level-banded, DAG + spatial locality, acyclicity check) →
-  container emit. The encode is the miniball sphere, the AABB, and `SHADE_MESHLET_V1`
-  attributes at their shipped widths (format §8): there is no cone field because cone culling
-  is declined (§9), and positions are raw float32 because quantization is a `payload_encoding`
-  that does not exist yet.
-- **The weld tolerance is scale-relative**, a fraction of each geometry's bounding-box
-  diagonal (`bt_mesh_relative_merge_distance`), resolved once off the source's bounds
-  before any pass has removed anything. A conversion is many geometries at many sizes and
-  no single distance is right for all of them: a fixed `1e-4` leaves an 18-unit dragon
-  intact and tears 1,061 faces out of the same dragon at 1/100th scale. The ratio's own
-  interval is narrow — floored by the float32 quantum (`~1e-7` of the diagonal), capped
-  well under the finest feature a quantized source can carry (`6.1e-5` at `gltfpack`'s
-  14-bit default) — so `1e-5` is bracketed rather than tuned, and is not a knob callers
-  are expected to move.
-- **Portable core**: the builder core is environment-agnostic JS — typed arrays and
-  `BinaryTopology` only, no fs/network/process APIs inside it. I/O and parallelism enter
-  through injected seams, and two harnesses are first-class: **node** (CLI, file streams,
-  worker_threads) and **browser** (user-picked handles / OPFS, Web Workers — injected
-  worker spawn, per the existing WorkerSystem precedent). The bounded-memory invariant
-  below is what makes the browser harness viable: the RAM budget is a configuration
-  input, and a browser build simply runs with a tighter budget and smaller islands.
-- **Bounded memory**: the builder never requires the full source mesh in RAM. The level
-  loop needs the current level plus one group neighborhood. Level 0 of a billions-scale
-  mesh does not fit one `BinaryTopology`, so the source is pre-split into spatial
-  islands. **Island seams are locked while islands are separate, so interiors halve but
-  seams do not** — islands therefore merge **hierarchically, pairwise**, dissolving the
-  shared seam at each merge (never "all at once at the top"), and the split heuristic
-  carries an explicit seam-size budget. Seams must be gone well before the root.
-- Deterministic seeds; asset identity = output hash (§3).
-
-**One source container, many assets.** A scene file is not a geometry: glTF holds meshes of
-primitives, placed by nodes. The unit the builder takes is the *primitive* — the smallest thing the
-container calls a geometry, and already one material's worth — so a container yields one `.vgeo` per
-primitive, each in object space with the node transforms left to the instances that carry them. The
-per-material split §7 asks for therefore costs nothing on this path.
-
-Open: island split heuristic and seam-quality validation; parallelism (WorkerSystem) vs
-the reproducibility goal; browser-harness plumbing (OPFS vs user-picked file handles;
-per-allocation ArrayBuffer ceilings feeding island sizing); the per-material split's
-boundary handling (adjacent per-material geometries coarsen independently, like any two
-neighboring assets); instance deduplication beyond what content addressing gives for free
-(identical geometry hashes to one file; *near*-identical fasteners still do not, and
-canonicalizing them is a preprocessor's job).
-
-## 9. Non-goals (v1)
-
-- **Backface normal-cone culling — declined outright, not deferred.** The two-pass HZB already
-  rejects what a cone would, on evidence rather than on a bound; see plan §5 for the mechanism
-  and the reports behind it. `cone_reserved` was a zeroed reserved field until `format_version` 5
-  spent it on `subtree_aabb` (format §7). This is the one entry here that is not a "v1" qualifier.
-- Skinned / morphing / WPO meshes through the VG path (static geometry only).
-- **Non-opaque VG instances.** The cut runs beside the mesh→meshlet expansion of the *opaque*
-  rasterization paths, and the transparent and alpha-tested bucket path
-  (`prepare_meshlet_draw_commands_by_material`) has no seam: it 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. A VG instance with a non-opaque material therefore expands to
-  zero meshlets and draws nothing at all. `GPUSceneRows.attach_mesh` says so out loud when one is
-  attached, because this bullet is the authority for it and did not exist while the code was citing
-  it.
-- Compute/software rasterization — WebGPU lacks portable 64-bit atomics; the hardware
-  raster path through the existing pipeline is the only raster path. Deferred G-buffer
-  shading already bounds the overshading cost of small triangles.
-- Ray tracing over the VG cut (`blas_from_meshlets` exists for static meshes; VG×RT is
-  future work).
-- *Sharing* one cut between views. §4 pins a cut per view and a proxy mesh where a view does
-  not justify one (plan §3.2, §3.3); what v1 does not attempt is a single cut made to serve the
-  camera and a shadow cascade at once, which was this document's earlier position and is wrong.
-- Attribute-quadric placement and UV-seam constraint planes (the boundary-plane-penalty
-  mechanism §2 requires for open boundaries is the same one UV seams will use; v1
-  targets position/normal-fidelity content).
-- Multi-buffer VRAM sharding beyond the single-binding limit.
-- Editor tooling beyond a playground prototype.
-
-## 10. Milestones
-
-These have not been taken in order. The format and the RAM-tier pager were built before the
-GPU cut, because the container is what the builder had to produce anyway and a reader is what
-proves it; the consequence is that M0's one *engine*-facing criterion — the expansion seam —
-is the piece still missing, and M1 is where the work now starts.
-
-- **M0 — DAG proof** — *the DAG half is done; the engine half is not*: builder (in-memory, no
-  format) → flat CPU-side cut → existing meshlet pipeline draws it in a playground; the VG
-  expansion seam is fixed here.
-  Acceptance: crack-free under τ sweep and flythrough (incl. group-boundary polyline and
-  flip validation); drawn-triangle count tracks resolution, not source size; §3 build
-  validations green.
-  **Done**: the builder; a CPU cut (`runtime/cut/__fixtures__/vgeo_select_cut.js`) that is a traversal
-  rather than the flat pass planned here, and that runs against a partially resident container,
-  which was M2's job; τ-sweep watertightness as a spec (`build/vgeo_cut.spec.js` counts edges
-  used by one triangle instead of two, at a spread of thresholds, and wants zero); the
-  group-boundary polyline guarantee, enforced by the builder rather than merely validated.
-  **Done since**: the expansion seam. `runtime/graph_vgeo_expand_instances_to_meshlets` runs beside
-  `graph_expand_meshes_to_meshlets` at each of the three opaque call sites and appends into the same
-  collection, so a VG instance enters through a VG-shaped door and everything past the expansion is
-  untouched. `shade/playground/vgeo_runtime/` is that, on screen.
-  **Still not done**: flip validation (§2, extension 3).
-- **M1 — GPU cut** — **done**: selection buffer + compute cut pass; wants/touches readback wired.
-  `runtime/` holds all of it and [runtime/RUNTIME_PLAN.md](./runtime/RUNTIME_PLAN.md) is its design.
-  Acceptance was parity with M0 and selection cost measured, and both were taken:
-
-  *Parity* is `runtime/cut/vgeo_cut_agreement.spec.js` — the kernels run under the WGSL emulator
-  against a real container and their drawn cluster **multiset** is held to exactly what
-  `vgeo_select_cut` selects, over seven cameras and four thresholds, fully resident and with pages
-  withheld, one instance and two. Multiset rather than set because a duplicate is the failure that
-  reads as corrupt geometry rather than as a missing page.
-
-  *Measured*, on an nvidia/lovelace adapter, a 13-page torus opened holding only its root page and
-  streamed entirely by the cut's own wants: 50 drawn clusters at τ=0.5 down to 8 at τ=16, monotone,
-  visiting 9 pages down to 5, clamping to zero as pages arrive, dropping nothing. Half the frames
-  skip feedback entirely under a two-deep readback cap, which is the virtual-texture contract and
-  costs streaming latency rather than pixels.
-
-  The flat-vs-hierarchy decision data is *not* what M1 produced, and §7 already says why: §4 pinned
-  the traversal and the question stopped being a measurement to take. What the cut measures instead
-  is that the hierarchy's own accelerator is sound — the node metric's `max_parent_error` cull fires
-  across the whole agreement sweep and changes not one selected cluster.
-- **M2 — format + streaming** — *the RAM tier landed early*: `.vgeo` container, pager,
-  residency tiers with the §6 invariants (page-slot pool, address-migration propagation,
-  occlusion-aware wants, touch-LRU, in-flight pinning), budgets, eviction. Position
-  quantization lands here (encode + struct + decode shaders). Acceptance: cold-load TTFP =
-  header + root page regardless of asset size; streaming never produces holes; page
-  size/codec chosen on measurement.
-  **Done ahead of M1**: the container and its validator; the RAM-tier pager with residency,
-  activation and eviction (`format/read/`); TTFP, which is header + level table + root page and
-  measured to hold on a 27M-triangle asset; the page codec, chosen on measurement (§5).
-  **Done with M1**: the VRAM page pool (`runtime/GPUVirtualGeometryPool`) with a byte budget and
-  touch-LRU under a protect window, and the want record now naming the page it was discovered
-  *through* — which is what in-flight pinning was blocked on, since the format stores parent counts
-  rather than parent references and nothing below the cut could name that page.
-  **Still M2's**: address-migration propagation, occlusion-aware wants, the in-flight pin itself,
-  and position quantization.
-- **M3 — hardening**: prefetch, disk page store decision, budget defaults, low-limit
-  adapters (τ fallback), stress on CAD-class input; browser builder-harness proof
-  (build a mid-size asset in-tab).
-
-## 11. References
-
-- Karis, *Nanite — A Deep Dive*, SIGGRAPH 2021 (Advances in Real-Time Rendering).
-- Michaelides & Vaisse, *Maximizing Graphics Performance with Flexible Virtualized
-  Geometry*, GDC 2024 (Virtuos "Hi-Res Vision").
-- Refinement-metric musings: https://share.gemini.google/AfYiNvAB2kt0
-- `../meshlet/README.md` — RE Engine meshlet compression notes, nv_cluster_builder.