@woosh/meep-engine 3.60.4 → 3.60.5

package/src/engine/navigation/mesh/OVERLAPPING_SURFACES_2026_08_25.md

@@ -1,661 +0,0 @@
-# Overlapping walkable surfaces in the navmesh build — investigation & proposal
-
-Status: **INVESTIGATION** · 2026-08-25 · one fix landed (D1), everything else deliberately not
-Tests: [`navmesh_overlapping_surfaces.spec.js`](navmesh_overlapping_surfaces.spec.js) — 20 tests: 5 controls run, 15 `test.skip`.
-The 15 assert what the build should do and all fail today. They are skipped, not deleted: the behaviour
-is still wrong and still worth stating, but a permanently-red suite hides the next real regression (CI
-gates on `npm run test:ci`, and the coverage deploy depends on it). Delete the `.skip` to work on one.
-Fix: [`navmesh_concave_obstacle.spec.js`](navmesh_concave_obstacle.spec.js) — 6 tests, green.
-
-> **What was executed.** Of everything below, exactly one thing was changed: **D1**, obstacles carved
-> as their convex hull (§5.1). It was the only finding that is a defect in shipping behaviour with a
-> self-contained fix and a single caller. A, B, C and D2 are documented and left alone — see §9 for
-> why, and §10 for the adversarial review of the change that did land.
-
----
-
-## 0. TL;DR
-
-Three failure modes were reported against `NavigationMesh.build`. **All three reproduce.** They look
-like one problem and are actually three, each needing a different kind of answer:
-
-| | reported as | reproduces | class of problem | fixable by a tolerance? |
-| --- | --- | --- | --- | --- |
-| **A** | stacked coplanar floors, the middle one should win | yes | **semantics** — the build has no notion of walkable-vs-walkable occlusion | no |
-| **B** | coplanar lateral overlap goes non-traversable / disconnected | yes, both | **topology** — overlapping sheets are never unioned | no (verified) |
-| **C** | split ridge / shallow wedge fails to weld | yes, worse than predicted | **tolerance** — a dead band between two constants | yes |
-
-Two further defects surfaced while investigating:
-
-* **D1** — overhead obstacles are carved as their **convex hull**, so an L-shaped, ring-shaped or
-  merely adjacent obstacle over-carves. A doorway frame removes the doorway. **Fixed** — §5.1, §10.
-* **D2** — island bridging inserts **90° vertical faces** that the climb-angle filter would have
-  rejected, and `bt_mesh_compute_face_islands` then reports connectivity that `find_path` does not
-  honour.
-
-The single sentence that covers all of it:
-
-> The build has a **repair** stage sized for float noise, and no **reconciliation** stage sized for
-> authoring error. Everything downstream assumes the source was already a manifold.
-
-Recommendation is in §9. Short version: **Stage 0 + Stage 1 are worth doing now; Stage 2 behind a
-flag; Stage 3 probably never** — and the adversarial review in §8 is the part worth reading before
-agreeing with any of it.
-
----
-
-## 1. What the build does today
-
-`NavigationMesh.build` → [`navmesh_build_topology`](build/navmesh_build_topology.js), in order:
-
-| # | pass | purpose |
-| --- | --- | --- |
-| 1 | walkable-angle filter + degenerate drop | keep faces within `agent_max_climb_angle` of `up` |
-| 2 | `bt_mesh_kill_short_edges(1e-6)` | remove slivers thinner than the weld can represent |
-| 3 | `bt_merge_vertices_by_distance(1e-6)` | fuse coincident positions |
-| 4 | `bt_mesh_fuse_duplicate_edges` | give the fused vertices a shared *edge* |
-| 5 | `bt_mesh_resolve_t_junctions(1e-4)` + re-weld/fuse | a corner sitting mid-edge of a bigger neighbour |
-| 6 | per-island `bt_mesh_face_island_erode(agent_radius)` | inset the outer boundary |
-| 7 | `clip_soup_against_overhangs` | subtract r-dilated obstacle footprints |
-| 8 | `bt_mesh_bridge_islands` *(opt-in)* | span steps / gaps |
-| 9 | `bt_mesh_split_pinched_vertices`, `bt_mesh_fill_small_holes`, `bt_mesh_simplify_by_error` | cleanup |
-
-Passes 2–5 are the whole of the input reconciliation, and the tolerance ladder they run on is:
-
-| tolerance | value | where | what it is *for* |
-| --- | --- | --- | --- |
-| weld | `1e-6`, **raised to the float32 step at the mesh's coordinate magnitude** | [navmesh_build_topology.js:69](build/navmesh_build_topology.js:69) | "reunite the same corner reached by different arithmetic — not to simplify anything" (its own docstring) |
-| T-junction | `1e-4` | [:197](build/navmesh_build_topology.js:197), [:250](build/navmesh_build_topology.js:250) | a corner mid-edge of a larger neighbour |
-| T-junction **endpoint exclusion** | `tolerance / ‖edge‖` | [bt_mesh_resolve_t_junctions.js:197](../../../core/geom/3d/topology/struct/binary/io/bt_mesh_resolve_t_junctions.js:197) | don't "split" an edge at a point that *is* its endpoint |
-| carve height band | `1e-3` | [clip_soup_against_overhangs.js:44](build/clip_soup_against_overhangs.js:44) | |
-| obstacle grouping quantum | `1e-3` | [clip_soup_against_overhangs.js:57](build/clip_soup_against_overhangs.js:57) | |
-| simplify | `0.05 × agent_radius` | [navmesh_build_topology.js:52](build/navmesh_build_topology.js:52) | |
-
-Note what is *absent* from that ladder: any number that means **"how far apart may two surfaces be and
-still be the same surface?"** The largest reconciliation tolerance in the build is `1e-4` — a tenth of a
-millimetre, several orders of magnitude below what any authoring tool guarantees. That absence is Case C.
-
----
-
-## 2. Case A — stacked coplanar floors
-
-### Setup
-
-Three identical 10×10 floors, `agent_height = 1.6`, gaps of 0.10. Soup order deliberately puts the
-winner second, so an implementation that kept "the first" or "the last" would pick a loser:
-
-```
-y = 0.20   <-- soup triangle #2   the only standable surface
-y = 0.10   <-- soup triangle #1   0.10 of headroom
-y = 0.00   <-- soup triangle #3   0.20 of headroom
-```
-
-### Observed
-
-| metric | observed | correct |
-| --- | --- | --- |
-| islands | 3 | 1 |
-| surface area | 300 | 100 |
-| heights present | `[0, 0.1, 0.2]` | `[0.2]` |
-| cover at one XZ point | 3 | 1 |
-| faces with < `agent_height` headroom | 4 | 0 |
-| 10 layers → | 10 islands, area 1000 | 1 island, area 100 |
-
-### Root cause
-
-[`clip_soup_against_overhangs.js:286`](build/clip_soup_against_overhangs.js:286):
-
-```js
-if (fn[0] * upx + fn[1] * upy + fn[2] * upz >= -HEIGHT_EPS) continue; // not downward-facing
-```
-
-Obstacles are **only** the downward-facing source faces. An upward-facing floor never occludes
-anything below it, so `agent_height` is never consulted for walkable-vs-walkable stacking. Erosion
-(pass 6) then runs *per island*, so with `agent_radius > 0` all three layers merely shrink.
-
-### What is *not* wrong
-
-The worry that an arbitrary tie-break might land on the first or last triangle **does not
-materialise**. All six soup permutations produce byte-identical island counts, areas and height sets.
-The failure is not that the wrong layer is chosen — it is that **no layer is dropped at all**. This is
-locked in as a green control so it stays true after any fix.
-
-### The control that proves the diagnosis
-
-Add a downward-facing face to the top slab (i.e. a closed slab rather than a single-sided plane) and
-the build gets it exactly right: 1 island, area 100, only `y = 0.20` survives. **The topmost does win,
-once the build can see the stack.** So the machinery is correct; only its input predicate is too narrow.
-
-### Prior art
-
-Recast solves this in `rcFilterWalkableLowHeightSpans` — a span with less than `walkableHeight` of
-clearance to the span above it is removed, regardless of which surface produced either span. The
-proposal in §7.3 is that filter, done on polygons instead of voxels.
-
----
-
-## 3. Case B — coplanar lateral overlap
-
-### Setup
-
-Two floors at `y = 0` whose footprints overlap. Two variants, because the two behave differently:
-
-```
- B1 "edge overlap"          B2 "corner overlap"
- +--------+                 +--------+
- |   A    |                 |   A    |
- |     +--+-----+           |     +--+-----+
- |     |##|  B  |           |     |##|  B  |
- +-----+--+-----+           +-----+--+     |
-                                  |    B   |
-                                  +--------+
-```
-
-In **B1** both of B's left corners land *exactly on* A's boundary edges. In **B2** the outlines cross
-edge-to-edge with no vertex at the crossing.
-
-### Observed
-
-| config | islands | A→B path | note |
-| --- | --- | --- | --- |
-| B1, `r = 0` | 1 | **15.84** vs 12 straight | joined only at the mesh corner `(10, 0, 10)`; a 32% detour |
-| B1, `r = 0.4` | 2 | **none** | |
-| B2, `r = 0` | 2 | **none** | zero erosion involved |
-| control: abutting, no overlap | 1 | 16.0 = straight | |
-
-Surface area is 200 against a true union of 160; the overlap carries two sheets everywhere.
-
-### Root cause
-
-Nothing in the pipeline unions coplanar sheets. Each keeps its own boundary running through the
-other's interior, and **whether the two connect at all is an accident of geometry**: B1 happens to
-present a stray vertex on a boundary edge, which `bt_mesh_resolve_t_junctions` can split on; B2
-presents an edge-edge crossing, which it cannot. B2 is the far more common modelling mistake.
-
-### Erosion turns the seam into a wall — verified directly
-
-Coverage sampled across `x` at `z = 2.3` for B1:
-
-```
-r=0    0.5:1 … 5.5:1  6:2 6.5:2 … 9.5:2 10:2  10.5:1 … 15.5:1
-r=0.4  0.5:1 … 5.5:1  6:0 6.5:2 … 9.5:2 10:0  10.5:1 … 15.5:1
-                      ^^^                ^^^^
-```
-
-Two zero-coverage walls, at exactly `x = 6` and `x = 10` — the two interior boundary lines. Erosion
-insets from **every** boundary edge, including the ones buried inside the other sheet, so it carves a
-wall along each and severs the single corner join that held B1 together.
-
-### No tolerance fixes this
-
-Pre-welding the source at 1e-2 and 5e-2 leaves B2 at 2 islands with no path. The defect is genuine
-interior overlap, not near-coincident vertices; welding has nothing to bite on.
-
----
-
-## 4. Case C — split ridge / shallow wedge
-
-### Setup
-
-Two slabs that used to share a ridge at `x = 0`, separated into two pairs of vertices, each pushed
-`δ` **into** the other, and tilted by 0.02 over a 10-unit span (~0.1°) into a convex roof or concave
-valley. The ridge lines end up `2δ` apart.
-
-### Observed (at the world origin, `r = 0`)
-
-| δ | islands | path across the ridge |
-| --- | --- | --- |
-| 0 (truly shared) | 1 | **15.997**, turning at `x ≈ 0` — correct |
-| 1e-7, 1e-6 | 1 | correct |
-| **1e-5** | **2** | **none** |
-| 1e-4, 1e-3, 1e-2 | 1 | **18.87** vs 16 — detour to `z = 10` |
-| 1e-3, `r = 0.4` | **2** | **none** |
-
-Concave behaves identically to convex; so does an asymmetric variant where the two halves are tilted
-by different amounts.
-
-So the prediction ("welding fails, the ridge becomes impassable") is right, and there are actually
-**two** distinct failures:
-
-1. **The dead band.** A separation past the weld but inside the T-junction tolerance is joined by
-   neither pass. [bt_mesh_resolve_t_junctions.js:197](../../../core/geom/3d/topology/struct/binary/io/bt_mesh_resolve_t_junctions.js:197) skips any candidate near the edge's own endpoints:
-
-   ```js
-   const t_margin = tolerance / Math.sqrt(ab_sq);
-   …
-   if (t <= t_margin || t >= 1 - t_margin) continue;   // "that IS the endpoint" — so, skip
-   ```
-
-   Correct reasoning for *splitting* — you cannot split an edge at its own endpoint. But the right
-   action for a distinct vertex sitting a hair off an endpoint is to **weld** it there, and nothing does.
-
-2. **Above the dead band, the join is cosmetic.** At δ ≥ 1e-4 the resolver joins the slabs, but only
-   over a `2δ`-long stub at each *end* of the ridge. The ridge itself is still a crack, so the path
-   runs out to the mesh edge and back — and any positive agent radius erodes the stub away entirely.
-
-### The dead band moves with world position — the sharpest finding
-
-`bt_merge_vertices_by_distance` floors its tolerance at the float32 step for the mesh's coordinate
-magnitude (see [`bt_mesh_vertex_merge_distance.js`](../../../core/geom/3d/topology/struct/binary/io/vertex/bt_mesh_vertex_merge_distance.js)). The
-T-junction tolerance is a flat `1e-4`. So the band where neither applies is
-`float32_step(‖coord‖) < 2δ < 1e-4`, and it **shrinks as geometry moves away from the origin**:
-
-| origin x | float32 step | δ=1e-6 | δ=1e-5 | δ=1e-4 | δ=1e-3 |
-| --- | --- | --- | --- | --- | --- |
-| 0 | 2.1e-6 | direct | **NO PATH** | detour | detour |
-| 100 | 2.1e-5 | direct | direct | detour | detour |
-| 2 000 | 4.1e-4 | direct | direct | direct | detour |
-| 10 000 | 2.1e-3 | direct | direct | direct | **direct** |
-
-**The same geometry builds more correctly the further it sits from the origin.** At 10 000 units the
-weld floor exceeds the T-junction tolerance, the band is empty, and every δ tested joins cleanly. This
-is float32 quantisation doing, by accident, the reconciliation job that no pass does on purpose.
-
-### What does and does not fix it
-
-| attempt | δ=1e-5 | δ=1e-3 |
-| --- | --- | --- |
-| weld the *source* at 1e-4 | **fixed**, direct crossing | no |
-| weld the *source* at 1e-2 | fixed | **fixed**, direct crossing |
-| `bt_mesh_bridge_islands` (step 0.01…0.5) | **fixed**, direct crossing | **no effect** |
-| bridging with `r = 0.4` | no | no |
-
-Two things worth extracting:
-
-* **Welding above `2δ` fixes Case C completely** — direct crossing, correct length. It is a pure
-  tolerance problem.
-* **Bridging is island-gated.** At δ=1e-3 the mesh is already nominally one island (via the end
-  stubs), so bridging sees nothing to bridge and does nothing. A *partial* connection defeats it.
-* **Erosion manufactures a `2r` gap.** Erosion (pass 6) runs *before* bridging (pass 8) and insets
-  each island by `r`, so two islands that were touching end up `2r` apart. With `r = 0.4`, bridging
-  only reconnects them once `max_step_distance ≥ 0.9`; at 0.5 it cannot, no matter the geometry.
-
----
-
-## 5. Two further defects found while investigating
-
-### D1 — overhead obstacles are carved as their convex hull
-
-[`clip_soup_against_overhangs`](build/clip_soup_against_overhangs.js) groups overhead triangles that
-share a (1 mm-quantised) vertex into one obstacle and takes **the convex hull of the group**. Anything
-concave, holed, or merely adjacent over-carves:
-
-| obstacle | probe | covered? | should be |
-| --- | --- | --- | --- |
-| L-shaped ceiling | `(12, 12)` — strictly in the notch | **no** | yes |
-| L-shaped ceiling | `(14, 11)` | **no** | yes |
-| ring / frame ceiling | `(10, 10)` — the middle of the hole | **no** | yes |
-| two 2×2 ceilings touching at a corner | `(9.5, 11)` — between them | **no** | yes |
-| control: single convex box | `(10, 10)` under it / `(5, 5)` clear | no / yes | correct |
-
-A doorway frame is a ring. A balcony is a ring. A row of touching pillars is one group. All of them
-remove walkable area that has nothing above it.
-
-**Fixed** in `fix(navmesh): an obstacle is carved as itself, not as its convex hull`. Minkowski dilation distributes over
-union — `(A ∪ B) ⊕ D = (A ⊕ D) ∪ (B ⊕ D)` — so subtracting each overhead triangle's *own* dilated
-footprint, sequentially from the running piece set, yields exactly the dilated true footprint of an
-arbitrarily concave obstacle. No grouping, no hull, no union-find, no 1 mm quantum. It costs more clip
-operations (one per overhead triangle rather than one per obstacle) and is the main perf question.
-
-Sequential subtraction matters: it keeps the result a *partition* of the triangle, so adjacent dilated
-footprints never produce edge-edge crossings — i.e. it does not reintroduce Case B inside the carve.
-
-The landed fix keeps the hull as a **fast path**, taken when the group's triangles tile it (compare the
-hull's area against the triangles' own). Every convex obstacle — tessellated or not — therefore takes
-the route it always did, face for face; only concave groups pay. Measured, 60×60 floor grid:
-
-| scene | before | after |
-| --- | --- | --- |
-| convex obstacles | 833 ms / 185 faces | 786 ms / **185** faces |
-| 24 L-shaped obstacles | 1268 ms / 523 faces | 1743 ms / 1216 faces |
-| tessellated ring overhang | 761 ms / 21 faces | **2343 ms** / 70 faces |
-
-Concave obstacles cost up to ~3× the build and leave 2–3× the faces, because they are no longer
-deleting the walkable area around themselves — the extra faces are recovered navmesh.
-
-### D2 — bridging inserts faces the climb filter would have rejected
-
-On the bridged 3-layer stack: 22 faces, of which **16 are steeper than `agent_max_climb_angle`, worst
-case 90°**. Nothing re-filters after bridging. `bt_mesh_compute_face_islands` reports **1 island**
-while `find_path` returns **no path** from the bottom layer to the top — island count and path
-reachability disagree, because the walk crosses vertical faces the query will not.
-
-This matters beyond the bug itself: **island count is not a sound proxy for reachability** once
-bridging is enabled, which affects how the tests in §7 should assert.
-
----
-
-## 6. Diagnosis
-
-| | what it really is | what would fix it | what would *not* |
-| --- | --- | --- | --- |
-| **A** | the occluder predicate is too narrow | add walkable surfaces to the occluder set | any tolerance |
-| **B** | no coplanar union exists | overlap resolution (clip or arrange) | any tolerance (verified) |
-| **C** | two tolerances with a hole between them, and neither is navigation-scale | close the hole; give the build one explicit reconciliation tolerance | bridging (island-gated); erosion order makes it worse |
-| **D1** | convex hull over a possibly-concave footprint | per-triangle dilate-and-subtract | — |
-| **D2** | bridging output is never re-filtered | re-apply the climb filter after bridging | — |
-
-A, B and C are not variants of one bug. They are the three ways an "already a manifold" precondition
-can be violated, and each is violated at a different layer of the stack.
-
----
-
-## 7. Proposal
-
-Staged so each stage stands alone and can be stopped after.
-
-### Stage 0 — make it visible (no behaviour change)
-
-Add a build-time **reconciliation report**: counts of (i) walkable faces with less than `agent_height`
-of walkable surface above them, (ii) pairs of walkable faces overlapping in the `up`-projection,
-(iii) boundary-vertex pairs separated by more than the weld and less than a navigation-scale
-tolerance, (iv) resulting island count. Surface it through the existing
-[`bt_mesh_validate`](../../../core/geom/3d/topology/struct/binary/query/bt_mesh_validate.js) channel or
-a returned struct.
-
-*Why first:* every one of these defects is currently silent. A level with a duplicated floor builds
-"successfully" and ships. This also gives the later stages their regression signal.
-
-**Effort:** ~1 day. **Risk:** none. **Un-skips:** nothing, by design.
-
-### Stage 1 — close the dead band, and name the tolerance
-
-Two parts.
-
-**1a. Weld, don't skip.** In `bt_mesh_resolve_t_junctions`, when a candidate falls within `t_margin`
-of an endpoint but is a *distinct vertex at a distinct position*, weld it onto that endpoint instead
-of skipping it. Same manifold guards as the split path.
-
-**1b. Give the build an explicit reconciliation tolerance.** Replace the implicit ladder with one
-named parameter — how far apart two surfaces may be and still be the same surface — derived the way
-the codebase already knows how ([`bt_mesh_relative_merge_distance`](../../../core/geom/3d/topology/struct/binary/io/vertex/bt_mesh_relative_merge_distance.js)),
-floored by float32 resolution, defaulted to something navigation-scale, and used by **a
-boundary-only stitch pass** (boundary vertices to boundary vertices, height difference also within
-tolerance) followed by fuse + T-junction resolve at the same number.
-
-Boundary-only is the point: interior tessellation is untouched, so nothing thin collapses.
-
-**Effort:** 1a ~half a day; 1b ~2–3 days with specs. **Risk:** see §8.1 — non-trivial.
-**Un-skips:** all 6 Case C tests, at any δ below the tolerance.
-
-### Stage 2 — one occlusion pass (fixes A *and* D1)
-
-Replace `clip_soup_against_overhangs`'s grouping+hull with per-triangle dilate-and-subtract (D1), and
-widen the occluder set to include **walkable surfaces above other walkable surfaces** (A):
-
-1. Project all source faces to `(u, v)`; BVH over their extents (the pass already builds one).
-2. For each walkable triangle `T`, gather occluders whose `(u, v)` extent overlaps.
-3. For each occluder `S`, compute the height difference over the *overlap polygon* — both are planar,
-   so the difference is linear there; evaluate at the overlap's vertices for an exact min/max, rather
-   than the current mean-height approximation.
-4. If `S` sits above `T` by less than `agent_height`, subtract `S`'s footprint (dilated by
-   `agent_radius`) from `T` using the existing `subtract_footprint`, sequentially over the running
-   piece set.
-
-Occlusion is tested against the **original** face set, not the surviving one, so the result is
-order-independent by construction — which is what the green control in §2 asserts.
-
-**Effort:** ~1 week. **Risk:** see §8.2. **Un-skips:** all 7 Case A tests.
-
-### Stage 3 — coplanar overlap resolution (fixes B)
-
-Same pass, additional branch: when the height difference over the overlap is *below* the
-reconciliation tolerance, the two are the same layer, and one must yield — subtract one from the other
-so the result is a partition, then let weld/fuse/T-junction join the conforming seams.
-
-The winner must be chosen by a **deterministic geometric key** (e.g. higher first, tie-broken on
-`(u, v)` centroid order), never by soup order.
-
-**Effort:** ~1 week on top of Stage 2, plus hardening. **Risk:** highest — see §8.3.
-**Un-skips:** all 5 Case B tests.
-
-### Summary
-
-| stage | fixes | effort | risk | un-skips |
-| --- | --- | --- | --- | --- |
-| 0 report | — | ~1d | none | 0 |
-| 1 dead band + tolerance | C | ~3d | medium | 6 |
-| 2 occlusion pass | A, D1 | ~1w | medium-high | 7 |
-| 3 coplanar resolution | B | ~1w+ | high | 5 |
-| (D2 re-filter after bridging) | D2 | ~half a day | low | 0 (needs its own test) |
-
----
-
-## 8. Adversarial review of the proposal
-
-*Written against my own proposal. Where I could not resolve an objection, it stays unresolved.*
-
-### 8.1 Against Stage 1
-
-**The endpoint exclusion is not a bug, and 1a may break its actual invariant.** The docstring is
-explicit that vertices near an endpoint "are already as connected as the split could make them" and
-that the alternative is a non-manifold edge. Turning a skip into a *mutation* changes a no-op into
-geometry movement. **Blast radius:** `bt_mesh_resolve_t_junctions` has a second production caller,
-[`atlas_mesh_weld_colocals.js:35`](../../../core/geom/3d/atlas/io/atlas_mesh_weld_colocals.js:35),
-which passes `max_distance * 100` — a *much* larger tolerance, so 1a would weld far more aggressively
-there than in the navmesh. That caller was not investigated. **1a must be opt-in per call, or it is a
-UV-atlas regression waiting to happen.**
-
-**1a has a concrete correctness hazard.** The function's own comment says the vertex BVH never needs
-rebuilding "because splitting only ever cuts an edge at a vertex that is already in it" — i.e. splits
-only *add*. Welding *removes* vertices, leaving stale leaves in a tree that is built once and reused
-across the `changed` loop. That is exactly the class of bug the existing "skip unlinked vertices"
-guard was added for. This needs either a rebuild or a liveness check on every candidate.
-
-**1a fixes a hole and leaves a lumpy surface.** After it, the effective weld tolerance is `1e-4` *near
-boundary-edge endpoints* and `1e-6` everywhere else. Two vertices 1e-5 apart that are not near any
-edge endpoint still will not weld. That is a strictly weirder tolerance model than the one we have,
-and it is not obviously better to have an irregular tolerance than a known gap.
-
-**1b's tolerance is unanswerable in the abstract, and the doc does not answer it.** Too small and
-δ=1e-3 stays broken; too large and genuine narrow features get welded shut. I asserted "a 2 cm slot
-is navigationally irrelevant for a 0.4 m agent" — but the navmesh is also used for area queries and
-nearest-surface snapping, not only for path width, so that argument is weaker than it sounds. **No
-number is proposed here on purpose; picking one without a corpus of real levels would be guessing.**
-
-**1b amplifies an existing order-dependence.** `MANIFOLD_COMPARISON` records that meep's vertex weld
-is order-dependent where manifold's is deterministic. Raising the tolerance makes *which* vertex wins
-a merge matter more often and over larger distances. Given that order-independence is exactly the
-property the Case A control locks in, making a different part of the build *more* order-dependent is
-an uncomfortable trade.
-
-**Boundary-only stitching does not generalise.** It works on the wedge because both ridges are single
-full-depth boundary edges with matching subdivision. If the two sides are tessellated differently, the
-stitch pairs vertices badly and the T-junction pass has to clean up behind it at the same tolerance —
-untested, and the interaction of "weld at T, then split at T" is not obviously convergent.
-
-**And the honest one:** float32 quantisation is currently doing this job by accident (§4), and it does
-it *better as coordinates grow*. Stage 1 replaces an accident with a policy — but if any level relies
-on the accidental behaviour at large coordinates, Stage 1 changes its navmesh.
-
-### 8.2 Against Stage 2
-
-**The biggest hazard is semantic, not geometric.** The build cannot distinguish collision geometry
-from render geometry. Today only downward faces occlude, which is conservative. After Stage 2 **any
-upward-facing surface culls what is under it** — including one-sided water planes, decals, projected
-shadow-catchers, and skirts. A level that builds fine today could lose large amounts of walkable area,
-and the failure is silent. This alone argues Stage 2 should be **opt-in** for at least one release,
-which weakens its value considerably: a fix nobody turns on fixes nothing.
-
-**"Cull the lower" conflicts with `agent_max_step_height`.** If two floors are 5 cm apart and the
-agent can step 30 cm, is the lower one an unreachable ghost (cull) or a step the agent may stand on
-(keep and connect)? Recast answers this with two separate constants and a span-merge before the
-height filter. The proposal has only the height filter, so a low step under a low ceiling gets culled
-where Recast would merge it. **This is a genuine gap in the design as written.**
-
-**The perf story is asserted, not measured.** Today the carve is `O(m log k)` with `k` = obstacle
-*groups* — small. Stage 2 makes it `O(m log m)` with `m` = walkable triangles, and every triangle is
-both subject and clipper. Measured baseline: a 60×60 grid (7 216 source triangles, 8 obstacles) builds
-in **~984 ms** today, roughly linear in source triangles. Stage 2 plus D1's per-triangle footprints
-adds clip work proportional to actual overlap; on clean input that is near zero, but on the pathological
-input this whole document is about — a fully duplicated floor — it is quadratic. **No bound is
-proposed. That is a real hole.**
-
-**D1's fix could be a regression against a test that currently passes.**
-[`navmesh_obstacle_outline.spec.js`](navmesh_obstacle_outline.spec.js) guards that the hole boundary is
-a *faithful* agent-radius offset. The `(A∪B)⊕D = (A⊕D)∪(B⊕D)` argument says per-triangle dilation is
-exactly equivalent — but that identity is about the *sets*, and the implementation approximates each
-corner arc with `CORNER_SEGMENT_ANGLE` segments. Many small dilated triangles produce many more arc
-approximations than one dilated hull, and the error does not obviously cancel. **Needs measuring
-against that spec before believing the identity argument.**
-
-**Reusing `subtract_footprint` triangle-against-triangle is unverified.** It is currently only ever
-called with dilated, many-sided, rounded footprints. `push_outside_piece`'s seam-conformance logic is
-written in terms of "the footprint edge's own endpoints", which for a bare triangle are its corners —
-plausible, but the function is not exported and was never exercised that way. Any estimate that
-assumes free reuse is optimistic.
-
-### 8.3 Against Stage 3
-
-**The project already decided against this.** `MANIFOLD_COMPARISON_2026_08_01.md` ranks 2D polygon
-boolean as **P4 #11** — "Big… only if the domain demands it" — and notes manifold spends ~70 KB and
-years of corpus hardening on it. Stage 3 is a hand-rolled subset of exactly that, written to fix an
-input error. **Proposing it here is in tension with a decision the repo already made deliberately, and
-this document does not present new evidence strong enough to overturn it.**
-
-**Clipping is not union, and the difference shows up at the seam.** Subtracting T from S leaves a seam
-that must conform for weld/fuse to join it. That is precisely the T-junction problem, at a tolerance
-that Stage 1 has just been fiddled with. Two half-fixes interacting at the same seam is how the
-current dead band came to exist in the first place.
-
-**Piece blow-up is worse here than in Stage 2.** Every overlapping triangle pair can split a piece
-into up to `fp_n` pieces, and coplanar overlap means *every* triangle of one sheet overlaps several of
-the other. A duplicated 10 k-triangle floor is not a contrived input — it is the exact bug being fixed.
-
-**The winner rule is arbitrary and will leak.** "Higher first, tie-broken on centroid order" is
-deterministic but geometrically meaningless for exactly-coplanar input, and any tie-break on
-floating-point centroids is one ULP away from flipping. Determinism under *rebuild* is easy;
-determinism under *tiny geometry edits* is what level designers actually notice.
-
-### 8.4 Against the investigation itself
-
-**The tests encode choices, not just facts.** "The topmost layer wins" and "area equals the union" are
-*my* reading of correct. A project could legitimately decide that stacked single-sided planes are
-caller error and should assert instead. Fifteen skipped tests look like fifteen bugs; some fraction of
-them are really unstated-requirement disagreements.
-
-**Two metrics are shakier than they look.** `coverCount` is edge-sensitive — three of my early probe
-points landed exactly on triangle diagonals and inflated the count; the spec now samples off-edge, but
-the metric stays fragile. And per §5/D2, **island count is not reachability** once bridging is on, so
-the Case A and Case C island assertions are proxies, not proofs; the path assertions are the real ones.
-
-**Path length as a correctness proxy has a blind spot.** `toBeCloseTo(16, 1)` would pass a path that
-crosses the ridge in the wrong place but happens to be the right length. The control test also asserts
-the turn is *on* the ridge; the other Case C tests do not.
-
-**What would falsify most of this document:** if real source geometry for this project is always closed
-solids from a modelling package, Case A is unreachable in practice (the §2 control shows closed slabs
-work), D1 becomes the most valuable finding here, and Stages 2–3 are largely wasted effort. **I do not
-know which it is, and that question dominates the value of everything after Stage 1.**
-
----
-
-## 9. Recommendation
-
-*Status against each item is marked. Only item 5 was executed.*
-
-1. ☐ **Do Stage 0.** It is cheap, risk-free, and it answers the question that decides everything else:
-   *how often does real geometry actually hit these?* Run it over the project's actual levels.
-2. ☐ **Do the D2 re-filter** (~half a day) — bridging emitting 90° faces is unambiguous.
-3. ☐ **Do Stage 1a only if it can be made opt-in per call site**, given the atlas caller, and only with
-   the BVH staleness hazard addressed. Otherwise hold.
-4. ☐ **Hold Stage 1b** until Stage 0 produces a distribution of real separations. Picking the tolerance
-   without that is guessing, and this document says so rather than guessing.
-5. ☑ **DONE — Split D1 out of Stage 2 and do it on its own.** It is a real, currently-shipping correctness bug
-   with a small, self-contained fix and one caller. It does not need the occlusion widening.
-6. ☐ **Hold Stage 2's occlusion widening** behind the answer to §8.4 — closed solids or not.
-7. ☐ **Do not do Stage 3** on this evidence. If coplanar overlap turns out to be common, the honest
-   answer is the one `MANIFOLD_COMPARISON` already gives: a real 2D boolean, or reject the input.
-
-The 15 tests are `test.skip`, not red. They document behaviour that is currently wrong without
-standing between CI and the next real regression, and three of the four decisions above are
-"measure first".
-
----
-
-## Appendix A — reproducing
-
-```bash
-npx vitest run src/engine/navigation/mesh/navmesh_overlapping_surfaces.spec.js --reporter=verbose
-```
-
-5 controls pass, 15 are skipped. Delete a `.skip` to see the case it describes fail; the value observed
-today is recorded next to each expectation. `src/engine/navigation` is otherwise green.
-
-## Appendix B — measurements
-
-Build scale (flat grid + 8 box obstacles, `r = 0.4`, `h = 1.6`):
-
-| grid | source tris | navmesh faces | build |
-| --- | --- | --- | --- |
-| 10×10 | 216 | 24 | 100 ms |
-| 20×20 | 816 | 130 | 216 ms |
-| 40×40 | 3 216 | 167 | 494 ms |
-| 60×60 | 7 216 | 185 | 984 ms |
-
-Erosion / bridging interaction (Case C, δ=1e-5, `r = 0.4`):
-
-| `max_step_distance` | islands | path |
-| --- | --- | --- |
-| 0.5 | 2 | none |
-| 0.9 | 1 | found (detour) |
-| 1.5 | 1 | found (detour) |
-
-— i.e. reconnection requires `max_step_distance ≳ 2r`, because erosion created that gap.
-
----
-
-## 10. Adversarial review of the change that landed
-
-*The D1 fix only. Written against it, after it was written.*
-
-### What was attacked, and what held
-
-| probe | result |
-| --- | --- |
-| convex obstacle, 2 triangles vs. tessellated into 32 | identical face count and area — the fast path is genuinely untouched |
-| source triangle order shuffled 4 ways | identical faces / area / islands every time — deterministic |
-| non-default `up` (+X), scene properly rotated | identical faces / area / islands to the +Y build |
-| obstacle tilted so its skirt acquires a downward normal | same carve as the flat lid, no fragmentation |
-| duplicated obstacle arm | carved correctly — duplication pushes the group to the per-triangle route |
-| whole repo suite | 13 925 pass, 0 fail (the 15 Case A/B/C tests are skipped) |
-
-Two of my own probes were wrong before the code was: a "rotation" that was actually a reflection (it
-flips every winding, turning floors into ceilings), and a filler triangle wound upward, which made it
-walkable surface rather than an obstacle. Both looked like dramatic failures of the fix. Neither was.
-
-### What did not hold
-
-**The tiling test can be defeated, and I built the input that does it.** L-shaped arms of 16 + 12 = 28
-under a hull of 46; add 18 of *duplicate* overhead area lying inside that hull and `member_area` reaches
-46 without the union growing at all. The guard accepts the hull and over-carves: area 354 where 372 is
-correct. Confirmed by construction, not by argument.
-
-It is left unfixed and documented in the code. No test on areas alone can catch it — `member == hull`
-exactly is what the fooling input produces, so distinguishing it needs a real union. The cost of being
-fooled is the hull carve this always did, i.e. no worse than before the change, and every non-exact
-duplication falls to the per-triangle route, which is correct. Fixing it properly means the 2D boolean
-that §8.3 argues against.
-
-### What remains unverified
-
-* **The perf figure is one machine, one shape of scene.** ~3× on a large tessellated concave overhang
-  is measured; how often real levels contain one is not known. This is the same question Stage 0 exists
-  to answer.
-* **Fragmentation is not bounded.** 24 L-shaped obstacles go from 523 to 1216 output faces. Most of
-  that is recovered walkable area, but some is extra seams from subtracting many small footprints
-  instead of one large one, and `bt_mesh_simplify_by_error` runs at only `0.05 × agent_radius`. No
-  measurement separates the two.
-* **A sub-`AREA_EPS` behaviour change.** `push_footprint` drops footprints under 1e-9 of area, where
-  the hull path previously kept any hull with ≥ 3 vertices. That is an obstacle tens of micrometres
-  across, and the reason for dropping it is that its winding is not reliable enough to dilate. Real,
-  documented, not believed reachable.
-* **The `up`-agnosticism rests on one probe.** No spec in the tree exercises a non-default `up` through
-  the obstacle carve; `NavigationMesh.spec.js:695` is the only place `up` is overridden at all.
-
-### The honest summary
-
-The change fixes a real defect, is deterministic, leaves the convex path bit-identical, and costs build
-time on exactly the scenes that were previously wrong. Its guard is a heuristic with a constructible
-counter-example whose consequence is the old behaviour. That is a reasonable trade for a conservative
-change; it would not be a reasonable trade for a load-bearing one.