@woosh/meep-engine 2.165.6 → 2.166.0

package/src/CORRECTNESS_HUNT_2026_07_24.md

@@ -0,0 +1,142 @@
+# Engine correctness bug hunt — 2026-07-24
+
+A targeted correctness sweep of the `meep` engine (`app/src/mir-engine/meep/src/`).
+Targets chosen from **architecture** (foundational / wide-blast-radius code) and **git commit
+history** (recently-landed, thinly-reviewed code). Method: multi-agent finder → adversarial
+verifier; every confirmed defect is pinned with a *failing* test before it is fixed.
+
+## Ground rules
+
+- **Fix only what is provably wrong**, and only after a red test reproduces it. Everything
+  uncertain is written up here rather than "fixed".
+- Black-box tests only — assert on observable behaviour, never on call counts / private paths.
+- No defensive guards for can't-happen conditions; no silent `try/catch`; correctness over bandaids.
+- `assert.*` is stripped in prod — do not test assert-rejections; real `throw` is testable.
+- Keep performance characteristics intact — a correctness fix must not regress the hot path.
+- Tests run from `H:/git/moh` via `node_modules/.bin/jest --config jest.conf.json <pattern>`.
+
+## What is already covered (do not re-litigate)
+
+Per prior review memory, these were swept recently and validated clean or fixed:
+- **Physics core** + reactive (14-bug sweep, 2026-07) — determinism gate green.
+- **Sound / acoustic** simulator + render (Sopra / Steam-Audio-gap work).
+- **Network** core (GNS review) — P0s catalogued separately.
+- **engine review 2026-07-03** — physics/sound/network CLEAN; defects concentrated in
+  ECS lifecycle + graphics bindings + serialization.
+- BVH2/8, clustered-lighting froxel geometry, path tracer, LPG stage correctness, EPA/GJK,
+  fluid MAC, navmesh simplify — each has a standing spec gate.
+
+The hunt therefore targets **the delta since those reviews** and **areas with thin spec coverage**.
+
+## Target map
+
+Tier 1 — recently landed (git history hot spots):
+- Gamepad input subsystem (`engine/input/devices/gamepad/*`, `GamepadDevice.js`)
+- Fog-of-war screen-space shader (`engine/ecs/fow/shader/*`)
+- Trail3D + tube geometry (`engine/graphics/ecs/trail3d/*`, `engine/graphics/trail/tube/*`)
+- Forward+ clustered light live updates (`engine/graphics/ecs/light/*`)
+- HUD edge-stick badge placement (`engine/ecs/gui/hud/*`)
+- Physics delta of the 14-bug sweep (adversarial check of changed files only)
+
+Tier 2 — foundational, wide blast radius (architecture):
+- `core/math/linalg`, `core/math/spline`, `core/math/statistics|random|noise`
+- `core/geom` transforms & primitives (Vector*, Quaternion, AABB, Matrix)
+- `core/collection` data structures
+
+Tier 3 — thin spec coverage:
+- `engine/animation` (16 specs / 83 src) — clip/curve binding, skinning
+- `engine/intelligence` (26 / 71) — behavior trees, blackboard, MCTS
+- `engine/navigation` (14 / 20) — pathfinding, path following
+- `engine/interpolation` (5 / 8) — interp snap was a deferred item
+- `engine/ecs` lifecycle (defects concentrate here per memory)
+- `engine/asset` loaders + serialization
+
+## Hand-verified clean (independent of the agent sweep)
+
+These were read and checked directly (some with a throwaway empirical harness); no defect found:
+
+- **Gamepad stick calibration** (`GamepadStickCalibrator`, `GamepadStick`, `GamepadStickCalibration`,
+  `apply_radial_dead_zone`, `gamepad_write_dpad_vector`) — robust median/MAD learning, self-correcting
+  accepted-magnitude gate, continuous radial dead zone, correct D-pad vector. 22 passing tests.
+- **Tube parallel-transport frame** (`tube_frame_transport` + `v3_orthonormal_matrix_from_normal`) — the
+  degenerate bootstrap correctly takes the perpendicular rows (util stores the input at rows 6..8), so N⊥T.
+- **Quaternion slerp** (`slerpQuaternions`) — correct shortest-path sign flip + lerp fallback near-parallel.
+- **Cubic animation curve** (`spline3_hermite`, `evaluate_two_key_curve`, `AnimationCurve.getKeyIndexLow`) —
+  canonical Hermite basis; tangents scaled by segment dt; binary search boundaries correct.
+- **core/color** — empirical 200k-sample round-trip harness: YCoCg exact, YCbCr ≤1 LSB, HSV ~1e-16,
+  OkLab ~1e-7, RGBE9995 matches the standard RGB9E5 algorithm exactly (the large minor-channel relative
+  error is inherent shared-exponent quantization, not a bug). No defect.
+
+## Findings
+
+The 23-area finder→adversarial-verifier sweep produced 26 candidate findings; 7 were rejected on
+verification, **18 confirmed** (real bug · reachable · node-testable), and **1 uncertain** (real logic
+defect but effectively unreachable on the shipped path — see below). Each confirmed item below was
+re-checked against source and pinned with a *failing* test before fixing.
+
+### Confirmed & fixed (test-first)
+
+| # | Severity | Area | File | Bug | Status |
+|---|----------|------|------|-----|--------|
+| 1 | high | statistics | `core/math/statistics/gaussian_amplitude.js` | Squared the variance in the exponent (passed `variance` to `gaussian()`, which squares its arg) → PDF ~45% off for any variance≠1 | ✅ fixed |
+| 2 | med | statistics | `core/math/statistics/computeStatisticalMean.js` | Loop started at `0` not `start`, but divided by `end-start` → wrong mean for any non-zero start | ✅ fixed |
+| 3 | med | linalg | `core/geom/Quaternion.js` (×3: XYZ/YXZ/ZYX) | `Math.asin` unclamped → **NaN at gimbal lock** (fp overshoot past 1). Hits `copy_transform_to_threejs_object` + first-person yaw seed | ✅ fixed |
+| 4 | med | geom | `core/geom/ConicRay.js` | `sampleRandomDirection` NaN for a cone axis of exactly `(0,0,-1)` (k=1/(1+dZ) singular at the antipode) | ✅ fixed |
+| 5 | low | geom | `core/geom/2d/line/line2_compute_segment_point_distance_sqr.js` | Zero-length segment → `clamp01(0/0)=NaN` (3D twin already guards this) | ✅ fixed |
+| 6 | med | collection | `core/collection/RingBuffer.js` `getHead()` | Returns `undefined` when head wraps to slot 0 on a full buffer (no wrap, unlike `getFromHead`) | ✅ fixed |
+| 7 | med | collection | `core/collection/RingBuffer.js` `contains()` | Scans whole backing array → reports `true` for `shift()`-ed-out elements | ✅ fixed |
+| 8 | low | binary | `engine/ecs/storage/binary/collection/BinaryCollectionDeSerializer.js` | Signed `>>2` corrupts a 32-bit dict back-ref offset ≥2²⁹ (should be `>>>2`) | ✅ fixed |
+| 9 | low | binary | `core/binary/EncodingBinaryBuffer.js` | Signed `>>1` corrupts interned-string back-ref ≥2³⁰ (should be `>>>1`) | ✅ fixed |
+| 10 | low | binary | `core/binary/BinaryBuffer.js` `writeASCIIString` | Boundary `> 0x80` lets non-ASCII U+0080 pass validation (should be `> 0x7F`) | ✅ fixed |
+| 11 | high | ecs | `engine/ecs/EntityComponentDataset.js` `traverseEntities` | Uses **module-shared scratch arrays** → nested traversal corrupts the outer loop (wrong-type component delivered) | ✅ fixed |
+| 12 | high | navigation | `engine/navigation/ecs/path_following/PathFollowingSystem.js` | `next_offset > path_length` (should be `>=`) → non-looping follower snaps to start & never finishes when a step lands exactly on the end | ✅ fixed |
+| 13 | med | navigation | `engine/navigation/ecs/components/Path.js` | `sample_linear`/`sample_catmull_rom` return `(t<0 && …)` — always false for valid offsets → `estimatePathViaIterativeIntegral` returns 0 | ✅ fixed |
+| 14 | med | input | `engine/input/ecs/systems/InputControllerSystem.js` | `link()/unlink()` ignore `enabled` → binding double-registration → double input dispatch after a disable/enable round-trip | ✅ fixed |
+| 15 | med | graphics | `engine/graphics/trail/tube/TubeX.js` | `rotate()` writes recycled segment with reversed winding → lit tubes shaded from the wrong side | ✅ fixed |
+| 16 | med | graphics | `engine/graphics/render/forward_plus/LightManager.js` | Reused sorted-lights array never shrinks → stale light records re-uploaded to the light-data texture every frame | ✅ fixed |
+| 17 | med | animation | `engine/animation/clip/ecd_bind_animation_curve.js` (fix) | LINEAR quaternion tracks nlerp'd component-wise with no hemisphere alignment → long-way rotation on `dot<0` key pairs | ✅ fixed |
+| 18 | low | fow | `engine/ecs/fow/FogOfWar.js` `conceal()` | No dedup guard (unlike `reveal()`) → conflicting fade rows on one cell | 📝 documented (see below) |
+
+19 confirmed defects were addressed test-first (18 from the sweep + the one below that the verifier
+had flagged as "uncertain"). Each fix landed in its subsystem commit with a red-before-green test.
+`#3` clamps all three Euler extractors; `#11` also removes the now-dead scratch pools; `#13` fixes both
+`Path.sample` and its consumer `estimatePathViaIterativeIntegral`.
+
+### Also fixed (verifier had marked "uncertain")
+
+- **`engine/animation/keyed2/AnimationTrackPlayback.js` — `on.ended` never fired when a frame landed
+  exactly on `timeEnd`.** Genuine logic defect: the strict `> __nextKeyTime` guard skips the exact-landing
+  frame, and the next frame fails the `position < timeEnd` guard, so the one-shot `ended` never dispatched.
+  Fixed by adding `|| newPosition >= timeEnd` to the outer guard (mid-track exact landings never reach
+  `timeEnd`, so they are unaffected; fire-once preserved). **Reachability caveat, recorded for the owner:**
+  the only in-engine driver (`ScriptSystem`, variable-rate float time) makes an exact landing a measure-zero
+  event, so this hardens the public primitive rather than fixing an observed in-game leak.
+
+### Not auto-fixed — owner decision required
+
+- **`#18` `FogOfWar.conceal()` missing dedup.** `reveal()` is idempotent (it guards on `samplerData === 255`
+  and immediately moves the cell off that state). `conceal()` guards only `value !== 255` and does **not**
+  move the cell, so a second `conceal` — or a `conceal` while the cell is mid-`reveal` — stacks a second,
+  opposing fade row on the same cell; the two rows then fight and the final visibility is decided by fade
+  timing, not by the last command (plus a one-frame flicker). **Why deferred:** (1) no in-engine caller uses
+  `conceal()` (`FogOfWarRevealerSystem` only reveals), so it is public-API-only, LOW severity; (2) the
+  *correct* conflict semantics are a design choice (should `conceal` cancel an in-progress `reveal`, or be
+  ignored?); and (3) an efficient "one fade row per cell" guard needs a cell→row index that `RowFirstTable`
+  does not provide — a naive per-cell scan of `fadeMask` is `O(rows·cells)` and could be costly for large
+  concealed regions. **Recommended fix:** enforce "at most one fade row per cell, latest command wins" by
+  updating an existing row's `speed`/target in place instead of adding, backed by a cell→row map.
+
+### Follow-up noted (not a regression)
+
+- **`#17` CubicTangents quaternion tracks.** The hemisphere-alignment fix covers LINEAR tracks (glTF's
+  default). GLTF cubic-spline (`CubicTangents`) quaternion tracks pack in/out tangents per key and would need
+  those tangents negated alongside the value; left as a follow-up.
+
+### Pre-existing failures (NOT caused by this sweep)
+
+- `engine/control/first-person/WallRunScenarios.spec.js` has 4 failing "unhappy path" tests. Confirmed
+  pre-existing by re-running the suite against the original `Quaternion.js` (identical 4 failures). The
+  commit that added them ("WallRun scenarios + 3 gaps they surfaced") marks them as gap-documenting tests
+  for unimplemented behaviour. Out of scope here.
+
+Full suite after the sweep: **8846 passed, 4 failed (the pre-existing WallRun gaps), 118 skipped.**

package/src/core/binary/BinaryBuffer.js

@@ -1238,7 +1238,7 @@ export class BinaryBuffer {
         for (let i = 0; i < char_count; i++) {
             const char_code = string.charCodeAt(i);
 
-            if (char_code > 0x80) {
+            if (char_code > 0x7F) {
                 throw new Error(`Character ${String.fromCharCode(char_code)} can\'t be represented by a US-ASCII byte.`);
             }
 

package/src/core/binary/EncodingBinaryBuffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EncodingBinaryBuffer.d.ts","sourceRoot":"","sources":["../../../../src/core/binary/EncodingBinaryBuffer.js"],"names":[],"mappings":"AAGA;IAEI,8BAA2B;IAG3B,kCAeC;IAED,sBA+BC;CACJ;6BAxD4B,mBAAmB;sBAD1B,4BAA4B"}
+{"version":3,"file":"EncodingBinaryBuffer.d.ts","sourceRoot":"","sources":["../../../../src/core/binary/EncodingBinaryBuffer.js"],"names":[],"mappings":"AAGA;IAEI,8BAA2B;IAG3B,kCAeC;IAED,sBAiCC;CACJ;6BA1D4B,mBAAmB;sBAD1B,4BAA4B"}

package/src/core/binary/EncodingBinaryBuffer.js

@@ -34,7 +34,9 @@ export class EncodingBinaryBuffer extends BinaryBuffer {
 
             const header = this.readUint32LE();
 
-            const address = header >> 1;
+            // unsigned: for a first-write address >= 2^30 the header sets bit 31, and a signed shift
+            // would sign-extend it into a negative (wrong) address
+            const address = header >>> 1;
 
             let value = this.__dictionary.getValueByKey(address);
 

package/src/core/binary/data_view/DataType2DataViewReaders.d.ts

@@ -1,14 +1,10 @@
 export type DataType2DataViewReaders = string;
-export namespace DataType2DataViewReaders {
-    let uint8: string;
-    let uint16: string;
-    let uint32: string;
-    let uint64: string;
-    let int8: string;
-    let int16: string;
-    let int32: string;
-    let int64: string;
-    let float32: string;
-    let float64: string;
-}
+/**
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView
+ * @readonly
+ * @enum {string}
+ */
+export const DataType2DataViewReaders: {
+    [x: string]: string;
+};
 //# sourceMappingURL=DataType2DataViewReaders.d.ts.map

package/src/core/binary/data_view/DataType2DataViewReaders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DataType2DataViewReaders.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/data_view/DataType2DataViewReaders.js"],"names":[],"mappings":"uCAKU,MAAM"}
+{"version":3,"file":"DataType2DataViewReaders.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/data_view/DataType2DataViewReaders.js"],"names":[],"mappings":"uCAKU,MAAM;AAHhB;;;;GAIG;AACH;;EAaE"}

package/src/core/binary/data_view/DataType2DataViewWriters.d.ts

@@ -1,14 +1,10 @@
 export type DataType2DataViewWriters = string;
-export namespace DataType2DataViewWriters {
-    let uint8: string;
-    let uint16: string;
-    let uint32: string;
-    let uint64: string;
-    let int8: string;
-    let int16: string;
-    let int32: string;
-    let int64: string;
-    let float32: string;
-    let float64: string;
-}
+/**
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView
+ * @readonly
+ * @enum {string}
+ */
+export const DataType2DataViewWriters: {
+    [x: string]: string;
+};
 //# sourceMappingURL=DataType2DataViewWriters.d.ts.map

package/src/core/binary/data_view/DataType2DataViewWriters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DataType2DataViewWriters.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/data_view/DataType2DataViewWriters.js"],"names":[],"mappings":"uCAKU,MAAM"}
+{"version":3,"file":"DataType2DataViewWriters.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/data_view/DataType2DataViewWriters.js"],"names":[],"mappings":"uCAKU,MAAM;AAHhB;;;;GAIG;AACH;;EAaE"}

package/src/core/binary/data_view/DataViewStructAccessor.d.ts

@@ -1,18 +1,39 @@
-import {BinaryDataType} from "../type/BinaryDataType";
-
-interface IBinarySchema {
-    [k: string]: BinaryDataType
-}
-
-export class DataViewStructAccessor<T extends IBinarySchema> {
-
-    constructor(type: T, little_endian?: boolean)
-
-    readonly $record_byte_size: number
-
-    bind(view: DataView, offset: number): void
-
-    bind_by_index(view: DataView, index: number): void
-
-    readonly record: { [prop in keyof T]: number }
-}
+export class DataViewStructAccessor {
+    /**
+     *
+     * @param {Object<BinaryDataType>} schema
+     * @param {boolean} [little_endian]
+     */
+    constructor(schema: any, little_endian?: boolean);
+    /**
+     * @type {DataView}
+     */
+    $data: DataView;
+    /**
+     * @type {number}
+     */
+    $offset: number;
+    /**
+     * @readonly
+     * @type {number}
+     */
+    readonly $record_byte_size: number;
+    /**
+     * Mainly here for TS interface's type inference
+     * @return {DataViewStructAccessor}
+     */
+    get record(): DataViewStructAccessor;
+    /**
+     *
+     * @param {DataView} data_view
+     * @param {number} byte_offset
+     */
+    bind(data_view: DataView, byte_offset: number): void;
+    /**
+     *
+     * @param {DataView} data_view
+     * @param {number} index
+     */
+    bind_by_index(data_view: DataView, index: number): void;
+}
+//# sourceMappingURL=DataViewStructAccessor.d.ts.map

package/src/core/binary/type/BinaryDataType.d.ts

@@ -1,15 +1,15 @@
-export enum BinaryDataType {
-    Uint8= "uint8",
-    Uint16= "uint16",
-    Uint32= "uint32",
-    Uint64= "uint64",
-
-    Int8= "int8",
-    Int16= "int16",
-    Int32= "int32",
-    Int64= "int64",
-
-    Float16= 'float16',
-    Float32= "float32",
-    Float64= "float64"
-}
+export type BinaryDataType = string;
+export namespace BinaryDataType {
+    let Uint8: string;
+    let Uint16: string;
+    let Uint32: string;
+    let Uint64: string;
+    let Int8: string;
+    let Int16: string;
+    let Int32: string;
+    let Int64: string;
+    let Float16: string;
+    let Float32: string;
+    let Float64: string;
+}
+//# sourceMappingURL=BinaryDataType.d.ts.map

package/src/core/binary/type/DataType2TypedArrayConstructorMapping.d.ts

@@ -8,16 +8,12 @@ export function compute_typed_array_constructor_from_data_type(dt: BinaryDataTyp
  * Mapping from {@link DataType } to TypedArray constructors
  */
 export type DataType2TypedArrayConstructorMapping = Function;
-export namespace DataType2TypedArrayConstructorMapping {
-    let uint8: Uint8ArrayConstructor;
-    let uint16: Uint16ArrayConstructor;
-    let uint32: Uint32ArrayConstructor;
-    let int8: Int8ArrayConstructor;
-    let int16: Int16ArrayConstructor;
-    let int32: Int32ArrayConstructor;
-    let float16: any;
-    let float32: Float32ArrayConstructor;
-    let float64: Float64ArrayConstructor;
-}
+/**
+ * Mapping from {@link DataType} to TypedArray constructors
+ * @enum {function}
+ */
+export const DataType2TypedArrayConstructorMapping: {
+    [x: string]: any;
+};
 import { BinaryDataType } from "./BinaryDataType.js";
 //# sourceMappingURL=DataType2TypedArrayConstructorMapping.d.ts.map

package/src/core/binary/type/DataType2TypedArrayConstructorMapping.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DataType2TypedArrayConstructorMapping.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/type/DataType2TypedArrayConstructorMapping.js"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,mEAHW,cAAc,GACZ,sBAAoB,CAUhC;;;;;;;;;;;;;;;;+BAhC8B,qBAAqB"}
+{"version":3,"file":"DataType2TypedArrayConstructorMapping.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/type/DataType2TypedArrayConstructorMapping.js"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,mEAHW,cAAc,GACZ,sBAAoB,CAUhC;;;;;AA7BD;;;GAGG;AACH;;EAUE;+BAjB6B,qBAAqB"}

package/src/core/binary/type/DataTypeByteSizes.d.ts

@@ -5,18 +5,12 @@
  */
 export function dataTypeByteSize(type: BinaryDataType): number;
 export type DataTypeByteSizes = number;
-export namespace DataTypeByteSizes {
-    let uint8: number;
-    let uint16: number;
-    let uint32: number;
-    let uint64: number;
-    let int8: number;
-    let int16: number;
-    let int32: number;
-    let int64: number;
-    let float16: number;
-    let float32: number;
-    let float64: number;
-}
+/**
+ * @readonly
+ * @enum {number}
+ */
+export const DataTypeByteSizes: {
+    [x: string]: number;
+};
 import { BinaryDataType } from "./BinaryDataType.js";
 //# sourceMappingURL=DataTypeByteSizes.d.ts.map

package/src/core/binary/type/DataTypeByteSizes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DataTypeByteSizes.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/type/DataTypeByteSizes.js"],"names":[],"mappings":"AAuBA;;;;GAIG;AACH,uCAHW,cAAc,GACb,MAAM,CAUjB;gCAhCS,MAAM;;;;;;;;;;;;;;+BAJe,qBAAqB"}
+{"version":3,"file":"DataTypeByteSizes.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/type/DataTypeByteSizes.js"],"names":[],"mappings":"AAuBA;;;;GAIG;AACH,uCAHW,cAAc,GACb,MAAM,CAUjB;gCAhCS,MAAM;AAFhB;;;GAGG;AACH;;EAcE;+BApB6B,qBAAqB"}

package/src/core/binary/type/DataTypeIndices.d.ts

@@ -3,15 +3,12 @@
  * Provides stable indices, mainly useful for serialization where other data is subject to change
  */
 export type DataTypeIndices = number;
-export namespace DataTypeIndices {
-    let uint8: number;
-    let uint16: number;
-    let uint32: number;
-    let int8: number;
-    let int16: number;
-    let int32: number;
-    let float32: number;
-    let float64: number;
-    let float16: number;
-}
+/***
+ * Provides stable indices, mainly useful for serialization where other data is subject to change
+ * @readonly
+ * @enum {number}
+ */
+export const DataTypeIndices: {
+    [x: string]: number;
+};
 //# sourceMappingURL=DataTypeIndices.d.ts.map

package/src/core/binary/type/DataTypeIndices.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DataTypeIndices.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/type/DataTypeIndices.js"],"names":[],"mappings":";;;;8BAKU,MAAM"}
+{"version":3,"file":"DataTypeIndices.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/type/DataTypeIndices.js"],"names":[],"mappings":";;;;8BAKU,MAAM;AAHhB;;;;GAIG;AACH;;EAUE"}