@woosh/meep-engine 2.168.1 → 2.169.1

package/src/REVIEW_2026_08_06/api-core.md

@@ -0,0 +1,296 @@
+# API-GAP analysis — `meep/src/core`
+
+Scope: `H:/git/moh/app/src/mir-engine/meep/src/core/`. Every path below is public API
+(`package.json` exports `./src/*`, no barrels).
+
+18 items. 6 MAJOR, 12 MINOR. Two corrections to the lead's pre-findings are at the bottom,
+along with the packages that came back clean.
+
+---
+
+### APIC-1 `BinaryBuffer.writeFloat64Array`
+- **Severity**: MAJOR
+- **Package**: core/binary
+- **Test met**: A (and D — the spec file names the missing symbol)
+- **Absent symbol**: `BinaryBuffer.prototype.writeFloat64Array(source, source_offset, length)`
+- **Evidence**: `core/binary/BinaryBuffer.js:547` defines `readFloat64Array`. Every other bulk
+  reader has a matching bulk writer — `writeFloat16Array:574`, `writeFloat32Array:559`,
+  `writeInt8Array:689`, `writeInt16Array:707`, `writeInt32Array:725`, `writeUint8Array:756`,
+  `writeUint16Array:809`, `writeUint32Array:982`. Float64 is the single hole in an otherwise
+  complete 8×8 matrix. The repo's own test is literally named `test("writeFloat64Array", ...)`
+  (`core/binary/BinaryBuffer.spec.js:4`) and then hand-rolls the write as a
+  `for (…) buffer.writeFloat64(expected[i])` loop (lines 7–10) because the method does not exist.
+  `engine/graphics/texture/sampler/serialization/TextureBinaryBufferSerializer.js:68` reads
+  `Float64Array` through the bulk reader; the write side of that same switch has no bulk
+  counterpart to call.
+- **Searched for**: `writeFloat64Array`, `readFloat64Array` across all of `src/` — three hits
+  total (reader, reader use, and the misnamed spec).
+
+### APIC-2 `Uint32Map` / `PairUint32Map` cannot be enumerated at all
+- **Severity**: MAJOR
+- **Package**: core/collection
+- **Test met**: B + C
+- **Absent symbol**: `Uint32Map.prototype.forEach` (and `keys()` / `values()` / `entries()` /
+  `[Symbol.iterator]`); same for `PairUint32Map`
+- **Evidence**: `core/collection/Uint32Map.js:57` documents itself as "Non-allocating
+  `Map<uint32, uint32>`" and implements `get:126`, `set:174`, `has:165`, `delete:249`,
+  `clear:315`, `get size:109` — the whole Map contract *except* iteration. There is no way to
+  read back what is stored without touching the `__data` typed array. Sibling
+  `core/collection/map/HashMap.js` provides `[Symbol.iterator]:840`, `entries():873`,
+  `values():883`, `keys():894`, `forEach:769`. `core/collection/PairUint32Map.js:56` has the
+  identical shape and the identical hole. A user who inserts into these maps and later needs to
+  walk them must reach into internals or keep a parallel key list.
+- **Searched for**: `forEach|Symbol.iterator|keys\(|values\(|entries\(` inside both files (0 hits).
+
+### APIC-3 `BiMap.delete`
+- **Severity**: MAJOR
+- **Package**: core/collection/map
+- **Test met**: A + C
+- **Absent symbol**: `BiMap.prototype.delete(key)` (also absent: `has`, `size`)
+- **Evidence**: `core/collection/map/BiMap.js` is 47 lines: `add:24`, `getKeyByValue:34`,
+  `getValueByKey:43`, plus `BiMap.prototype.get = …getValueByKey` and
+  `BiMap.prototype.set = …add` at lines 46–47 — i.e. it deliberately presents the standard `Map`
+  surface. Insert exists, remove does not, so a mapping can never be retired. The only workaround
+  is to drive the two public `forward` / `backward` `Map`s by hand, which additionally requires
+  knowing that `add(key, value)` stores `forward.set(value, key)` (the fields are populated
+  inverted relative to their names) — that is exactly "reach into internals".
+- **Searched for**: `delete|remove|unset|size|has` in `BiMap.js` (0 hits); `BiMap` across `src/`.
+
+### APIC-4 `CSRGraph` has an `arrayBuffer` getter and no way back
+- **Severity**: MAJOR
+- **Package**: core/graph/csr
+- **Test met**: A + D
+- **Absent symbol**: `CSRGraph.fromArrayBuffer(vertex_count, adjacency_length, buffer)`
+  (or a `set arrayBuffer(buffer)`)
+- **Evidence**: `core/graph/csr/CSRGraph.js:112` exposes `get arrayBuffer()` whose JSDoc
+  (lines 107–111) states it is "Useful for fast bulk operations and for **passing the graph
+  between Web Workers via transfer**". Nothing in the class or package can adopt such a buffer on
+  the receiving side: the only factory is `static fromArrays(...)` at line 310, which takes four
+  separate `ArrayLike`s and **copies** into a freshly allocated buffer. The documented
+  worker-transfer workflow therefore cannot be completed with the public API — the receiver must
+  recompute the four sub-array offsets by hand (`(vertex_count + 1)`, `adjacency_length * 2`,
+  `vertex_count`) and rebuild the views. The peer container `core/collection/table/RowFirstTable.js`
+  gets this right: `set array_buffer(buffer)` at line 109, documented "Useful for deserialization".
+- **Searched for**: `fromArrayBuffer|set arrayBuffer|array_buffer|adopt|wrap` in `CSRGraph.js`
+  and across `core/graph/`.
+
+### APIC-5 The indexed float heaps have no peek
+- **Severity**: MAJOR
+- **Package**: core/collection/heap
+- **Test met**: B
+- **Absent symbol**: `IndexedFloatMinHeap.prototype.peek_min` / `peek_score` / `get_score(id)`
+  (same on `IndexedFloatMaxHeap`: `peek_max` / `peek_score` / `get_score`)
+- **Evidence**: `core/collection/heap/IndexedFloatMinHeap.js` exposes `size:64`, `clear:72`,
+  `contains:82`, `insert:174`, `pop_min:192`, `update:219`, `remove:238` — you can only see the
+  top by destroying it. Every peer heap in the same package offers a non-destructive read:
+  `Uint32Heap.js` has `top_id:242`, `peek_score:258`, `peek_min:266`, `get_score:413`;
+  `Uint32Heap4.js` has the same four; `FibonacciHeap.js` has `peek_score:140`, `peek_min:151`,
+  `get_score:511`; `BinaryHeap.js` has `peek:190`. The class's own header (line 23) says
+  "Storage layout mirrors meep's `Uint32Heap`", so it is explicitly a peer of the class it
+  diverges from, and its stated use case (line 9: "shortest-path / A* distance frontiers,
+  deadline queues") is the canonical peek-the-frontier workload. Workaround is `pop_min()` +
+  re-`insert()` (mutates, O(log n), and loses tie order) or reading `__data_float32`.
+  `is_empty()` and `insert_or_update()` are missing from the same two classes for the same reason.
+- **Searched for**: `peek|top|min_score|get_score` in both IndexedFloat heap files (only a local
+  `const top_id` variable inside `pop_min`).
+
+### APIC-6 `ObservedInteger.process`
+- **Severity**: MAJOR
+- **Package**: core/model
+- **Test met**: B
+- **Absent symbol**: `ObservedInteger.prototype.process(f, thisArg)`
+- **Evidence**: `process` is this family's "invoke now, then on every change" binder — the
+  standard way to attach UI to an observable. It exists on `ObservedValue.js:80`,
+  `ObservedBoolean.js:127`, `ObservedString.js:110` and `ObservedEnum.js:127`, with identical
+  bodies (`this.onChanged.add(f, thisArg); f.call(thisArg, v, v); return this;`).
+  `core/model/ObservedInteger.js` — the most commonly bound member of the family, and the one
+  with `onChanged` declared at line 10 — does not have it. Beyond the boilerplate, this breaks
+  polymorphic binder code: any helper that accepts "an observed value" and calls `.process()`
+  throws on `ObservedInteger`. `.process(` is used 32 times across `src/`.
+- **Searched for**: `process` in `ObservedInteger.js` (0 hits, including the trailing
+  `prototype.` alias block at line 208).
+
+---
+
+### APIC-7 `Stack.size`
+- **Severity**: MINOR
+- **Package**: core/collection
+- **Test met**: B
+- **Absent symbol**: `Stack.prototype.size` (or `length`)
+- **Evidence**: `core/collection/Stack.js:7` offers `asArray:26`, `isEmpty:34`, `remove:43`,
+  `push:58`, `pop:71`, `peek:89`, `clear:96` — no element count. Every sibling container has one:
+  `queue/Deque.js:200 size()`, `set/ArraySet.js:28 get size()`, `map/HashMap.js:254 get size()`,
+  `set/HashSet.js:33 get size()`, `heap/BinaryHeap.js:260 size()`, `Uint32MinHeap.js:42 get size()`.
+  Workaround `stack.asArray().length` copies the whole backing array.
+- **Searched for**: `size|length|count|depth` in `Stack.js`.
+
+### APIC-8 `ArraySet.removeAll`
+- **Severity**: MINOR
+- **Package**: core/collection/set
+- **Test met**: A
+- **Absent symbol**: `ArraySet.prototype.removeAll(elements)`
+- **Evidence**: `core/collection/set/ArraySet.js` has `add:57`, `remove:74`, `addAll:120` and
+  `setFromArray:132`, but no bulk removal — the `addAll`/`removeAll` pair is broken in one
+  direction. (`clear:110` removes everything, which is not the same operation.) `List`, the
+  analogous observable container, has both `addAll:297` and `removeAll:388`
+  (`core/collection/list/List.js`).
+- **Searched for**: `removeAll|removeMany|deleteAll|subtract` in `ArraySet.js` and `core/collection/set/`.
+
+### APIC-9 `ArraySet[Symbol.iterator]` — further instances of the missing-iterator pattern
+- **Severity**: MINOR
+- **Package**: core/collection, core/binary
+- **Test met**: B + C
+- **Absent symbol**: `ArraySet.prototype[Symbol.iterator]` (same absence on `RingBuffer`,
+  `Uint32Map`, `PairUint32Map`, `BitSet`)
+- **Evidence**: this is the lead's `List` finding recurring elsewhere. `set/HashSet.js:70` and
+  `map/HashMap.js:840` and `queue/Deque.js:416` are generators, so `for…of` and spread work on
+  those; `set/ArraySet.js` (has `forEach:160`, `asArray:170`) and `RingBuffer.js` (has
+  `forEach:222`, `contains:245`) are visibly iterable collections where `for…of` throws.
+  `binary/BitSet.js` exposes `nextSetBit:264` so iteration is at least expressible; the four
+  container classes above have no such escape hatch beyond `asArray()`.
+- **Searched for**: `Symbol.iterator` across `core/collection/` and `core/binary/`.
+
+### APIC-10 `BitImage2` can set a bit but never clear one
+- **Severity**: MINOR
+- **Package**: core/binary
+- **Test met**: A + B
+- **Absent symbol**: `BitImage2.prototype.clear(x, y)`
+- **Evidence**: `core/binary/BitImage2.js` has `get(x, y):34` and `set(x, y):44`, and the only
+  way to unset anything is `reset():49`, which zeroes the entire image. The sibling bit container
+  `core/binary/BitSet.js` has the full pair — `set(bit_index, value):385` and
+  `clear(bit_index):424`, plus `setRange`/`clearRange` and `getAndSet`/`getAndClear`. A 2D
+  occupancy mask that cannot retract a placement is a one-way structure.
+- **Searched for**: `clear|unset|reset|toggle` in `BitImage2.js` (only `reset()` and a doc
+  mention of clearing `out`).
+
+### APIC-11 `BitSet.previousClearBit`
+- **Severity**: MINOR
+- **Package**: core/binary
+- **Test met**: A
+- **Absent symbol**: `BitSet.prototype.previousClearBit(from_index)`
+- **Evidence**: `core/binary/BitSet.js` implements three of the four scan directions —
+  `previousSetBit:220`, `nextSetBit:264`, `nextClearBit:324`. The class is modelled on
+  `java.util.BitSet` (same `cardinality`, `getAndSet`, `nextSetBit`, `previousSetBit` naming),
+  which defines all four. Backwards free-slot search (allocators scanning down) has to be
+  hand-written.
+- **Searched for**: `previousClearBit|prevClearBit|previous_clear` across `src/` (0 hits).
+
+### APIC-12 `Signal.send7`
+- **Severity**: MINOR
+- **Package**: core/events/signal
+- **Test met**: A/B
+- **Absent symbol**: `Signal.prototype.send7(a, b, c, d, e, f, g)`
+- **Evidence**: `core/events/signal/Signal.js` defines the monomorphic fast-dispatch ladder
+  `send0:378`, `send1:430`, `send2:481`, `send3:532`, `send4:584`, `send5:637`, `send6:691`,
+  `send8:747` — 7 is skipped, 8 is present. The class doc at line 325 says the generic
+  `dispatch(...args)` is "always" slower and directs users to the `sendN` forms, so a 7-argument
+  signal is pushed onto the documented slow path for no reason.
+- **Searched for**: `send7` across all of `src/` (0 hits).
+
+### APIC-13 `NumericInterval.intersect`
+- **Severity**: MINOR
+- **Package**: core/math/interval
+- **Test met**: A
+- **Absent symbol**: `NumericInterval.prototype.intersect(other)`
+- **Evidence**: `core/math/interval/NumericInterval.js:209` implements `union(other)` (mutating,
+  min/max), plus `overlaps:223` and `contains:234` — the predicates for intersection are there but
+  the operation is not. This is the mirror image of the lead's `compute_set_intersection` /
+  no-union finding, in the same repo. The free functions next to it don't cover it either:
+  `overlap1D.js` returns the overlap *magnitude*, `separation1D.js` the gap, `intersects1D.js` a
+  boolean — none produce the intersecting interval.
+- **Searched for**: `intersect` in `NumericInterval.js`; `interval_intersect|intersect1D|
+  intersection1D|clampToInterval` across `src/` (0 hits).
+
+### APIC-14 `string_strip_leading`
+- **Severity**: MINOR
+- **Package**: core/primitives/strings
+- **Test met**: A
+- **Absent symbol**: `string_strip_leading(string, leading_sequence)`
+- **Evidence**: `core/primitives/strings/string_strip_trailing.js:7` exists (repeatedly strips a
+  suffix sequence). The prefix half does not. The package is otherwise scrupulous about pairing —
+  `insert_before.js`/`insert_after.js`, `insert_before_or_replace.js`/`insert_after_or_replace.js`
+  are all present.
+- **Searched for**: `string_strip_leading|strip_leading|trimStart|strip_prefix` across `src/` (0 hits).
+
+### APIC-15 `de_interleave_3_bits`
+- **Severity**: MINOR
+- **Package**: core/binary
+- **Test met**: A + B
+- **Absent symbol**: `de_interleave_3_bits(interleaved)` (the compact-by-3 inverse of `split_by_3`)
+- **Evidence**: a concrete instance of the lead's "Morton encode without decode" pattern.
+  `core/binary/split_by_2.js` (spread bits 2 apart) *does* have its inverse next to it —
+  `core/binary/de_interleave_2_bits.js`. `core/binary/split_by_3.js` (spread bits 3 apart, the
+  3D Morton primitive) has none, so the 3D case is encode-only while the 2D case round-trips.
+- **Searched for**: `de_interleave_3|compact_by_3|compact_by_2|morton.*decode|unmorton|demorton`
+  across `src/` (0 hits).
+
+### APIC-16 `core/path` decomposes paths but cannot compose one
+- **Severity**: MINOR
+- **Package**: core/path
+- **Test met**: A
+- **Absent symbol**: `path_join(...parts)` (and its usual companion `path_normalize`)
+- **Evidence**: the package is a faithful subset of the standard path module —
+  `computePathBase.js` (basename), `computePathDirectory.js` (dirname),
+  `computeFileExtension.js` (extname), `computeFileName.js`, `PATH_SEPARATOR.js`,
+  `convertPathToURL.js`. Every function splits a path apart; none puts one back together, so
+  `dirname + child` (with duplicate-separator and `..`/`.` handling) is left to callers.
+  `convertPathToURL.js` already contains a private, ad-hoc version of that normalisation
+  (`replace(/\/+/g, '/')`, trailing-slash trimming) which is not exported.
+- **Searched for**: `path_join|joinPath|combinePath|concatPath|path_combine|path_normalize|
+  normalizePath` across `src/` (0 hits).
+
+### APIC-17 `rgb2uint32` has no inverse
+- **Severity**: MINOR
+- **Package**: core/color
+- **Test met**: A
+- **Absent symbol**: `uint32_to_rgba(value)` (and a float-domain `uint24_to_rgb`)
+- **Evidence**: `core/color/rgb2uint32.js:12` packs `(r, g, b, a)` given as 0..1 floats into a
+  32-bit RGBA word. Nothing unpacks it. The nearest thing, `core/color/int2rgb.js:6`, handles only
+  24-bit values (no alpha channel) and returns components as **0..255 integers**, whereas
+  `core/color/rgb2uint24.js:10` consumes **0..1 floats** — so `int2rgb(rgb2uint24(r, g, b))` does
+  not round-trip either. The rest of the colour package is rigorously paired
+  (`hex2rgb`/`rgb2hex`, `rgb_to_ycocg`/`ycocg_to_rgb`, `rgb_to_YCbCr_uint24`/`YCbCr_to_rgb_uint24`,
+  `kelvin_to_rgb`/`rgb_to_kelvin`, `rgb_to_rgbe9995`/`rgbe9995_to_rgb`, `toe`/`toe_inv`), which
+  makes this the outlier.
+- **Searched for**: `uint322rgb|uint32_to_rgb|uint242rgb|uint24_to_rgb|int2rgba` across `src/`
+  (0 hits).
+
+### APIC-18 `core/geom/vec2` has no arithmetic free functions
+- **Severity**: MINOR
+- **Package**: core/geom/vec2
+- **Test met**: B
+- **Absent symbol**: `v2_add`, `v2_subtract`, `v2_scale` (also `v2_normalize` for scalar args,
+  `v2_lerp`)
+- **Evidence**: the whole point of the `vN_*` free-function packages is component-wise math
+  without allocating a vector object. `core/geom/vec3/` provides `v3_add.js`, `v3_subtract.js`,
+  `v3_multiply.js`, `v3_multiply_scalar.js`, `v3_scale.js`, `v3_normalize_array.js`,
+  `v3_negate_array.js`, `v3_lerp` machinery and ~60 more. `core/geom/vec2/` contains only
+  `v2_angle_between`, `v2_array_normalize`, `v2_bearing_angle_towards`, `v2_cross_product`,
+  `v2_distance`, `v2_distance_sqr`, `v2_dot`, `v2_length`, `v2_length_sqr` and the two matrix3
+  multiplies — you can measure 2D vectors but not combine them. Falling back to `geom/Vector2.js`
+  (`add:369`, `sub:213`, `multiplyScalar:415`) means allocating the object the free functions
+  exist to avoid.
+- **Searched for**: `export function v2_(add|sub|scale|lerp)` and `v2_add|v2_subtract|v2_scale`
+  across `src/` (0 hits).
+
+---
+
+## Corrections to the lead's pre-findings
+
+- **`HashMap` DOES have `keys()`/`values()`/`entries()`** — `core/collection/map/HashMap.js:894`,
+  `:883`, `:873`, all generators delegating to `[Symbol.iterator]:840`. `HashSet.js:71` calls
+  `this.__map.keys()`, which would be broken otherwise. That item should be dropped.
+- Near-miss worth recording: `ObservedString` looks like it is missing `toJSON`/`fromJSON`
+  relative to its siblings, but they are installed as prototype aliases at
+  `core/model/ObservedString.js:171-172`. Not a gap.
+
+## Packages that came back clean
+
+`core/json` (resolvePath/resolvePathByArray/objectHasProperty/abstractJSONSerializer +
+abstractJSONDeserializer are a complete pair set), `core/parser/simple` (token readers, no
+inverse expected), `core/math/spline` (hermite↔bezier both ways, derivative/integral,
+bounds/subdivide/reverse), `core/math/random`, `core/color/operations`
+(darken/lighten, saturate/desaturate), `core/collection/table` (RowFirstTable +
+serialize/deserialize pair), `core/graph/v2/Graph` (add/remove/has for both nodes and edges),
+`core/binary` reinterpret/half-float/normalize families (all four/both directions present),
+`core/binary/float/SmallFloat`, `core/collection/CuckooFilter` (insert/remove/mightContain).

package/src/REVIEW_2026_08_06/api-engine.md

@@ -0,0 +1,195 @@
+# API-GAP analysis — `meep/src/engine`
+
+Scope: `H:/git/moh/app/src/mir-engine/meep/src/engine/`, `@woosh/meep-engine` v2.168.1.
+Question answered: *what would a competent game developer reach for and not find?*
+
+Packages examined and found **complete** against the inclusion bar (no reportable gap):
+`ecs/` (core: `EntityComponentDataset`, `EntityManager`, `Entity`, `System`, `EntityObserver`,
+`EntityBlueprint`, `parent/`, `transform/`, `attachment/`), `asset/` (`AssetManager`),
+`scene/` (`SceneManager`, `Scene`), `input/`, `graphics/` (`GraphicsEngine`, `Camera`,
+`MaterialManager`, `LayerCompositer`, decals, particles, path tracer), `sound/sopra/`,
+`animation/`, `physics/` apart from APIE-1, and the binary serialization stack
+(`ecs/storage/binary/`, adapters + upgraders, both directions present).
+
+Six items met the bar.
+
+---
+
+### APIE-1 `PhysicsSystem.setAngularVelocity`
+- **Severity**: MAJOR
+- **Package**: engine/physics
+- **Test met**: B (sibling inconsistency), C (category contract)
+- **Absent symbol / unreachable claim**: `PhysicsSystem.prototype.setAngularVelocity(rigidBody, v)`
+- **Evidence**: `engine/physics/ecs/PhysicsSystem.js:1047` defines
+  `setLinearVelocity(rigidBody, v)` whose contract is *"Replace the linear velocity. **Wakes the
+  body if asleep.**"* Every other state mutator on the system honours the same contract and calls
+  `__wake_body`: `applyImpulse` (`:908`), `applyImpulseAt` (`:930`), `applyTorque` (`:979`),
+  `applyForceAt` (`:1003`), `applyForce` (`:1033`), `setPose` (`:1075`). There is no angular
+  counterpart to `setLinearVelocity`. `RigidBody.angularVelocity`
+  (`engine/physics/ecs/RigidBody.js:47`) is a public `Vector3`, so the only route is a direct
+  write — which silently skips the wake. A sleeping body is held out of the active list by
+  `storage.mark_sleeping` (`PhysicsSystem.js:1165`) and is never integrated, so
+  `body.angularVelocity.set(...)` on a settled body does nothing until something else wakes it.
+  This is an ordinary task: spawning a spinning projectile, applying an authoritative network
+  state, or scripting a rotating platform. `applyTorque` is not a substitute — it accumulates a
+  torque, it does not set a velocity, and inverting it requires the caller to reimplement the
+  inverse-inertia transform.
+- **Searched for**: `setAngularVelocity`, `set_angular_velocity`, `setAngular`, `angularVelocity`
+  (whole `src/` tree, all files), `setSpin`, `setVelocity`. Only field reads/writes exist; no
+  method anywhere in `src/`.
+
+---
+
+### APIE-2 `Terrain.removeLayer`
+- **Severity**: MAJOR
+- **Package**: engine/ecs/terrain
+- **Test met**: A (broken pair), B (sibling inconsistency)
+- **Absent symbol / unreachable claim**: `Terrain.prototype.removeLayer(layer)`
+- **Evidence**: `engine/ecs/terrain/ecs/Terrain.js:672` `addLayer(layer)` is the public way to add
+  a splat layer, and it does four things the layer store cannot: grows the splat
+  (`this.splat.addWeightLayer()`), rebuilds the array texture (`layers.buildTexture()`), streams
+  the layer's texture data, and re-derives the `SPLAT_LAYER_COUNT` shader define via
+  `updateMaterial()` (`:613`, `:627`). No `removeLayer` exists on `Terrain`.
+  The two lower levels both have their removal half — `TerrainLayers.removeLayer(layer)`
+  (`engine/ecs/terrain/ecs/layers/TerrainLayers.js:302`) and
+  `SplatMapping.removeWeightLayer(index)`
+  (`engine/ecs/terrain/ecs/splat/SplatMapping.js:398`) — so the asymmetry is only at the public
+  component level. A user editing terrain at runtime must call both internals in the right order
+  and then re-run `buildTexture()` + `updateMaterial()` by hand, or the array texture depth and
+  the `SPLAT_LAYER_COUNT` define desynchronise from the layer list.
+- **Searched for**: `removeLayer`, `remove_layer`, `deleteLayer`, `dropLayer`, `eraseLayer`,
+  `removeWeightLayer` across all of `src/`.
+
+---
+
+### APIE-3 Navigation-mesh agent API
+- **Severity**: MAJOR
+- **Package**: engine/navigation
+- **Test met**: C (category contract), D (documented but absent)
+- **Absent symbol / unreachable claim**: any agent operation — `NavigationMeshAgent.setDestination`
+  / `.stop()` / `.update()` / a `NavigationMeshAgentSystem`. README: *"Pathfinding: A\* grid search
+  and a navigation mesh **with agents** and runtime obstacle carving."*
+- **Evidence**: `engine/navigation/mesh/NavigationMeshAgent.js` is the whole file — an eleven-line
+  class with a single `radius = 0` field and **zero methods**. It is imported by nothing:
+  `grep -rn "NavigationMeshAgent" src/` returns only its own declaration. `NavigationMesh`
+  (`engine/navigation/mesh/NavigationMesh.js:42`) exposes exactly `build({...})` (`:62`) and
+  `find_path(output, sx,sy,sz, gx,gy,gz)` (`:108`) — a stateless point-to-point query. The agent
+  radius that actually matters is a *build* parameter (`agent_radius` at `NavigationMesh.js:63`),
+  not the field on `NavigationMeshAgent`. `engine/navigation/ecs/` contains only
+  `Path`/`PathFollower`/`PathFollowingSystem`, which follow an already-authored spline — they have
+  no navmesh binding, no replanning and no avoidance. So a developer gets a path polyline and must
+  write the agent (destination state, replanning, steering, local avoidance, arrival) themselves.
+- **Searched for**: `NavigationMeshAgent`, `setDestination`, `set_destination`, `NavAgent`,
+  `AgentSystem`, `steering`, `avoidance`, `crowd`, `moveTo` across all of `src/`.
+
+---
+
+### APIE-4 Runtime navmesh obstacles
+- **Severity**: MAJOR
+- **Package**: engine/navigation
+- **Test met**: D (documented but absent)
+- **Absent symbol / unreachable claim**: `NavigationMesh.addObstacle` / `removeObstacle` /
+  `carve` / any incremental re-carve. README: *"a navigation mesh with agents and **runtime
+  obstacle carving**"*.
+- **Evidence**: all carving happens inside the one-shot build. `navmesh_build_topology.js:194`
+  (*"Carve obstacle footprints, pre-dilated by the agent radius"*) and
+  `build/clip_soup_against_overhangs.js` derive obstacles implicitly from downward-facing faces of
+  the *source geometry*; there is no obstacle list, no obstacle primitive and no parameter for one
+  in `NavigationMesh.build({source, agent_radius, agent_height, agent_max_step_height,
+  agent_max_step_distance, agent_max_climb_angle, up})` (`NavigationMesh.js:62-70`). The only way
+  to reflect a door closing or a crate dropping is to mutate the source `BinaryTopology` and call
+  `build()` again, which re-runs erosion, overhang clipping, sliver-fill, simplification and a full
+  BVH rebuild (`bt_mesh_build_face_bvh`, `NavigationMesh.js:83`) for the entire mesh. That is a
+  level-build operation, not the dynamic-obstacle facility the claim describes.
+- **Searched for**: `addObstacle`, `add_obstacle`, `removeObstacle`, `remove_obstacle`,
+  `NavMeshObstacle`, `carve`, `tile_cache`, `dtTileCache`, `obstacles` across all of `src/`.
+
+---
+
+### APIE-5 `engine/save` has no usable save-slot API
+- **Severity**: MAJOR
+- **Package**: engine/save
+- **Test met**: C (category contract), D (documented but absent), A (write without delete)
+- **Absent symbol / unreachable claim**: an importable save-game manager. `GameStateLoader` is the
+  package's only high-level entry point and it cannot be loaded from the published package.
+- **Evidence**: `engine/save/GameStateLoader.js:1` is
+  `import { GameSaveStateMetadata } from "../../../../view/game/save/GameSaveStateMetadata.js";`
+  — four levels up from `src/engine/save/` lands *outside* the `meep` package root, in the host
+  application's tree. `package.json` `files` ships `src/**`, so this module is published but its
+  import specifier resolves to nothing for any third-party consumer: the module throws on load.
+  Every method also delegates to a plugin that does not exist in the engine —
+  `engine.plugins.getById('game-save-state-manager')` at `:29`, `:76`, `:126`, `:151`;
+  `grep -rn "game-save-state-manager\|GameSaveStateManager" src/` matches only this file's own
+  call sites and JSDoc. Separately, even taken at face value the surface is one-sided: `save`
+  (`:19`), `load` (`:68`), `exists` (`:144`), `count` (`:119`) — there is **no delete** and no
+  slot enumeration, although the `Storage` backend it sits on has both
+  (`Storage.remove` at `engine/save/Storage.js:86`, `Storage.list` at `:68`). What remains usable
+  is the raw key/value `Storage` tier (`InMemoryStorage`, `IndexedDBStorage`) — a developer must
+  build the save-slot layer themselves.
+- **Searched for**: `GameSaveStateManager`, `GameSaveStateMetadata`, `game-save-state-manager`,
+  `SaveManager`, `SaveSlot`, `deleteSave`, `removeSave` across all of `src/`; also swept
+  `src/engine/` for other imports escaping the package root (only
+  `engine/animation/behavior/animateProperty.js:3` does the same, five levels up into
+  `model/game/story/...`).
+
+---
+
+### APIE-6 `SoundEngine.stop` / `suspendContext`
+- **Severity**: MINOR
+- **Package**: engine/sound
+- **Test met**: A (broken pair), B (sibling inconsistency)
+- **Absent symbol / unreachable claim**: `SoundEngine.prototype.stop()` /
+  `SoundEngine.prototype.suspendContext()`
+- **Evidence**: `engine/sound/SoundEngine.js` (126 lines, the whole class) has `start()` (`:113`)
+  and `resumeContext()` (`:103`) and neither counterpart. Its sibling subsystem
+  `GraphicsEngine` has both halves — `start()` at `engine/graphics/GraphicsEngine.js:491` and
+  `stop()` at `:642`. The consequence shows at the top level: `Engine.start()`
+  (`engine/Engine.js:569`) starts graphics and calls `this.sound.start()` (`:584`), but
+  `Engine.stop()` (`:635`) tears down the ticker, entity manager, plugins, GUI and asset manager
+  and leaves audio running, because there is nothing to call. Suspending audio on tab-blur or a
+  pause menu is an ordinary requirement; the workaround —
+  `engine.sound.context.suspend()` on the raw WebAudio object — is easy but steps outside the
+  engine's own abstraction, and there is no `close()` to release the AudioContext at all.
+- **Searched for**: `suspendContext`, `pauseContext`, `stopSound`, `stopAll`, `\.suspend\(`,
+  `context.close`, and `stop` within `engine/sound/` across all of `src/`.
+  (`SoundEmitter.stopAllTracks`/`fadeOutAllTracks` and `SopraEngine.stop(instance)` exist but are
+  per-emitter/per-instance, not engine-level.)
+
+---
+
+## README claims — reachable?
+
+| Claim | Verdict |
+|---|---|
+| "component queries are instantaneous / query, filter, and iterate over millions of entities" | **REACHABLE** — `EntityComponentDataset.traverseEntities(classes, visitor)` (`ecs/EntityComponentDataset.js:1309`) for ad-hoc queries, plus incremental reactive matching via `EntityObserver` + `addObserver` (`:290`), which is what `System.link`/`unlink` is built on (`EntityManager.js:562`). |
+| "The Hierarchy Problem: Solved" (scene-graph parent-child in pure ECS) | **REACHABLE** — `ParentEntity` + `TransformAttachment` components, driven by `ParentEntitySystem` and `TransformAttachmentSystem`; the child's `Transform` holds the composed world pose (`TransformAttachmentBinding.update`, `ecs/attachment/TransformAttachmentBinding.js:13`). Both directions are queryable: `ParentEntitySystem.findParentEntity/findChildrenOf/findRoot/isAncestorOf/traverse` (`ecs/parent/ParentEntitySystem.js:95-192`). `EntityNode` (`ecs/parent/EntityNode.js`) is the sugar layer with `parent`, `addChild`, `removeChild`, `children`, `root`, `traverse`. *(Note: `ecs/parent/ChildEntities.js` is declared and referenced by nothing — a dead leftover, not the mechanism.)* |
+| "Tiered API Access: high-level abstraction AND low-level raw typed arrays" | **REACHABLE, with a caveat.** The typed-array tier is real where it is claimed to matter — physics runs an SoA body pool, `Transform.matrix` is a `Float32Array`, geometry/BVH/topology are typed-array backed, and query APIs are `(result, result_offset, …)`-first. But the **ECS component store itself is not typed arrays**: `EntityComponentDataset.components` is `Object[][]` and marked `@private` (`ecs/EntityComponentDataset.js:188`). The ECS low-level tier is index-based, not array-based (`computeComponentTypeIndex`, `getComponentByIndex`, `addComponentToEntityByIndex`, `traverseComponentsByIndex`). No absent symbol; the phrasing overstates the ECS half. |
+| clustered forward+ with "unlimited lighting" | **REACHABLE** — `graphics/render/forward_plus/LightManager.js` + `plugin/`, driven by the ECS light components in `graphics/ecs/light/`. No hard light-count constant in the binning path; the light set is a cluster texture sized at runtime (`__build_cluster_texture`, `LightManager.js:418`). |
+| "1,000,000+ GPU-driven decals" | **REACHABLE** — `Decal` component (`graphics/ecs/decal/v2/Decal.js`) + `FPDecalSystem` (`.../FPDecalSystem.js`, BVH-indexed with `queryOverlapFrustum` at `:306` and `raycast` at `:377`), consumed by `FP_SHADER_CHUNK_APPLY_DECALS`. No cap constant found. |
+| terrain with "up to 256 layers" | **REACHABLE** — `Terrain.addLayer` (`ecs/terrain/ecs/Terrain.js:672`) → `TerrainLayers` array texture + `SplatMapping`; layer count is dynamic (`SPLAT_LAYER_COUNT` define, `Terrain.js:627`) with no cap constant in code. *(Removal is the gap — see APIE-2.)* |
+| a path tracer | **REACHABLE** — `graphics/sh3/path_tracer/` : `PathTracer`, `PathTracedRenderer`, `PathTracedScene`, `populate_path_traced_scene_from_ecd.js`, over `BufferedGeometryBVH`. |
+| deterministic rigid-body physics with CCD | **REACHABLE** — `physics/ecs/PhysicsSystem.js` (sequential impulse, warm start, island sleep/wake, `determinism.spec.js` as the standing gate). CCD is per-body opt-in and publicly switchable: `RigidBodyFlags.CCD` (`physics/ecs/RigidBodyFlags.js`) via `RigidBody.setFlag`, implemented in `physics/ccd/linear_sweep.js`. |
+| raycast vehicle | **REACHABLE** — `physics/vehicle/RaycastVehicle.js`: `addWheel`, `setSteering`, `setDriveForce`, `setBrake`, `update`. *(No `removeWheel`, but wheels are a construction-time set — below the bar.)* |
+| kinematic first-person character controller with stair/ramp handling | **REACHABLE** — `engine/control/first-person/`: `FirstPersonPlayerController` + `FirstPersonPlayerControllerSystem` + `collision/KinematicMover.js` (`stepHeight`, stair/ramp cases covered by `Stairs.spec.js`, `GymGrayBoxStop.spec.js`), plus an ability set (mantle, ledge grab, slide, wall-run). |
+| Inverse Kinematics: FABRIK + analytic two-joint | **REACHABLE** — `physics/inverse_kinematics/fabrik/fabrik_solve.js`, `fabrik3d_solve_primitive.js`, `two_joint_ik.js`. |
+| Fluids: MAC-grid Eulerian + MLS-MPM | **REACHABLE** — `physics/fluid/` (`FluidField`, `FluidSimulator`, `solver/`, `ecs/`, `effector/`) and `physics/mls-mpm/MLS_MPM.js`. |
+| navigation: A\* grid search | **REACHABLE** — `navigation/grid/find_path_on_grid_astar.js`. |
+| navigation: navmesh **with agents** | **NOT REACHABLE** — see APIE-3. `NavigationMeshAgent` is an empty stub; only stateless `NavigationMesh.find_path` exists. |
+| navigation: **runtime obstacle carving** | **NOT REACHABLE** — see APIE-4. Carving is build-time only; no obstacle add/remove and no incremental rebuild. |
+| Input: unified Touch / Mouse / Keyboard / **Gamepad**, event-driven AND query-based | **REACHABLE, both tiers.** Devices: `PointerDevice`, `KeyboardDevice`, `touch/TouchDevice`, `GamepadDevice` (full: hot-plug, stuck-input release, `main` stable handle, learned stick calibration, standard mapping). Event-driven = the `on.*` Signals; query-based = `pad.buttons[i].is_down`, `keys.w.is_down`, `pad.stickLeft.value`. Bindable declaratively through `input/ecs/ism/InputBinding` + `InputSystem` path resolution (e.g. `"gamepad/main/buttons/0/down"`). |
+| Sound: events, mixer bus tree, RTPC, voice stealing, snapshots, ducking, serializable | **REACHABLE** — `sound/sopra/SopraEngine.js`: `setBuses`/`defaultBuses`, `playEvent`/`playOneShot`/`createInstance`/`stop`/`crossfade`, `defineParameter`/`setParameter`/`bindParameter`/`bindParameterToBusVolume`, `captureSnapshot`/`applySnapshot`, `addDucker`/`clearDuckers`, `setListener`; instances expose `seek`, `restart`, `fadeOutAndStop`, `stop`. Definitions live in `sound/sopra/definition/` with binary adapters. |
+| Sound: opt-in acoustic simulation (occlusion, transmission, pathing, baked reverb probes) | **REACHABLE** — `sound/simulation/`: `AcousticSimulator`, `configureAcousticSimulation.js`, `probe/`, `render/`, `ecs/`. |
+| Assets: web-first streaming, engine runs before assets load | **REACHABLE** — `asset/AssetManager.js`: `promise`/`get` with `progress` + scopes, `insertAsync`, `isPending`/`isLoaded`/`isFailed`, `remove`, `clear`, `registerLoader`/`unregisterLoader`, `registerTransformer`/`unregisterTransformer`, `startup`/`shutdown` with drain + abort. Symmetric throughout. |
+| Serialization: binary with version upgrading | **REACHABLE** — `ecs/storage/BinaryBufferSerializer.js` / `BinaryBufferDeSerializer.js`, `ecs/storage/binary/BinarySerializationRegistry.js` (`registerAdapter`/`removeAdapter`, `registerUpgrader`, `getUpgradersChain`) and `executeBinaryClassUpgraderChain.js`. |
+
+---
+
+## Incidental (not an API gap, noted in passing)
+
+`ecs/Entity.js:256` — `Entity.getComponentSafe` builds its error message with
+`computeComponentClassName(klass)`, which is **not imported** in that file (imports are `assert`,
+`Signal`, `EntityFlags`, `EntityReference`, `EventType`). The miss path throws
+`ReferenceError: computeComponentClassName is not defined` instead of the intended
+"Component of given class 'X' not found". The function exists at
+`ecs/computeComponentClassName.js`; this is a one-line missing import, i.e. a defect rather than
+a gap, so it is excluded from the numbered list.