@woosh/meep-engine 3.1.0 → 3.3.0

package/src/REVIEW_2026_08_06/core-collection.md

@@ -1,376 +1,376 @@
-# Correctness review — `core/collection`, `core/cache`, `core/events`, `core/fsm`, `core/function`, `core/IdPool.js`
-
-Scope: every non-spec source file under the listed directories. Every finding below was reproduced
-by executing the real modules through the project's jest harness (`npx jest --config jest.conf.json`
-from `H:/git/moh`, with a throwaway spec under `app/src/`, since removed). Observed values quoted in
-the failure scenarios are actual program output, not derivations.
-
----
-
-## CRITICAL
-
-### COLL-1 `SortedListProjection` inserts at the wrong index — output is never sorted
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/list/SortedListProjection.js:47-51`
-- **Defect**: `binarySearchLowIndex` returns *the index of the largest element `<= el`* (or `-1` when
-  `el` precedes everything). `handleAddition` passes that value straight to `List.insert`, so the
-  element is placed **before** its predecessor instead of after it. The `-1` case is worse: it reaches
-  `List.insert(-1, el)`, whose `else` branch runs `this.data.splice(-1, 0, el)` — a negative splice
-  index that inserts before the *last* element — and then dispatches `on.added` with index `-1`.
-- **Failure scenario**:
-  ```js
-  const input = new List();
-  const p = new SortedListProjection(input, (a, b) => a - b);
-  p.link();
-  input.add(3); input.add(5); input.add(7); input.add(4); input.add(1);
-  ```
-  `p.output.asArray()` → `[5, 7, 4, 1, 3]` (measured). Expected `[1, 3, 4, 5, 7]`. The very first
-  two insertions happen to look right, which is why the defect hides in small cases.
-- **Fix**: insert after the found floor index, and normalise the "before everything" result:
-  `const where = binarySearchLowIndex(this.output.data, el, this.comparator); this.output.insert(where + 1, el);`
-  (`-1 + 1 === 0` gives the correct front insert). Separately, `List.insert` should reject negative
-  indices rather than forwarding them to `splice`.
-- **Confidence**: Confirmed
-
-### COLL-2 `BiMap.add` writes both directions inverted — every accessor returns `undefined`
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/map/BiMap.js:24-45`
-- **Defect**: `add(key, value)` does `forward.set(value, key)` and `backward.set(key, value)`, i.e.
-  `forward` ends up keyed by *value* and `backward` by *key* — the opposite of the declared field
-  types (`forward: Map<K,V>`, `backward: Map<V,K>`) and of what `getValueByKey` / `getKeyByValue`
-  read. Both accessors, and therefore the `get`/`set` Map-compatibility aliases installed on the
-  prototype, miss on every entry.
-- **Failure scenario**:
-  ```js
-  const m = new BiMap();
-  m.set('a', 1);
-  m.get('a');            // undefined   (expected 1)
-  m.getValueByKey('a');  // undefined   (expected 1)
-  m.getKeyByValue(1);    // undefined   (expected 'a')
-  ```
-  All three measured as `undefined`.
-- **Fix**: swap the two writes in `add`: `this.forward.set(key, value); this.backward.set(value, key);`.
-  Note that the single in-repo consumer, `core/binary/EncodingBinaryBuffer.js` (`writeUTF8String` /
-  `readUTF8String`), currently compensates for the inversion by calling `add(stringValue, address)`
-  and then reading it back with `getKeyByValue(stringValue)` → address and `getValueByKey(address)` →
-  string. Its two `add(...)` call sites must have their arguments swapped in the same change,
-  otherwise fixing `BiMap` breaks string interning in the encoding buffer.
-- **Confidence**: Confirmed
-
-### COLL-3 `Signal.merge` forwards the `arguments` object instead of the arguments
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/events/signal/Signal.js:797-808`
-- **Defect**: the bridging handler is `function handler() { result.dispatch(arguments); }`. `dispatch`
-  is variadic (`dispatch(...args)`), so the whole `arguments` object arrives as `args[0]`. Every
-  listener on a merged signal receives one array-like object rather than the original payload.
-- **Failure scenario**:
-  ```js
-  const a = new Signal(), b = new Signal();
-  const m = a.merge(b);
-  m.add((...args) => console.log(args));
-  a.send1(42);
-  ```
-  Logged `[ { '0': 42 } ]` (measured); expected `[ 42 ]`.
-- **Fix**: `function handler() { result.dispatch(...arguments); }` (or `result.dispatch.apply(result, arguments)`).
-- **Confidence**: Confirmed
-
----
-
-## MAJOR
-
-### COLL-4 `Deque.removeFirst` / `removeLast` on an empty deque corrupts head/tail/status
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/queue/Deque.js:321-327` and `:353-360`
-- **Defect**: neither method checks `#status`. On an empty deque `removeFirst` still advances `#head`
-  past `#tail`, then `#reset_status(false)` sees `head !== tail` and sets `STATUS_NORMAL`. The deque
-  now reports itself as non-empty and `size()` computes `tail + capacity - head` — one short of the
-  whole backing array. `removeLast` fails symmetrically by moving `#tail` backwards.
-- **Failure scenario**:
-  ```js
-  const d = new Deque();      // default capacity 16
-  d.removeFirst();            // -> undefined, as documented by @returns {T|undefined}
-  d.isEmpty();                // false   (measured; expected true)
-  d.size();                   // 15      (measured; expected 0)
-  ```
-  Any drain loop written against the documented `undefined` sentinel —
-  `while ((v = q.removeFirst()) !== undefined) {...}`, or the `pop()` alias in stack usage — leaves
-  the deque permanently poisoned: a following `while (!q.isEmpty()) q.removeFirst()` spins over 15
-  phantom `undefined` slots.
-- **Fix**: return `undefined` immediately when `this.#status === STATUS_EMPTY` in both `removeFirst`
-  and `removeLast`, before touching `#head`/`#tail`.
-- **Confidence**: Confirmed
-
-### COLL-5 `BinaryHeap.pop` on an empty heap sets `length = -1`; the next `push` throws
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/heap/BinaryHeap.js:160-184`
-- **Defect**: `pop()` decrements `this.length` unconditionally. On an empty heap `length` becomes
-  `-1`, `new_length !== 0` so the method falls through and writes `this.data[0] = undefined`,
-  re-growing the backing array. The subsequent `push` computes `position = this.length` (`-1`) and
-  calls `bubbleUp(-1)`, which reads `data[-1]` (`undefined`) and hands it to the score function.
-- **Failure scenario**:
-  ```js
-  const h = new BinaryHeap(x => x.score);
-  h.pop();          // -> undefined  (behaviour asserted by BinaryHeap.spec.js:23 and :34)
-  h.size();         // -1     (measured)
-  h.isEmpty();      // false  (measured)
-  h.push({score: 7});
-  // TypeError: Cannot read properties of undefined (reading 'score')   (measured)
-  ```
-  With a total score function such as `returnZero` there is no throw, but the pushed element is
-  silently lost (`size()` returns 0 afterwards). `BinaryHeap.spec.js:150` itself uses the
-  `while ((x = h.pop()) !== undefined)` drain pattern, so popping past empty is a sanctioned call.
-- **Fix**: early-return `undefined` when `this.length === 0` at the top of `pop()`.
-- **Confidence**: Confirmed
-
-### COLL-6 `FilteredListProjection.apply` uses `invokeObjectEquals`, throwing on any element without `.equals`
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/list/FilteredListProjection.js:139`
-- **Defect**: the diff uses `array_set_diff(oldOutput, newOutput, invokeObjectEquals)`, and
-  `invokeObjectEquals(a, b)` is an unguarded `a.equals(b)`. Any element type without an `equals`
-  method (numbers, strings, plain objects) throws. The throw is swallowed by `Signal`'s dispatch
-  `try/catch`, so the projection just stops updating and `output` silently goes stale forever.
-  `List.patch`, which performs the identical diff, correctly uses the guarded `objectsEqual`.
-- **Failure scenario**:
-  ```js
-  const input = new List([1, 2, 3]);
-  const p = new FilteredListProjection(input, new List());
-  p.deferred = false;
-  p.link();        // output === [1,2,3] — first apply is safe because oldOutput is empty
-  input.add(4);    // second apply
-  ```
-  Measured: `Failed to dispatch handler [Function: update] TypeError: a.equals is not a function`
-  at `invokeObjectEquals.js:9` via `array_set_diff.js:30`. `p.output` stays `[1,2,3]` with no
-  visible error to the caller.
-- **Fix**: pass `objectsEqual` (from `core/function/objectsEqual.js`) instead of
-  `invokeObjectEquals`, matching `List.patch`.
-- **Confidence**: Confirmed
-
-### COLL-7 `SortedListProjection` never observes removals from the input list
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/list/SortedListProjection.js:33-41`
-- **Defect**: `link()` subscribes only to `input.on.added`; `unlink()` unsubscribes only that. There
-  is no `on.removed` handler, so elements deleted from the input remain in `output` indefinitely.
-  This is independent of COLL-1 — fixing the insertion index alone still leaves the projection wrong.
-- **Failure scenario**: with COLL-1 fixed, `input.add(3); input.add(5); input.remove(0);` leaves
-  `output` as `[3, 5]` while `input` is `[5]`. Measured on the current code: after
-  `input.add(3..1); input.remove(0)`, `output` was unchanged at `[5,7,4,1,3]`.
-- **Fix**: in `link()` add `this.input.on.removed.add(this.handleRemoval, this)` with a handler that
-  locates the element in `output` (binary search on the comparator, then linear scan across the
-  equal-comparing run for identity) and removes it; mirror the unsubscribe in `unlink()`.
-- **Confidence**: Confirmed
-
-### COLL-8 `ArrayIteratorRandom.initialize` does not truncate the shuffle sequence
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/array/iterator/ArrayIteratorRandom.js:23-35`
-- **Defect**: `initialize` writes `__sequence[i] = i` for `i < data.length` but never shrinks
-  `__sequence`. `array_shuffle` then permutes the full stale length and `next()` bounds its loop with
-  `sequence.length`, so re-initialising the (explicitly reusable, allocation-free) iterator with a
-  shorter array yields too many items — including `undefined` — and repeats real ones.
-- **Failure scenario**:
-  ```js
-  const it = new ArrayIteratorRandom();
-  it.initialize(['a','b','c']);
-  it.initialize(['x','y']);
-  // drain via next(result)
-  ```
-  Yielded `["x", "y", undefined]` (measured) — three items from a two-element array.
-- **Fix**: `this.__sequence.length = n;` after the fill loop (before `array_shuffle`), or pass the
-  explicit `length` argument that `array_shuffle` already supports and use it as the bound in `next`.
-- **Confidence**: Confirmed
-
-### COLL-9 `RowFirstTable.hash()` is inconsistent with `RowFirstTable.equals()`
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/table/RowFirstTable.js:121-150`
-- **Defect**: `hash()` seeds from `this.data.byteLength` and taps across the whole *allocated buffer*,
-  including capacity beyond `length`. `equals()` compares only `length * bytesPerRecord` bytes. Two
-  tables that compare equal therefore hash differently whenever their capacities differ, breaking the
-  hash/equals contract for any `HashMap`/`HashSet`/`Cache` keyed by a table, and for hash-based
-  dirty-checking. (`hash()` also returns a non-int32 value because the accumulator is never masked.)
-- **Failure scenario**:
-  ```js
-  const spec = RowFirstTableSpec.get([BinaryDataType.Uint32]);
-  const a = new RowFirstTable(spec);
-  for (let i = 0; i < 20; i++) a.addRow([i]);   // grows to capacity 52
-  const b = new RowFirstTable(spec);
-  b.copy(a);
-  b.trim();                                     // capacity 20
-  a.equals(b);   // true            (measured)
-  a.hash();      // -13796099888    (measured)
-  b.hash();      // 4190943312      (measured)
-  ```
-- **Fix**: derive the hash from the live region only — seed with `this.length` (and
-  `spec.bytesPerRecord`) and bound the tap loop by `this.length * spec.bytesPerRecord >> 2` instead of
-  `this.data.byteLength >> 2`. Also `|0` the accumulator so the result is a 32-bit integer.
-- **Confidence**: Confirmed
-
-### COLL-10 `serializeRowFirstTable` / `deserializeRowFirstTable` drop the spec's endianness
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/table/serializeRowFirstTable.js:8-27`,
-  `H:/git/moh/app/src/mir-engine/meep/src/core/collection/table/deserializeRowFirstTable.js:39`
-- **Defect**: the serializer writes column types, record size and record count but not
-  `spec.endianType`. The deserializer rebuilds the spec with `RowFirstTableSpec.get(types)`, which
-  defaults to `EndianType.LittleEndian`. A table built on a big-endian spec round-trips with every
-  multi-byte cell byte-swapped. (`bytesPerRecord` is read and then discarded, so there is not even an
-  incidental mismatch check.)
-- **Failure scenario**:
-  ```js
-  const spec = new RowFirstTableSpec([BinaryDataType.Uint32], EndianType.BigEndian);
-  const t = new RowFirstTable(spec);
-  t.addRow([1]);
-  // serialize into a BinaryBuffer, rewind, deserialize into a fresh table
-  t2.readCellValue(0, 0);   // 16777216   (measured; expected 1)
-  ```
-  `t2.spec.endianType` came back as LittleEndian regardless of the source spec.
-- **Fix**: write `spec.endianType` (one byte) after the type list in the serializer and pass it to
-  `RowFirstTableSpec.get(types, endianType)` on read. Bump/branch on a format marker if existing
-  payloads must stay readable.
-- **Confidence**: Confirmed
-
-### COLL-11 `FrequencySketch` keeps Caffeine's 16-counters-per-slot layout on a 32-bit table
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/cache/FrequencySketch.js:43-68`, `:172-218`
-- **Defect**: the port kept Caffeine's `long[]` addressing — `start = (hash & 3) << 2` with
-  `start + i` spanning `0..15`, and shifts of `(start + i) << 2` spanning `0..60` — but the table is a
-  `Uint32Array`, which holds only 8 four-bit counters per word. JavaScript takes shift counts mod 32,
-  so logical counters 8..15 silently alias counters 0..7 in both `incrementAt` (`0xF << offset`,
-  `1 << offset`) and `frequency` (`table[index] >>> ((start + i) << 2)`). Half the counter space is
-  unreachable and the documented width / error bound (`e / width`, 93.75% confidence) does not hold.
-- **Failure scenario**:
-  ```js
-  const s = new FrequencySketch();
-  s.ensureCapacity(1);
-  s.increment(0);        // spread(0)  & 3 === 0  -> logical counters 0..3
-  s.frequency(3);        // spread(3)  & 3 === 2  -> logical counters 8..11
-  ```
-  Measured `s.frequency(3) === 1` (table word `0x1111`); the 16-counter layout the class documents
-  gives `0`. Element 3 was never incremented. This feeds `CacheWTinylfu.__admissionDuel` /
-  `shouldPromoteToProtected` directly, so admission and promotion decisions are made on inflated
-  frequencies.
-- **Fix**: either restrict the layout to the 8 counters a `Uint32Array` actually has
-  (`start = (hash & 1) << 2`, `start + i` in `0..7`, `RESET_MASK`/`ONE_MASK` already correct for 32
-  bits), or keep 16 counters per logical slot by addressing a `Uint32Array` of `2 * length` as pairs
-  (word `= index * 2 + ((start + i) >> 3)`, shift `= ((start + i) & 7) << 2`). Update the class
-  docstring to match whichever is chosen.
-- **Confidence**: Confirmed
-
----
-
-## MINOR
-
-### COLL-12 `Signal.contains` ignores its documented "thisArg optional" contract
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/events/signal/Signal.js:101-113`
-- **Defect**: the JSDoc states `@param {*} [thisArg] if not present, will not be considered`, but the
-  call is forwarded to `signal_handler_list_find`, which requires `n.context === thisArg`. With
-  `thisArg` omitted the comparison becomes `context === undefined`, so any handler registered with a
-  context reports as absent.
-- **Failure scenario**: `const s = new Signal(); s.add(f, ctx); s.contains(f)` → `false` (measured),
-  while `s.contains(f, ctx)` → `true`. Callers using `contains` as an "is this function subscribed at
-  all?" guard will double-register.
-- **Fix**: when `thisArg === undefined`, walk the chain matching on `handle` only (a dedicated
-  `signal_handler_list_find_by_handle`, mirroring the existing
-  `findSignalHandlerIndexByHandle`/`...AndContext` pair), or correct the JSDoc to state that the
-  context is always part of the match.
-- **Confidence**: Confirmed
-
-### COLL-13 `array_contains_duplicates` ignores `end_index` when scanning forward
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/array/array_contains_duplicates.js:22`
-- **Defect**: the outer loop respects `end_index`, but the inner probe is
-  `source.indexOf(element, k + 1)` with no upper bound, so it reports duplicates that lie outside the
-  requested `[start_index, end_index]` window. The parameters are documented as
-  "first/last index to be included in the search".
-- **Failure scenario**: `array_contains_duplicates([1, 2, 1], 0, 1)` → `true` (measured). The window
-  `[0,1]` contains `[1, 2]`, which has no duplicates. The spec only exercises the whole-array default.
-- **Fix**: bound the probe, e.g.
-  `const p = source.indexOf(element, k + 1); if (p !== -1 && p <= end_index) return true;`
-- **Confidence**: Confirmed
-
-### COLL-14 `weightedRandomFromArray` can return a zero-weight element
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/array/weightedRandomFromArray.js:43-50`
-- **Defect**: zero-weight entries leave `weight_total` unchanged, so the cumulative array repeats a
-  value. `binarySearchHighIndex` returns on exact equality, which selects the *first* index holding
-  that cumulative value — the zero-weight one. The intended semantics need the first index whose
-  cumulative weight is *strictly greater* than the target.
-- **Failure scenario**:
-  `weightedRandomFromArray(['A','B'], () => 0, x => x === 'A' ? 0 : 1)` → `'A'` (measured), an element
-  whose weight is 0 and which should be unreachable. Triggered whenever the supplied `random` returns
-  exactly `0` (seeded generators commonly can) and the leading element has zero weight.
-- **Fix**: after the binary search, advance past any run of equal cumulative values —
-  `while (index < length - 1 && scratch_weights[index] === scratch_weights[index + 1]) index++;` — or
-  use a dedicated upper-bound search that never short-circuits on equality.
-- **Confidence**: Confirmed
-
-### COLL-15 `sparse_typed_array_hash` silently ignores its `offset` parameter
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/array/typed/sparse_typed_array_hash.js:13-25`
-- **Defect**: the function takes `offset` but hard-codes `0` in the `computeStridedArrayHash` call, so
-  the hash always starts at index 0 regardless of the requested range.
-- **Failure scenario**:
-  `sparse_typed_array_hash(new Uint8Array([9,1,2]), 1, 3)` → `79698` and
-  `sparse_typed_array_hash(new Uint8Array([7,1,2]), 1, 3)` → `81620` (both measured). The two arrays
-  are identical over the requested `[1,3)` range and must hash the same; they differ only at index 0,
-  which should have been skipped. All three in-repo callers pass `offset === 0`, so nothing live is
-  affected today — but this is public library surface.
-- **Fix**: forward the parameter: `computeStridedArrayHash(array, offset, offset + hash_evaluation_length, stride, computeHashFloat)`
-  (`computeStridedArrayHash` treats its third argument as an exclusive end index), or drop the
-  parameter from the signature if a fixed prefix is genuinely intended.
-- **Confidence**: Confirmed
-
-### COLL-16 `uint8_array_hash` / `uint16_array_hash` mis-handle a non-zero `offset`
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/array/typed/uint8_array_hash.js:13-33`,
-  `H:/git/moh/app/src/mir-engine/meep/src/core/collection/array/typed/uint16_array_hash.js:13-26`
-- **Defect**: the head-alignment count is derived from `length` alone (`length & 3`, `length & 1`)
-  while the cursor starts at `offset`, and the main loop's bound is `i < length`. With `offset > 0`
-  the two disagree: the word loop reads `array[i+1..i+3]` past the requested end, so bytes outside
-  the range enter the hash (and out-of-range reads coerce to `0`). The sibling `uint32_array_hash`
-  and the only in-repo caller `array_buffer_hash` treat the third argument as an exclusive end index
-  and always pass `offset === 0`; under either reading (end index or count) the 8-bit and 16-bit
-  variants are wrong for `offset > 0`.
-- **Failure scenario**:
-  `uint8_array_hash(new Uint8Array([0,0,1,2,3,7,7]), 2, 5)` → `117904870` and
-  `uint8_array_hash(new Uint8Array([0,0,1,2,3,8,8]), 2, 5)` → `134747622` (both measured). The
-  requested range `[2,5)` is `1,2,3` in both arrays, so the hashes must match; indices 5 and 6 leaked
-  in. The existing spec calls `uint8_array_hash(arr, 1, 3)` but only asserts the result is a finite
-  integer, so the defect is untested.
-- **Fix**: compute the head remainder from the range size, not the total — `const n = length - offset;
-  const overflow = n & 3;` — and run the word loop while `i + 3 < length`, handling any tail
-  byte-wise. Same shape for the 16-bit variant (`(length - offset) & 1`, loop while `i + 1 < length`).
-- **Confidence**: Confirmed
-
-### COLL-17 `HashMap`/`HashSet`/`Cache` constructed with `capacity: 0` throw
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/map/HashMap.js:224` and `:247, 270-290`
-- **Defect**: the constructor explicitly permits `capacity === 0` (`assert.isNonNegativeInteger`), but
-  `ceilPowerOfTwo(0)` returns `0` and `#setBinCount(0)` computes `ctz32(0) === 32`, giving
-  `__entries_allocated_count = 2 ** 32`. In development the `greaterThanOrEqual(count, 1)` assert
-  fires; in a production bundle that assert is stripped and execution reaches
-  `UintArrayForCount(2 ** 32 + 2)`, which throws `Unsupported size 4294967298`. Either way an
-  otherwise-legal argument aborts construction, and it propagates to `HashSet` and `Cache`, both of
-  which forward `capacity` untouched.
-- **Failure scenario**: `new HashMap({ capacity: 0 })` → thrown
-  `bucket count must be at least 1. Expected 0 >= 1.` (measured under the test harness);
-  `Unsupported size 4294967298` in a production build. Same for `new HashSet({capacity: 0})` and
-  `new Cache({capacity: 0})`.
-- **Fix**: clamp in the constructor — `this.#setBinCount(ceilPowerOfTwo(max2(1, capacity)))` — so a
-  zero/undersized request lands on the minimum table instead of overflowing the shift.
-- **Confidence**: Confirmed
-
----
-
-## Checked and found clean (no findings)
-
-`IdPool`, `Uint32Map`, `PairUint32Map`, `Uint32MinHeap`, `Uint32Heap`, `Uint32Heap4`,
-`IndexedFloatMinHeap` / `IndexedFloatMaxHeap` (index/slot bookkeeping, sift directions, grow paths),
-`RingBuffer` (including the full-buffer `removeElementByIndex` shift), `Deque` apart from COLL-4
-(expand, ring arithmetic, `#remove_internal_shift_backward` on a full deque all verified),
-`HashMap` open addressing (Robin Hood probe, backward-shift delete, `rebuild` compaction, load-factor
-accounting — the bins array is provably never saturated), `HashSet`, `ArraySet`, `Stack`,
-`CuckooFilter` (alt-bucket reversibility confirmed), `union_find` (path halving), `Cache` LRU
-list/weight accounting (the pre-`data.set` eviction window is unreachable), `CacheWTinylfu` +
-`CacheRegionWTinylfu` + `wtinylfuDecisions`, `LoadingCache`, `Signal` add/remove/dispatch generation
-tracking and once-handler removal, `SignalBinding`, `SimpleStateMachine(Description)`,
-`FunctionCompiler`, `array_sort_quick` / `array_quick_sort_by_*`, `array_set_diff(_sorting)`,
-`array_shuffle`, `binarySearchHighIndex`, and the remaining `array/` and `array/typed/` helpers.
+# Correctness review — `core/collection`, `core/cache`, `core/events`, `core/fsm`, `core/function`, `core/IdPool.js`
+
+Scope: every non-spec source file under the listed directories. Every finding below was reproduced
+by executing the real modules through the project's jest harness (`npx jest --config jest.conf.json`
+from `H:/git/moh`, with a throwaway spec under `app/src/`, since removed). Observed values quoted in
+the failure scenarios are actual program output, not derivations.
+
+---
+
+## CRITICAL
+
+### COLL-1 `SortedListProjection` inserts at the wrong index — output is never sorted
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/list/SortedListProjection.js:47-51`
+- **Defect**: `binarySearchLowIndex` returns *the index of the largest element `<= el`* (or `-1` when
+  `el` precedes everything). `handleAddition` passes that value straight to `List.insert`, so the
+  element is placed **before** its predecessor instead of after it. The `-1` case is worse: it reaches
+  `List.insert(-1, el)`, whose `else` branch runs `this.data.splice(-1, 0, el)` — a negative splice
+  index that inserts before the *last* element — and then dispatches `on.added` with index `-1`.
+- **Failure scenario**:
+  ```js
+  const input = new List();
+  const p = new SortedListProjection(input, (a, b) => a - b);
+  p.link();
+  input.add(3); input.add(5); input.add(7); input.add(4); input.add(1);
+  ```
+  `p.output.asArray()` → `[5, 7, 4, 1, 3]` (measured). Expected `[1, 3, 4, 5, 7]`. The very first
+  two insertions happen to look right, which is why the defect hides in small cases.
+- **Fix**: insert after the found floor index, and normalise the "before everything" result:
+  `const where = binarySearchLowIndex(this.output.data, el, this.comparator); this.output.insert(where + 1, el);`
+  (`-1 + 1 === 0` gives the correct front insert). Separately, `List.insert` should reject negative
+  indices rather than forwarding them to `splice`.
+- **Confidence**: Confirmed
+
+### COLL-2 `BiMap.add` writes both directions inverted — every accessor returns `undefined`
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/map/BiMap.js:24-45`
+- **Defect**: `add(key, value)` does `forward.set(value, key)` and `backward.set(key, value)`, i.e.
+  `forward` ends up keyed by *value* and `backward` by *key* — the opposite of the declared field
+  types (`forward: Map<K,V>`, `backward: Map<V,K>`) and of what `getValueByKey` / `getKeyByValue`
+  read. Both accessors, and therefore the `get`/`set` Map-compatibility aliases installed on the
+  prototype, miss on every entry.
+- **Failure scenario**:
+  ```js
+  const m = new BiMap();
+  m.set('a', 1);
+  m.get('a');            // undefined   (expected 1)
+  m.getValueByKey('a');  // undefined   (expected 1)
+  m.getKeyByValue(1);    // undefined   (expected 'a')
+  ```
+  All three measured as `undefined`.
+- **Fix**: swap the two writes in `add`: `this.forward.set(key, value); this.backward.set(value, key);`.
+  Note that the single in-repo consumer, `core/binary/EncodingBinaryBuffer.js` (`writeUTF8String` /
+  `readUTF8String`), currently compensates for the inversion by calling `add(stringValue, address)`
+  and then reading it back with `getKeyByValue(stringValue)` → address and `getValueByKey(address)` →
+  string. Its two `add(...)` call sites must have their arguments swapped in the same change,
+  otherwise fixing `BiMap` breaks string interning in the encoding buffer.
+- **Confidence**: Confirmed
+
+### COLL-3 `Signal.merge` forwards the `arguments` object instead of the arguments
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/events/signal/Signal.js:797-808`
+- **Defect**: the bridging handler is `function handler() { result.dispatch(arguments); }`. `dispatch`
+  is variadic (`dispatch(...args)`), so the whole `arguments` object arrives as `args[0]`. Every
+  listener on a merged signal receives one array-like object rather than the original payload.
+- **Failure scenario**:
+  ```js
+  const a = new Signal(), b = new Signal();
+  const m = a.merge(b);
+  m.add((...args) => console.log(args));
+  a.send1(42);
+  ```
+  Logged `[ { '0': 42 } ]` (measured); expected `[ 42 ]`.
+- **Fix**: `function handler() { result.dispatch(...arguments); }` (or `result.dispatch.apply(result, arguments)`).
+- **Confidence**: Confirmed
+
+---
+
+## MAJOR
+
+### COLL-4 `Deque.removeFirst` / `removeLast` on an empty deque corrupts head/tail/status
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/queue/Deque.js:321-327` and `:353-360`
+- **Defect**: neither method checks `#status`. On an empty deque `removeFirst` still advances `#head`
+  past `#tail`, then `#reset_status(false)` sees `head !== tail` and sets `STATUS_NORMAL`. The deque
+  now reports itself as non-empty and `size()` computes `tail + capacity - head` — one short of the
+  whole backing array. `removeLast` fails symmetrically by moving `#tail` backwards.
+- **Failure scenario**:
+  ```js
+  const d = new Deque();      // default capacity 16
+  d.removeFirst();            // -> undefined, as documented by @returns {T|undefined}
+  d.isEmpty();                // false   (measured; expected true)
+  d.size();                   // 15      (measured; expected 0)
+  ```
+  Any drain loop written against the documented `undefined` sentinel —
+  `while ((v = q.removeFirst()) !== undefined) {...}`, or the `pop()` alias in stack usage — leaves
+  the deque permanently poisoned: a following `while (!q.isEmpty()) q.removeFirst()` spins over 15
+  phantom `undefined` slots.
+- **Fix**: return `undefined` immediately when `this.#status === STATUS_EMPTY` in both `removeFirst`
+  and `removeLast`, before touching `#head`/`#tail`.
+- **Confidence**: Confirmed
+
+### COLL-5 `BinaryHeap.pop` on an empty heap sets `length = -1`; the next `push` throws
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/heap/BinaryHeap.js:160-184`
+- **Defect**: `pop()` decrements `this.length` unconditionally. On an empty heap `length` becomes
+  `-1`, `new_length !== 0` so the method falls through and writes `this.data[0] = undefined`,
+  re-growing the backing array. The subsequent `push` computes `position = this.length` (`-1`) and
+  calls `bubbleUp(-1)`, which reads `data[-1]` (`undefined`) and hands it to the score function.
+- **Failure scenario**:
+  ```js
+  const h = new BinaryHeap(x => x.score);
+  h.pop();          // -> undefined  (behaviour asserted by BinaryHeap.spec.js:23 and :34)
+  h.size();         // -1     (measured)
+  h.isEmpty();      // false  (measured)
+  h.push({score: 7});
+  // TypeError: Cannot read properties of undefined (reading 'score')   (measured)
+  ```
+  With a total score function such as `returnZero` there is no throw, but the pushed element is
+  silently lost (`size()` returns 0 afterwards). `BinaryHeap.spec.js:150` itself uses the
+  `while ((x = h.pop()) !== undefined)` drain pattern, so popping past empty is a sanctioned call.
+- **Fix**: early-return `undefined` when `this.length === 0` at the top of `pop()`.
+- **Confidence**: Confirmed
+
+### COLL-6 `FilteredListProjection.apply` uses `invokeObjectEquals`, throwing on any element without `.equals`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/list/FilteredListProjection.js:139`
+- **Defect**: the diff uses `array_set_diff(oldOutput, newOutput, invokeObjectEquals)`, and
+  `invokeObjectEquals(a, b)` is an unguarded `a.equals(b)`. Any element type without an `equals`
+  method (numbers, strings, plain objects) throws. The throw is swallowed by `Signal`'s dispatch
+  `try/catch`, so the projection just stops updating and `output` silently goes stale forever.
+  `List.patch`, which performs the identical diff, correctly uses the guarded `objectsEqual`.
+- **Failure scenario**:
+  ```js
+  const input = new List([1, 2, 3]);
+  const p = new FilteredListProjection(input, new List());
+  p.deferred = false;
+  p.link();        // output === [1,2,3] — first apply is safe because oldOutput is empty
+  input.add(4);    // second apply
+  ```
+  Measured: `Failed to dispatch handler [Function: update] TypeError: a.equals is not a function`
+  at `invokeObjectEquals.js:9` via `array_set_diff.js:30`. `p.output` stays `[1,2,3]` with no
+  visible error to the caller.
+- **Fix**: pass `objectsEqual` (from `core/function/objectsEqual.js`) instead of
+  `invokeObjectEquals`, matching `List.patch`.
+- **Confidence**: Confirmed
+
+### COLL-7 `SortedListProjection` never observes removals from the input list
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/list/SortedListProjection.js:33-41`
+- **Defect**: `link()` subscribes only to `input.on.added`; `unlink()` unsubscribes only that. There
+  is no `on.removed` handler, so elements deleted from the input remain in `output` indefinitely.
+  This is independent of COLL-1 — fixing the insertion index alone still leaves the projection wrong.
+- **Failure scenario**: with COLL-1 fixed, `input.add(3); input.add(5); input.remove(0);` leaves
+  `output` as `[3, 5]` while `input` is `[5]`. Measured on the current code: after
+  `input.add(3..1); input.remove(0)`, `output` was unchanged at `[5,7,4,1,3]`.
+- **Fix**: in `link()` add `this.input.on.removed.add(this.handleRemoval, this)` with a handler that
+  locates the element in `output` (binary search on the comparator, then linear scan across the
+  equal-comparing run for identity) and removes it; mirror the unsubscribe in `unlink()`.
+- **Confidence**: Confirmed
+
+### COLL-8 `ArrayIteratorRandom.initialize` does not truncate the shuffle sequence
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/array/iterator/ArrayIteratorRandom.js:23-35`
+- **Defect**: `initialize` writes `__sequence[i] = i` for `i < data.length` but never shrinks
+  `__sequence`. `array_shuffle` then permutes the full stale length and `next()` bounds its loop with
+  `sequence.length`, so re-initialising the (explicitly reusable, allocation-free) iterator with a
+  shorter array yields too many items — including `undefined` — and repeats real ones.
+- **Failure scenario**:
+  ```js
+  const it = new ArrayIteratorRandom();
+  it.initialize(['a','b','c']);
+  it.initialize(['x','y']);
+  // drain via next(result)
+  ```
+  Yielded `["x", "y", undefined]` (measured) — three items from a two-element array.
+- **Fix**: `this.__sequence.length = n;` after the fill loop (before `array_shuffle`), or pass the
+  explicit `length` argument that `array_shuffle` already supports and use it as the bound in `next`.
+- **Confidence**: Confirmed
+
+### COLL-9 `RowFirstTable.hash()` is inconsistent with `RowFirstTable.equals()`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/table/RowFirstTable.js:121-150`
+- **Defect**: `hash()` seeds from `this.data.byteLength` and taps across the whole *allocated buffer*,
+  including capacity beyond `length`. `equals()` compares only `length * bytesPerRecord` bytes. Two
+  tables that compare equal therefore hash differently whenever their capacities differ, breaking the
+  hash/equals contract for any `HashMap`/`HashSet`/`Cache` keyed by a table, and for hash-based
+  dirty-checking. (`hash()` also returns a non-int32 value because the accumulator is never masked.)
+- **Failure scenario**:
+  ```js
+  const spec = RowFirstTableSpec.get([BinaryDataType.Uint32]);
+  const a = new RowFirstTable(spec);
+  for (let i = 0; i < 20; i++) a.addRow([i]);   // grows to capacity 52
+  const b = new RowFirstTable(spec);
+  b.copy(a);
+  b.trim();                                     // capacity 20
+  a.equals(b);   // true            (measured)
+  a.hash();      // -13796099888    (measured)
+  b.hash();      // 4190943312      (measured)
+  ```
+- **Fix**: derive the hash from the live region only — seed with `this.length` (and
+  `spec.bytesPerRecord`) and bound the tap loop by `this.length * spec.bytesPerRecord >> 2` instead of
+  `this.data.byteLength >> 2`. Also `|0` the accumulator so the result is a 32-bit integer.
+- **Confidence**: Confirmed
+
+### COLL-10 `serializeRowFirstTable` / `deserializeRowFirstTable` drop the spec's endianness
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/table/serializeRowFirstTable.js:8-27`,
+  `H:/git/moh/app/src/mir-engine/meep/src/core/collection/table/deserializeRowFirstTable.js:39`
+- **Defect**: the serializer writes column types, record size and record count but not
+  `spec.endianType`. The deserializer rebuilds the spec with `RowFirstTableSpec.get(types)`, which
+  defaults to `EndianType.LittleEndian`. A table built on a big-endian spec round-trips with every
+  multi-byte cell byte-swapped. (`bytesPerRecord` is read and then discarded, so there is not even an
+  incidental mismatch check.)
+- **Failure scenario**:
+  ```js
+  const spec = new RowFirstTableSpec([BinaryDataType.Uint32], EndianType.BigEndian);
+  const t = new RowFirstTable(spec);
+  t.addRow([1]);
+  // serialize into a BinaryBuffer, rewind, deserialize into a fresh table
+  t2.readCellValue(0, 0);   // 16777216   (measured; expected 1)
+  ```
+  `t2.spec.endianType` came back as LittleEndian regardless of the source spec.
+- **Fix**: write `spec.endianType` (one byte) after the type list in the serializer and pass it to
+  `RowFirstTableSpec.get(types, endianType)` on read. Bump/branch on a format marker if existing
+  payloads must stay readable.
+- **Confidence**: Confirmed
+
+### COLL-11 `FrequencySketch` keeps Caffeine's 16-counters-per-slot layout on a 32-bit table
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/cache/FrequencySketch.js:43-68`, `:172-218`
+- **Defect**: the port kept Caffeine's `long[]` addressing — `start = (hash & 3) << 2` with
+  `start + i` spanning `0..15`, and shifts of `(start + i) << 2` spanning `0..60` — but the table is a
+  `Uint32Array`, which holds only 8 four-bit counters per word. JavaScript takes shift counts mod 32,
+  so logical counters 8..15 silently alias counters 0..7 in both `incrementAt` (`0xF << offset`,
+  `1 << offset`) and `frequency` (`table[index] >>> ((start + i) << 2)`). Half the counter space is
+  unreachable and the documented width / error bound (`e / width`, 93.75% confidence) does not hold.
+- **Failure scenario**:
+  ```js
+  const s = new FrequencySketch();
+  s.ensureCapacity(1);
+  s.increment(0);        // spread(0)  & 3 === 0  -> logical counters 0..3
+  s.frequency(3);        // spread(3)  & 3 === 2  -> logical counters 8..11
+  ```
+  Measured `s.frequency(3) === 1` (table word `0x1111`); the 16-counter layout the class documents
+  gives `0`. Element 3 was never incremented. This feeds `CacheWTinylfu.__admissionDuel` /
+  `shouldPromoteToProtected` directly, so admission and promotion decisions are made on inflated
+  frequencies.
+- **Fix**: either restrict the layout to the 8 counters a `Uint32Array` actually has
+  (`start = (hash & 1) << 2`, `start + i` in `0..7`, `RESET_MASK`/`ONE_MASK` already correct for 32
+  bits), or keep 16 counters per logical slot by addressing a `Uint32Array` of `2 * length` as pairs
+  (word `= index * 2 + ((start + i) >> 3)`, shift `= ((start + i) & 7) << 2`). Update the class
+  docstring to match whichever is chosen.
+- **Confidence**: Confirmed
+
+---
+
+## MINOR
+
+### COLL-12 `Signal.contains` ignores its documented "thisArg optional" contract
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/events/signal/Signal.js:101-113`
+- **Defect**: the JSDoc states `@param {*} [thisArg] if not present, will not be considered`, but the
+  call is forwarded to `signal_handler_list_find`, which requires `n.context === thisArg`. With
+  `thisArg` omitted the comparison becomes `context === undefined`, so any handler registered with a
+  context reports as absent.
+- **Failure scenario**: `const s = new Signal(); s.add(f, ctx); s.contains(f)` → `false` (measured),
+  while `s.contains(f, ctx)` → `true`. Callers using `contains` as an "is this function subscribed at
+  all?" guard will double-register.
+- **Fix**: when `thisArg === undefined`, walk the chain matching on `handle` only (a dedicated
+  `signal_handler_list_find_by_handle`, mirroring the existing
+  `findSignalHandlerIndexByHandle`/`...AndContext` pair), or correct the JSDoc to state that the
+  context is always part of the match.
+- **Confidence**: Confirmed
+
+### COLL-13 `array_contains_duplicates` ignores `end_index` when scanning forward
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/array/array_contains_duplicates.js:22`
+- **Defect**: the outer loop respects `end_index`, but the inner probe is
+  `source.indexOf(element, k + 1)` with no upper bound, so it reports duplicates that lie outside the
+  requested `[start_index, end_index]` window. The parameters are documented as
+  "first/last index to be included in the search".
+- **Failure scenario**: `array_contains_duplicates([1, 2, 1], 0, 1)` → `true` (measured). The window
+  `[0,1]` contains `[1, 2]`, which has no duplicates. The spec only exercises the whole-array default.
+- **Fix**: bound the probe, e.g.
+  `const p = source.indexOf(element, k + 1); if (p !== -1 && p <= end_index) return true;`
+- **Confidence**: Confirmed
+
+### COLL-14 `weightedRandomFromArray` can return a zero-weight element
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/array/weightedRandomFromArray.js:43-50`
+- **Defect**: zero-weight entries leave `weight_total` unchanged, so the cumulative array repeats a
+  value. `binarySearchHighIndex` returns on exact equality, which selects the *first* index holding
+  that cumulative value — the zero-weight one. The intended semantics need the first index whose
+  cumulative weight is *strictly greater* than the target.
+- **Failure scenario**:
+  `weightedRandomFromArray(['A','B'], () => 0, x => x === 'A' ? 0 : 1)` → `'A'` (measured), an element
+  whose weight is 0 and which should be unreachable. Triggered whenever the supplied `random` returns
+  exactly `0` (seeded generators commonly can) and the leading element has zero weight.
+- **Fix**: after the binary search, advance past any run of equal cumulative values —
+  `while (index < length - 1 && scratch_weights[index] === scratch_weights[index + 1]) index++;` — or
+  use a dedicated upper-bound search that never short-circuits on equality.
+- **Confidence**: Confirmed
+
+### COLL-15 `sparse_typed_array_hash` silently ignores its `offset` parameter
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/array/typed/sparse_typed_array_hash.js:13-25`
+- **Defect**: the function takes `offset` but hard-codes `0` in the `computeStridedArrayHash` call, so
+  the hash always starts at index 0 regardless of the requested range.
+- **Failure scenario**:
+  `sparse_typed_array_hash(new Uint8Array([9,1,2]), 1, 3)` → `79698` and
+  `sparse_typed_array_hash(new Uint8Array([7,1,2]), 1, 3)` → `81620` (both measured). The two arrays
+  are identical over the requested `[1,3)` range and must hash the same; they differ only at index 0,
+  which should have been skipped. All three in-repo callers pass `offset === 0`, so nothing live is
+  affected today — but this is public library surface.
+- **Fix**: forward the parameter: `computeStridedArrayHash(array, offset, offset + hash_evaluation_length, stride, computeHashFloat)`
+  (`computeStridedArrayHash` treats its third argument as an exclusive end index), or drop the
+  parameter from the signature if a fixed prefix is genuinely intended.
+- **Confidence**: Confirmed
+
+### COLL-16 `uint8_array_hash` / `uint16_array_hash` mis-handle a non-zero `offset`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/array/typed/uint8_array_hash.js:13-33`,
+  `H:/git/moh/app/src/mir-engine/meep/src/core/collection/array/typed/uint16_array_hash.js:13-26`
+- **Defect**: the head-alignment count is derived from `length` alone (`length & 3`, `length & 1`)
+  while the cursor starts at `offset`, and the main loop's bound is `i < length`. With `offset > 0`
+  the two disagree: the word loop reads `array[i+1..i+3]` past the requested end, so bytes outside
+  the range enter the hash (and out-of-range reads coerce to `0`). The sibling `uint32_array_hash`
+  and the only in-repo caller `array_buffer_hash` treat the third argument as an exclusive end index
+  and always pass `offset === 0`; under either reading (end index or count) the 8-bit and 16-bit
+  variants are wrong for `offset > 0`.
+- **Failure scenario**:
+  `uint8_array_hash(new Uint8Array([0,0,1,2,3,7,7]), 2, 5)` → `117904870` and
+  `uint8_array_hash(new Uint8Array([0,0,1,2,3,8,8]), 2, 5)` → `134747622` (both measured). The
+  requested range `[2,5)` is `1,2,3` in both arrays, so the hashes must match; indices 5 and 6 leaked
+  in. The existing spec calls `uint8_array_hash(arr, 1, 3)` but only asserts the result is a finite
+  integer, so the defect is untested.
+- **Fix**: compute the head remainder from the range size, not the total — `const n = length - offset;
+  const overflow = n & 3;` — and run the word loop while `i + 3 < length`, handling any tail
+  byte-wise. Same shape for the 16-bit variant (`(length - offset) & 1`, loop while `i + 1 < length`).
+- **Confidence**: Confirmed
+
+### COLL-17 `HashMap`/`HashSet`/`Cache` constructed with `capacity: 0` throw
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/collection/map/HashMap.js:224` and `:247, 270-290`
+- **Defect**: the constructor explicitly permits `capacity === 0` (`assert.isNonNegativeInteger`), but
+  `ceilPowerOfTwo(0)` returns `0` and `#setBinCount(0)` computes `ctz32(0) === 32`, giving
+  `__entries_allocated_count = 2 ** 32`. In development the `greaterThanOrEqual(count, 1)` assert
+  fires; in a production bundle that assert is stripped and execution reaches
+  `UintArrayForCount(2 ** 32 + 2)`, which throws `Unsupported size 4294967298`. Either way an
+  otherwise-legal argument aborts construction, and it propagates to `HashSet` and `Cache`, both of
+  which forward `capacity` untouched.
+- **Failure scenario**: `new HashMap({ capacity: 0 })` → thrown
+  `bucket count must be at least 1. Expected 0 >= 1.` (measured under the test harness);
+  `Unsupported size 4294967298` in a production build. Same for `new HashSet({capacity: 0})` and
+  `new Cache({capacity: 0})`.
+- **Fix**: clamp in the constructor — `this.#setBinCount(ceilPowerOfTwo(max2(1, capacity)))` — so a
+  zero/undersized request lands on the minimum table instead of overflowing the shift.
+- **Confidence**: Confirmed
+
+---
+
+## Checked and found clean (no findings)
+
+`IdPool`, `Uint32Map`, `PairUint32Map`, `Uint32MinHeap`, `Uint32Heap`, `Uint32Heap4`,
+`IndexedFloatMinHeap` / `IndexedFloatMaxHeap` (index/slot bookkeeping, sift directions, grow paths),
+`RingBuffer` (including the full-buffer `removeElementByIndex` shift), `Deque` apart from COLL-4
+(expand, ring arithmetic, `#remove_internal_shift_backward` on a full deque all verified),
+`HashMap` open addressing (Robin Hood probe, backward-shift delete, `rebuild` compaction, load-factor
+accounting — the bins array is provably never saturated), `HashSet`, `ArraySet`, `Stack`,
+`CuckooFilter` (alt-bucket reversibility confirmed), `union_find` (path halving), `Cache` LRU
+list/weight accounting (the pre-`data.set` eviction window is unreachable), `CacheWTinylfu` +
+`CacheRegionWTinylfu` + `wtinylfuDecisions`, `LoadingCache`, `Signal` add/remove/dispatch generation
+tracking and once-handler removal, `SignalBinding`, `SimpleStateMachine(Description)`,
+`FunctionCompiler`, `array_sort_quick` / `array_quick_sort_by_*`, `array_set_diff(_sorting)`,
+`array_shuffle`, `binarySearchHighIndex`, and the remaining `array/` and `array/typed/` helpers.