@woosh/meep-engine 3.1.0 → 3.2.0

package/src/REVIEW_2026_08_06.md

@@ -1,610 +1,610 @@
-# meep engine — deep correctness / API / test review (2026-08-06)
-
-**Scope:** `app/src/mir-engine/meep/` — the whole engine library. The `editor/` tree is **out of scope** by request.
-Also excluded: `prototype*.js` (internal tools), `*.spec.js` (used as evidence only), `.d.ts` (deliberately unmaintained here).
-
-**Subject:** `@woosh/meep-engine` v2.168.1 — a *published* library. `package.json` exposes `./src/*` and there are **no barrel/index files**, so **every module path is public API surface**. That materially raises the stakes on public-surface defects: a broken exported helper is a shipped defect even when nothing in this repo calls it.
-
-**Ground rules applied to every finding** (these are the project's standing conventions):
-- Correctness only — logical errors and real bugs. No style, naming, taste, or performance opinions.
-- Every finding requires a **concrete failure scenario**: specific inputs → specific wrong output, crash, hang, or data loss.
-- `assert.*` is **compiled out of production**. Nothing is reported that depends on an assert firing, and no fix is proposed as an assert.
-- No "defensive guard" findings for conditions that cannot happen.
-- No re-entrancy findings without a named, concrete triggering caller in this repo. (A prior review had four withdrawn on exactly this basis; that precedent was enforced here.)
-- Unreferenced exports are **public surface, not dead code**.
-
-> **Methodological note on `assert.*` and jest.** Stripping is a webpack-production transform, so `assert.*` is **live under jest**. A defect reproduced in a spec is therefore running in a *more* guarded environment than production. This cuts one way only: a repro that merely trips an assert is **not** a production finding and was excluded, while a defect that reproduces despite live asserts is, if anything, worse in production. One finding (VIEW-27) is explicitly in that second category.
-
----
-
-## 1. Method
-
-Fan-out review: specialist agents over disjoint slices of the tree, each with a strict correctness-only brief and the exclusion list above, followed by an adversarial verification pass and lead-reviewer spot-checks against source.
-
-Two workstreams ran that previous reviews did not include:
-1. **Re-verification of every prior finding.** `engine/REVIEW_2026_07_03.md` (21 CRITICAL, ~61 HIGH) and `CORRECTNESS_HUNT_2026_07_24.md` were re-checked line by line against current source, because a review's value depends on whether its remediation actually landed.
-2. **API-gap and test-gap analysis**, with objective inclusion bars (see §5 and §6) designed to keep out wish-list items.
-
-### Test baseline (measured at review time)
-
-Full suite, run from `H:/git/moh` via `node_modules/.bin/jest --config jest.conf.json`:
-
-```
-Test Suites: 31 skipped, 1542 passed, 1542 of 1573 total
-Tests:       136 skipped, 9337 passed, 9473 total
-```
-
-**The suite is green.** The four `WallRunScenarios` failures recorded in the 2026-07-24 hunt are gone. Every defect in this document therefore ships green today — none of them is caught by an existing test.
-
-Adjacent-spec coverage (a crude but useful proxy — a file counts as covered if a `<name>.spec.js` sits beside it):
-
-| | source files | with adjacent spec | none |
-|---|---:|---:|---:|
-| **total** | 3701 | 1405 (38%) | 2296 |
-
-Worst packages: `engine/metrics` 0/6, `engine/save` 0/6, `view/elements` 0/34, `view/minimap` 0/12, `view/controller` 0/10, `core/debug` 2/23, `core/science` 6/40, `engine/graphics` 139/856, `engine/ecs` 46/204.
-
-**The single strongest predictor of a defect in this review was the absence of an adjacent spec.** Nearly every agent reported the same clustering independently.
-
----
-
-## 2. Status of the previous review — the headline finding
-
-The 2026-07-03 review's remediation **landed only partially, and the split is not by severity or effort — it is arbitrary.**
-
-| Prior review | Fixed | **Still open** | Unclear |
-|---|---:|---:|---:|
-| CRITICAL (C1–C22) | 17 | **4** | 0 |
-| HIGH + §2 recurring patterns | 34 | **32** | 1 |
-
-The four CRITICALs still open, all verified against current source:
-
-| ID | Location | Defect |
-|---|---|---|
-| **C5** | `engine/graphics/ecs/decal/v2/FPDecalSystem.js:216` | `unlink()` calls `transform.subscribe(...)` where `unsubscribe` was meant, *after* nulling `__fp_decal` → next transform change calls `.setTransform` on `null` → crash + listener leak. |
-| **C13** | `engine/ecs/terrain/tiles/TerrainTileManager.js:566` | `stitchTile` floors `gridSize` while `initializeTiles` ceils it → partial edge tiles are never seam-stitched → lighting crease on every non-multiple terrain boundary. |
-| **C17** | `engine/graphics/geometry/MikkT/BuildNeighborsFast.js:116` | `i1_B` and `edgenum_B` both read `temp_edge_B[2]`; `i1_B` should read `[0]`. The match test compares a vertex index against an edge number (0–2), so it effectively never succeeds → face neighbours are never assigned → **per-face (faceted) tangents on every real mesh** → normal-map seams. *(Verified first-hand.)* |
-| **C18** | `engine/graphics/geometry/MikkT/GenerateSharedVerticesIndexList.js:79` | `pass * 257 + (key >> shift) & 0xff` — JS binds `+` tighter than `&`, so the mask applies to the whole sum. Correct only for `pass === 0`; every later pass bins wrongly → **vertex welding fails** for any mesh whose hash exceeds 8 bits. *(Verified first-hand.)* |
-
-**None of the four open items has a regression spec.** Every *fixed* finding except one shipped with a spec whose test name cites the finding ID. That asymmetry is strong evidence these four were never worked, rather than fixed-and-untested.
-
-`C17` and `C18` deserve emphasis: they are both on the tangent-generation path, and the only spec in that directory (`MikkTSpace.spec.js`) covers empty geometry and a single triangle — neither case reaches edge pairing or vertex welding. **Both defects are structurally invisible to the current suite**, which is why they survived two reviews.
-
----
-
-## 3. Recurring patterns — fix the class, not the instance
-
-Independent agents reviewing unrelated subsystems converged on the same four root causes. Each is worth a targeted sweep, because fixing instances one at a time will not stop them recurring.
-
-### 3.1 Lifecycle asymmetry — the single largest class
-
-Something acquired in `link`/`startup`/`build` is not released in `unlink`/`shutdown`/`dispose`. Variants seen: subscribing to the wrong signal; passing a handler without its context so `remove` silently no-ops; removing from a *different* signal than the one subscribed; and GPU/DOM resources never disposed.
-
-The characteristic failure is **not** a slow leak — it is that **the second time you do anything, it breaks**. A level reload, a scene swap, or an engine restart is the trigger. `ShadedGeometrySystem` is the sharpest example: it registers a render layer at startup and never removes it, and `RenderLayerManager.add()` *throws* on a duplicate name — so the second load throws outright.
-
-Why it is systemic here: there is no test anywhere that asserts listener symmetry across a `link`/`unlink` cycle, so every instance of this class is invisible to CI.
-
-### 3.2 Serialization divergence
-
-For a given class, three sources of truth disagree: the field initialiser, the `toJSON`/`fromJSON` pair, and the `toBinary`/`fromBinary` pair. Observed variants: a field persisted in one path and dropped in the other; a `fromJSON` default that differs from the field initialiser (`ClingToTerrain.rotationSpeed` defaults to `Infinity` in JSON and `3` in the field); a flag field truncated from 32 bits to 8; a `toJSON` key that `fromJSON` does not read.
-
-These are silent — the object loads, it is just *wrong*. No component anywhere has a round-trip test asserting `field-init == fromJSON(toJSON()) == fromBinary(toBinary())`, which is why the whole class survives.
-
-### 3.3 Promises that never settle
-
-A code path that neither resolves nor rejects, so the caller waits forever. Found in the task executor (a task blocked on a *failed* dependency is never failed and never resolved), the undo processor, the worker proxy (a failed `postMessage` drops the request), asset loaders (a stream error mid-download), `GameStateLoader.count()`, and the engine bootstrapper (an `async` Promise executor swallows its own rejection).
-
-The related sub-pattern is **failure reported as success**: `Engine.start()` logs a startup rejection and resolves anyway; `GameStateLoader` resolves `undefined` for a missing save; `SVGAssetLoader` resolves on a `<parsererror>` document.
-
-### 3.4 Sentinels consumed as data
-
-A function returns a placeholder for a degenerate input, and its caller uses that placeholder as if it were a real value. The clearest case is `tri3_compute_normal`, which writes `(0,1,0)` with the comment *"degenerate triangle, provide arbitrary invalid result"* — and `compute_face_normal_change_dot_product` dots it against the original normal, so the mesh-simplifier's flip-rejection test silently becomes "does this face point downward". Same shape elsewhere: `Team`'s `INT32_MAX` aliasing an `Infinity` sentinel, and `indexOf`'s `-1` reaching a `splice`.
-
-This class is worth calling out separately because the *producer* is behaving as documented. The defect is the missing contract at the boundary, and the fix is to make failure signalled rather than encoded in the return value.
-
-### 3.5 Two mechanical classes worth a grep sweep
-
-- **JS semantics traps**: `pass * 257 + (key >> shift) & 0xff` (`+` binds tighter than `&`, so the mask hits the whole sum); `>>` where `>>>` is required; `x|0` used as `floor` (it truncates toward zero, so it is wrong for every negative coordinate); bare `.sort()` on numbers (lexicographic).
-- **Axis / variable copy-paste**: `size.y` written twice, `a.height` compared against `b.width`, `i1_B` and `edgenum_B` both reading slot `[2]`, vertex C's Y read from the wrong offset. These hide behind square and identity-transform test fixtures.
-
----
-
-## 4. New correctness findings
-
-**436 new findings: 50 CRITICAL, 235 MAJOR, 151 MINOR.** Per-finding detail — defect, concrete failure scenario, fix, confidence — is in `REVIEW_2026_08_06/<area>.md`.
-
-Severity here means: **CRITICAL** = crash, corruption, hang, or wrong result on a common or default path. **MAJOR** = wrong result or crash in a real but specific configuration. **MINOR** = edge case only.
-
-| Area | CRIT | MAJOR | MINOR | total | Verdict |
-|---|---:|---:|---:|---:|---|
-| `graphics/texture` + particles + geometry | 13 | 42 | 21 | 76 | Core algorithms sound; the *seams* (type/format pairing, attribute interleaving, draw-range bookkeeping) are not |
-| `view/` | 6 | 26 | 10 | 42 | Worst area in the engine. Several files cannot be constructed |
-| `core/process` + graph + debug | 6 | 16 | 5 | 27 | Graph algorithms clean; `debug` matchers and `undo` are not |
-| `engine/ecs` | 3 | 23 | 25 | 51 | Core structurally sound; edges leak |
-| `core/collection` + cache + events | 3 | 8 | 6 | 17 | Typed-array core solid; the unspecced projections are broken |
-| `engine/input` + control | 3 | 7 | 5 | 15 | Control maths well-reasoned; device shutdown paths unfinished |
-| `bvh2/8` + unspecced physics/sound/net | 2 | 16 | 9 | 27 | Cores confirmed clean; defects in the unspecced bridge |
-| `core/binary` + parser + model | 2 | 15 | 13 | 30 | Bit-twiddling solid; string/serialization edges are not |
-| `engine/asset` | 2 | 7 | 6 | 15 | `AssetManager` solid; loaders and decoders weak |
-| `graphics/sh3` GI + material + impostors | 2 | 7 | 0 | 9 | SH maths sound; three-r136 drift at the seams |
-| `core/math` | 2 | 6 | 2 | 10 | Broadly sound; defects where specs test only half the domain |
-| `generation` | 2 | 4 | 3 | 9 | Algorithms clean, no nondeterminism; seed *plumbing* broken |
-| `graphics/render` + ECS bindings | 1 | 17 | 13 | 31 | Froxel/cluster maths correct; five lifecycle leaks |
-| `engine/intelligence` + navigation + grid | 1 | 9 | 5 | 15 | Pathfinding correct; BT lifecycle bookkeeping is not |
-| `engine/animation` + interpolation | 1 | 5 | 1 | 7 | New spline layer correct; older `keyed2` playback is not |
-| `core/geom/3d` | 1 | 2 | 4 | 7 | New xatlas/BinaryTopology work good; old `simplify` path bad |
-| `engine` misc (save, Engine, UI, logging) | 0 | 13 | 8 | 21 | Save durability and engine lifecycle are the weak points |
-| `core/geom/2d` + primitives | 0 | 6 | 8 | 14 | New triangulator verified by fuzzing; old ray/hull code weak |
-| `core/science` + color | 0 | 3 | 4 | 7 | Colour science verified to reference precision; app layer leaks alpha |
-| `engine/ecs/terrain` (second pass) | 0 | 3 | 3 | 6 | — |
-| **TOTAL** | **50** | **235** | **151** | **436** | |
-
-### 4.1 The consistent shape of this review
-
-Every agent, independently, reported the same split: **the algorithmic cores are correct and the seams around them are not.**
-
-Verified clean under direct scrutiny: the physics solver and narrowphase, the acoustic simulator, the fluid MAC solver, colour science (reproduced to reference precision, including a CMF×D65 integration landing on xy = 0.31273, 0.32902 against a standard 0.31272, 0.32903), the BVH traversal and froxel/cluster geometry, SH irradiance evaluation, the earcut port (700 fuzz cases, zero area deviation), Polyanya navmesh pathing, grid A*, MikkTSpace's group/subgroup machinery, the max-rect packer, and the ECS occupancy/stride arithmetic and recursion-safe dispatcher.
-
-That is a real and unusual strength. **The defects are not in the hard parts.** They are in type/format pairings, lifecycle teardown, serialization adapters, and device shutdown — the code that is easy to write, boring to test, and therefore untested.
-
-### 4.2 The most severe individual findings
-
-Ranked by blast radius, all verified first-hand by the lead reviewer:
-
-1. **`BinaryBuffer.writeUTF8String` silently destroys non-ASCII strings** (`core/binary/BinaryBuffer.js`). The pre-reservation is `1.5 × len + 7` bytes, but Cyrillic encodes at 2 B/char and CJK at 3, so the buffer grows mid-write — and `setCapacity` copies only up to `this.position`, which the write loop does not update until it finishes. Everything written so far is zeroed. **Reproduced: a 20,000-char Cyrillic or CJK string round-trips to `""`.** ASCII is unaffected, which is exactly why nothing caught it. This is silent, total data loss in the binary serializer, and the game ships Russian.
-2. **`ThemeEngine` seed plumbing makes the whole theme layer seed-invariant** (`generation/theme/ThemeEngine.js:212`). A float in `[0,1)` is passed as a child seed; Mulberry32 does `_seed += 0x6D2B79F5` then applies bitwise ops, which coerce to int32 and **discard the fraction** — so every seed in `[0,1)` produces byte-identical output to seed `0`. Different world seeds give identical themed results. A green suite can never see this, because every run agrees with every other run.
-3. **`AtlasLookupTexture` never allocates storage for the first 32 patches** (`graphics/texture/atlas/AtlasLookupTexture.js:58`). The constructor makes a **1×1** `DataTexture` backed by a 4-element array; `update()` guards on `image.height < expected_row_count`, and with `__row_size = 32` any atlas of 1–32 patches gives `expected_row_count === 1`, so `1 < 1` is false and no reallocation happens. The loop writes `patch_count * 4` entries into a 4-element array and typed-array semantics discard everything past patch 0. *This also means the C10 fix landed in 2026-07 only ever affects patch 0.* (`format = RGBAIntegerFormat` is also paired with `internalFormat = 'RGB16UI'`.)
-4. **`ShadedGeometrySystem` never removes its render layer** (`graphics/ecs/mesh-v2/ShadedGeometrySystem.js:254`), and `RenderLayerManager.add()` **throws** on a duplicate name — so the second engine start throws outright. Three more MAJOR lifecycle leaks share that same level-reload trigger.
-5. **The mesh simplifier's flip-rejection test is nonsense on exactly the collapses it exists to reject** (`core/geom/3d/topology/simplify/`). `tri3_compute_normal` writes `(0,1,0)` for a degenerate triangle — its comment says *"provide arbitrary invalid result"* — and `compute_face_normal_change_dot_product` dots it against the original normal, so the test degenerates to `original_normal.y < 0`, i.e. "does this face point downward".
-6. **`view/` contains classes that cannot run at all.** `MinimapMarkerView` reads `this` before `super()` (guaranteed `ReferenceError`); `ViewGroup.remove()` calls `.remove()` on a native `Set`; `ViewGroup.disconnect()` calls `addChild` where `removeChild` is meant; `TabbedView` renders a literal empty `<div></div>`.
-7. **`PromiseWatcher.add()` leaks an unhandled rejection** (`core/process/PromiseWatcher.js:45`). It discards the promise returned by `.finally()`, which rejects with the same reason — so watching any promise that rejects produces an unhandled rejection *even when the caller has attached its own `.catch()`*. Under Node's default this terminates the process. Its whole spec suite is skipped as "TODO broken tests"; **the tests are right and the code is wrong.**
-8. **`sampler2d_scale_down_lanczos` returns `NaN`.** Its spec is `describe.skip("currently broken")` and it genuinely is: for a 3×1→1×1 downscale every sample lands in the kernel's negative lobe, `if (weight <= 0) continue` discards them all, `weight_sum` is 0, and `0 * Infinity = NaN`. A 2×2→1×1 box returns `4` instead of `2.5`. Three independent defects — discarding negative lobes (the point of Lanczos), a radial rather than separable kernel, and a pixel-centre convention error (`f = i - center` where `i + 0.5 - center` is meant).
-
----
-
-## 5. API gaps
-
-Both API passes used a deliberately strict inclusion bar — an item qualifies only if it is **(A)** half of a broken pair, **(B)** a member one sibling has and its peer lacks for no reason, **(C)** an omission from a concept's universal contract, or **(D)** documented but absent. Wish-list items, naming, and taste were excluded, and every claimed absence was grepped under several plausible names first.
-
-**The headline result is that the API is in good shape.** Both agents independently reported that most "obvious" absences they chased turned out to exist under a prototype alias or in a sibling file. The core is described as "unusually disciplined about pairs". This is the strongest area of the review.
-
-### 5.1 Where the real gaps cluster
-
-Two clusters, both explicable:
-
-1. **Recently-added typed-array containers, written to exactly one call site and never given the read-back half of their interface.** `Uint32Map` and `PairUint32Map` are Map-like but cannot be enumerated (no `forEach`, no iterator). `IndexedFloatMinHeap`/`MaxHeap` have no `peek` although every sibling heap does. `CSRGraph` exposes a getter that advertises worker transfer but has no `fromArrayBuffer` receiver. `BitImage2` can `set(x,y)` but only clear the whole image.
-2. **Older classes that predate the conventions their newer siblings follow.** `BiMap` aliases `add`/`set` to the Map API but has **no `delete`** — entries can never be removed. `Stack` has no `size`. `ArraySet` has `addAll` but no `removeAll`. `List` has `some()` but no `every()`, and **no `[Symbol.iterator]`** — so `for...of` and spread do not work on the most-used collection in the codebase, while `HashMap`, `HashSet` and `Deque` all support them.
-
-### 5.2 Engine-side gaps
-
-Only one sits on a path a typical game hits:
-
-- **`PhysicsSystem` has `setLinearVelocity` but no `setAngularVelocity`** — and this is not cosmetic: `setLinearVelocity` *wakes the body*, whereas the direct field write a user is forced into does not. The workaround is silently wrong.
-- `Terrain.addLayer` with no `removeLayer`, though both lower tiers support removal.
-- `engine/save`'s `GameStateLoader` imports from outside the package, so the save layer **cannot be loaded standalone from the published library** — and there is no delete.
-
-### 5.3 Two README claims are not reachable
-
-The README is otherwise accurate — instantaneous component queries, ECS scene-graph hierarchy, clustered forward+, 1M+ decals, 256-layer terrain, the path tracer, deterministic physics with CCD, the raycast vehicle and the kinematic FPS controller were each traced to a real entry point. Two are not:
-
-| Claim | Reality |
-|---|---|
-| navmesh **"with agents"** | `NavigationMeshAgent` is an **empty stub**. There is a stateless `find_path` and nothing else — no agent state, steering, or avoidance. |
-| **runtime obstacle carving** | No obstacle primitive exists. Carving is build-time only; the sole way to change the navmesh at runtime is a full rebuild. |
-
-One caveat rather than a gap: *"Tiered API Access — low-level raw typed arrays"* holds for physics, geometry and transforms, but **not for the ECS store itself** — `EntityComponentDataset.components` is `Object[][]` and marked `@private`. The ECS low tier is index-based, not array-based.
-
----
-
-## 6. Functional test gaps
-
-The suite is green and large (9,337 tests). The question this section answers is not "is coverage high" but **"where would a real defect ship undetected?"** Benchmarks behind `test.skip` are deliberate and were excluded.
-
-**The suite genuinely protects the numerical cores** — physics solver and narrowphase, the acoustic simulator, colour science, the BVHs, the fluid MAC solver, spline/Hermite maths, the path tracer. Those areas have standing gates and this review found almost nothing in them, which is exactly what good tests buy.
-
-**It does not protect serialization, lifecycle, or startup/shutdown at all.** That is precisely where §3's recurring patterns live — the correlation is not a coincidence, it is cause and effect.
-
-### 6.1 The critical gaps
-
-| ID | Gap | What ships broken |
-|---|---|---|
-| **TG-1** | `engine/save/**` — 6 files, **zero specs** | Durability is never verified. Nothing asserts a save actually committed. |
-| **TG-2** | Only **one** component in the entire engine has ever round-tripped through the binary save format | Any field silently dropped, reordered, or read at the wrong width. |
-| **TG-3** | 121 classes implement `toJSON`/`fromJSON`; ~77 also have a binary adapter. **Nothing compares the two.** | A component authored in a JSON blueprint and the same component restored from a save disagree — silently. |
-| **TG-4** | **21 binary format upgraders, zero specs** | The backward-compatibility path for old saves is entirely unverified. An upgrader's only contract is "read exactly the old layout, write exactly the new" — and nothing checks it. |
-| **TG-5** | Transient-entity and non-serializable-component exclusion is structurally unreachable by the suite | Invert either gate and you either persist entities that must not be persisted, or silently drop ones that must be. |
-| **TG-6** | `Engine.js` is 682 lines; `Engine.spec.js` is **15 lines** ("constructor does not throw"). `EnginePluginManager` (319 lines) has no spec; `EngineHarness` (548 lines) is referenced by zero specs. | Every startup-ordering and shutdown defect in §4 — including `Engine.stop()` throwing before it tears anything down. |
-
-TG-2, TG-3 and TG-4 are one gap wearing three hats, and they explain §3.2 completely.
-
-### 6.2 The highest-value MAJOR gaps
-
-- **TG-7 — `link`/`unlink` symmetry is never asserted for any System**, despite `System.js` documenting it as *the* contract. 70 `*System.js` implementations; deleting a single `signal.remove(...)` or `scene.remove(object3d)` turns no test red. This is why §3.1 is the largest defect class in the review.
-- **TG-9 — `view/View.spec.js` is a 6-line smoke test** standing in for `View.js` (804 lines) and 54 subclasses. This is why `view/` contains classes that cannot even be constructed.
-- **TG-11 — `Signal` has nine hand-copied dispatch implementations (`send0`…`send8`); only `dispatch()` is behaviourally tested.** `Signal.merge` forwarding the `arguments` object instead of the arguments was found by this review and sits in exactly that untested band.
-- **TG-10 — eleven of twelve asset loaders are untested**; the `AssetManager` contract ("call exactly one of `callback`/`failure`") is only ever proven against stubs, never against a real loader. Both asset CRITICALs are settlement-contract violations.
-- **TG-12 — grid↔world conversion tests only one direction, never the round trip**, and never on a non-square grid.
-
-### 6.3 The cheapest closing move by far
-
-Three generic, table-driven harnesses would close TG-2, TG-3, TG-4 and most of §3.2 at once:
-
-1. **Triple round-trip**, driven by the registered-class list: assert `field-init == fromJSON(toJSON()) == fromBinary(toBinary())` for every registered component. Covers ~121 classes in one spec.
-2. **Per-upgrader golden bytes**: hand-construct the old-version buffer, run the upgrader, assert the exact new bytes. 21 small specs.
-3. **`link`/`unlink` symmetry harness**: build a real `EntityComponentDataset`, link a system, unlink it, assert no residual subscriptions. Applies to 70 systems.
-
-These are worth more than any individual fix in this review, because they convert an entire recurring class from invisible to caught.
-
-### 6.4 Stale skips
-
-Three skipped suites are not benchmarks and should be resolved rather than left:
-
-- `core/process/PromiseWatcher.spec.js` — **whole suite** skipped as "TODO broken tests". Un-skipping it crashes the Node worker with an unhandled rejection, because `PromiseWatcher.add()` discards the promise returned by `.finally()`. **The tests are right and the code is wrong.**
-- `engine/graphics/texture/sampler/resize/sampler2d_scale_down_lanczos.spec.js` — skipped as "currently broken". Verified: **still broken** (see §4).
-- `core/binary/BitSet.spec.js` "resizing up and down" — verified: **now passes**. Just un-skip it.
-
----
-
-## 7. Adversarial review
-
-Every CRITICAL, plus every MAJOR making a total-failure claim ("never works", "always throws", "renders nothing"), was handed to independent verifiers **instructed to refute it**, defaulting to REFUTED under uncertainty. They were given six explicit grounds for rejection: the code does not say what the finding claims; the trigger cannot occur; `assert.*` confusion; deliberate documented behaviour; severity inflation; already fixed. Verifiers preferred *execution* over reading — writing throwaway specs, running them, and deleting them.
-
-**174 findings checked: 160 confirmed, 2 refuted, 12 downgraded.**
-
-| Pass | Checked | Confirmed | Refuted | Downgraded |
-|---|---:|---:|---:|---:|
-| core (collection, binary, process, math, science) | 67 | 58 | 0 | 9 |
-| view + engine misc | 45 | 44 | 0 | 1 |
-| graphics, geom, ecs, asset | 62 | 58 | 2 | 2 |
-
-### What this tells us
-
-**Factual accuracy was high; severity calibration was not.** Verifiers reported that claims "reproduced exactly, often to the digit". Only two findings were factually wrong, both in the same report (`gfx-gi`) and both resting on incorrect premises about three.js r136 — checked against the *installed* `node_modules/three`, not from memory:
-
-- **GFXG-3 REFUTED** — r136 `ShaderMaterial` defaults `fog = false`, so the block claimed to fail compilation is unreachable.
-- **GFXG-4 REFUTED** — `computeMaterialEquality` returns false for all `ShaderMaterial`s, so the claimed bad dedup cannot happen.
-
-The 12 downgrades share **one** cause, and it is the most important calibration lesson in this review: *a total break of public API surface that no shipped code path reaches.* `SortedListProjection`, `Signal.merge`, `BiMap`, `hammersley_sequence`, `extractTransferables` and `IsAnything` are genuinely broken — reproduced — but nothing in the shipping game calls them.
-
-This is a real tension with the project's standing convention that unreferenced exports are public surface, not dead code. **Both things are true**: they are real bugs in a published library and must be fixed, *and* they cannot break the game today. The proposal in §8 resolves this by separating **"breaks the shipping product"** from **"breaks a published API"**, rather than collapsing them into one severity axis.
-
-### Post-adversarial totals
-
-| | CRITICAL | MAJOR | MINOR | total |
-|---|---:|---:|---:|---:|
-| Raw | 50 | 237 | 153 | 440 |
-| **After adversarial adjustment** | **42** | **239** | **157** | **438** |
-
-**Confidence.** 174 of 438 findings (40%) were independently verified, weighted toward the severe end — every CRITICAL was checked. In that sample the factual error rate was **1.1%** (2/174). Unverified MINORs carry the source reports' reliability rather than a verifier's; the risk there is severity, not fabrication.
-
-### One test-reliability note
-
-`engine/simulation/Ticker.spec.js` → *"no ticks are dispatched while the page is hidden"* failed once in a full-suite run under heavy CPU contention, and passed 9/9 in three isolated runs and in a clean full re-run. It is **timing-flaky under load**, not a regression. Worth pinning to fake timers before it erodes trust in the suite.
-
----
-
-## 8. Proposal
-
-Tagged **CRITICAL / MAJOR / MINOR**. Because a published library has two distinct failure surfaces, each item also carries a reach marker:
-
-- **[product]** — breaks the shipping game today.
-- **[library]** — breaks a published API; no in-repo caller, so invisible to the game but live for any consumer.
-
-Phases are ordered by value-per-effort, not by severity alone.
-
-### Phase 0 — Silent data loss and cannot-run-twice · **CRITICAL**
-
-Small, well-understood, high blast radius. Land each with a red-before-green regression test.
-
-| Item | Tag | Reach |
-|---|---|---|
-| `BinaryBuffer.writeUTF8String` zeroes the body on mid-write growth. Fix: advance `this.position` as the loop writes, or copy to `cursor` rather than `position` in `setCapacity`. | **CRITICAL** | product |
-| `ThemeEngine`/`TerrainTheme` pass a `[0,1)` float as a child seed; Mulberry32 truncates it to a constant. Fix: derive integer child seeds. Restores all seed variation in the theme layer. | **CRITICAL** | product |
-| `ShadedGeometrySystem` never removes its render layer; second engine start throws. Fix teardown, plus the three sibling leaks (`CameraSystem.rebuild`, `LightSystem` cache, `LightManager.dispose`). | **CRITICAL** | product |
-| `AtlasLookupTexture` allocates no storage for the first 32 patches. Fix the reallocation guard and the `RGBA`/`RGB16UI` format mismatch. | **CRITICAL** | product |
-| `WebGLTextureAtlas.add` never records patch size; `TextureAtlas.repack()` clears `Packed` twice and never `Painted`. | **CRITICAL** | product |
-| `ParticleGroup` reuses one swap source for every deletion; `optimizeCommandQueue`'s comparator never returns `+1`. Corrupts particle data on any multi-delete frame. | **CRITICAL** | product |
-| BVH8 `NodeProxy` loop runs at `j = -1`, emitting structurally invalid nodes on ~0.2% of ordinary builds. | **CRITICAL** | product |
-| `ServerAuthoritativeClient` reconcile watermark is per-frame not per-entity — a client owning >1 predicted entity reconciles exactly one, forever. | **CRITICAL** | product |
-| The four **unfixed 2026-07-03 CRITICALs**: `C5` decal `subscribe`/`unsubscribe`, `C13` terrain seam floor-vs-ceil, `C17`+`C18` MikkTSpace (faceted tangents + failed vertex welding on every real mesh). | **CRITICAL** | product |
-| `Engine.stop()` throws before tearing anything down; `Engine.start()` swallows startup failure and resolves. | **CRITICAL** | product |
-| `save/IndexedDBStorage` resolves on request success rather than transaction commit — a save can be reported successful and not committed. | **CRITICAL** | product |
-
-### Phase 1 — Three generic harnesses · **CRITICAL**
-
-**This is the highest-value work in the review**, and it should be done *before* the long tail of individual fixes. Each converts an entire recurring class from invisible to caught, and each is one parameterised spec.
-
-| Harness | Closes | Tag |
-|---|---|---|
-| **Triple round-trip** over the registered-class list: `field-init == fromJSON(toJSON()) == fromBinary(toBinary())`. ~121 classes. | TG-2, TG-3, and the whole of §3.2 | **CRITICAL** |
-| **Per-upgrader golden bytes**: construct the old buffer, run the upgrader, assert exact new bytes. 21 upgraders, currently zero specs — this is the old-save migration path. | TG-4 | **CRITICAL** |
-| **`link`/`unlink` symmetry**: real dataset, link a system, unlink, assert no residual subscriptions. 70 systems. | TG-7, and most of §3.1 | **CRITICAL** |
-
-Without these, Phase 2 is a treadmill: the same classes will regrow.
-
-### Phase 2 — Pattern sweeps · **MAJOR**
-
-Fix the class, not the instance. Each is a mechanical pass now that a harness exists to hold it.
-
-- **[MAJOR, product]** Lifecycle sweep — every `link`/`startup` subscription needs a matching removal on the *same* signal with the *same* context; every GPU/DOM resource acquired needs disposal. Largest single defect class.
-- **[MAJOR, product]** Serialization sweep — reconcile JSON, binary, and field-initialiser defaults per component. Includes point lights losing `distance`, water losing 7 of 9 fields, `SerializationMetadata` truncated to 8 bits, `Team`'s `INT32_MAX`/`Infinity` aliasing.
-- **[MAJOR, product]** Promise-terminal sweep — `ConcurrentExecutor`, `ActionProcessor.doMany`, `WorkerProxy`, `ArrayBufferLoader`, `SVGAssetLoader`, `GameStateLoader`, `EngineHarness`. Every path must settle exactly once; failure must not resolve.
-- **[MAJOR, product]** Sentinel-boundary sweep — make degenerate results *signalled* rather than encoded. `tri3_compute_normal` is the model case; it also drives `GFXT-45`.
-- **[MAJOR, product]** Grep sweep for the mechanical classes: `& 0xff` precedence, `>>` vs `>>>`, `x|0` as floor, bare `.sort()` on numbers.
-- **[MAJOR, product]** Device shutdown/cancellation — `PointerDevice` and `KeyboardDevice` leave input latched down after `stop()`, blur, or `pointercancel`.
-
-### Phase 3 — Area rehabilitation · **MAJOR**
-
-- **[MAJOR, product]** `view/` — 42 findings, 6 of them classes that cannot run. Two root patterns cover most of it: raw `Signal.add` on caller-owned models instead of `bindSignal`, and teardown gated on `view.isLinked` *after* `View.unlink()` has already cleared it. Pair with TG-9 (a real `View` lifecycle spec) or it will regress.
-- **[MAJOR, product]** `graphics/texture` — 76 findings. The algorithms are fine; the type/format pairings are not (`Uint8ClampedArray`, `Float16`, integer-vs-normalized internal formats, interleaved attributes, the `normalized` flag).
-- **[MAJOR, library]** `core/debug` matcher library — `anything()` matches nothing, `nothing()` matches everything, the template formatter never substitutes. Broken as published; nothing in-repo reaches it.
-- **[MAJOR, library]** `ActionProcessor` — two independent ways to permanently brick itself (redo crash after undo→do→redo; `doMany` failure deadlocks every later call).
-- **[MAJOR, product]** Behaviour-tree lifecycle — `initialize`/`finalize` pairing across `ParallelBehavior`, `ConditionalBehavior`, `RepeatBehavior`.
-- **[MAJOR, product]** `sampler2d_scale_down_lanczos` — needs a real rewrite (separable kernel, keep negative lobes, pixel-centre convention), then un-skip its spec.
-
-### Phase 4 — API and documentation · **MINOR**
-
-- **[MAJOR, product]** `PhysicsSystem.setAngularVelocity` — the only API gap on a hot path, and the workaround is *silently wrong* because the direct field write does not wake the body.
-- **[MAJOR, library]** `BiMap` has no `delete`; `List` has no `[Symbol.iterator]` or `every()`; `Uint32Map`/`PairUint32Map` cannot be enumerated; `IndexedFloat*Heap` has no `peek`; `CSRGraph` has no `fromArrayBuffer` receiver.
-- **[MAJOR, product]** Correct the README, or build the features: **navmesh "with agents"** (`NavigationMeshAgent` is an empty stub) and **runtime obstacle carving** (no obstacle primitive exists) are advertised and absent. Also soften *"low-level raw typed arrays"* for the ECS store, which is `Object[][]` and `@private`.
-- **[MINOR, library]** `engine/save` cannot be loaded standalone from the published package (`GameStateLoader` imports outside the package). Also no delete.
-- **[MINOR]** Resolve the three stale skips: un-skip `BitSet` "resizing" (now passes), fix `PromiseWatcher` (the tests are right, the code is wrong), fix Lanczos then un-skip.
-- **[MINOR]** Pin `Ticker.spec.js`'s hidden-page test to fake timers.
-
-### Sequencing
-
-Phase 0 and Phase 1 are independent and can run in parallel; **Phase 1 should not be deferred behind Phase 0**, because it is what stops Phases 2–3 from regressing. Phases 2–3 are large but mechanical once the harnesses exist. Phase 4 is cheap and can be slotted anywhere.
-
-**The single most valuable decision available** is to build the three harnesses in Phase 1. This review found 438 defects in a codebase with a green 9,337-test suite; the gap is not effort or skill, it is that the engine's *edges* have no contract tests, so defects there are structurally invisible. Fixing 438 bugs without closing that gap buys a snapshot. Closing it buys a ratchet.
-
-
----
-
-## 9. Remediation outcome
-
-The proposal above was executed. This section records what actually landed, and — more usefully — where the review's own conclusions turned out to be wrong.
-
-**23 commits. Suite: 1554 suites / 9507 tests green, up from 1542 / 9337. Skips down from 136 to 129.**
-
-### Phase 0 — the CRITICALs on the Phase 0 list
-
-**Not every CRITICAL in this document.** Section 8's Phase 0 was a curated
-subset chosen for blast radius; the review found 50 CRITICALs in total and
-**14 of them are fixed**, alongside the 4 outstanding CRITICALs inherited from
-the 2026-07-03 review (C5, C13, C17, C18). **36 discovered CRITICALs remain
-open**, listed at the end of this section.
-
-`writeUTF8String` data loss · theme seed invariance · MikkTSpace edge pairing and vertex welding (C17/C18) · decal `subscribe`/`unsubscribe` (C5) · terrain seam floor-vs-ceil (C13) · three broken atlas paths · particle compaction · BVH8 `triangles[-1]` · engine headless/failure lifecycle · save durability · network per-entity reconcile.
-
-Two shipped without a regression gate and were flagged as such: the decal fix (its context needs the whole Forward+ plugin) — now gated by the teardown contract — and IndexedDB durability, which has no IDB implementation available to the suite.
-
-### Phase 1 — three contract harnesses
-
-| Harness | Covers | Found |
-|---|---|---|
-| binary round-trip | 48 of 77 adapters meaningfully exercised, the rest reported with reasons | Camera losing its entire lens; flags dropped by four components |
-| teardown contract | every source in the tree | proven against the real decal defect |
-| upgrader chain | 21 upgraders | **Path writes version 3 with no 2→3 upgrader — every older save unloadable** |
-
-A fourth (runtime link/unlink symmetry) was prototyped and **dropped**: it reached only 7 of ~70 systems and reported four leaks that could not be attributed to either the system or the harness. Baselining unexplained results would record noise as signal.
-
-### Phases 2–4
-
-Serialization: Camera v1 with upgrader. Promise terminals: `ConcurrentExecutor` no longer drops a task whose dependency failed, `Future` settles once, `PromiseWatcher` no longer leaks an unhandled rejection. Areas: the Lanczos downscaler rewritten (it returned `NaN`), `ViewGroup` and `MinimapMarkerView` made constructible, `anything()`/`nothing()` un-inverted. API: `setAngularVelocity`, `List.every`/iterator, `BiMap` removal. README corrected on navmesh agents and runtime obstacle carving.
-
-### Corrections to this document
-
-Adversarial review of the implementation refuted several of the findings above. Recorded because a review that only accumulates is not trustworthy:
-
-- **`optimizeCommandQueue` was downgraded on false grounds.** The first fix claimed the missing `+1` branch could not be shown to change V8's output. Wrong — the sample inputs were too small. Every permutation of a five-operation multiset finds orderings where a write sorts ahead of a remove.
-- **The round-trip harness's first baseline was ~30 entries of the harness's own making.** It claimed Light and Water lose their colours entirely. They do not: the perturber assigned colour channels outside the 0..1 domain, and the 8-bit pack clamped them. What survives is narrower — `Color.toUint()` is RGB-only, so alpha is dropped by design.
-- **`TransformPose` declaring `klass = Transform` is deliberate**, not a collision: it is a second, local interpolation format. A name-keyed chain check mistakes it for the save adapter.
-- **`BiMap`'s inverted stores are load-bearing.** Flipping `add` to match its parameter names would have broken `EncodingBinaryBuffer`'s string interning. The names were corrected instead.
-- Three Phase 0 fixes stopped one step short of the defect they named (`WebGLTextureAtlas` position, the lone-surrogate desync, `Engine.stop` leaving the render loop running), and one introduced a regression (an empty atlas allocating a 32×0 texture).
-
-### CRITICALs still open
-
-```
-AI-1 ANIM-1 ASSET-1 ASSET-2 BIN-2 COLL-1 COLL-3 ECS-1 ECS-14 ECS-40 GEN-2
-GEOM3-1 GFXG-1 GFXG-2 GFXR-11 GFXT-1 GFXT-2 GFXT-3 GFXT-4 GFXT-32 GFXT-40
-GFXT-68 GFXT-69 INPUT-1 INPUT-2 INPUT-3 MATH-1 MATH-2 PROC-10 PROC-11
-PROC-19 PROC-20 VIEW-1 VIEW-2 VIEW-4 VIEW-6
-```
-
-Worth pulling out, because they are cheap relative to their reach:
-
-- **GFXR-11** `ShadedGeometrySystem` never removes its render layer, and
-  `RenderLayerManager.add()` throws on a duplicate — the *second* engine start
-  throws. This was named in the Phase 0 list and never implemented.
-- **GEOM3-1** the mesh simplifier's flip test degenerates to "does this face
-  point downward", via `tri3_compute_normal`'s `(0,1,0)` sentinel.
-- **PROC-10 / PROC-11** `ActionProcessor` has two independent ways to brick
-  itself permanently.
-- **INPUT-2** pointer "down" state can never be cleared — no `pointercancel`
-  or blur handling.
-- **VIEW-1 / VIEW-2 / VIEW-4 / VIEW-6** four more `view/` classes that throw or
-  silently do nothing.
-
-### What remains
-
-The bulk of the 438 findings — most MAJORs and nearly all MINORs — is untouched. The `KNOWN_DIVERGENCE` baseline in the round-trip harness is the honest ledger for the serialization class: each entry deleted is one component that survives a save. Golden-bytes verification of what each upgrader *emits* is still outstanding; the chain check only proves a path exists.
-
----
-
-## 10. Round 2 proposal
-
-Selection rule for this round: **only work where the correct behaviour is not a design decision.** A fix qualifies if the current code is wrong against a contract that already exists elsewhere in the tree — a sibling that does it right, a documented convention, a method that does not exist, a promise that cannot settle. Anything requiring a judgement call about intended behaviour is deferred, not because it matters less but because guessing at intent is how a review turns into a rewrite.
-
-Second constraint: **performance characteristics are load-bearing.** Two candidates below sit on hot paths and are called out individually; neither is worth a correctness fix that costs a per-frame allocation or a per-sample branch.
-
-### 10.1 Batch A — wrong identifier, no behavioural judgement (12)
-
-Each is a single wrong token whose correct value is fixed by the surrounding code. No design latitude, no perf surface.
-
-| ID | Site | Wrong | Right |
-|---|---|---|---|
-| GFXT-1 | `sampler2d_paint.js:68` | `x + sourceY` | `x + sourceX` |
-| GFXT-40 | `computeMeshSurfaceArea.js:40` | vertex C's Y read from the Z slot | `points[c3 + 1]` |
-| GFXT-2 | `bitSet2Sampler2D.js:35,37` | `target.set(...)` — `Sampler2D` has no `set` | `target.write(...)` |
-| GFXT-3 | `computeSignedDistanceField_Chamfer.js:72` | stale `v`, stores last instead of min | assign `v = vN` after each write |
-| GFXT-68 | `Ribbon.js:143` | tip vertices on opposite sides | negate the cross to match the degenerate branch |
-| GFXT-69 | `load_environment_map.js:57` | `EXRLoader` asked for `UnsignedByteType` | `HalfFloatType` |
-| ECS-40 | `LineSetDescription.js:56` | walks `set.children`, unbounded loop | `set.sets` |
-| ECS-14 | `TerrainTileManager.js:461` | reads the vertical axis as a grid row | index by `v3[0]`/`v3[2]` |
-| COLL-3 | `Signal.js:797` | dispatches the `arguments` object | spread it |
-| BIN-2 | `Localization.js:140` | trailing-slash trim never terminates | slice, do not re-test |
-| INPUT-1 | `TopDownCameraControllerHelper.js:45` | geometry classes never imported | import them |
-| GFXR-11 | `ShadedGeometrySystem.js:254` | render layer never removed; second start throws | remove it in `shutdown` |
-
-### 10.2 Batch B — a promise that cannot settle (3)
-
-The contract is not in question: a path that neither resolves nor rejects is a hang.
-
-- **PROC-20** `WorkerProxy` — a failed `postMessage` drops the request without rejecting.
-- **ASSET-2** `ArrayBufferLoader` — a fetch stream error mid-download never reaches the consumer; `pump()` has no rejection handler.
-- **PROC-19** `extractTransferables(null)` throws while the inline duplicate a few lines away guards for exactly that.
-
-### 10.3 Batch C — hot path, correctness *and* cost (2)
-
-Both are real defects. Both sit somewhere the naive fix is unacceptable, so each carries a required approach.
-
-- **MATH-1** — `sdnoise` computes its lattice cell with `x | 0`, which truncates toward zero and is therefore wrong for every negative coordinate. This is the inner loop of noise generation. `Math.floor` is the obvious fix and must be **measured, not assumed**: if it costs anything measurable, use the branchless `(x | 0) - (x < 0 ? 1 : 0)` form instead. Correctness is not negotiable; which of the two lands is a measurement.
-- **INPUT-3** — `InputControllerSystem` mutates its binding array mid-dispatch, so destroying an entity from an input handler throws. The stated fix is "iterate a snapshot", but dispatch runs per input event and a per-dispatch `slice()` is a per-event allocation in a zero-allocation engine. Prefer a reverse walk or an index-stable removal that needs no copy.
-
-### 10.4 Explicitly deferred, with reasons
-
-Not "lower priority" — genuinely not unambiguous:
-
-- **ANIM-1**, **GEOM3-1** — the fix changes which result the algorithm considers best. That is a behavioural change needing a decision, not a repair.
-- **ECS-1**, **GEN-2**, **VIEW-1/2/4**, **PROC-10/11** — each needs a lifecycle or task-graph restructure with more than one defensible shape.
-- **GFXG-1**, **GFXG-2**, **GFXT-4** — GPU-side or shared-buffer ownership; cannot be verified from the suite, and `GFXT-4`'s fix trades a mutation for a copy, which is a perf decision.
-- **ASSET-1** (Adam7), **INPUT-2** (`pointercancel`), **MATH-2**, **COLL-1**, **AI-1**, **GFXT-32** — each is likely correct as written up, but each needs a fixture or a browser behaviour I cannot confirm here, and shipping an unverified fix to a CRITICAL is worse than leaving it listed.
-
-### 10.5 Revision after adversarial review of the proposal
-
-The proposal was reviewed before any of it was written. Three items were wrong, one was missing, and two deferrals were unjustified.
-
-**Removed from the plan:**
-
-- **GFXT-68** (`Ribbon`) — *not unambiguous.* With `normal = -Z` the unnegated branch already agrees; the correct sign depends on a winding convention that is not stated anywhere in the tree. Negating on a guess would invert every ribbon. Deferred.
-- **INPUT-3** — *the prescribed fix is wrong.* A reverse walk inverts binding priority order, and does nothing about `registerBinding`'s re-sort, which is the actual source of the mutation. Deferred until the dispatch/registration interaction is understood.
-
-**Corrected:**
-
-- **MATH-1** — the fallback this document proposed, `(x | 0) - (x < 0 ? 1 : 0)`, **is not floor**: it over-subtracts at exact negative integers (`floor(-1) = -1`, the form yields `-2`). Measurement also shows no penalty for `Math.floor` — across warmed runs the two are indistinguishable, and the variance between repeats of the *same* function exceeds the difference between them. So the fix is plainly `Math.floor`. Separately, it turns a currently-green spec red, which has to be resolved on its merits: a spec that pins truncation is pinning the defect.
-- **ECS-14** — the table lost the load-bearing half of the fix. The divisors matter: index by `v3[0] / scale.x` and `v3[2] / scale.y`. `scale.y` really is the right divisor for the Z axis (the terrain's scale is 2D).
-
-**Added — it was missing from both lists:**
-
-- **VIEW-6** `Minimap.clear()` calls `addChild` where `removeChild` is meant, from `unlink()`. One wrong token, intent fixed by the method name. It belongs in Batch A and was simply dropped.
-
-**Promoted out of "deferred" — the stated reason was false:**
-
-- **COLL-1** `SortedListProjection` — deferred as needing a fixture; it reproduces in plain node in seconds, and the `where + 1` insert is forced by `binarySearchLowIndex`'s contract.
-- **MATH-2** `hammersley_sequence` — deferred for the same false reason; it is pure maths with a sibling (`halton_sequence`) as the reference and no callers to break.
-
-**Two items are sound but cannot take the red-test-first protocol**, and are marked as such rather than pretended otherwise: **GFXT-69** (no `.exr` fixture exists) and **BIN-2** (the red test wedges the jest worker synchronously, because the bug is an infinite loop).
-
-## 11. Round 2 outcome
-
-Landed across `1c13a74ae`, `18f627741`, `62047e542`, with a self-review after each. Every item below is pinned by a test that was verified red against the unfixed code, except where stated.
-
-### 11.1 What landed
-
-**Batch A — wrong identifier (11 of 12).**
-
-| ID | Site | Pinned by |
-|---|---|---|
-| GFXT-1 | `sampler2d_paint` read the source column from `sourceY` | `sampler2d_paint.spec.js` |
-| GFXT-40 | `computeMeshSurfaceArea` read vertex C's Y from the Z slot | `computeMeshSurfaceArea.spec.js` |
-| GFXT-2 | `bitSet2Sampler2D` called `target.set`, which does not exist | existing sampler specs |
-| GFXT-3 | chamfer SDF compared each candidate against the original, not the running minimum | `computeSignedDistanceField_Chamfer.spec.js` |
-| GFXT-69 | `EXRLoader` asked for `UnsignedByteType` | *not pinned — no `.exr` fixture* |
-| ECS-40 | `LineSetDescription.collect` re-walked the root's children forever | `LineSetDescription.spec.js` (times out unfixed) |
-| ECS-14 | `TerrainTileManager` world lookup: vertical axis read as a grid row, grid scale not divided out | `TerrainTileManager.spec.js` |
-| COLL-3 | `Signal.merge` dispatched the `arguments` object as one argument | `Signal.spec.js` |
-| BIN-2 | `Localization` trailing-slash trim discarded the slice and never terminated | `Localization.spec.js` |
-| INPUT-1 | `TopDownCameraControllerHelper` used geometry classes it never imported | import resolution |
-| GFXR-11 | `ShadedGeometrySystem` never released its render layer, so a second startup threw | `RenderLayerManager.spec.js` (contract only) |
-
-GFXT-68 (`Ribbon`) stayed deferred, per §10.5.
-
-**Batch B — a promise that cannot settle (3 of 3).** `WorkerProxy` (failed `postMessage` dropped the request), `ArrayBufferLoader` (stream failure never reached the consumer), `extractTransferables` (threw on `null`). All three pinned; the first two time out against the unfixed code.
-
-**Batch C.** `MATH-1` deferred — see §11.3. `INPUT-3` deferred per §10.5.
-
-**Promoted out of "deferred".** `COLL-1` (`SortedListProjection` insert position) and `MATH-2` (`hammersley_sequence`), both pinned. `hammersley_sequence` also lost its `count` parameter: the radical inverse does not depend on the size of the set, no version of the body ever read it, and the function has no callers in the tree — it is pure published surface, so a parameter documented as permanently unused is worse for a library consumer than a clean two-argument signature.
-
-### 11.2 What the self-review of this round caught
-
-The round-2 work was itself reviewed, and it found four defects in the fixes and three false statements. Recording both, because a review that only records the wins is not a review.
-
-**Defects in the round-2 work, since fixed in `62047e542`:**
-
-- **`hammersley_sequence` — a regression I introduced.** Correcting the accumulator turned the incremental formulation numerically unstable: base 3 produced **13 distinct values over 512 samples**. The spec tested base 2 only, so it stayed green. Rewritten to the closed-form radical inverse that the sibling `halton_sequence` already uses — O(log i) instead of O(i), stable for any base — and the spec now cross-validates against `halton_sequence` for bases 2/3/5/7/11 and asserts 512-sample distinctness. **The missing distinctness check is the reason this got through, and it is the durable part of the fix.**
-- **ECS-14 landed half-done.** §10.5 explicitly called the scale divisors "the load-bearing half", and the implementation applied the axis fix without them. Wrong tile for every terrain whose `gridScale` is not 1.
-- **`ArrayBufferLoader` was still one throw away from a hang.** The rejection handler went in as the second argument to `.then`, which cannot see a throw from its own fulfilment path — so a throwing caller-supplied `progress` callback still wedged the load forever. Now `.catch`, and pinned.
-- **`Minimap.clear()` was justified with a comment about the wrong array, and stopped short of the real defect.** `removeChild` does not mutate the array the `.slice()` was defending, and `removeObserver(observer, true)` has usually emptied `__cameraViews` before `clear()` runs — so as written the fix was close to inert. The array is assigned **in the constructor**, not in `link()`, and `link()` re-registers the observer with `notify = true`; leaving stale entries in it therefore breaks the second `link()` after an `unlink()` — the same cannot-run-twice shape as GFXR-11. `clear()` now drops the entries too.
-
-**False statements, corrected:**
-
-- **Two Batch A items were listed as landed and were not: BIN-2 and GFXT-69.** Both have since landed. GFXT-69 was worse than the table said — `EXRLoader` does not merely prefer float types, it falls through to a `default` branch that never allocates the output buffer, so *no* `.exr` environment map could load at all.
-- **The chamfer commit claimed the fix meant "fewer stores".** Measured, it is **13% more stores and about 2% slower**. The fix is still correct and still lands; the justification was invented. Cost, measured: negligible against a two-pass sweep that is memory-bound anyway.
-- **The MATH-1 deferral reasoning was not honest** — see below.
-
-### 11.3 MATH-1, restated honestly
-
-The deferral was argued on the grounds that `FASTFLOOR` is "neither truncation nor floor, so the correct target is unclear". That is false, and the argument does not survive contact with the code:
-
-- `FASTFLOOR` **equals `Math.floor` at every non-integer input**, and differs only at exact negative integers.
-- `x | 0` differs from **both** at every negative coordinate — it is the one form that is wrong everywhere below zero.
-- `create_simplex_noise_2d.js`, in the same directory, **already made this exact fix and has a regression spec for it.** The convention is settled in the tree.
-
-So MATH-1 is unambiguous on its merits and belongs in Batch A. The one real reason to hold it is unchanged and sufficient on its own: **`sdnoise` feeds procedural generation, and changing lattice cell selection re-rolls every generated map from a given seed.** That is a content decision with a migration cost, not a code decision — it needs a deliberate call about whether existing seeds are allowed to change, and it should land on its own so the diff in generated output is attributable.
-
-Measurement, since the original proposal asked for it: `Math.floor` and `x | 0` are indistinguishable across warmed runs — repeat-to-repeat variance on the *same* function exceeds the gap between them. **There is no performance argument on either side.** The proposal's suggested branchless fallback `(x | 0) - (x < 0 ? 1 : 0)` is not floor at all (it yields `-2` for `floor(-1)`) and must not be used.
-
-### 11.4 Standing state
-
-Round 2 closed 16 items. The CRITICALs listed as still open in §9 are unchanged by this round except for ECS-14 and BIN-2 — round 2 deliberately took the unambiguous work, and the open CRITICALs are open precisely because they are not.
-
-The three durable additions from this round are worth more than the individual fixes: the `hammersley` distinctness check, the `ArrayBufferLoader` settle-under-failure specs, and `Localization`'s first spec (which drives a real `AssetManager` through a real loader, the pattern the rest of the loader tests should follow).
-
-## 12. Review of the round-1 and round-2 commits
-
-A pass over all 34 commits, in `62047e542..a0e4b9dbc` plus the round-1 range. The point was to find defects in the remediation itself, so what follows leads with those.
-
-### 12.1 Verified rather than assumed
-
-- **Particle compaction** — the swap plan was brute-forced against a reference over every victim subset for arrays up to 12 elements: 8178 cases, 0 mismatches.
-- **Camera 0→1 and Path 2→3 upgraders** — executed end to end; see §12.3, which turned this into a standing harness.
-- **Both new upgraders are registered** in `GameBinarySerializationRegistry.js` (`3ecf5c16`, `8b8df83a`). A version bump without registration silently breaks every existing save, and that was the failure worth checking.
-- **`ServerAuthoritativeClient`** — `Uint32Map.get` does return −1 for absent; network ids come off a free list, so the watermark map is bounded by peak concurrent entities rather than leaking; and a recycled id inherits a watermark that is always behind the current server frame, so reuse cannot drop state.
-- **Physics hot paths** — `solve_constraints`, `convex_convex_manifold`, `raycast`, `ManifoldStore`, `quat3_multiply`: zero executable changes across the whole range, JSDoc only.
-- **`BiMap`** — the argument swap is names-only; identical behaviour for the same positional call.
-- **`Engine` lifecycle** — `Ticker.start` re-adds its lifecycle listeners, so `stop()`→`start()` is clean; the one consumer testing `graphics === undefined` also tests for null; and `start()` already returned a promise before it became `async`.
-- **The round-trip harness is not vacuous** — deleting a field's restoration from an adapter turns it red on exactly that adapter.
-
-### 12.2 Defects found in the remediation, and fixed
-
-- **`IndexedDBStorage.store` rejected up to three times for one failure.** `resolve`/`reject` there are the caller's own callbacks, not promise settle functions, and a failed write raises `error` on the request, bubbles to `error` on the transaction, then aborts it — with a listener on each. In-tree callers wrap the call in a promise, which hides it; `Storage` is published API, so an external consumer saw one lost save reported three times. Now it rejects on `abort` alone, which is the event that always fires for a transaction that will not commit, and it carries `transaction.error` as the reason. The storage classes had no specs at all; they have one now.
-- **The Lanczos `weight_sum === 0` fallback was unreachable.** Swept over every downscale ratio from 1 to 40 at 2 and 3 lobes, the weight sum was never zero, never negative, and never below 1. The NaN it claimed to prevent came from the *old* `if (weight <= 0) continue`, which discarded the negative lobes — and the rewrite had already removed that. Keeping the whole kernel makes the sum the integral of the kernel over the footprint, which stays near 1. Removed: it was precisely the defensive guard for a can't-happen condition this project rejects, and its comment described a failure the new code cannot produce.
-
-### 12.3 The gap that mattered most: upgraders were never executed
-
-`upgrader_chain_contract.spec.js` checks that a path from every historical version to the current one *exists*. That catches a missing upgrader, which is what it was built for. It does not catch an upgrader that is present and emits the wrong layout — and at load time that is the worse failure, because the deserializer then reads real bytes at wrong offsets instead of failing loudly. Its own docblock admitted this and left it outstanding.
-
-`upgrader_execution_contract.spec.js` closes it. Each covered upgrader gets a source buffer in the layout it reads, the chain runs to the current version through `executeBinaryClassUpgraderChain` — the same executor production uses — and the current adapter deserializes the result. The assertion that does the work is the byte count: the adapter must consume exactly what the chain produced.
-
-Two properties make it honest rather than decorative:
-
-- **It is a check of what an upgrader *writes*, not what it reads.** The golden describes the start version's layout, which is derived from the upgrader's own reads. The adapter that originally wrote that layout is gone, so there is nothing left to check the read side against, and the spec says so instead of implying otherwise.
-- **Coverage is enumerated, not assumed.** 9 of 23 upgraders have goldens; the other 14 are listed in `WITHOUT_GOLDEN`, and a new upgrader that appears in neither list fails the spec. Each entry is a save-format version nothing verifies can still be read.
-
-Mutation-verified in both directions: making an upgrader emit one extra field, and making it omit one, each turns its own case red.
-
-### 12.4 Left open, deliberately
-
-- **The Lanczos rewrite changed the filter shape** from radial (`sqrt(fx²+fy²)`) to separable (`L(x)·L(y)`). Separable is the correct Lanczos and it is cheaper — O(rx+ry) transcendental evaluations per output pixel instead of O(rx·ry) — but every downscaled texture now differs from before, and the commit framed it purely as a NaN fix. Recorded here rather than reverted; the old behaviour was not worth preserving.
-- **`sampler2d_scale_down_lanczos` throws "source is larger than destination"** when the condition, `source_width < d_w`, means the source is *smaller*. Pre-existing, and left alone rather than folded into an unrelated change.
-- **`IndexedDBStorage.remove` still reports success off the request** rather than the transaction commit — the same durability gap `store` had. Not touched here because it is a separate defect from the triple-reject this pass was fixing, and it deserves its own change.
+# meep engine — deep correctness / API / test review (2026-08-06)
+
+**Scope:** `app/src/mir-engine/meep/` — the whole engine library. The `editor/` tree is **out of scope** by request.
+Also excluded: `prototype*.js` (internal tools), `*.spec.js` (used as evidence only), `.d.ts` (deliberately unmaintained here).
+
+**Subject:** `@woosh/meep-engine` v2.168.1 — a *published* library. `package.json` exposes `./src/*` and there are **no barrel/index files**, so **every module path is public API surface**. That materially raises the stakes on public-surface defects: a broken exported helper is a shipped defect even when nothing in this repo calls it.
+
+**Ground rules applied to every finding** (these are the project's standing conventions):
+- Correctness only — logical errors and real bugs. No style, naming, taste, or performance opinions.
+- Every finding requires a **concrete failure scenario**: specific inputs → specific wrong output, crash, hang, or data loss.
+- `assert.*` is **compiled out of production**. Nothing is reported that depends on an assert firing, and no fix is proposed as an assert.
+- No "defensive guard" findings for conditions that cannot happen.
+- No re-entrancy findings without a named, concrete triggering caller in this repo. (A prior review had four withdrawn on exactly this basis; that precedent was enforced here.)
+- Unreferenced exports are **public surface, not dead code**.
+
+> **Methodological note on `assert.*` and jest.** Stripping is a webpack-production transform, so `assert.*` is **live under jest**. A defect reproduced in a spec is therefore running in a *more* guarded environment than production. This cuts one way only: a repro that merely trips an assert is **not** a production finding and was excluded, while a defect that reproduces despite live asserts is, if anything, worse in production. One finding (VIEW-27) is explicitly in that second category.
+
+---
+
+## 1. Method
+
+Fan-out review: specialist agents over disjoint slices of the tree, each with a strict correctness-only brief and the exclusion list above, followed by an adversarial verification pass and lead-reviewer spot-checks against source.
+
+Two workstreams ran that previous reviews did not include:
+1. **Re-verification of every prior finding.** `engine/REVIEW_2026_07_03.md` (21 CRITICAL, ~61 HIGH) and `CORRECTNESS_HUNT_2026_07_24.md` were re-checked line by line against current source, because a review's value depends on whether its remediation actually landed.
+2. **API-gap and test-gap analysis**, with objective inclusion bars (see §5 and §6) designed to keep out wish-list items.
+
+### Test baseline (measured at review time)
+
+Full suite, run from `H:/git/moh` via `node_modules/.bin/jest --config jest.conf.json`:
+
+```
+Test Suites: 31 skipped, 1542 passed, 1542 of 1573 total
+Tests:       136 skipped, 9337 passed, 9473 total
+```
+
+**The suite is green.** The four `WallRunScenarios` failures recorded in the 2026-07-24 hunt are gone. Every defect in this document therefore ships green today — none of them is caught by an existing test.
+
+Adjacent-spec coverage (a crude but useful proxy — a file counts as covered if a `<name>.spec.js` sits beside it):
+
+| | source files | with adjacent spec | none |
+|---|---:|---:|---:|
+| **total** | 3701 | 1405 (38%) | 2296 |
+
+Worst packages: `engine/metrics` 0/6, `engine/save` 0/6, `view/elements` 0/34, `view/minimap` 0/12, `view/controller` 0/10, `core/debug` 2/23, `core/science` 6/40, `engine/graphics` 139/856, `engine/ecs` 46/204.
+
+**The single strongest predictor of a defect in this review was the absence of an adjacent spec.** Nearly every agent reported the same clustering independently.
+
+---
+
+## 2. Status of the previous review — the headline finding
+
+The 2026-07-03 review's remediation **landed only partially, and the split is not by severity or effort — it is arbitrary.**
+
+| Prior review | Fixed | **Still open** | Unclear |
+|---|---:|---:|---:|
+| CRITICAL (C1–C22) | 17 | **4** | 0 |
+| HIGH + §2 recurring patterns | 34 | **32** | 1 |
+
+The four CRITICALs still open, all verified against current source:
+
+| ID | Location | Defect |
+|---|---|---|
+| **C5** | `engine/graphics/ecs/decal/v2/FPDecalSystem.js:216` | `unlink()` calls `transform.subscribe(...)` where `unsubscribe` was meant, *after* nulling `__fp_decal` → next transform change calls `.setTransform` on `null` → crash + listener leak. |
+| **C13** | `engine/ecs/terrain/tiles/TerrainTileManager.js:566` | `stitchTile` floors `gridSize` while `initializeTiles` ceils it → partial edge tiles are never seam-stitched → lighting crease on every non-multiple terrain boundary. |
+| **C17** | `engine/graphics/geometry/MikkT/BuildNeighborsFast.js:116` | `i1_B` and `edgenum_B` both read `temp_edge_B[2]`; `i1_B` should read `[0]`. The match test compares a vertex index against an edge number (0–2), so it effectively never succeeds → face neighbours are never assigned → **per-face (faceted) tangents on every real mesh** → normal-map seams. *(Verified first-hand.)* |
+| **C18** | `engine/graphics/geometry/MikkT/GenerateSharedVerticesIndexList.js:79` | `pass * 257 + (key >> shift) & 0xff` — JS binds `+` tighter than `&`, so the mask applies to the whole sum. Correct only for `pass === 0`; every later pass bins wrongly → **vertex welding fails** for any mesh whose hash exceeds 8 bits. *(Verified first-hand.)* |
+
+**None of the four open items has a regression spec.** Every *fixed* finding except one shipped with a spec whose test name cites the finding ID. That asymmetry is strong evidence these four were never worked, rather than fixed-and-untested.
+
+`C17` and `C18` deserve emphasis: they are both on the tangent-generation path, and the only spec in that directory (`MikkTSpace.spec.js`) covers empty geometry and a single triangle — neither case reaches edge pairing or vertex welding. **Both defects are structurally invisible to the current suite**, which is why they survived two reviews.
+
+---
+
+## 3. Recurring patterns — fix the class, not the instance
+
+Independent agents reviewing unrelated subsystems converged on the same four root causes. Each is worth a targeted sweep, because fixing instances one at a time will not stop them recurring.
+
+### 3.1 Lifecycle asymmetry — the single largest class
+
+Something acquired in `link`/`startup`/`build` is not released in `unlink`/`shutdown`/`dispose`. Variants seen: subscribing to the wrong signal; passing a handler without its context so `remove` silently no-ops; removing from a *different* signal than the one subscribed; and GPU/DOM resources never disposed.
+
+The characteristic failure is **not** a slow leak — it is that **the second time you do anything, it breaks**. A level reload, a scene swap, or an engine restart is the trigger. `ShadedGeometrySystem` is the sharpest example: it registers a render layer at startup and never removes it, and `RenderLayerManager.add()` *throws* on a duplicate name — so the second load throws outright.
+
+Why it is systemic here: there is no test anywhere that asserts listener symmetry across a `link`/`unlink` cycle, so every instance of this class is invisible to CI.
+
+### 3.2 Serialization divergence
+
+For a given class, three sources of truth disagree: the field initialiser, the `toJSON`/`fromJSON` pair, and the `toBinary`/`fromBinary` pair. Observed variants: a field persisted in one path and dropped in the other; a `fromJSON` default that differs from the field initialiser (`ClingToTerrain.rotationSpeed` defaults to `Infinity` in JSON and `3` in the field); a flag field truncated from 32 bits to 8; a `toJSON` key that `fromJSON` does not read.
+
+These are silent — the object loads, it is just *wrong*. No component anywhere has a round-trip test asserting `field-init == fromJSON(toJSON()) == fromBinary(toBinary())`, which is why the whole class survives.
+
+### 3.3 Promises that never settle
+
+A code path that neither resolves nor rejects, so the caller waits forever. Found in the task executor (a task blocked on a *failed* dependency is never failed and never resolved), the undo processor, the worker proxy (a failed `postMessage` drops the request), asset loaders (a stream error mid-download), `GameStateLoader.count()`, and the engine bootstrapper (an `async` Promise executor swallows its own rejection).
+
+The related sub-pattern is **failure reported as success**: `Engine.start()` logs a startup rejection and resolves anyway; `GameStateLoader` resolves `undefined` for a missing save; `SVGAssetLoader` resolves on a `<parsererror>` document.
+
+### 3.4 Sentinels consumed as data
+
+A function returns a placeholder for a degenerate input, and its caller uses that placeholder as if it were a real value. The clearest case is `tri3_compute_normal`, which writes `(0,1,0)` with the comment *"degenerate triangle, provide arbitrary invalid result"* — and `compute_face_normal_change_dot_product` dots it against the original normal, so the mesh-simplifier's flip-rejection test silently becomes "does this face point downward". Same shape elsewhere: `Team`'s `INT32_MAX` aliasing an `Infinity` sentinel, and `indexOf`'s `-1` reaching a `splice`.
+
+This class is worth calling out separately because the *producer* is behaving as documented. The defect is the missing contract at the boundary, and the fix is to make failure signalled rather than encoded in the return value.
+
+### 3.5 Two mechanical classes worth a grep sweep
+
+- **JS semantics traps**: `pass * 257 + (key >> shift) & 0xff` (`+` binds tighter than `&`, so the mask hits the whole sum); `>>` where `>>>` is required; `x|0` used as `floor` (it truncates toward zero, so it is wrong for every negative coordinate); bare `.sort()` on numbers (lexicographic).
+- **Axis / variable copy-paste**: `size.y` written twice, `a.height` compared against `b.width`, `i1_B` and `edgenum_B` both reading slot `[2]`, vertex C's Y read from the wrong offset. These hide behind square and identity-transform test fixtures.
+
+---
+
+## 4. New correctness findings
+
+**436 new findings: 50 CRITICAL, 235 MAJOR, 151 MINOR.** Per-finding detail — defect, concrete failure scenario, fix, confidence — is in `REVIEW_2026_08_06/<area>.md`.
+
+Severity here means: **CRITICAL** = crash, corruption, hang, or wrong result on a common or default path. **MAJOR** = wrong result or crash in a real but specific configuration. **MINOR** = edge case only.
+
+| Area | CRIT | MAJOR | MINOR | total | Verdict |
+|---|---:|---:|---:|---:|---|
+| `graphics/texture` + particles + geometry | 13 | 42 | 21 | 76 | Core algorithms sound; the *seams* (type/format pairing, attribute interleaving, draw-range bookkeeping) are not |
+| `view/` | 6 | 26 | 10 | 42 | Worst area in the engine. Several files cannot be constructed |
+| `core/process` + graph + debug | 6 | 16 | 5 | 27 | Graph algorithms clean; `debug` matchers and `undo` are not |
+| `engine/ecs` | 3 | 23 | 25 | 51 | Core structurally sound; edges leak |
+| `core/collection` + cache + events | 3 | 8 | 6 | 17 | Typed-array core solid; the unspecced projections are broken |
+| `engine/input` + control | 3 | 7 | 5 | 15 | Control maths well-reasoned; device shutdown paths unfinished |
+| `bvh2/8` + unspecced physics/sound/net | 2 | 16 | 9 | 27 | Cores confirmed clean; defects in the unspecced bridge |
+| `core/binary` + parser + model | 2 | 15 | 13 | 30 | Bit-twiddling solid; string/serialization edges are not |
+| `engine/asset` | 2 | 7 | 6 | 15 | `AssetManager` solid; loaders and decoders weak |
+| `graphics/sh3` GI + material + impostors | 2 | 7 | 0 | 9 | SH maths sound; three-r136 drift at the seams |
+| `core/math` | 2 | 6 | 2 | 10 | Broadly sound; defects where specs test only half the domain |
+| `generation` | 2 | 4 | 3 | 9 | Algorithms clean, no nondeterminism; seed *plumbing* broken |
+| `graphics/render` + ECS bindings | 1 | 17 | 13 | 31 | Froxel/cluster maths correct; five lifecycle leaks |
+| `engine/intelligence` + navigation + grid | 1 | 9 | 5 | 15 | Pathfinding correct; BT lifecycle bookkeeping is not |
+| `engine/animation` + interpolation | 1 | 5 | 1 | 7 | New spline layer correct; older `keyed2` playback is not |
+| `core/geom/3d` | 1 | 2 | 4 | 7 | New xatlas/BinaryTopology work good; old `simplify` path bad |
+| `engine` misc (save, Engine, UI, logging) | 0 | 13 | 8 | 21 | Save durability and engine lifecycle are the weak points |
+| `core/geom/2d` + primitives | 0 | 6 | 8 | 14 | New triangulator verified by fuzzing; old ray/hull code weak |
+| `core/science` + color | 0 | 3 | 4 | 7 | Colour science verified to reference precision; app layer leaks alpha |
+| `engine/ecs/terrain` (second pass) | 0 | 3 | 3 | 6 | — |
+| **TOTAL** | **50** | **235** | **151** | **436** | |
+
+### 4.1 The consistent shape of this review
+
+Every agent, independently, reported the same split: **the algorithmic cores are correct and the seams around them are not.**
+
+Verified clean under direct scrutiny: the physics solver and narrowphase, the acoustic simulator, the fluid MAC solver, colour science (reproduced to reference precision, including a CMF×D65 integration landing on xy = 0.31273, 0.32902 against a standard 0.31272, 0.32903), the BVH traversal and froxel/cluster geometry, SH irradiance evaluation, the earcut port (700 fuzz cases, zero area deviation), Polyanya navmesh pathing, grid A*, MikkTSpace's group/subgroup machinery, the max-rect packer, and the ECS occupancy/stride arithmetic and recursion-safe dispatcher.
+
+That is a real and unusual strength. **The defects are not in the hard parts.** They are in type/format pairings, lifecycle teardown, serialization adapters, and device shutdown — the code that is easy to write, boring to test, and therefore untested.
+
+### 4.2 The most severe individual findings
+
+Ranked by blast radius, all verified first-hand by the lead reviewer:
+
+1. **`BinaryBuffer.writeUTF8String` silently destroys non-ASCII strings** (`core/binary/BinaryBuffer.js`). The pre-reservation is `1.5 × len + 7` bytes, but Cyrillic encodes at 2 B/char and CJK at 3, so the buffer grows mid-write — and `setCapacity` copies only up to `this.position`, which the write loop does not update until it finishes. Everything written so far is zeroed. **Reproduced: a 20,000-char Cyrillic or CJK string round-trips to `""`.** ASCII is unaffected, which is exactly why nothing caught it. This is silent, total data loss in the binary serializer, and the game ships Russian.
+2. **`ThemeEngine` seed plumbing makes the whole theme layer seed-invariant** (`generation/theme/ThemeEngine.js:212`). A float in `[0,1)` is passed as a child seed; Mulberry32 does `_seed += 0x6D2B79F5` then applies bitwise ops, which coerce to int32 and **discard the fraction** — so every seed in `[0,1)` produces byte-identical output to seed `0`. Different world seeds give identical themed results. A green suite can never see this, because every run agrees with every other run.
+3. **`AtlasLookupTexture` never allocates storage for the first 32 patches** (`graphics/texture/atlas/AtlasLookupTexture.js:58`). The constructor makes a **1×1** `DataTexture` backed by a 4-element array; `update()` guards on `image.height < expected_row_count`, and with `__row_size = 32` any atlas of 1–32 patches gives `expected_row_count === 1`, so `1 < 1` is false and no reallocation happens. The loop writes `patch_count * 4` entries into a 4-element array and typed-array semantics discard everything past patch 0. *This also means the C10 fix landed in 2026-07 only ever affects patch 0.* (`format = RGBAIntegerFormat` is also paired with `internalFormat = 'RGB16UI'`.)
+4. **`ShadedGeometrySystem` never removes its render layer** (`graphics/ecs/mesh-v2/ShadedGeometrySystem.js:254`), and `RenderLayerManager.add()` **throws** on a duplicate name — so the second engine start throws outright. Three more MAJOR lifecycle leaks share that same level-reload trigger.
+5. **The mesh simplifier's flip-rejection test is nonsense on exactly the collapses it exists to reject** (`core/geom/3d/topology/simplify/`). `tri3_compute_normal` writes `(0,1,0)` for a degenerate triangle — its comment says *"provide arbitrary invalid result"* — and `compute_face_normal_change_dot_product` dots it against the original normal, so the test degenerates to `original_normal.y < 0`, i.e. "does this face point downward".
+6. **`view/` contains classes that cannot run at all.** `MinimapMarkerView` reads `this` before `super()` (guaranteed `ReferenceError`); `ViewGroup.remove()` calls `.remove()` on a native `Set`; `ViewGroup.disconnect()` calls `addChild` where `removeChild` is meant; `TabbedView` renders a literal empty `<div></div>`.
+7. **`PromiseWatcher.add()` leaks an unhandled rejection** (`core/process/PromiseWatcher.js:45`). It discards the promise returned by `.finally()`, which rejects with the same reason — so watching any promise that rejects produces an unhandled rejection *even when the caller has attached its own `.catch()`*. Under Node's default this terminates the process. Its whole spec suite is skipped as "TODO broken tests"; **the tests are right and the code is wrong.**
+8. **`sampler2d_scale_down_lanczos` returns `NaN`.** Its spec is `describe.skip("currently broken")` and it genuinely is: for a 3×1→1×1 downscale every sample lands in the kernel's negative lobe, `if (weight <= 0) continue` discards them all, `weight_sum` is 0, and `0 * Infinity = NaN`. A 2×2→1×1 box returns `4` instead of `2.5`. Three independent defects — discarding negative lobes (the point of Lanczos), a radial rather than separable kernel, and a pixel-centre convention error (`f = i - center` where `i + 0.5 - center` is meant).
+
+---
+
+## 5. API gaps
+
+Both API passes used a deliberately strict inclusion bar — an item qualifies only if it is **(A)** half of a broken pair, **(B)** a member one sibling has and its peer lacks for no reason, **(C)** an omission from a concept's universal contract, or **(D)** documented but absent. Wish-list items, naming, and taste were excluded, and every claimed absence was grepped under several plausible names first.
+
+**The headline result is that the API is in good shape.** Both agents independently reported that most "obvious" absences they chased turned out to exist under a prototype alias or in a sibling file. The core is described as "unusually disciplined about pairs". This is the strongest area of the review.
+
+### 5.1 Where the real gaps cluster
+
+Two clusters, both explicable:
+
+1. **Recently-added typed-array containers, written to exactly one call site and never given the read-back half of their interface.** `Uint32Map` and `PairUint32Map` are Map-like but cannot be enumerated (no `forEach`, no iterator). `IndexedFloatMinHeap`/`MaxHeap` have no `peek` although every sibling heap does. `CSRGraph` exposes a getter that advertises worker transfer but has no `fromArrayBuffer` receiver. `BitImage2` can `set(x,y)` but only clear the whole image.
+2. **Older classes that predate the conventions their newer siblings follow.** `BiMap` aliases `add`/`set` to the Map API but has **no `delete`** — entries can never be removed. `Stack` has no `size`. `ArraySet` has `addAll` but no `removeAll`. `List` has `some()` but no `every()`, and **no `[Symbol.iterator]`** — so `for...of` and spread do not work on the most-used collection in the codebase, while `HashMap`, `HashSet` and `Deque` all support them.
+
+### 5.2 Engine-side gaps
+
+Only one sits on a path a typical game hits:
+
+- **`PhysicsSystem` has `setLinearVelocity` but no `setAngularVelocity`** — and this is not cosmetic: `setLinearVelocity` *wakes the body*, whereas the direct field write a user is forced into does not. The workaround is silently wrong.
+- `Terrain.addLayer` with no `removeLayer`, though both lower tiers support removal.
+- `engine/save`'s `GameStateLoader` imports from outside the package, so the save layer **cannot be loaded standalone from the published library** — and there is no delete.
+
+### 5.3 Two README claims are not reachable
+
+The README is otherwise accurate — instantaneous component queries, ECS scene-graph hierarchy, clustered forward+, 1M+ decals, 256-layer terrain, the path tracer, deterministic physics with CCD, the raycast vehicle and the kinematic FPS controller were each traced to a real entry point. Two are not:
+
+| Claim | Reality |
+|---|---|
+| navmesh **"with agents"** | `NavigationMeshAgent` is an **empty stub**. There is a stateless `find_path` and nothing else — no agent state, steering, or avoidance. |
+| **runtime obstacle carving** | No obstacle primitive exists. Carving is build-time only; the sole way to change the navmesh at runtime is a full rebuild. |
+
+One caveat rather than a gap: *"Tiered API Access — low-level raw typed arrays"* holds for physics, geometry and transforms, but **not for the ECS store itself** — `EntityComponentDataset.components` is `Object[][]` and marked `@private`. The ECS low tier is index-based, not array-based.
+
+---
+
+## 6. Functional test gaps
+
+The suite is green and large (9,337 tests). The question this section answers is not "is coverage high" but **"where would a real defect ship undetected?"** Benchmarks behind `test.skip` are deliberate and were excluded.
+
+**The suite genuinely protects the numerical cores** — physics solver and narrowphase, the acoustic simulator, colour science, the BVHs, the fluid MAC solver, spline/Hermite maths, the path tracer. Those areas have standing gates and this review found almost nothing in them, which is exactly what good tests buy.
+
+**It does not protect serialization, lifecycle, or startup/shutdown at all.** That is precisely where §3's recurring patterns live — the correlation is not a coincidence, it is cause and effect.
+
+### 6.1 The critical gaps
+
+| ID | Gap | What ships broken |
+|---|---|---|
+| **TG-1** | `engine/save/**` — 6 files, **zero specs** | Durability is never verified. Nothing asserts a save actually committed. |
+| **TG-2** | Only **one** component in the entire engine has ever round-tripped through the binary save format | Any field silently dropped, reordered, or read at the wrong width. |
+| **TG-3** | 121 classes implement `toJSON`/`fromJSON`; ~77 also have a binary adapter. **Nothing compares the two.** | A component authored in a JSON blueprint and the same component restored from a save disagree — silently. |
+| **TG-4** | **21 binary format upgraders, zero specs** | The backward-compatibility path for old saves is entirely unverified. An upgrader's only contract is "read exactly the old layout, write exactly the new" — and nothing checks it. |
+| **TG-5** | Transient-entity and non-serializable-component exclusion is structurally unreachable by the suite | Invert either gate and you either persist entities that must not be persisted, or silently drop ones that must be. |
+| **TG-6** | `Engine.js` is 682 lines; `Engine.spec.js` is **15 lines** ("constructor does not throw"). `EnginePluginManager` (319 lines) has no spec; `EngineHarness` (548 lines) is referenced by zero specs. | Every startup-ordering and shutdown defect in §4 — including `Engine.stop()` throwing before it tears anything down. |
+
+TG-2, TG-3 and TG-4 are one gap wearing three hats, and they explain §3.2 completely.
+
+### 6.2 The highest-value MAJOR gaps
+
+- **TG-7 — `link`/`unlink` symmetry is never asserted for any System**, despite `System.js` documenting it as *the* contract. 70 `*System.js` implementations; deleting a single `signal.remove(...)` or `scene.remove(object3d)` turns no test red. This is why §3.1 is the largest defect class in the review.
+- **TG-9 — `view/View.spec.js` is a 6-line smoke test** standing in for `View.js` (804 lines) and 54 subclasses. This is why `view/` contains classes that cannot even be constructed.
+- **TG-11 — `Signal` has nine hand-copied dispatch implementations (`send0`…`send8`); only `dispatch()` is behaviourally tested.** `Signal.merge` forwarding the `arguments` object instead of the arguments was found by this review and sits in exactly that untested band.
+- **TG-10 — eleven of twelve asset loaders are untested**; the `AssetManager` contract ("call exactly one of `callback`/`failure`") is only ever proven against stubs, never against a real loader. Both asset CRITICALs are settlement-contract violations.
+- **TG-12 — grid↔world conversion tests only one direction, never the round trip**, and never on a non-square grid.
+
+### 6.3 The cheapest closing move by far
+
+Three generic, table-driven harnesses would close TG-2, TG-3, TG-4 and most of §3.2 at once:
+
+1. **Triple round-trip**, driven by the registered-class list: assert `field-init == fromJSON(toJSON()) == fromBinary(toBinary())` for every registered component. Covers ~121 classes in one spec.
+2. **Per-upgrader golden bytes**: hand-construct the old-version buffer, run the upgrader, assert the exact new bytes. 21 small specs.
+3. **`link`/`unlink` symmetry harness**: build a real `EntityComponentDataset`, link a system, unlink it, assert no residual subscriptions. Applies to 70 systems.
+
+These are worth more than any individual fix in this review, because they convert an entire recurring class from invisible to caught.
+
+### 6.4 Stale skips
+
+Three skipped suites are not benchmarks and should be resolved rather than left:
+
+- `core/process/PromiseWatcher.spec.js` — **whole suite** skipped as "TODO broken tests". Un-skipping it crashes the Node worker with an unhandled rejection, because `PromiseWatcher.add()` discards the promise returned by `.finally()`. **The tests are right and the code is wrong.**
+- `engine/graphics/texture/sampler/resize/sampler2d_scale_down_lanczos.spec.js` — skipped as "currently broken". Verified: **still broken** (see §4).
+- `core/binary/BitSet.spec.js` "resizing up and down" — verified: **now passes**. Just un-skip it.
+
+---
+
+## 7. Adversarial review
+
+Every CRITICAL, plus every MAJOR making a total-failure claim ("never works", "always throws", "renders nothing"), was handed to independent verifiers **instructed to refute it**, defaulting to REFUTED under uncertainty. They were given six explicit grounds for rejection: the code does not say what the finding claims; the trigger cannot occur; `assert.*` confusion; deliberate documented behaviour; severity inflation; already fixed. Verifiers preferred *execution* over reading — writing throwaway specs, running them, and deleting them.
+
+**174 findings checked: 160 confirmed, 2 refuted, 12 downgraded.**
+
+| Pass | Checked | Confirmed | Refuted | Downgraded |
+|---|---:|---:|---:|---:|
+| core (collection, binary, process, math, science) | 67 | 58 | 0 | 9 |
+| view + engine misc | 45 | 44 | 0 | 1 |
+| graphics, geom, ecs, asset | 62 | 58 | 2 | 2 |
+
+### What this tells us
+
+**Factual accuracy was high; severity calibration was not.** Verifiers reported that claims "reproduced exactly, often to the digit". Only two findings were factually wrong, both in the same report (`gfx-gi`) and both resting on incorrect premises about three.js r136 — checked against the *installed* `node_modules/three`, not from memory:
+
+- **GFXG-3 REFUTED** — r136 `ShaderMaterial` defaults `fog = false`, so the block claimed to fail compilation is unreachable.
+- **GFXG-4 REFUTED** — `computeMaterialEquality` returns false for all `ShaderMaterial`s, so the claimed bad dedup cannot happen.
+
+The 12 downgrades share **one** cause, and it is the most important calibration lesson in this review: *a total break of public API surface that no shipped code path reaches.* `SortedListProjection`, `Signal.merge`, `BiMap`, `hammersley_sequence`, `extractTransferables` and `IsAnything` are genuinely broken — reproduced — but nothing in the shipping game calls them.
+
+This is a real tension with the project's standing convention that unreferenced exports are public surface, not dead code. **Both things are true**: they are real bugs in a published library and must be fixed, *and* they cannot break the game today. The proposal in §8 resolves this by separating **"breaks the shipping product"** from **"breaks a published API"**, rather than collapsing them into one severity axis.
+
+### Post-adversarial totals
+
+| | CRITICAL | MAJOR | MINOR | total |
+|---|---:|---:|---:|---:|
+| Raw | 50 | 237 | 153 | 440 |
+| **After adversarial adjustment** | **42** | **239** | **157** | **438** |
+
+**Confidence.** 174 of 438 findings (40%) were independently verified, weighted toward the severe end — every CRITICAL was checked. In that sample the factual error rate was **1.1%** (2/174). Unverified MINORs carry the source reports' reliability rather than a verifier's; the risk there is severity, not fabrication.
+
+### One test-reliability note
+
+`engine/simulation/Ticker.spec.js` → *"no ticks are dispatched while the page is hidden"* failed once in a full-suite run under heavy CPU contention, and passed 9/9 in three isolated runs and in a clean full re-run. It is **timing-flaky under load**, not a regression. Worth pinning to fake timers before it erodes trust in the suite.
+
+---
+
+## 8. Proposal
+
+Tagged **CRITICAL / MAJOR / MINOR**. Because a published library has two distinct failure surfaces, each item also carries a reach marker:
+
+- **[product]** — breaks the shipping game today.
+- **[library]** — breaks a published API; no in-repo caller, so invisible to the game but live for any consumer.
+
+Phases are ordered by value-per-effort, not by severity alone.
+
+### Phase 0 — Silent data loss and cannot-run-twice · **CRITICAL**
+
+Small, well-understood, high blast radius. Land each with a red-before-green regression test.
+
+| Item | Tag | Reach |
+|---|---|---|
+| `BinaryBuffer.writeUTF8String` zeroes the body on mid-write growth. Fix: advance `this.position` as the loop writes, or copy to `cursor` rather than `position` in `setCapacity`. | **CRITICAL** | product |
+| `ThemeEngine`/`TerrainTheme` pass a `[0,1)` float as a child seed; Mulberry32 truncates it to a constant. Fix: derive integer child seeds. Restores all seed variation in the theme layer. | **CRITICAL** | product |
+| `ShadedGeometrySystem` never removes its render layer; second engine start throws. Fix teardown, plus the three sibling leaks (`CameraSystem.rebuild`, `LightSystem` cache, `LightManager.dispose`). | **CRITICAL** | product |
+| `AtlasLookupTexture` allocates no storage for the first 32 patches. Fix the reallocation guard and the `RGBA`/`RGB16UI` format mismatch. | **CRITICAL** | product |
+| `WebGLTextureAtlas.add` never records patch size; `TextureAtlas.repack()` clears `Packed` twice and never `Painted`. | **CRITICAL** | product |
+| `ParticleGroup` reuses one swap source for every deletion; `optimizeCommandQueue`'s comparator never returns `+1`. Corrupts particle data on any multi-delete frame. | **CRITICAL** | product |
+| BVH8 `NodeProxy` loop runs at `j = -1`, emitting structurally invalid nodes on ~0.2% of ordinary builds. | **CRITICAL** | product |
+| `ServerAuthoritativeClient` reconcile watermark is per-frame not per-entity — a client owning >1 predicted entity reconciles exactly one, forever. | **CRITICAL** | product |
+| The four **unfixed 2026-07-03 CRITICALs**: `C5` decal `subscribe`/`unsubscribe`, `C13` terrain seam floor-vs-ceil, `C17`+`C18` MikkTSpace (faceted tangents + failed vertex welding on every real mesh). | **CRITICAL** | product |
+| `Engine.stop()` throws before tearing anything down; `Engine.start()` swallows startup failure and resolves. | **CRITICAL** | product |
+| `save/IndexedDBStorage` resolves on request success rather than transaction commit — a save can be reported successful and not committed. | **CRITICAL** | product |
+
+### Phase 1 — Three generic harnesses · **CRITICAL**
+
+**This is the highest-value work in the review**, and it should be done *before* the long tail of individual fixes. Each converts an entire recurring class from invisible to caught, and each is one parameterised spec.
+
+| Harness | Closes | Tag |
+|---|---|---|
+| **Triple round-trip** over the registered-class list: `field-init == fromJSON(toJSON()) == fromBinary(toBinary())`. ~121 classes. | TG-2, TG-3, and the whole of §3.2 | **CRITICAL** |
+| **Per-upgrader golden bytes**: construct the old buffer, run the upgrader, assert exact new bytes. 21 upgraders, currently zero specs — this is the old-save migration path. | TG-4 | **CRITICAL** |
+| **`link`/`unlink` symmetry**: real dataset, link a system, unlink, assert no residual subscriptions. 70 systems. | TG-7, and most of §3.1 | **CRITICAL** |
+
+Without these, Phase 2 is a treadmill: the same classes will regrow.
+
+### Phase 2 — Pattern sweeps · **MAJOR**
+
+Fix the class, not the instance. Each is a mechanical pass now that a harness exists to hold it.
+
+- **[MAJOR, product]** Lifecycle sweep — every `link`/`startup` subscription needs a matching removal on the *same* signal with the *same* context; every GPU/DOM resource acquired needs disposal. Largest single defect class.
+- **[MAJOR, product]** Serialization sweep — reconcile JSON, binary, and field-initialiser defaults per component. Includes point lights losing `distance`, water losing 7 of 9 fields, `SerializationMetadata` truncated to 8 bits, `Team`'s `INT32_MAX`/`Infinity` aliasing.
+- **[MAJOR, product]** Promise-terminal sweep — `ConcurrentExecutor`, `ActionProcessor.doMany`, `WorkerProxy`, `ArrayBufferLoader`, `SVGAssetLoader`, `GameStateLoader`, `EngineHarness`. Every path must settle exactly once; failure must not resolve.
+- **[MAJOR, product]** Sentinel-boundary sweep — make degenerate results *signalled* rather than encoded. `tri3_compute_normal` is the model case; it also drives `GFXT-45`.
+- **[MAJOR, product]** Grep sweep for the mechanical classes: `& 0xff` precedence, `>>` vs `>>>`, `x|0` as floor, bare `.sort()` on numbers.
+- **[MAJOR, product]** Device shutdown/cancellation — `PointerDevice` and `KeyboardDevice` leave input latched down after `stop()`, blur, or `pointercancel`.
+
+### Phase 3 — Area rehabilitation · **MAJOR**
+
+- **[MAJOR, product]** `view/` — 42 findings, 6 of them classes that cannot run. Two root patterns cover most of it: raw `Signal.add` on caller-owned models instead of `bindSignal`, and teardown gated on `view.isLinked` *after* `View.unlink()` has already cleared it. Pair with TG-9 (a real `View` lifecycle spec) or it will regress.
+- **[MAJOR, product]** `graphics/texture` — 76 findings. The algorithms are fine; the type/format pairings are not (`Uint8ClampedArray`, `Float16`, integer-vs-normalized internal formats, interleaved attributes, the `normalized` flag).
+- **[MAJOR, library]** `core/debug` matcher library — `anything()` matches nothing, `nothing()` matches everything, the template formatter never substitutes. Broken as published; nothing in-repo reaches it.
+- **[MAJOR, library]** `ActionProcessor` — two independent ways to permanently brick itself (redo crash after undo→do→redo; `doMany` failure deadlocks every later call).
+- **[MAJOR, product]** Behaviour-tree lifecycle — `initialize`/`finalize` pairing across `ParallelBehavior`, `ConditionalBehavior`, `RepeatBehavior`.
+- **[MAJOR, product]** `sampler2d_scale_down_lanczos` — needs a real rewrite (separable kernel, keep negative lobes, pixel-centre convention), then un-skip its spec.
+
+### Phase 4 — API and documentation · **MINOR**
+
+- **[MAJOR, product]** `PhysicsSystem.setAngularVelocity` — the only API gap on a hot path, and the workaround is *silently wrong* because the direct field write does not wake the body.
+- **[MAJOR, library]** `BiMap` has no `delete`; `List` has no `[Symbol.iterator]` or `every()`; `Uint32Map`/`PairUint32Map` cannot be enumerated; `IndexedFloat*Heap` has no `peek`; `CSRGraph` has no `fromArrayBuffer` receiver.
+- **[MAJOR, product]** Correct the README, or build the features: **navmesh "with agents"** (`NavigationMeshAgent` is an empty stub) and **runtime obstacle carving** (no obstacle primitive exists) are advertised and absent. Also soften *"low-level raw typed arrays"* for the ECS store, which is `Object[][]` and `@private`.
+- **[MINOR, library]** `engine/save` cannot be loaded standalone from the published package (`GameStateLoader` imports outside the package). Also no delete.
+- **[MINOR]** Resolve the three stale skips: un-skip `BitSet` "resizing" (now passes), fix `PromiseWatcher` (the tests are right, the code is wrong), fix Lanczos then un-skip.
+- **[MINOR]** Pin `Ticker.spec.js`'s hidden-page test to fake timers.
+
+### Sequencing
+
+Phase 0 and Phase 1 are independent and can run in parallel; **Phase 1 should not be deferred behind Phase 0**, because it is what stops Phases 2–3 from regressing. Phases 2–3 are large but mechanical once the harnesses exist. Phase 4 is cheap and can be slotted anywhere.
+
+**The single most valuable decision available** is to build the three harnesses in Phase 1. This review found 438 defects in a codebase with a green 9,337-test suite; the gap is not effort or skill, it is that the engine's *edges* have no contract tests, so defects there are structurally invisible. Fixing 438 bugs without closing that gap buys a snapshot. Closing it buys a ratchet.
+
+
+---
+
+## 9. Remediation outcome
+
+The proposal above was executed. This section records what actually landed, and — more usefully — where the review's own conclusions turned out to be wrong.
+
+**23 commits. Suite: 1554 suites / 9507 tests green, up from 1542 / 9337. Skips down from 136 to 129.**
+
+### Phase 0 — the CRITICALs on the Phase 0 list
+
+**Not every CRITICAL in this document.** Section 8's Phase 0 was a curated
+subset chosen for blast radius; the review found 50 CRITICALs in total and
+**14 of them are fixed**, alongside the 4 outstanding CRITICALs inherited from
+the 2026-07-03 review (C5, C13, C17, C18). **36 discovered CRITICALs remain
+open**, listed at the end of this section.
+
+`writeUTF8String` data loss · theme seed invariance · MikkTSpace edge pairing and vertex welding (C17/C18) · decal `subscribe`/`unsubscribe` (C5) · terrain seam floor-vs-ceil (C13) · three broken atlas paths · particle compaction · BVH8 `triangles[-1]` · engine headless/failure lifecycle · save durability · network per-entity reconcile.
+
+Two shipped without a regression gate and were flagged as such: the decal fix (its context needs the whole Forward+ plugin) — now gated by the teardown contract — and IndexedDB durability, which has no IDB implementation available to the suite.
+
+### Phase 1 — three contract harnesses
+
+| Harness | Covers | Found |
+|---|---|---|
+| binary round-trip | 48 of 77 adapters meaningfully exercised, the rest reported with reasons | Camera losing its entire lens; flags dropped by four components |
+| teardown contract | every source in the tree | proven against the real decal defect |
+| upgrader chain | 21 upgraders | **Path writes version 3 with no 2→3 upgrader — every older save unloadable** |
+
+A fourth (runtime link/unlink symmetry) was prototyped and **dropped**: it reached only 7 of ~70 systems and reported four leaks that could not be attributed to either the system or the harness. Baselining unexplained results would record noise as signal.
+
+### Phases 2–4
+
+Serialization: Camera v1 with upgrader. Promise terminals: `ConcurrentExecutor` no longer drops a task whose dependency failed, `Future` settles once, `PromiseWatcher` no longer leaks an unhandled rejection. Areas: the Lanczos downscaler rewritten (it returned `NaN`), `ViewGroup` and `MinimapMarkerView` made constructible, `anything()`/`nothing()` un-inverted. API: `setAngularVelocity`, `List.every`/iterator, `BiMap` removal. README corrected on navmesh agents and runtime obstacle carving.
+
+### Corrections to this document
+
+Adversarial review of the implementation refuted several of the findings above. Recorded because a review that only accumulates is not trustworthy:
+
+- **`optimizeCommandQueue` was downgraded on false grounds.** The first fix claimed the missing `+1` branch could not be shown to change V8's output. Wrong — the sample inputs were too small. Every permutation of a five-operation multiset finds orderings where a write sorts ahead of a remove.
+- **The round-trip harness's first baseline was ~30 entries of the harness's own making.** It claimed Light and Water lose their colours entirely. They do not: the perturber assigned colour channels outside the 0..1 domain, and the 8-bit pack clamped them. What survives is narrower — `Color.toUint()` is RGB-only, so alpha is dropped by design.
+- **`TransformPose` declaring `klass = Transform` is deliberate**, not a collision: it is a second, local interpolation format. A name-keyed chain check mistakes it for the save adapter.
+- **`BiMap`'s inverted stores are load-bearing.** Flipping `add` to match its parameter names would have broken `EncodingBinaryBuffer`'s string interning. The names were corrected instead.
+- Three Phase 0 fixes stopped one step short of the defect they named (`WebGLTextureAtlas` position, the lone-surrogate desync, `Engine.stop` leaving the render loop running), and one introduced a regression (an empty atlas allocating a 32×0 texture).
+
+### CRITICALs still open
+
+```
+AI-1 ANIM-1 ASSET-1 ASSET-2 BIN-2 COLL-1 COLL-3 ECS-1 ECS-14 ECS-40 GEN-2
+GEOM3-1 GFXG-1 GFXG-2 GFXR-11 GFXT-1 GFXT-2 GFXT-3 GFXT-4 GFXT-32 GFXT-40
+GFXT-68 GFXT-69 INPUT-1 INPUT-2 INPUT-3 MATH-1 MATH-2 PROC-10 PROC-11
+PROC-19 PROC-20 VIEW-1 VIEW-2 VIEW-4 VIEW-6
+```
+
+Worth pulling out, because they are cheap relative to their reach:
+
+- **GFXR-11** `ShadedGeometrySystem` never removes its render layer, and
+  `RenderLayerManager.add()` throws on a duplicate — the *second* engine start
+  throws. This was named in the Phase 0 list and never implemented.
+- **GEOM3-1** the mesh simplifier's flip test degenerates to "does this face
+  point downward", via `tri3_compute_normal`'s `(0,1,0)` sentinel.
+- **PROC-10 / PROC-11** `ActionProcessor` has two independent ways to brick
+  itself permanently.
+- **INPUT-2** pointer "down" state can never be cleared — no `pointercancel`
+  or blur handling.
+- **VIEW-1 / VIEW-2 / VIEW-4 / VIEW-6** four more `view/` classes that throw or
+  silently do nothing.
+
+### What remains
+
+The bulk of the 438 findings — most MAJORs and nearly all MINORs — is untouched. The `KNOWN_DIVERGENCE` baseline in the round-trip harness is the honest ledger for the serialization class: each entry deleted is one component that survives a save. Golden-bytes verification of what each upgrader *emits* is still outstanding; the chain check only proves a path exists.
+
+---
+
+## 10. Round 2 proposal
+
+Selection rule for this round: **only work where the correct behaviour is not a design decision.** A fix qualifies if the current code is wrong against a contract that already exists elsewhere in the tree — a sibling that does it right, a documented convention, a method that does not exist, a promise that cannot settle. Anything requiring a judgement call about intended behaviour is deferred, not because it matters less but because guessing at intent is how a review turns into a rewrite.
+
+Second constraint: **performance characteristics are load-bearing.** Two candidates below sit on hot paths and are called out individually; neither is worth a correctness fix that costs a per-frame allocation or a per-sample branch.
+
+### 10.1 Batch A — wrong identifier, no behavioural judgement (12)
+
+Each is a single wrong token whose correct value is fixed by the surrounding code. No design latitude, no perf surface.
+
+| ID | Site | Wrong | Right |
+|---|---|---|---|
+| GFXT-1 | `sampler2d_paint.js:68` | `x + sourceY` | `x + sourceX` |
+| GFXT-40 | `computeMeshSurfaceArea.js:40` | vertex C's Y read from the Z slot | `points[c3 + 1]` |
+| GFXT-2 | `bitSet2Sampler2D.js:35,37` | `target.set(...)` — `Sampler2D` has no `set` | `target.write(...)` |
+| GFXT-3 | `computeSignedDistanceField_Chamfer.js:72` | stale `v`, stores last instead of min | assign `v = vN` after each write |
+| GFXT-68 | `Ribbon.js:143` | tip vertices on opposite sides | negate the cross to match the degenerate branch |
+| GFXT-69 | `load_environment_map.js:57` | `EXRLoader` asked for `UnsignedByteType` | `HalfFloatType` |
+| ECS-40 | `LineSetDescription.js:56` | walks `set.children`, unbounded loop | `set.sets` |
+| ECS-14 | `TerrainTileManager.js:461` | reads the vertical axis as a grid row | index by `v3[0]`/`v3[2]` |
+| COLL-3 | `Signal.js:797` | dispatches the `arguments` object | spread it |
+| BIN-2 | `Localization.js:140` | trailing-slash trim never terminates | slice, do not re-test |
+| INPUT-1 | `TopDownCameraControllerHelper.js:45` | geometry classes never imported | import them |
+| GFXR-11 | `ShadedGeometrySystem.js:254` | render layer never removed; second start throws | remove it in `shutdown` |
+
+### 10.2 Batch B — a promise that cannot settle (3)
+
+The contract is not in question: a path that neither resolves nor rejects is a hang.
+
+- **PROC-20** `WorkerProxy` — a failed `postMessage` drops the request without rejecting.
+- **ASSET-2** `ArrayBufferLoader` — a fetch stream error mid-download never reaches the consumer; `pump()` has no rejection handler.
+- **PROC-19** `extractTransferables(null)` throws while the inline duplicate a few lines away guards for exactly that.
+
+### 10.3 Batch C — hot path, correctness *and* cost (2)
+
+Both are real defects. Both sit somewhere the naive fix is unacceptable, so each carries a required approach.
+
+- **MATH-1** — `sdnoise` computes its lattice cell with `x | 0`, which truncates toward zero and is therefore wrong for every negative coordinate. This is the inner loop of noise generation. `Math.floor` is the obvious fix and must be **measured, not assumed**: if it costs anything measurable, use the branchless `(x | 0) - (x < 0 ? 1 : 0)` form instead. Correctness is not negotiable; which of the two lands is a measurement.
+- **INPUT-3** — `InputControllerSystem` mutates its binding array mid-dispatch, so destroying an entity from an input handler throws. The stated fix is "iterate a snapshot", but dispatch runs per input event and a per-dispatch `slice()` is a per-event allocation in a zero-allocation engine. Prefer a reverse walk or an index-stable removal that needs no copy.
+
+### 10.4 Explicitly deferred, with reasons
+
+Not "lower priority" — genuinely not unambiguous:
+
+- **ANIM-1**, **GEOM3-1** — the fix changes which result the algorithm considers best. That is a behavioural change needing a decision, not a repair.
+- **ECS-1**, **GEN-2**, **VIEW-1/2/4**, **PROC-10/11** — each needs a lifecycle or task-graph restructure with more than one defensible shape.
+- **GFXG-1**, **GFXG-2**, **GFXT-4** — GPU-side or shared-buffer ownership; cannot be verified from the suite, and `GFXT-4`'s fix trades a mutation for a copy, which is a perf decision.
+- **ASSET-1** (Adam7), **INPUT-2** (`pointercancel`), **MATH-2**, **COLL-1**, **AI-1**, **GFXT-32** — each is likely correct as written up, but each needs a fixture or a browser behaviour I cannot confirm here, and shipping an unverified fix to a CRITICAL is worse than leaving it listed.
+
+### 10.5 Revision after adversarial review of the proposal
+
+The proposal was reviewed before any of it was written. Three items were wrong, one was missing, and two deferrals were unjustified.
+
+**Removed from the plan:**
+
+- **GFXT-68** (`Ribbon`) — *not unambiguous.* With `normal = -Z` the unnegated branch already agrees; the correct sign depends on a winding convention that is not stated anywhere in the tree. Negating on a guess would invert every ribbon. Deferred.
+- **INPUT-3** — *the prescribed fix is wrong.* A reverse walk inverts binding priority order, and does nothing about `registerBinding`'s re-sort, which is the actual source of the mutation. Deferred until the dispatch/registration interaction is understood.
+
+**Corrected:**
+
+- **MATH-1** — the fallback this document proposed, `(x | 0) - (x < 0 ? 1 : 0)`, **is not floor**: it over-subtracts at exact negative integers (`floor(-1) = -1`, the form yields `-2`). Measurement also shows no penalty for `Math.floor` — across warmed runs the two are indistinguishable, and the variance between repeats of the *same* function exceeds the difference between them. So the fix is plainly `Math.floor`. Separately, it turns a currently-green spec red, which has to be resolved on its merits: a spec that pins truncation is pinning the defect.
+- **ECS-14** — the table lost the load-bearing half of the fix. The divisors matter: index by `v3[0] / scale.x` and `v3[2] / scale.y`. `scale.y` really is the right divisor for the Z axis (the terrain's scale is 2D).
+
+**Added — it was missing from both lists:**
+
+- **VIEW-6** `Minimap.clear()` calls `addChild` where `removeChild` is meant, from `unlink()`. One wrong token, intent fixed by the method name. It belongs in Batch A and was simply dropped.
+
+**Promoted out of "deferred" — the stated reason was false:**
+
+- **COLL-1** `SortedListProjection` — deferred as needing a fixture; it reproduces in plain node in seconds, and the `where + 1` insert is forced by `binarySearchLowIndex`'s contract.
+- **MATH-2** `hammersley_sequence` — deferred for the same false reason; it is pure maths with a sibling (`halton_sequence`) as the reference and no callers to break.
+
+**Two items are sound but cannot take the red-test-first protocol**, and are marked as such rather than pretended otherwise: **GFXT-69** (no `.exr` fixture exists) and **BIN-2** (the red test wedges the jest worker synchronously, because the bug is an infinite loop).
+
+## 11. Round 2 outcome
+
+Landed across `1c13a74ae`, `18f627741`, `62047e542`, with a self-review after each. Every item below is pinned by a test that was verified red against the unfixed code, except where stated.
+
+### 11.1 What landed
+
+**Batch A — wrong identifier (11 of 12).**
+
+| ID | Site | Pinned by |
+|---|---|---|
+| GFXT-1 | `sampler2d_paint` read the source column from `sourceY` | `sampler2d_paint.spec.js` |
+| GFXT-40 | `computeMeshSurfaceArea` read vertex C's Y from the Z slot | `computeMeshSurfaceArea.spec.js` |
+| GFXT-2 | `bitSet2Sampler2D` called `target.set`, which does not exist | existing sampler specs |
+| GFXT-3 | chamfer SDF compared each candidate against the original, not the running minimum | `computeSignedDistanceField_Chamfer.spec.js` |
+| GFXT-69 | `EXRLoader` asked for `UnsignedByteType` | *not pinned — no `.exr` fixture* |
+| ECS-40 | `LineSetDescription.collect` re-walked the root's children forever | `LineSetDescription.spec.js` (times out unfixed) |
+| ECS-14 | `TerrainTileManager` world lookup: vertical axis read as a grid row, grid scale not divided out | `TerrainTileManager.spec.js` |
+| COLL-3 | `Signal.merge` dispatched the `arguments` object as one argument | `Signal.spec.js` |
+| BIN-2 | `Localization` trailing-slash trim discarded the slice and never terminated | `Localization.spec.js` |
+| INPUT-1 | `TopDownCameraControllerHelper` used geometry classes it never imported | import resolution |
+| GFXR-11 | `ShadedGeometrySystem` never released its render layer, so a second startup threw | `RenderLayerManager.spec.js` (contract only) |
+
+GFXT-68 (`Ribbon`) stayed deferred, per §10.5.
+
+**Batch B — a promise that cannot settle (3 of 3).** `WorkerProxy` (failed `postMessage` dropped the request), `ArrayBufferLoader` (stream failure never reached the consumer), `extractTransferables` (threw on `null`). All three pinned; the first two time out against the unfixed code.
+
+**Batch C.** `MATH-1` deferred — see §11.3. `INPUT-3` deferred per §10.5.
+
+**Promoted out of "deferred".** `COLL-1` (`SortedListProjection` insert position) and `MATH-2` (`hammersley_sequence`), both pinned. `hammersley_sequence` also lost its `count` parameter: the radical inverse does not depend on the size of the set, no version of the body ever read it, and the function has no callers in the tree — it is pure published surface, so a parameter documented as permanently unused is worse for a library consumer than a clean two-argument signature.
+
+### 11.2 What the self-review of this round caught
+
+The round-2 work was itself reviewed, and it found four defects in the fixes and three false statements. Recording both, because a review that only records the wins is not a review.
+
+**Defects in the round-2 work, since fixed in `62047e542`:**
+
+- **`hammersley_sequence` — a regression I introduced.** Correcting the accumulator turned the incremental formulation numerically unstable: base 3 produced **13 distinct values over 512 samples**. The spec tested base 2 only, so it stayed green. Rewritten to the closed-form radical inverse that the sibling `halton_sequence` already uses — O(log i) instead of O(i), stable for any base — and the spec now cross-validates against `halton_sequence` for bases 2/3/5/7/11 and asserts 512-sample distinctness. **The missing distinctness check is the reason this got through, and it is the durable part of the fix.**
+- **ECS-14 landed half-done.** §10.5 explicitly called the scale divisors "the load-bearing half", and the implementation applied the axis fix without them. Wrong tile for every terrain whose `gridScale` is not 1.
+- **`ArrayBufferLoader` was still one throw away from a hang.** The rejection handler went in as the second argument to `.then`, which cannot see a throw from its own fulfilment path — so a throwing caller-supplied `progress` callback still wedged the load forever. Now `.catch`, and pinned.
+- **`Minimap.clear()` was justified with a comment about the wrong array, and stopped short of the real defect.** `removeChild` does not mutate the array the `.slice()` was defending, and `removeObserver(observer, true)` has usually emptied `__cameraViews` before `clear()` runs — so as written the fix was close to inert. The array is assigned **in the constructor**, not in `link()`, and `link()` re-registers the observer with `notify = true`; leaving stale entries in it therefore breaks the second `link()` after an `unlink()` — the same cannot-run-twice shape as GFXR-11. `clear()` now drops the entries too.
+
+**False statements, corrected:**
+
+- **Two Batch A items were listed as landed and were not: BIN-2 and GFXT-69.** Both have since landed. GFXT-69 was worse than the table said — `EXRLoader` does not merely prefer float types, it falls through to a `default` branch that never allocates the output buffer, so *no* `.exr` environment map could load at all.
+- **The chamfer commit claimed the fix meant "fewer stores".** Measured, it is **13% more stores and about 2% slower**. The fix is still correct and still lands; the justification was invented. Cost, measured: negligible against a two-pass sweep that is memory-bound anyway.
+- **The MATH-1 deferral reasoning was not honest** — see below.
+
+### 11.3 MATH-1, restated honestly
+
+The deferral was argued on the grounds that `FASTFLOOR` is "neither truncation nor floor, so the correct target is unclear". That is false, and the argument does not survive contact with the code:
+
+- `FASTFLOOR` **equals `Math.floor` at every non-integer input**, and differs only at exact negative integers.
+- `x | 0` differs from **both** at every negative coordinate — it is the one form that is wrong everywhere below zero.
+- `create_simplex_noise_2d.js`, in the same directory, **already made this exact fix and has a regression spec for it.** The convention is settled in the tree.
+
+So MATH-1 is unambiguous on its merits and belongs in Batch A. The one real reason to hold it is unchanged and sufficient on its own: **`sdnoise` feeds procedural generation, and changing lattice cell selection re-rolls every generated map from a given seed.** That is a content decision with a migration cost, not a code decision — it needs a deliberate call about whether existing seeds are allowed to change, and it should land on its own so the diff in generated output is attributable.
+
+Measurement, since the original proposal asked for it: `Math.floor` and `x | 0` are indistinguishable across warmed runs — repeat-to-repeat variance on the *same* function exceeds the gap between them. **There is no performance argument on either side.** The proposal's suggested branchless fallback `(x | 0) - (x < 0 ? 1 : 0)` is not floor at all (it yields `-2` for `floor(-1)`) and must not be used.
+
+### 11.4 Standing state
+
+Round 2 closed 16 items. The CRITICALs listed as still open in §9 are unchanged by this round except for ECS-14 and BIN-2 — round 2 deliberately took the unambiguous work, and the open CRITICALs are open precisely because they are not.
+
+The three durable additions from this round are worth more than the individual fixes: the `hammersley` distinctness check, the `ArrayBufferLoader` settle-under-failure specs, and `Localization`'s first spec (which drives a real `AssetManager` through a real loader, the pattern the rest of the loader tests should follow).
+
+## 12. Review of the round-1 and round-2 commits
+
+A pass over all 34 commits, in `62047e542..a0e4b9dbc` plus the round-1 range. The point was to find defects in the remediation itself, so what follows leads with those.
+
+### 12.1 Verified rather than assumed
+
+- **Particle compaction** — the swap plan was brute-forced against a reference over every victim subset for arrays up to 12 elements: 8178 cases, 0 mismatches.
+- **Camera 0→1 and Path 2→3 upgraders** — executed end to end; see §12.3, which turned this into a standing harness.
+- **Both new upgraders are registered** in `GameBinarySerializationRegistry.js` (`3ecf5c16`, `8b8df83a`). A version bump without registration silently breaks every existing save, and that was the failure worth checking.
+- **`ServerAuthoritativeClient`** — `Uint32Map.get` does return −1 for absent; network ids come off a free list, so the watermark map is bounded by peak concurrent entities rather than leaking; and a recycled id inherits a watermark that is always behind the current server frame, so reuse cannot drop state.
+- **Physics hot paths** — `solve_constraints`, `convex_convex_manifold`, `raycast`, `ManifoldStore`, `quat3_multiply`: zero executable changes across the whole range, JSDoc only.
+- **`BiMap`** — the argument swap is names-only; identical behaviour for the same positional call.
+- **`Engine` lifecycle** — `Ticker.start` re-adds its lifecycle listeners, so `stop()`→`start()` is clean; the one consumer testing `graphics === undefined` also tests for null; and `start()` already returned a promise before it became `async`.
+- **The round-trip harness is not vacuous** — deleting a field's restoration from an adapter turns it red on exactly that adapter.
+
+### 12.2 Defects found in the remediation, and fixed
+
+- **`IndexedDBStorage.store` rejected up to three times for one failure.** `resolve`/`reject` there are the caller's own callbacks, not promise settle functions, and a failed write raises `error` on the request, bubbles to `error` on the transaction, then aborts it — with a listener on each. In-tree callers wrap the call in a promise, which hides it; `Storage` is published API, so an external consumer saw one lost save reported three times. Now it rejects on `abort` alone, which is the event that always fires for a transaction that will not commit, and it carries `transaction.error` as the reason. The storage classes had no specs at all; they have one now.
+- **The Lanczos `weight_sum === 0` fallback was unreachable.** Swept over every downscale ratio from 1 to 40 at 2 and 3 lobes, the weight sum was never zero, never negative, and never below 1. The NaN it claimed to prevent came from the *old* `if (weight <= 0) continue`, which discarded the negative lobes — and the rewrite had already removed that. Keeping the whole kernel makes the sum the integral of the kernel over the footprint, which stays near 1. Removed: it was precisely the defensive guard for a can't-happen condition this project rejects, and its comment described a failure the new code cannot produce.
+
+### 12.3 The gap that mattered most: upgraders were never executed
+
+`upgrader_chain_contract.spec.js` checks that a path from every historical version to the current one *exists*. That catches a missing upgrader, which is what it was built for. It does not catch an upgrader that is present and emits the wrong layout — and at load time that is the worse failure, because the deserializer then reads real bytes at wrong offsets instead of failing loudly. Its own docblock admitted this and left it outstanding.
+
+`upgrader_execution_contract.spec.js` closes it. Each covered upgrader gets a source buffer in the layout it reads, the chain runs to the current version through `executeBinaryClassUpgraderChain` — the same executor production uses — and the current adapter deserializes the result. The assertion that does the work is the byte count: the adapter must consume exactly what the chain produced.
+
+Two properties make it honest rather than decorative:
+
+- **It is a check of what an upgrader *writes*, not what it reads.** The golden describes the start version's layout, which is derived from the upgrader's own reads. The adapter that originally wrote that layout is gone, so there is nothing left to check the read side against, and the spec says so instead of implying otherwise.
+- **Coverage is enumerated, not assumed.** 9 of 23 upgraders have goldens; the other 14 are listed in `WITHOUT_GOLDEN`, and a new upgrader that appears in neither list fails the spec. Each entry is a save-format version nothing verifies can still be read.
+
+Mutation-verified in both directions: making an upgrader emit one extra field, and making it omit one, each turns its own case red.
+
+### 12.4 Left open, deliberately
+
+- **The Lanczos rewrite changed the filter shape** from radial (`sqrt(fx²+fy²)`) to separable (`L(x)·L(y)`). Separable is the correct Lanczos and it is cheaper — O(rx+ry) transcendental evaluations per output pixel instead of O(rx·ry) — but every downscaled texture now differs from before, and the commit framed it purely as a NaN fix. Recorded here rather than reverted; the old behaviour was not worth preserving.
+- **`sampler2d_scale_down_lanczos` throws "source is larger than destination"** when the condition, `source_width < d_w`, means the source is *smaller*. Pre-existing, and left alone rather than folded into an unrelated change.
+- **`IndexedDBStorage.remove` still reports success off the request** rather than the transaction commit — the same durability gap `store` had. Not touched here because it is a separate defect from the triple-reject this pass was fixing, and it deserves its own change.