@woosh/meep-engine 3.1.0 → 3.2.0

package/src/REVIEW_2026_08_06/api-core.md

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