@woosh/meep-engine 3.1.0 → 3.2.0

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

@@ -1,434 +1,434 @@
-# Correctness review — `core/geom/` 2D half + shared primitives
-
-Scope: everything under `core/geom/2d/`, plus the loose files directly in `core/geom/`
-(`Vector1.js`, `Vector2.js`, `Vector3.js`, `Vector4.js`, `Quaternion.js`, `ConicRay.js`,
-`normalize_angle_rad.js`) and the shared sub-packages `vec/`, `vec2/`, `vec4/`, `mat2/`,
-`mat3/`, `packing/`, `random/`.
-`AABB3`, `Ray`, `Plane`, `Sphere`, `Frustum`, `Transform`, `Matrix4` all live under
-`core/geom/3d/` and were **not** reviewed (other reviewer's scope). `vec3/` likewise skipped
-as 3D-specific.
-
-Every finding below was reproduced by executing the real module in node
-(the files are plain ESM and import cleanly with `file:///` URLs, no jest needed).
-
----
-
-## Files with no adjacent spec (prioritised, in review order)
-
-High-risk (non-trivial logic, no spec):
-`2d/line/ray2_ray2_compute_intersection_array_2d.js`,
-`2d/line/segment2_intersects_segment2_2d.js`,
-`2d/line/segment2_segment_compute_intersection_array_2d.js`,
-`2d/line/line2_segment_intersection_fraction_2d.js`,
-`2d/convex-hull/convex_hull_fixed_count_2d_bruteforce.js`,
-`2d/convex-hull/convex_hull_fixed_count_2d_relaxation.js`,
-`2d/quad-tree/qt_collect_by_box.js`, `qt_collect_by_circle.js`,
-`qt_query_closest_to_point.js`, `qt_query_data_raycast.js`, `qt_collect_data_all.js`,
-`2d/triangle/tri2_compute_barycentric.js`, `2d/triangle/tri2_contains_point.js`,
-`2d/aabb/aabb2_intersects_ray.js`, `aabb2_intersects_circle.js`,
-`aabb2_compute_intersection.js`, `aabb2_signed_distance_to_point.js`,
-`2d/polygon/polygon2_triangulation_deviation.js`,
-`packing/max-rect/*` (whole directory), `packing/miniball/*`,
-`mat3/m3_invert.js`, `m3_make_rotation_TBN.js`, `m3_rm_compose_transform.js`,
-`vec/vector_normalize.js` (spec exists but does not cover the zero vector).
-
-Low-risk / trivially correct on read (verified, no findings):
-`2d/aabb/aabb2_area.js`, `aabb2_array_set.js`, `aabb2_contains_point.js`,
-`aabb2_distance_sqr_to_point.js`, `aabb2_union_array.js`,
-`2d/circle/circle_*.js`, `2d/rectangle_to_aabb.js`, `2d/spline2_quadratic_bezier.js`,
-`vec2/*`, `vec4/*`, `mat2/*`, `vec/vector_*`, `random/*`, all the `@deprecated`
-rename shims.
-
-Areas checked and found **clean** (no finding to report):
-- `polygon2_triangulate.js` — faithful earcut port; the sign inversion at `orient()`
-  (line 202-204) is correct and consistently applied through every one of ~20 comparisons
-  (verified against earcut 3.x term by term). 400 random simple polygons + 300
-  hole cases: area deviation `0` in every case. Duplicated-vertex contours agree
-  above and below `HASH_THRESHOLD`. `ensure_node_capacity` bound (`3V + 2C`) is sound.
-- `polygon2_is_counter_clockwise.js` — 20 000 randomised contours at offset (1000,1000),
-  zero disagreements with `polygon2_signed_area`'s sign. The exact-predicate-at-the-lex-min
-  vertex argument is valid (a simple polygon cannot be collinear at its lex-min vertex).
-- `polygon2_signed_area.js` / `tri2_signed_area.js` — the "form differences first"
-  rewrites are algebraically identical to the shoelace/cross reference and correctly
-  handle the repeated-first-as-last point.
-- `v2_morton_encode.js` — `split_by_2` masks to 16 bits, the `<< 1` + `>>> 0` handles
-  bit 31 correctly.
-- `orient2d_indexed.js` — confirmed by execution that `robust-predicates@3.0.2`
-  `orient2d(0,0, 1,0, 0,1) === -1`, i.e. NEGATIVE for CCW. `convex_hull_monotone_2d`
-  (ported from `monotone-convex-hull-2d`, which used `robust-orientation` — same
-  inverted convention) and `convex_hull_jarvis_2d` are both consistent with it.
-- `aabb2_intersects_ray.js` — matches Geometric Tools `IntrRay2Box2::Test` exactly.
-- `aabb2_clip_line_cohen_sutherland.js` — matches the reference Cohen–Sutherland.
-- `aabb2_signed_distance_sqr_to_point.js` — the `-dx * dx` in the penetration branch
-  reads as a precedence bug but is correct (`(-dx)*dx == -(dx*dx)` since `dx < 0` there).
-- `circle_compute_intersection.js` — matches Bourke's circle-circle formula term for term.
-- `tri2_rasterize_conservative.js` — SAT axis set is complete (2 box + 3 edge normals),
-  and touching counts as overlap, which is what "conservative" requires.
-- `packing/skyline.js` — the `count + 2` scratch bound is provably sufficient (at most one
-  segment can straddle both cut edges); `find`'s dead `x < best_x` tie-break is harmless
-  because segments are x-ascending, so first-found is already leftmost.
-- `tri2_contains_point.js` — the `Float32Array` scratch was suspected of losing the
-  `|1-u-v-w| < 1e-7` test; 400 000 fuzz cases (including coordinates at 1e5) produced
-  zero false negatives at triangle centroids. Not a defect.
-- `Vector3.crossVectors` reads all six components before writing, so
-  `m3_make_rotation_TBN`'s `v3_scratch_1.crossVectors(v3_scratch_2, v3_scratch_1)`
-  aliasing is safe.
-- `StaticR2Tree.build()` heap-layout arithmetic, `qt_collect_data_all` cursor arithmetic,
-  `QuadTreeNode` merge/split `treeDataCount` bookkeeping — all verified correct.
-
----
-
-### GEOM2-1 `polygon2_clip_halfplane` extrapolates the crossing vertex far outside the segment
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/polygon/polygon2_clip_halfplane.js:32-46`
-- **Defect**: `in_a`/`in_b` classify vertices with an epsilon-slacked side test
-  (`sa >= -POINT_EPS`), but the emitted crossing uses the *exact* line parameter
-  `t = sa / (sa - sb)`. When `in_a !== in_b` while `sa` and `sb` have the **same** sign
-  (`sa` inside the slack band, `sb` just outside it) `t` is negative and unbounded as
-  `sa - sb → 0`, so the emitted vertex is extrapolated backwards off the segment.
-  The axis-aligned twin `polygon2_clip_axis_halfplane` has no epsilon and therefore
-  cannot produce this — its `in_a !== in_b` really does imply opposite sides, so
-  `t ∈ [0,1]`.
-- **Failure scenario**:
-  ```js
-  polygon2_clip_halfplane(
-      Float64Array.from([0, -1e-9,  1, -1.0000000001e-9,  1, 5,  0, 5]), 4,
-      out, /*ex*/0, /*ey*/0, /*dx*/1, /*dy*/0, /*keep_left*/true);
-  ```
-  Here `s == y`, so `sa = -1e-9` (inside the slack, `in_a = true`) and
-  `sb = -1.0000000001e-9` (outside it, `in_b = false`), `sa - sb = 1e-19`,
-  `t = -1e10`.
-  Produced: 5 vertices, the second being `(-10000006779.697906, 0)`.
-  Expected: the crossing must lie **on** the segment `(0,-1e-9) → (1,-1e-9)`,
-  i.e. x ∈ [0, 1] (Sutherland–Hodgman, Foley & van Dam §3.14: the emitted point is
-  `A + t(B-A)` with `t ∈ [0,1]` by construction).
-  Every downstream consumer of the clipped polygon (area, containment, further clips)
-  is then wrong by ten orders of magnitude. The mirrored case
-  (`keep_left = false`, `sa ∈ (0, POINT_EPS]`) is identical.
-- **Fix**: clamp the parameter — the crossing is on the segment by construction:
-  `const t = clamp01(sa / (sa - sb));` (`core/math/clamp01.js`). Alternatively decide
-  `in_a`/`in_b` on the exact sign (`sa >= 0`) and use `POINT_EPS` only to snap a
-  near-boundary *vertex* onto the kept side, which is what the comment claims the
-  epsilon is for.
-- **Confidence**: Confirmed (executed).
-
----
-
-### GEOM2-2 `shg_query_elements_line` skips cells the segment passes through, so it misses elements
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/hash-grid/shg_query_elements_line.js:108-131`
-- **Defect**: the grid walk is not a DDA. It steps to whichever of the two candidate
-  cells has the **cell centre** closest to the segment
-  (`line2_compute_segment_point_distance_sqr(... x+step_x+0.5, y+0.5)` vs
-  `... x+0.5, y+step_y+0.5`). That ordering is not equivalent to the order in which the
-  segment actually crosses cell boundaries, so the 4-connected path can step onto a cell
-  the segment never enters *instead of* one it does. Elements registered only in the
-  skipped cell are never visited — a silent false negative.
-- **Failure scenario**: `new SpatialHashGrid(8, 8, 1)` holding a single element with
-  bounds `(3.0, 3.0)–(3.999, 3.999)` (entirely inside cell `(3,3)`), queried with
-  ```js
-  shg_query_elements_line(result, 0, grid,
-      5.516462491825223, 3.617749162018299,
-      3.8124522920697927, 4.040001254528761);
-  ```
-  Produced: `0` hits.
-  Expected: `1` hit — `aabb2_clip_line_cohen_sutherland` on the same segment and the same
-  box returns `true` (clip `(3.999, 3.9938)–(3.9779, 3.999)`). The segment crosses `y = 4`
-  at `x = 3.9739`, i.e. inside column 3, so the true cell sequence is
-  `(5,3) (4,3) (3,3) (3,4)`; the walk produces `(5,3) (4,3) (4,4) (3,4)`.
-  A 4000-segment fuzz over an 8×8 grid missed at least one truly-crossed cell in
-  **14 cases (0.35 %)**.
-- **Fix**: replace the centre-distance heuristic with the standard Amanatides–Woo
-  voxel traversal (Amanatides & Woo 1987, *A Fast Voxel Traversal Algorithm for Ray
-  Tracing*): precompute `t_max_x`/`t_max_y` to the next cell boundary and
-  `t_delta_x`/`t_delta_y`, then step the axis with the smaller `t_max`. That is exact by
-  construction and no more expensive per step.
-- **Confidence**: Confirmed (executed end-to-end against the real `SpatialHashGrid`).
-
----
-
-### GEOM2-3 `convex_hull_fixed_count_2d_bruteforce` minimises a SIGNED area, so clockwise input yields the *largest* polygon
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/convex-hull/convex_hull_fixed_count_2d_bruteforce.js:111-116`
-- **Defect**: `const area = polygon2_signed_area(intersections, k); if (area < best_area)`.
-  `polygon2_signed_area` is **signed** — negative for a clockwise loop. The intersection
-  polygon inherits the input's winding, so for clockwise input every candidate area is
-  negative and `area < best_area` selects the *most negative*, i.e. the maximum-area
-  polygon. The function's contract ("such that the area would be minimal") and its input
-  contract ("must be an ordered loop… must form a convex hull") say nothing about winding,
-  and nothing normalises it.
-- **Failure scenario**: regular octagon, circumradius 10, `output_point_count = 4`.
-  - CCW input → produced quad area **341.421**, which is the true minimum
-    (the square on four alternating edge lines, side `2·10·cos 22.5° = 18.478`).
-  - The *same octagon* wound CW → produced quad area **482.843**
-    (`(0,-24.14) (-10,0) (0,24.14) (10,0)`), 41 % larger than the achievable minimum.
-  - 12-gon: CCW → 373.205 (correct minimum, `= (2·10·cos15°)²`); CW → **746.410**, exactly
-    2× the minimum.
-- **Fix**: compare `Math.abs(area)`, or normalise the input winding once at entry
-  (`polygon2_is_counter_clockwise` + reversed iteration) so the objective is unsigned.
-- **Confidence**: Confirmed (executed).
-
----
-
-### GEOM2-4 `convex_hull_fixed_count_2d_relaxation` uses a signed collapse cost, so clockwise input diverges
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/convex-hull/convex_hull_fixed_count_2d_relaxation.js:161-170`
-- **Defect**: `compute_collapse_cost` returns `tri2_signed_area(v0, target, v1)`, fed
-  straight into `edge_heap` and consumed with `pop_min`. For a counter-clockwise loop the
-  collapse target lies to the right of `v0→v1`, so the signed area is positive and the
-  greedy correctly removes the cheapest (smallest added area) edge. For a clockwise loop
-  every cost is negative, so `pop_min` selects the collapse that adds the **most** area,
-  and the hull runs away. (The commented-out `if (area < 0 || Number.isNaN(area))
-  debugger;` at lines 166-168 shows the non-negative assumption.)
-- **Failure scenario**: regular 12-gon, circumradius 10, `output_point_count = 4`.
-  - CCW input → 4 points, area 402.07 (greedy, documented as suboptimal vs the
-    exact 373.205 — acceptable).
-  - Same 12-gon wound CW → 4 points at
-    `(1790557056.00, 6682451968.00), (8.66,-5.00), (-5.00,-18.66), (-10.00,0)`,
-    area **6.68e10**. Every input point has |coordinate| ≤ 10; a bounding polygon
-    must too, and its area cannot exceed a few hundred.
-- **Fix**: `return Math.abs(area)` in `compute_collapse_cost`, or normalise the input
-  winding at entry (same fix as GEOM2-3, and the two functions should share it).
-- **Confidence**: Confirmed (executed).
-
----
-
-### GEOM2-5 `ray2_ray2_compute_intersection_array_2d` rejects every intersection with `t < 0.5`
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/line/ray2_ray2_compute_intersection_array_2d.js:33-34`
-- **Defect**: `if (t < 0.5) return false; // Intersects on the wrong side`. For a ray,
-  "wrong side" is `t < 0`; `0.5` discards the entire first half of the parameter range.
-  The `t` derivation above it is correct (`t = (dir_b × (o_a - o_b)) / (dir_a × dir_b)`),
-  so the rejection threshold is the only defect. The adjacent spec
-  (`2d/intersect_ray_2d.spec.js`) only exercises `t = 2`, so it does not pin this down.
-- **Failure scenario**: ray A origin `(0,0)` direction `(1,0)`; ray B origin `(0.25,-1)`
-  direction `(0,1)`. The rays cross at `(0.25, 0)` with `t = 0.25 ≥ 0`.
-  Produced: `false`, `result` untouched.
-  Expected: `true`, `result = [0.25, 0]`. (Same call with B at `x = 0.75` → `t = 0.75`
-  → correctly returns `true, [0.75, 0]`, confirming the threshold is what rejects it.)
-- **Fix**: `if (t < 0) return false;`.
-- **Confidence**: Confirmed (executed).
-
----
-
-### GEOM2-6 `ray2_ray2_compute_intersection_array_2d` uses an absolute parallelism epsilon on an unnormalised cross product
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/line/ray2_ray2_compute_intersection_array_2d.js:21-26`
-- **Defect**: `if (Math.abs(denominator) < 1e-7) return false;` where
-  `denominator = dir_a × dir_b`. The function's own doc requires the directions to be
-  **unnormalised**, "derived from line length", so the cross product scales as
-  `|dir_a|·|dir_b|·sin θ`. For short edges the magnitude collapses and perfectly
-  perpendicular rays are reported parallel. `convex_hull_fixed_count_2d_bruteforce` and
-  `..._relaxation` build their directions exactly this way from polygon edges, so a
-  small-scale polygon silently loses valid edge intersections.
-- **Failure scenario**: ray A origin `(0,0)` direction `(1e-4, 0)`; ray B origin
-  `(0.5e-4, -1e-4)` direction `(0, 1e-4)`. `denominator = 1e-8 < 1e-7`.
-  Produced: `false` ("parallel").
-  Expected: `true`, `result = [0.5e-4, 0]` — the directions are exactly orthogonal
-  (`sin θ = 1`).
-- **Fix**: make the test scale-relative, e.g. reject when
-  `Math.abs(denominator) <= EPS * Math.hypot(dir_a_x, dir_a_y) * Math.hypot(dir_b_x, dir_b_y)`,
-  or test `denominator === 0` and let the caller filter by the resulting magnitude.
-- **Confidence**: Confirmed (executed).
-
----
-
-### GEOM2-7 `segment2_intersects_segment2_2d` / `..._compute_intersection_array_2d` report collinear overlapping segments as disjoint
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/line/segment2_intersects_segment2_2d.js:23-28`
-  and `2d/line/segment2_segment_compute_intersection_array_2d.js:33-38`
-- **Defect**: `inv_denom = 1 / (-s2_x*s1_y + s1_x*s2_y)`. For parallel segments the
-  denominator is `0`, so `inv_denom = Infinity`; for *collinear* segments the numerators
-  are also `0`, giving `s = t = 0 * Infinity = NaN`, and every comparison against `NaN`
-  is false. The in-file twin used by the triangulator
-  (`2d/polygon/polygon2_triangulate.js:425-452 segments_intersect`) explicitly handles the
-  collinear-touching case via `on_segment`, so the two "do these segments intersect"
-  predicates in the same package disagree.
-- **Failure scenario**: `segment2_intersects_segment2_2d(0,0, 2,0, 1,0, 3,0)` — the two
-  segments overlap along `x ∈ [1,2]` on the line `y = 0`.
-  Produced: `false`. Expected: `true` (they share infinitely many points).
-  This matters for grid-aligned data, where collinear edges are the common case.
-- **Fix**: branch on `denominator === 0` and, when the segments are also collinear
-  (`cross(b0 - a0, s1) === 0`), decide by 1D interval overlap along the dominant axis —
-  the same structure `polygon2_triangulate.segments_intersect` already uses. If the
-  exclusion is deliberate, document it on both functions.
-- **Confidence**: Confirmed (executed).
-
----
-
-### GEOM2-8 `min_area_rect_2d` returns `area: Infinity` alongside `width: 0, height: 0`
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/oriented-box/min_area_rect_2d.js:26,38-40,68`
-- **Defect**: `best_area` is seeded to `Infinity` and only ever lowered inside the loop.
-  When every hull edge is shorter than the `1e-12` guard the loop body is `continue`d for
-  all of them and the seed is returned, while `best_width`/`best_height` keep their `0`
-  seeds. The `h < 2` early-out at line 22-24 does not cover this: `convex_hull_monotone_2d`
-  returns two indices for three coincident points.
-- **Failure scenario**: `min_area_rect_2d([1,1, 1,1, 1,1], 3)`
-  Produced: `{ angle: 0, width: 0, height: 0, area: Infinity }`.
-  Expected: `{ angle: 0, width: 0, height: 0, area: 0 }` — the object is internally
-  inconsistent as returned (`area !== width * height`), and a caller ranking candidate
-  boxes by `area` will rank a degenerate cluster as the worst possible instead of the best.
-  Also reachable with two near-coincident points: `min_area_rect_2d([0,0, 1e-13,0], 2)`.
-- **Fix**: after the loop, `if (best_area === Infinity) { return { angle: 0, width: 0,
-  height: 0, area: 0 }; }` — or derive the returned `area` from `best_width * best_height`
-  so the three fields cannot disagree.
-- **Confidence**: Confirmed (executed).
-
----
-
-### GEOM2-9 `convex_hull_monotone_2d` and `convex_hull_jarvis_2d` return opposite windings
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/convex-hull/convex_hull_monotone_2d.js:103-114`
-  vs `2d/convex-hull/convex_hull_jarvis_2d.js:64-87`
-- **Defect**: both are correct hulls, but they traverse in opposite directions and neither
-  documents its winding. `convex_hull_jarvis_2d`'s doc says only "ordered to form a closed
-  loop around the hull"; `convex_hull_monotone_2d` says nothing. A caller that swaps one
-  for the other (they are drop-in compatible by signature and return type — flat xy in,
-  index array out) silently inverts every downstream orientation test.
-- **Failure scenario**: `points = [0,0, 4,0, 4,4, 0,4, 2,2]`, `point_count = 5`.
-  - `convex_hull_jarvis_2d` → `[0, 1, 2, 3]` = `(0,0) (4,0) (4,4) (0,4)`,
-    signed area `+16` (counter-clockwise).
-  - `convex_hull_monotone_2d` → `[0, 3, 2, 1]` = `(0,0) (0,4) (4,4) (4,0)`,
-    signed area `−16` (clockwise).
-  Existing consumers happen to be winding-insensitive (`min_area_rect_2d` takes
-  min/max projections), so nothing is broken today — but the contract gap is a live trap.
-- **Fix**: document the winding on both, and make them agree (reverse the merge order in
-  `convex_hull_monotone_2d`'s `result` assembly, lines 107-113, is the smaller change).
-- **Confidence**: Confirmed (executed).
-
----
-
-### GEOM2-10 `qt_match_data_by_circle` / `qt_query_data_raycast` throw when the documented-optional `predicate` is omitted
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/quad-tree/qt_match_data_by_circle.js:17,56`
-  and `2d/quad-tree/qt_query_data_raycast.js:18,76`
-- **Defect**: both declare `@param {function(...)} [predicate]` and
-  `@param {*} [predicateContext]` — square brackets, i.e. optional — but call
-  `predicate.call(predicateContext, ...)` unconditionally for every candidate datum.
-- **Failure scenario**:
-  ```js
-  const tree = new QuadTreeNode(0, 0, 100, 100);
-  tree.add("a", 1, 1, 2, 2);
-  qt_match_data_by_circle([], 0, tree, 1.5, 1.5, 5);   // predicate omitted
-  ```
-  Produced: `TypeError: Cannot read properties of undefined (reading 'call')`.
-  Expected: `1` (the datum is inside the circle), per the JSDoc.
-  Note the throw only happens once a candidate is found, so an empty tree passes and the
-  bug hides until there is data.
-- **Fix**: either drop the brackets in the JSDoc (making `predicate` required — the
-  no-predicate case is already served by `qt_collect_by_circle`), or guard:
-  `if (d2_to_datum <= r2 && (predicate === undefined || predicate.call(...)))`.
-  Given the codebase preference for uniform control flow, the JSDoc fix is the better one.
-- **Confidence**: Confirmed (executed).
-
----
-
-### GEOM2-11 `StaticR2Tree.sort_morton` seeds the shared scratch stack at absolute index 0, but reads from `stack.pointer`
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/r-tree/StaticR2Tree.js:219-245`
-- **Defect**:
-  ```js
-  const stack_top = stack.pointer;
-  let stackPointer = stack_top + 2;
-  stack[0] = 0;                              // <- absolute 0
-  stack[1] = this.__node_count_leaf - 1;     // <- absolute 1
-  ...
-  while (stackPointer > stack_top) {
-      stackPointer -= 2;
-      const right = stack[stackPointer + 1]; // <- reads stack_top+1
-      const left  = stack[stackPointer];     // <- reads stack_top
-  ```
-  The seed is written at absolute indices 0/1 while the first pop reads
-  `stack_top`/`stack_top + 1`. This is only correct when `stack.pointer === 0`.
-  `SCRATCH_UINT32_TRAVERSAL_STACK` is a module-level singleton shared with
-  `bvh2d_query_all_data_by_circle` and the other traversals.
-- **Failure scenario**: with `SCRATCH_UINT32_TRAVERSAL_STACK.pointer === 4` on entry
-  (a BVH traversal in progress, e.g. `sort_morton` called from a query callback), the
-  first iteration reads `stack[4]`/`stack[5]` — stale node indices from that traversal —
-  as the quicksort range. With those being arbitrary node ids, `__swap_leaves` writes
-  outside the leaf block or the sort silently does nothing; the tree is then built from
-  unsorted leaves. Expected: the sort range is always `[0, leaf_count-1]`.
-  Also note `sort_morton` never claims or releases `stack.pointer`, so it corrupts the
-  in-flight traversal's stack regardless.
-- **Fix**: write the seed relative to the claimed region —
-  `stack[stack_top] = 0; stack[stack_top + 1] = this.__node_count_leaf - 1;` — and
-  advance/restore `stack.pointer` around the sort the way the query functions do
-  (`stack.pointer = stackPointer` on entry, `stack.pointer = stack_top` on exit).
-- **Confidence**: Likely (the index mismatch is unambiguous; the reachability depends on
-  a nested call, which the file's own "mostly untested" note does not exclude).
-
----
-
-### GEOM2-12 `vector_normalize` produces NaN for a zero vector while its 2D twin returns zero
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/vec/vector_normalize.js:19-23`
-- **Defect**: `const magnitude_inv = 1 / Math.sqrt(magnitude2);` with no zero check.
-  Every sibling normalise in the package guards: `vec2/v2_array_normalize.js:24`
-  (`length_sqr !== 0 ? 1/sqrt(...) : 1`), `Vector2.normalize():621`,
-  `Vector3.normalize():560`. The N-dimensional one is the odd one out, and its spec
-  (`vec/vector_normalize.spec.js`) does not cover the case.
-- **Failure scenario**: `const r = [0,0,0]; vector_normalize(r, [0,0,0], 3);`
-  Produced: `r === [NaN, NaN, NaN]`.
-  Expected (per the behaviour of every twin in this package): `[0, 0, 0]` — the result is
-  left unscaled rather than poisoned. A NaN written into a solver's basis vector then
-  propagates silently through every subsequent dot product.
-- **Fix**: `const magnitude_inv = magnitude2 !== 0 ? 1 / Math.sqrt(magnitude2) : 1;`
-  (exactly the form `v2_array_normalize` already uses).
-- **Confidence**: Confirmed (executed).
-
----
-
-### GEOM2-13 `Vector2`/`Vector3`/`Quaternion` shadow the typed-array `length` property with a `length()` method
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/Vector2.js:605-607`
-  (same shape at `Vector3.js:543` and `Quaternion.js`)
-- **Defect**: these classes `extend Float64Array` and also define a prototype method named
-  `length`. `Vector2.prototype.length` sits between the instance and
-  `%TypedArray%.prototype`'s `length` getter, so `instance.length` resolves to the
-  **function**, not the element count. The class doc at `Vector2.js:25` claims instances
-  are "usable directly as typed-array views"; that claim does not hold for any generic
-  consumer that reads `.length`. The `normalize()` comment at lines 614-618 documents that
-  V8 sometimes resolves `this.length` to the number instead — i.e. the property is not
-  merely wrong, it is *inconsistently* wrong depending on JIT state, which is why
-  `normalize()` had to be rewritten to call `v2_length` directly.
-- **Failure scenario**: `const v = new Vector2(3, 4);`
-  - `typeof v.length` → `"function"` (expected `"number"`, value `2`).
-  - `Array.prototype.slice.call(v)` → `[]` (`ToLength(function) === 0`);
-    expected `[3, 4]`.
-  - `Array.prototype.indexOf.call(v, 3)` → `-1`; expected `0`.
-  (Internal typed-array methods and `Array.from(v)` still work, because they use the
-  internal `[[ArrayLength]]` slot / the iterator rather than the property.)
-- **Fix**: rename the method (`magnitude()`), keeping `length()` as a deprecated alias
-  on a differently-named prototype slot is not possible — the name is the problem. If the
-  method name must be preserved for compatibility, stop extending `Float64Array` and hold
-  the buffer as a field instead.
-- **Confidence**: Confirmed (executed).
-
----
-
-### GEOM2-14 `AABB2.computeArea()` on the canonical empty box returns `+Infinity`
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/aabb/AABB2.js:392-399, 405-415, 360-386, 675-677`
-- **Defect**: `setNegativelyInfiniteBounds()` is the package's "empty box" representation
-  (`x0=y0=+∞, x1=y1=−∞`) and is used as an accumulator seed in ~15 call sites. None of the
-  size/cost accessors handle it: `aabb2_area(∞,∞,−∞,−∞)` computes
-  `(−∞ − ∞) * (−∞ − ∞) = (−∞)·(−∞) = +∞`.
-- **Failure scenario**: `const b = new AABB2(); b.setNegativelyInfiniteBounds();`
-  - `b.computeArea()` → `Infinity`; expected `0` (an empty box encloses nothing).
-  - `b.computeSurfaceArea()` → `-Infinity`; expected `0`.
-  - `b.costForInclusion(new AABB2(0,0,1,1))` → `-Infinity`; expected a finite
-    non-negative growth cost. A BVH/packing insertion loop ranking candidates by
-    `costForInclusion` will always pick a not-yet-initialised (empty) node, because
-    `-Infinity` beats every real candidate.
-  This is reachable whenever an accumulator loop turns out to be empty — e.g.
-  `entity_node_compute_bounding_box.js:37` or `View.js:505` seed an `AABB2` this way and
-  then only `_expandToFit` inside a loop over children.
-- **Fix**: give the three accessors an emptiness early-out — `if (this.x1 < this.x0 ||
-  this.y1 < this.y0) return 0;` in `computeArea`/`computeSurfaceArea`, and make
-  `_costForInclusion` fall back to the area of the *other* box when `this` is empty.
-  Note `_costForInclusion` also drops the second-order term of the true area growth
-  (`x*dy + y*dx`, missing `x*y`), so `AABB2(0,0,1,1).costForInclusion(AABB2(2,2,3,3))`
-  returns `4` where the actual area increase is `8`; worth deciding whether the function
-  is meant to be an exact growth or a first-order heuristic, and documenting it.
-- **Confidence**: Confirmed (executed).
+# Correctness review — `core/geom/` 2D half + shared primitives
+
+Scope: everything under `core/geom/2d/`, plus the loose files directly in `core/geom/`
+(`Vector1.js`, `Vector2.js`, `Vector3.js`, `Vector4.js`, `Quaternion.js`, `ConicRay.js`,
+`normalize_angle_rad.js`) and the shared sub-packages `vec/`, `vec2/`, `vec4/`, `mat2/`,
+`mat3/`, `packing/`, `random/`.
+`AABB3`, `Ray`, `Plane`, `Sphere`, `Frustum`, `Transform`, `Matrix4` all live under
+`core/geom/3d/` and were **not** reviewed (other reviewer's scope). `vec3/` likewise skipped
+as 3D-specific.
+
+Every finding below was reproduced by executing the real module in node
+(the files are plain ESM and import cleanly with `file:///` URLs, no jest needed).
+
+---
+
+## Files with no adjacent spec (prioritised, in review order)
+
+High-risk (non-trivial logic, no spec):
+`2d/line/ray2_ray2_compute_intersection_array_2d.js`,
+`2d/line/segment2_intersects_segment2_2d.js`,
+`2d/line/segment2_segment_compute_intersection_array_2d.js`,
+`2d/line/line2_segment_intersection_fraction_2d.js`,
+`2d/convex-hull/convex_hull_fixed_count_2d_bruteforce.js`,
+`2d/convex-hull/convex_hull_fixed_count_2d_relaxation.js`,
+`2d/quad-tree/qt_collect_by_box.js`, `qt_collect_by_circle.js`,
+`qt_query_closest_to_point.js`, `qt_query_data_raycast.js`, `qt_collect_data_all.js`,
+`2d/triangle/tri2_compute_barycentric.js`, `2d/triangle/tri2_contains_point.js`,
+`2d/aabb/aabb2_intersects_ray.js`, `aabb2_intersects_circle.js`,
+`aabb2_compute_intersection.js`, `aabb2_signed_distance_to_point.js`,
+`2d/polygon/polygon2_triangulation_deviation.js`,
+`packing/max-rect/*` (whole directory), `packing/miniball/*`,
+`mat3/m3_invert.js`, `m3_make_rotation_TBN.js`, `m3_rm_compose_transform.js`,
+`vec/vector_normalize.js` (spec exists but does not cover the zero vector).
+
+Low-risk / trivially correct on read (verified, no findings):
+`2d/aabb/aabb2_area.js`, `aabb2_array_set.js`, `aabb2_contains_point.js`,
+`aabb2_distance_sqr_to_point.js`, `aabb2_union_array.js`,
+`2d/circle/circle_*.js`, `2d/rectangle_to_aabb.js`, `2d/spline2_quadratic_bezier.js`,
+`vec2/*`, `vec4/*`, `mat2/*`, `vec/vector_*`, `random/*`, all the `@deprecated`
+rename shims.
+
+Areas checked and found **clean** (no finding to report):
+- `polygon2_triangulate.js` — faithful earcut port; the sign inversion at `orient()`
+  (line 202-204) is correct and consistently applied through every one of ~20 comparisons
+  (verified against earcut 3.x term by term). 400 random simple polygons + 300
+  hole cases: area deviation `0` in every case. Duplicated-vertex contours agree
+  above and below `HASH_THRESHOLD`. `ensure_node_capacity` bound (`3V + 2C`) is sound.
+- `polygon2_is_counter_clockwise.js` — 20 000 randomised contours at offset (1000,1000),
+  zero disagreements with `polygon2_signed_area`'s sign. The exact-predicate-at-the-lex-min
+  vertex argument is valid (a simple polygon cannot be collinear at its lex-min vertex).
+- `polygon2_signed_area.js` / `tri2_signed_area.js` — the "form differences first"
+  rewrites are algebraically identical to the shoelace/cross reference and correctly
+  handle the repeated-first-as-last point.
+- `v2_morton_encode.js` — `split_by_2` masks to 16 bits, the `<< 1` + `>>> 0` handles
+  bit 31 correctly.
+- `orient2d_indexed.js` — confirmed by execution that `robust-predicates@3.0.2`
+  `orient2d(0,0, 1,0, 0,1) === -1`, i.e. NEGATIVE for CCW. `convex_hull_monotone_2d`
+  (ported from `monotone-convex-hull-2d`, which used `robust-orientation` — same
+  inverted convention) and `convex_hull_jarvis_2d` are both consistent with it.
+- `aabb2_intersects_ray.js` — matches Geometric Tools `IntrRay2Box2::Test` exactly.
+- `aabb2_clip_line_cohen_sutherland.js` — matches the reference Cohen–Sutherland.
+- `aabb2_signed_distance_sqr_to_point.js` — the `-dx * dx` in the penetration branch
+  reads as a precedence bug but is correct (`(-dx)*dx == -(dx*dx)` since `dx < 0` there).
+- `circle_compute_intersection.js` — matches Bourke's circle-circle formula term for term.
+- `tri2_rasterize_conservative.js` — SAT axis set is complete (2 box + 3 edge normals),
+  and touching counts as overlap, which is what "conservative" requires.
+- `packing/skyline.js` — the `count + 2` scratch bound is provably sufficient (at most one
+  segment can straddle both cut edges); `find`'s dead `x < best_x` tie-break is harmless
+  because segments are x-ascending, so first-found is already leftmost.
+- `tri2_contains_point.js` — the `Float32Array` scratch was suspected of losing the
+  `|1-u-v-w| < 1e-7` test; 400 000 fuzz cases (including coordinates at 1e5) produced
+  zero false negatives at triangle centroids. Not a defect.
+- `Vector3.crossVectors` reads all six components before writing, so
+  `m3_make_rotation_TBN`'s `v3_scratch_1.crossVectors(v3_scratch_2, v3_scratch_1)`
+  aliasing is safe.
+- `StaticR2Tree.build()` heap-layout arithmetic, `qt_collect_data_all` cursor arithmetic,
+  `QuadTreeNode` merge/split `treeDataCount` bookkeeping — all verified correct.
+
+---
+
+### GEOM2-1 `polygon2_clip_halfplane` extrapolates the crossing vertex far outside the segment
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/polygon/polygon2_clip_halfplane.js:32-46`
+- **Defect**: `in_a`/`in_b` classify vertices with an epsilon-slacked side test
+  (`sa >= -POINT_EPS`), but the emitted crossing uses the *exact* line parameter
+  `t = sa / (sa - sb)`. When `in_a !== in_b` while `sa` and `sb` have the **same** sign
+  (`sa` inside the slack band, `sb` just outside it) `t` is negative and unbounded as
+  `sa - sb → 0`, so the emitted vertex is extrapolated backwards off the segment.
+  The axis-aligned twin `polygon2_clip_axis_halfplane` has no epsilon and therefore
+  cannot produce this — its `in_a !== in_b` really does imply opposite sides, so
+  `t ∈ [0,1]`.
+- **Failure scenario**:
+  ```js
+  polygon2_clip_halfplane(
+      Float64Array.from([0, -1e-9,  1, -1.0000000001e-9,  1, 5,  0, 5]), 4,
+      out, /*ex*/0, /*ey*/0, /*dx*/1, /*dy*/0, /*keep_left*/true);
+  ```
+  Here `s == y`, so `sa = -1e-9` (inside the slack, `in_a = true`) and
+  `sb = -1.0000000001e-9` (outside it, `in_b = false`), `sa - sb = 1e-19`,
+  `t = -1e10`.
+  Produced: 5 vertices, the second being `(-10000006779.697906, 0)`.
+  Expected: the crossing must lie **on** the segment `(0,-1e-9) → (1,-1e-9)`,
+  i.e. x ∈ [0, 1] (Sutherland–Hodgman, Foley & van Dam §3.14: the emitted point is
+  `A + t(B-A)` with `t ∈ [0,1]` by construction).
+  Every downstream consumer of the clipped polygon (area, containment, further clips)
+  is then wrong by ten orders of magnitude. The mirrored case
+  (`keep_left = false`, `sa ∈ (0, POINT_EPS]`) is identical.
+- **Fix**: clamp the parameter — the crossing is on the segment by construction:
+  `const t = clamp01(sa / (sa - sb));` (`core/math/clamp01.js`). Alternatively decide
+  `in_a`/`in_b` on the exact sign (`sa >= 0`) and use `POINT_EPS` only to snap a
+  near-boundary *vertex* onto the kept side, which is what the comment claims the
+  epsilon is for.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-2 `shg_query_elements_line` skips cells the segment passes through, so it misses elements
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/hash-grid/shg_query_elements_line.js:108-131`
+- **Defect**: the grid walk is not a DDA. It steps to whichever of the two candidate
+  cells has the **cell centre** closest to the segment
+  (`line2_compute_segment_point_distance_sqr(... x+step_x+0.5, y+0.5)` vs
+  `... x+0.5, y+step_y+0.5`). That ordering is not equivalent to the order in which the
+  segment actually crosses cell boundaries, so the 4-connected path can step onto a cell
+  the segment never enters *instead of* one it does. Elements registered only in the
+  skipped cell are never visited — a silent false negative.
+- **Failure scenario**: `new SpatialHashGrid(8, 8, 1)` holding a single element with
+  bounds `(3.0, 3.0)–(3.999, 3.999)` (entirely inside cell `(3,3)`), queried with
+  ```js
+  shg_query_elements_line(result, 0, grid,
+      5.516462491825223, 3.617749162018299,
+      3.8124522920697927, 4.040001254528761);
+  ```
+  Produced: `0` hits.
+  Expected: `1` hit — `aabb2_clip_line_cohen_sutherland` on the same segment and the same
+  box returns `true` (clip `(3.999, 3.9938)–(3.9779, 3.999)`). The segment crosses `y = 4`
+  at `x = 3.9739`, i.e. inside column 3, so the true cell sequence is
+  `(5,3) (4,3) (3,3) (3,4)`; the walk produces `(5,3) (4,3) (4,4) (3,4)`.
+  A 4000-segment fuzz over an 8×8 grid missed at least one truly-crossed cell in
+  **14 cases (0.35 %)**.
+- **Fix**: replace the centre-distance heuristic with the standard Amanatides–Woo
+  voxel traversal (Amanatides & Woo 1987, *A Fast Voxel Traversal Algorithm for Ray
+  Tracing*): precompute `t_max_x`/`t_max_y` to the next cell boundary and
+  `t_delta_x`/`t_delta_y`, then step the axis with the smaller `t_max`. That is exact by
+  construction and no more expensive per step.
+- **Confidence**: Confirmed (executed end-to-end against the real `SpatialHashGrid`).
+
+---
+
+### GEOM2-3 `convex_hull_fixed_count_2d_bruteforce` minimises a SIGNED area, so clockwise input yields the *largest* polygon
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/convex-hull/convex_hull_fixed_count_2d_bruteforce.js:111-116`
+- **Defect**: `const area = polygon2_signed_area(intersections, k); if (area < best_area)`.
+  `polygon2_signed_area` is **signed** — negative for a clockwise loop. The intersection
+  polygon inherits the input's winding, so for clockwise input every candidate area is
+  negative and `area < best_area` selects the *most negative*, i.e. the maximum-area
+  polygon. The function's contract ("such that the area would be minimal") and its input
+  contract ("must be an ordered loop… must form a convex hull") say nothing about winding,
+  and nothing normalises it.
+- **Failure scenario**: regular octagon, circumradius 10, `output_point_count = 4`.
+  - CCW input → produced quad area **341.421**, which is the true minimum
+    (the square on four alternating edge lines, side `2·10·cos 22.5° = 18.478`).
+  - The *same octagon* wound CW → produced quad area **482.843**
+    (`(0,-24.14) (-10,0) (0,24.14) (10,0)`), 41 % larger than the achievable minimum.
+  - 12-gon: CCW → 373.205 (correct minimum, `= (2·10·cos15°)²`); CW → **746.410**, exactly
+    2× the minimum.
+- **Fix**: compare `Math.abs(area)`, or normalise the input winding once at entry
+  (`polygon2_is_counter_clockwise` + reversed iteration) so the objective is unsigned.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-4 `convex_hull_fixed_count_2d_relaxation` uses a signed collapse cost, so clockwise input diverges
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/convex-hull/convex_hull_fixed_count_2d_relaxation.js:161-170`
+- **Defect**: `compute_collapse_cost` returns `tri2_signed_area(v0, target, v1)`, fed
+  straight into `edge_heap` and consumed with `pop_min`. For a counter-clockwise loop the
+  collapse target lies to the right of `v0→v1`, so the signed area is positive and the
+  greedy correctly removes the cheapest (smallest added area) edge. For a clockwise loop
+  every cost is negative, so `pop_min` selects the collapse that adds the **most** area,
+  and the hull runs away. (The commented-out `if (area < 0 || Number.isNaN(area))
+  debugger;` at lines 166-168 shows the non-negative assumption.)
+- **Failure scenario**: regular 12-gon, circumradius 10, `output_point_count = 4`.
+  - CCW input → 4 points, area 402.07 (greedy, documented as suboptimal vs the
+    exact 373.205 — acceptable).
+  - Same 12-gon wound CW → 4 points at
+    `(1790557056.00, 6682451968.00), (8.66,-5.00), (-5.00,-18.66), (-10.00,0)`,
+    area **6.68e10**. Every input point has |coordinate| ≤ 10; a bounding polygon
+    must too, and its area cannot exceed a few hundred.
+- **Fix**: `return Math.abs(area)` in `compute_collapse_cost`, or normalise the input
+  winding at entry (same fix as GEOM2-3, and the two functions should share it).
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-5 `ray2_ray2_compute_intersection_array_2d` rejects every intersection with `t < 0.5`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/line/ray2_ray2_compute_intersection_array_2d.js:33-34`
+- **Defect**: `if (t < 0.5) return false; // Intersects on the wrong side`. For a ray,
+  "wrong side" is `t < 0`; `0.5` discards the entire first half of the parameter range.
+  The `t` derivation above it is correct (`t = (dir_b × (o_a - o_b)) / (dir_a × dir_b)`),
+  so the rejection threshold is the only defect. The adjacent spec
+  (`2d/intersect_ray_2d.spec.js`) only exercises `t = 2`, so it does not pin this down.
+- **Failure scenario**: ray A origin `(0,0)` direction `(1,0)`; ray B origin `(0.25,-1)`
+  direction `(0,1)`. The rays cross at `(0.25, 0)` with `t = 0.25 ≥ 0`.
+  Produced: `false`, `result` untouched.
+  Expected: `true`, `result = [0.25, 0]`. (Same call with B at `x = 0.75` → `t = 0.75`
+  → correctly returns `true, [0.75, 0]`, confirming the threshold is what rejects it.)
+- **Fix**: `if (t < 0) return false;`.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-6 `ray2_ray2_compute_intersection_array_2d` uses an absolute parallelism epsilon on an unnormalised cross product
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/line/ray2_ray2_compute_intersection_array_2d.js:21-26`
+- **Defect**: `if (Math.abs(denominator) < 1e-7) return false;` where
+  `denominator = dir_a × dir_b`. The function's own doc requires the directions to be
+  **unnormalised**, "derived from line length", so the cross product scales as
+  `|dir_a|·|dir_b|·sin θ`. For short edges the magnitude collapses and perfectly
+  perpendicular rays are reported parallel. `convex_hull_fixed_count_2d_bruteforce` and
+  `..._relaxation` build their directions exactly this way from polygon edges, so a
+  small-scale polygon silently loses valid edge intersections.
+- **Failure scenario**: ray A origin `(0,0)` direction `(1e-4, 0)`; ray B origin
+  `(0.5e-4, -1e-4)` direction `(0, 1e-4)`. `denominator = 1e-8 < 1e-7`.
+  Produced: `false` ("parallel").
+  Expected: `true`, `result = [0.5e-4, 0]` — the directions are exactly orthogonal
+  (`sin θ = 1`).
+- **Fix**: make the test scale-relative, e.g. reject when
+  `Math.abs(denominator) <= EPS * Math.hypot(dir_a_x, dir_a_y) * Math.hypot(dir_b_x, dir_b_y)`,
+  or test `denominator === 0` and let the caller filter by the resulting magnitude.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-7 `segment2_intersects_segment2_2d` / `..._compute_intersection_array_2d` report collinear overlapping segments as disjoint
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/line/segment2_intersects_segment2_2d.js:23-28`
+  and `2d/line/segment2_segment_compute_intersection_array_2d.js:33-38`
+- **Defect**: `inv_denom = 1 / (-s2_x*s1_y + s1_x*s2_y)`. For parallel segments the
+  denominator is `0`, so `inv_denom = Infinity`; for *collinear* segments the numerators
+  are also `0`, giving `s = t = 0 * Infinity = NaN`, and every comparison against `NaN`
+  is false. The in-file twin used by the triangulator
+  (`2d/polygon/polygon2_triangulate.js:425-452 segments_intersect`) explicitly handles the
+  collinear-touching case via `on_segment`, so the two "do these segments intersect"
+  predicates in the same package disagree.
+- **Failure scenario**: `segment2_intersects_segment2_2d(0,0, 2,0, 1,0, 3,0)` — the two
+  segments overlap along `x ∈ [1,2]` on the line `y = 0`.
+  Produced: `false`. Expected: `true` (they share infinitely many points).
+  This matters for grid-aligned data, where collinear edges are the common case.
+- **Fix**: branch on `denominator === 0` and, when the segments are also collinear
+  (`cross(b0 - a0, s1) === 0`), decide by 1D interval overlap along the dominant axis —
+  the same structure `polygon2_triangulate.segments_intersect` already uses. If the
+  exclusion is deliberate, document it on both functions.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-8 `min_area_rect_2d` returns `area: Infinity` alongside `width: 0, height: 0`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/oriented-box/min_area_rect_2d.js:26,38-40,68`
+- **Defect**: `best_area` is seeded to `Infinity` and only ever lowered inside the loop.
+  When every hull edge is shorter than the `1e-12` guard the loop body is `continue`d for
+  all of them and the seed is returned, while `best_width`/`best_height` keep their `0`
+  seeds. The `h < 2` early-out at line 22-24 does not cover this: `convex_hull_monotone_2d`
+  returns two indices for three coincident points.
+- **Failure scenario**: `min_area_rect_2d([1,1, 1,1, 1,1], 3)`
+  Produced: `{ angle: 0, width: 0, height: 0, area: Infinity }`.
+  Expected: `{ angle: 0, width: 0, height: 0, area: 0 }` — the object is internally
+  inconsistent as returned (`area !== width * height`), and a caller ranking candidate
+  boxes by `area` will rank a degenerate cluster as the worst possible instead of the best.
+  Also reachable with two near-coincident points: `min_area_rect_2d([0,0, 1e-13,0], 2)`.
+- **Fix**: after the loop, `if (best_area === Infinity) { return { angle: 0, width: 0,
+  height: 0, area: 0 }; }` — or derive the returned `area` from `best_width * best_height`
+  so the three fields cannot disagree.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-9 `convex_hull_monotone_2d` and `convex_hull_jarvis_2d` return opposite windings
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/convex-hull/convex_hull_monotone_2d.js:103-114`
+  vs `2d/convex-hull/convex_hull_jarvis_2d.js:64-87`
+- **Defect**: both are correct hulls, but they traverse in opposite directions and neither
+  documents its winding. `convex_hull_jarvis_2d`'s doc says only "ordered to form a closed
+  loop around the hull"; `convex_hull_monotone_2d` says nothing. A caller that swaps one
+  for the other (they are drop-in compatible by signature and return type — flat xy in,
+  index array out) silently inverts every downstream orientation test.
+- **Failure scenario**: `points = [0,0, 4,0, 4,4, 0,4, 2,2]`, `point_count = 5`.
+  - `convex_hull_jarvis_2d` → `[0, 1, 2, 3]` = `(0,0) (4,0) (4,4) (0,4)`,
+    signed area `+16` (counter-clockwise).
+  - `convex_hull_monotone_2d` → `[0, 3, 2, 1]` = `(0,0) (0,4) (4,4) (4,0)`,
+    signed area `−16` (clockwise).
+  Existing consumers happen to be winding-insensitive (`min_area_rect_2d` takes
+  min/max projections), so nothing is broken today — but the contract gap is a live trap.
+- **Fix**: document the winding on both, and make them agree (reverse the merge order in
+  `convex_hull_monotone_2d`'s `result` assembly, lines 107-113, is the smaller change).
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-10 `qt_match_data_by_circle` / `qt_query_data_raycast` throw when the documented-optional `predicate` is omitted
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/quad-tree/qt_match_data_by_circle.js:17,56`
+  and `2d/quad-tree/qt_query_data_raycast.js:18,76`
+- **Defect**: both declare `@param {function(...)} [predicate]` and
+  `@param {*} [predicateContext]` — square brackets, i.e. optional — but call
+  `predicate.call(predicateContext, ...)` unconditionally for every candidate datum.
+- **Failure scenario**:
+  ```js
+  const tree = new QuadTreeNode(0, 0, 100, 100);
+  tree.add("a", 1, 1, 2, 2);
+  qt_match_data_by_circle([], 0, tree, 1.5, 1.5, 5);   // predicate omitted
+  ```
+  Produced: `TypeError: Cannot read properties of undefined (reading 'call')`.
+  Expected: `1` (the datum is inside the circle), per the JSDoc.
+  Note the throw only happens once a candidate is found, so an empty tree passes and the
+  bug hides until there is data.
+- **Fix**: either drop the brackets in the JSDoc (making `predicate` required — the
+  no-predicate case is already served by `qt_collect_by_circle`), or guard:
+  `if (d2_to_datum <= r2 && (predicate === undefined || predicate.call(...)))`.
+  Given the codebase preference for uniform control flow, the JSDoc fix is the better one.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-11 `StaticR2Tree.sort_morton` seeds the shared scratch stack at absolute index 0, but reads from `stack.pointer`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/r-tree/StaticR2Tree.js:219-245`
+- **Defect**:
+  ```js
+  const stack_top = stack.pointer;
+  let stackPointer = stack_top + 2;
+  stack[0] = 0;                              // <- absolute 0
+  stack[1] = this.__node_count_leaf - 1;     // <- absolute 1
+  ...
+  while (stackPointer > stack_top) {
+      stackPointer -= 2;
+      const right = stack[stackPointer + 1]; // <- reads stack_top+1
+      const left  = stack[stackPointer];     // <- reads stack_top
+  ```
+  The seed is written at absolute indices 0/1 while the first pop reads
+  `stack_top`/`stack_top + 1`. This is only correct when `stack.pointer === 0`.
+  `SCRATCH_UINT32_TRAVERSAL_STACK` is a module-level singleton shared with
+  `bvh2d_query_all_data_by_circle` and the other traversals.
+- **Failure scenario**: with `SCRATCH_UINT32_TRAVERSAL_STACK.pointer === 4` on entry
+  (a BVH traversal in progress, e.g. `sort_morton` called from a query callback), the
+  first iteration reads `stack[4]`/`stack[5]` — stale node indices from that traversal —
+  as the quicksort range. With those being arbitrary node ids, `__swap_leaves` writes
+  outside the leaf block or the sort silently does nothing; the tree is then built from
+  unsorted leaves. Expected: the sort range is always `[0, leaf_count-1]`.
+  Also note `sort_morton` never claims or releases `stack.pointer`, so it corrupts the
+  in-flight traversal's stack regardless.
+- **Fix**: write the seed relative to the claimed region —
+  `stack[stack_top] = 0; stack[stack_top + 1] = this.__node_count_leaf - 1;` — and
+  advance/restore `stack.pointer` around the sort the way the query functions do
+  (`stack.pointer = stackPointer` on entry, `stack.pointer = stack_top` on exit).
+- **Confidence**: Likely (the index mismatch is unambiguous; the reachability depends on
+  a nested call, which the file's own "mostly untested" note does not exclude).
+
+---
+
+### GEOM2-12 `vector_normalize` produces NaN for a zero vector while its 2D twin returns zero
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/vec/vector_normalize.js:19-23`
+- **Defect**: `const magnitude_inv = 1 / Math.sqrt(magnitude2);` with no zero check.
+  Every sibling normalise in the package guards: `vec2/v2_array_normalize.js:24`
+  (`length_sqr !== 0 ? 1/sqrt(...) : 1`), `Vector2.normalize():621`,
+  `Vector3.normalize():560`. The N-dimensional one is the odd one out, and its spec
+  (`vec/vector_normalize.spec.js`) does not cover the case.
+- **Failure scenario**: `const r = [0,0,0]; vector_normalize(r, [0,0,0], 3);`
+  Produced: `r === [NaN, NaN, NaN]`.
+  Expected (per the behaviour of every twin in this package): `[0, 0, 0]` — the result is
+  left unscaled rather than poisoned. A NaN written into a solver's basis vector then
+  propagates silently through every subsequent dot product.
+- **Fix**: `const magnitude_inv = magnitude2 !== 0 ? 1 / Math.sqrt(magnitude2) : 1;`
+  (exactly the form `v2_array_normalize` already uses).
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-13 `Vector2`/`Vector3`/`Quaternion` shadow the typed-array `length` property with a `length()` method
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/Vector2.js:605-607`
+  (same shape at `Vector3.js:543` and `Quaternion.js`)
+- **Defect**: these classes `extend Float64Array` and also define a prototype method named
+  `length`. `Vector2.prototype.length` sits between the instance and
+  `%TypedArray%.prototype`'s `length` getter, so `instance.length` resolves to the
+  **function**, not the element count. The class doc at `Vector2.js:25` claims instances
+  are "usable directly as typed-array views"; that claim does not hold for any generic
+  consumer that reads `.length`. The `normalize()` comment at lines 614-618 documents that
+  V8 sometimes resolves `this.length` to the number instead — i.e. the property is not
+  merely wrong, it is *inconsistently* wrong depending on JIT state, which is why
+  `normalize()` had to be rewritten to call `v2_length` directly.
+- **Failure scenario**: `const v = new Vector2(3, 4);`
+  - `typeof v.length` → `"function"` (expected `"number"`, value `2`).
+  - `Array.prototype.slice.call(v)` → `[]` (`ToLength(function) === 0`);
+    expected `[3, 4]`.
+  - `Array.prototype.indexOf.call(v, 3)` → `-1`; expected `0`.
+  (Internal typed-array methods and `Array.from(v)` still work, because they use the
+  internal `[[ArrayLength]]` slot / the iterator rather than the property.)
+- **Fix**: rename the method (`magnitude()`), keeping `length()` as a deprecated alias
+  on a differently-named prototype slot is not possible — the name is the problem. If the
+  method name must be preserved for compatibility, stop extending `Float64Array` and hold
+  the buffer as a field instead.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-14 `AABB2.computeArea()` on the canonical empty box returns `+Infinity`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/aabb/AABB2.js:392-399, 405-415, 360-386, 675-677`
+- **Defect**: `setNegativelyInfiniteBounds()` is the package's "empty box" representation
+  (`x0=y0=+∞, x1=y1=−∞`) and is used as an accumulator seed in ~15 call sites. None of the
+  size/cost accessors handle it: `aabb2_area(∞,∞,−∞,−∞)` computes
+  `(−∞ − ∞) * (−∞ − ∞) = (−∞)·(−∞) = +∞`.
+- **Failure scenario**: `const b = new AABB2(); b.setNegativelyInfiniteBounds();`
+  - `b.computeArea()` → `Infinity`; expected `0` (an empty box encloses nothing).
+  - `b.computeSurfaceArea()` → `-Infinity`; expected `0`.
+  - `b.costForInclusion(new AABB2(0,0,1,1))` → `-Infinity`; expected a finite
+    non-negative growth cost. A BVH/packing insertion loop ranking candidates by
+    `costForInclusion` will always pick a not-yet-initialised (empty) node, because
+    `-Infinity` beats every real candidate.
+  This is reachable whenever an accumulator loop turns out to be empty — e.g.
+  `entity_node_compute_bounding_box.js:37` or `View.js:505` seed an `AABB2` this way and
+  then only `_expandToFit` inside a loop over children.
+- **Fix**: give the three accessors an emptiness early-out — `if (this.x1 < this.x0 ||
+  this.y1 < this.y0) return 0;` in `computeArea`/`computeSurfaceArea`, and make
+  `_costForInclusion` fall back to the area of the *other* box when `this` is empty.
+  Note `_costForInclusion` also drops the second-order term of the true area growth
+  (`x*dy + y*dx`, missing `x*y`), so `AABB2(0,0,1,1).costForInclusion(AABB2(2,2,3,3))`
+  returns `4` where the actual area increase is `8`; worth deciding whether the function
+  is meant to be an exact growth or a first-order heuristic, and documenting it.
+- **Confidence**: Confirmed (executed).