@woosh/meep-engine 3.1.0 → 3.3.0

package/src/REVIEW_2026_08_06/geom-3d.md

@@ -1,117 +1,117 @@
-# Correctness review — `core/geom/3d/`
-
-Scope: everything under `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/`.
-Excluded per brief: `core/geom/2d/`, loose files in `core/geom/`, `editor/`, `prototype*.js`,
-`*.spec.js` (evidence only), and the already-fixed/known-good items listed in the brief.
-
-## Tree survey (what was covered)
-
-~800 `.js` files. Roughly half are thin `@deprecated` re-export shims for the camelCase→snake_case
-rename; those were checked and dismissed.
-
-Directories read in depth (priority order from the brief):
-
-| area | dir | files w/o adjacent spec (sampled/read) |
-|---|---|---|
-| half-edge / topology | `topology/**` (233 files) | `bt_loop_kill`, `bt_mesh_fill_small_holes`, `bt_mesh_from_unindexed_geometry`, `edge/bt_edge_get_or_create`, `edge/bt_edge_kill`, `edge/bt_edge_swap_vertex_slots`, `edge/bt_kill_only_edge`, `face/bt_face_kill`, `face/bt_kill_only_face`, `vertex/bt_vertex_kill`, `vertex/bt_vertex_kill_only`, `query/bt_collect_boundary_segments`, `query/bt_edge_is_boundary`, `query/bt_face_get_edge_adjacent_faces`, `query/bt_face_get_shared_loop`, `query/bt_face_get_vertex_adjacent_faces`, `query/bt_mesh_count_edge_faces`, `query/bt_mesh_is_closed`, `query/bt_mesh_is_manifold`, `query/bt_mesh_build_boundary_euclidean_distance_field`, all of `topology/simplify/**` except 4, all of `topology/query/**`, `topology/three/**`, `topology/util/**` |
-| UV atlas / LSCM / packing | `atlas/**` (39 files) | `atlas_generate`, `atlas_extract_chart`, `Chart`, `atlas_write_chart_uvs`(spec'd), `data/atlas_build_edge_dihedrals`, `data/atlas_build_edge_lengths`, `data/atlas_build_face_areas`, `param/atlas_chart_param_validity`, `param/atlas_chart_parameterize_ortho`, `param/atlas_chart_stretch_metric`, `pack/ChartPlacement`, `segment/RegionGraph`, `segment/atlas_build_region_graph` |
-| triangulation | `polygon/**`, `topology/.../face/bt_face_triangulate`, `bt_mesh_triangulate` | `polygon3_compute_normal`, `bt_mesh_triangulate` |
-| convex hull | no 3D hull constructor exists in this tree — only `shape/ConvexHullShape3D` (already-fixed item) | — |
-| mesh queries / sampling | `triangle/**`, `query/bt_mesh_sample_interior_grid_points`, `shape/util/**` | `tri3_area`, `tri3_compute_normal`, `tri3_compute_plane_side`, `tri3_incenter`, `tri3_intersects_clipping_volume`, `tri3_mesh_compute_signed_volume`, `tri3_ray_intersection_barycentric_edge`, `tri3_ray_intersection_indexed`, `shape/util/shape3_voxelize_to_grid`, `shape/util/compute_signed_distance_gradient_by_sampling` |
-| simplification / welding | `topology/simplify/**`, `io/vertex/bt_merge_vertices_by_distance`, `io/edge/bt_mesh_fuse_duplicate_edges` | `compute_edge_collapse_cost`, `compute_face_normal_change_dot_product`, `build_vertex_quadrics`, `apply_border_penalty_to_vertex_quadrics`, `compute_edge_collapse_cost_quadric`, `deep_copy_vertex_quadrics`, `partial_edge_collapse`, `collapse_edge`, `edge_collapse_quadratic`, `EdgeCollapseCandidate`, `tm_edge_collapse_is_degenerate_flip`, `simplifyTopoMesh`, `simplifyTopoMesh2` |
-| GJK / MPR | `gjk/**` | `minkowski_support` (mpr, gjk, gjk_epa_penetration have specs) |
-| encodings / misc | `normal/**`, `morton/**`, `equirectangular/**`, `SurfacePoint3`, `tetrahedra/delaunay/**` | spot-checked |
-
-Checked and found clean (no finding): `bt_edge_split` (radial + disk rewiring verified end-to-end,
-both halves get one loop per original face), `bt_edge_create`/`bt_disk_edge_add`/`bt_disk_edge_remove`
-self-loop convention, `bt_mesh_compact` (remap/patch/compact/truncate ordering), `bt_face_poke`
-fan wiring, `bt_face_triangulate` ear replay (`_ring_prev` ↔ `loop_read_prev` correspondence holds
-for both the forward and backward ear orderings, and the emitted mesh winding matches the source
-face), `bt_mesh_walk_boundary_loops` + `order_cycle_from` direction seeding (the `edges_at_v[0]`
-tiebreak provably resolves to `cycle[0]`, so the new hole face winds opposite the existing loop),
-`polygon3_triangulate` axis-drop table (all six ±x/±y/±z cases preserve CCW-from-+normal),
-`polygon3_compute_normal`, `tri3_closest_point_barycentric` (all seven Voronoi regions and the
-collinear-degenerate paths traced numerically), `mpr.js` portal discovery (both plane tests
-algebraically identical to libccd's `det[v0,v1,v3] < 0` / `det[v0,v2,v3] > 0` after expanding the
-relative-to-V0 form) and `expandPortal` branch table, `matrix_symmetric_3x3_eigen` column/ascending
-convention used by `fit_plane_basis`, `min_area_rect_2d` angle convention vs
-`rotate_uv_to_min_area_box`, `atlas_pack_charts` rot-1 UV remap (transpose ↔ `(x+tv, y+tu)`
-verified), the skyline/bitmap growth loops, `atlas_segment_charts` vs `atlas_segment_charts_atomic`
-boundary/seam arithmetic (both reduce to `chart_boundary + perimeter − 2·shared`),
-`encode_unit_to_octahedron`/`decode_octahedron_to_unit` fold (pre-fold abs values used on both
-sides), `topo_mesh_to_three_buffer_geometry` index-width thresholds (no Uint16 overflow),
-`Quadric3.optimize` aliasing and symmetric-inverse index layout, `v3_normalize_array` zero guard.
-
----
-
-## Findings
-
-### GEOM3-1 Edge-collapse flip rejection degenerates into "is the face normal pointing down?"
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/simplify/compute_edge_collapse_cost.js:43-54` (with `compute_face_normal_change_dot_product.js:29-47` and `tri3_compute_normal.js:40-46`)
-- **Defect**: The flip test loops over **every** face of the victim, including the 1–2 faces that contain *both* endpoints of the collapsing edge — the faces the collapse deletes. Substituting `victim → target` in those faces produces a triangle with two identical vertices, so `tri3_compute_normal` takes its zero-area branch and writes the documented "arbitrary invalid result" `(0, 1, 0)`. The dot product against the real face normal is therefore just `original_normal.y`, and the whole test collapses to `original_normal.y >= 0`. The sibling helper `tm_edge_collapse_is_degenerate_flip.js:26-29` skips exactly these faces, confirming the intent.
-- **Failure scenario**: A `TopoMesh` quad in the XZ plane facing **down** — A(0,0,0), B(1,0,0), C(1,0,1), D(0,0,1), triangles (A,B,C) and (A,C,D) wound so both normals are `(0,-1,0)`. Call `compute_edge_collapse_cost(A, C, edge_AC, quadrics)`. Face ABC contains both A and C, so substitution gives (C,B,C): `vCB = C−B`, `vAB = C−B`, cross `= 0`, `l_sqr === 0` → normal `(0,1,0)`. `dot((0,1,0), (0,-1,0)) = -1 < 0` → **produced `Number.MAX_VALUE`**; expected the ordinary quadric cost (0 here, plus the border constants). The reverse direction `compute_edge_collapse_cost(C, A, …)` hits the same faces and also returns `MAX_VALUE`, so `EdgeCollapseCandidate.update` (EdgeCollapseCandidate.js:117-140) records `MAX_VALUE` for the edge in both orientations. Flip the same quad to face up (normals `(0,1,0)`) and the dot becomes `+1` and the edge is accepted. Net effect on a real model: `simplifyTopoMesh` refuses to collapse any edge whose adjacent face normal has a negative Y component — on a closed mesh (cube, sphere, rock) that is the entire downward-facing half, which is simply never decimated while the upward-facing half is.
-- **Fix**: In the loop at `compute_edge_collapse_cost.js:43`, skip faces that contain `target` as well as `victim` (they are deleted by the collapse), mirroring `tm_edge_collapse_is_degenerate_flip.js:26-29`:
-  ```js
-  if (face.containsVertex(target)) { continue; }
-  ```
-- **Confidence**: Confirmed
-
-### GEOM3-2 Zero-area faces inject a fabricated `(0,1,0)` plane into vertex quadrics
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadrics.js:70-91`; same defect in `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/simplify/quadratic/build_vertex_quadrics.js:12-30`
-- **Defect**: Both quadric builders derive the supporting plane from `tri3_compute_normal`, which for a zero-area triangle writes the sentinel `(0, 1, 0)` (`tri3_compute_normal.js:40-46`, "degenerate triangle, provide arbitrary invalid result"). Neither builder tests for that case, so the sentinel is treated as a genuine plane and accumulated onto all three vertices at full weight. A degenerate face carries no geometric constraint and must contribute a zero quadric. (`build_vertex_quadrics` would be saved by area weighting, but `use_triangle_area` defaults to `false`; `bt_mesh_compute_vertex_quadrics` has no area weighting at all.)
-- **Failure scenario**: A sheet lying in the plane `z = 0` that also contains one collinear triangle `T = (0,0,0), (1,0,0), (2,0,0)` — a routine artifact after `bt_merge_vertices_by_distance` welds colocal points, or from an imported model. For `T`: `vCB = (1,0,0)`, `vAB = (-1,0,0)`, cross `= 0` → normal `(0,1,0)`, `d = -dot((0,1,0),(0,0,0)) = 0`, i.e. the plane `y = 0`, added to the quadrics of `(0,0,0)`, `(1,0,0)`, `(2,0,0)`. Now score the collapse of edge `B=(1,0,0) — E=(1,1,0)` at target `(1, 0.5, 0)` (`evaluate_edge_collapse`, `bt_mesh_simplify.js:110-115`): every real supporting plane is `z = 0` and the target lies in it, so the true cost is **0**; the fabricated plane contributes `0.5² = 0.25`, so the **produced cost is 0.25**. The bogus plane also raises the rank of the combined tensor, so `Quadric3.optimize` succeeds where it should have reported singular and pulls the survivor off the sheet toward `y = 0`.
-- **Fix**: Detect the degeneracy where the plane is built rather than relying on `tri3_compute_normal`'s sentinel — compute the raw cross product and `continue` when its squared length is 0 (`bt_mesh_compute_vertex_quadrics.js` before line 87; `quadric_set_from_face` in `build_vertex_quadrics.js` before line 29).
-- **Confidence**: Confirmed
-
-### GEOM3-3 `bt_vertex_replace` silently rewrites edge 0 when a vertex has more than 1024 incident edges
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/struct/binary/io/vertex/bt_vertex_replace.js:6,40-42,57-58`
-- **Defect**: The victim's disk cycle is snapshotted into the module-static `const scratch_edges = new Uint32Array(1024)`. The bound is only checked by an `assert` (compiled out in production). Past 1024, `scratch_edges[edges_to_move_count++] = curr_e` is a silently-dropped out-of-range typed-array store while the counter keeps incrementing, so stage 3 reads `scratch_edges[i] === undefined` for `i >= 1024`. That `undefined` then flows into `mesh.edge_read_loop(undefined)` → `element_address(undefined)` = `28 * undefined` = `NaN` → `data_view.getUint32(NaN)`, and `DataView` coerces the index with `ToIndex`, which maps `NaN` to **0**. So every over-budget iteration reads *and rewrites* **edge 0**.
-- **Failure scenario**: Take a vertex `v` with 1200 incident edges and call `bt_vertex_replace(mesh, v, r)` (directly, or via `bt_edge_collapse` → `bt_mesh_simplify`; survivor valence grows monotonically with each collapse, so decimating a ≥200k-triangle mesh down to a few hundred faces reaches this routinely). Produced: edges 0..1023 are correctly re-pointed; for the remaining 176 iterations the code instead sets `edge 0`'s `vertex1`/`vertex2` to `r` and splices edge 0 into `r`'s disk cycle repeatedly, while edges 1024..1199 keep pointing at `v` — which `bt_edge_collapse` then releases via `bt_vertex_kill`, leaving 176 edges referencing a freed vertex. Expected: all 1200 edges re-pointed and edge 0 untouched.
-- **Fix**: Grow `scratch_edges` on demand before the write (`if (edges_to_move_count >= scratch_edges.length) { scratch_edges = grow(...) }` with `let` instead of `const`), or count the disk cycle first and size the buffer to the valence.
-- **Confidence**: Likely (the `NaN → index 0` mechanism is Confirmed; reaching valence > 1024 depends on the input mesh / decimation ratio)
-
-### GEOM3-4 `atlas_extract_chart` marks chart-interior edges as boundary on non-manifold edges
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/atlas/atlas_extract_chart.js:84-91`
-- **Defect**: The boundary test consults only the single `loop_read_radial_next` neighbour: `is_boundary = opp === li || face_chart[loop_read_face(opp)] !== chart_id`. On an edge with three or more faces the answer depends on where the loop sits in the radial cycle, so an edge that is interior to the chart can be recorded as a chart boundary. The correct predicate is "no *other* loop on the radial cycle belongs to this chart".
-- **Failure scenario**: Edge `e` shared by faces A, B (both in chart 0) and C (chart 1), radial cycle A→B→C→A. For A's loop, `radial_next` is B (chart 0) → not boundary. For B's loop, `radial_next` is C (chart 1) → **boundary**, so `chart.boundary_edges` gains the pair `(vB0, vB1)` for an edge that is interior to chart 0. Downstream: the extra edge gives one of its endpoints two outgoing boundary edges, so `atlas_chart_parameterize_bff` hits `if (succ[a] !== -1) return false` (`atlas_chart_parameterize_bff.js:102`) and rejects a chart that really is a disk; and `atlas_chart_param_validity` tests that interior segment for crossings against the true outline, so a bijective LSCM layout can be reported `self_intersects: true` and be needlessly exploded by `atlas_piecewise_resegment`. Expected: `boundary_edges` contains only edges with no in-chart face across them.
-- **Fix**: Walk the full radial cycle from `li` and treat the edge as boundary only if no other loop's face has `face_chart === chart_id`.
-- **Confidence**: Confirmed (for non-manifold input)
-
-### GEOM3-5 `build_triangle_adjacency` keeps the *last* pairing, not the first, on a non-manifold edge
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/atlas/param/atlas_piecewise_resegment.js:26-33`
-- **Defect**: `edge_map` retains the first slot forever, so the third and later triangles on an edge each overwrite `tri_neighbor[first_slot]`. The result is an asymmetric adjacency graph, contradicting the function's own doc ("a non-manifold edge keeps the first pairing").
-- **Failure scenario**: Triangles `t1, t2, t3` share an edge, visited in that order. After `t2`: `tri_neighbor[slot1] = t2`, `tri_neighbor[slot2] = t1`. After `t3`: `tri_neighbor[slot3] = t1` and `tri_neighbor[slot1] = t3` — overwriting `t2`. Now grow a sub-chart containing `{t1, t2}`: `build_subchart` reads `tri_neighbor[slot1] = t3`, which is not in `member`, so it pushes that edge into `sub.boundary_edges` even though `t2` sits across it. Produced: `is_ortho_valid` runs the O(b²) crossing test on an interior edge and can reject a legitimate growth step, splitting the chart into more pieces than necessary; and `t2 → t1` while `t1 → t3` makes the traversal non-symmetric. Expected: `tri_neighbor[slot1] === t2` and `tri_neighbor[slot2] === t1`, with `t3`'s slot left at `-1`.
-- **Fix**: `edge_map.delete(key)` after the first pairing is consumed, so a third triangle on the same edge starts a fresh (or no) pairing instead of clobbering `slot1`.
-- **Confidence**: Confirmed (for non-manifold input)
-
-### GEOM3-6 Mesh edits allocate through the raw pools, bypassing the data-pool capacity sync
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/struct/binary/io/face/bt_face_poke.js:53,83`; also `edge/bt_edge_split.js:73,146`, `face/bt_face_triangulate.js:61`, `bt_mesh_close_boundary_holes.js:112`, `bt_mesh_fill_small_holes.js:80`, `bt_mesh_face_decouple.js:85`, `edge/bt_edge_create.js:71`
-- **Defect**: These call `mesh.vertices.allocate()` / `mesh.faces.allocate()` / `mesh.edges.allocate()` directly instead of `mesh.vertex_create()` / `face_create()` / `edge_create()`. The `*_create()` wrappers exist precisely to run `__*_data_pool?.ensure_capacity(id + 1)` (`BinaryTopology.js:635-680`). The same functions *do* use `mesh.loop_create()` for their loops, so the omission is inconsistent within a single function body — this is not the documented "caller keeps `__size` in sync" contract, it is a missing capacity grow that leaves the data buffer physically too short.
-- **Failure scenario**: `topo.create_face_data(4)` on a 100-face mesh → the data pool is sized by `allocate_continuous(100)`, giving `capacity = 128` and a 512-byte buffer (128 words). Call `bt_face_poke` on a 40-gon: it allocates 39 new faces, ids 100…138. `face_data.element_word(138)` is 138, but `face_data.data_uint32.length` is 128. Produced: writes at index 138 are silently discarded and reads return `undefined` (and `NaN` once arithmetic touches them). Expected: the data pool grows so face 138 is addressable, exactly as `mesh.loop_create()` already guarantees for the loops created in the same call.
-- **Fix**: Use `mesh.vertex_create()` / `mesh.face_create()` / `mesh.edge_create()` in these seven sites.
-- **Confidence**: Confirmed
-
-### GEOM3-7 `atlas_generate` reports a `chart_count` that undercounts the charts it returns
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/atlas/atlas_generate.js:36-38` (value originates at `atlas_compute_charts.js:187`)
-- **Defect**: `atlas_compute_charts` returns the *segmentation* chart count alongside `face_chart` — self-consistent there, since `face_chart` holds segmentation ids. `atlas_generate` forwards that number as `chart_count` but does **not** return `face_chart`, so the only array the caller has is `charts`, whose length differs whenever `atlas_piecewise_resegment` fires (each failed chart becomes N sub-charts, all appended).
-- **Failure scenario**: A mesh whose segmentation produces 4 charts, one of which fails ortho, LSCM and BFF and is re-segmented into 7 pieces. `atlas_generate` returns `charts.length === 10` but `chart_count === 4`. A caller sizing a per-chart array from `chart_count` (the obvious reading of the field) under-allocates by 6 and drops six charts' metadata. Expected: `chart_count === charts.length` for the value returned next to `charts`.
-- **Fix**: In `atlas_generate`, return `chart_count: computed.charts.length` (or return `face_chart` too and document the field as the segmentation count).
-- **Confidence**: Confirmed
-
----
-
-## Notable non-findings (checked, deliberately not reported)
-
-- `tri3_ray_intersection_barycentric_edge` returns `true` for negative `t` (hit behind the origin). Both in-tree BVH callers (`ebvh_geometry_query_nearest_triangle_ray.js:127`, `ebvh_geometry_query_any_triangle_ray.js:129`) and `BufferedGeometryBVH` gate on `t > min_distance`, and the function's contract is "returns the barycentric solution", so this is by design, not a defect.
-- `tri3_ray_intersection` writes an **un-normalised** normal into `result.normal`. Its only in-tree consumer (`bt_mesh_sample_interior_grid_points`) uses the boolean only. Contract ambiguity, no wrong value.
-- `bt_face_is_degenerate` uses an absolute `area² <= 1e-17` threshold, so a valid triangle with ~3e-5 edges is called degenerate. Scale-dependent tolerance rather than a logic error.
-- `compute_edge_collapse_cost.js:29` declares `normal_cost` and never assigns it, so the curvature term of the Melax cost is dead. Incomplete, but it produces no wrong value on its own (the quadric term carries the geometric error) — GEOM3-1 is the actual defect in that file.
-- `BinaryElementPool.copy` leaves `__capacity` stale when `item_size` shrinks and the existing buffer is reused (`BinaryElementPool.js:471-489`). Self-heals on the next `allocate()`; no reachable wrong value found.
-- `tetrahedral_mesh_compute_cavity`'s facet-vertex table (`k0/k1/k2`) yields the correct vertex *sets* for all four facets but the opposite *orientation* to the table in `tetrahedral_mesh_walk_towards_containing_tetrahedron`. The flip is uniform across all four facets, so it is self-consistent; without running `compute_delaunay_tetrahedral_mesh.spec.js` against the mesh's sign convention I could not construct a produced-vs-expected, so it is not reported — but it is the one place in this tree I would re-check first.
+# Correctness review — `core/geom/3d/`
+
+Scope: everything under `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/`.
+Excluded per brief: `core/geom/2d/`, loose files in `core/geom/`, `editor/`, `prototype*.js`,
+`*.spec.js` (evidence only), and the already-fixed/known-good items listed in the brief.
+
+## Tree survey (what was covered)
+
+~800 `.js` files. Roughly half are thin `@deprecated` re-export shims for the camelCase→snake_case
+rename; those were checked and dismissed.
+
+Directories read in depth (priority order from the brief):
+
+| area | dir | files w/o adjacent spec (sampled/read) |
+|---|---|---|
+| half-edge / topology | `topology/**` (233 files) | `bt_loop_kill`, `bt_mesh_fill_small_holes`, `bt_mesh_from_unindexed_geometry`, `edge/bt_edge_get_or_create`, `edge/bt_edge_kill`, `edge/bt_edge_swap_vertex_slots`, `edge/bt_kill_only_edge`, `face/bt_face_kill`, `face/bt_kill_only_face`, `vertex/bt_vertex_kill`, `vertex/bt_vertex_kill_only`, `query/bt_collect_boundary_segments`, `query/bt_edge_is_boundary`, `query/bt_face_get_edge_adjacent_faces`, `query/bt_face_get_shared_loop`, `query/bt_face_get_vertex_adjacent_faces`, `query/bt_mesh_count_edge_faces`, `query/bt_mesh_is_closed`, `query/bt_mesh_is_manifold`, `query/bt_mesh_build_boundary_euclidean_distance_field`, all of `topology/simplify/**` except 4, all of `topology/query/**`, `topology/three/**`, `topology/util/**` |
+| UV atlas / LSCM / packing | `atlas/**` (39 files) | `atlas_generate`, `atlas_extract_chart`, `Chart`, `atlas_write_chart_uvs`(spec'd), `data/atlas_build_edge_dihedrals`, `data/atlas_build_edge_lengths`, `data/atlas_build_face_areas`, `param/atlas_chart_param_validity`, `param/atlas_chart_parameterize_ortho`, `param/atlas_chart_stretch_metric`, `pack/ChartPlacement`, `segment/RegionGraph`, `segment/atlas_build_region_graph` |
+| triangulation | `polygon/**`, `topology/.../face/bt_face_triangulate`, `bt_mesh_triangulate` | `polygon3_compute_normal`, `bt_mesh_triangulate` |
+| convex hull | no 3D hull constructor exists in this tree — only `shape/ConvexHullShape3D` (already-fixed item) | — |
+| mesh queries / sampling | `triangle/**`, `query/bt_mesh_sample_interior_grid_points`, `shape/util/**` | `tri3_area`, `tri3_compute_normal`, `tri3_compute_plane_side`, `tri3_incenter`, `tri3_intersects_clipping_volume`, `tri3_mesh_compute_signed_volume`, `tri3_ray_intersection_barycentric_edge`, `tri3_ray_intersection_indexed`, `shape/util/shape3_voxelize_to_grid`, `shape/util/compute_signed_distance_gradient_by_sampling` |
+| simplification / welding | `topology/simplify/**`, `io/vertex/bt_merge_vertices_by_distance`, `io/edge/bt_mesh_fuse_duplicate_edges` | `compute_edge_collapse_cost`, `compute_face_normal_change_dot_product`, `build_vertex_quadrics`, `apply_border_penalty_to_vertex_quadrics`, `compute_edge_collapse_cost_quadric`, `deep_copy_vertex_quadrics`, `partial_edge_collapse`, `collapse_edge`, `edge_collapse_quadratic`, `EdgeCollapseCandidate`, `tm_edge_collapse_is_degenerate_flip`, `simplifyTopoMesh`, `simplifyTopoMesh2` |
+| GJK / MPR | `gjk/**` | `minkowski_support` (mpr, gjk, gjk_epa_penetration have specs) |
+| encodings / misc | `normal/**`, `morton/**`, `equirectangular/**`, `SurfacePoint3`, `tetrahedra/delaunay/**` | spot-checked |
+
+Checked and found clean (no finding): `bt_edge_split` (radial + disk rewiring verified end-to-end,
+both halves get one loop per original face), `bt_edge_create`/`bt_disk_edge_add`/`bt_disk_edge_remove`
+self-loop convention, `bt_mesh_compact` (remap/patch/compact/truncate ordering), `bt_face_poke`
+fan wiring, `bt_face_triangulate` ear replay (`_ring_prev` ↔ `loop_read_prev` correspondence holds
+for both the forward and backward ear orderings, and the emitted mesh winding matches the source
+face), `bt_mesh_walk_boundary_loops` + `order_cycle_from` direction seeding (the `edges_at_v[0]`
+tiebreak provably resolves to `cycle[0]`, so the new hole face winds opposite the existing loop),
+`polygon3_triangulate` axis-drop table (all six ±x/±y/±z cases preserve CCW-from-+normal),
+`polygon3_compute_normal`, `tri3_closest_point_barycentric` (all seven Voronoi regions and the
+collinear-degenerate paths traced numerically), `mpr.js` portal discovery (both plane tests
+algebraically identical to libccd's `det[v0,v1,v3] < 0` / `det[v0,v2,v3] > 0` after expanding the
+relative-to-V0 form) and `expandPortal` branch table, `matrix_symmetric_3x3_eigen` column/ascending
+convention used by `fit_plane_basis`, `min_area_rect_2d` angle convention vs
+`rotate_uv_to_min_area_box`, `atlas_pack_charts` rot-1 UV remap (transpose ↔ `(x+tv, y+tu)`
+verified), the skyline/bitmap growth loops, `atlas_segment_charts` vs `atlas_segment_charts_atomic`
+boundary/seam arithmetic (both reduce to `chart_boundary + perimeter − 2·shared`),
+`encode_unit_to_octahedron`/`decode_octahedron_to_unit` fold (pre-fold abs values used on both
+sides), `topo_mesh_to_three_buffer_geometry` index-width thresholds (no Uint16 overflow),
+`Quadric3.optimize` aliasing and symmetric-inverse index layout, `v3_normalize_array` zero guard.
+
+---
+
+## Findings
+
+### GEOM3-1 Edge-collapse flip rejection degenerates into "is the face normal pointing down?"
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/simplify/compute_edge_collapse_cost.js:43-54` (with `compute_face_normal_change_dot_product.js:29-47` and `tri3_compute_normal.js:40-46`)
+- **Defect**: The flip test loops over **every** face of the victim, including the 1–2 faces that contain *both* endpoints of the collapsing edge — the faces the collapse deletes. Substituting `victim → target` in those faces produces a triangle with two identical vertices, so `tri3_compute_normal` takes its zero-area branch and writes the documented "arbitrary invalid result" `(0, 1, 0)`. The dot product against the real face normal is therefore just `original_normal.y`, and the whole test collapses to `original_normal.y >= 0`. The sibling helper `tm_edge_collapse_is_degenerate_flip.js:26-29` skips exactly these faces, confirming the intent.
+- **Failure scenario**: A `TopoMesh` quad in the XZ plane facing **down** — A(0,0,0), B(1,0,0), C(1,0,1), D(0,0,1), triangles (A,B,C) and (A,C,D) wound so both normals are `(0,-1,0)`. Call `compute_edge_collapse_cost(A, C, edge_AC, quadrics)`. Face ABC contains both A and C, so substitution gives (C,B,C): `vCB = C−B`, `vAB = C−B`, cross `= 0`, `l_sqr === 0` → normal `(0,1,0)`. `dot((0,1,0), (0,-1,0)) = -1 < 0` → **produced `Number.MAX_VALUE`**; expected the ordinary quadric cost (0 here, plus the border constants). The reverse direction `compute_edge_collapse_cost(C, A, …)` hits the same faces and also returns `MAX_VALUE`, so `EdgeCollapseCandidate.update` (EdgeCollapseCandidate.js:117-140) records `MAX_VALUE` for the edge in both orientations. Flip the same quad to face up (normals `(0,1,0)`) and the dot becomes `+1` and the edge is accepted. Net effect on a real model: `simplifyTopoMesh` refuses to collapse any edge whose adjacent face normal has a negative Y component — on a closed mesh (cube, sphere, rock) that is the entire downward-facing half, which is simply never decimated while the upward-facing half is.
+- **Fix**: In the loop at `compute_edge_collapse_cost.js:43`, skip faces that contain `target` as well as `victim` (they are deleted by the collapse), mirroring `tm_edge_collapse_is_degenerate_flip.js:26-29`:
+  ```js
+  if (face.containsVertex(target)) { continue; }
+  ```
+- **Confidence**: Confirmed
+
+### GEOM3-2 Zero-area faces inject a fabricated `(0,1,0)` plane into vertex quadrics
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadrics.js:70-91`; same defect in `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/simplify/quadratic/build_vertex_quadrics.js:12-30`
+- **Defect**: Both quadric builders derive the supporting plane from `tri3_compute_normal`, which for a zero-area triangle writes the sentinel `(0, 1, 0)` (`tri3_compute_normal.js:40-46`, "degenerate triangle, provide arbitrary invalid result"). Neither builder tests for that case, so the sentinel is treated as a genuine plane and accumulated onto all three vertices at full weight. A degenerate face carries no geometric constraint and must contribute a zero quadric. (`build_vertex_quadrics` would be saved by area weighting, but `use_triangle_area` defaults to `false`; `bt_mesh_compute_vertex_quadrics` has no area weighting at all.)
+- **Failure scenario**: A sheet lying in the plane `z = 0` that also contains one collinear triangle `T = (0,0,0), (1,0,0), (2,0,0)` — a routine artifact after `bt_merge_vertices_by_distance` welds colocal points, or from an imported model. For `T`: `vCB = (1,0,0)`, `vAB = (-1,0,0)`, cross `= 0` → normal `(0,1,0)`, `d = -dot((0,1,0),(0,0,0)) = 0`, i.e. the plane `y = 0`, added to the quadrics of `(0,0,0)`, `(1,0,0)`, `(2,0,0)`. Now score the collapse of edge `B=(1,0,0) — E=(1,1,0)` at target `(1, 0.5, 0)` (`evaluate_edge_collapse`, `bt_mesh_simplify.js:110-115`): every real supporting plane is `z = 0` and the target lies in it, so the true cost is **0**; the fabricated plane contributes `0.5² = 0.25`, so the **produced cost is 0.25**. The bogus plane also raises the rank of the combined tensor, so `Quadric3.optimize` succeeds where it should have reported singular and pulls the survivor off the sheet toward `y = 0`.
+- **Fix**: Detect the degeneracy where the plane is built rather than relying on `tri3_compute_normal`'s sentinel — compute the raw cross product and `continue` when its squared length is 0 (`bt_mesh_compute_vertex_quadrics.js` before line 87; `quadric_set_from_face` in `build_vertex_quadrics.js` before line 29).
+- **Confidence**: Confirmed
+
+### GEOM3-3 `bt_vertex_replace` silently rewrites edge 0 when a vertex has more than 1024 incident edges
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/struct/binary/io/vertex/bt_vertex_replace.js:6,40-42,57-58`
+- **Defect**: The victim's disk cycle is snapshotted into the module-static `const scratch_edges = new Uint32Array(1024)`. The bound is only checked by an `assert` (compiled out in production). Past 1024, `scratch_edges[edges_to_move_count++] = curr_e` is a silently-dropped out-of-range typed-array store while the counter keeps incrementing, so stage 3 reads `scratch_edges[i] === undefined` for `i >= 1024`. That `undefined` then flows into `mesh.edge_read_loop(undefined)` → `element_address(undefined)` = `28 * undefined` = `NaN` → `data_view.getUint32(NaN)`, and `DataView` coerces the index with `ToIndex`, which maps `NaN` to **0**. So every over-budget iteration reads *and rewrites* **edge 0**.
+- **Failure scenario**: Take a vertex `v` with 1200 incident edges and call `bt_vertex_replace(mesh, v, r)` (directly, or via `bt_edge_collapse` → `bt_mesh_simplify`; survivor valence grows monotonically with each collapse, so decimating a ≥200k-triangle mesh down to a few hundred faces reaches this routinely). Produced: edges 0..1023 are correctly re-pointed; for the remaining 176 iterations the code instead sets `edge 0`'s `vertex1`/`vertex2` to `r` and splices edge 0 into `r`'s disk cycle repeatedly, while edges 1024..1199 keep pointing at `v` — which `bt_edge_collapse` then releases via `bt_vertex_kill`, leaving 176 edges referencing a freed vertex. Expected: all 1200 edges re-pointed and edge 0 untouched.
+- **Fix**: Grow `scratch_edges` on demand before the write (`if (edges_to_move_count >= scratch_edges.length) { scratch_edges = grow(...) }` with `let` instead of `const`), or count the disk cycle first and size the buffer to the valence.
+- **Confidence**: Likely (the `NaN → index 0` mechanism is Confirmed; reaching valence > 1024 depends on the input mesh / decimation ratio)
+
+### GEOM3-4 `atlas_extract_chart` marks chart-interior edges as boundary on non-manifold edges
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/atlas/atlas_extract_chart.js:84-91`
+- **Defect**: The boundary test consults only the single `loop_read_radial_next` neighbour: `is_boundary = opp === li || face_chart[loop_read_face(opp)] !== chart_id`. On an edge with three or more faces the answer depends on where the loop sits in the radial cycle, so an edge that is interior to the chart can be recorded as a chart boundary. The correct predicate is "no *other* loop on the radial cycle belongs to this chart".
+- **Failure scenario**: Edge `e` shared by faces A, B (both in chart 0) and C (chart 1), radial cycle A→B→C→A. For A's loop, `radial_next` is B (chart 0) → not boundary. For B's loop, `radial_next` is C (chart 1) → **boundary**, so `chart.boundary_edges` gains the pair `(vB0, vB1)` for an edge that is interior to chart 0. Downstream: the extra edge gives one of its endpoints two outgoing boundary edges, so `atlas_chart_parameterize_bff` hits `if (succ[a] !== -1) return false` (`atlas_chart_parameterize_bff.js:102`) and rejects a chart that really is a disk; and `atlas_chart_param_validity` tests that interior segment for crossings against the true outline, so a bijective LSCM layout can be reported `self_intersects: true` and be needlessly exploded by `atlas_piecewise_resegment`. Expected: `boundary_edges` contains only edges with no in-chart face across them.
+- **Fix**: Walk the full radial cycle from `li` and treat the edge as boundary only if no other loop's face has `face_chart === chart_id`.
+- **Confidence**: Confirmed (for non-manifold input)
+
+### GEOM3-5 `build_triangle_adjacency` keeps the *last* pairing, not the first, on a non-manifold edge
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/atlas/param/atlas_piecewise_resegment.js:26-33`
+- **Defect**: `edge_map` retains the first slot forever, so the third and later triangles on an edge each overwrite `tri_neighbor[first_slot]`. The result is an asymmetric adjacency graph, contradicting the function's own doc ("a non-manifold edge keeps the first pairing").
+- **Failure scenario**: Triangles `t1, t2, t3` share an edge, visited in that order. After `t2`: `tri_neighbor[slot1] = t2`, `tri_neighbor[slot2] = t1`. After `t3`: `tri_neighbor[slot3] = t1` and `tri_neighbor[slot1] = t3` — overwriting `t2`. Now grow a sub-chart containing `{t1, t2}`: `build_subchart` reads `tri_neighbor[slot1] = t3`, which is not in `member`, so it pushes that edge into `sub.boundary_edges` even though `t2` sits across it. Produced: `is_ortho_valid` runs the O(b²) crossing test on an interior edge and can reject a legitimate growth step, splitting the chart into more pieces than necessary; and `t2 → t1` while `t1 → t3` makes the traversal non-symmetric. Expected: `tri_neighbor[slot1] === t2` and `tri_neighbor[slot2] === t1`, with `t3`'s slot left at `-1`.
+- **Fix**: `edge_map.delete(key)` after the first pairing is consumed, so a third triangle on the same edge starts a fresh (or no) pairing instead of clobbering `slot1`.
+- **Confidence**: Confirmed (for non-manifold input)
+
+### GEOM3-6 Mesh edits allocate through the raw pools, bypassing the data-pool capacity sync
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/struct/binary/io/face/bt_face_poke.js:53,83`; also `edge/bt_edge_split.js:73,146`, `face/bt_face_triangulate.js:61`, `bt_mesh_close_boundary_holes.js:112`, `bt_mesh_fill_small_holes.js:80`, `bt_mesh_face_decouple.js:85`, `edge/bt_edge_create.js:71`
+- **Defect**: These call `mesh.vertices.allocate()` / `mesh.faces.allocate()` / `mesh.edges.allocate()` directly instead of `mesh.vertex_create()` / `face_create()` / `edge_create()`. The `*_create()` wrappers exist precisely to run `__*_data_pool?.ensure_capacity(id + 1)` (`BinaryTopology.js:635-680`). The same functions *do* use `mesh.loop_create()` for their loops, so the omission is inconsistent within a single function body — this is not the documented "caller keeps `__size` in sync" contract, it is a missing capacity grow that leaves the data buffer physically too short.
+- **Failure scenario**: `topo.create_face_data(4)` on a 100-face mesh → the data pool is sized by `allocate_continuous(100)`, giving `capacity = 128` and a 512-byte buffer (128 words). Call `bt_face_poke` on a 40-gon: it allocates 39 new faces, ids 100…138. `face_data.element_word(138)` is 138, but `face_data.data_uint32.length` is 128. Produced: writes at index 138 are silently discarded and reads return `undefined` (and `NaN` once arithmetic touches them). Expected: the data pool grows so face 138 is addressable, exactly as `mesh.loop_create()` already guarantees for the loops created in the same call.
+- **Fix**: Use `mesh.vertex_create()` / `mesh.face_create()` / `mesh.edge_create()` in these seven sites.
+- **Confidence**: Confirmed
+
+### GEOM3-7 `atlas_generate` reports a `chart_count` that undercounts the charts it returns
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/atlas/atlas_generate.js:36-38` (value originates at `atlas_compute_charts.js:187`)
+- **Defect**: `atlas_compute_charts` returns the *segmentation* chart count alongside `face_chart` — self-consistent there, since `face_chart` holds segmentation ids. `atlas_generate` forwards that number as `chart_count` but does **not** return `face_chart`, so the only array the caller has is `charts`, whose length differs whenever `atlas_piecewise_resegment` fires (each failed chart becomes N sub-charts, all appended).
+- **Failure scenario**: A mesh whose segmentation produces 4 charts, one of which fails ortho, LSCM and BFF and is re-segmented into 7 pieces. `atlas_generate` returns `charts.length === 10` but `chart_count === 4`. A caller sizing a per-chart array from `chart_count` (the obvious reading of the field) under-allocates by 6 and drops six charts' metadata. Expected: `chart_count === charts.length` for the value returned next to `charts`.
+- **Fix**: In `atlas_generate`, return `chart_count: computed.charts.length` (or return `face_chart` too and document the field as the segmentation count).
+- **Confidence**: Confirmed
+
+---
+
+## Notable non-findings (checked, deliberately not reported)
+
+- `tri3_ray_intersection_barycentric_edge` returns `true` for negative `t` (hit behind the origin). Both in-tree BVH callers (`ebvh_geometry_query_nearest_triangle_ray.js:127`, `ebvh_geometry_query_any_triangle_ray.js:129`) and `BufferedGeometryBVH` gate on `t > min_distance`, and the function's contract is "returns the barycentric solution", so this is by design, not a defect.
+- `tri3_ray_intersection` writes an **un-normalised** normal into `result.normal`. Its only in-tree consumer (`bt_mesh_sample_interior_grid_points`) uses the boolean only. Contract ambiguity, no wrong value.
+- `bt_face_is_degenerate` uses an absolute `area² <= 1e-17` threshold, so a valid triangle with ~3e-5 edges is called degenerate. Scale-dependent tolerance rather than a logic error.
+- `compute_edge_collapse_cost.js:29` declares `normal_cost` and never assigns it, so the curvature term of the Melax cost is dead. Incomplete, but it produces no wrong value on its own (the quadric term carries the geometric error) — GEOM3-1 is the actual defect in that file.
+- `BinaryElementPool.copy` leaves `__capacity` stale when `item_size` shrinks and the existing buffer is reused (`BinaryElementPool.js:471-489`). Self-heals on the next `allocate()`; no reachable wrong value found.
+- `tetrahedral_mesh_compute_cavity`'s facet-vertex table (`k0/k1/k2`) yields the correct vertex *sets* for all four facets but the opposite *orientation* to the table in `tetrahedral_mesh_walk_towards_containing_tetrahedron`. The flip is uniform across all four facets, so it is self-consistent; without running `compute_delaunay_tetrahedral_mesh.spec.js` against the mesh's sign convention I could not construct a produced-vs-expected, so it is not reported — but it is the one place in this tree I would re-check first.