@woosh/meep-engine 3.28.0 → 3.29.0

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

@@ -0,0 +1,358 @@
+# Wedges — plan, 2026-09-18
+
+`ATTRIBUTE_PLAN_2026_09_18.md` §7, taken up. That plan fixed *how a coarse vertex is given its
+shading values*; this one fixes the fact that a vertex can only hold **one set of them**, so every
+hard edge and every texture seam in a source is destroyed before the builder has done anything at
+all.
+
+## 1. The defect, restated with its measurement
+
+`BinaryTopology` carries one attribute record per vertex, and `bt_merge_vertices_by_distance` says
+plainly 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.
+
+The weld itself is not the defect and is not going anywhere. `vgeo_normalize_source` says why: without
+it *"two triangles welded along a seam still look unrelated to every query downstream, and the
+clusterer shreds the mesh along every UV seam it has."* Connectivity wants the weld. Appearance does
+not.
+
+**Second consequence, and it is the visible one on Zorah.** A source that authors no normals gets them
+synthesized by area-weighted averaging with no crease rule, because there is nowhere to put a second
+value at a corner. At LOD 0 the angle between a vertex's normal and its own face's normal runs to a
+mean of 8.6°, a p99 of 37.7° and a **max of 179.9°**. That is the soft gradient smeared across flat
+panels, and no amount of work above the leaf can undo it.
+
+## 2. Loops are where this belongs, and the codebase already says so
+
+`BinaryTopology` has had per-loop storage since it was written — `loop_data`, `loop_data_add_layer` —
+and it has one real consumer, whose own documentation is the argument:
+
+> UVs live on loops rather than vertices so that one geometric vertex shared by several charts carries
+> a distinct UV per chart — which is exactly how a seam is represented.
+> — `bt_loop_uv.js`
+
+`bt_mesh_compact` already compacts loop data with everything else. So this is a mechanism to *use*,
+not one to invent.
+
+Two facts make it work through simplification:
+
+- **Loop identity survives a collapse.** `bt_vertex_replace` re-points a surviving loop to the
+  survivor vertex and leaves the loop itself alone, so whatever a loop carries travels with it for
+  free. Loops of killed faces die, which is also correct — their corners no longer exist.
+- **The payload encoder is already generic over it.** `vgeo_encode_cluster_payload(positions,
+  indices, vertex_ids, layers)` only ever does `layers[attribute].read(…, vertex_ids[v])`. Hand it
+  loop ids and loop layers and it is unchanged. The parameter is misnamed for that use and gets
+  renamed; nothing else about the encoder, the format, or the runtime moves.
+
+## 3. The representation
+
+A **wedge** is a maximal set of loops at one vertex that carry the same appearance. Three pieces:
+
+| what | where | indexed by |
+|---|---|---|
+| attribute values | loop data layers | loop |
+| wedge id | a `u32` loop data layer | loop |
+| attribute quadrics | a flat `Float64Array` | wedge |
+
+**The invariant, and it is what the specs hold:** every loop with the same wedge id carries
+byte-identical attribute values. That makes the wedge id a *cache* of an equivalence that the values
+themselves define, which is checkable rather than trusted.
+
+> **What it became.** There is no `u32` loop layer, because a cache that can go stale is worse than
+> the thing it caches and this one did not need to exist. The partition is *decided* in exactly one
+> place — `vgeo_mesh_wedges`, at the leaf, reading byte equality of each corner's whole record, which
+> is the invariant above applied directly — and **everywhere else it travels by provenance**, the way
+> `source_vertex_ids` always has: the submesh gets its wedge ids from the frontier's, the stitch
+> hands out the next frontier's, and an accumulated quadric crosses each seam by an id map. A
+> `BtWedgeSet` holds a wedge id per *loop* that is never rewritten, a union-find that resolves it
+> after a merge, and one intrusive list per vertex. Byte equality rather than a tolerance because an
+> equivalence relation has to be transitive: a tolerance is not, so grouping by one would depend on
+> the order the corners were walked in and two runs over the same mesh could disagree about it.
+
+Why values per loop rather than per wedge with an indirection: the gather and the encoder both want a
+value per corner, the duplication is bounded (`3F` records against `V`, so about six times, ~108 MB on
+a million-triangle primitive against the 3.7 GB the build already peaks at), and an indirection at
+that seam would have to be threaded through every consumer for nothing. Why quadrics per wedge rather
+than per loop: a per-loop quadric only ever accumulates its own triangle, and a fit from one triangle
+is exact and says nothing. The quadric's whole value is the history, and the history belongs to the
+wedge.
+
+**Geometric quadrics stay per vertex.** They are about position, position is the vertex's, and
+`ATTRIBUTE_PLAN` §3's units guard depends on that set staying untouched.
+
+## 4. What a collapse does
+
+Today: the survivor's attribute record is fitted from its accumulated quadric at the new position.
+
+With wedges, the same, once per wedge — plus the one new decision:
+
+**When the victim's loops arrive at the survivor, which of them join a wedge that is already there?**
+
+> **This section's answer is wrong, and the implementation does not use it.** Matching on attribute
+> equality within a tolerance says that two wedges merge when their *values* agree — and two
+> neighbours on a smoothly curved surface have genuinely different normals, so on a sphere it would
+> refuse to merge almost every collapse and invent a crease at each one. The wedge count would grow
+> without bound on exactly the content that has no seams in it at all.
+>
+> **What decides it is a live face.** Each face on the collapsing edge holds one corner at each
+> endpoint and is about to die into the survivor, so those two corners are one corner's worth of
+> surface afterwards; everything else the pair carries stays apart. Topological, exact, no tolerance
+> anywhere, and it keeps every property listed below — on a smooth mesh every edge has its faces and
+> every collapse merges the pair, so the whole thing still degenerates to the old behaviour exactly.
+> A faceless edge is a fuse of two points rather than a simplification of a surface and is treated as
+> one group; rare, and measured rather than assumed, at 6 of 6,195 collapses over a
+> 12,288-triangle sphere's whole DAG.
+>
+> The **wedge count cannot grow** under that rule, which is what made the tolerance unnecessary
+> rather than merely wrong. A vertex's wedges are the fans its creases cut its ring into; a manifold
+> edge's two faces merge one pair each, so a smooth pair goes 1+1−1 = 1, a crease-to-crease pair
+> 2+2−2 = 2, and a crease-to-smooth pair 2+1−1 = 2. The fan structure of the source is the ceiling,
+> and the DAG still reaches one root because a cluster's triangle count keeps falling whatever its
+> wedge count does.
+
+Attribute equality, within a tolerance. Two wedges that describe the same appearance are one wedge;
+two that do not stay two. This is Nanite's rule (`MeshSimplifier` matches corners by attribute
+equality on a collapse) and it has the properties that matter:
+
+- On a smooth mesh every wedge at a vertex is equal to every other, so there is exactly one, and the
+  whole thing degenerates to today's behaviour **exactly**. That is §6's first gate.
+- A hard edge stays split as long as its two sides genuinely differ.
+- It stays split *only* that long. Wedges that have converged merge, which is what stops the wedge
+  count from being a floor under how far the DAG can coarsen — and the builder has to reach a single
+  128-triangle root.
+
+The tolerance is per channel and has precedent in this package:
+`geometry_simplify_redundant_topology` already carries `normal_cosine_tolerance = 1e-3` and
+`attribute_tolerance = 1e-5` for the same question asked of a different pass.
+
+**Merging two wedges adds their quadrics**, which is the same operation a survivor already performs
+on a victim's and needs nothing new.
+
+## 5. Seam constraint planes
+
+An attribute seam is a place where sliding *along* the surface destroys something the face-plane
+quadric cannot see — which is the same situation an open boundary is in, and the same situation
+`bt_mesh_compute_vertex_quadrics` already handles:
+
+> for each open edge, add the plane through it perpendicular to its face
+> — `add_boundary_constraints`, at `BOUNDARY_WEIGHT = 3`
+
+An edge whose two loops on one side belong to a different wedge than the two on the other is a seam,
+and it wants that same plane. This is the "boundary-plane-penalty mechanism" `VIRTUAL_GEOMETRY_DESIGN`
+§2 named, reused rather than invented. It lands in §8's third stage, because it is an improvement to
+where a seam vertex goes rather than a requirement for the seam to exist.
+
+> **Not taken, and the reason is that it would be a second answer to a question already answered.**
+> `ATTRIBUTE_PLAN_2026_09_18.md` put the attribute quadric's *reduction* into the placement solve and
+> into the cost, so a collapse that would smear a seam is already both moved away from it and priced
+> for it — in the metric, where it belongs, rather than as a penalty bolted onto the geometry. Adding
+> planes to the **geometric** quadric would also inflate what `r_e` reports, and `r_e` is the one
+> number the runtime's cut rule depends on; §3's units guard exists precisely to keep that set
+> untouched by anything the attributes do. If a seam is later measured to drift, this is where to
+> start — but it should be measured first.
+
+## 6. Staging
+
+Three stages, each with a gate that can fail.
+
+### 6.1 — Attributes move to loops, one wedge per vertex — **DONE**
+
+A pure refactor. Wedge id is derived from the vertex, so every vertex has exactly one wedge and
+nothing about the output can change.
+
+- `VirtualGeometryMesh.layers` are declared on `loop_data`.
+- `vgeo_layers_declare` / `_like` / `_copy_vertex` become the loop-indexed equivalents.
+- `vgeo_gather_faces` dedupes on `(vertex, wedge)` and returns a representative loop per output
+  vertex; `vgeo_encode_cluster_payload`'s third parameter is renamed to what it is.
+- `vgeo_attribute_vector_{read,write}`, `bt_mesh_compute_vertex_attribute_quadrics` and the
+  simplifier index by wedge.
+
+**Gate: the DAG is byte-identical**, and it very nearly is. `vgeo_build` is already proved
+deterministic, so the container built before and after was hashed on five fixtures. A derived-attribute
+sphere, a torus, a grid, **and a grid with authored normals and UVs** all match byte for byte. Zorah's
+whole 450-primitive smoke run comes to the same 92.1 MiB it did before.
+
+The one fixture that moves is a sphere whose source disagrees with *itself* — the wrap seam and the
+poles, where two coincident vertices carry different UVs. There the weld picks an arbitrary winner
+either way, and its choice moved. There was never a non-arbitrary one to preserve; that is the defect
+§6.2 removes. **The seamless authored grid is what makes that claim precise rather than convenient**:
+it has every channel, it goes through the same code, and it does not move.
+
+Cost, measured on a 400,008-triangle Zorah primitive: **11.4 s to 11.9 s and 857 MiB to 934**. The
+`3F` records against `V` is about six times the channel storage, arriving as 9% of a build that is
+mostly not channels.
+
+#### What it turned out to cost, that this plan did not foresee
+
+Three things, each found by a gate rather than by reading:
+
+1. **A pinned vertex is *written* now, and writing it is what keeps it pinned.** Pinning meant "leave
+   it alone", and under per-vertex storage leaving it alone left its value alone. Under corner
+   storage it does not: a collapse re-points the victim's corners onto the survivor and they arrive
+   carrying the victim's appearance. So the carried value goes back over every corner, pinned or not,
+   and what pinning now means is that nothing is *derived* — no renormalize, no re-orthogonalize.
+2. **The tangent's handedness needed a vector of its own.** It is a flag no fit touches and no
+   derivation replaces, so a donated corner simply kept the one it arrived with. `vgeo_cut.spec.js`
+   caught it: one vertex of a cube-sphere came out of a cut with two different tangents in two
+   payloads. It now travels in a second, *verbatim* vector that the simplifier is never handed, so a
+   survivor's flag stays a survivor's. §4's "the survivor's flag is kept" was a sentence; it is now
+   a data structure.
+3. **A byte-identity gate cannot see a quadratic.** Reading a vertex's appearance means naming one of
+   its corners, finding one means a pass over the loop pool, and `vgeo_extract_submesh` did that per
+   extraction — a pass over the whole frontier repeated once per part of it. 11.4 s became 47.7 s
+   with the output byte-identical throughout. The frontier holds the map now
+   (`vgeo_frontier_loop_of_vertex`). **Every stage below needs a timing reading, not only a
+   correctness one.**
+
+### 6.2 — The source's splits become wedges — **DONE**
+
+`vgeo_normalize_source` stops destroying them. The weld still runs and still welds *positions*; the
+corners it re-points keep the values they arrived with, so a vertex the source split comes out of
+normalization still split. `vgeo_layers_unify_corners` — the module written the day before purely so
+the defect had a name and a line to delete — is deleted.
+
+No loop has to remember which source vertex it came from, as this section supposed: it carries the
+*values*, and `vgeo_mesh_wedges` reads the partition back off them.
+
+- **Gate:** a box ships six normals and not a gradient. Every shipped corner normal on a subdivided
+  cube is within **2 degrees of a coordinate axis, at every level of the DAG**; take the split away
+  and it reads **54.7**, which is the diagonal of three faces averaged into one. That one number
+  separates the two behaviours without needing to know which face a vertex belongs to.
+- **Gate:** a UV-charted box keeps each chart's coordinates on its own side of every seam — its
+  twelve triangles over eight points ship **24 vertices**, three per corner, one per chart. The
+  fixture needed fixing before it said that: with each face charted `0..1`, two of a corner's three
+  charts hand it the *same* coordinate, they are genuinely one wedge, and the answer is 20. Each face
+  into its own sixth of an atlas, as a real one would be, and it is 24.
+- **Gate:** a smooth source produces exactly one wedge per vertex, asserted directly on a torus, and
+  6.1's byte-identity gate still passes on four of its five fixtures.
+
+### 6.3 — Wedges merge through the collapse
+
+§4's rule, plus §5's seam planes.
+
+**6.2 and 6.3 have to land together.** Separately, 6.2 is a regression: the leaf would keep its splits
+and the first group step would throw them away again, because the simplifier carries one value per
+*vertex* and writes it over every corner. A DAG whose LOD 0 has hard edges and whose LOD 1 does not is
+worse than one that never had them, and there is no honest place to stop between.
+
+#### The shape the merge wants, sharpened by 6.1
+
+- **Wedge ids are a `u32` loop layer**, assigned densely at the leaf by grouping each vertex's corners
+  on attribute equality. Values and quadrics are indexed by wedge.
+- **Merging is per collapse, not a pass between them.** A pass at the end of a step would leave every
+  collapse *within* the step fitting from a quadric that never absorbed its victim's — the survivor's
+  wedge and the victim's would stay separate for thousands of collapses, and "conformance to the
+  source" is exactly the property that history carries.
+- **Union-find over wedge ids** is what makes that cheap: merging is a union, the loop layer is never
+  rewritten, and lookups go through `find`. No corner has to be located to be re-pointed.
+- **A `wedges_of_vertex` list per vertex** is what the collapse iterates: survivor's list against
+  victim's, matching on value within tolerance. **For a smooth mesh every list has length one**, so
+  the hot loop costs one comparison — which is what makes this affordable on content like Zorah,
+  where the wedge machinery has nothing to do.
+- The tolerance has precedent in this package already: `geometry_simplify_redundant_topology` carries
+  `normal_cosine_tolerance = 1e-3` and `attribute_tolerance = 1e-5` for the same question asked of a
+  different pass.
+
+Two passes stop being re-indexable and have to be **rewritten** rather than adjusted, and both say so
+in their own source today: `vgeo_compute_vertex_tangents` (Lengyel's solve is per vertex and does not
+become per corner by reading corners) and `vgeo_compute_vertex_normals` (which is where crease-angle
+splitting goes, and is the whole of §1's second consequence).
+
+- **Gate:** a hard-edged box converges to a single root — no wedge floor. It does, in 6 levels.
+- **Gate:** it keeps its creases while it does — the 2-degree bound above is over *every* level, not
+  only the leaf.
+- **Gate:** the crease-angle synthesis this unlocks. `vgeo_compute_vertex_normals` averages per
+  corner group, where a group is the connected run of faces a crease does not interrupt, and
+  `VGEO_CREASE_ANGLE` (also `VGeoBuildOptions#crease_angle`) is the threshold. It reproduces
+  `bt_mesh_compute_vertex_normals` step for step — Newell's normal out of a float32 scratch, summed
+  face-then-corner, scaled by a reciprocal — so a mesh **without** a crease comes out bit for bit
+  what it always did. That is not fastidiousness: without it every smooth fixture moved, for nothing,
+  and the gate could no longer tell a real change from a rounding one.
+- **Gate:** `ATTRIBUTE_PLAN` §3's invariants all still hold. The seam identity test keys on
+  *position*, which is exact while every vertex has one wedge and is the wrong question the moment
+  one does not — a creased mesh ships two frames at one point **on purpose**. Its creased form is a
+  bound instead: a point of a box ships at most one frame per plane it touches, over the whole DAG,
+  so a fit that drifted or a level that disagreed with the level below shows up as a fourth.
+
+#### What it cost
+
+**Measured, on Zorah's 203 primitives of at most 5,000 triangles, every one of which built and
+validated before and after.** 12.1 MiB stored becomes 13.0 (+7.4%), 14.1 MiB decoded becomes 16.5
+(+17%), and the conversion runs 13.5 s against 15.3. That is the price of a hard edge and it is not
+an overhead: a shipped vertex is a *wedge*, and small architectural props are mostly creases.
+
+The clearest statement of it is the scattered-cube fixture. A cube is eight vertices and **twenty-four
+shading vertices**, so 200 of them cut into 40 leaves where they cut into a dozen before — 4,800
+wedges against a 128-vertex meshlet ceiling cannot be fewer than 38 clusters however well they are
+packed. The DAG still closes, in 7 levels over 9 pages.
+
+Against the *level loop* alone, with no channels changed, there is nothing to pay: paired A/B over an
+81,920-triangle sphere, alternating which tree runs first, is 2,697 ms before and 2,664 after.
+
+## 7. What does not change
+
+- **The container format.** No new fields, no version move. A wedge is a builder concept; what ships
+  is what has always shipped, a value per cluster-local vertex.
+- **The runtime.** Nothing on the device knows what a wedge is.
+- **The cut rule and `r_e`.** Geometric quadrics stay per vertex and stay the only thing an error is
+  reported from.
+- **The weld.** Positions still fuse at `weld_ratio`; connectivity is what that is for.
+- **Vertex counts in the *topology*.** A wedge does not add a vertex. It adds an output vertex at
+  gather time, which is where a seam has always cost one.
+
+## 8. Rejected
+
+- **Stop welding attribute-distinct vertices.** The obvious move and the wrong one:
+  `vgeo_normalize_source` already records what it costs — the clusterer shreds the mesh along every
+  seam, because face adjacency is read off radial cycles and two triangles across an unfused seam
+  look unrelated. Weld for connectivity; split for appearance. They are different questions and the
+  answer has to be different.
+- **A per-vertex list of wedges with a loop→index.** The same thing as a wedge id on the loop, with an
+  extra structure to keep in step and nothing bought.
+- **Wedges fixed at the leaf, never merged.** No tolerance to choose, and a floor under the DAG at
+  whatever the source's seam count happens to be. The builder must reach one root.
+- **Deduping only at gather, with no wedge in the simplifier.** Values would travel correctly and the
+  quadrics would not: each loop would accumulate its own triangle and nothing else, and a fit from one
+  triangle is exact and worthless.
+
+## 9. Review ledger
+
+### 6.1
+
+| # | finding | resolution |
+|---|---|---|
+| 1 | Moving the channels onto corners cost 4.2x the build time — `vgeo_extract_submesh` scanned the whole frontier's loop pool once per group | The frontier holds the map. 47.7 s back to 11.9. **The output was byte-identical the whole time**, which is the finding behind the finding: correctness gates are blind to this and every later stage needs a timing reading of its own. |
+| 2 | A pinned vertex's corners could be a collapse's donations, so "leave it alone" stopped meaning "leave its value alone" | It is written, with the value it already had; what pinning means is that nothing is *derived* for it. |
+| 3 | The tangent's handedness is fitted by nothing and derived by nothing, so a donated corner kept the flag it arrived with — and a cut disagreed with itself | A second, verbatim vector the simplifier is never handed. Caught by `vgeo_cut.spec.js`, which existed. |
+| 4 | `vgeo_layers_unify_corners` claimed two call sites | One. The collapse path stopped needing it when 2 landed, and the doc had not caught up. |
+| 5 | The layer-declaration comment still talked about vertices | Loops, and three records per triangle rather than one per vertex. |
+| 6 | `vgeo_stitch_frontier`'s comment claimed "a handful of topologies" | One per group plus the frontier, which sums to a pass over the round. The cost was right; the description was not. |
+
+`check-types` at budget: declarations emit clean, the consumer program reports 19, all in the
+documented set, none in a file this touched. Zorah's smoke: 450 of 450, every container audited,
+92.1 MiB — the same byte count as before.
+
+### 6.2 and 6.3
+
+| # | finding | resolution |
+|---|---|---|
+| 1 | §4's merge rule is wrong. Matching wedges on **attribute equality within a tolerance** means two neighbours on a curved surface — whose normals genuinely differ — refuse to merge, so a sphere would gain a crease at every collapse and the wedge count would grow without bound on content with no seams at all | A live face decides it instead: each face on the collapsing edge holds one corner at each endpoint and is about to die into the survivor, so those two are one corner's worth of surface. Topological, exact, no tolerance anywhere. And it made the tolerance *unnecessary* as well as wrong — the fan arithmetic in §4 shows the wedge count cannot grow, which was the thing the tolerance was there to prevent. |
+| 2 | §3's `u32` wedge-id loop layer is a cache of the values, and a cache that can go stale | Deleted before it was written. The partition is decided in exactly one place, from the values themselves, and travels by provenance everywhere else — the way `source_vertex_ids` always has. Byte equality rather than a tolerance, because an equivalence relation must be transitive or the partition depends on the order corners were walked in. |
+| 3 | **A set that is not maintained is a set whose ids go stale.** The wedge set lived inside the `attributes` bundle, so a mesh with no channels carried none, and a victim's loops arrived at the survivor still naming the victim's wedge | It is its own argument to the simplifier and is merged whether or not values ride on it. **The byte-identity gate saw nothing**: the containers matched throughout, and what caught it was an unrelated ceiling assertion — clusters of 132 vertices against a cap of 128. |
+| 4 | Two ceilings counted the wrong thing. `VGeoFaceGraph.count_unique_vertices` and the bin packer's `unique_vertices` both fed the meshlet's 128-vertex limit a count of **mesh vertices**, where a meshlet carries one record per wedge | Both count wedges. Found by a hard-edged fixture at 240 against 128 — and the two had to be fixed separately, because the second is the packer's own and the first only bounds the pieces going into it. |
+| 5 | The crease pass reimplemented the face normal as a cross product, so every smooth fixture moved for no reason and the gate could no longer tell a real change from a rounding one | It reproduces `bt_mesh_compute_vertex_normals` step for step: Newell's normal out of a float32 scratch, summed face-then-corner, scaled by a reciprocal rather than divided. Four of the five fixtures went back to byte-identical, and the one that moves is the one with a real seam in it. |
+| 6 | The UV-chart gate asserted 24 shipped vertices and got 20 | The fixture, not the builder. With every face charted `0..1`, two of a corner's three charts hand it the same coordinate — they *are* one wedge and 20 is right. Each face into its own sixth of an atlas, as a real one would be. |
+| 7 | The seam identity test keys on position, which a creased mesh is entitled to break: two frames at one point is what a hard edge **is** | Said so where the test is, and asked the creased form of the question separately — a point of a box ships at most one frame per plane it touches, over the whole DAG. |
+| 8 | The scattered-cube test expected fewer than 40 leaves and got exactly 40 | Not a regression to hide: a cube is eight vertices and twenty-four shading vertices, and 4,800 wedges cannot pack below 38 clusters. The expectation carries the arithmetic now. |
+| 9 | **A third place counting the wrong thing**, found by going looking for it after the first two: `vgeo_build_group_step`'s overshoot heuristic divides `topology.vertices.count()` by the meshlet vertex ceiling to decide how far to tighten its target | `bt_wedges_live_count`. Only a heuristic — the gate is the re-cut's own cluster count — but one that reads low at every crease, so the step aims at a target it has already missed and can give up a group it could have simplified. The lesson is the pattern rather than the line: **every ceiling that says "vertices" means wedges**, and there were three. |
+| 10 | The cost model and the collapse disagreed about a faceless edge. `reduce_pair_attributes` unioned *everything* into one group; `carry_wedges` merged only the victim's wedges into the survivor's first, leaving the survivor's others alone | The cost model follows the collapse. It is 0.1% of collapses and a heuristic either way, but a price that is not the price of the collapse that happens is a bug waiting for someone to trust it. |
+| 11 | **A timing harness read a 1.57x regression that did not exist.** It built its sphere by hand and never called `vgeo_normalize_source`, so the mesh kept its raw wrap seam and its degenerate poles — and the two trees then built *different DAGs*, 39 levels against 19. It was comparing two different builds and reporting the difference as a cost | Through the real path: **13 levels and 1,710 clusters on both**, median 2,294 ms against 2,405, and identical retained heap. Which is the same +3 to 5% the Zorah conversion measures over 3,095,102 triangles. The rule the §6.1 review wrote — take a timing reading at every stage — needs a second half: *take it through the pipeline the asset goes through*, or the reading is of something else. |
+
+`check-types` at budget: declarations emit clean, the consumer program reports 19, all in the
+documented set, none in a file this touched.

package/src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.d.ts

@@ -6,20 +6,36 @@
  */
 export class VGeoBuildOptions {
     /**
-     * Which codec page blobs are stored under — {@link VGEO_CODEC_RAW} or {@link VGEO_CODEC_LZ4}.
-     * Compressed by default, and there is no case where turning it off makes a file smaller: the
-     * encoder stores a page raw whenever compressing it would not shrink it, per page.
+     * Which codec page blobs are stored under — {@link VGEO_CODEC_RAW}, {@link VGEO_CODEC_LZ4} or
+     * {@link VGEO_CODEC_DEFLATE}. Compressed by default, and there is no case where turning it off
+     * makes a file smaller: the encoder stores a page raw whenever compressing it would not shrink
+     * it, per page.
      *
-     * What it costs a reader is one LZ4 block decode per page installed, into the buffer the page
-     * was going to be copied into anyway. What it saves is transfer and disk on every fetch of
-     * every page, forever.
+     * What it costs a reader is one block decode per page installed, into the buffer the page was
+     * going to be copied into anyway. What it saves is transfer and disk on every fetch of every
+     * page, forever.
+     *
+     * **Deflate, because a build happens once and a fetch happens forever.** It is the denser of
+     * the two compressing codecs — 1.369x against LZ4's 1.295x over the pages of a 240x120 torus,
+     * 1.48x against 1.38x over a 6,016-triangle sphere — and the bytes it saves are saved on every
+     * fetch of every page by every client, for the life of the asset. What it costs is decode:
+     * 126 MB/s of decoded output against LZ4's 562, about four and a half times, and that lands on
+     * the residency path where it is the arrival cost of a page. `VGEO_CODEC_LZ4` is the setting for a
+     * container whose pages arrive while someone is looking at it, and it is one line away.
+     *
+     * Choosing it here is a choice about *readers*, not about the format: a codec id is a per-asset
+     * capability gate (`VGEO_FORMAT.md` §5), so a container built under this default opens only in
+     * a reader that carries the deflate decoder. `format_version` does not move, and an older
+     * reader refuses the asset rather than misreading it.
      *
      * @type {number}
      */
     codec: number;
     /**
      * How hard the codec looks for matches, from {@link LZ4_LEVEL}. Nine by default, which is the
-     * top of the reference's hash-chain levels.
+     * top of the reference's hash-chain levels. **LZ4 only, and the default codec is not LZ4** —
+     * `CompressionStream` exposes no level, so this does nothing at all unless {@link codec} was
+     * set to {@link VGEO_CODEC_LZ4}.
      *
      * **It changes nothing about the file.** Every level writes the same LZ4 block format, so a
      * container built at any of them reads in every build of the reader that exists; the level is
@@ -65,6 +81,19 @@ export class VGeoBuildOptions {
      * @type {number}
      */
     weld_ratio: number;
+    /**
+     * How far two triangles may turn across a shared edge before a **synthesized** normal is split
+     * there rather than averaged, in degrees. See {@link VGEO_CREASE_ANGLE}, which is where the
+     * default and the measurement behind it live.
+     *
+     * A build option rather than only a constant because it is the one number in this work that is a
+     * judgement about content rather than a consequence of arithmetic: a source of hard-surface
+     * props and a source of organic scans want different answers, and a conversion should be able to
+     * say which it has.
+     *
+     * @type {number}
+     */
+    crease_angle: number;
     /**
      * Decoded bytes per page, as a **hard cap**: no page of the asset exceeds it, and the container
      * says so with a feature bit a runtime can require (`VGEO_FORMAT.md` §11.14). That is what makes
@@ -81,6 +110,27 @@ export class VGeoBuildOptions {
      * @type {number}
      */
     nominal_page_size: number;
+    /**
+     * How much a full unit of each shading channel is worth in object-space position error, as a
+     * **fraction of the geometry's own bounding-box diagonal** — one entry per
+     * {@link VGEO_ATTRIBUTES} channel, position's ignored.
+     *
+     * This is the number that makes the simplifier's metric mean anything. An attribute's gradient
+     * is *attribute per length*, so the error it contributes is dimensionless while the geometric
+     * error beside it is a squared length; adding them without saying how they compare would let the
+     * arbitrary range a channel happens to use decide how much the surface is allowed to move. The
+     * weight is that statement, and {@link vgeo_resolve_attribute_weights} is where it is made.
+     *
+     * A ratio rather than a distance for the same reason {@link weld_ratio} is: a conversion is many
+     * geometries at many sizes, and a fixed distance right for a doorknob is wrong for a cathedral.
+     *
+     * The defaults are {@link VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS}, which says what they were
+     * measured against. Raising one buys fidelity in that channel at the price of geometric error,
+     * and the exchange rate is exactly what the number says it is.
+     *
+     * @type {number[]}
+     */
+    attribute_weight_ratios: number[];
     /**
      * @type {VGeoLevelOptions}
      */

package/src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VGeoBuildOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH;IACI;;;;;;;;;;OAUG;IACH,OAFU,MAAM,CAEO;IAEvB;;;;;;;;;;;;;;;;OAgBG;IACH,aAFU,MAAM,CAEmB;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAFU,MAAM,CAEE;IAElB;;;;;;;;;;;;;;OAcG;IACH,mBAFU,MAAM,CAE2B;IAE3C;;OAEG;IACH,eAFU,gBAAgB,CAEa;CAC1C;iCA7FgC,6BAA6B"}
+{"version":3,"file":"VGeoBuildOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH;IACI;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAFU,MAAM,CAEW;IAE3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAFU,MAAM,CAEmB;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAFU,MAAM,CAEE;IAElB;;;;;;;;;;;OAWG;IACH,cAFU,MAAM,CAEiB;IAEjC;;;;;;;;;;;;;;OAcG;IACH,mBAFU,MAAM,CAE2B;IAE3C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,yBAFU,MAAM,EAAE,CAEqD;IAEvE;;OAEG;IACH,eAFU,gBAAgB,CAEa;CAC1C;iCAjJgC,6BAA6B"}

package/src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js

@@ -1,5 +1,7 @@
+import { VGEO_CREASE_ANGLE } from "./mesh/VGEO_CREASE_ANGLE.js";
 import { LZ4_LEVEL } from "../../../../../core/binary/lz4/LZ4_LEVEL.js";
-import { VGEO_CODEC_LZ4 } from "../format/frame/VGEO_CODEC_LZ4.js";
+import { VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS } from "./mesh/VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS.js";
+import { VGEO_CODEC_DEFLATE } from "../format/frame/VGEO_CODEC_DEFLATE.js";
 import { VGEO_DEFAULT_PAGE_SIZE } from "../format/page/VGEO_DEFAULT_PAGE_SIZE.js";
 import { VGeoLevelOptions } from "./level/VGeoLevelOptions.js";
 
@@ -11,21 +13,37 @@ import { VGeoLevelOptions } from "./level/VGeoLevelOptions.js";
  */
 export class VGeoBuildOptions {
     /**
-     * Which codec page blobs are stored under — {@link VGEO_CODEC_RAW} or {@link VGEO_CODEC_LZ4}.
-     * Compressed by default, and there is no case where turning it off makes a file smaller: the
-     * encoder stores a page raw whenever compressing it would not shrink it, per page.
+     * Which codec page blobs are stored under — {@link VGEO_CODEC_RAW}, {@link VGEO_CODEC_LZ4} or
+     * {@link VGEO_CODEC_DEFLATE}. Compressed by default, and there is no case where turning it off
+     * makes a file smaller: the encoder stores a page raw whenever compressing it would not shrink
+     * it, per page.
      *
-     * What it costs a reader is one LZ4 block decode per page installed, into the buffer the page
-     * was going to be copied into anyway. What it saves is transfer and disk on every fetch of
-     * every page, forever.
+     * What it costs a reader is one block decode per page installed, into the buffer the page was
+     * going to be copied into anyway. What it saves is transfer and disk on every fetch of every
+     * page, forever.
+     *
+     * **Deflate, because a build happens once and a fetch happens forever.** It is the denser of
+     * the two compressing codecs — 1.369x against LZ4's 1.295x over the pages of a 240x120 torus,
+     * 1.48x against 1.38x over a 6,016-triangle sphere — and the bytes it saves are saved on every
+     * fetch of every page by every client, for the life of the asset. What it costs is decode:
+     * 126 MB/s of decoded output against LZ4's 562, about four and a half times, and that lands on
+     * the residency path where it is the arrival cost of a page. `VGEO_CODEC_LZ4` is the setting for a
+     * container whose pages arrive while someone is looking at it, and it is one line away.
+     *
+     * Choosing it here is a choice about *readers*, not about the format: a codec id is a per-asset
+     * capability gate (`VGEO_FORMAT.md` §5), so a container built under this default opens only in
+     * a reader that carries the deflate decoder. `format_version` does not move, and an older
+     * reader refuses the asset rather than misreading it.
      *
      * @type {number}
      */
-    codec = VGEO_CODEC_LZ4;
+    codec = VGEO_CODEC_DEFLATE;
 
     /**
      * How hard the codec looks for matches, from {@link LZ4_LEVEL}. Nine by default, which is the
-     * top of the reference's hash-chain levels.
+     * top of the reference's hash-chain levels. **LZ4 only, and the default codec is not LZ4** —
+     * `CompressionStream` exposes no level, so this does nothing at all unless {@link codec} was
+     * set to {@link VGEO_CODEC_LZ4}.
      *
      * **It changes nothing about the file.** Every level writes the same LZ4 block format, so a
      * container built at any of them reads in every build of the reader that exists; the level is
@@ -73,6 +91,20 @@ export class VGeoBuildOptions {
      */
     weld_ratio = 1e-5;
 
+    /**
+     * How far two triangles may turn across a shared edge before a **synthesized** normal is split
+     * there rather than averaged, in degrees. See {@link VGEO_CREASE_ANGLE}, which is where the
+     * default and the measurement behind it live.
+     *
+     * A build option rather than only a constant because it is the one number in this work that is a
+     * judgement about content rather than a consequence of arithmetic: a source of hard-surface
+     * props and a source of organic scans want different answers, and a conversion should be able to
+     * say which it has.
+     *
+     * @type {number}
+     */
+    crease_angle = VGEO_CREASE_ANGLE;
+
     /**
      * Decoded bytes per page, as a **hard cap**: no page of the asset exceeds it, and the container
      * says so with a feature bit a runtime can require (`VGEO_FORMAT.md` §11.14). That is what makes
@@ -90,6 +122,28 @@ export class VGeoBuildOptions {
      */
     nominal_page_size = VGEO_DEFAULT_PAGE_SIZE;
 
+    /**
+     * How much a full unit of each shading channel is worth in object-space position error, as a
+     * **fraction of the geometry's own bounding-box diagonal** — one entry per
+     * {@link VGEO_ATTRIBUTES} channel, position's ignored.
+     *
+     * This is the number that makes the simplifier's metric mean anything. An attribute's gradient
+     * is *attribute per length*, so the error it contributes is dimensionless while the geometric
+     * error beside it is a squared length; adding them without saying how they compare would let the
+     * arbitrary range a channel happens to use decide how much the surface is allowed to move. The
+     * weight is that statement, and {@link vgeo_resolve_attribute_weights} is where it is made.
+     *
+     * A ratio rather than a distance for the same reason {@link weld_ratio} is: a conversion is many
+     * geometries at many sizes, and a fixed distance right for a doorknob is wrong for a cathedral.
+     *
+     * The defaults are {@link VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS}, which says what they were
+     * measured against. Raising one buys fidelity in that channel at the price of geometric error,
+     * and the exchange rate is exactly what the number says it is.
+     *
+     * @type {number[]}
+     */
+    attribute_weight_ratios = VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS.slice();
+
     /**
      * @type {VGeoLevelOptions}
      */

package/src/shade/renderer/geometry/virtual/build/level/VGeoContribution.d.ts

@@ -0,0 +1,40 @@
+/**
+ * One cluster's geometry expressed against the frontier it came out of, which is what lets the next
+ * frontier be stitched from a mixture of freshly simplified clusters and untouched ones.
+ *
+ * Produced by `vgeo_try_repack`, `vgeo_build_group_step` and `vgeo_build_levels` — the last for
+ * the clusters a round left alone — and consumed by `vgeo_stitch_frontier`, which is the only
+ * thing that ever reads one.
+ */
+type VGeoContribution = {
+    positions: Float32Array;
+    /**
+     * local to {@link positions }
+     */
+    indices: Uint32Array;
+    /**
+     * ids in the mesh {@link topology } belongs to; not
+     * unique, because there is one entry per *wedge* and a seam vertex is several
+     */
+    local_vertex_ids: Uint32Array;
+    /**
+     * the same vertices, named in the frontier's mesh
+     */
+    source_vertex_ids: Uint32Array;
+    /**
+     * one corner of {@link topology } per entry, which is where
+     * that entry's appearance is read from — a vertex alone does not address it
+     */
+    attribute_ids: Uint32Array;
+    /**
+     * the wedge each entry is, named in the frontier's mesh,
+     * which is how its accumulated attribute quadric follows it across the seam
+     */
+    source_wedge_ids: Uint32Array;
+    /**
+     * the mesh {@link local_vertex_ids } name vertices of, whose
+     * loop data block holds their attributes
+     */
+    topology: BinaryTopology;
+};
+//# sourceMappingURL=VGeoContribution.d.ts.map

package/src/shade/renderer/geometry/virtual/build/level/VGeoContribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoContribution.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/VGeoContribution.js"],"names":[],"mappings":";;;;;;;;;eASc,YAAY;;;;aACZ,WAAW;;;;;sBACX,WAAW;;;;uBAEX,WAAW;;;;;mBACX,WAAW;;;;;sBAEX,WAAW"}

package/src/shade/renderer/geometry/virtual/build/level/VGeoContribution.js

@@ -0,0 +1,24 @@
+/**
+ * One cluster's geometry expressed against the frontier it came out of, which is what lets the next
+ * frontier be stitched from a mixture of freshly simplified clusters and untouched ones.
+ *
+ * Produced by `vgeo_try_repack`, `vgeo_build_group_step` and `vgeo_build_levels` — the last for
+ * the clusters a round left alone — and consumed by `vgeo_stitch_frontier`, which is the only
+ * thing that ever reads one.
+ *
+ * @typedef {object} VGeoContribution
+ * @property {Float32Array} positions
+ * @property {Uint32Array} indices local to {@link positions}
+ * @property {Uint32Array} local_vertex_ids ids in the mesh {@link topology} belongs to; not
+ *     unique, because there is one entry per *wedge* and a seam vertex is several
+ * @property {Uint32Array} source_vertex_ids the same vertices, named in the frontier's mesh
+ * @property {Uint32Array} attribute_ids one corner of {@link topology} per entry, which is where
+ *     that entry's appearance is read from — a vertex alone does not address it
+ * @property {Uint32Array} source_wedge_ids the wedge each entry is, named in the frontier's mesh,
+ *     which is how its accumulated attribute quadric follows it across the seam
+ * @property {BinaryTopology} topology the mesh {@link local_vertex_ids} name vertices of, whose
+ *     loop data block holds their attributes
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */