@woosh/meep-engine 2.163.11 → 2.165.0

package/src/core/geom/GEOMETRY_REVIEW_002_API_ISSUES.md

@@ -0,0 +1,381 @@
+# GEOMETRY_REVIEW_002 — API shape issues
+
+`app/src/mir-engine/meep/src/core/geom`
+
+> Companion to **GEOMETRY_REVIEW_002_NAMING.md** (naming convention + full rename plan). This
+> document covers **API *shape*** problems — parameter order, output-argument placement,
+> calling conventions, return-shape divergence, allocation, duplicated functions, dead/
+> mismatched exports — plus the **genuine correctness defects** the audit surfaced along the way.
+
+## Method
+
+The package (565 source files) was swept by a fan-out of per-area cataloguing agents; the
+resulting candidate issues were then **independently re-verified against the source** by a
+separate skeptic per issue (instructed to refute). Every issue below was **confirmed**; where
+verification narrowed or corrected the original claim, the refinement is recorded inline as
+*Scope (verified)*. Two cataloguer claims that did **not** survive verification were dropped
+(a non-existent "dead `return indices_0`" in `triangle_encode_rasterized_depth`, and
+`m2_transpose` as an out-offset offender — it follows the offset-free mat2 family).
+
+Severity: **major** = wrong results, silent corruption hazard, or a cross-cutting shape trap a
+caller cannot predict; **minor** = consistency/ergonomics gap with no correctness impact.
+
+---
+
+## 0. Correctness defects (fix at root — these are bugs, not style)
+
+These were found while auditing API shape but are genuine defects. Per the project rule
+*correctness first, no bandaids*, fix the root cause (and add a regression test) rather than
+renaming around them. Each was read line-by-line and confirmed.
+
+| # | Symbol | File | Defect | Fix |
+|---|--------|------|--------|-----|
+| 1 | `circle_intersects_point` | [2d/circle/circle_intersects_point.js](2d/circle/circle_intersects_point.js) | Calls `v2_distance(cx, cx, px, py)` — passes `cx` twice, **`cy` is never used**. Wrong for any circle with `cx != cy`. | Pass `(cx, cy, px, py)`; add a regression test with `cx != cy`. |
+| 2 | `circle_compute_circle_penetration` | [2d/circle/circle_compute_circle_penetration.js](2d/circle/circle_compute_circle_penetration.js) | Line 17 computes `const dy = by - ax;` — mixes B.y with A.x. Penetration depth is wrong whenever `ax != ay`. | Use `dy = by - ay`; add a regression test. |
+| 3 | `aabb3_transformed_compute_plane_side` | [3d/aabb/aabb3_transformed_compute_plane_side.js](3d/aabb/aabb3_transformed_compute_plane_side.js) | Uses the **signed** distance from `v3_distance_above_plane(...)` directly as a truthy `if`. On-plane (0) counts as below; any nonzero (incl. negative) counts as above. Disagrees with the non-transformed `aabb3_compute_plane_side`; a box fully below returns +2 instead of −2. | Compare to 0 explicitly (`d > 0` / `d < 0`), matching `aabb3_compute_plane_side`'s on-plane convention (`>= 0` ⇒ above). |
+| 4 | `ray3_shift_origin_along_direction` | [3d/ray/ray3_shift_origin_along_direction.js](3d/ray/ray3_shift_origin_along_direction.js) | Writes the shifted origin via a **hardcoded offset 0** but writes the direction at `output_offset+3..5`. For `output_offset != 0` the packed ray is corrupted (origin lands at [0..2], direction elsewhere). | Pass `output_offset` (not 0) to the `v3_array_displace_in_direction` call. |
+| 5 | `aabb3_score_boxes_SAH_delta` | [3d/aabb/aabb3_score_boxes_SAH_delta.js](3d/aabb/aabb3_score_boxes_SAH_delta.js) | **(a)** Never `export`ed — unreachable public surface. **(b)** Mixes a *half*-surface-area union term (`aabb3_compute_half_surface_area`) with *full*-area children (`.getSurfaceArea()` ⇒ `aabb3_compute_surface_area`, which is ×2) — a 2× magnitude bug in the delta. | Export it; make both terms the same area convention (half vs full). |
+| 6 | `compareEdges` | [3d/topology/compareEdges.js](3d/topology/compareEdges.js) | **(a)** Never `export`ed. **(b)** Compares `a.v0`/`b.v0` **twice** and never `v1`, so the second edge vertex is ignored in ordering. | Export it; compare `v1` on the tie (`compareVertices(a.v1, b.v1)`). |
+
+**Latent traps (verified; not yet firing, but a guaranteed future bug):**
+
+- **`TransformedShape3D.isTransformedShape3D` is set on the constructor, not the prototype**
+  ([3d/shape/TransformedShape3D.js](3d/shape/TransformedShape3D.js)). Every sibling shape brands its
+  `prototype`; instance-side dispatch (`shape.isTransformedShape3D`, the documented pattern) reads
+  `undefined`. The spec only asserts the static form, masking the break. → move to `.prototype.`.
+- **`Vector4.prototype.toArray` is defined twice** ([Vector4.js](Vector4.js)): the class-body
+  `toArray(result)` is silently overwritten at file bottom by `= writeToArray`. Bodies happen to
+  agree today (default offset 0) — remove the define-then-clobber.
+- **Asymmetric codec**: `decode_spheremap_to_unit` is declared but not exported while its
+  `encode_unit_to_spheremap` partner is ([3d/normal/spherical/sphere_map_transform.js](3d/normal/spherical/sphere_map_transform.js)).
+
+---
+
+## 1. Major API-shape issues
+
+### 1. Allocation on common paths where zero-alloc siblings exist
+
+`allocation-on-hot-path-vs-zero-alloc-siblings` · **major** · category: allocation · confidence: high
+
+**Files:** `3d/shape/UnionShape3D.js`, `3d/shape/TransformedShape3D.js`, `3d/sphere/compute_bounding_sphere_of_2_spheres.js`, `2d/aabb/aabb2_compute_center_from_multiple.js`, `2d/aabb/AABB2.js`, `2d/rectangle_to_aabb.js`, `mat2/m2_is_orthogonal.js`, `Quaternion.js`, `3d/ray/Ray3.js`, `2d/line/line_segment_compute_line_segment_intersection_vectors_array_2d.js`, `3d/sphere/harmonics/sh3_dering_optimize_positive.js`
+
+In a perf-oriented, scratch-pool library, several methods/functions allocate per call while their siblings take out-params or use module-static scratch. UnionShape3D.compute_bounding_box does `new Float32Array(6)` and TransformedShape3D.compute_bounding_box does `const tmp = []` per call, on output-arg methods where Box/Sphere/Capsule/etc. are zero-alloc; compute_bounding_sphere_of_2_spheres news a Miniball+PointSet every call (closed form exists); aabb2_compute_center_from_multiple and rectangle_to_aabb always allocate and return instead of taking a result; AABB2.computeLineBetweenTwoBoxes allocates 2 Vector2/call; m2_is_orthogonal allocates two temp arrays/call; Quaternion.computeTwistAngle news 2 Quaternions and toArray() news []; Ray3.origin/direction getters allocate a Float32Array view per access; the allocating _vectors_array_2d hides a per-call `[]` behind an innocuous _array token; sh3_dering's sh3_min news gl-matrix vec3/mat3 per bisection iteration.
+
+**Recommendation:** Hoist module-static scratch (the established pattern) or add result out-params so the common path is allocation-free, matching the rest of each family. For the 2-sphere bound use the closed form.
+
+> Verified against source.
+
+### 2. The `_array` token carries several contradictory meanings within and across directories
+
+`array-token-overloaded-meanings` · **major** · category: misleading-name · confidence: high
+
+**Files:** `vec3/v3_array_normalize.js`, `vec3/v3_cross_array.js`, `vec3/v3_dot_array_array.js`, `vec3/v3_array_centroid.js`, `vec3/v3_array_displace_in_direction.js`, `2d/aabb/aabb2_array_set.js`, `2d/aabb/aabb2_from_v2_array.js`, `3d/aabb/aabb3_array_intersects_ray_array.js`, `3d/aabb/aabb3_array_intersects_clipping_volume_array.js`, `3d/aabb/aabb3_expand_array.js`, `2d/line/line_segment_compute_line_segment_intersection_array_2d.js`, `2d/line/line_segment_compute_line_segment_intersection_vectors_array_2d.js`, `3d/sphere/sphere_array_intersects_point.js`, `3d/frustum/frustum_from_projection_matrix_array.js`, `packing/max-rect/removeRedundantBoxesArray.js`
+
+`array` is placed as a prefix (v3_array_normalize) and as a suffix (v3_cross_array, v3_negate_array) for the identical single-vector-at-offset shape, with a double suffix (v3_dot_array_array). Worse, the token means different things: 'this operand lives in a flat array at an offset' (aabb2_array_set, v3_array_normalize); 'a contiguous batch of many vectors' (v3_array_centroid); 'the OTHER operand is packed as a scalar array' (aabb3_array_intersects_ray_array, sphere_array_intersects_point); 'the matrix input is a flat array' (frustum_from_projection_matrix_array, compose_matrix4_array); 'allocate and RETURN a new array' (line_segment_..._vectors_array_2d, vs the write-into-flat-array meaning of ..._array_2d in the same folder); and 'operates on a plain JS Array' (removeRedundantBoxesArray). v3_array_displace_in_direction even uses array_ when its inputs are scalars.
+
+**Recommendation:** Reserve `_array` for one meaning (flat-typed-array-with-offset for the subject), pick a consistent placement (suffix), and use distinct tokens for the others (e.g. _batch for many vectors, _packed for a packed second operand, _new/explicit return for allocating variants, _points/_vertices for vertex lists). Drop the redundant double _array_array.
+
+> **Scope (verified):** Two of the example glosses are imprecise though they still support the overloading point: (a) For aabb3_array_intersects_ray_array(aabb, ray), the description calls it 'the OTHER operand is packed as a scalar array', but BOTH operands (aabb and ray) are packed flat arrays read at fixed indices 0..5 — neither is scalar; the accurate meaning is 'operand(s) packed as a flat array read at fixed indices, no offset'. The 'scalar array' framing fits sphere_array_intersects_point (sphere packed, point as scalars) but not the ray case. (b) For compose_matrix4_array(result, position, rotation, scale), the `_array` suffix refers to the OUTPUT matrix being a flat array (result[0..15]); position/rotation/scale are plain objects. So it is not 'the matrix INPUT is a flat array' as grouped with frustum_from_projection_matrix_array — it is the matrix OUTPUT, arguably a sixth distinct meaning. These corrections strengthen rather than weaken the overall finding.
+
+### 3. Same primitive accepted three incompatible ways (scalars vs vector/object vs packed array+offset)
+
+`calling-convention-split-scalars-vs-object-vs-packed-array` · **major** · category: calling-convention · confidence: high
+
+**Files:** `3d/quaternion/quat3_createFromAxisAngle.js`, `3d/plane/plane3_compute_plane_intersection.js`, `3d/mat4/compose_matrix4_array.js`, `3d/mat4/decompose_matrix_4_array.js`, `mat3/m3_make_rotation.js`, `mat3/m3_determinant.js`, `mat2/m2_determinant.js`, `vec4/v4_multiply_mat4.js`, `3d/triangle/compute_triangle_normal.js`, `3d/triangle/rayTriangleIntersection.js`, `2d/uv_map_circle_to_square.js`, `3d/octahedra/octahedral_uv_to_direction.js`, `3d/cone/compute_bounding_cone_of_2_cones.js`, `3d/cone/computeConePlaneSide.js`
+
+The perf-oriented free-function layer is meant to take flattened scalars and write into typed arrays, but siblings within one directory disagree. quat3_createFromAxisAngle takes Vector3 axis + a .set()-able result while every other quat3_* takes scalars; plane3_compute_plane_intersection takes Plane OBJECTS (and string-indexes normals) while plane3_intersect_plane takes 8 scalars; compose/decompose_matrix*_array take {x,y,z,w} objects and m3_make_rotation_TBN takes Vector3 objects while the rest of mat3/mat4 take flat arrays; m2_determinant takes a 4-array but m3_determinant takes 9 scalars; v4_multiply_mat4 takes arrays while v4_dot/v4_length take scalars; compute_triangle_normal/rayTriangleIntersection take vector objects while v3_compute_triangle_normal/triangle_compute_signed_volume take scalars; octahedral_uv_to_direction uses (array,offset) for in AND out while equirectangular_uv_to_direction uses scalar (u,v); uv_map_* and spline take a Vector2 result object; cone helpers split ConicRay-object vs scalar-spread. A caller cannot predict whether to pass scalars, an object, or an array+offset.
+
+**Recommendation:** Document a two-tier rule: scalar-in / (array,offset)-out is the low-level core; object/Vector convenience forms are thin, distinctly-named wrappers. Provide the scalar/array form for the object-only outliers (or vice versa) so each core has a predictable companion.
+
+> **Scope (verified):** The claim is substantively accurate; two small precision notes that do not change the verdict: (1) equirectangular_uv_to_direction is actually a hybrid — scalar (u,v) for INPUT but (out, out_offset) array for OUTPUT — so the contrast with octahedral_uv_to_direction is specifically on the input/coordinate side, not a pure scalar-vs-array opposition across the whole signature. (2) compute_triangle_normal does not take .x/.y/.z 'vector objects'; it indexes array-likes (vA[0], vA[1], vA[2]). rayTriangleIntersection is the one in that pair that takes true Vector3 objects (.x/.y/.z, result.copy). The grouping is right (both take aggregate args vs the scalar v3_*/triangle_* forms), just the 'vector objects' label is imprecise for compute_triangle_normal.
+
+### 4. circle_compute_circle_penetration computes dy = by - ax (wrong axis)
+
+`correctness-bug-circle-penetration-dy` · **major** · category: misleading-name · confidence: high · ⚠ correctness
+
+**Files:** `2d/circle/circle_compute_circle_penetration.js`
+
+Verified at line 17: `const dy = by - ax;` mixes b's y with a's x; it should be `by - ay`. The penetration depth (used in the sqrt at line 23) is wrong whenever ax != ay. Surfaced while auditing this producer's API shape (it returns a scalar while its sibling circle_compute_circle_intersection writes a result buffer + bool — itself a return-shape inconsistency).
+
+**Recommendation:** Use dy = by - ay; add a regression test. Separately, reconcile the producer return-shape with its _intersection sibling.
+
+> Verified against source.
+
+### 5. circle_intersects_point ignores cy (passes cx twice to v2_distance)
+
+`correctness-bug-cy-ignored-circle-intersects-point` · **major** · category: misleading-name · confidence: high · ⚠ correctness
+
+**Files:** `2d/circle/circle_intersects_point.js`
+
+Verified at line 13: `const distance = v2_distance(cx, cx, px, py);` — the circle's y-center cy is never used and cx is passed twice, so the containment test is wrong for any circle whose cx != cy. This is a name/behavior-relevant defect in a containment predicate that the wider codebase also mis-names as 'intersects'.
+
+**Recommendation:** Pass (cx, cy, px, py). Add a regression test with a circle where cx != cy. (Also fold into the contains-vs-intersects rename so the predicate name reflects containment.)
+
+> **Scope (verified):** The core technical claim is accurate and confirmed; no correction needed for the bug itself. One framing caveat: for a point-vs-circle predicate, "contains" and "intersects" denote the same condition (the point is inside the disc), so the contains-vs-intersects naming aspect is cosmetic rather than a behavioral defect — the real, verified defect is solely that `cy` is ignored (cx passed twice to v2_distance), wrong for any circle with cx != cy.
+
+### 6. aabb3_transformed_compute_plane_side treats a signed distance as a truthy boolean
+
+`correctness-bug-plane-side-signed-distance-as-bool` · **major** · category: return-shape · confidence: high · ⚠ correctness
+
+**Files:** `3d/aabb/aabb3_transformed_compute_plane_side.js`, `3d/aabb/aabb3_compute_plane_side.js`
+
+Verified lines 71-74: `if (v3_distance_above_plane(...)) has_above = true; else has_below = true;`. v3_distance_above_plane returns a SIGNED distance, so a point exactly on the plane (0) is counted as below, and any nonzero (including negative/below) counts as above. The {2,0,-2} classification therefore disagrees with the non-transformed aabb3_compute_plane_side for any box on/straddling the plane. This makes the transformed/non-transformed pair return wrong-and-inconsistent results.
+
+**Recommendation:** Compare the signed distance to 0 explicitly: `const d = v3_distance_above_plane(...); if (d > 0) has_above = true; else if (d < 0) has_below = true;`, matching aabb3_compute_plane_side's on-plane semantics.
+
+> **Scope (verified):** Diagnosis is correct; only a minor line-range nit (the misuse spans lines 71-75, not 71-74) and a caveat on the fix: aabb3_compute_plane_side counts an exactly-on-plane corner as "above" (line 78 uses `>=`), so for full consistency the threshold handling of the d==0 case should match that convention rather than treating on-plane as neither side.
+
+### 7. ray3_shift_origin_along_direction ignores output_offset for the origin write
+
+`correctness-bug-ray3-shift-origin-offset` · **major** · category: output-arg-placement · confidence: high · ⚠ correctness
+
+**Files:** `3d/ray/ray3_shift_origin_along_direction.js`
+
+Verified: it writes the direction to output[output_offset+3..5] (lines 31-33) but writes the shifted origin via v3_array_displace_in_direction with a hardcoded offset 0, so for output_offset !== 0 the origin lands at [0..2] while the direction lands at [offset+3..5], corrupting the packed ray. Every sibling (ray3_array_apply_matrix4, ray3_interval_array_apply_matrix4) honors output_offset throughout.
+
+**Recommendation:** Pass output_offset (not 0) to the displace call so origin and direction land in the same slot range.
+
+> Verified against source.
+
+### 8. Function declared but never exported — unreachable public surface
+
+`declared-but-not-exported-dead-public-surface` · **major** · category: missing-companion · confidence: high
+
+**Files:** `3d/aabb/aabb3_score_boxes_SAH_delta.js`, `3d/normal/spherical/sphere_map_transform.js`, `packing/max-rect/aabb2_validate_packing.js`, `compareEdges.js`
+
+Verified by grep that these files contain a function but no `export`: aabb3_score_boxes_SAH_delta.js (zero export statements; also mixes half-area union term with full-area b0/b1.getSurfaceArea(), a magnitude bug on top of being unimportable); sphere_map_transform.js declares decode_spheremap_to_unit with no export while its encode partner IS exported (asymmetric codec); aabb2_validate_packing.js names its inner function `validate` (not the file's aabb2_ name) and never exports it; compareEdges.js declares compareEdges with no export AND has a logic bug (compares v0/v0 twice, never v1). In a library where unreferenced exports are public surface, the missing exports are real gaps.
+
+**Recommendation:** Add the missing export (and fix the SAH-delta area-magnitude mismatch and the compareEdges v1 bug at the same time) or remove the file; for the codec, export decode_spheremap_to_unit so the pair is symmetric. Do not silently delete — these are intended public functions.
+
+> **Scope (verified):** The compareEdges.js path is wrong: it is located at app/src/mir-engine/meep/src/core/geom/3d/topology/compareEdges.js, not at the geom root (compareEdges.js). All other claims — missing exports in all four files, the SAH-delta half-area vs full-area magnitude mismatch, the asymmetric spheremap codec, the misnamed `validate` inner function, and the compareEdges v0/v0-twice (never v1) logic bug — are accurate.
+
+### 9. Duplicate functions: same computation under two+ names/signatures
+
+`duplicate-functions-same-job-different-names` · **major** · category: duplication · confidence: high
+
+**Files:** `3d/aabb/aabb3_combined_surface_area.js`, `3d/aabb/aabb3_score_boxes_SAH.js`, `3d/plane/plane3_intersect_plane.js`, `3d/plane/plane3_compute_plane_intersection.js`, `3d/mat4/m4_multiply.js`, `3d/mat4/m4_multiply_alphatensor.js`, `3d/triangle/compute_triangle_normal.js`, `3d/triangle/v3_compute_triangle_normal.js`, `3d/morton/v3_morton_encode.js`, `3d/morton/mortonEncode_magicbits.js`, `packing/max-rect/removeRedundantBoxes.js`, `packing/max-rect/removeRedundantBoxesArray.js`, `3d/topology/simplify/computeEdgeCollapseCost.js`, `3d/topology/simplify/simplifyTopoMesh.js`, `3d/topology/simplify/simplifyTopoMesh2.js`
+
+Verified: aabb3_combined_surface_area and aabb3_score_boxes_SAH both `return aabb3_compute_half_surface_area(x0,y0,z0,x1,y1,z1)` over the union — exact duplicates under two names. plane3_intersect_plane (8 scalars, out-first, returns bool) and plane3_compute_plane_intersection (2 Plane objects, out-last) compute the same plane-pair intersection line — the source itself carries a TODO to consolidate. m4_multiply vs m4_multiply_alphatensor do the same 4x4 multiply (alphatensor ~2.5x slower per its own doc, and its JSDoc @param names don't match its a_in/b_in params). compute_triangle_normal vs v3_compute_triangle_normal differ only by token + arg style. v3_morton_encode default-export is a re-alias of mortonEncode_magicbits. removeRedundantBoxes vs removeRedundantBoxesArray differ only by container type. simplify/ ships two whole decimation pipelines (simplifyTopoMesh vs simplifyTopoMesh2) on duplicate cost functions (computeEdgeCollapseCost vs compute_edge_collapse_cost).
+
+**Recommendation:** Keep one canonical implementation per job; make the other a thin documented adapter or @deprecated alias (meep is a library — prefer aliasing over deletion). Consolidate the plane-pair intersection (per the in-source TODO), the SAH/combined-area pair, the morton alias, and pick one decimation entry point.
+
+> **Scope (verified):** Two of the seven pairs are mildly overstated. (a) compute_triangle_normal vs v3_compute_triangle_normal are NOT two independent computations: compute_triangle_normal is already a thin wrapper that unpacks vector args and delegates to v3_compute_triangle_normal(result, 0, ...) (line 24). It is the exact "thin adapter" the recommendation asks for, so the "duplicate computation, differ only by token + arg style" framing is inaccurate for this pair — only the scalar version contains the actual normal math. (b) removeRedundantBoxes vs removeRedundantBoxesArray do the same job with the same containment test, but they differ by more than "container type": the QuadTree version uses spatial-traversal intersection queries (traverseRectangleIntersections) and a removalSet, while the array version is a brute-force O(n^2) double loop with in-place splices — genuinely different algorithms, not just a container swap. Neither nuance changes the overall verdict: the duplication pattern is real and the plane/SAH/morton/alphatensor/decimation cases are accurate as described.
+
+### 10. Export name does not match its filename (breaks one-export-per-file discoverability)
+
+`export-filename-mismatch` · **major** · category: misleading-name · confidence: high
+
+**Files:** `3d/aabb/aabb3_build_frustum.js`, `3d/aabb/aabb3_compute_projected_area.js`, `3d/sphere/sphere_matrix4_transform.js`, `mat3/m3_make_rotation.js`, `3d/topology/struct/binary/io/face/bt_face_poke.js`, `3d/normal/hemioct/encode_unit3_hemioct.js`, `3d/normal/spherical/sphere_map_transform.js`, `3d/tetrahedra/triangle/triangle_encode_rasterized_depth.js`, `packing/max-rect/aabb2_validate_packing.js`
+
+Verified by grep: 3d/aabb/aabb3_build_frustum.js exports aabb_build_frustum (missing the '3'); aabb3_compute_projected_area.js exports aabb3_project_to_2d (and that name lies — it returns a scalar area, not a 2D box); sphere_matrix4_transform.js exports sphere_matrix4_project (and 'project' is a misnomer — it transforms center+radius); m3_make_rotation.js exports m3_make_rotation_TBN; bt_face_poke.js exports bt_mesh_face_poke (wrong object token too — operates on one face); encode_unit3_hemioct.js exports encode_unit_to_hemioct. Also export-or-name mismatches: triangle_encode_rasterized_depth.js holds a second export triangle_decode_depth, and sphere_map_transform.js holds both encode/decode under a generic file name.
+
+**Recommendation:** Rename each file to match its single export (or rename the export to match the file). For the names that also lie about behavior (aabb3_project_to_2d returns an area; sphere_matrix4_project transforms), fix the verb too.
+
+> **Scope (verified):** One small imprecision: the claim says sphere_map_transform.js "holds both encode/decode" implying two exports. In fact only `encode_unit_to_spheremap` is exported; `decode_spheremap_to_unit` (line 55) is a module-private `function` with no `export`. So that file has exactly one export (whose name still mismatches the filename) plus a private decode helper. This does not weaken the filename-mismatch thesis. Separately, the file list includes packing/max-rect/aabb2_validate_packing.js but the prose makes no assertion about it; for completeness, that file exports nothing at all and its sole function is named `validate` (not `aabb2_validate_packing`), which reinforces rather than contradicts the claim.
+
+### 11. Name says 'line' (infinite) but the function clamps to a segment
+
+`misleading-name-line-means-segment` · **major** · category: misleading-name · confidence: high
+
+**Files:** `2d/line/line2_distance_to_point_sqr.js`, `3d/line/line3_compute_nearest_point_to_point.js`
+
+Both names promise infinite-line behavior but clamp the projection parameter to [0,1], i.e. they measure to a SEGMENT. line2_distance_to_point_sqr clamp01's t (its correct 3D analogue is named line3_compute_segment_point_distance_sqr). line3_compute_nearest_point_to_point delegates to line3_compute_SEGMENT_nearest_point_to_point_t. A caller wanting true infinite-line distance gets the wrong answer with no signal.
+
+**Recommendation:** Rename to include 'segment' (line2_compute_segment_point_distance_sqr, line3_compute_segment_nearest_point_to_point) to match the honest siblings, or add a real infinite-line variant.
+
+> **Scope (verified):** The claim is substantively accurate. One small nuance: the 2D function's JSDoc DOES describe it as "between a line segment(defined by 2 points) and a point", so there is a documentation-level signal of segment behavior even though the function NAME is misleading. The claim's phrasing "with no signal" is therefore slightly overstated at the doc level; the name-level misleading-ness (and the inconsistency with the explicitly "segment"-named 3D siblings) is correct. The recommended rename (line2_compute_segment_point_distance_sqr, line3_compute_segment_nearest_point_to_point) would restore naming consistency.
+
+### 12. 'intersects' predicate names return non-boolean (containment degree) or test containment, not surface intersection
+
+`misleading-name-predicate-prefix-wrong-return` · **major** · category: misleading-name · confidence: high
+
+**Files:** `3d/aabb/aabb3_intersects_frustum_degree.js`, `3d/aabb/aabb3_array_intersects_frustum_degree.js`, `3d/sphere/sphere_intersects_point.js`, `2d/circle/circle_intersects_point.js`, `2d/aabb/aabb2_intersects_point.js`, `3d/frustum/frustum3_computeNearestPointToPoint.js`
+
+The library-wide convention is intersects_* => boolean. But aabb3_intersects_frustum_degree and aabb3_array_intersects_frustum_degree return a 3-state degree code (0/1/2), with only the easy-to-miss _degree suffix as a hint. Separately, sphere_intersects_point / circle_intersects_point / aabb2_intersects_point actually test point CONTAINMENT (point inside the volume), not surface intersection — a point 'intersecting' a sphere/circle would be on the boundary. And frustum3_computeNearestPointToPoint returns a boolean with inverted semantics: true = point was already inside (no projection), false = a nearest point WAS computed and written — a 'success'-looking flag that means the opposite.
+
+**Recommendation:** Reserve intersects_ strictly for boolean predicates: rename the degree functions to classify_/containment_degree, rename the containment tests to contains_point, and either make frustum3 return a documented 'wasInside' or always-true-on-write semantics so the boolean isn't backwards.
+
+> **Scope (verified):** The claim is substantially correct but slightly overstated/miscategorized in one place: frustum3_computeNearestPointToPoint is NOT an intersects_-prefixed function and its inverted boolean is explicitly documented in its JSDoc ('if point is inside the frustum - true'), so it does not actually violate the intersects_*=>boolean naming convention the claim is built around — it is a separate, documented wasInside-style return. Also, the point-containment naming (sphere/circle/aabb2 _intersects_point) is a common colloquial convention, so 'major' severity is arguably high for that sub-point. The two core observations stand: the _degree functions genuinely return a 0/1/2 code under an intersects_ name, and the *_intersects_point functions genuinely test containment (strict inside for sphere/circle, inclusive inside for aabb2), not surface intersection.
+
+### 13. Several writers omit the out_offset their siblings provide, breaking packed-buffer addressing
+
+`missing-out-offset-companion-breaks-packed-buffer-convention` · **major** · category: missing-companion · confidence: high
+
+**Files:** `3d/quaternion/quat3_integrate.js`, `3d/aabb/aabb3_nearest_point_on_surface.js`, `3d/aabb/aabb3_from_v2_array.js`, `2d/aabb/aabb2_from_v2_array.js`, `3d/ray/ray3_array_compose.js`, `3d/triangle/compute_triangle_normal.js`, `tetrahedron_compute_circumsphere.js`, `3d/frustum/frustum_from_projection_matrix_array.js`, `3d/frustum/frustum_slice.js`, `mat2/m2_transpose.js`
+
+Functions that should accept (out, out_offset) per their family convention instead hardcode offset 0 or omit the offset entirely, so callers packing many results into one buffer cannot use them without copying. Confirmed/flagged: quat3_integrate writes result_q[0..3] with no offset (siblings quat3_multiply/to_matrix3/decode all take one); aabb3_nearest_point_on_surface takes result first but no offset while raycast/detailed_volume_intersection take (result,result_offset); aabb3_from_v2_array and aabb2_from_v2_array hardcode array_set(result, 0, ...) ignoring offset while array_set/array_combine/clip all accept one; ray3_array_compose is the only ray3_array_* without output_offset; tetrahedron_compute_circumsphere takes result with no offset while its sub_determinant/aabb3 siblings take one; compute_triangle_normal omits result_offset that v3_compute_triangle_normal has; frustum_from_projection_matrix_array and frustum_slice omit offsets on the frustum buffer.
+
+**Recommendation:** Add the missing out_offset (and matching input-offset where relevant) so every member of a family is offset-addressable, matching the (buffer, offset) convention the rest of the library relies on for zero-copy packing.
+
+> **Scope (verified):** The pattern holds for quat3_integrate, aabb3_nearest_point_on_surface, aabb2_from_v2_array, ray3_array_compose, compute_triangle_normal, aabb3_from_v3_array (NOT "aabb3_from_v2_array" — that path does not exist), tetrahedron_compute_circumsphere (located at 3d/tetrahedra/, not geom root; and it has no "sub_determinant" sibling), and frustum_from_projection_matrix_array (missing OUTPUT base offset). Two cited items are wrong: (a) frustum_slice already exposes output_offset — only its frustum INPUT lacks an input_offset, so it is not an output-offset offender; (b) m2_transpose follows the mat2 family convention, which is entirely offset-free (m2_multiply, m2_add, etc. all use (result,a,b) with no offsets), so it is a false positive, not a convention break. Recommendation should target only the genuine offenders and frame frustum_slice/circumsphere as missing INPUT offsets rather than output ones.
+
+### 14. Output-argument position differs among siblings that all write into a caller buffer
+
+`output-arg-placement-divergence-among-siblings` · **major** · category: output-arg-placement · confidence: high
+
+**Files:** `3d/quaternion/quat3_createFromAxisAngle.js`, `3d/aabb/aabb3_expand_array.js`, `3d/aabb/aabb3_nearest_point_on_surface.js`, `vec3/v3_displace_in_direction.js`, `vec3/v3_rigid_align_paired_unit_vectors.js`, `vec3/v3_array_displace_in_direction.js`, `vec3/serialization/v3_binary_equality_decode.js`, `3d/mat4/decompose_matrix_4_array.js`, `3d/mat4/apply_mat4_transform_to_v3_array.js`, `3d/mat4/m4_extract_scale.js`, `2d/aabb/aabb2_compute_overlap.js`, `2d/polygon/polygon2_clip_axis_halfplane.js`, `2d/line/line_segment_compute_line_segment_intersection_2d.js`, `3d/equirectangular/equirectangular_uv_to_direction.js`, `3d/octahedra/octahedral_uv_to_direction.js`, `3d/sphere/harmonics/sh3_basis_at.js`, `3d/tetrahedra/tetrahedral_mesh_flip_23.js`, `3d/topology/struct/binary/query/bt_mesh_build_boundary_distance_field.js`, `3d/topology/struct/binary/query/bt_face_get_attached_faces.js`, `3d/frustum/read_three_planes_to_array.js`, `2d/bvh/bvh2d_query_all_data_by_circle.js`
+
+The library's dominant write-in-place convention is output-FIRST (often (out, out_offset, ...)), but many siblings doing the same kind of write break it. Confirmed examples: aabb3_expand_array(input, output, distance) puts output SECOND; quat3_createFromAxisAngle(axis, angle, result) puts output LAST while quat3_multiply/quat3_to_matrix3/quat_decode put it first; sh3_basis_at(x,y,z,output) is LAST while every other sh3_* is first; v3_rigid_align_paired_unit_vectors writes its out-quaternion LAST; the matrix4 apply_*_to_v3_array writers bury destination in the 3rd slot with mat4 last; aabb2_compute_overlap takes result LAST while aabb2_array_set/combine/clip/from_v2_array take it first; the equirectangular_* uv<->direction pair places out LAST while the octahedral_* pair places it FIRST for the identical operation; bt_mesh_build_boundary_distance_field puts the result Map FIRST and mesh SECOND, violating the otherwise-universal mesh-first rule; bvh2d_query_all_data_by_circle puts (bvh, root) before (result, result_offset) while every shg_/qt_ query puts result first; serializers/decoders place the destination 2nd or last; read_three_planes_to_array and slice_frustum_linear_to_points write output LAST. A caller habituated to output-first will silently corrupt the input buffer.
+
+**Recommendation:** Adopt one rule per layer (the prevailing one is output-first, (out, out_offset, ...inputs)) and migrate the outliers. Where a deliberate exception is needed (e.g. buffer-first serializers, multi-output decompose), document it prominently. At minimum make named forward/inverse and uv<->direction pairs agree with each other.
+
+> **Scope (verified):** The claim is accurate on every concrete signature. One framing point to soften: the dominant rule is output-first ((out, out_offset, ...inputs)), not a 'mesh-first' rule. bt_mesh_build_boundary_distance_field putting the result Map first is therefore consistent with output-first, not a violation of it; and its sibling bt_face_get_attached_faces also does not put mesh first (output, output_offset, mesh, face_id). So that bullet is better described as 'result-first, mesh second' (in line with the convention) rather than a mesh-first violation. Everything else stands as stated.
+
+### 15. Functions doing the same job return incompatible shapes (void vs out-arg vs bool vs scalar vs allocated array)
+
+`return-shape-divergence-among-same-job-functions` · **major** · category: return-shape · confidence: high
+
+**Files:** `3d/box/box3_raycast.js`, `3d/aabb/aabb3_raycast.js`, `3d/gjk/mpr.js`, `3d/gjk/gjk_epa_penetration.js`, `2d/line/line_segment_compute_line_segment_intersection_array_2d.js`, `2d/line/line_segment_compute_line_segment_intersection_vectors_array_2d.js`, `2d/line/line_segment_line_segment_intersection_exists_2d.js`, `mat2/m2_add.js`, `3d/mat4/m4_multiply.js`, `vec3/v3_array_centroid.js`, `3d/sphere/harmonics/sh3_rotate_bl.js`, `2d/triangle2d_compute_area.js`, `3d/triangle/compute_triangle_area_3d.js`, `3d/triangle/computeTriangleRayIntersection.js`, `3d/triangle/computeTriangleRayIntersectionBarycentric.js`
+
+Confirmed: box3_raycast returns a numeric t (Infinity on miss) and writes an exact unit normal, while aabb3_raycast solves the same ray-vs-box query but returns a boolean and writes a 6-tuple (position + |0-quantized normal). mpr returns boolean and writes MTV (normal*depth) while gjk_epa_penetration returns a depth number and writes a unit normal — two different MTV/normal encodings for the same penetration query (verified mpr returns bool, the internal gjk returns a number). The 2D segment-segment family has four protocols: bool+flat-array, bool+Vector2, allocated number[]|null, and bool-only. Among write-in-place math, some return the out buffer (m2_transpose, m4_multiply, m4_make_*, v3_array_centroid, sh3_rotate_bl) while siblings return void (m2_add, m2_multiply, m3_multiply, sh3_add). triangle area returns SIGNED in 2D but UNSIGNED in 3D under parallel names. Ray-triangle writes a SurfacePoint3 object in one variant and a flat [t,u,v] in another.
+
+**Recommendation:** Pick one return contract per operation family and document it: write-in-place math either always returns the out buffer or always void; ray/penetration queries share one normal+distance encoding; segment-intersection collapses to one success protocol; barycentric/area encode sign explicitly in the name or doc. Treat box3_raycast (distance + exact normal, matching sphere/capsule_raycast) as canonical and reimplement/deprecate the divergent aabb3_raycast.
+
+> **Scope (verified):** The 2D segment-segment family has THREE divergent protocols across the three cited files, not four: (1) line_segment_compute_line_segment_intersection_array_2d — returns bool, writes intersection point into result[result_offset..+1]; (2) line_segment_compute_line_segment_intersection_vectors_array_2d — takes Vector2 args and returns an allocated number[] (2 elements) or null; (3) line_segment_line_segment_intersection_exists_2d — returns bool only, no output write. The claim's "bool+Vector2" entry is a miscount (the vectors variant returns an allocated array, not a boolean). Also minor: in the MPR/EPA comparison the depth-returning function is epa()/gjk_epa_penetration, not the internal gjk() (which returns simplex rank 4 or 0); the externally claimed shapes (mpr→bool+MTV-vector, gjk_epa_penetration→number depth + unit normal) are correct. Everything else in the claim verified exactly as stated.
+
+### 16. Surprising / inconsistent parameter order among sibling functions
+
+`surprising-param-order-among-siblings` · **major** · category: param-order · confidence: high
+
+**Files:** `3d/sphere/sphere_project.js`, `3d/sphere/sphere_projected_sphere_radius_sqr.js`, `3d/aabb/aabb3_compute_distance_above_plane_max.js`, `3d/aabb/aabb3_transformed_compute_plane_side.js`, `3d/aabb/aabb3_detailed_volume_intersection.js`, `3d/box/box3_raycast.js`, `3d/aabb/aabb3_raycast.js`, `3d/plane/plane3_matrix4_project.js`, `3d/triangle/triangle2d_get_barycentric.js`, `3d/triangle/computeTriangleClosestPointToPointBarycentric.js`, `vec/vector_axpy.js`, `vec/vector_scale_array.js`, `3d/tetrahedra/tetrahedral_mesh_tet_get_neighbours.js`, `2d/bvh/bvh2d_query_all_data_by_circle.js`
+
+Sibling functions that should be drop-in swappable disagree on argument order. sphere_project(sph,cam,fl) vs sphere_projected_sphere_radius_sqr(fl,matrix,sph) — reversed AND different matrix param name AND different return units. The plane-classification family is plane-first (aabb3_compute_plane_side, _distance_above_plane_*) except aabb3_transformed_compute_plane_side which is box-first. box3_raycast is ray-then-box with tMax; aabb3_raycast is box-then-ray without tMax. plane3_matrix4_project puts the matrix in the middle while frustum_/clipping_volume_matrix4_project put it last. 2D barycentric puts the query point LAST while 3D closest-point-barycentric puts it FIRST. The scalar multiplier sits 2nd in vector_axpy but last in vector_scale_array. Spatial queries split structure-first vs result-first. aabb3_detailed_volume_intersection's JSDoc param order even contradicts its real signature (plane_mask/planes swapped).
+
+**Recommendation:** Standardize argument order within each family (plane-vs-box, ray-vs-box, scalar-vs-vector, structure-vs-result, query-point position) and fix the aabb3_detailed_volume_intersection JSDoc to match the implementation.
+
+> **Scope (verified):** Two minor inaccuracies, neither undermining the claim. (a) Two cited file paths are wrong: triangle2d_get_barycentric.js lives at geom/2d/triangle2d_get_barycentric.js, NOT geom/3d/triangle/triangle2d_get_barycentric.js (the 3D computeTriangleClosestPointToPointBarycentric.js path is correct). (b) The "Spatial queries split structure-first vs result-first" sub-claim is not substantiated by the cited files: geom contains only one bvh2d query (bvh2d_query_all_data_by_circle, which is structure-first: bvh, root, result, ...), with no result-first sibling to contrast it against, and tetrahedral_mesh_tet_get_neighbours(mesh, out, out_offset, tet_id) is also structure-first — so the two cited "spatial" functions are actually mutually consistent. That single sub-point should be dropped (or moved out of geom scope); the other six families plus the JSDoc bug fully stand.
+
+### 17. TransformedShape3D type marker is on the constructor, not the prototype like every sibling
+
+`transformedshape3d-marker-on-constructor-not-prototype` · **major** · category: misleading-name · confidence: high
+
+**Files:** `3d/shape/TransformedShape3D.js`, `3d/shape/BoxShape3D.js`
+
+Verified: `TransformedShape3D.isTransformedShape3D = true` (line 295, on the constructor) while every other shape puts its brand on the prototype (e.g. `BoxShape3D.prototype.isBoxShape3D = true`, line 158). Instance-side dispatch via `shape.isTransformedShape3D` — the documented marker pattern used everywhere else — therefore reads `undefined`. The spec only checks the static form, masking the break.
+
+**Recommendation:** Move to `TransformedShape3D.prototype.isTransformedShape3D = true` so instance dispatch works consistently with all sibling shapes.
+
+> Verified against source.
+
+## 2. Minor API-shape issues
+
+### 1. camelCase legacy islands sit inside otherwise snake_case directories
+
+`camelCase-vs-snake-style-islands` · **minor** · category: calling-convention · confidence: high
+
+**Files:** `3d/mat4/eulerAnglesFromMatrix.js`, `3d/cone/computeConePlaneSide.js`, `3d/cone/computeConeBoundingBox.js`, `packing/computeBoundingSphereOfSpheres.js`, `3d/triangle/computeTriangleRayIntersection.js`, `3d/triangle/rayTriangleIntersection.js`, `3d/frustum/frustum3_computeNearestPointToPoint.js`, `3d/aabb/serializeAABB3.js`, `3d/aabb/deserializeAABB3Quantized16Uint.js`, `random/randomPointInBox.js`, `packing/max-rect/packMaxRectangles.js`, `3d/topology/simplify/simplifyTopoMesh.js`
+
+The dominant style is typePrefixSnake/verboseSnake, but whole pockets are camelCase: the cone/ helpers, packing/computeBoundingSphereOfSpheres, the 6 AABB3 (de)serializers, the entire random/ and packing/max-rect/ folders, the camelCase ray-triangle island in 3d/triangle/, frustum3_computeNearestPointToPoint (the sole camelCase + sole digit-prefixed name in frustum/), eulerAnglesFromMatrix (sole camelCase in mat4/), and the simplify*/compute* legacy layer in topology. They sit next to snake siblings doing the same kind of work, so a consumer can't predict the casing.
+
+**Recommendation:** Rename the camelCase islands to the snake convention (e.g. compute_cone_plane_side, aabb3_serialize/aabb3_deserialize_quantized_u16, random_point_in_box), keeping deprecated aliases for public surface.
+
+> **Scope (verified):** One sub-clause is slightly overstated: the description calls "the entire random/ and packing/max-rect/ folders" camelCase. random/ is indeed 100% camelCase, but packing/max-rect/ is only predominantly camelCase — it also contains one snake-style file, aabb2_validate_packing.js. So max-rect is a *mixed* folder rather than wholly camelCase. This is a minor wording imprecision and does not affect the overall finding.
+
+### 2. Same concept named multiple ways across siblings (element count, output buffer, mesh/points/offset)
+
+`element-count-and-operand-param-name-disagreement` · **minor** · category: calling-convention · confidence: high
+
+**Files:** `vec/vector_copy.js`, `vec/vector_dot.js`, `vec/vector_scale_array.js`, `vec3/v3_array_copy.js`, `vec3/v3_matrix4_multiply.js`, `mat3/m3_multiply.js`, `3d/mat4/m4_multiply.js`, `3d/aabb/aabb3_build_corners.js`, `3d/aabb/compute_triangle_group_aabb3.js`, `3d/quaternion/quat3_integrate.js`, `3d/sphere/harmonics/sh3_vector_accumulate.js`, `3d/tetrahedra/compute_tetrahedron_volume.js`, `3d/topology/struct/binary/io/vertex/bt_vert_kill.js`, `3d/plane/plane3_normalize.js`
+
+The element-count is named length / n / dimensions / dimension_count / channel_count across siblings; the output buffer is named out / output / result / target / destination / r across mat2/mat3/mat4/vec3/sh3; the plane 4th scalar is w / constant / plane_offset / dist; the mesh-bound tet-id is tet_index / tet / tet_id / tetrahedron_index / containing_tetra; the points array is points / positions / input; and the vertex token is spelled vert / verts / vertex (bt_vert_kill vs bt_vertex_replace vs bt_merge_verts_by_distance). A caller cannot rely on a single name for the same role.
+
+**Recommendation:** Pick one name per role and apply across each family: e.g. `n`/`dimension_count` for counts, `result`/`out` (+ `_offset`) for outputs, `constant` for the plane scalar, `tet_id` for tet ids, `points` for coordinate buffers, and the full word `vertex`.
+
+> **Scope (verified):** One minor factual slip in the description (does not change the verdict): it says outputs vary "across mat2/mat3/mat4/vec3/sh3", but there is no mat2 directory in core/geom — only mat3 and mat4 exist. The output-naming divergence is nonetheless real among mat3 (`r`), mat4 (`out`), vec3 (`output`/`result`/`target`), and sh3 (`result`/`out`). So drop the "mat2" reference; everything else stands.
+
+### 3. Mesh-argument position and destructive-op verbs are inconsistent across topology
+
+`mesh-first-vs-mesh-last-and-kill-verb-sprawl-in-topology` · **minor** · category: param-order · confidence: med
+
+**Files:** `3d/topology/simplify/collapse_all_degenerate_edges.js`, `3d/topology/simplify/collapse_degenerate_edge.js`, `3d/topology/tm_edge_kill.js`, `3d/topology/struct/binary/io/edge/bt_edge_kill.js`, `3d/topology/struct/binary/io/edge/bt_kill_only_edge.js`, `3d/topology/struct/binary/io/bt_mesh_cleanup_faceless_references.js`, `3d/topology/struct/binary/io/bt_mesh_close_boundary_holes.js`, `3d/topology/struct/binary/io/bt_mesh_fill_small_holes.js`, `3d/topology/struct/binary/io/bt_mesh_face_decouple.js`
+
+The dominant tm_/bt_ convention is mesh-first, but collapse_all_degenerate_edges(edges, mesh), collapse_degenerate_edge(edge, mesh), and deep_copy_vertex_quadratics(dest, src, mesh) put mesh last; the two simplify pipelines even disagree internally (collapse_edges has mesh 3rd vs edge_collapse_reduce_face_count mesh 1st). Destructive/removal verbs sprawl across kill/cleanup/decouple, and hole-filling is split between close_boundary_holes and fill_small_holes for the same fan-fill concept, while the kill families invert verb order (bt_edge_kill vs bt_kill_only_edge).
+
+**Recommendation:** Make mesh the first parameter everywhere, settle a documented verb taxonomy (kill = element release+cascade, cleanup = sweep, decouple = split) and unify close/fill hole-filling under one verb with element-first kill_only naming.
+
+> Verified against source.
+
+### 4. Names that misstate magnitude/behavior (half-area as 'surface_area', quadric as 'quadratic', etc.)
+
+`misleading-name-half-surface-area-and-misnomers` · **minor** · category: misleading-name · confidence: high
+
+**Files:** `3d/aabb/aabb3_combined_surface_area.js`, `3d/aabb/aabb3_box_surface_area_2.js`, `3d/aabb/aabb3_score_boxes_SAH.js`, `3d/sphere/harmonics/SH3_COEFFICIENTS.js`, `3d/topology/simplify/quadratic/build_vertex_quadratics.js`, `3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadratics.js`, `2d/rectangle_to_aabb.js`, `3d/plane/plane3_compute_convex_3_plane_intersection.js`, `2d/quad-tree/qt_query_data_raycast.js`, `packing/computeBoundingSphereOfSpheres.js`
+
+Verified that aabb3_combined_surface_area and aabb3_score_boxes_SAH both return HALF surface area (delegate to aabb3_compute_half_surface_area) yet omit 'half', mismatching aabb3_compute_surface_area by 2x; aabb3_box_surface_area_2 has a meaningless '_2' (no '_1' exists). Other behavior-misleading names: the pervasive 'quadratics' for Quadric error metrics; rectangle_to_aabb silently clamps negative width/height; plane3_compute_convex_3_plane_intersection's 'convex' means only non-degenerate; qt_query_data_raycast ranks by distance-to-origin not ray-t; computeBoundingSphereOfSpheres stores a linear distance in a var named sqr_distance_to_center.
+
+**Recommendation:** Rename area-implying half-area functions (or document the 2x), standardize on 'quadric', drop the meaningless '_2', and either rename or JSDoc-document the sanitizing/convex/origin-distance behaviors so the names stop misleading.
+
+> **Scope (verified):** All substantive sub-claims are accurate. One minor caveat: SH3_COEFFICIENTS.js is listed in files[] but no naming defect is asserted for it and none exists (it is a correctly-named standard 3-band real-SH coefficient array) — it should be dropped from the file list, but its presence does not affect the verdict.
+
+### 5. Asymmetric _sqr / distance companion coverage implies functions that don't exist
+
+`missing-sqr-or-non-sqr-companion` · **minor** · category: missing-companion · confidence: med
+
+**Files:** `vec4/v4_distance_sqr.js`, `3d/aabb/aabb3_signed_distance_sqr_to_point.js`, `3d/aabb/aabb3_signed_distance_to_aabb3.js`, `vec3/v3_subtract.js`, `vec3/v3_cross.js`, `3d/topology/struct/binary/query/bt_vertex_distance_to_edge.js`, `3d/topology/struct/binary/query/bt_vertex_distance_to_vertex.js`, `Vector2.js`, `Vector4.js`
+
+Coverage of the _sqr/non-sqr and scalar/array axes is lopsided. vec4 ships v4_distance_sqr but no v4_distance (vec2/vec3 have both), and no v4_normalize/v4_add/v4_sub/v4_cross; aabb3 has signed_distance_sqr_to_point but no non-sqr point form, and signed_distance_to_aabb3 (sqrt) but no _sqr box-to-box form; v3_cross/v3_dot have array-offset companions but v3_subtract has no v3_subtract_array; bt_vertex_distance_to_edge/_to_vertex return sqrt with no _sqr companion despite wrapping *_distance_sqr primitives; Vector2 has length() but no lengthSqr(); Vector4 lacks length/lengthSqr/normalize/distanceTo that Vector2/Vector3 expose despite the v4_* free functions existing to back them.
+
+**Recommendation:** Fill the obvious gaps (v4_distance, the box-to-box/_to_point _sqr forms, v3_subtract_array, the bt_vertex_*_sqr forms, Vector2.lengthSqr, Vector4.length/lengthSqr/normalize wired to v4_*), or document the omissions so the names don't imply companions that don't exist.
+
+> **Scope (verified):** Substantively accurate; one minor imprecision in wording. The description says bt_vertex_distance_to_edge/_to_vertex both 'wrap *_distance_sqr primitives'. That is exactly true for bt_vertex_distance_to_edge (wraps line3_compute_segment_point_distance_sqr), but bt_vertex_distance_to_vertex actually calls v3_distance (which internally sqrts), not a _sqr primitive directly. The conclusion (no _sqr companion exists for either) still holds. Also worth noting aabb3_unsigned_distance_sqr_to_point.js does exist alongside the signed sqr form, though no signed non-sqr point form or box-to-box sqr form exists, so the gap stands.
+
+### 6. Several files export multiple symbols, several not matching the filename
+
+`multiple-exports-per-file` · **minor** · category: misleading-name · confidence: med
+
+**Files:** `3d/normal/lamber_azimuth/transform.js`, `Vector4.js`, `3d/topology/build_face_graph_from_mesh.js`, `3d/topology/simplify/decimate_edge_collapse_snap.js`, `3d/topology/simplify/edge_collapse_quadratic.js`, `3d/topology/struct/binary/query/bt_mesh_build_boundary_euclidean_distance_field.js`, `3d/tetrahedra/validate_tetrahedral_mesh.js`, `3d/tetrahedra/triangle/triangle_encode_rasterized_depth.js`
+
+The library's one-export-per-file-named-after-the-file convention is broken in several places, hurting discoverability and sometimes hiding a latent trap. Examples: transform.js exports two normal codecs; build_face_graph_from_mesh.js piggybacks graph_create_off_mesh_links (which belongs in graph/); decimate_edge_collapse_snap.js exports 4 symbols; bt_mesh_build_boundary_euclidean_distance_field.js exports 3 (two names not matching the file, one a generic point-segment helper with no mesh handle); validate_tetrahedral_mesh.js exports 3; edge_collapse_quadratic.js exports tm_edge_collapse. Separately, Vector4.prototype.toArray is assigned (= writeToArray) at file bottom, silently overwriting the class-body toArray(result) — a define-then-overwrite latent trap (bodies happen to match today).
+
+**Recommendation:** Split multi-export files into one-file-per-export named after the symbol; move misplaced helpers to their proper module; remove the Vector4 define-then-overwrite by keeping a single toArray definition.
+
+> Verified against source.
+
+### 7. 'nearest' and 'closest' used interchangeably for the same concept across the library
+
+`nearest-vs-closest-synonym-split` · **minor** · category: misleading-name · confidence: med
+
+**Files:** `3d/aabb/aabb3_nearest_point_on_surface.js`, `2d/aabb/AABB2.js`, `3d/line/line3_closest_points_segment_segment.js`, `3d/line/line3_compute_nearest_point_to_point.js`, `3d/ray/ray3_compute_nearest_point_to_point.js`, `3d/triangle/computeTriangleClosestPointToPointBarycentric.js`, `3d/frustum/frustum3_computeNearestPointToPoint.js`, `2d/quad-tree/qt_query_data_nearest_to_point.js`
+
+The closest-point concept is spelled 'nearest' (aabb3_nearest_point_on_surface, line3/ray3 _nearest_point_to_point, frustum3, qt_query_data_nearest, AABB2.computeNearestPointToPoint) and 'closest' (line3_closest_points_segment_segment, computeTriangleClosestPointToPointBarycentric) — sometimes in collaborating functions that call each other. The repo's broader convention elsewhere (closestHit) uses 'closest'. AABB2.computeNearestPointToPoint also redundantly doubles 'Point'.
+
+**Recommendation:** Pick one term library-wide (note the codebase uses 'closest' elsewhere) and rename for consistency; drop the redundant PointToPoint doubling.
+
+> **Scope (verified):** The naming split and redundant 'PointToPoint' doubling are real and confirmed. Refinement: (1) The redundant 'Point' doubling is not unique to AABB2 — it also occurs in frustum3_computeNearestPointToPoint and computeTriangleClosestPointToPointBarycentric. (2) The 'sometimes in collaborating functions that call each other' detail is imprecise: the actual caller/callee pairs are internally term-consistent ('nearest' calls 'nearest'); the cross-term inconsistency is between sibling functions in the same directories (e.g. line3_compute_nearest_point_to_point vs line3_closest_points_segment_segment) and in internal code comments (ray3's body says 'closest' while its name says 'nearest'), not between a function and the function it invokes.
+
+### 8. QuadTree query verbs (collect_/match_/query_data_) and return shapes diverge for near-identical traversals
+
+`qt-traversal-verb-and-return-sprawl` · **minor** · category: return-shape · confidence: med
+
+**Files:** `2d/quad-tree/qt_collect_by_circle.js`, `2d/quad-tree/qt_match_data_by_circle.js`, `2d/quad-tree/qt_collect_data_all.js`, `2d/quad-tree/qt_query_data_nearest_to_point.js`, `2d/quad-tree/qt_query_data_raycast.js`, `2d/quad-tree/qt_collect_by_box.js`
+
+Three verbs name near-identical traversals: qt_collect_by_* and qt_match_data_by_circle differ only by an effectively-required predicate; 'data' in the name is an unreliable signal of return type (collect_by_* return the QuadTreeDatum wrapper, collect_data_all returns unwrapped .data). qt_query_data_nearest/raycast break the shared (result,result_offset)->count contract by returning a single datum-or-undefined, and their predicate params are typed optional but invoked unconditionally (omitting throws).
+
+**Recommendation:** Unify the collect family on one verb with an optional predicate that is actually optional; keep single-result queries clearly distinct in name and document that they don't follow the count-writing contract; reserve the 'data' suffix strictly for payload-returning variants.
+
+> **Scope (verified):** One scoping error: the claim says "qt_query_data_nearest/raycast ... their predicate params are typed optional but invoked unconditionally (omitting throws)." Only qt_query_data_raycast has a predicate param (typed `[predicate]` optional, called unconditionally at line 76 — omitting throws). qt_query_data_nearest_to_point has NO predicate parameter — its 4th argument is `max_distance = Infinity` and it performs no predicate call. The optional-but-required-predicate critique applies to qt_query_data_raycast and qt_match_data_by_circle, not to qt_query_data_nearest_to_point. All other points are accurate; additionally, qt_match_data_by_circle returns the QuadTreeDatum wrapper despite carrying 'data' in its name, which strengthens (rather than weakens) the 'data'-suffix-is-unreliable point.
+
+### 9. Quaternion free-function type token split (quat3_ vs quat_) and quat3 dimension token confusion
+
+`quat-type-token-and-quat3-split` · **minor** · category: misleading-name · confidence: med
+
+**Files:** `3d/quaternion/quat3_multiply.js`, `3d/quaternion/quat3_to_matrix3.js`, `3d/quaternion/quat3_integrate.js`, `3d/quaternion/quat3_createFromAxisAngle.js`, `3d/quaternion/quat_encode_to_uint32.js`, `3d/quaternion/quat_decode_from_uint32.js`, `vec3/v3_quat3_apply.js`
+
+Within one directory the quaternion token splits: quat3_ (multiply/to_matrix3/integrate/createFromAxisAngle) vs quat_ (encode/decode_uint32), with no dimensional reason. quat3_createFromAxisAngle additionally glues a camelCase verb onto the snake prefix, carries 'create' while not allocating, and (as noted elsewhere) takes objects + output-last. v3_quat3_apply reuses 'quat3' where the 3 reads as a quaternion-dimension marker but means the 3-vector; this 'quat'/'quat3' abbreviation also differs from any qt_ token and the Quaternion class.
+
+**Recommendation:** Use one token across the quaternion free-function family (the majority is quat3_) and reconcile the vec3 'quat3' apply naming; rename quat3_createFromAxisAngle to snake (quat3_from_axis_angle), drop 'create', and align its arg shape with siblings.
+
+> Verified against source.
+
+### 10. compute_/make_/build_/from_ verb presence is arbitrary across producer siblings
+
+`verb-prefix-presence-inconsistent` · **minor** · category: misleading-name · confidence: med
+
+**Files:** `2d/aabb/aabb2_compute_area.js`, `2d/aabb/aabb2_contains.js`, `3d/aabb/aabb3_compute_surface_area.js`, `3d/box/box3_projected_half_extent.js`, `mat3/m3_cm_from_translation.js`, `3d/mat4/m4_make_translation.js`, `3d/triangle/triangle_compute_signed_volume.js`, `3d/triangle/compute_triangle_area_3d.js`, `3d/topology/struct/binary/query/bt_mesh_build_boundary_distance_field.js`, `3d/topology/struct/binary/query/bt_mesh_compute_edge_distance_eikonal.js`, `2d/triangle2d_get_barycentric.js`
+
+Producers of derived values inconsistently carry a verb prefix and inconsistently choose which verb. aabb2_compute_area/compute_overlap carry compute_ but aabb2_distance_to_point does not; box3_projected_half_extent omits compute_ while aabb3_compute_surface_area has it; build-a-matrix is m3_cm_from_translation ('from') vs m4_make_translation ('make'); triangle verbs flip order (triangle_compute_signed_volume vs compute_triangle_area_3d); distance-field builders split build_ vs compute_; triangle2d_get_barycentric uses 'get_' (implying a cheap accessor) for a barycentric solve while siblings use compute_.
+
+**Recommendation:** Adopt one rule: verb-prefix (compute_/make_) for value/buffer producers, no verb for predicates, and one verb per concept (make_ for matrix builders, compute_ for distance fields, not get_ for solves). Apply uniformly within each family.
+
+> Verified against source.
+