@woosh/meep-engine 2.165.7 → 2.167.0

package/src/core/cache/wtinylfu/benchmark/CacheWTinylfu.bench.md

@@ -0,0 +1,243 @@
+# W-TinyLFU benchmarks
+
+Benchmarks comparing `CacheWTinylfu` against the LRU `Cache` sibling. They split into **two axes**
+that answer different questions:
+
+| Axis | Question | Answered by |
+|------|----------|-------------|
+| **Effectiveness** (hit rate) | What fraction of accesses hit? Determined by the **policy**. | `hitRate.spec.js` |
+| **Performance** (throughput / latency / space) | What does each operation **cost**? Determined by the **implementation**. | everything else |
+
+You need both to judge the trade: the policy benchmark tells you what W-TinyLFU *saves you in misses*;
+the performance benchmarks tell you what it *costs per op and in RAM*. The exchange rate between them is
+the cost of a miss in your system (a disk/network miss dwarfs a few hundred ns; a cheap recompute does not).
+
+> ⚠️ **About the numbers below.** They're from one dev machine (Node v20.14.0, Windows 11) and microbenchmarks
+> are noisy — absolute nanoseconds wander run-to-run by tens of percent. **Trust the ratios and the shape, not
+> the exact ns.** The ratios are measured *interleaved* (LRU and W-TinyLFU timed back-to-back each round, then
+> the per-round ratios medianed), so they stay stable even as the absolutes drift. Re-run on your own hardware
+> for absolutes.
+
+---
+
+## Running
+
+Each benchmark is a **self-executing spec**: a single `<name>.spec.js` that is *both* a runnable Node
+benchmark and a Jest spec. The measurement **only ever runs under plain `node`** — never in-process under
+Jest, because Jest's babel transform badly distorts the timings (see *Why not measure under Jest* below).
+The files are stripped from the published npm package by the `*.spec.js` rule.
+
+**To get numbers — run it directly with `node`, from the repo root:**
+
+```bash
+node src/core/cache/wtinylfu/benchmark/<name>.spec.js
+```
+
+where `<name>` is one of: `hitRate`, `fillDrain`, `readAll`, `continuousPut`, `mixed`, `latency`, `scaling`,
+`memory`.
+
+**Under Jest** each file is a `describe.skip`, so `npx jest` collects but skips them (zero CI cost). Un-skip
+one (flip `describe.skip` → `describe`) and Jest will **spawn a clean `node` child on the file** and check the
+output is sane — you get the same pristine numbers, never the transformed ones.
+
+Two flags (for the `node` invocation):
+
+- **`--expose-gc`** (a Node flag, goes *before* the script path): lets a benchmark force GC between trials for
+  cleaner numbers. Optional for most; **required** for `memory` (it refuses to run without it). *(When run via
+  Jest, the child is always spawned with `--expose-gc`.)*
+  ```bash
+  node --expose-gc src/core/cache/wtinylfu/benchmark/fillDrain.spec.js
+  ```
+- **`HASH=int`** (an env var): the **isolated-hash toggle** — use integer keys + an identity hash instead of
+  string keys + `computeStringHash`, to strip string-hashing cost and see pure-policy overhead. Works on
+  **every** benchmark.
+  ```bash
+  HASH=int node --expose-gc src/core/cache/wtinylfu/benchmark/readAll.spec.js
+  ```
+
+All workloads are **seeded**, so runs are reproducible. Both caches are always built at **matched capacity**
+(N weight-1 entries) so the comparison is fair.
+
+### Layout & file structure
+
+Each benchmark lives in its own self-contained file in this `benchmark/` folder as `<name>.spec.js`.
+There is **no shared harness** — each file inlines the scaffolding it needs, so it stands alone (copy it,
+run it, read it without chasing imports). Every file follows the same skeleton:
+
+```
+1. HEADER       what it measures · how to run · how to read it
+2. CONFIG       the knobs: CAPACITY / WARMUP / TRIALS / SEED
+3. SCAFFOLDING  inlined: clock, rng, matched-capacity factories, measureInterleaved, any workload
+                (top-level — pure definitions, safe when Jest imports the file)
+   if (under Jest) → spawn a clean `node` on this file + assert the output is sane
+   else            → the actual benchmark:
+4. WORKLOAD       the setup + the timed body                       (the "arrange")
+5. MEASURE        measureInterleaved([LRU, W-TinyLFU], {...})      (the "act")
+6. REPORT         formatting + console.log                         (the "assert" analog — reports, no pass/fail)
+```
+
+The `if (typeof describe === "function")` split is what keeps the measurement out of Jest's transform: under
+Jest only the spawn-branch runs; under `node` only the `else` (measurement) branch runs.
+
+A benchmark **reports** numbers; it does not **assert** pass/fail. That's why the measurement always runs
+under plain `node` — the Jest side only launches it and checks the output isn't empty.
+
+### Why not measure under Jest
+
+Jest runs every file through **babel-jest** before V8 sees it (transpiled to CommonJS, wrapped in Jest's
+module registry). That transformed code JITs differently from the native ES module `node` runs — and the
+overhead is **not uniform**: a cheap op (LRU) takes a bigger proportional hit than a heavier one (W-TinyLFU).
+Measured in-process under Jest, absolutes inflated ~2–12× **and several ratios inverted** — `fill` read
+1.76x → 0.91x, `mixed` 1.48x → 0.90x, `latency p50` 3.0x → 0.86x — i.e. Jest would tell you W-TinyLFU is
+*faster* than LRU on inserts, which is false. It was also ~4× slower wall-clock. So the benchmark body never
+runs under Jest; the spec spawns a clean `node` child and only checks the output is well-formed.
+
+---
+
+## Effectiveness — `hitRate.spec.js`
+
+Replays seeded access traces as a read-through cache and reports **hit ratio** (capacity N = 500). This is
+where W-TinyLFU earns its keep.
+
+```
+                                       LRU      W-TinyLFU    Δ
+uniform random (no skew)              10.0%      10.0%      0.0   ← control: no harm
+zipfian skew 0.7 / 0.9 / 1.1        22.7/45.4/70.7  ~equal  ±1    ← realistic skew: roughly even
+scan (hot set + one-shot scans)       31.6%      47.0%     +15.4  ← scan resistance: the big win
+cyclic loop (size > capacity)         LRU pathological case  win  ← incumbent-favoring ties
+```
+
+**Takeaway:** roughly even with LRU on plain skew, *no worse* on uniform, and a large win on **scan-heavy**
+and **cyclic** workloads (where LRU is catastrophic). That scan resistance is the reason to pay the costs below.
+
+---
+
+## Performance
+
+Realistic (string-key) mode, `--expose-gc`, interleaved, median of 100 trials. **Capacities:** the read / fill /
+space and `continuousPut` benchmarks use **N = 65,536**; `mixed` uses a quarter of that (**N = 16,384**,
+keyspace 10×N) so its keyspace can dwarf the cache for realistic misses. All are powers of two — safe under
+churn because the shared HashMap grows headroom at its load factor.
+
+### `fillDrain` — insert + teardown
+
+```
+fill (put)       | LRU ~197 ns/op  | W-TinyLFU ~378 ns/op  | ~2.1x
+drain (clear)    | LRU ~21 ms/call | W-TinyLFU ~11 ms/call  | ~0.52x
+drain (remove)   | LRU ~259 ns/op  | W-TinyLFU ~317 ns/op   | ~1.2x
+```
+`fill` is the policy's insert cost (sketch + region routing). The `drain` rows reflect each class's *teardown
+implementation*, not the policy — LRU's `clear()` removes element-by-element while W-TinyLFU bulk-resets, so the
+drain difference is an implementation artifact.
+
+### `readAll` — read path (cold vs warm)
+
+```
+read cold        | LRU ~370 ns/op | W-TinyLFU ~710 ns/op | ~1.9x
+read warm        | LRU ~290 ns/op | W-TinyLFU ~490 ns/op | ~1.7x
+```
+Every get is a hit. `cold` = first read-pass (W-TinyLFU's promotion activity); `warm` = settled steady state.
+The premium is modest and one-time, not a recurring spike.
+
+### `continuousPut` — sustained load (churn vs update)
+
+```
+put churn        | LRU ~660 ns/op | W-TinyLFU ~656 ns/op | ~1.0x   (new keys → evict + admission duel)
+put update       | LRU ~220 ns/op | W-TinyLFU ~447 ns/op | ~2.0x   (re-put existing keys → in-place)
+```
+**The key reframe.** W-TinyLFU's extra policy work is roughly **additive (~150–200 ns/op)**, not a multiplier —
+on the cheap `update` baseline it shows as ~2.1×. On `churn` it doesn't show at all: **element pooling** makes
+W-TinyLFU's inserts allocation-free, while LRU still allocates an element per insert, so that saving *offsets*
+the policy overhead and W-TinyLFU draws level with LRU (~1.0×).
+
+### `mixed` — realistic blended throughput
+
+```
+mixed get/put    | LRU ~157 ns/op | W-TinyLFU ~224 ns/op | ~1.4x
+```
+Zipfian read-through (get; on miss, put) over a keyspace 10× the cache — the most representative single number.
+
+### `latency` — the tail (percentiles)
+
+```
+              p50    p99    p999     max
+LRU           200   ~700   ~2400    multi-ms (GC)
+W-TinyLFU     300   ~1300  ~7400    multi-ms (GC)
+```
+Per-op timing during a fill. W-TinyLFU's whole distribution shifts up ~2× — its heavier insert, paid broadly
+rather than in a rare spike. The **max is a multi-ms GC pause on both**, not a policy event — read the policy
+tail in p99/p999, not max.
+
+### `memory` — bytes per entry (space) · requires `--expose-gc`
+
+```
+                       fresh fill                 after churn (steady state)
+LRU          | ~144 (heap ~136 + ext ~8)  | ~224 (heap ~208 + ext ~16)  bytes/entry
+W-TinyLFU    | ~164 (heap ~152 + ext ~12) | ~245 (heap ~225 + ext ~20)  bytes/entry
+→ fresh, W-TinyLFU vs LRU: +~20 B/entry  (+~16 heap = per-element `region` + `keyHash`; +~4 sketch)
+→ churn cost (both caches): +~80 B/entry  (the shared HashMap doubling its slab at the load factor)
+```
+~14% more RAM per entry for the **policy** (fresh) — the **W-vs-LRU difference of ~4 B ≈ the sketch**. The
+**churn cost** is the same +~80 for both because it's the *shared HashMap*, not the policy: once the cache is
+full and evicting, the entries slab (and its bins) hits the 0.75 load factor and **doubles** to keep amortised
+O(1) inserts, so a churning cache carries ~2× the entry headroom of a fresh fill.
+
+### `scaling` — O(1) check + locality across N
+
+```
+     N        LRU      W-TinyLFU   ratio
+    2,048     62.3       175.6      2.88x
+   16,384    102.8       230.0      2.25x
+  131,072    379.2       556.8      1.47x
+1,048,576    667.7       911.8      1.37x        (warm random read, ns/op)
+```
+Per-op cost rises only ~11× from 2k→1M (not ~500×) → **O(1) confirmed**; the rise is **CPU-cache locality**.
+The ratio **compresses as N grows** — both caches increasingly bottlenecked on RAM latency at large N.
+
+### `HASH=int` — pure-policy overhead (cross-cutting)
+
+Run any benchmark with `HASH=int` to strip string hashing. Example (read warm):
+
+```
+                realistic        isolated (HASH=int)
+LRU              ~290 ns/op        ~151 ns/op
+W-TinyLFU        ~490 ns/op        ~338 ns/op
+ratio             ~1.7x             ~2.3x
+```
+Reveals that **string hashing is a large *shared* cost** (~140 ns of LRU's warm read was just `Map` string
+hashing, paid by both caches). Removing it shrinks the baseline, so the *same* fixed policy overhead becomes a
+bigger multiple.
+
+---
+
+## Headline findings
+
+1. **Cost is a roughly fixed additive overhead, not a multiplier** — ~100–300 ns/op of extra work (sketch
+   increment + region bookkeeping), so the "Nx" you see depends mostly on how cheap the underlying op already was.
+2. **O(1) and predictable** — confirmed across 3 orders of magnitude; the only growth is shared CPU-cache locality.
+3. **No tail surprises** — the overhead is spread across the whole distribution (median through p999), not a rare
+   spike; the worst-case `max` is a GC pause both caches share.
+4. **~14% more memory per entry** — the per-element `region` + `keyHash` fields plus the O(N) frequency sketch
+   (plus a shared ~+80 B/entry once any cache is full and churning — the HashMap doubling its slab, not policy-specific).
+5. **Bought against scan resistance** — the effectiveness axis shows large hit-rate wins on scan/cyclic workloads,
+   while staying roughly even with LRU on plain skew and doing no harm on uniform.
+
+**The trade in one line:** ~150–200 ns/op and ~14% RAM, predictable and O(1), in exchange for scan-resistant,
+frequency-aware retention — worth it exactly when your misses are expensive and your traffic isn't purely uniform.
+
+## Methodology notes (why the numbers are trustworthy)
+
+- **Pre-generated keys** outside the timed region (else you measure string allocation, not the cache).
+- **Warmup** discarded so the JIT has compiled the hot path (we measure optimized machine code, not the cold
+  interpreter).
+- **Interleaved trials** — every round times LRU and W-TinyLFU back-to-back, and the ratio is the **median of
+  the per-round ratios** (paired). So machine drift within a round hits both equally and cancels in the ratio.
+- **Median of trials** (not mean) to shrug off the occasional GC pause.
+- **Selective `forceGc`** — forced for low-allocation bodies (reads, teardown) where a stray pause is pure noise;
+  *not* for allocation-heavy bodies (fill, churn) where GC is part of the real cost.
+- **Result sinks** so pure-read loops aren't deleted by dead-code elimination.
+- **Matched capacity & shared seeded workloads** so LRU and W-TinyLFU face identical conditions.
+- **Measured under `node`, never in-process under a test runner** — a transform (babel/esbuild) distorts both
+  the absolute ns *and* the ratio (a cheap op suffers proportionally more overhead). Measured under Jest
+  in-process, several ratios *inverted* (e.g. `fill` read 1.76x → 0.91x). That's why the self-executing spec
+  spawns a clean `node` child instead of measuring inside Jest — see *Why not measure under Jest*.

package/src/core/cache/wtinylfu/wtinylfuDecisions.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Pure decision predicates for the W-TinyLFU policy.
+ *
+ * No state: weights and frequencies in, verdicts out. This is the policy's "functional core" —
+ * what makes the cache W-TinyLFU rather than a generic cache — extracted so each decision can be
+ * unit-tested directly with plain numbers, without observing element placement.
+ */
+/**
+ * Total weight Main (Trial + Protected) is allowed to hold.
+ * @param {number} maxWeight total cache weight budget
+ * @param {number} windowMaxWeight Window region's weight cap
+ * @returns {number}
+ */
+export function mainCapacity(maxWeight: number, windowMaxWeight: number): number;
+/**
+ * Does Main exceed its budget once `extraWeight` is added? Counts current Trial occupancy.
+ * @param {number} trialWeight
+ * @param {number} protectedWeight
+ * @param {number} extraWeight
+ * @param {number} mainCap
+ * @returns {boolean}
+ */
+export function exceedsMainWeight(trialWeight: number, protectedWeight: number, extraWeight: number, mainCap: number): boolean;
+/**
+ * Could `weight` never fit in Main, even with Trial fully evicted? Only Protected's live weight is
+ * the immovable floor (Trial is fully evictable). Distinct from {@link exceedsMainWeight}, which
+ * counts current Trial occupancy.
+ * @param {number} protectedWeight
+ * @param {number} weight
+ * @param {number} mainCap
+ * @returns {boolean}
+ */
+export function cannotFitMain(protectedWeight: number, weight: number, mainCap: number): boolean;
+/**
+ * Is `weight` too big to ever fit in Window, even when empty? (ceiling test, ignores occupancy)
+ * @param {number} weight
+ * @param {number} windowMaxWeight
+ * @returns {boolean}
+ */
+export function tooBigForWindow(weight: number, windowMaxWeight: number): boolean;
+/**
+ * Decide where a new element of `weight` goes on admission:
+ *  - REJECT: can never fit Main, even with Trial fully evicted;
+ *  - TRIAL:  fits Main but too big for Window, so goes straight to the admission duel;
+ *  - WINDOW: normal case.
+ * @param {number} weight
+ * @param {number} protectedWeight  live Protected occupancy (the immovable floor)
+ * @param {number} windowMaxWeight  Window's weight cap
+ * @param {number} mainCap          Main's weight budget
+ * @returns {number} one of {@link AdmissionRoute}
+ */
+export function classifyAdmission(weight: number, protectedWeight: number, windowMaxWeight: number, mainCap: number): number;
+/**
+ * Does the admission candidate beat the victim on frequency? Ties favour the incumbent (strict >).
+ * @param {number} candidateFrequency
+ * @param {number} victimFrequency
+ * @returns {boolean}
+ */
+export function winsAdmissionDuel(candidateFrequency: number, victimFrequency: number): boolean;
+/**
+ * Should a Trial element be promoted to Protected? It must be hot enough AND fit Protected — an
+ * element with weight > protectedMaxWeight is a valid Trial resident that stays pinned (never
+ * promotable). So this is the full Trial→Protected transition gate.
+ * @param {number} frequency
+ * @param {number} promotionThreshold
+ * @param {number} weight
+ * @param {number} protectedMaxWeight
+ * @returns {boolean}
+ */
+export function shouldPromoteToProtected(frequency: number, promotionThreshold: number, weight: number, protectedMaxWeight: number): boolean;
+/**
+ * Where a newly-admitted element should be routed.
+ */
+export type AdmissionRoute = number;
+export namespace AdmissionRoute {
+    let REJECT: number;
+    let WINDOW: number;
+    let TRIAL: number;
+}
+//# sourceMappingURL=wtinylfuDecisions.d.ts.map

package/src/core/cache/wtinylfu/wtinylfuDecisions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wtinylfuDecisions.d.ts","sourceRoot":"","sources":["../../../../../src/core/cache/wtinylfu/wtinylfuDecisions.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,wCAJW,MAAM,mBACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;GAOG;AACH,+CANW,MAAM,mBACN,MAAM,eACN,MAAM,WACN,MAAM,GACJ,OAAO,CAKnB;AAED;;;;;;;;GAQG;AACH,+CALW,MAAM,UACN,MAAM,WACN,MAAM,GACJ,OAAO,CAKnB;AAED;;;;;GAKG;AACH,wCAJW,MAAM,mBACN,MAAM,GACJ,OAAO,CAInB;AAQD;;;;;;;;;;GAUG;AACH,0CANW,MAAM,mBACN,MAAM,mBACN,MAAM,WACN,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;GAKG;AACH,sDAJW,MAAM,mBACN,MAAM,GACJ,OAAO,CAInB;AAED;;;;;;;;;GASG;AACH,oDANW,MAAM,sBACN,MAAM,UACN,MAAM,sBACN,MAAM,GACJ,OAAO,CAKnB;;;;6BA5CS,MAAM"}

package/src/core/cache/wtinylfu/wtinylfuDecisions.js

@@ -0,0 +1,102 @@
+/**
+ * Pure decision predicates for the W-TinyLFU policy.
+ *
+ * No state: weights and frequencies in, verdicts out. This is the policy's "functional core" —
+ * what makes the cache W-TinyLFU rather than a generic cache — extracted so each decision can be
+ * unit-tested directly with plain numbers, without observing element placement.
+ */
+
+/**
+ * Total weight Main (Trial + Protected) is allowed to hold.
+ * @param {number} maxWeight total cache weight budget
+ * @param {number} windowMaxWeight Window region's weight cap
+ * @returns {number}
+ */
+export function mainCapacity(maxWeight, windowMaxWeight) {
+    return maxWeight - windowMaxWeight;
+}
+
+/**
+ * Does Main exceed its budget once `extraWeight` is added? Counts current Trial occupancy.
+ * @param {number} trialWeight
+ * @param {number} protectedWeight
+ * @param {number} extraWeight
+ * @param {number} mainCap
+ * @returns {boolean}
+ */
+export function exceedsMainWeight(trialWeight, protectedWeight, extraWeight, mainCap) {
+    const projectedMainWeight = trialWeight + protectedWeight + extraWeight
+    return projectedMainWeight > mainCap;
+}
+
+/**
+ * Could `weight` never fit in Main, even with Trial fully evicted? Only Protected's live weight is
+ * the immovable floor (Trial is fully evictable). Distinct from {@link exceedsMainWeight}, which
+ * counts current Trial occupancy.
+ * @param {number} protectedWeight
+ * @param {number} weight
+ * @param {number} mainCap
+ * @returns {boolean}
+ */
+export function cannotFitMain(protectedWeight, weight, mainCap) {
+    const requiredMainWeight = protectedWeight + weight;
+    return requiredMainWeight > mainCap;
+}
+
+/**
+ * Is `weight` too big to ever fit in Window, even when empty? (ceiling test, ignores occupancy)
+ * @param {number} weight
+ * @param {number} windowMaxWeight
+ * @returns {boolean}
+ */
+export function tooBigForWindow(weight, windowMaxWeight) {
+    return weight > windowMaxWeight;
+}
+
+/**
+ * Where a newly-admitted element should be routed.
+ * @enum {number}
+ */
+export const AdmissionRoute = { REJECT: 0, WINDOW: 1, TRIAL: 2 };
+
+/**
+ * Decide where a new element of `weight` goes on admission:
+ *  - REJECT: can never fit Main, even with Trial fully evicted;
+ *  - TRIAL:  fits Main but too big for Window, so goes straight to the admission duel;
+ *  - WINDOW: normal case.
+ * @param {number} weight
+ * @param {number} protectedWeight  live Protected occupancy (the immovable floor)
+ * @param {number} windowMaxWeight  Window's weight cap
+ * @param {number} mainCap          Main's weight budget
+ * @returns {number} one of {@link AdmissionRoute}
+ */
+export function classifyAdmission(weight, protectedWeight, windowMaxWeight, mainCap) {
+    if (cannotFitMain(protectedWeight, weight, mainCap)) return AdmissionRoute.REJECT;
+    if (tooBigForWindow(weight, windowMaxWeight))        return AdmissionRoute.TRIAL;
+    return AdmissionRoute.WINDOW;
+}
+
+/**
+ * Does the admission candidate beat the victim on frequency? Ties favour the incumbent (strict >).
+ * @param {number} candidateFrequency
+ * @param {number} victimFrequency
+ * @returns {boolean}
+ */
+export function winsAdmissionDuel(candidateFrequency, victimFrequency) {
+    return candidateFrequency > victimFrequency;
+}
+
+/**
+ * Should a Trial element be promoted to Protected? It must be hot enough AND fit Protected — an
+ * element with weight > protectedMaxWeight is a valid Trial resident that stays pinned (never
+ * promotable). So this is the full Trial→Protected transition gate.
+ * @param {number} frequency
+ * @param {number} promotionThreshold
+ * @param {number} weight
+ * @param {number} protectedMaxWeight
+ * @returns {boolean}
+ */
+export function shouldPromoteToProtected(frequency, promotionThreshold, weight, protectedMaxWeight) {
+    return (frequency > promotionThreshold)
+        && (weight <= protectedMaxWeight);
+}

package/src/core/collection/RingBuffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RingBuffer.d.ts","sourceRoot":"","sources":["../../../../src/core/collection/RingBuffer.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH;IACI;;OAEG;IACH,kBAFW,MAAM,EAoChB;IA7BG;;;OAGG;IACH,MAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,MAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,MAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,OAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,MAFU,CAAC,EAAE,CAEc;IAG/B;;;OAGG;IACH,iBAFW,MAAM,QAwBhB;IAED;;;OAGG;IACH,WAFY,CAAC,CAIZ;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACJ,CAAC,CAYb;IAED,cAIC;IAED;;;OAGG;IACH,cAFW,CAAC,QAuBX;IAED;;;OAGG;IACH,SAFa,CAAC,GAAC,SAAS,CAcvB;IAED;;;OAGG;IACH,4BAFW,MAAM,QA8BhB;IAED;;;;;OAKG;IACH,2BAJoB,CAAC,KAAE,OAAO,kBAEjB,CAAC,GAAC,SAAS,CAsBvB;IAED;;;;OAIG;IACH,wBAHoB,CAAC,+BAmBpB;IAED;;;;OAIG;IACH,gBAHW,CAAC,GACC,OAAO,CAKnB;CACJ"}
+{"version":3,"file":"RingBuffer.d.ts","sourceRoot":"","sources":["../../../../src/core/collection/RingBuffer.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH;IACI;;OAEG;IACH,kBAFW,MAAM,EAoChB;IA7BG;;;OAGG;IACH,MAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,MAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,MAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,OAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,MAFU,CAAC,EAAE,CAEc;IAG/B;;;OAGG;IACH,iBAFW,MAAM,QAwBhB;IAED;;;OAGG;IACH,WAFY,CAAC,CAKZ;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACJ,CAAC,CAYb;IAED,cAIC;IAED;;;OAGG;IACH,cAFW,CAAC,QAuBX;IAED;;;OAGG;IACH,SAFa,CAAC,GAAC,SAAS,CAcvB;IAED;;;OAGG;IACH,4BAFW,MAAM,QA8BhB;IAED;;;;;OAKG;IACH,2BAJoB,CAAC,KAAE,OAAO,kBAEjB,CAAC,GAAC,SAAS,CAsBvB;IAED;;;;OAIG;IACH,wBAHoB,CAAC,+BAmBpB;IAED;;;;OAIG;IACH,gBAHW,CAAC,GACC,OAAO,CAgBnB;CACJ"}

package/src/core/collection/RingBuffer.js

@@ -80,7 +80,8 @@ export class RingBuffer {
      * @return {V}
      */
     getHead() {
-        return this.data[this.head - 1];
+        // delegate so the head-1 index wraps correctly when the write cursor sits at slot 0
+        return this.getFromHead(0);
     }
 
     /**
@@ -242,7 +243,18 @@ export class RingBuffer {
      * @returns {boolean}
      */
     contains(value) {
-        // TODO do a bounds check
-        return this.data.indexOf(value) !== -1;
+        // scan only live slots — a shift()-ed element is still physically present in the backing array
+        const count = this.count;
+        const size = this.size;
+        const tail = this.tail;
+        const data = this.data;
+
+        for (let i = 0; i < count; i++) {
+            if (data[(tail + i) % size] === value) {
+                return true;
+            }
+        }
+
+        return false;
     }
 }

package/src/core/collection/map/HashMap.d.ts

@@ -79,7 +79,7 @@ export class HashMap<K, V> {
      */
     private __bin_count_mask;
     /**
-     * How full the table can get before number of buckets is increased
+     * Fraction of the entries slab allowed live before it grows instead of compacting
      * @type {number}
      * @private
      */

package/src/core/collection/map/HashMap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HashMap.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/map/HashMap.js"],"names":[],"mappings":"AA+GA;;;;;;;;;GASG;AACH;IAsFI;;;;;;OAMG;IACH,4FALuB,MAAM,EAsC5B;IA7HD;;;;;OAKG;IACH,eAAoB;IAEpB;;;;OAIG;IACH,kBAAyB;IAEzB;;;;OAIG;IACH,wBAAoB;IAEpB;;;;OAIG;IACH,wBAAoB;IAEpB;;;;OAIG;IACH,eAAW;IAEX;;;;OAIG;IACH,oBAAgB;IAEhB;;;;OAIG;IACH,kCAA8B;IAE9B;;;;OAIG;IACH,iCAA6B;IAE7B;;;;OAIG;IACH,qCAAiC;IAEjC;;;;OAIG;IACH,yBAAqB;IAErB;;;;OAIG;IACH,sBAAoC;IAEpC;;;;OAIG;IACH,kBAAc;IAwBV;;;;;OAKG;IACH,iCAAsC;IACtC;;;;;OAKG;IACH,qCAA8C;IAOlD;;;OAGG;IACH,mBAEC;IAED;;;OAGG;IACH,kBAFa,MAAM,CAIlB;IA2CD;;;;;OAKG;IACH,0BAUC;IAuGD;;;;OAIG;IACH,SAHW,CAAC,SACD,CAAC,QA0EX;IAED;;;;OAIG;IACH,SAHW,CAAC,GACC,CAAC,GAAC,SAAS,CA+BvB;IAED;;;;;;;;OAQG;IACH,kBALW,CAAC,kBACQ,CAAC,KAAE,CAAC,0BAEZ,CAAC,CAgBZ;IAED;;;;;OAKG;IACH,cAJW,CAAC,SACD,CAAC,GACA,CAAC,CAaZ;IAwBD;;;;OAIG;IACH,YAHW,CAAC,GACC,OAAO,CA+CnB;IAED;;;;;OAKG;IACH,4CAFa,OAAO,CA+BnB;IAOD;;OAEG;IACH,gBA0DC;IAmBD,2CA0BC;IAED;;;;OAIG;IACH,SAHW,CAAC,GACC,OAAO,CAInB;IAED;;OAEG;IACH,cA6BC;IA+BD;;;OAGG;IACH,WAFa,SAAS,CAAC,CAAC,EAAC,CAAC,CAAC,CAAC,CAM3B;IAED;;;OAGG;IACH,UAFa,SAAS,CAAC,CAAC,CAOvB;IAED;;;OAGG;IACH,QAFa,SAAS,CAAC,CAAC,CAMvB;IA1DD,yDA2BC;;CAgCJ"}
+{"version":3,"file":"HashMap.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/map/HashMap.js"],"names":[],"mappings":"AA+GA;;;;;;;;;GASG;AACH;IAsFI;;;;;;OAMG;IACH,4FALuB,MAAM,EAsC5B;IA7HD;;;;;OAKG;IACH,eAAoB;IAEpB;;;;OAIG;IACH,kBAAyB;IAEzB;;;;OAIG;IACH,wBAAoB;IAEpB;;;;OAIG;IACH,wBAAoB;IAEpB;;;;OAIG;IACH,eAAW;IAEX;;;;OAIG;IACH,oBAAgB;IAEhB;;;;OAIG;IACH,kCAA8B;IAE9B;;;;OAIG;IACH,iCAA6B;IAE7B;;;;OAIG;IACH,qCAAiC;IAEjC;;;;OAIG;IACH,yBAAqB;IAErB;;;;OAIG;IACH,sBAAoC;IAEpC;;;;OAIG;IACH,kBAAc;IAwBV;;;;;OAKG;IACH,iCAAsC;IACtC;;;;;OAKG;IACH,qCAA8C;IAOlD;;;OAGG;IACH,mBAEC;IAED;;;OAGG;IACH,kBAFa,MAAM,CAIlB;IA2CD;;;;;OAKG;IACH,0BAUC;IAsGD;;;;OAIG;IACH,SAHW,CAAC,SACD,CAAC,QA+DX;IAED;;;;OAIG;IACH,SAHW,CAAC,GACC,CAAC,GAAC,SAAS,CA+BvB;IAED;;;;;;;;OAQG;IACH,kBALW,CAAC,kBACQ,CAAC,KAAE,CAAC,0BAEZ,CAAC,CAgBZ;IAED;;;;;OAKG;IACH,cAJW,CAAC,SACD,CAAC,GACA,CAAC,CAaZ;IAwBD;;;;OAIG;IACH,YAHW,CAAC,GACC,OAAO,CA+CnB;IAED;;;;;OAKG;IACH,4CAFa,OAAO,CA+BnB;IAOD;;OAEG;IACH,gBA0DC;IAmBD,2CA0BC;IAED;;;;OAIG;IACH,SAHW,CAAC,GACC,OAAO,CAInB;IAED;;OAEG;IACH,cA6BC;IA+BD;;;OAGG;IACH,WAFa,SAAS,CAAC,CAAC,EAAC,CAAC,CAAC,CAAC,CAM3B;IAED;;;OAGG;IACH,UAFa,SAAS,CAAC,CAAC,CAOvB;IAED;;;OAGG;IACH,QAFa,SAAS,CAAC,CAAC,CAMvB;IA1DD,yDA2BC;;CAgCJ"}

package/src/core/collection/map/HashMap.js

@@ -192,7 +192,7 @@ export class HashMap {
     __bin_count_mask = 0;
 
     /**
-     * How full the table can get before number of buckets is increased
+     * Fraction of the entries slab allowed live before it grows instead of compacting
      * @type {number}
      * @private
      */
@@ -413,12 +413,11 @@ export class HashMap {
             return;
         }
 
-        if (this.__size === this.__entries_allocated_count) {
-            // used up all allocated entries
-            // bin count must always be larger than end of the entries table
+        if (this.__size >= this.__entries_allocated_count * this.__load_factor) {
+            // slab mostly live — grow for headroom (compacting would reclaim too little and thrash)
             this.#grow();
         } else {
-            // exhausted entries array, perform compaction
+            // dead entries to reclaim — compact in place
             this.rebuild();
         }
     }
@@ -488,18 +487,7 @@ export class HashMap {
 
         }
 
-        const old_size = this.__size;
-        const new_size = old_size + 1;
-        this.__size = new_size;
-
-        // compute actual current load
-        const bucket_count = this.__bin_count;
-        const load = new_size / bucket_count;
-
-        if (load > this.__load_factor) {
-            // current load is too high, increase table size
-            this.#grow();
-        }
+        this.__size++;
     }
 
     /**

package/src/core/geom/2d/line/line2_compute_segment_point_distance_sqr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"line2_compute_segment_point_distance_sqr.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/line/line2_compute_segment_point_distance_sqr.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,6DAPW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,UA4BhB"}
+{"version":3,"file":"line2_compute_segment_point_distance_sqr.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/line/line2_compute_segment_point_distance_sqr.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,6DAPW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,UAiChB"}

package/src/core/geom/2d/line/line2_compute_segment_point_distance_sqr.js

@@ -26,6 +26,11 @@ export function line2_compute_segment_point_distance_sqr(
     //
     const d2 = line_delta_x * line_delta_x + line_delta_y * line_delta_y;
 
+    if (d2 === 0) {
+        // line is a point
+        return v2_distance_sqr(px, py, x0, y0);
+    }
+
     const d3 = line_delta_x * sp0_x + line_delta_y * sp0_y;
 
     const t = clamp01(d3 / d2);

package/src/core/geom/ConicRay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConicRay.d.ts","sourceRoot":"","sources":["../../../../src/core/geom/ConicRay.js"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH;IAgLI;;;;;;;OAOG;IACH,sBANW,MAAM,KACN,MAAM,KACN,MAAM,cACN,MAAM,GACJ,QAAQ,CAkBpB;IAtMD;;;;OAIG;IACH,oBAFU,OAAO,CAEgB;IAEjC;;;;OAIG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;MAKC;IAED,0BAGC;IAED;;;OAGG;IACH,2CAGC;IAED;;;OAGG;IACH,6CAMC;IAED;;;;OAIG;IACH,cAHW,QAAQ,GACN,OAAO,CAMnB;IAED;;;;;OAKG;IACH,qBAJW,QAAQ,cACR,MAAM,GACJ,OAAO,CAKnB;IAED;;;OAGG;IACH,QAFY,MAAM,CAOjB;IAED;;;OAGG;IACH,YAFW,QAAQ,QAKlB;IAED;;;;OAIG;IACH,4BAHW,OAAO,GACL,OAAO,CAMnB;IAED;;;;;OAKG;IACH,gDAFW,OAAO,QAoEjB;IA6BL;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAN5B;;kBAUS,MAAM;;oBA7NI,cAAc"}
+{"version":3,"file":"ConicRay.d.ts","sourceRoot":"","sources":["../../../../src/core/geom/ConicRay.js"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH;IAuLI;;;;;;;OAOG;IACH,sBANW,MAAM,KACN,MAAM,KACN,MAAM,cACN,MAAM,GACJ,QAAQ,CAkBpB;IA7MD;;;;OAIG;IACH,oBAFU,OAAO,CAEgB;IAEjC;;;;OAIG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;MAKC;IAED,0BAGC;IAED;;;OAGG;IACH,2CAGC;IAED;;;OAGG;IACH,6CAMC;IAED;;;;OAIG;IACH,cAHW,QAAQ,GACN,OAAO,CAMnB;IAED;;;;;OAKG;IACH,qBAJW,QAAQ,cACR,MAAM,GACJ,OAAO,CAKnB;IAED;;;OAGG;IACH,QAFY,MAAM,CAOjB;IAED;;;OAGG;IACH,YAFW,QAAQ,QAKlB;IAED;;;;OAIG;IACH,4BAHW,OAAO,GACL,OAAO,CAMnB;IAED;;;;;OAKG;IACH,gDAFW,OAAO,QA2EjB;IA6BL;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAN5B;;kBAUS,MAAM;;oBApOI,cAAc"}

package/src/core/geom/ConicRay.js

@@ -153,6 +153,13 @@ export class ConicRay {
             return;
         }
 
+        // The antipode (0,0,-1) is the singularity of the k = 1/(1+dZ) rotation below (dZ === -1 -> k = Infinity).
+        // Map the cap onto the south pole with a 180 degree rotation about the X axis: (x, y, z) -> (x, -y, -z).
+        if (direction._equals(0, 0, -1)) {
+            result.set(x, -y, -z);
+            return;
+        }
+
         assert.ok(direction.isNormalized(), 'direction vector must be normalized');
 
         // Find the rotation axis `u` and rotation angle `rot` [1]
@@ -168,8 +175,8 @@ export class ConicRay {
 
         //write matrix
         const c = dZ;
-        // NOTE: singular at dZ === -1 (the antipode). The (0,0,1) case is handled by the early return above and
-        // cone sampling here keeps dZ > -1.
+        // Singular at dZ === -1 (the antipode); both the (0,0,1) and (0,0,-1) poles are handled by the early
+        // returns above, so dZ is strictly in (-1, 1) here.
         const k = 1 / (1 + dZ);
         const tx = -k * dY;
         const ty = k * dX;

package/src/core/geom/Quaternion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Quaternion.d.ts","sourceRoot":"","sources":["../../../../src/core/geom/Quaternion.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Quaternion.d.ts","sourceRoot":"","sources":["../../../../src/core/geom/Quaternion.js"],"names":[],"mappings":"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"}

package/src/core/geom/Quaternion.js

@@ -687,7 +687,9 @@ export class Quaternion extends Float64Array {
 
         const r21 = 2 * (x * z + y * w);
 
-        const theta = Math.asin(r21);
+        // r21 is mathematically in [-1, 1]; floating-point rounding can push it just past the bound at
+        // gimbal lock, where Math.asin would return NaN. Clamp removes only the overshoot.
+        const theta = Math.asin(clamp(r21, -1, 1));
 
         const r11 = 2 * (z * w - x * y);
         const r12 = w2 + x2 - y2 - z2;
@@ -721,7 +723,8 @@ export class Quaternion extends Float64Array {
             r32 = w2 - x2 + y2 - z2;
 
         const psi = Math.atan2(r31, r32);
-        const theta = Math.asin(r21);
+        // clamp against floating-point overshoot at gimbal lock (see toEulerAnglesXYZ)
+        const theta = Math.asin(clamp(r21, -1, 1));
         const phi = Math.atan2(r11, r12);
 
         // result.set(psi, theta, phi);
@@ -752,7 +755,8 @@ export class Quaternion extends Float64Array {
             r32 = ww - xx - yy + zz;
 
         const psi = Math.atan2(r31, r32);
-        const theta = Math.asin(r21);
+        // clamp against floating-point overshoot at gimbal lock (see toEulerAnglesXYZ)
+        const theta = Math.asin(clamp(r21, -1, 1));
         const phi = Math.atan2(r11, r12);
 
         result.set(psi, theta, phi);

package/src/core/math/build_gaussian_kernel_1d.d.ts

@@ -1,8 +1,8 @@
 /**
- *
+ * Build a normalized 1-dimensional gaussian kernel, taps sum to 1.
  * @param {Float32Array} kernel
  * @param {number} sample_count
- * @param {number} sigma
+ * @param {number} sigma standard deviation, must be greater than 0. A sigma of 0 makes every tap `NaN`, as the centre tap evaluates `exp(-0/0)`
  */
 export function build_gaussian_kernel_1d(kernel: Float32Array, sample_count: number, sigma: number): void;
 //# sourceMappingURL=build_gaussian_kernel_1d.d.ts.map

package/src/core/math/build_gaussian_kernel_1d.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build_gaussian_kernel_1d.d.ts","sourceRoot":"","sources":["../../../../src/core/math/build_gaussian_kernel_1d.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,iDAJW,YAAY,gBACZ,MAAM,SACN,MAAM,QAmBhB"}
+{"version":3,"file":"build_gaussian_kernel_1d.d.ts","sourceRoot":"","sources":["../../../../src/core/math/build_gaussian_kernel_1d.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,iDAJW,YAAY,gBACZ,MAAM,SACN,MAAM,QAoBhB"}