@zakkster/lite-logn 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,120 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-20
+
+### Added
+
+- **MinMaxHeap** -- the seventh member and the family's DOUBLE-ENDED priority queue
+  (DEPQ): a single array-embedded binary heap whose levels ALTERNATE min / max (Atkinson,
+  Sack, Santoro & Strothotte 1986). Even depth (the root is depth 0) is a MIN level, odd
+  depth a MAX level, so the global minimum sits at the root and the global maximum is the
+  LARGER of the root's up-to-two children. `peekMin` / `peekMax` / `peekMinKey` /
+  `peekMaxKey` are O(1); `push` / `popMin` / `popMax` are all WORST-case O(log n) from that
+  ONE heap (no second heap, no paired-heap correspondence). Surface: `push(id, key)` /
+  `popMin` / `popMax` / `peekMin` / `peekMax` / `peekMinKey` / `peekMaxKey` / `clear` /
+  `forEach` / `[Symbol.iterator]`, and `size` / `capacity` getters, plus a Floyd O(n)
+  `MinMaxHeap.build(ids, keys, capacity)` (deepest-first, level-aware sift-down). Keys are
+  finite numbers (typeof-guarded before coercion -- Symbol / BigInt / NaN / +-Infinity fail
+  closed with a `[lite-logn]` throw, key checked FIRST, then the id, then a full heap).
+- **id + key payload, NON-addressable (the asymmetry vs BinaryHeap).** Two parallel
+  pointer-free typed-array columns (`_id` Uint32Array + `_key` Float64Array), the BinaryHeap
+  id+key idiom -- but with NO `_pos` reverse map, and therefore deliberately NO `changeKey` /
+  `remove`. The id is an OPAQUE Uint32 payload (NOT unique; the full [0, 2^32) domain, wider
+  than BinaryHeap's [0, capacity)). A DEPQ's job is the two extremes; addressability is the
+  separable concern BinaryHeap already carries. There is also NO `kind` argument / getter (a
+  DEPQ has both ends; a kind getter would be a lie).
+- **Classic one-element-per-node min-max heap only.** The interval-heap DEPQ (two elements
+  per node) is a deliberately deferred alternative -- named, never silently omitted (see
+  `decisions/0009-minmaxheap.md` and "What this is not").
+- **Level parity, computed zero-alloc.** Slot i is a MIN level iff
+  `((31 - Math.clz32(i + 1)) & 1) === 0`. The sifts are hole-punching (one write per level,
+  only local scalar temporaries): `push` compares to the parent to pick the own-level vs
+  other-level chain then bubbles by grandparents; `popMin` / `popMax` trickle down over the
+  up-to-six descendants (children + grandchildren), bound-checking every grandchild index
+  against the live size (the classic min-max off-by-one, verified at n = 1, 2, 3, 4).
+
+### Verified
+
+- **Witness (D-M5).** `MinMaxHeap.popMin` is the gated O(log n) witness op (the full-height
+  level-aware trickle-down). It inherits the FROZEN family R^2 floor 0.958 and calibrates its
+  OWN slope band by the shared ADR-0004 method: median-of-15 popMin fit-runs = 10.30 ns/level
+  (runs spanned 9.38..10.59, R^2 0.9897..0.9991), band = median x `[0.6, 1.4]` = `[6.18, 14.42]`.
+  A DEPQ whose push / popMin / popMax are ALL worst-case, so there is NO max-single-op line.
+  The O(n) foil is a linear min-scan-and-splice extract-min (R^2 ~ 0.77, OFF the line).
+- **Zero-GC.** `node --expose-gc test/torture.mjs` -- 0 B/op on the popMin / popMax / mixed
+  push+popMin+popMax churn and the peek read lanes, gc major = 0, the deliberately-allocating
+  control lane still non-zero (teeth), arrayBuffers do not grow across fill/clear soak cycles.
+  `npm run test:perf` -- 0 scavenges + `grows === 0` on every MinMaxHeap scenario.
+
+### Notes
+
+- `LogN.js` gains `MMH_MAX_CAPACITY` (`0x7FFFFFFF`) + the `MinMaxHeap` class, appended after
+  Scapegoat; the prior six classes stay BYTE-IDENTICAL (only the `VERSION` const changes above
+  the append point). Version bumped to 0.7.0 across `package.json`, `LogN.js`, and `llms.txt`.
+
+## [0.6.0] - 2026-09-20
+
+### Added
+
+- **Scapegoat** -- the sixth member and the family's DETERMINISTIC balanced BST, the
+  honest PAIR to Treap: a weight-balanced binary search tree that is ALSO an
+  order-statistic tree (an AUGMENTED ordered map key -> value). Where a treap randomizes
+  its shape to be balanced IN EXPECTATION, a scapegoat keeps a hard WORST-CASE height
+  bound -- so `get` is O(log n) WORST-case (never merely expected) -- and pays for it with
+  AMORTIZED O(log n) `set` / `delete`, where an occasional subtree rebuild absorbs the
+  imbalance. A subtree-size column `_size` (maintained in the same pass as every link
+  rewrite and every rebuild) adds O(log n) order statistics. Surface: `get` / `has` /
+  `set` (updates the value in place on an existing key) / `delete` (idempotent) /
+  `rank(x)` (count of keys STRICTLY less than x) / `select(k)` (the k-th smallest key,
+  0-based) / `successor` (strictly greater) / `predecessor` (strictly less) /
+  `rangeIter(lo, hi)` (a VERSION-STAMPED iterator over `[lo, hi]` inclusive, ascending;
+  `+-Infinity` bounds allowed, structural OR value mutation mid-iteration throws) /
+  `forEach` / `clear`, and `size` / `capacity` / `alpha` getters. Keys and values are
+  finite numbers (typeof-guarded before coercion -- Symbol / BigInt / NaN / +-Infinity
+  fail closed with a `[lite-logn]` throw).
+- **NO priorities, NO RNG (fully deterministic).** Unlike Treap, Scapegoat draws no random
+  priority and uses no LCG / `Math.random` anywhere: the tree shape is a deterministic
+  function of the insert / delete order. `alpha` (the weight-balance factor) is validated
+  to the OPEN interval `(0.55, 0.75)` -- both ends throw -- and frozen at construction
+  (default `2/3`); the alpha-derived depth constant `_invAlpha = 1/alpha` is ctor-cached so
+  the hot insert path uses no per-op `Math.log` (the depth test is `_invAlpha^d > size`).
+- **Zero-GC rebuild over preallocated scratch (the load-bearing design call).** No fresh
+  array per rebuild: ONE `_flat` (`Uint32Array(capacity)`) + ONE `_stack`
+  (`Uint32Array(capacity+1)`) are allocated at construction and reused every rebuild. An
+  ITERATIVE, Morris-free in-order flatten (via `_stack`) writes sorted slot indices into
+  `_flat`; a bounded log-depth balanced rebuild re-links `_left` / `_right` / `_size` on
+  the native call stack. Proven 0 B/op even under a rebuild-HEAVY ascending-insert trace by
+  the torture gate and a dedicated PerfGate scavenge-clean scenario
+  (decisions/0008-scapegoat.md).
+- **Third bind of the shared NodePool.** Nodes are slot INDICES in five flat columns
+  (`_key` / `_value` Float64; `_left` / `_right` / `_size` Uint32, `NIL = 0`) over the SAME
+  private free-list (`NodePool`) SkipList and Treap ship -- design-parity, not a fork or a
+  runtime dep. The conservation invariant `activeSlots + freeListLength === capacity` holds
+  after every op, INCLUDING across rebuild storms. `SG_MAX_CAPACITY = 0x7FFFFFFF` (2^31 - 1:
+  slot indices + subtree counts fit a `Uint32`).
+- **The documented asymmetry vs Treap: NO `split` / `merge`.** A scapegoat has no priority
+  heap to merge by, and an honest deterministic split/merge would be O(n) rebuilds
+  (forfeiting the sub-linear headline), so Scapegoat's surface is the ordered-map +
+  order-statistic core and split/merge are deliberately absent -- named on the public
+  surface (JSDoc + `llms.txt` + README + the `.d.ts`), not hidden.
+- **Witness: `Scapegoat.get` gated + the amortized-trace assertion.** `get` (a
+  deterministic weight-balanced descent) is gated ON the O(log n) line in its own
+  calibrated band `SCAPEGOAT_GET_SLOPE_LO/HI = [2.41, 5.63]` (median-of-15 slope 4.02
+  ns/level * [0.6, 1.4], MEDIAN-centered per ADR-0004), inheriting the FROZEN shared R^2
+  floor 0.958; its O(n) linear-scan foil leaves the line. The rebuild spike lives on the
+  AMORTIZED `set` path and is NEVER gated as a per-op line; instead the amortized-trace
+  assertion proves the amortization -- the cumulative ascending-insert (rebuild-heavy)
+  cost/op tracks a LOG curve (last/first ratio ~1.5x, gated `< 4x`) where a rebuild-less
+  BST would blow to ~64x. The five prior members' bands are UNTOUCHED.
+
+### Notes
+
+- Append-only: `LogN.js` gains `SG_MAX_CAPACITY` + the `Scapegoat` class after Treap;
+  BinaryHeap / Fenwick / SegmentTree / SkipList / Treap are BYTE-IDENTICAL (only the
+  `VERSION` const changes). The repo-only benchmark admits Scapegoat as the 6th SUBJECT
+  (matrix 5x8=40 -> 6x8=48, a new `OLOGN_AMORTIZED` honesty class for `set` / `delete`).
+
 ## [0.5.0] - 2026-09-20
 
 ### Added
@@ -250,7 +364,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   [`decisions/0003-pack.md`](./decisions/0003-pack.md) (D-07: `files[]` ships the
   six files only; `test/`, `benchmark/`, `decisions/`, `demo/` are repo-only).
 
-[Unreleased]: https://github.com/PeshoVurtoleta/lite-logn/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/PeshoVurtoleta/lite-logn/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/PeshoVurtoleta/lite-logn/compare/v0.6.0...v0.7.0
 [0.4.0]: https://github.com/PeshoVurtoleta/lite-logn/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/PeshoVurtoleta/lite-logn/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/PeshoVurtoleta/lite-logn/compare/v0.1.0...v0.2.0

package/LogN.d.ts

@@ -226,3 +226,106 @@ export class Treap {
      *  both. Non-Treap inputs, different arenas, or an overlapping range throw. */
     static merge(a: Treap, b: Treap): Treap;
 }
+
+/**
+ * A scapegoat tree: a DETERMINISTIC, weight-balanced BST that is also an order-statistic
+ * tree (an AUGMENTED ordered map key -> value) -- the honest pair to Treap. `get` is
+ * WORST-case O(log n) (a hard height bound, never merely expected); `set` / `delete` are
+ * AMORTIZED O(log n) (an occasional subtree rebuild absorbs the imbalance). A subtree-size
+ * column adds O(log n) rank / select. No priorities, no RNG: the shape is a deterministic
+ * function of the insert / delete order. Nodes are slot INDICES in flat typed-array columns
+ * over a private free-list, and every rebuild reuses ONE preallocated scratch buffer + index
+ * stack (no heap object, no fresh array per op). Keys and values are finite numbers (typeof-
+ * guarded before coercion; Symbol / BigInt / NaN / +-Infinity fail closed). set on an existing
+ * key updates the value in place. Fixed capacity: a full pool throws. Every hot op allocates
+ * zero bytes. There is deliberately NO split / merge (the treap's arena-sharing surgery has no
+ * honest deterministic O(log n) analogue here) -- the documented asymmetry vs Treap.
+ */
+export class Scapegoat {
+    /** @param capacity exact max live entries; integer in [1, 2^31-1].
+     *  @param alpha weight-balance factor in the OPEN interval (0.55, 0.75); default 2/3.
+     *         Both ends throw. Frozen after construction. */
+    constructor(capacity: number, alpha?: number);
+
+    /** Live entry count. */
+    readonly size: number;
+    /** The fixed capacity this tree was sized for. */
+    readonly capacity: number;
+    /** The frozen weight-balance factor. */
+    readonly alpha: number;
+
+    /** The value under key, or undefined if absent (no throw). Non-finite key throws. */
+    get(key: number): number | undefined;
+    /** True iff key is currently stored. Non-finite key throws. */
+    has(key: number): boolean;
+    /** Insert key -> value, or update the value in place if key exists. Non-finite
+     *  key/value throws; a full pool throws. */
+    set(key: number, value: number): this;
+    /** Remove key; true if it was present, false if absent (idempotent). Non-finite key throws. */
+    delete(key: number): boolean;
+    /** Count of stored keys strictly less than x (its rank), in [0, size]. Non-finite x throws. */
+    rank(x: number): number;
+    /** The k-th smallest key (0-based), or undefined if k is out of [0, size). Non-integer k throws. */
+    select(k: number): number | undefined;
+    /** The smallest key strictly greater than key, or undefined. Non-finite key throws. */
+    successor(key: number): number | undefined;
+    /** The largest key strictly less than key, or undefined. Non-finite key throws. */
+    predecessor(key: number): number | undefined;
+    /** A version-stamped iterator over keys in [lo, hi] inclusive, ascending. Bounds
+     *  may be +-Infinity (unbounded ends); NaN or lo > hi throws; mutation during
+     *  iteration throws. */
+    rangeIter(lo: number, hi: number): IterableIterator<number>;
+    /** Visit every (key, value) pair in ascending key order. */
+    forEach(fn: (key: number, value: number, tree: Scapegoat) => void): void;
+    /** Empty the tree, keeping capacity. */
+    clear(): this;
+}
+
+/**
+ * A min-max heap: a DOUBLE-ENDED priority queue (DEPQ) in ONE array-embedded binary heap
+ * whose levels ALTERNATE min / max (Atkinson et al. 1986). The minimum is the root; the
+ * maximum is the larger of the root's up-to-two children. peekMin / peekMax are O(1);
+ * push / popMin / popMax are O(log n) WORST-case. Two parallel typed-array columns (_key
+ * Float64, _id Uint32); the id is an OPAQUE Uint32 payload in [0, 2^32) (not unique, no
+ * reverse map), so there is deliberately NO changeKey / remove (the asymmetry vs
+ * BinaryHeap). Keys are finite numbers (typeof-guarded before coercion; Symbol / BigInt /
+ * NaN / +-Infinity fail closed). Fixed capacity: a full heap throws. Every hot op
+ * allocates zero bytes.
+ */
+export class MinMaxHeap {
+    /** @param capacity exact max live entries; integer in [1, 2^31-1]. */
+    constructor(capacity: number);
+
+    /** Live entry count. */
+    readonly size: number;
+    /** The fixed capacity this heap was sized for. */
+    readonly capacity: number;
+
+    /** Insert id with priority key. Throws on non-finite key, out-of-range id, or a full heap. */
+    push(id: number, key: number): void;
+    /** Remove and return the id at the minimum key, or undefined if empty. */
+    popMin(): number | undefined;
+    /** Remove and return the id at the maximum key, or undefined if empty. */
+    popMax(): number | undefined;
+    /** The id at the minimum key, or undefined if empty. */
+    peekMin(): number | undefined;
+    /** The id at the maximum key, or undefined if empty. */
+    peekMax(): number | undefined;
+    /** The minimum key, or undefined if empty. */
+    peekMinKey(): number | undefined;
+    /** The maximum key, or undefined if empty. */
+    peekMaxKey(): number | undefined;
+    /** Empty the heap, keeping capacity. */
+    clear(): void;
+    /** Visit every live (id, key) pair in unspecified (heap-array) order. */
+    forEach(fn: (id: number, key: number, heap: MinMaxHeap) => void): void;
+    /** Iterate live entity ids in unspecified (heap-array) order (NOT sorted). */
+    [Symbol.iterator](): IterableIterator<number>;
+
+    /** Floyd O(n) bulk build from parallel ids/keys arrays (level-aware sift-down). */
+    static build(
+        ids: ArrayLike<number>,
+        keys: ArrayLike<number>,
+        capacity: number,
+    ): MinMaxHeap;
+}