@woosh/meep-engine 3.60.4 → 3.60.6

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

@@ -1,229 +0,0 @@
-# Navmesh shortest-path: goal-directed, early-terminating, edge-based Eikonal A*
-
-## Where we are
-
-`bt_mesh_face_find_path` returns the face **corridor** that
-`NavigationMesh.find_path` feeds to `funnel_string_pull`. The funnel produces the exact
-shortest path *inside* the corridor, so the corridor must **contain the true geodesic** or the final
-path is permanently too long.
-
-The original implementation ran A* on the face dual graph using **centroid-to-centroid distance**.
-That metric is shape-sensitive: across thin/sliver triangles the centroid path zig-zags so hard that a
-dense patch looks more expensive than detouring around large skirt triangles, so it routed *around*
-finely-tessellated regions (measured 1.2–1.55× the straight line). `bt_mesh_face_find_path.shortest_path.spec.js`
-locks this down (flat convex mesh ⇒ straight line is the true shortest path; every pair must be within
-1% of it).
-
-The current implementation fixes correctness with an **exact geodesic field**:
-
-1. `collect_island` — BFS the whole connected component from the start (reachability + vertex set).
-2. `bt_mesh_build_boundary_distance_field` — Fast Marching (Eikonal, Kimmel–Sethian) over **every**
-   island vertex, seeded at the goal face ⇒ true along-surface distance-to-goal at each vertex.
-3. `trace_corridor` — descend the field's in-plane gradient from the start (hugs the geodesic), with a
-   `search_corridor` best-first fallback for the cases the gradient can't follow cleanly (winding
-   around a hole).
-
-This is correct (all 92 navigation tests pass) but **per query it touches the entire connected
-component**: O(component) flood-fill + O(component · log) full Eikonal solve, regardless of how close
-start and goal are. On a large navmesh that is a real regression versus the old localized A*. The
-benchmark (`bt_mesh_face_find_path.bench.spec.js`, behind `.skip`) measures exactly this.
-
-## Target design
-
-A single **goal-directed, early-terminating** Eikonal search, with the corridor reconstructed from
-**edge/portal** parents rather than the fragile gradient trace.
-
-### Phase 1 — goal-directed, early-terminating fill (the big perf win, low risk)
-
-Replace `collect_island` + full `bt_mesh_build_boundary_distance_field` with one Fast Marching pass
-that is ordered as **A*** and stops as soon as it has resolved the start:
-
-- Seed the Eikonal wavefront at the **goal** face's three vertices (distance 0).
-- Order the heap by `f = g + h`, where `g` is the tentative geodesic distance-to-goal and
-  `h(v) = ‖v − start_centroid‖` (straight-line distance to the start). Euclidean `h` is **admissible
-  and consistent** for geodesic distance (geodesic ≥ Euclidean, and Euclidean obeys the triangle
-  inequality), so a popped vertex has its **final** `g` — exactly what the Eikonal update needs from
-  its inputs. The heuristic only changes *pop order*, pulling the front toward the start so we explore
-  the start↔goal "ellipse" instead of the whole component.
-- **Early termination:** stop once all three vertices of the **start** face have been popped (frozen).
-  Every vertex on the geodesic corridor has `g ≤ g(start)` and `f ≤ g(start)` (consistent `h` ⇒ on an
-  optimal path `f` is constant `= total`), so when the start is frozen the whole corridor is already
-  frozen. Reachability falls out for free: if the heap drains without freezing the start face, there is
-  no path ⇒ return 0 (drops the separate `collect_island` BFS entirely).
-
-Keep `trace_corridor` + `search_corridor` unchanged. Both only ever move *downhill* (toward smaller
-distance-to-goal), and the downhill region is exactly what the early-terminated fill computed, so they
-operate entirely within the resolved ellipse — including the around-a-hole geodesic, whose faces all
-satisfy `g ≤ g(start)` and are therefore frozen.
-
-**Causality / correctness note to honour:** the popped-is-final guarantee holds only if Eikonal
-updates use **frozen** inputs. Pure-`g` (and consistent `g + h`) ordering already makes
-*popped ⇒ final* because every update produces a value `≥` the popping vertex's `g` and the heap pops
-non-decreasing. The Dijkstra edge-relaxation fallback (for not-yet-fronted / obtuse cases) only ever
-supplies an upper bound that a later Eikonal update lowers *before* the vertex is popped, so it does
-not violate finality. This must be verified, not assumed, when the fill is split out from
-`bt_mesh_build_boundary_distance_field` (whose label-correcting full solve never relied on early-stop
-finality).
-
-### Phase 2 — exact any-angle (Polyanya), standalone
-
-The original sketch here was "swap the corridor extractor for a portal-based search." That was tried
-(descend the lowest-field portal, re-enter at its midpoint) and **did not move the ~2% around-obstacle
-gap** — see `_diag` runs: the corridor `touchesCornerL=true touchesCornerR=false`, i.e. it cuts one
-reflex corner on the descending side. The root cause is structural: the corner-*cutting* corridor is
-shorter by *every* corridor metric (centroid, portal-midpoint, field); only the funnel knows the
-corner-*touching* corridor yields a shorter final path. So no corridor-extraction swap can be exact —
-you must run the funnel *inside* the search.
-
-That is **Polyanya** (Cui/Harabor/Grastien, IJCAI 2017): A* over (root, interval-on-edge) search nodes.
-The cone from `root` through an interval is projected into the next triangle and clipped against its
-two far edges; visible pieces keep `root` (observable), pieces hidden behind a **reflex corner** at an
-interval endpoint turn there (the corner becomes the new root, non-observable). It returns the exact
-point path, turning only at obstacle corners — no corridor, no funnel post-pass.
-
-Built as a **standalone 2-D module** `bt_mesh_face_find_path_polyanya` (xy-plane; not yet wired into the
-3-D `NavigationMesh`). Two things were essential to get it correct *and* terminating:
-- **Reflex-corner restriction:** only boundary vertices whose incident-triangle angles sum to > 180°
-  are turning roots. Admitting flat/convex boundary vertices makes the search blow up combinatorially.
-- **Per-(edge, root) interval dedup:** a fixed root implies a fixed `g`, so the first node to cover a
-  stretch of an edge is optimal there; later nodes are clipped to the still-uncovered part. Without
-  this the wavefront re-floods every edge at the same `f` (the straight-line heuristic ignores
-  obstacles) and never terminates.
-
-## Sequencing
-
-1. **[done]** Land this plan + the benchmark (behind `.skip`) + the geodesic implementation. Baseline
-   (full-island `bt_mesh_build_boundary_distance_field`, ~100k-face mesh): **mean 2714 ms/search**,
-   ~0.4 searches/s. A large part of that was `insert_or_update`'s **O(n) linear-scan decrease-key**,
-   making the fill O(V²).
-2. **[done]** Phase 1. Self-contained goal-directed fill with **lazy-deletion** heap (kills the O(V²))
-   and early termination, replacing `collect_island` + the full solve. Same mesh: **mean 42.5 ms/search**
-   (p50 36, p99 126, min 0.17 for local queries), ~24 searches/s — **~64× faster**. `shortest_path.spec`
-   and all 92 navigation tests stay green; the gradient trace + graph-walk fallback are kept, with a
-   full-field re-solve as the backstop for under-resolved hole-winding corridors.
-3. **[done]** Phase 2. Standalone exact `bt_mesh_face_find_path_polyanya` (2-D). Validated by
-   `bt_mesh_face_find_path_polyanya.spec.js`: exact on analytic oracles (straight line, single hole,
-   U-barrier, asymmetric wall — all corner-hugging to 4 decimals) and, over 60 random pairs on a holed
-   mesh, never longer than the FMM+funnel path and never shorter than the straight line (strictly
-   shorter on detours). Benchmark on the same ~100k-face mesh: **mean 7.1 ms/search** (p50 3.3, p90 5.5,
-   p99 9.5), ~141 searches/s — faster *typical* than Phase 1 because most pairs have line-of-sight (avg
-   2.0 path points) and Polyanya short-circuits, where the FMM fills the whole ellipse regardless.
-   **Caveat:** a heavy tail (originally max ~6.2 s) on rare far pairs that force long, corner-rich
-   detours.
-
-   **Optimisation pass (done):** made the hot path allocation-light — `reserve` rewritten to flat,
-   in-place range arrays writing into a scratch buffer (no per-call uncovered/merged/`[lo,hi]` arrays,
-   no sort), and the string dedup key replaced by nested numeric-keyed Maps (the crossed edge is
-   uniquely `(from_face, neighbour)`). Same ~100k-face mesh: **mean 4.7 ms** (p50 2.0, p99 6.8), tail
-   **6.2 s → 3.35 s** (~33% faster mean, ~46% lower tail); `spec` stays green. The residual tail is now
-   dominated by node *count* (the Euclidean heuristic is weak on long forced detours), not per-node
-   cost.
-
-   **GC-free node storage (done):** search nodes moved out of per-node object literals into fixed
-   16-word records in a flat `ArrayBuffer` (uint32 + float32 views overlaid), referenced by integer id,
-   with the open list a `Uint32Heap4` (id + f32 score) instead of an object heap. Allocation is a
-   monotonic bump counter reset per query; nodes are never released mid-search, so there is no free list
-   and no occupancy bookkeeping — the buffer only ever grows (by doubling, copying the records over) and
-   the two cached views are re-read after a grow. This is a deliberate **latency**, not throughput, choice: it is a touch slower
-   on mean throughput (**~4.7 → ~6.0 ms**, p99 6.8 → 18.3 on the bench — object literals are cheap and
-   the typical query is tiny, avg ~2 points, so there was little GC to remove and the typed-array
-   bookkeeping costs more than it saves *in aggregate*), but pathfinding is a hot path and the point is
-   to emit **zero garbage** so it never triggers a GC pause that jitters the rest of the engine's frame.
-   Unpredictable pauses are worse than a predictable constant cost here. (Storage was first prototyped on
-   `BinaryElementPool`, but the never-free, bump-allocated access pattern reads none of its allocator —
-   no `allocate()`/`release()`/`is_allocated()`/`clear()` — so it was reduced to the raw `ArrayBuffer` it
-   degenerates to; the `allocate()`/`clear()` pool variants measured slower still.)
-
-   **3-D / intrinsic (done):** `bt_mesh_face_find_path_polyanya` takes 3-D start/goal and writes a 3-D point
-   path. It assumes **no global "up"** — the search follows the surface by UNFOLDING. Each node carries the
-   2-D positions of its entry edge in a frame accumulated along its own corridor; expanding flattens the
-   next triangle into that frame by placing the apex from its two 3-D edge lengths (an isometry of the
-   triangle), on the side fixed by the face winding. So frame distances are true geodesic distances and `g`
-   is **exact on a curved/folded surface**, not just a planar one. Corners are detected from the 3-D
-   incident-angle sum (also intrinsic). The goal has no fixed position across frames, so the A* heuristic is
-   the exact straight-3-D-chord shortest root→interval→goal (a lower bound on the geodesic, hence
-   admissible); a terminal's *exact* cost unfolds the goal into that node's frame (barycentric). Waypoints
-   lift back to 3-D from vertex ids — turning corners are mesh vertices (exact), start/goal are the given
-   points, a goal-edge bend is the exact point on that edge. Validated: flat oracles still exact; a
-   rigidly-rotated holed mesh reproduces the flat path R-for-R (rotation-invariance, no up passed); and a
-   developable curved strip's straight geodesic crosses every crease with **no spurious turn** (the
-   unfolding flattens several non-coplanar faces into one frame). `e1 = up × …` and any per-face/per-region
-   up decision are gone.
-
-   **Precision fix (with the 3-D work):** the rotation test surfaced a latent bug — the search's `1e-9`
-   tolerances assume exact coordinates, but vertices are stored **float32**, so once a mesh is *not*
-   axis-aligned its edge fractions carry ~`coord·2^-23` quantisation noise, far above `1e-9`. Coverage
-   intervals then fail to merge, the same edge stretches re-cover as slivers, and the wavefront floods
-   without converging. Fix: a parameter-space tolerance `PEPS = 1e-4` (edge fractions, interval coverage,
-   vertex snapping) sized to float32 precision, kept separate from the tight area-sign `EPS`. Never moves a
-   waypoint (corners are exact vertex positions). The old axis-aligned integer-grid tests never exposed this
-   because integers are exact in float32; the standing rotation test now jitters the lattice off the grid (a
-   perfectly integer lattice rotated exactly onto an axis is a measure-zero collinearity degeneracy that
-   does not occur on real navmeshes).
-
-   **Cost of going intrinsic (measured):** full ~100k-face bench, intrinsic — **mean 9.1 ms/search**
-   (p50 3.9, p90 14.2, p99 40.9, max 4.47 s), 100 % found, ~110 searches/s. Versus the previous
-   single-plane-projection build on the same mesh: object-heap **4.7 ms** (p50 2.0, p99 6.8) and GC-free
-   pool **~6.0 ms** (p99 18.3). So intrinsic is ~1.5–2× slower in the mean and markedly heavier in the
-   tail (p99 6.8 → 40.9). The whole gap is the **heuristic**: the straight-3-D-chord lower bound ignores
-   on-surface curvature, so it is weaker than the old in-plane touch distance and expands more nodes. The
-   per-node work (an extra unfold + a 3-D touch) is minor by comparison. This is the price of "follow face
-   normals" with no up assumption, and it buys exactness on curved surfaces.
-
-   **Intermediate-node pruning — tried, does NOT pay off (two benches).** Implemented the Anya/Polyanya
-   pruning (collapse single-observable-successor "pass-through" nodes inline: no heap, no heuristic, no
-   alloc), exact and `spec`-green. On the open Eden-blob bench it was flat in the bulk (mean/p50/throughput
-   unchanged) with only a tail improvement (max 4.47 → 2.38 s); on a deliberately corridor-heavy mesh
-   (`bt_mesh_face_find_path_polyanya_rooms.bench.spec.js`, below) a deterministic same-queries measure was **identical**
-   (40 queries: 4261 ms baseline vs 4246 ms pruned). Root cause: the weak heuristic floods the *open
-   rooms*, where the cone fans into many successors; the narrow corridors where chaining fires are a small
-   fraction. Pruning attacks per-node overhead, but the bottleneck is the *node count* the heuristic
-   forces. Not committed.
-
-   **Rooms-and-corridors bench (`bt_mesh_face_find_path_polyanya_rooms.bench.spec.js`, `.skip`).** 25×25 square rooms,
-   each at one of 5 random heights, connected N/S/E/W by narrow ramped corridors (~99k faces, genuinely
-   non-planar). It dramatises the heuristic weakness: **mean ~2.4 s/search** (vs 9 ms on the open blob),
-   ~0.4 searches/s, because the straight-3-D-chord estimate cuts through walls and across levels, so A*
-   explores most of the mesh. This is the standing stress case for any heuristic work.
-
-   **Wired into `NavigationMesh.find_path` (done).** It replaces the face-corridor + funnel string-pull:
-   snap start/goal via the BVH, then run Polyanya. One robustness measure was needed — the snapped points
-   are pulled a hair (1e-3) toward their face centroid, because the cone search degenerates when a root or
-   the goal lies exactly on a triangle edge, which snapped grid-aligned queries frequently do (the funnel
-   sidestepped it by orienting on face normals, not a cone). Full `navigation/mesh` suite stays green.
-
-   **Path validation + a finding (done).** Both benches keep their paths and validate them against a
-   BVH: `bt_mesh_segment_penetrates_surface` flags any piece that crosses a triangle interior transversally, and
-   sampling reports how far each piece strays off the surface. The finding: a **corner-only** waypoint path
-   is correct only AT its turning corners, so the straight chord between two corners on different levels
-   flew over / cut through the ramped geometry between them (the funnel had the same property) — on the
-   multi-level rooms bench ≈4 % of pieces penetrated, maxOff up to the full height range.
-
-   **Surface-following output (done — fixes the above).** The reconstruction no longer emits bare corner
-   waypoints; it emits the point where the geodesic crosses each face-boundary edge (`line(root→next) ∩
-   edge`, lifted to 3-D by lerping the edge endpoints), plus the turning corner at each root change. Every
-   emitted segment therefore lies within a single triangle, so the path neither flies over a convex crease
-   nor tunnels through a concave fold. Two subtleties: (1) the geodesic often grazes a shared grid vertex,
-   where `line ∩ edge` reports no crossing (-1, both endpoints on one side of the line) — snapped to the nearer endpoint;
-   (2) flat stretches would otherwise gain a point at every interior edge, so **collinear runs are collapsed
-   to their endpoints** (perpendicular offset / span < `COLLINEAR_EPS = 1e-4`). The flat-mesh output is thus
-   unchanged (minimal corner polyline — the sparse-output specs still hold); subdivision only adds points
-   where the surface actually folds. **Both benches now ASSERT `penetrating === 0 && offSurface === 0`**
-   (the rooms bench flipped from report to assert), and `bt_mesh_face_find_path_polyanya.spec.js` adds
-   minimal surface oracles: two triangles folded into a convex ridge and a concave valley, and a 3-triangle
-   folded strip — each asserts the path sticks to the surface (`maxOffSurface < 1e-3`) and bends over the
-   crease rather than chording across it.
-
-   Remaining lever: a tighter still-admissible heuristic is now clearly **the** win — the rooms bench shows
-   the chord heuristic is catastrophic on walled/multi-level meshes; candidates are a cached lower-bound
-   distance-to-goal field (one FMM-style sweep per query, like `bt_mesh_face_find_path`) or an
-   obstacle-aware estimate.
-
-## Gates
-
-- **Correctness:** `bt_mesh_face_find_path.shortest_path.spec.js` (true shortest path on a flat convex
-  mesh) + the existing `bt_mesh_face_find_path.spec.js` + the `NavigationMesh` / `navmesh_*` suites
-  (holes, gaps, erosion — the fallback's job).
-- **Performance:** `bt_mesh_face_find_path.bench.spec.js` — random searches on a ~100k-face seeded
-  mesh for a fixed wall-clock budget; reports throughput and per-search timing percentiles. `.skip` by
-  default (not a quality gate); run on demand.

package/src/engine/network/CONGESTION_CONTROL.md

@@ -1,87 +0,0 @@
-# Congestion control — deferred design note (review item #6)
-
-**Status: NOT IMPLEMENTED. Deliberately deferred.** This note records the design
-and the decision so it isn't re-litigated. It came out of the comparative review
-against Valve GameNetworkingSockets (GNS), 2026-06.
-
-## The gap
-
-There is no congestion control on the meep-owned send path. Each peer's `Connection`
-(`MESSAGE_TRANSPORT.md`) paces its reliable USER and BULK lanes with a token bucket at a fixed
-rate — a ceiling, but not one that learns: loss never reduces it. The action stream, AUTH_STATE and
-the CONTROL lane are not paced at all. `NetworkPeer.flush_outbound` packs
-`[last_acked+1 .. current]` for every peer every tick, so under a constrained link output *rises*
-exactly when the path sheds load (the repacked unacked frames plus reliable re-sends stack on top) —
-classic self-inflicted bufferbloat with no AIMD backoff. The token bucket is where a governor would
-set the rate.
-
-GNS, by contrast, paces every packet through `SNP_TokenBucket_Accumulate` at a
-`m_nCurrentSendRateEstimate` that is RFC3390-seeded, shrinks on loss, grows on
-clean acks, and is clamped to `[SendRateMin, SendRateMax]` with a bounded burst.
-
-## Why it's deferred (not "won't do")
-
-The criticality is **conditional on transport choice**:
-
-- **WebRTC / WebSocket / WebTransport** ride DTLS-over-SCTP / TLS-over-TCP. Those
-  layers already do congestion control. On the transports the project actually
-  ships to browsers, this gap is **masked** — adding a second governor on top
-  would fight the underlying one.
-- **NodeUDP / Simulated** are raw datagrams with none of that. These are the
-  *only* transports where #6 bites, and they're scoped as test/LAN today.
-
-So the payoff is low until raw UDP is shipped to real, constrained, or untrusted
-networks. The cost to build correctly is high (see below). That trade puts it
-behind the cheaper items (liveness reaping, in-flight cap, resume ring-floor),
-which are all landed.
-
-## What it would cost to *run* (cheap)
-
-Per connection:
-
-- Token bucket: `tokens`, `rate_estimate`, `last_refill_ms` — ~32 B.
-- Smoothed RTT / RTO (EWMA + variance, RFC6298 shape) — ~24 B.
-- RTT-from-acks needs a send-timestamp per in-flight seq — ~8 B × in-flight.
-- If `PriorityAccumulator` is wired per-peer for fairness when the bucket binds —
-  ~16·`type_count` B (T=50 → ~800 B).
-
-Total ≈ **100 B – 1 KB per peer** (≈ 0.1–1 MB at 1000 peers). ALU is **tens of
-FLOP per peer per tick** (refill + check + deduct; EWMA + AIMD on ack/loss;
-`PriorityAccumulator.sorted_descending` is allocation-free and only runs when the
-bucket binds). Well under 0.1% of a core even at 1000 peers. Cycles and bytes are
-not the obstacle.
-
-## What it would cost to *build* (the real obstacle)
-
-1. **RTT plumbing.** Nothing currently feeds RTT into the live path —
-   `time/TimeSync.js` is built but wired to nothing, and it tracks *min* RTT
-   (SNTP), not the *smoothed* RTT a governor needs. You must add either explicit
-   ping/pong (extra packets) or derive RTT from ack timing with Karn's algorithm
-   (exclude retransmit-ambiguous samples), which means stamping a send time per
-   in-flight seq.
-2. **Latency / buffering interaction.** Pacing deliberately *delays* sends when
-   the bucket is empty. That's the point (avoid self-inflicted loss) but it
-   changes timing and interacts with client prediction / reconciliation.
-3. **Determinism.** The rate decision is wall-clock driven and MUST stay on the
-   transport side, never the deterministic sim path, or it breaks the
-   determinism contract (there is a standing determinism gate). `TimeDilation`
-   already regulates the sim *tick rate* against input-buffer depth — that is
-   orthogonal application-tier flow control, **not** a byte-pacing substitute,
-   and the two must not be conflated.
-
-## Design sketch (if/when built)
-
-- Add a per-connection rate governor on the UDP transport path, gating
-  `NetworkPeer.#send_to_peer` and the retransmit paths. Scope it to
-  `NodeUDPTransport` / `SimulatedTransport`; leave the browser transports alone.
-- Seed the rate from measured RTT (`TimeSync`), reduce on `onPacketLost`, grow on
-  clean acks, clamp `[min, max]` with a bounded burst.
-- When the bucket binds, consult `PriorityAccumulator.sorted_descending` to pick
-  which bytes go out this tick and defer the rest (`BandwidthMeter` can verify
-  the achieved rate). These primitives already exist and are correct — they are
-  intentionally unwired opt-in surface, **not** dead code.
-- Do NOT add a cipher/sliding-window or any of this to `Connection`'s packet layer; congestion
-  control belongs above the seq/ack layer, on the transport-facing send path.
-
-@author Alex Goldring
-@copyright Company Named Limited (c) 2026