@woosh/meep-engine 3.27.0 → 3.29.0

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

@@ -0,0 +1,540 @@
+# Attribute-aware simplification — plan, 2026-09-18
+
+`VIRTUAL_GEOMETRY_DESIGN.md` §9 lists "attribute-quadric placement and UV-seam constraint planes"
+as out of scope for v1, on the grounds that v1 targets "position/normal-fidelity content". This plan
+is the measurement showing that the *normal* half of that claim does not hold — the builder's shading
+frame is wrong on a third to a half of every level above the leaves — and the design that fixes it.
+
+Nothing here changes the container format, the runtime, or the cut rule. §8 says why, and holds the
+work to it.
+
+## 1. What is wrong, measured
+
+Instrumented builds of `zorah_main_public.v2.gltf` `mesh1[0]` — 128,318 triangles, 13 levels.
+Instrumentation was temporary and is not in the tree; the probes that produced these numbers are
+reproduced by `vgeo_attribute_fidelity.bench.spec.js` (§9).
+
+### 1.1 The builder ships two different normal fields in one mesh
+
+`vgeo_build_group_step` ends a group step with
+
+```js
+vgeo_compute_vertex_normals(submesh.mesh, locked);
+vgeo_compute_vertex_tangents(submesh.mesh, locked);
+```
+
+and those two calls run **two incompatible rules over one mesh**:
+
+- an **interior** vertex is given the area-weighted normal of the mesh as the simplifier just left
+  it — a property of the coarse tessellation;
+- a **`locked`** vertex — the group's perimeter, which the step was forbidden to move — keeps what
+  it inherited, which tracks the surface the asset was authored from.
+
+They meet along every triangle that straddles a group perimeter, and the perimeter is not a rare
+place:
+
+| | L1 | L3 | L5 | L7 | L8 |
+|---|---|---|---|---|---|
+| pinned share of live vertices | 31% | 38% | 49% | 50% | 37% |
+| pinned normal vs. **the surface it ships on**, p90 / max | 9.5° / 68° | 11.2° / 52° | 17.2° / 154° | 27.6° / 80° | 21.8° / 88° |
+| pinned normal vs. **the source field**, mean | 0.00° | 0.95° | 4.1° | 8.7° | 8.0° |
+| interior normal vs. **the source field**, mean | 5.7° | 9.8° | 15.5° | 21.9° | 26.7° |
+
+Read the last two rows together. The pinned value is the *correct* one; it is the interior recompute
+that has walked away from what was authored. A second primitive reaches 175° at L1 — a normal
+pointing into the surface it shades.
+
+The visible result is a dark wedge fanning out from a single vertex, and it needs no LOD transition
+to appear: it is wrong in one level, standing still.
+
+### 1.2 Recomputing from coarse geometry guarantees a pop
+
+The same vertex's shipped normal, between the level that holds it and the level that replaces it:
+mean 5.3° at L1 rising to 13–23° at L8–L11, p90 13.6° rising to 40–58°. That is not approximation
+error. The area-weighted normal of the coarse mesh is a *different surface's* normal, and the whole
+reason shading normals exist is that they do not have to follow the tessellation.
+
+### 1.3 The representation cannot hold an attribute discontinuity
+
+`BinaryTopology` carries one attribute record per vertex, and `bt_merge_vertices_by_distance` says
+what it does with that: *"Only considers distance, no other attributes are accounted for."*
+`bt_vertex_replace` re-points references and orphans the victim's record.
+
+Measured on a hard-edged, UV-charted subdivided box pushed through `vgeo_normalize_source`: 1,734
+source vertices become 1,538, the 196 splits along the twelve cube edges are gone, and **six distinct
+normals survive, every one of them axis-aligned** — the master's record won outright and nothing was
+blended. Every hard edge now carries a normal 90° wrong for half the triangles using it, and each UV
+chart bleeds across its seam. Before a single collapse.
+
+Zorah does not hit this only because its source primitives carry `["POSITION"]` and nothing else.
+Every textured asset does.
+
+### 1.4 A source with no normals is smoothed across its creases
+
+Because Zorah authors no normals, `vgeo_normalize_source` synthesizes them by area-weighted
+averaging over the welded mesh, with no crease rule anywhere. At **LOD 0**, the angle between a
+vertex's normal and its own face's normal: mean 8.6°, p90 19.5°, p99 37.7°, max 179.9°; 2.5% of
+corners over 30°.
+
+This is a consequence of §1.3, not an independent defect: hard normals need more than one value at a
+position, and there is nowhere to put the second one.
+
+**Which symptom each stage fixes.** The reported defect is two visually distinct things. The dark
+wedge fanning out of a single vertex is §1.1 and §1.2, and §5/§6 remove it. The broad soft gradient
+smeared across a flat panel is §1.4, and §7 is what removes that — it is deferred, so a close-up of
+Zorah will still look smoother than it should after §5 and §6 land. Saying so here rather than
+discovering it in a screenshot.
+
+## 2. Why the current design is what it is
+
+`vgeo_compute_vertex_normals` states the case against the obvious alternative correctly:
+
+> carrying a surviving vertex's original normal through a dozen collapses shades a coarse level by
+> whichever vertices happened to win, which is visibly wrong.
+
+That is true. Survivor-takes-all *is* wrong. What was not considered is the third option: neither
+inherit the attribute nor re-derive it from the coarse geometry, but **fit** it — choose the value
+that best explains the source attribute field over everything folded into the vertex. That is what
+the geometric quadric already does for position, and it is the same machinery.
+
+The pin was then added on top to protect cut seams. The pin is *correct* and must survive this plan
+(§3). It only reads as the defect because the interior rule it sits beside is incompatible with it.
+
+## 3. Invariants any fix must keep
+
+1. **A cut is crack-free in geometry.** A vertex two groups share is never moved. Unchanged: this
+   plan does not touch `locked`, `protected_faces`, or the boundary polyline check.
+2. **A cut is crease-free in shading.** If cluster X at level L and cluster Y at level M sit side by
+   side in a cut, every vertex they share must carry **byte-identical** attribute values in both
+   payloads. Held by a spec: over a whole DAG, every position that appears in two payloads carries
+   the same encoded normal and tangent in both — across levels and within one. It needs *both*
+   gates removed to go red (§11), because they are genuinely redundant. The seam vertex is on a group perimeter at every level between L and M, so the rule
+   that delivers this is: *a pinned vertex keeps its attribute values exactly*. That rule stays.
+   Note what it rules out: deriving the frame once on the stitched frontier fixes §1.1 and breaks
+   this, because a pinned vertex's one-ring still changes between L and M even though the vertex
+   does not move.
+3. **`r_e` is an object-space length.** `VIRTUAL_GEOMETRY_DESIGN.md` §3's units guard: solve in the
+   higher-dimensional metric, report error by plugging the resulting *position* into the pure 3-D
+   geometric quadric. The reported error therefore stays exactly what it is today in kind, and the
+   cut rule, the error bands and the page layout keep working with no change.
+4. **Monotonicity.** `parent.error >= self.error` transitively. Already imposed in
+   `vgeo_build_group_step`; unaffected.
+5. **The position weld stays.** `vgeo_normalize_source`'s weld is load-bearing for *connectivity* —
+   without it the clusterer shreds the mesh along every seam. §7 separates "weld for topology" from
+   "weld for attributes"; it does not remove the first.
+
+## 4. The design
+
+Generalized quadrics — Garland & Heckbert 1998 (*Simplifying Surfaces with Color and Texture using
+Quadric Error Metrics*) for the naive `(3+m)`-dimensional lift, **Hoppe 1999** (*New Quadric Metric
+for Simplifying Meshes with Appearance Attributes*) for the form worth implementing. Unreal's Nanite
+uses the latter (`MeshSimplify.h` / `Quadric.h`: attribute-carrying quadrics, per-attribute weights,
+and a separate edge quadric for boundary and seam penalties); `meshoptimizer`'s
+`meshopt_simplifyWithAttributes` is a far more readable second reference for the same maths and for
+weight calibration.
+
+### 4.1 The maths, in the form this codebase will hold it
+
+For one triangle `(p1, p2, p3)` and one scalar attribute channel with corner values `(s1, s2, s3)`,
+the attribute is the linear field `s(p) = g·p + d` that interpolates the corners and has no gradient
+along the face normal:
+
+```
+e1 = p2 - p1,  e2 = p3 - p1,  n = normalize(e1 x e2),  det = |e1 x e2|
+g  = ( (s2 - s1) * (e2 x n) + (s3 - s1) * (n x e1) ) / det
+d  = s1 - g . p1
+```
+
+The error of a candidate `(v, s)` against that triangle is `(g·v + d - s)²`. Accumulated over every
+triangle folded into a vertex, with per-triangle weight `w`:
+
+```
+P  = SUM w * (g g^T)        3x3 symmetric      6
+q  = SUM w * (d g)          vector             3
+r  = SUM w * d^2            scalar             1
+W  = SUM w                  scalar             1
+G_i = SUM w * g_i           vector, per channel  3m
+D_i = SUM w * d_i           scalar, per channel   m
+```
+
+`P`, `q`, `r`, `W` occupy **exactly the `Quadric3` layout** — 11 elements, `A`/`b`/`c`/`w` — so an
+attribute quadric is a `Quadric3`-shaped header followed by `4m` elements, and every `quadric3_*`
+function applies to the header unchanged. Size is `11 + 4m`.
+
+Minimising over `s` for a fixed `v` is exact and gives the readout:
+
+```
+s_i = (G_i . v + D_i) / W
+```
+
+Substituting it back leaves a **3-D** quadric in `v` alone — the *reduced* quadric:
+
+```
+A_a = P - SUM_i (G_i G_i^T) / W
+b_a = q - SUM_i (D_i G_i)   / W
+c_a = r - SUM_i (D_i^2)     / W
+```
+
+which is again `Quadric3`-shaped. So placement is unchanged in kind: solve
+`(A_g + A_a) v = -(b_g + b_a)` with the existing `quadric3_optimize`, on the sum of the geometric
+quadric and the reduced attribute quadric. Attributes fall out afterwards.
+
+This is the whole reason to implement Hoppe's form rather than the lift: `11 + 4m` elements instead
+of `(m+4)(m+5)/2`, and a 3x3 solve instead of an `(3+m)x(3+m)` one.
+
+### 4.2 Weights
+
+`g` has units of `attribute / length`, so `(g·v + d - s)²` is dimensionless while the geometric
+quadric evaluates to `length²`. Summing them without a weight is meaningless. Each channel therefore
+carries a weight with units of length, applied by scaling the attribute values before the quadric is
+built and dividing it out on readout.
+
+The weight is stored as a **ratio of the geometry's own bounding-box diagonal**, for the same reason
+`weld_ratio` is (`VGeoBuildOptions#weld_ratio`): a conversion is many geometries at many sizes and no
+one distance is right for all of them.
+
+It is resolved once, off the source's bounds, before any pass has removed anything — the same moment
+`weld_distance` is resolved — and travels as an already-multiplied `Float64Array`, one entry per
+`VGEO_ATTRIBUTES` channel, from `vgeo_build` down to `vgeo_build_leaf_frontier` and every group step.
+`vgeo_normalize_source` returns a distance today and keeps doing so; the resolution is its own
+function so the two are not entangled and the weights can be read without normalising anything.
+
+Defaults start **low** — low enough that placement barely moves and the DAG's shape, error numbers
+and page layout stay comparable to today's — because the dominant win in §1.1/§1.2 is the *readout*,
+not the placement. Raising them additionally protects creases from being collapsed across, which is
+a second and smaller win. §6.4 is the sweep that picks the shipped numbers, and the numbers it picks
+are recorded here rather than asserted from taste.
+
+### 4.3 Per-channel handling
+
+| channel | carried | note |
+|---|---|---|
+| `NORMAL` (3) | in the quadric | renormalised after readout |
+| `TANGENT` (4) | xyz in the quadric **when the mesh has `UV0`**; otherwise derived from the normal | handedness is a discrete flag, taken from the survivor; re-orthogonalised against the final normal |
+| `COLOR` (3) | in the quadric | clamped to `[0, 1]` |
+| `UV0` (2) | in the quadric | |
+| `UV1` (2) | in the quadric | |
+
+The tangent split is not a special case dodged: with no `UV0` there is no parameterisation to be
+tangent to and the tangent is a pure function of the normal (`build_tangent_from_normal`, Frisvad).
+A pure function of a byte-identical input is byte-identical, so deriving it costs nothing against
+invariant 2 — and it is *more* robust than blending, because Frisvad's frame flips discontinuously
+and two nearly-opposite tangents average to nothing.
+
+**This table governs §5 as much as §6.** The moment the group step stops calling
+`vgeo_compute_vertex_tangents`, something has to produce a tangent, and blending a four-component
+tangent blends the handedness flag — a discrete `±1` — into a number that means nothing. Zorah is
+exactly the `UV0`-less case, so getting this wrong at Stage 0 would trade a shading defect for a
+worse one.
+
+### 4.4 Numerical guards
+
+- `g` divides by `det = 2 * area`, so a sliver produces an enormous gradient. Triangles whose `det`
+  is below an epsilon relative to the mesh contribute no attribute quadric. `vgeo_normalize_source`
+  has already collapsed and killed the worst of them; this is the backstop.
+- `W <= 0` means nothing has been accumulated — a faceless vertex. The readout is skipped and the
+  vertex keeps whatever it had.
+- Per-triangle weight is **1**, matching `quadric3_set_from_vector4`'s convention
+  (*"One plane, and callers pass unit normals, so it weighs one"*), not Hoppe's area weighting. The
+  two terms have to be commensurate when summed, and `quadric3_distance` already reads the whole
+  codebase's quadrics as a mean over unit-weight planes.
+- `vgeo_normalize_source`'s own `bt_mesh_collapse_short_edges` stays survivor-takes-all for
+  attributes, and that is left alone deliberately: it acts only on edges shorter than the weld
+  tolerance — `1e-5` of the diagonal — where the two records it is choosing between differ by less
+  than the octahedral encoding can represent. Recorded so it is a decision rather than an oversight.
+
+## 5. Stage 0 — transport instead of recompute
+
+The smallest change that removes the §1.1 artifact, and the plumbing every later stage needs.
+
+### 5.1 What changes
+
+- `bt_mesh_simplify_with_quadrics` gains an optional per-vertex attribute vector. At each collapse
+  the survivor's vector becomes the combination of the two endpoints' blended by their accumulated
+  quadric weights — how much source surface each of them stands for. A **restricted** survivor is
+  left exactly as it is, which is invariant 2 and is not negotiable.
+- `vgeo_build_group_step` hands it the mesh's channels flattened into that vector, writes the result
+  back into the layers for every non-pinned vertex, and **stops calling**
+  `vgeo_compute_vertex_normals` / `vgeo_compute_vertex_tangents`.
+- The normal is renormalised after the blend, and the tangent follows §4.3 — derived from the normal
+  where the mesh has no `UV0`, blended xyz with the survivor's handedness where it does, then
+  re-orthogonalised.
+- `vgeo_normalize_source` keeps calling both — that is the leaf field, and it is the thing everything
+  above now tracks. Neither pass becomes dead code.
+
+### 5.2 Why this is on the way to §6 and not a detour
+
+Stage 0 and Stage 1 differ only in *how the value at a collapse is chosen*. The plumbing — where the
+value is set, what the pin means, that nothing is re-derived from coarse geometry afterwards — is
+identical, and so are the specs that assert it. Stage 0 is the degenerate case of Stage 1: diagonal
+weights, no coupling to placement.
+
+### 5.3 Acceptance
+
+Measured, prototyped, against the source normal field on the same primitive:
+
+| level | recompute mean | transport mean | recompute >30° | transport >30° |
+|---|---|---|---|---|
+| L4 | 12.85° | 9.77° | 9.5% | 4.0% |
+| L5 | 15.49° | 11.50° | 14.0% | 5.7% |
+| L7 | 21.87° | 17.41° | 29.2% | 18.4% |
+
+The percentages matter more than the means: the pinned/interior split becomes vacuous, both follow
+one rule, and the wedge has nowhere to come from.
+
+- [x] A spec proving a pinned vertex's attribute record is byte-identical before and after a
+      simplification that moves everything around it. Over a *curved* fixture — see §11's second
+      entry for why a flat one proves nothing.
+- [x] A spec proving nothing re-derives a normal from coarse geometry in a group step. Stated as a
+      property rather than as equality, because the blend does change values: hand the builder a mesh
+      whose authored normals point somewhere its faces do not, and every level still points that way.
+      Equality was the wrong assertion — §6 replaced the blend with a fit and the numbers moved
+      again, while the property held through both, which is what it was written for.
+- [x] A spec proving a `UV0`-less mesh ships a unit tangent orthogonal to its normal at every level,
+      which is §4.3's rule stated as a test.
+- [x] The whole suite green, and both of Stage 0's own specs run red against the pass they replaced
+      first: the authored field arrived 175° out where it now arrives within one, and the root's own
+      derived field sat 8.6° from the surface it stands for against 3.2°.
+- [x] Zorah smoke conversion clean, with the refusal count unchanged — see §6.4, which ran it.
+
+## 6. Stage 1 — the attribute quadric
+
+### 6.1 New, in `core/geom/3d/quadric/`
+
+One function per file with a spec beside it, matching the `quadric3_*` family. Every function reads
+and writes `11 + 4m` consecutive elements of any array-like at any offset, the same way `quadric3_*`
+does.
+
+**And the builder takes that offer.** `Quadric3` is carried as an array of objects with `clone`,
+`add` and `sub`; the attribute quadrics are carried as **one flat `Float64Array` indexed by vertex**
+instead, which is the case `quadric3_*`'s own documentation names — *"how a caller holding a great
+many quadrics keeps them in one flat buffer instead of one object each"*. A round clones the whole
+frontier's set once per round; at `11 + 4m` doubles a million-vertex primitive would otherwise be a
+million short-lived objects per round on top of the million already there.
+
+- `quadric_attribute_size(m)` — `11 + 4 * m`.
+- `quadric_attribute_set_from_triangle(...)` — §4.1's construction for all `m` channels at once.
+- `quadric_attribute_add(...)` — elementwise; the reduction is done at solve time, never at
+  accumulate time, which is what keeps `add` associative.
+- `quadric_attribute_sub(...)` — the fold-back in `vgeo_build_levels` subtracts *gains*.
+- `quadric_attribute_reduce(...)` — writes the `Quadric3`-shaped `(A_a, b_a, c_a)` of §4.1.
+- `quadric_attribute_solve(...)` — the readout `s_i = (G_i·v + D_i)/W`.
+
+`Quadric3` itself is **untouched**, and so are its other callers (`bt_mesh_simplify_by_error`,
+`navmesh_build_topology`, `compute_tetrahedral_mesh_from_surface`). Keeping the geometric quadric
+pure is what makes invariant 3 free rather than something to be careful about.
+
+### 6.2 New, in the topology layer
+
+- `bt_mesh_compute_vertex_attribute_quadrics(mesh, values, components, ...)` — builds one per vertex
+  from every allocated triangle. It takes a flat `values` array and a component count and knows
+  nothing about `VGEO_ATTRIBUTES`, so it is reusable and testable on its own.
+
+### 6.3 Changed
+
+- `bt_mesh_simplify_with_quadrics` — Stage 0's blend becomes: reduce the summed attribute quadric,
+  add it to the geometric one, solve for position on the sum, read the attributes out at that
+  position. The cost that orders the heap becomes geometric + attribute, so a collapse that wrecks
+  the normal field is expensive. The **returned deviation is still the pure geometric quadric**
+  evaluated at the chosen position (invariant 3).
+
+  **A restricted survivor is still left exactly as it is** — position *and* attributes. The readout
+  would move it: a pinned vertex absorbs its victims' quadrics like any other survivor, so `W`, `G`
+  and `D` grow under it and the fit at its unchanged position comes out different. That is invariant
+  2, and it is the one place where "read the attributes out" is wrong.
+
+  **Attributes are opt-in and nothing else opts in.** `bt_mesh_simplify` passes none.
+  `bt_mesh_simplify_by_error` turns out not to be a caller at all — it is a separate implementation
+  with its own `choose_collapse` and `quadric_cost_at` — which is a stronger isolation than this
+  expected, and worth knowing because it simplifies to a *tolerance* that an attribute term in the
+  cost would silently move.
+- `VGeoBuildOptions` — per-channel weight ratios.
+- `vgeo_normalize_source` — resolves them to object-space beside `weld_distance`.
+- `vgeo_build_leaf_frontier` — builds the attribute quadrics once from the source, beside
+  `bt_mesh_compute_vertex_quadrics`.
+- `vgeo_build_group_step`, `vgeo_build_levels` — carry, fold back and re-index them exactly as
+  `Quadric3` is carried, folded back and re-indexed. The fold-back is gains-not-results for the same
+  reason.
+
+### 6.4 Acceptance
+
+**Met.** Measured on `mesh1[0]` of `zorah_main_public.v2.gltf` — 128,318 triangles, 64,231 welded
+vertices — Stage 0 against Stage 1, same primitive, same measurement, read out of the encoded
+payloads. How far the shipped normal sits from the source's field, by level:
+
+| level | Stage 0 mean | Stage 1 mean | Stage 0 over 30° | Stage 1 over 30° |
+|---|---|---|---|---|
+| 1 | 3.36° | **2.21°** | 0.6% | 0.4% |
+| 2 | 3.09° | **1.96°** | 0.5% | 0.4% |
+| 3 | 5.48° | **2.97°** | 1.5% | 0.8% |
+| 4 | 6.44° | **4.84°** | 2.5% | 1.1% |
+| 5 | 7.47° | **5.98°** | 3.5% | 1.9% |
+| 6 | 9.35° | **7.07°** | 6.6% | 2.5% |
+| 7 | 11.85° | **9.22°** | 10.9% | 5.9% |
+| 8 | 16.13° | **12.61°** | 19.2% | 11.6% |
+| 9 | 21.88° | **18.01°** | 30.1% | 22.6% |
+| 10 | 28.69° | **23.85°** | 39.0% | 29.8% |
+| 11 | 31.63° | **26.70°** | 40.7% | 35.6% |
+
+Better at every level, by a third at L1–L3 and by a fifth or more through the middle of the DAG,
+which is the part a camera actually spends its time in. Level 0 reads `0.01°` on both, which is the
+octahedral encoding and nothing else — the leaves are exact, as they must be.
+
+- [x] Source-field error at every level at most Stage 0's, and materially below it at L3 and above.
+- [x] A sweep of the weight ratios: `VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS` carries the table and the
+      argument. `1/1024`. Above `1/64` it stops being a trade — eighteen times the geometric error
+      for a normal field that is *worse* — because this content is smooth and there is no crease for
+      the placement term to defend. A subdivided cube, which is all crease, goes from 14.9° of
+      worst-case normal error to **1.38°** at `1/4`; that is what raising it is for.
+- [x] `self_error` at the root **fell**, 7.325e-2 to 6.019e-2, which is 0.82x and inside the 20% the
+      gate allowed in either direction.
+- [x] Levels 13 to 14, clusters 2,677 to 2,686 — a third of a percent. The DAG is the same shape.
+- [x] Build time 2,373 ms to 2,906 ms, **1.22x**, against the 2x gate. All the scratch in
+      `evaluate_edge_collapse` is module-level and grown once per channel count, never allocated per
+      candidate.
+- [x] The whole suite green: 19,377 tests.
+- [x] Zorah smoke conversion, run both sides of the change: **203 of 203** geometries under 5,000
+      triangles convert on each, and **450 of 450** under 20,000 convert here with the full container
+      audit on — every build invariant, checksum and directory record, in every file. 3,095,102
+      source triangles, no refusals either side. Bytes 12.0 to 12.1 MiB on the smaller run, which is
+      0.8%, and the conversion is 9.7 s against 10.1 s.
+- [x] Peak builder memory, as process RSS across the level loop, both sides of the change:
+
+      | primitive | Stage 0 | Stage 1 | |
+      |---|---|---|---|
+      | 400,008 triangles | 774 MiB, 9.7 s | 874 MiB, 9.7 s | 1.13x, 1.00x |
+      | 801,427 triangles | 3,055 MiB, 32.7 s | 3,741 MiB, 37.4 s | 1.22x, 1.14x |
+
+      The `11 + 4m` doubles a vertex carries against `Quadric3`'s `11` is 23 for a normal-only asset,
+      and the frontier's set is one flat buffer rather than an object each; a fifth more is what that
+      comes to in practice. Not the *largest* primitive — that one is 1,076,562 triangles and takes
+      many minutes.
+
+      **The reading that twice the triangles cost 3.4x the time is not a superlinearity, and saying
+      so here was wrong.** Investigated separately: the builder is linear, in **clusters**, at about
+      a millisecond each — and how many clusters a source cuts into is set by its vertex-to-face
+      ratio rather than by its triangle count, so two primitives of the same size can be an order of
+      magnitude apart in cost. Triangles were the wrong x-axis.
+
+## 7. Stage 2 — wedges. Specified here, planned in full separately
+
+§1.3 and §1.4 need a position to carry more than one attribute record. That is a change to what
+`BinaryTopology` means for this builder, and it reaches the clusterer, the payload encoder and the
+gather — a much larger blast radius than §5 and §6, with none of their measurements to lean on until
+the format work is done. Doing it badly is worse than not doing it, so it is specified here and taken
+separately.
+
+**Taken up in [WEDGE_PLAN_2026_09_18.md](./WEDGE_PLAN_2026_09_18.md)**, which is this section with
+the representation decided, the collapse rule chosen, and three staged gates. What follows is the
+shape it starts from.
+
+- **Weld for connectivity, not for attributes.** `bt_merge_vertices_by_distance` keeps doing exactly
+  what it does. What changes is that a topology vertex gains a small set of *wedges* — attribute
+  records — and a loop names one of them, so one position can shade two ways.
+- **Seams are pinned by constraint planes, not by luck.** The mechanism already exists:
+  `bt_mesh_compute_vertex_quadrics`'s `add_boundary_constraints` adds Garland & Heckbert's
+  perpendicular plane at every open edge at `BOUNDARY_WEIGHT = 3`. An attribute seam is the same
+  situation — sliding along the surface destroys something the face-plane quadric cannot see — and
+  wants the same plane. This is the "boundary-plane-penalty mechanism" `VIRTUAL_GEOMETRY_DESIGN.md`
+  §2 already requires, reused rather than invented.
+- **A collapse merges wedges that agree and keeps those that do not**, which is where the vertex-count
+  growth is bounded.
+- **Crease-angle synthesis** (§1.4) then becomes available for a source that authors no normals:
+  split by angle instead of averaging a 179° corner into one value. It is blocked on wedges and on
+  nothing else.
+
+## 8. What this does not change
+
+- **The container format.** No new fields, no version move. Attribute values are encoded exactly as
+  they are today (`vgeo_encode_cluster_payload`, octahedral normals and tangents).
+- **The runtime.** Nothing on the device reads a quadric.
+- **The cut rule.** `r_e` stays an object-space length by invariant 3.
+- **Existing `.vgeo` files.** They remain readable; they are simply built from a worse metric, and a
+  rebuild is what improves them. The Zorah asset needs re-converting to benefit (§9).
+
+## 9. Measurement
+
+The three probes that produced §1 become a bench spec, `vgeo_attribute_fidelity.bench.spec.js`,
+beside the builder — so the numbers in this document can be re-taken rather than believed.
+
+It follows the house shape for a bench (`atlas_generate.bench.spec.js`): **deterministic synthetic
+fixtures, no asset dependency, behind `.skip`** so it is not a gate on a normal run. No spec in this
+package reads `test_assets/`, and one that did could not run in CI, where the 51 GiB of converted
+Zorah is not present. The Zorah figures in §1 come from a scratch driver over the real container and
+stay there; what the bench gives is the same three measurements on geometry the repository owns, so a
+regression is caught by the suite rather than by a conversion someone remembers to run.
+
+The three:
+
+- **shipped vs. the surface it ships on**, split by pinned / interior. §1.1's table. This is the one
+  that should read zero for both columns after Stage 0.
+- **shipped vs. the source attribute field**, sampled at the nearest source vertex. §1.2 and §5.3.
+- **shipped vs. the level below at the same vertex** — the pop across a LOD transition.
+
+Per `test-helpers-live-in-the-specs`, the fixtures and the sampling grid live in the spec file, not
+in a shared helper.
+
+The end-to-end check is the Zorah smoke conversion: the 5-second subset run that
+`vgeo-build-refusal-harness` describes, whose refusal list is the regression signal.
+
+## 10. Rejected
+
+- **Derive the frame once on the stitched frontier.** Fixes §1.1 and breaks invariant 3: a seam
+  vertex's one-ring differs between the level that holds it and the level that replaces it even
+  though the vertex never moves, so the two payloads disagree and the cut creases. Trades a wedge for
+  a seam.
+- **Bake the source normals into a map.** No UVs on the content that shows the defect, and it
+  contradicts the premise that virtual geometry carries its own detail.
+- **Keep the survivor's attribute record.** §2: this is the failure the current design was written
+  to avoid, and it is a real one.
+- **The full `(3+m)`-dimensional quadric.** Correct, and strictly more expensive than §4.1 for the
+  same answer.
+
+## 11. Review ledger
+
+This plan was reviewed against the code before any of it was written. What the review changed:
+
+| # | finding | resolution |
+|---|---|---|
+| 1 | §4.1's closed form was asserted, not checked | Verified numerically before the plan was accepted: interpolation residual and `g·n` both at `8e-15`, the reduced form matches the exact minimum over `s` to `2e-14`, and the reduced 3x3 solve reaches the same optimum as gradient descent on the full `(3+m)`-dimensional problem to `1e-15`. The same three properties become specs in §6.1. |
+| 2 | Stage 0 stopped calling `vgeo_compute_vertex_tangents` without saying what produces a tangent instead — and blending a 4-component tangent blends the handedness flag. Zorah is the `UV0`-less case that would have shipped it | §4.3 now says it governs §5 as much as §6; §5.1 states the rule; §5.3 adds the spec |
+| 3 | §6.3 said "read the attributes out at that position" with no exception, which moves a **pinned** vertex's value and breaks invariant 2 | §6.3 states the exception and why the readout is wrong there |
+| 4 | Nothing said what happens to `bt_mesh_simplify_by_error`, which shares `evaluate_edge_collapse` and simplifies to a *tolerance* | §6.3: attributes are opt-in, and neither other caller opts in |
+| 5 | §6.3 said the attribute quadrics are carried "exactly as `Quadric3` is" — an object per vertex, cloned per round, at `11 + 4m` doubles each | §6.1: one flat `Float64Array` indexed by vertex, which is the idiom `quadric3_*` documents for exactly this |
+| 6 | The plan implied it fixed the reported symptom outright; the soft gradient across flat panels is §1.4 and needs §7 | §1.4 now states which stage fixes which half |
+| 7 | "within a stated factor" / "a stated tolerance" are not acceptance criteria | §6.4 names 2x on build time and 20% on `self_error`, and asks for level and cluster counts |
+| 8 | §9 put the Zorah measurement in a spec; no spec in this package reads `test_assets/`, and CI has no Zorah | §9: synthetic fixtures behind `.skip`, house shape; the Zorah driver stays a scratch script |
+| 9 | Weight resolution was hand-waved onto `vgeo_normalize_source`, which returns a distance | §4.2: its own function, resolved at the same moment, travelling as a `Float64Array` per channel |
+| 10 | `bt_mesh_collapse_short_edges` is survivor-takes-all for attributes and the plan was silent | §4.4: named, with the reason it is left alone |
+
+## 12. Implementation review ledger
+
+The work was reviewed against itself after it landed. What that found:
+
+| # | finding | resolution |
+|---|---|---|
+| 1 | A step handed the level loop one `Float64Array` per surviving vertex, where the geometric side hands over a reference and allocates nothing | The step keeps the buffer the simplifier finished with, whole, and `step.quadrics` — which already had an identical key set — says which entries are live. Same output; 2,906 ms to 2,774. |
+| 2 | "A pinned vertex keeps its record" was asserted over a *flat* fixture with a field affine over the whole mesh — where every triangle projects the same gradient and the fit reproduces the original value at every point, pin or no pin. The spec could not have failed | Bent the grid. Removing the pin now fails it. |
+| 3 | Nothing asserted the invariant §3.2 states, which is the one the DAG rests on | A spec over every position in a whole DAG. It needs **both** pins removed to go red — the write-side gate catches what the collapse-side gate lets through — which is a real property of the design rather than a weakness of the spec, and is recorded rather than deduplicated away. |
+| 4 | The blend fallback — a vertex with no field to fit from — was unreachable from any spec | Handing the simplifier quadrics that are all zero is that case everywhere at once. |
+| 5 | A fitted colour can leave `[0, 1]`, which §4.3 called for and the code did not do. The encoder saturates, so no word was ever wrong — but the out-of-range value stays in the layer, and it is what the *next* level's field is fitted from | Clamped on the way back into the layer. |
+| 6 | `bt_mesh_simplify_by_error` was documented as a caller that passes `null` | It is not a caller at all — its own `choose_collapse` and `quadric_cost_at`. A stronger isolation than claimed, and stated correctly now. |
+| 7 | The bench's pop column keyed by coordinate, so it compared only vertices that never moved — the pinned perimeters, which are byte-identical by construction. It would have reported a pop of zero on a build that had one | Sampled at the nearest place on the coarser surface instead, which is what a pixel sees. |
+| 8 | The default-ratio note quoted one cube as "a subdivided cube" | Sixteen subdivisions per face reads 14.9° of worst-case normal error against 1.38° at a quarter; twenty-four reads a hundredth of a degree at every ratio. Named which. |
+
+**`check-types` is at its budget of 19, and none of the nineteen are in a file this touched.**
+
+Worth saying how that was arrived at, because the first answer was wrong. `npm run check-types` in a
+`.claude/worktrees/` tree reports *zero*, and zero is not progress — the script spawns
+`<pkg>/../../node_modules/.bin/tsc`, which a bare worktree does not have, `spawnSync` fails silently,
+and the run counts errors in an empty output. The number only means anything from a tree with a
+populated `node_modules`, or by invoking the main checkout's compiler directly:
+
+```
+/h/git/CompanyNamed/meep/node_modules/.bin/tsc --project tsconfig.types.json
+/h/git/CompanyNamed/meep/node_modules/.bin/tsc --project type-check/tsconfig.json
+```
+
+Declarations emit clean; the consumer program reports 19, every one of them in the documented set
+(`Vector3`, `Vector2`, `Quaternion`, `EnginePlugin` and the rest that `scripts/BUDGET.md` lists), and
+none in any file this change wrote or edited.