@woosh/meep-engine 3.1.0 → 3.3.0

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

@@ -0,0 +1,661 @@
+# 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.