@woosh/meep-engine 3.0.2 → 3.2.0

package/src/REVIEW_2026_08_06/api-engine.md

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