@woosh/meep-engine 3.60.3 → 3.60.5

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

@@ -1,483 +0,0 @@
-# Virtual Geometry — plan
-
-Scheduled and deferred work. [VIRTUAL_GEOMETRY_DESIGN.md](./VIRTUAL_GEOMETRY_DESIGN.md) pins
-what has been *decided*; [VGEO_FORMAT.md](./VGEO_FORMAT.md) specifies what is *written*.
-This file holds what is *next*, and — more usefully — the reasoning and the source for
-ideas that are accepted but not yet scheduled, so that picking one up does not mean
-rediscovering it.
-
-The GPU runtime is **built** — `runtime/`, and
-[runtime/RUNTIME_PLAN.md](./runtime/RUNTIME_PLAN.md) is its design and its adversarial review. The
-cut runs on the device, the VRAM tier holds pages under a budget, wants and touches come back
-through a readback, and a VG instance enters the meshlet pipeline through a door of its own. §3's
-items are no longer blocked on "a runtime"; each names what it is actually waiting for now.
-
-Items carry their provenance. `[M §x]` is a section of
-[MICRON_COMPARISON_2026_08_20.md](./MICRON_COMPARISON_2026_08_20.md), the review of the
-prior WebGL implementation at
-`H:\git\moicon\prime\src\components\Viewer\Viewer.Meep\Micron\`. `[V §x]` is a section of
-[VK_LOD_CLUSTERS_COMPARISON_2026_08_20.md](./VK_LOD_CLUSTERS_COMPARISON_2026_08_20.md), the
-review of [nvpro-samples/vk_lod_clusters](https://github.com/nvpro-samples/vk_lod_clusters).
-
-## 1. Landed
-
-For the record, so that a later reader can tell an accepted-and-done item from an
-accepted-and-waiting one.
-
-- **Accumulated quadrics carried from the source to the root** `[M §2.1]`, `[V §3.1]`.
-  Vertex quadrics are built once from the source triangles and threaded through every
-  round; error is the accumulated quadric evaluated at the vertex's final position,
-  normalized by its weight, which makes it an object-space distance from the *source*
-  rather than a sum of per-round residuals. `bt_mesh_simplify_with_quadrics` in
-  `core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.js`; `Quadric3.distance`.
-- **Cluster-count simplification target** `[M §2.2]`, and a minimum cluster fill through the
-  generalized leaf repack `[V §3.3]`.
-- **Compactness-weighted cluster adjacency** `[M §2.3]` — `compactness()` in
-  `build/level/vgeo_build_levels.js`.
-- **Speculative groups, rejected individually** `[M §2.4]`.
-- **Per-level summary table in the file head** `[V §4.1, §6.1]` — VGEO_FORMAT §4.1.
-- **A traversal metric on the page DAG, and a group tree inside each page** `[V §2.1, §6.3]` —
-  VGEO_FORMAT §6.1–6.2. See §2.2 below for why, which is worth keeping: the reasoning corrects
-  an error this file previously made.
-- **Boundary constraint quadrics** — see §4.1, which was the blocking item.
-- **A partitioning fallback** `[M §3.3]`, `[V §3.2]` — see §2.1.
-- **An incremental reader, and residency with it** — `format/read/`. A container opens in its
-  header, level table and root frame; after that a page arrives only because something asked for
-  it, from exactly the byte range the page pointing at it wrote down. `VGeoContainerReader`
-  holds residency, activation and eviction; `VGeoByteSource` is the seam — an `ArrayBuffer`, a
-  dropped `Blob`, or HTTP ranges that refuse a `200` where they asked for a range. The
-  whole-file audit is a tool in `format/read/tool/` and nothing on the runtime path can reach it;
-  format §4/§5's reject rules always run.
-  VGEO_FORMAT §10 marks, requirement by requirement, what this covers and what it leaves to a
-  budget owner.
-- **The reader hardened for 1000 assets, and the budget owner it was waiting for** —
-  `virtual/residency/`. Measured first, and three of the audit's suspicions did not survive the
-  measurement, which is the more useful half of the result: the per-page allocation the reader adds
-  on top of a decoded page is 6.4–11.9 KB, which is 1.2% of a 544 KB page and not worth a rewrite;
-  the reverse-reference index tracks the residency frontier rather than the session's history, so it
-  does not leak; and the pinned root page is one cluster by invariant §11.7, measured at 1,472 and
-  1,732 B, so a thousand of them is under 2 MB and no builder-side cap is wanted. What *was* real:
-  a 256 KiB head prefix retained for the reader's life outside every budget (released now, and the
-  default cut to 64 KiB), no retry/backoff/quarantine so one bad page threw (now §10's full
-  sequence, with telemetry), no cancellation at all (now a per-read `AbortSignal` end to end), and a
-  whole-file audit and install-every-page sweep reachable from a reader a renderer holds (now tools,
-  with a 1 GiB bound and a message instead of an allocator failure). Above the reader,
-  `VGeoResidencyManager` owns the byte budget, the touch stamps, the eviction order and — through
-  one `core/process/ConcurrencyGate` — one fetch cap across every reader, because a per-reader cap
-  does not compose, measured at sixteen concurrent requests from four readers capped at four.
-- **Activation, and the double-draw it prevents** — format §10's selectable invariant, as one
-  live-reference counter per resident group with cascades on install and evict. The clamp reads
-  *selectable*, not *resident*: a group whose parents are split across pages must not be refined
-  into through the parents that happen to have arrived. Measured on a 19-page bunny, 21 of whose
-  362 non-root groups have split parents: 355 of 576 camera positions double-drew, up to 10.7%
-  of drawn triangles, before. Zero after. It reads as corrupt geometry rather than as a missing
-  page, which is why the tool that found it could not name it.
-- **A CPU cut against a partially resident container** —
-  `runtime/cut/__fixtures__/vgeo_select_cut.js`. It is the runtime's rule rather than a debug
-  approximation of it, and `vgeo_select_cut.spec.js` holds it to the format's guarantees. A
-  `vgeo_viewer` playground used to draw it on screen through Shade's direct geometry path, which is
-  what made clamping, streaming and eviction watchable; once `playground/vgeo_runtime/` could show
-  all of that through the meshlet pipeline, the page was a second renderer and a second streaming
-  loop for no gain, and it was retired. The traversal stayed, because it is the oracle.
-
-- **The GPU runtime** — `runtime/`, and [runtime/RUNTIME_PLAN.md](./runtime/RUNTIME_PLAN.md) for the
-  design and the adversarial review that reshaped it. The cut is a wavefront BFS over the page DAG
-  with a per-cluster predicate at the leaves, and that combination is the whole design: the
-  hierarchy decides which clusters to *look at*, the predicate decides whether to *draw* them, and
-  because the predicate is a pure function of one row, a page visited twice costs a duplicate record
-  rather than a wrong answer — so dedup is one bit per (instance, resident page) and never per
-  cluster, which is the number design §4 is trying not to pay.
-
-  Three things the review found, in descending order of how much they cost to rediscover:
-
-  - **Design §4's per-cluster rule double-draws as written.** A group that is resident but not
-    selectable has clusters satisfying it while their coarse stand-in is drawn over the same
-    surface. The rule needs an *own group selectable* term that a traversal gets for free and an
-    evaluator does not. §6 states the fact without stating it as a term of the rule, because §4 was
-    written for a traversal.
-  - **Page size decides whether that state is even reachable.** At the 8 KB pages
-    `vgeo_select_cut.spec.js` uses, a torus puts exactly one group in every page — so a blocked group is
-    a blocked page, no page is ever mixed, and no page is ever entered twice. Measured: 40 pages
-    withheld one at a time and 60 random residency subsets produced *no* mixed page. At 64 KB the
-    median page holds eight groups and it is ordinary. A spec for anything about mixed selectability
-    has to be written at a page size that produces it.
-  - **Every bound degrades in one direction.** A full meshlet collection drops records; a claim
-    allocation that does not fit drops the *instance*, because an instance run unclaimed draws its
-    whole cut once per parent page that reaches it.
-
-  Held against mutation: removing the own-group term, the claim, the child selectability check or
-  the parent projection each turns the agreement suite red. Proved on a device in
-  `playground/vgeo_runtime/` — a 13-page container opened holding only its root page, streamed to 9
-  by its own wants, 50 drawn clusters at τ=0.5 falling monotonically to 8 at τ=16, clamping to zero,
-  dropping nothing.
-
-## 2. Next
-
-§2.1 and §2.2 both landed. They are kept because their notes are the reasoning behind decisions
-that are now only visible in code, and rediscovering them is the expensive part. §2.3 **half**
-closed, and the half that did not is the more interesting one — read it before building a
-prefetch.
-
-### 2.1 A partitioning fallback for when METIS fails `[M §3.3]`, `[V §3.2]` — LANDED
-
-`core/graph/graph_partition_spectral.js` — recursive spectral bisection over CSR, matrix-free,
-signature-compatible with `metis_partition_kway`. `build/partition/vgeo_partition_graph.js` tries METIS
-and falls back to it; both of the builder's partitioning sites go through that wrapper.
-
-Notes worth keeping:
-
-- **Matrix-free, deliberately.** The Fiedler vector comes from power iteration on `d·I − L`
-  with the constant projected out each step; `L` is applied, never built. A dense
-  formulation — which is what made Micron's third partitioner unattractive to port — is
-  O(n²) in memory and unusable at the sizes that make a fallback necessary.
-- **It is a floor, not a competitor, and the code says so.** The shift needed to make the
-  operator positive leaves the eigenvalues of interest within a fraction of a per cent of
-  each other, so a graph with no real bottleneck converges only approximately. Measured: a
-  20×20 grid cuts at 23 edges against an optimum of 20. Iterations are 256, chosen where the
-  curve flattens — the same grid's four-way cut is 82 edges at 64 iterations, 47 at 256, 48
-  at 1024. Balance is exact at every setting; only the cut moves.
-- **METIS is much harder to make fail than expected**, and this is insurance rather than a fix
-  for an observed problem. Probing it with NaN and negative edge weights, adjacency indices
-  past the end of the graph, more parts than vertices, zero parts, and edgeless graphs
-  returned a partition every time. The only inputs that stop it malform the CSR itself, which
-  is a caller bug. Worth knowing before anyone spends effort here again.
-
-Still open, and related: meshopt's builder treats a group as **stuck** when simplification
-leaves more than `merged.size() * simplify_threshold` faces, and escalates to permissive, then
-sloppy modes, inflating the recorded error to pay for it. We have no middle rung between
-"simplified" and "refused". This is now safe to build — it was not before, because a sloppy
-mode that erodes boundaries needed §4.1 first, and §4.1 has landed.
-
-### 2.2 A traversal metric on the page DAG, then nodes within a page `[V §2.1, §6.3]` — LANDED
-
-**Correcting an earlier framing in this file.** A previous revision called paging "the open
-question" for a node hierarchy, on the grounds that nvpro never had to answer it — their node
-array is per-geometry and resident, and at 1 G triangles ours would be tens of megabytes.
-Both halves of that were wrong, and the second one was wrong in a way that hid the actual
-work.
-
-**The pages already form a rooted DAG, and it is already validated.** Every one of the
-properties a traversal wants from a hierarchy is a rule the format states and
-`vgeo_validate_container` enforces:
-
-- rooted at page 0, and *every page is reachable from it through child tables* (§11.3);
-- acyclic — a child table's `frame_offset` is strictly greater than the referencing page's,
-  so file order is a topological order (§11.3);
-- levelled — a cluster's child group is always in a page whose band tops out strictly below
-  its own page's (§11.4);
-- and a group never spans a page, so an edge is a whole LOD decision, not part of one.
-
-It is a DAG rather than a tree, and measurably so. On a 98k-triangle sphere at 32 KB pages:
-**91 pages, 291 edges, in-degree up to 7, 82 of the 91 pages have more than one parent, none
-unreachable, longest path from the root 12.** At 8 KB pages a 24k sphere gives 102 pages and
-182 edges with 68 multi-parent pages. It degenerates to a chain only when every band fits in
-one page, which is to say only on assets too small for any of this to matter.
-
-That the page DAG is a *useful* coarsening rather than an arbitrary one rests on something
-already in the builder: groups are laid into pages in Morton order of their centroid within a
-band (`vgeo_assemble_pages`). A page is therefore spatially local, and a bounding volume over
-one means something. Pack pages arbitrarily and every page bound covers the model.
-
-**Nanite does exactly this combination**, which settles the compatibility question outright.
-Cluster data lives in a paged, streamed virtual byte buffer
-(`Nanite.StreamingManager.ClusterPageData`) with the BVH in
-`Nanite.StreamingManager.Hierarchy`; nodes form a BVH within a mesh connecting clusters
-across detail levels; `PersistentNodeAndClusterCull` in `NaniteHierarchyTraversal.ush` walks
-it on the GPU from an MPMC queue, where only nodes generate new work and clusters are only
-consumed. And when a child's memory is not present, **processing stops at the parent and a
-request is made for the child** — a lower-detail LOD is what you see until it arrives. That
-is the same mechanism as nvpro's invalid-address-is-the-request-slot (§2.3 of the
-vk_lod_clusters review), and it is the answer to "what does a traversal do about paging":
-nothing special. It stops.
-
-#### What is actually missing
-
-Not a hierarchy. A **metric on the one we have**. A child-table entry today carries
-`frame_offset`, `page_index`, `fetch_size`, `decoded_size` and four reserved bytes — enough
-to fetch a page, and nothing at all with which to decide whether to. So the DAG is
-traversable but not *cullable*: the only way to learn that a page was not wanted is to fetch
-it and decode it, which is precisely backwards. The decision worth making cheaply is the one
-before the fetch.
-
-The work is two steps, and both are natively paged because they live inside structures that
-already are:
-
-**Step 1 — a traversal metric per child-table entry.** The child page's LOD-metric sphere and
-its error range, 24 bytes, taking the entry from 24 to 48. It buys, in one change: frustum and
-LOD culling of a whole page and everything reachable only through it; a want-list that is
-exactly the pages that passed the test and are not resident; and prefetch depth as a policy
-dial instead of a guess. The page header carries the same metric for its own content, so an
-installed page can be re-tested without walking back to its parent.
-
-**Step 2 — a node tree within a page, over that page's own groups.** Finer culling and more
-width at the top. This one has *no* paging question by construction: it is inside a page, it
-ships and evicts with it, and it cannot dangle.
-
-Both landed together; VGEO_FORMAT §6.1–6.2 specifies them, `build/page/vgeo_build_page_nodes.js`
-builds them. Notes worth keeping:
-
-- The tree needs no partitioner. A page's groups arrive in Morton order of their centroid, so
-  a balanced split of that order is already a spatial split.
-- A node's metric comes from the groups under it and needs no new geometry: every cluster of a
-  group shares the sphere and error of the step that consumed it — the same fact that makes
-  the group the atomic LOD decision — and monotonicity makes that one sphere cover everything
-  in it.
-- Fanout 4, breadth-first, children contiguous, parents at lower indices than children.
-  Measured across spheres from 3k to 98k triangles at 8 KB–256 KB pages: **0.3%–1.6% of asset
-  size, trees one to three deep**.
-- The validator earns its keep here. A node whose sphere does not cover its subtree drops
-  geometry that nothing downstream would notice, and a child-table metric is a *copy* that can
-  drift from the page it describes without that page being wrong. Both are checked, and both
-  checks have corruption tests behind them (VGEO_FORMAT §11.10–11.11).
-
-#### On width at the root
-
-The concern that a descent from one root cluster starves a GPU dispatch was overstated.
-Nanite's queue is seeded with *the root cluster for each instance*, so width comes from the
-instance count first and from fan-out immediately after — measured out-degree reaches 10 by
-the middle bands of the 98k sphere. It bites only for a single instance in close-up, and only
-for the first few bands, which are also the cheapest to walk.
-
-### 2.3 The node tree has a reader; the child-table metric still does not — LANDED (half)
-
-§2.2 built both, and the format specifies both: every child-table entry carries the child page's
-LOD-metric sphere and error range (VGEO_FORMAT §5, §6.2), and every page carries a fanout-4 tree
-over its own groups (§6.1). The writer emits them, `vgeo_validate_container` checks them
-(§11.10–11.11) with corruption tests behind both checks, and **nothing reads either**.
-`VGeoPage` records `node_count` and stops; `vgeo_select_cut` descends group by group.
-
-This is not a defect to fix on its own account. Building a consumer for its own sake would fix
-the interface before the pass that has to live with it, and the CPU traversal does not need the
-acceleration — it walks a resident page set on a machine with branches. It is written down here
-for two reasons: because "the validator checks it" reads exactly like "something uses it", and
-because the cost is already paid — 0.3%–1.6% of asset size, on disk, in every asset already
-built, earning nothing.
-
-What it buys when the pass arrives, and what to hold it to:
-
-- **Before the fetch.** A page can be frustum- and LOD-culled from its parent's child-table
-  entry, so a want list is exactly the pages that passed the test and are not resident, rather
-  than everything a descent happened to reach. Today the only way to learn a page was not wanted
-  is to fetch and decode it, which is backwards.
-- **Below the page.** A node discards a region rather than a cluster, and gives the top of the
-  descent width it does not otherwise have.
-
-Neither is measurable until there is a GPU traversal to measure, which is the honest reason it
-has waited.
-
-**What happened when the traversal arrived**, and it is not what this section predicted.
-
-*Below the page*, the node tree has its reader. `runtime/cut/shader_vgeo_cut_traverse` descends it,
-tests each node's sphere and `max_parent_error`, and discards a region rather than a cluster. The
-cull fires across the whole agreement sweep and changes not one selected cluster, which is what
-sound means for an accelerator. The 0.3%–1.6% of asset size is earning something now.
-
-*Before the fetch*, the child-table metric **still has no reader, and now for a reason rather than
-for want of a consumer.** Held against the cut, it buys nothing. A want is emitted from a cluster
-that has already passed `project(parent) > τ` and `project(self) > τ`; the child page's metric
-covers that cluster's child group among others, so its `max_parent_error` is at least that group's
-`parent_error` and its sphere contains that group's `parent_sphere` — and the projection is monotone
-in both. The page-level test is therefore **always** above τ at exactly the moment the question is
-asked. It cannot reject what a per-cluster test has just accepted, because the per-cluster test is
-strictly tighter. The frustum half dies the same way: the cluster's own `self_sphere` is a tighter
-test than the child page's union sphere, available locally, for free.
-
-Where the copy *is* load-bearing is **prefetch** — ranking and bounding pages nobody has asked for
-yet, which by definition has no cluster-level evidence to be tighter than. `min_self_error` is in
-the same position: it ranks a want and the cut never asks it anything. So the field is not dead, it
-is early, and the thing it is early for is §3's territory rather than the cut's. Anyone building a
-prefetch should start here.
-
-## 3. Was waiting on a GPU runtime
-
-Accepted, documented here so the reasoning is not lost. "Waiting on a runtime" used to mean waiting
-on all of it; the runtime exists now (`runtime/`), so §3.1 has landed with it and the rest name what
-they are actually waiting for.
-
-### 3.1 Object-space refinement `[M §2.7]` — LANDED
-
-`RefinementSpec.build` in `Micron/render/refinement/RefinementSpec.js`: multiply the camera's
-view-projection by the instance transform once, derive the frustum planes from the result,
-and run every cull and error test in **object space** against untransformed cluster bounds.
-One matrix multiply per instance instead of transforming every cluster's bounds to world
-space. With thousands of instances sharing one geometry that difference is the entire cost.
-
-**Landed** with the cut. `runtime/cut/shader_vgeo_cut_collect` is the one place a VG transform is
-touched: it multiplies the camera's view-projection by the instance transform, extracts the frustum
-from the result, inverts the transform once for the eye, and writes both into the instance record.
-Every cull and error test downstream runs against untransformed cluster bounds.
-
-One thing fell out that `RefinementSpec.build` never had to face, because object space is not free
-when an instance is scaled: error and distance are **both** object-space, so a *uniform* scale
-cancels out of `r_e · k / d` exactly and needs no term at all. A non-uniform one does not, and the
-correction is the ratio of the largest axis scale to the smallest — conservative, so it over-refines
-rather than under-refines, and exactly 1 for every instance that is not stretched. Worth knowing
-before anyone adds a scale term that does nothing in the common case.
-
-### 3.2 Proxy geometry from a DAG cut `[M §2.6]`
-
-`Micron/format/micron_build_proxy_geometry.js`: refine from the root with a heap keyed on
-`-patch.lod` until a target polygon fraction is reached, and emit the result as an ordinary
-mesh. Shadows, physics, raycasts, editor previews and impostors all want a cheap whole-object
-mesh, and a cluster DAG hands one over for the cost of a heap walk.
-
-Two consumers make this more than a convenience:
-
-- A **shadow or secondary view** that does not justify its own cut can take a proxy instead
-  (§3.3).
-- Anything outside the renderer — physics, navigation — that wants geometry without
-  understanding clusters.
-
-### 3.3 One cut per view, and proxies where a cut is not worth it
-
-**Correcting the design.** VIRTUAL_GEOMETRY_DESIGN §4 claimed the cut is "view-agnostic in
-*coverage*" and that keeping it so is "what lets shadow views reuse it". That is wrong, and
-the design has been corrected: virtual geometry is view-*dependent* by construction. A cut
-selected for the main camera is selected at the main camera's distances and pixel budget, and
-is simply the wrong cut for a shadow view — a light a hundred metres behind the camera wants
-different clusters, and a cascade wants a different set again. Epic acknowledge computing
-several cuts per frame for exactly this reason.
-
-So the plan is **a cut per view**, with the setup shared rather than the result: the traversal
-kernel, the residency state, and the page working set are all view-independent, and only the
-projection and threshold differ. That half is built — a cut runs per expansion site per view, and
-what it costs is measured in CUT_PLAN_2026_09_14 §0, which also plans to keep each view's cut
-between frames rather than re-walking it from the root. And where a view does not justify a cut
-at all — a distant cascade, a low-resolution reflection — it should be able to take a proxy
-(§3.2) instead. That choice belongs to the view, not to the geometry.
-
-### 3.4 GPU-driven allocation `[V §4.3]`
-
-**Narrower now, and the runtime says exactly how much.** A VG page is one arena allocation holding
-its node, group and cluster rows back to back, and an eviction frees one allocation and writes one
-lookup word. Nothing inside a resident page can move, growth appends through `OffsetAllocator#grow`
-and relocates nothing, and no address migrates. What VG's churn *does* still reach is
-`GPUMeshletManager`: a page install is an `add_batch` and an eviction a `remove_batch`, so the holes
-accumulate in that pool and closing them is still a CPU-side rebuild with the unhandled
-address-migration TODO downstream of it. Pages are near-uniform in size, so a hole is usually
-re-usable by the next install — which narrows the problem without closing it, and is the reason this
-is still an item rather than an incident.
-
-Worth pursuing **beyond virtual geometry** — this is a GPU-driven engine and CPU-side
-allocation for GPU-resident data is a standing mismatch.
-
-`vk_lod_clusters/docs/clas_allocation.md` reports host-side size estimates running "often 3-5x
-bigger than actual" and moves allocation on-device, reading back true sizes. Two designs are
-given: naive dense compaction (discouraged — "high memory movement bursts") and a
-**device-resident allocator that relocates an allocation once, after construction**, with a
-free-gap list maintained on the GPU —
-`shaders/stream_allocator_build_freegaps.comp.glsl`,
-`shaders/stream_allocator_freegaps_insert.comp.glsl`,
-`shaders/stream_allocator_load_groups.comp.glsl`,
-`shaders/stream_allocator_unload_groups.comp.glsl`.
-
-The mirror-image problem on our side is recorded in design §2: `GPUMeshletManager`'s
-*compaction* is a CPU-side rebuild costing ~2× VRAM transiently, and meshlet-address migration
-is an acknowledged unhandled TODO in `GPUGeometryManager`. Growth has stopped being a rebuild
-since this was written — it appends through `OffsetAllocator#grow` and moves no record — which
-narrows the problem to exactly the case VG churn produces: closing holes, not adding room.
-
-## 4. Was blocking
-
-### 4.1 Boundary constraint quadrics — LANDED
-
-Was the single most important open item, and had been listed as a required simplifier
-extension in design §2 from the start. It became load-bearing rather than latent once the
-round loop began converging through boundary erosion: an asset built over open geometry
-recorded error that was not merely optimistic but wrong. Measured before the fix: 400 loose
-triangles built a root of 25 triangles carrying `self_error = 0`, and `project((s, 0)) ≡ 0`
-means such a root is selected at any distance and never refined. Nothing downstream could
-catch it — the validator checks monotonicity, and zero is monotonic.
-
-`bt_mesh_compute_vertex_quadrics` now adds, for every edge whose face count is not two, the
-plane through it perpendicular to its face, weighted. A face-plane quadric says only how far a
-vertex has moved *off* the surface and by construction says nothing about it sliding *along*
-one; for an interior vertex that is right, and for a vertex on a border it is exactly wrong.
-Non-manifold edges are treated the same way and for the same reason — a seam is no freer to
-move than a border.
-
-Two things fell out that are worth knowing:
-
-- **Weight 3, measured.** The error a vertex reports is the mean over its planes, so a border
-  vertex with a handful of faces and two constraint planes has the retreat diluted threefold
-  at weight one. Three brings it back to roughly the displacement itself while leaving the
-  border free enough to erode at all — which it must, or a mesh of open shells has no coarse
-  form and no root.
-- **The measurement had a second hole, and it was the larger one.** Taking the error as the
-  max over *surviving* vertices misses geometry that vanished outright: a patch consumed
-  whole leaves a vertex belonging to no face, which is swept away by cleanup, and that vertex
-  is the only thing still holding the quadric of what used to be there. A triangle soup
-  simplifies by *deleting* triangles, so this reported the loss of most of a model as free
-  even with boundary quadrics in place. `bt_mesh_simplify` now measures before the cleanup
-  and returns the object-space distance the surface moved — which is also a better return
-  value than the raw squared residual it used to give, and nothing outside its own specs was
-  reading that.
-
-Result: the 400-triangle soup now reports 0.22 at its first merge rising to 0.39 at the root,
-on triangles about a unit across. A **flat** sheet still reports exactly zero at every level,
-which is the other half of the contract — a flat surface is exactly representable at any
-triangle count, and a vertex partway along a straight border slides off without changing the
-outline. Its corners are not free, which is what stops it collapsing to nothing.
-
-### 4.2 Payload size
-
-Deferred deliberately; it is a separate campaign. Two threads, in the order they should be
-attacked:
-
-- **Mantissa-bit dropping** `[V §3.5, §6.6]`. The nvpro README recommends dropping low
-  mantissa bits of positions and UVs ahead of its lossless group compression. It keeps the
-  float32 layout, the metadata struct and every decode shader exactly as they are, and simply
-  makes the bytes compress. A fraction of the work of quantization for a real share of the
-  benefit, and it composes with the page codec, which has since shipped: LZ4 finds only
-  1.12x–1.18x on today's payloads *because* float32 positions give an LZ matcher nothing, and
-  dropping mantissa bits is how you give it something.
-- **Cluster-local position quantization**, as design §2 describes — invasive, spanning
-  encode, the metadata struct and every decode shader.
-
-## 5. Considered and declined
-
-- **Backface normal-cone culling** `[M §2.3]` — the `cone_reserved` field, a producer for it,
-  and the cull pass that would read it. **Declined: the HZB already rejects what a cone would,
-  and it does it on evidence rather than on a bound.** On a closed surface backfacing *is*
-  occluded, and §7's two-pass HZB sees that; what a cone adds over it is pre-emption by one
-  pass, bought with per-cluster data and a per-cluster test in the cull pass, every frame and
-  per view. It pays best where cones are tight — flat clusters, which are also the cheapest
-  to raster — and degrades exactly where a cut spends its clusters, because a group's cone
-  widens toward hemispherical as the levels coarsen. Micron paid for tight cones by scoring
-  merges on cone angle (`[M §2.3]`), which is the real price: grouping stops being a purely
-  spatial criterion in order to feed a cull that the HZB was already doing.
-
-  This is not our finding alone, which is why it is a decline rather than an experiment: Epic
-  did not ship it in Nanite, meshoptimizer's author argues against the payoff despite the
-  library exposing cone data, and Remedy report the same for Northlight. Taken together with
-  the mechanism above, there is nothing left to measure.
-
-  Consequences, so that nobody re-derives them: `cone_reserved` was a zeroed reserved u32 until
-  `format_version` 5 (format §7) — reclaiming 4 bytes of 112 was never worth a version move on its
-  own, and it went when `subtree_aabb` needed 24 and the version moved anyway. `bt_face_cluster_compute_normal_bounding_cone`
-  has no consumer and no prospect of one.
-- **Fixed-size residency slots** `[M §2.5]`. Micron gives every resident patch one slot of
-  `MICRON_PATCH_SIZE_MAX × 3` vertices with occupancy in a BitSet: no allocator, no
-  fragmentation, no address migration, at the cost of internal fragmentation proportional to
-  `1 − fill`. **Declined: pages already are the compaction mechanism.** A page is fixed-size
-  and carries whole groups; the lever to pull is page waste, by keeping clusters full — which
-  §1's cluster-count target and repack are for — not by giving up variable-size allocation.
-
-  *(2026-09-12: "by construction" was the original wording and it was not true — the builder
-  overran `nominal_page_size` whenever a group did not fit, and the format told readers not to
-  assume the number at all. It is true now, by enforcement rather than by construction:
-  FORMAT §11.14, the builder refusing a page size no group fits, and the validator behind it.
-  The conclusion this bullet reaches is unchanged; the premise had to be made real first.)*
-- **Shape-aware greedy leaf clustering** `[M §2.8]`. Micron grows leaf patches with a heap
-  scored on perimeter change, added-neighbour count, and "open face freedom" — how many of a
-  candidate face's neighbours are about to be stranded
-  (`Micron/build/clustering/computeOpenFaceFreedom.js`). **Declined: we lean on METIS
-  heavily**, and replacing it with a bespoke region grower is a large step away from a
-  partitioner that is tested and shared with the navmesh and graph code. We get the
-  anti-stranding effect structurally instead, in `absorb_singleton_pieces` — after the
-  partition rather than before it, which is weaker but far cheaper to own.
-- **Spectral partitioning as a primary partitioner** `[M §3.3]`. Dense Laplacian
-  eigen-decomposition is O(n²) in memory. Kept only as the failure fallback in §2.1.
-- **Crack repair instead of crack prevention** `[M §3.2]`. `patch_fill_holes_by_uncollapse`
-  and `patch_stitch_parent_border` are dead code in Micron — a road already walked. Locked
-  perimeters won.