@zakkster/lite-logn 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,68 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [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

package/LogN.d.ts

@@ -226,3 +226,57 @@ 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;
+}

package/LogN.js

@@ -39,7 +39,7 @@
  */
 
 /** Package version. One of the three version sites (package.json / VERSION / llms.txt). */
-export const VERSION = '0.5.0';
+export const VERSION = '0.6.0';
 
 // --- members land here, append-only, one tree-shakeable class each -----------
 // BinaryHeap  (v0.1.0 session) -- indexed O(log n) min|max heap  (BELOW)
@@ -1983,3 +1983,516 @@ export class Treap {
         throw new RangeError('[lite-logn] Treap full (capacity ' + this._cap + ')');
     }
 }
+
+// Scapegoat (v0.6.0 session) -- a DETERMINISTIC weight-balanced augmented ordered map (BELOW).
+
+/**
+ * Max Scapegoat capacity: `0x7FFFFFFF` (2^31 - 1). Every node is addressed by a slot
+ * INDEX stored in `Uint32Array` link columns (`_left` / `_right`), each subtree count
+ * lives in a `Uint32Array` (`_size`), and the rebuild scratch (`_flat`) plus the
+ * flatten index-stack (`_stack`) are `Uint32Array` slot buffers; an index and a count
+ * must both fit an unsigned 32-bit word. `NIL = 0` reserves slot 0 as the empty-subtree
+ * sentinel, so live slots run [1, capacity]. The index / count arithmetic (Uint32 slot
+ * indices + `NIL = 0` + Uint32 subtree sizes), not the byte count, is the hard ceiling
+ * -- the same "the arithmetic caps it" reasoning as the array-embedded members.
+ */
+const SG_MAX_CAPACITY = 0x7FFFFFFF; // 2^31 - 1
+
+/**
+ * A SCAPEGOAT TREE: a DETERMINISTIC, weight-balanced BINARY SEARCH TREE that is ALSO an
+ * order-statistic tree (an AUGMENTED ordered map key -> value). It is the honest PAIR to
+ * Treap: where a treap randomizes its shape to be balanced IN EXPECTATION, a scapegoat
+ * keeps a hard WORST-CASE height bound (`get` is O(log n) worst-case, never merely
+ * expected) by paying for it with AMORTIZED O(log n) `set` / `delete` -- an occasional
+ * subtree rebuild absorbs the imbalance. No priorities, no RNG anywhere: the tree shape
+ * is a deterministic function of the insert / delete order. The trick that keeps it
+ * zero-GC is the SkipList / Treap one: nodes are slot INDICES in flat typed-array columns
+ * over the same private free-list (NodePool), never heap objects; AND the rebuild reuses
+ * ONE preallocated scratch buffer (`_flat`) + ONE preallocated index-stack (`_stack`),
+ * so even a rebuild-heavy trace allocates ZERO bytes after construction.
+ *
+ * Two invariants held at once:
+ *   - BST order on `_key` (an in-order walk is ascending by key); and
+ *   - alpha-WEIGHT-BALANCE: after every mutation the height stays <= log_{1/alpha}(n) + 1
+ *     (h_alpha), enforced by the dual trigger below. The augmentation is a third
+ *     invariant: `_size[x]` is the number of nodes in x's subtree, maintained in the SAME
+ *     pass as every link rewrite, so `rank` (keys < x) and `select` (k-th smallest key)
+ *     are O(log n) via subtree counts.
+ *
+ * The DUAL trigger (alpha frozen at construction, `alpha` in the OPEN interval
+ * (0.55, 0.75); default 2/3):
+ *   - `set`: descend recording the path, link the new leaf at depth d, then if the node
+ *     is "too deep" (d > h_alpha(size)) walk the recorded path back up to the SCAPEGOAT
+ *     -- the lowest ancestor whose child subtree exceeds `alpha` of its own size -- and
+ *     rebuild THAT subtree perfectly balanced. `_maxCount` tracks the high-water size.
+ *   - `delete`: remove the node (standard BST delete, `_size` fixed on the unwind), then
+ *     when `size < alpha * _maxCount` rebuild the WHOLE tree and reset `_maxCount = size`.
+ * The depth test uses NO per-op `Math.log`: since `_invAlpha = 1/alpha` is ctor-cached,
+ * `d > h_alpha(n)` (= `d > floor(_invLog * log2(n))`, `_invLog = 1/log2(1/alpha)`) is
+ * tested EXACTLY as `_invAlpha^d > n` (for integer d the strict `>` matches the floor),
+ * accumulated with one float multiply per path level -- only on the `set` path.
+ *
+ * ZERO-GC rebuild (the load-bearing design call, decisions/0008-scapegoat.md): NO fresh
+ * array per rebuild. `_flatten` walks the target subtree in-order ITERATIVELY (Morris-
+ * free) using the preallocated `_stack` index-column, writing sorted slot indices into
+ * the preallocated `_flat` buffer; `_buildBalanced` reads that sorted range and re-links
+ * `_left` / `_right` / `_size` via bounded native recursion whose depth is O(log
+ * subtree) <= ~31 (it produces a perfectly balanced subtree), so it runs on the native
+ * call stack, never the GC heap. Both are 0 B/op -- proven by the torture gate's rebuild-
+ * heavy ascending-insert lane. RECURSION: `delete` and `forEach` also recurse to a depth
+ * equal to the tree height, which is O(log n) worst-case here (the weight balance bounds
+ * it) -- strictly safer than Treap's expected bound, disclosed here + in the ADR, on the
+ * native stack, so still 0 B/op.
+ *
+ * Keys and values are FINITE numbers (typeof-guarded BEFORE coercion -- Symbol / BigInt /
+ * NaN / +-Infinity fail closed with a `[lite-logn]` throw). `set` on an EXISTING key
+ * updates its value in place (no new node, no rebuild). A missing / empty query returns
+ * `undefined` (never throws). Fixed capacity: a full pool throws, never silently drops.
+ * `rangeIter` is a VERSION-STAMPED iterator -- any structural OR value mutation mid-
+ * iteration throws `[lite-logn]` rather than yield stale data.
+ *
+ * Unlike Treap there is NO `split` / `merge`: those are the treap's arena-sharing set
+ * surgery (they rewire a randomized heap in place); 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 the surface is deliberately the ordered-map + order-
+ * statistic core (get / has / set / delete / rank / select / successor / predecessor /
+ * rangeIter / forEach / clear), documented in the ADR as the asymmetry vs Treap.
+ */
+export class Scapegoat {
+    /**
+     * @param {number} capacity  exact max live entries; integer in [1, 2^31-1].
+     * @param {number} [alpha]    weight-balance factor in the OPEN interval (0.55, 0.75)
+     *                            (both ends throw); default 2/3. Frozen after construction.
+     */
+    constructor(capacity, alpha = 2 / 3) {
+        // typeof guard BEFORE coercion (Number.isInteger is Symbol/BigInt-safe).
+        if (typeof capacity !== 'number' || !Number.isInteger(capacity) ||
+            capacity < 1 || capacity > SG_MAX_CAPACITY) {
+            throw new RangeError(
+                '[lite-logn] Scapegoat capacity must be an integer in [1, 2^31-1], got ' +
+                String(capacity));
+        }
+        // typeof guard BEFORE the range check; the interval is OPEN (both 0.55 and 0.75 throw).
+        if (typeof alpha !== 'number' || !Number.isFinite(alpha) || alpha <= 0.55 || alpha >= 0.75) {
+            throw new RangeError(
+                '[lite-logn] Scapegoat alpha must be a number in the open interval (0.55, 0.75), got ' +
+                String(alpha));
+        }
+        this._cap = capacity;                          // max live entries
+        this._key = new Float64Array(capacity + 1);    // key at each slot
+        this._value = new Float64Array(capacity + 1);  // value at each slot
+        this._left = new Uint32Array(capacity + 1);    // left child slot; NIL = 0
+        this._right = new Uint32Array(capacity + 1);   // right child slot; NIL = 0
+        this._size = new Uint32Array(capacity + 1);    // subtree node count; _size[0] = 0
+        this._pool = new NodePool(capacity);           // free-list over slots [1, capacity]
+        this._flat = new Uint32Array(capacity);        // rebuild scratch: sorted slot indices
+        this._stack = new Uint32Array(capacity + 1);   // flatten / descent index-stack (reused)
+        this._root = 0;                                // NIL == empty tree
+        this._maxCount = 0;                            // high-water size since the last full rebuild
+        this._version = 0;                             // iterator invalidation stamp
+        this._alpha = alpha;                           // ctor-frozen weight-balance factor
+        this._invAlpha = 1 / alpha;                    // ctor-cached: no per-op Math.log
+    }
+
+    /** Live entry count. O(1) (the root subtree count). */
+    get size() { return this._root === 0 ? 0 : this._size[this._root]; }
+
+    /** The fixed capacity this tree was sized for. O(1). */
+    get capacity() { return this._cap; }
+
+    /** The frozen weight-balance factor. O(1). */
+    get alpha() { return this._alpha; }
+
+    /**
+     * The value stored under `key`, or `undefined` if absent (never throws on a missing /
+     * empty query). O(log n) WORST-case: a plain BST descent over a weight-balanced tree.
+     * Fails closed on a non-number / non-finite key (typeof-guarded first).
+     * @param {number} key  a finite number
+     * @returns {number|undefined}
+     */
+    get(key) {
+        if (typeof key !== 'number' || !Number.isFinite(key)) return this._badKey(key);
+        const L = this._left, R = this._right, K = this._key;
+        let t = this._root;
+        while (t !== 0) {
+            if (key < K[t]) t = L[t];
+            else if (key > K[t]) t = R[t];
+            else return this._value[t];
+        }
+        return undefined;
+    }
+
+    /**
+     * True iff `key` is currently in the tree. O(log n) worst-case. Fails closed on a
+     * non-finite key (typeof-guarded first).
+     * @param {number} key  a finite number
+     * @returns {boolean}
+     */
+    has(key) {
+        if (typeof key !== 'number' || !Number.isFinite(key)) return this._badKey(key);
+        const L = this._left, R = this._right, K = this._key;
+        let t = this._root;
+        while (t !== 0) {
+            if (key < K[t]) t = L[t];
+            else if (key > K[t]) t = R[t];
+            else return true;
+        }
+        return false;
+    }
+
+    /**
+     * Insert `key -> value`, or UPDATE the value in place if `key` already exists (no new
+     * node, no rebuild). AMORTIZED O(log n): a descent recording the path, then (on
+     * insert) an amortized-cheap weight-balance check that occasionally rebuilds the
+     * scapegoat subtree. Fails closed: a non-finite key or value (typeof-guarded first),
+     * or a full pool, each throw `[lite-logn]` as a no-op.
+     * @param {number} key    a finite number
+     * @param {number} value  a finite number
+     * @returns {this}
+     */
+    set(key, value) {
+        if (typeof key !== 'number' || !Number.isFinite(key)) return this._badKey(key);
+        if (typeof value !== 'number' || !Number.isFinite(value)) return this._badValue(value);
+        const K = this._key, L = this._left, R = this._right, S = this._size, stk = this._stack;
+        let t = this._root, sp = 0;
+        while (t !== 0) { // descend, recording the path; update in place if present
+            stk[sp++] = t;
+            if (key < K[t]) t = L[t];
+            else if (key > K[t]) t = R[t];
+            else { this._value[t] = value; this._version = (this._version + 1) | 0; return this; }
+        }
+        const slot = this._pool.alloc();
+        if (slot === 0) return this._full();
+        K[slot] = key; this._value[slot] = value; L[slot] = 0; R[slot] = 0; S[slot] = 1;
+        if (sp === 0) this._root = slot;             // first node
+        else { const p = stk[sp - 1]; if (key < K[p]) L[p] = slot; else R[p] = slot; }
+        for (let i = 0; i < sp; i++) S[stk[i]]++;     // every ancestor gained one node
+        const newSize = S[this._root];                // == old size + 1
+        if (newSize > this._maxCount) this._maxCount = newSize;
+        this._version = (this._version + 1) | 0;
+        // Depth test with NO Math.log: the new node sits at depth d == sp; it is too deep
+        // iff d > h_alpha(newSize) == floor(_invLog * log2(newSize)), tested EXACTLY as
+        // _invAlpha^d > newSize (integer d, so strict > matches the floor). One float
+        // multiply per level -- only on this insert path, never on get.
+        let bound = 1;
+        for (let i = 0; i < sp; i++) bound *= this._invAlpha;
+        if (bound > newSize) {
+            // Walk the recorded path up to the SCAPEGOAT: the lowest ancestor whose
+            // path-child subtree exceeds alpha of its own (post-insert) size.
+            let g = -1;
+            for (let i = sp - 1; i >= 0; i--) {
+                const node = stk[i];
+                const child = i === sp - 1 ? slot : stk[i + 1];
+                if (S[child] > this._alpha * S[node]) { g = i; break; }
+            }
+            if (g === -1) {
+                this._rebuildSubtree(this._root, 0, false); // defensive: rebuild whole tree
+            } else {
+                const node = stk[g];
+                const parent = g > 0 ? stk[g - 1] : 0;
+                const wasLeft = parent !== 0 && L[parent] === node;
+                this._rebuildSubtree(node, parent, wasLeft);
+            }
+        }
+        return this;
+    }
+
+    /**
+     * Remove `key`. AMORTIZED O(log n). Idempotent: returns `false` if `key` is absent (no
+     * throw), `true` if it was present and removed. A standard BST delete fixes `_size` on
+     * the unwind; when the tree has shrunk below `alpha * _maxCount` the WHOLE tree is
+     * rebuilt perfectly balanced and `_maxCount` reset. Fails closed on a non-finite key.
+     * @param {number} key  a finite number
+     * @returns {boolean}
+     */
+    delete(key) {
+        if (typeof key !== 'number' || !Number.isFinite(key)) return this._badKey(key);
+        const L = this._left, R = this._right, K = this._key;
+        let t = this._root, found = false;
+        while (t !== 0) {
+            if (key < K[t]) t = L[t];
+            else if (key > K[t]) t = R[t];
+            else { found = true; break; }
+        }
+        if (!found) return false; // absent (no throw)
+        this._root = this._delete(this._root, key);
+        this._version = (this._version + 1) | 0;
+        const newSize = this._root === 0 ? 0 : this._size[this._root];
+        if (newSize < this._alpha * this._maxCount) {
+            this._rebuildSubtree(this._root, 0, false); // global rebuild
+            this._maxCount = newSize;
+        }
+        return true;
+    }
+
+    /**
+     * The number of stored keys STRICTLY LESS than `x` (its rank / position). O(log n) via
+     * subtree counts. `x` need not be present; `rank` of the smallest key is 0, of a key
+     * past the max is `size`. Fails closed on a non-finite `x`.
+     * @param {number} x  a finite number
+     * @returns {number} count of keys < x, in [0, size]
+     */
+    rank(x) {
+        if (typeof x !== 'number' || !Number.isFinite(x)) return this._badKey(x);
+        const L = this._left, R = this._right, K = this._key, S = this._size;
+        let t = this._root, r = 0;
+        while (t !== 0) {
+            if (x <= K[t]) t = L[t];              // t (and its right) are >= x
+            else { r += S[L[t]] + 1; t = R[t]; }  // t's left subtree + t precede x
+        }
+        return r;
+    }
+
+    /**
+     * The k-th smallest KEY (0-based order statistic), or `undefined` if `k` is out of
+     * range [0, size). O(log n) via subtree counts. Fails closed on a non-integer `k`
+     * (typeof-guarded first); an in-type out-of-range `k` returns `undefined`.
+     * @param {number} k  integer in [0, size)
+     * @returns {number|undefined} the k-th smallest key
+     */
+    select(k) {
+        if (typeof k !== 'number' || !Number.isInteger(k)) return this._badRank(k);
+        const sz = this._root === 0 ? 0 : this._size[this._root];
+        if (k < 0 || k >= sz) return undefined;
+        const L = this._left, R = this._right, K = this._key, S = this._size;
+        let t = this._root;
+        for (;;) {
+            const ls = S[L[t]];
+            if (k < ls) t = L[t];
+            else if (k > ls) { k -= ls + 1; t = R[t]; }
+            else return K[t];
+        }
+    }
+
+    /**
+     * The smallest key STRICTLY greater than `key`, or `undefined` if none. O(log n).
+     * `key` itself need not be present. Fails closed on a non-finite key.
+     * @param {number} key  a finite number
+     * @returns {number|undefined}
+     */
+    successor(key) {
+        if (typeof key !== 'number' || !Number.isFinite(key)) return this._badKey(key);
+        const L = this._left, R = this._right, K = this._key;
+        let t = this._root, best;
+        while (t !== 0) {
+            if (K[t] > key) { best = K[t]; t = L[t]; }
+            else t = R[t];
+        }
+        return best;
+    }
+
+    /**
+     * The largest key STRICTLY less than `key`, or `undefined` if none. O(log n). `key`
+     * itself need not be present. Fails closed on a non-finite key.
+     * @param {number} key  a finite number
+     * @returns {number|undefined}
+     */
+    predecessor(key) {
+        if (typeof key !== 'number' || !Number.isFinite(key)) return this._badKey(key);
+        const L = this._left, R = this._right, K = this._key;
+        let t = this._root, best;
+        while (t !== 0) {
+            if (K[t] < key) { best = K[t]; t = R[t]; }
+            else t = L[t];
+        }
+        return best;
+    }
+
+    /**
+     * A VERSION-STAMPED iterator over the keys in `[lo, hi]` INCLUSIVE, ascending. Bounds
+     * may be any number INCLUDING +-Infinity (an unbounded end); `NaN` fails closed, as
+     * does `lo > hi`. The generator captures the tree's version and throws `[lite-logn]`
+     * if any STRUCTURAL or VALUE mutation happens mid-iteration, rather than yield stale
+     * data. It walks by repeated `successor` (each step a fresh O(log n) descent, so NO
+     * scratch stack is allocated); the one documented per-protocol allocator is the
+     * {value, done} per step.
+     * @param {number} lo  lower bound (inclusive); may be -Infinity
+     * @param {number} hi  upper bound (inclusive); may be +Infinity
+     * @returns {IterableIterator<number>} the keys in [lo, hi], ascending
+     */
+    rangeIter(lo, hi) {
+        if (typeof lo !== 'number' || Number.isNaN(lo)) return this._badBound(lo);
+        if (typeof hi !== 'number' || Number.isNaN(hi)) return this._badBound(hi);
+        if (lo > hi) return this._badRange(lo, hi);
+        return this._rangeGen(lo, hi);
+    }
+
+    /** @private version-stamped range generator (see rangeIter). */
+    *_rangeGen(lo, hi) {
+        const ver = this._version;
+        let cur = this._ceil(lo); // smallest key >= lo, or undefined
+        while (cur !== undefined && cur <= hi) {
+            if (this._version !== ver) {
+                throw new Error('[lite-logn] Scapegoat mutated during iteration');
+            }
+            yield cur;
+            cur = this.successor(cur);
+        }
+    }
+
+    /**
+     * Visit every live `(key, value)` pair in ASCENDING key order. O(n) cold in-order walk
+     * (recursion depth = tree height, O(log n)), allocation-free in the loop body (pass a
+     * hoisted callback). Unlike rangeIter this is NOT version-stamped -- mutating from
+     * within the callback is the caller's responsibility (matching the other members).
+     * @param {(key:number, value:number, tree:Scapegoat)=>void} fn
+     */
+    forEach(fn) {
+        this._forEach(this._root, fn);
+    }
+
+    /** @private recursive in-order walk. */
+    _forEach(t, fn) {
+        if (t === 0) return;
+        this._forEach(this._left[t], fn);
+        fn(this._key[t], this._value[t], this);
+        this._forEach(this._right[t], fn);
+    }
+
+    /**
+     * Empty the tree, keeping the fixed capacity. O(capacity) cold path: returns every
+     * node to the pool and points the root at NIL. @returns {this}
+     */
+    clear() {
+        this._pool.clear();
+        this._root = 0;
+        this._maxCount = 0;
+        this._version = (this._version + 1) | 0;
+        return this;
+    }
+
+    // ---- private structure (rebuild + recursive delete; hot bodies elsewhere) ----
+
+    /**
+     * @private In-order flatten of subtree `root` into `_flat` using the preallocated
+     * `_stack` index-column (Morris-free, ITERATIVE -- so a degenerate pre-rebuild chain
+     * cannot overflow the native stack). Returns the node count written. 0 B/op.
+     */
+    _flatten(root) {
+        const L = this._left, R = this._right, stk = this._stack, flat = this._flat;
+        let node = root, sp = 0, c = 0;
+        while (node !== 0 || sp > 0) {
+            while (node !== 0) { stk[sp++] = node; node = L[node]; }
+            node = stk[--sp];
+            flat[c++] = node;
+            node = R[node];
+        }
+        return c;
+    }
+
+    /**
+     * @private Build a perfectly balanced BST from the sorted slot range `_flat[lo..hi]`,
+     * re-linking `_left` / `_right` / `_size`. Returns the subtree root (NIL if empty).
+     * Bounded native recursion: depth is O(log(hi-lo+1)) <= ~31 (it produces a balanced
+     * subtree), so it runs on the native call stack, never the GC heap. 0 B/op.
+     */
+    _buildBalanced(lo, hi) {
+        if (lo > hi) return 0;
+        const mid = (lo + hi) >> 1;
+        const s = this._flat[mid];
+        const l = this._buildBalanced(lo, mid - 1);
+        const r = this._buildBalanced(mid + 1, hi);
+        this._left[s] = l;
+        this._right[s] = r;
+        this._size[s] = this._size[l] + this._size[r] + 1; // _size[0] is a permanent 0
+        return s;
+    }
+
+    /**
+     * @private Rebuild subtree `root` perfectly balanced and re-link it under `parent`
+     * (or the tree root when `parent === 0`). `wasLeft` records which child link to
+     * rewrite. Reuses the preallocated `_flat` + `_stack` scratch: 0 B/op.
+     */
+    _rebuildSubtree(root, parent, wasLeft) {
+        const count = this._flatten(root);
+        const nr = this._buildBalanced(0, count - 1);
+        if (parent === 0) this._root = nr;
+        else if (wasLeft) this._left[parent] = nr;
+        else this._right[parent] = nr;
+    }
+
+    /** @private recursive BST delete of `key` from subtree `t`; frees the removed slot,
+     *  fixing `_size` on the unwind. Depth = tree height = O(log n). */
+    _delete(t, key) {
+        const L = this._left, R = this._right, S = this._size, K = this._key;
+        if (key < K[t]) {
+            L[t] = this._delete(L[t], key);
+            S[t] = S[L[t]] + S[R[t]] + 1;
+            return t;
+        }
+        if (key > K[t]) {
+            R[t] = this._delete(R[t], key);
+            S[t] = S[L[t]] + S[R[t]] + 1;
+            return t;
+        }
+        // found t
+        const l = L[t], r = R[t];
+        if (l === 0) { this._pool.free(t); return r; }
+        if (r === 0) { this._pool.free(t); return l; }
+        // two children: copy the in-order successor (min of the right subtree) into t,
+        // then delete that successor from the right subtree (frees ITS slot).
+        let m = r; while (L[m] !== 0) m = L[m];
+        K[t] = K[m]; this._value[t] = this._value[m];
+        R[t] = this._deleteMin(R[t]);
+        S[t] = S[L[t]] + S[R[t]] + 1;
+        return t;
+    }
+
+    /** @private remove the minimum of subtree `t`, freeing its slot; return the new root. */
+    _deleteMin(t) {
+        const L = this._left, R = this._right, S = this._size;
+        if (L[t] === 0) { const r = R[t]; this._pool.free(t); return r; }
+        L[t] = this._deleteMin(L[t]);
+        S[t] = S[L[t]] + S[R[t]] + 1;
+        return t;
+    }
+
+    /** @private smallest key >= `lo`, or undefined (the range-iter start). */
+    _ceil(lo) {
+        const L = this._left, R = this._right, K = this._key;
+        let t = this._root, best;
+        while (t !== 0) {
+            if (K[t] >= lo) { best = K[t]; t = L[t]; }
+            else t = R[t];
+        }
+        return best;
+    }
+
+    // ---- cold path only: throw builders (string concat off the hot body) ----
+
+    /** @private */
+    _badKey(key) {
+        throw new TypeError(
+            '[lite-logn] Scapegoat key must be a finite number, got ' + String(key));
+    }
+
+    /** @private */
+    _badValue(value) {
+        throw new TypeError(
+            '[lite-logn] Scapegoat value must be a finite number, got ' + String(value));
+    }
+
+    /** @private */
+    _badRank(k) {
+        throw new TypeError(
+            '[lite-logn] Scapegoat select index must be an integer, got ' + String(k));
+    }
+
+    /** @private */
+    _badBound(b) {
+        throw new TypeError(
+            '[lite-logn] Scapegoat rangeIter bound must be a number (not NaN), got ' + String(b));
+    }
+
+    /** @private */
+    _badRange(lo, hi) {
+        throw new RangeError(
+            '[lite-logn] Scapegoat rangeIter needs lo <= hi, got lo=' + String(lo) +
+            ' hi=' + String(hi));
+    }
+
+    /** @private */
+    _full() {
+        throw new RangeError('[lite-logn] Scapegoat full (capacity ' + this._cap + ')');
+    }
+}

package/README.md

@@ -1,6 +1,6 @@
 # @zakkster/lite-logn
 
-> Zero-GC, O(log n) data structures that PROVE their logarithm. The O(log n) sibling of `@zakkster/lite-o1`: where lite-o1 holds the constant (a flat ops/ms line), lite-logn holds the logarithm (a straight line on a log-x axis -- one added level per doubling of n). v0.5.0 ships five members: BinaryHeap (array-embedded O(log n) push / pop min|max heap), Fenwick / BIT (O(log n) point-update AND prefix-sum via the `i & -i` walk), SegmentTree (O(log n) associative range-query -- min / max / sum / gcd -- plus point-update over a flat 2n array), SkipList (pointer-free expected-O(log n) ordered map over a private free-list node pool), and Treap (a randomized-balanced augmented ordered map with O(log n) rank / select / split / merge) -- each zero-GC, each shipped with a log-linear Witness that fits `nsPerOp = intercept + slope*log2(n)` and shows the straight log line while an O(n) foil leaves it.
+> Zero-GC, O(log n) data structures that PROVE their logarithm. The O(log n) sibling of `@zakkster/lite-o1`: where lite-o1 holds the constant (a flat ops/ms line), lite-logn holds the logarithm (a straight line on a log-x axis -- one added level per doubling of n). v0.6.0 ships six members: BinaryHeap (array-embedded O(log n) push / pop min|max heap), Fenwick / BIT (O(log n) point-update AND prefix-sum via the `i & -i` walk), SegmentTree (O(log n) associative range-query -- min / max / sum / gcd -- plus point-update over a flat 2n array), SkipList (pointer-free expected-O(log n) ordered map over a private free-list node pool), Treap (a randomized-balanced augmented ordered map with O(log n) rank / select / split / merge), and Scapegoat (a DETERMINISTIC weight-balanced augmented ordered map: worst-case-O(log n) get, amortized-O(log n) set / delete, zero-GC rebuild) -- each zero-GC, each shipped with a log-linear Witness that fits `nsPerOp = intercept + slope*log2(n)` and shows the straight log line while an O(n) foil leaves it.
 
 [![npm version](https://img.shields.io/npm/v/@zakkster/lite-logn.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-logn)
 [![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
@@ -19,7 +19,7 @@ Almost no JavaScript data-structure library ships the evidence that its Big-O cl
 
 lite-logn is the O(log n) sibling of [`@zakkster/lite-o1`](https://www.npmjs.com/package/@zakkster/lite-o1). lite-o1 proves a FLAT ops/ms line on a log-x axis (the constant -- slope ~ 0); lite-logn proves a STRAIGHT line on that same axis (one added level per doubling of `n` -- slope > 0, within a per-member band). The gate SHAPE differs; the discipline is identical: zero allocation on every hot path and a witness that turns "trust me, it is O(log n)" into a straight line you can see, with a foil that leaves it.
 
-**v0.5.0 ships five members: BinaryHeap, Fenwick, SegmentTree, SkipList and Treap.** Members land one per session, each append-only so prior members stay byte-identical. The planned roster below fills in per release.
+**v0.6.0 ships six members: BinaryHeap, Fenwick, SegmentTree, SkipList, Treap and Scapegoat.** Members land one per session, each append-only so prior members stay byte-identical. The planned roster below fills in per release.
 
 ```bash
 npm install @zakkster/lite-logn
@@ -61,6 +61,7 @@ Every hot op allocates zero bytes after construction, and `npm run witness` prov
   - [SegmentTree](#segmenttree)
   - [SkipList](#skiplist)
   - [Treap](#treap)
+  - [Scapegoat](#scapegoat)
 - [Zero-GC design notes](#zero-gc-design-notes)
 - [Testing](#testing)
 - [What this is not](#what-this-is-not)
@@ -85,7 +86,7 @@ lite-logn ships the O(log n) structures that matter with the allocation removed
 
 ## The roster
 
-One member per session, each landing append-only (prior members stay byte-identical). At v0.5.0, BinaryHeap, Fenwick, SegmentTree, SkipList and Treap are shipped.
+One member per session, each landing append-only (prior members stay byte-identical). At v0.6.0, BinaryHeap, Fenwick, SegmentTree, SkipList, Treap and Scapegoat are shipped.
 
 | Member | Version | Status | Shape | Hot ops |
 | --- | --- | --- | --- | --- |
@@ -94,8 +95,9 @@ One member per session, each landing append-only (prior members stay byte-identi
 | **SegmentTree** | 0.3.0 | shipped | single flat `Float64Array(2n)` (leaves n..2n-1); associative fold (min/max/sum/gcd) chosen at construction | `query` / `update` O(log n), `at` O(1) |
 | **SkipList** | 0.4.0 | shipped | pointer-free over a private free-list node pool; expected O(log n) | `get` / `set` / `delete` / `successor` / `predecessor` |
 | **Treap** | 0.5.0 | shipped | randomized-balanced augmented BST over the same node pool; expected O(log n) | `get` / `has` / `set` / `delete` / `rank` / `select` / `successor` / `predecessor` / `forEach` / `rangeIter` / `split` + `merge` |
+| **Scapegoat** | 0.6.0 | shipped | DETERMINISTIC weight-balanced augmented BST over the same node pool; worst-case O(log n) get, amortized O(log n) set/delete (zero-GC rebuild) | `get` / `has` / `set` / `delete` / `rank` / `select` / `successor` / `predecessor` / `forEach` / `rangeIter` (NO split/merge) |
 
-Later tiers (Scapegoat, OrderStatTree, IndexedHeap, SortedArray, MinMaxHeap, SplayTree, and presets) are queued in [`ROADMAP.md`](./ROADMAP.md).
+Later tiers (OrderStatTree, IndexedHeap, SortedArray, MinMaxHeap, SplayTree, and presets) are queued in [`ROADMAP.md`](./ROADMAP.md).
 
 ## The O(log n) Witness
 
@@ -105,7 +107,7 @@ The family anchor. Time a fixed batch of the hot op at each `n` in a geometric s
 - `slope` inside the member's band (the per-level cost, ns/level), AND
 - the FOIL leaves the line (low `R^2` -- the O(n) default a working programmer reaches for, shown losing as `n` grows).
 
-For amortized / randomized members the witness also prints the MAX single-op time -- the honesty hook: a rebuild spike or a degenerate tail shows as a tall bar even when the mean still fits the line. The `R^2` floor (0.958) is frozen family-wide in BinaryHeap; each member then calibrates its OWN per-op slope band (median-of-15 fit-runs x `[0.6, 1.4]`), because a cheaper op honestly has a lower per-level slope (see [`decisions/0004-witness-band.md`](./decisions/0004-witness-band.md)). At v0.5.0 the witness gates eight ops: BinaryHeap `pop` (R^2 ~ 0.99, slope ~ 8-10 ns/level), Fenwick `update` (R^2 ~ 0.98-0.99, slope ~ 2.9-3.0 ns/level) and `prefix` (R^2 ~ 0.97, slope ~ 2.6-2.7 ns/level), SegmentTree `update` (R^2 ~ 0.99, slope ~ 3.2 ns/level, band `[2.29, 5.35]`) and `query` (R^2 ~ 0.99, slope ~ 7 ns/level, band `[4.30, 10.04]`), SkipList `get` (R^2 ~ 0.97-0.99, slope ~ 9 ns/level, band `[5.27, 12.30]`) and `set` (R^2 ~ 0.97-0.99, slope ~ 14 ns/level, band `[8.36, 19.50]`), and Treap `get` (R^2 ~ 0.99, slope ~ 4 ns/level, band `[2.55, 5.95]`) all ON the line. Treap's descent touches one node per level, so its per-level slope is lower than SkipList's tower search -- expected, which is why only the R^2 floor is shared and each op calibrates its own band. SkipList's two ops are gated over DIFFERENT sweeps -- each measured where its logarithm is visible, not where the cache wall is: `get` (a clean search with no per-op randomness) over `[2^11, 2^17]` for dynamic range; `set` (a heavier insert+delete churn whose per-insert tower height is random) over the smaller, fully cache-resident `[2^9, 2^14]` so the fit sees the structural level count, not DRAM latency. Because SkipList is EXPECTED (not worst-case) O(log n), the witness also prints the MAX single insert over a realistic randomized build trace -- the unlucky-tower tail a mean hides. Each op's O(n) foil fits well below the floor: the sorted-array insert (BinaryHeap / SkipList) foil runs R^2 ~ 0.77-0.87, the Fenwick foils (prefix-array rebuild, naive re-sum) and SkipList's linear-scan search foil hold at R^2 ~ 0.75-0.82, and SegmentTree's foils (whole-tree rebuild per update, scan-fold per query) fit at R^2 ~ 0.72-0.85 -- all foil families sit comfortably under the 0.958 floor.
+For amortized / randomized members the witness also prints the MAX single-op time -- the honesty hook: a rebuild spike or a degenerate tail shows as a tall bar even when the mean still fits the line. The `R^2` floor (0.958) is frozen family-wide in BinaryHeap; each member then calibrates its OWN per-op slope band (median-of-15 fit-runs x `[0.6, 1.4]`), because a cheaper op honestly has a lower per-level slope (see [`decisions/0004-witness-band.md`](./decisions/0004-witness-band.md)). At v0.6.0 the witness gates nine ops: BinaryHeap `pop` (R^2 ~ 0.99, slope ~ 8-10 ns/level), Fenwick `update` (R^2 ~ 0.98-0.99, slope ~ 2.9-3.0 ns/level) and `prefix` (R^2 ~ 0.97, slope ~ 2.6-2.7 ns/level), SegmentTree `update` (R^2 ~ 0.99, slope ~ 3.2 ns/level, band `[2.29, 5.35]`) and `query` (R^2 ~ 0.99, slope ~ 7 ns/level, band `[4.30, 10.04]`), SkipList `get` (R^2 ~ 0.97-0.99, slope ~ 9 ns/level, band `[5.27, 12.30]`) and `set` (R^2 ~ 0.97-0.99, slope ~ 14 ns/level, band `[8.36, 19.50]`), Treap `get` (R^2 ~ 0.99, slope ~ 4 ns/level, band `[2.55, 5.95]`), and Scapegoat `get` (R^2 ~ 0.99, slope ~ 4 ns/level, band `[2.41, 5.63]`) all ON the line. Scapegoat is DETERMINISTIC, so its `get` is WORST-case (not expected) O(log n); its rebuild spike lives on the AMORTIZED `set` path and is proven not by a per-op line but by an amortized-trace assertion -- the cumulative ascending-insert (rebuild-heavy) cost/op tracks a LOG curve (last/first ratio ~1.5x over `[2^11, 2^17]`, gated `< 4x`) where a rebuild-less BST would degenerate to an O(n)-amortized chain and blow the ratio to ~64x. Treap's descent touches one node per level, so its per-level slope is lower than SkipList's tower search -- expected, which is why only the R^2 floor is shared and each op calibrates its own band. SkipList's two ops are gated over DIFFERENT sweeps -- each measured where its logarithm is visible, not where the cache wall is: `get` (a clean search with no per-op randomness) over `[2^11, 2^17]` for dynamic range; `set` (a heavier insert+delete churn whose per-insert tower height is random) over the smaller, fully cache-resident `[2^9, 2^14]` so the fit sees the structural level count, not DRAM latency. Because SkipList is EXPECTED (not worst-case) O(log n), the witness also prints the MAX single insert over a realistic randomized build trace -- the unlucky-tower tail a mean hides. Each op's O(n) foil fits well below the floor: the sorted-array insert (BinaryHeap / SkipList) foil runs R^2 ~ 0.77-0.87, the Fenwick foils (prefix-array rebuild, naive re-sum) and SkipList's linear-scan search foil hold at R^2 ~ 0.75-0.82, and SegmentTree's foils (whole-tree rebuild per update, scan-fold per query) fit at R^2 ~ 0.72-0.85 -- all foil families sit comfortably under the 0.958 floor.
 
 ## Benchmarks
 
@@ -145,6 +147,9 @@ Each op fits `nsPerOp = intercept + slope*log2(n)`. ON-LINE = `R^2 >= 0.958` (th
 | `SkipList.get` | 0.988 | 8.0 | `[5.27, 12.30]` | ON | linear scan | 0.79 | off |
 | `SkipList.set` | 0.985 | 12.1 | `[8.36, 19.50]` | ON | sorted-array insert | 0.77 | off |
 | `Treap.get` | 0.988 | 4.0 | `[2.55, 5.95]` | ON | linear scan | 0.79 | off |
+| `Scapegoat.get` | 0.988 | 3.8 | `[2.41, 5.63]` | ON | linear scan | 0.79 | off |
+
+**Scapegoat amortized-trace (the rebuild honesty).** Scapegoat's `get` is WORST-case O(log n) (a deterministic weight-balance height bound), so it carries no expected-op MAX-single-op disclosure. The rebuild spike lives on the AMORTIZED `set` path; D1 proves the amortization not with a per-op line but with an amortized-trace assertion -- the cumulative ascending-insert (rebuild-heavy) cost/op tracks a LOG curve (last/first ratio `~1.5x` over `[2^11, 2^17]`, gated `< 4x`) where a rebuild-less BST would blow to `~64x`.
 
 **SkipList counter-foil (the order tax).** A native `Map` is O(1) at get/set (`~27 ns/op`, FLATTER than any log line) but ORDER-BLIND: it cannot answer `successor` / `predecessor` / `rangeIter`. The log factor SkipList pays buys exactly the ordered queries Map cannot. SkipList is EXPECTED O(log n), so D1 also DISCLOSES its MAX single insert (an unlucky tall tower over a randomized build: `~18-130 us`, not gated).
 
@@ -178,8 +183,8 @@ All seven gated op-rows report **0 B/op** across the `n = 1e3..1e6` sweep, with
 
 - **D2 amortized cost** -- cumulative ns/op stays bounded over a `~1M`-op mixed trace (drift `< 1.0` here: the trace speeds up as the JIT warms, never degrades).
 - **D4 cache (PROXY, labelled)** -- dense `forEach` iteration vs random single-element lookup; the random/dense gap is `~1.9x` (SegmentTree) to `~2.9x` (SkipList). No native perf counters.
-- **D7 scalability** -- numeric substrates: string + object keys read `n/a`. Load factors `0.3/0.5/0.7/0.9`; insertion order (sorted / random / adversarial-reverse) applies to the comparison-ordered BinaryHeap + SkipList + Treap, `n/a` for the index-addressed Fenwick + SegmentTree.
-- **D8 workloads** -- churn (all members) + an ordered scan (`successor` + `rangeIter`, SkipList + Treap; `n/a` elsewhere).
+- **D7 scalability** -- numeric substrates: string + object keys read `n/a`. Load factors `0.3/0.5/0.7/0.9`; insertion order (sorted / random / adversarial-reverse) applies to the comparison-ordered BinaryHeap + SkipList + Treap + Scapegoat, `n/a` for the index-addressed Fenwick + SegmentTree.
+- **D8 workloads** -- churn (all members) + an ordered scan (`successor` + `rangeIter`, SkipList + Treap + Scapegoat; `n/a` elsewhere).
 
 ## API reference
 
@@ -187,7 +192,7 @@ All seven gated op-rows report **0 B/op** across the `n = 1e3..1e6` sweep, with
 
 | Export | Type | Value | Meaning |
 | --- | --- | --- | --- |
-| `VERSION` | `string` | `'0.5.0'` | The package version. One of the three version sites (package.json / `LogN.js` `VERSION` const / `llms.txt`), kept in lockstep and enforced in review. |
+| `VERSION` | `string` | `'0.6.0'` | The package version. One of the three version sites (package.json / `LogN.js` `VERSION` const / `llms.txt`), kept in lockstep and enforced in review. |
 
 ### BinaryHeap
 
@@ -372,6 +377,42 @@ const whole = Treap.merge(lo, hi);// fuse back (all lo keys < all hi keys); both
 | `merge` (static) | `Treap.merge(a, b) -> Treap` | expected O(log n) | Fuse two arena-sharing treaps where every key of `a` < every key of `b`; CONSUMES both. Non-Treap inputs, cross-arena treaps, or an overlapping range throw. |
 | `size` / `capacity` | getters | O(1) | Live entry count / fixed capacity. |
 
+### Scapegoat
+
+A **scapegoat tree**: a **DETERMINISTIC**, weight-balanced **binary search tree** that is also an **order-statistic tree** -- an AUGMENTED ordered map (key -> value) -- the honest **pair to Treap**. Where a treap randomizes its shape to be balanced *in expectation*, a scapegoat keeps a hard **worst-case height bound** (`height <= log_{1/alpha}(n) + 1`), so `get` is **worst-case O(log n)** (never merely expected). It pays for that with **amortized O(log n)** `set` / `delete`: after a mutation makes the tree too deep (or, on delete, too sparse), an occasional **subtree rebuild** restores balance in bulk. A subtree-size column (maintained in the same pass as every link rewrite and every rebuild) adds `rank(x)` / `select(k)`, O(log n). **No priorities, no RNG anywhere** -- the shape is a deterministic function of the insert / delete order. 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 use. 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. Every hot op allocates zero bytes after construction.
+
+Zero-GC rebuild (the load-bearing design call): there is **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`, and 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 (see [`decisions/0008-scapegoat.md`](./decisions/0008-scapegoat.md)). Unlike Treap there is **no `split` / `merge`**: a scapegoat has no priority heap to merge by, and an honest deterministic split/merge would be O(n) rebuilds -- the documented asymmetry vs Treap. `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`).
+
+```js
+import { Scapegoat } from '@zakkster/lite-logn';
+
+const sg = new Scapegoat(1000);   // capacity 1000, alpha = 2/3 (deterministic, no seed)
+sg.set(50, 500);                  // insert key 50 -> value 500
+sg.set(20, 200);
+sg.set(80, 800);
+sg.get(20);            // -> 200                                   -- worst-case O(log n)
+sg.rank(50);           // -> 1    (one key, 20, is strictly less than 50)
+sg.select(0);          // -> 20   (the smallest key)
+sg.successor(20);      // -> 50   (smallest key strictly greater)
+[...sg.rangeIter(20, 80)]; // -> [20, 50, 80]  (inclusive, ascending)
+```
+
+| Member | Signature | Complexity | Notes |
+| --- | --- | --- | --- |
+| constructor | `new Scapegoat(capacity, alpha?)` | O(capacity) | `capacity` integer in `[1, 2^31-1]` (slot indices + subtree counts are `Uint32`, `NIL = 0` reserves slot 0); `alpha` in the OPEN interval `(0.55, 0.75)` (both ends throw), frozen at construction (default `2/3`). Allocates five columns + private pool + two rebuild scratch buffers once. |
+| `get` | `get(key) -> number \| undefined` | worst-case O(log n) | The value under `key`, or `undefined` if absent (no throw). Non-finite key throws. |
+| `has` | `has(key) -> boolean` | worst-case O(log n) | True iff `key` is stored. Non-finite key throws. |
+| `set` | `set(key, value) -> this` | amortized O(log n) | Insert `key -> value`, or update the value in place if `key` exists (no rebuild). Non-finite key/value throws; a full pool throws. |
+| `delete` | `delete(key) -> boolean` | amortized O(log n) | Idempotent: `false` if absent, `true` if removed. Non-finite key throws. |
+| `rank` | `rank(x) -> number` | worst-case O(log n) | Count of stored keys STRICTLY less than `x`, in `[0, size]`. `x` need not be present. Non-finite `x` throws. |
+| `select` | `select(k) -> number \| undefined` | worst-case O(log n) | The k-th smallest key (0-based), or `undefined` if `k` is out of `[0, size)`. Non-integer `k` throws. |
+| `successor` | `successor(key) -> number \| undefined` | worst-case O(log n) | The smallest key STRICTLY greater than `key`, or `undefined`. |
+| `predecessor` | `predecessor(key) -> number \| undefined` | worst-case O(log n) | The largest key STRICTLY less than `key`, or `undefined`. |
+| `rangeIter` | `rangeIter(lo, hi) -> IterableIterator<number>` | O(k log n) | Version-stamped iterator over keys in `[lo, hi]` INCLUSIVE, ascending. Bounds may be `+-Infinity`; `NaN` or `lo > hi` throws; a structural OR value mutation mid-iteration throws. |
+| `forEach` | `forEach(fn) -> void` | O(n) | Visits `(key, value, tree)` in ascending key order. |
+| `clear` | `clear() -> this` | O(capacity) | Empties the tree, keeps capacity. |
+| `size` / `capacity` / `alpha` | getters | O(1) | Live entry count / fixed capacity / frozen weight-balance factor. |
+
 Member signatures for later members are appended here as each ships.
 
 ## Zero-GC design notes
@@ -399,8 +440,12 @@ Member signatures for later members are appended here as each ships.
 | `Treap` forEach | 0 B/op in the loop body (recursive in-order walk, hoisted callback) |
 | `Treap` rangeIter | one iterator + `{value, done}` per step (the documented per-protocol allocator; transient, not retained) |
 | `Treap` split / merge | 0 B/op beyond the returned Treap view(s); rewire in place, share the arena, consume the input(s) |
+| `Scapegoat` get / has / set / delete / rank / select / successor / predecessor | 0 B/op (nodes are slot indices; the rebuild reuses the preallocated `_flat` + `_stack` scratch and the native call stack, so even a rebuild storm is 0 B/op) |
+| `Scapegoat` constructor / `clear` | O(capacity) five columns + pool + two rebuild scratch buffers, once (cold) |
+| `Scapegoat` forEach | 0 B/op in the loop body (recursive in-order walk, hoisted callback) |
+| `Scapegoat` rangeIter | one iterator + `{value, done}` per step (the documented per-protocol allocator; transient, not retained) |
 
-Gated witness numbers (this machine, shared R^2 floor 0.958): BinaryHeap `pop` R^2 ~ 0.99, slope ~ 8-10 ns/level; Fenwick `update` R^2 ~ 0.98-0.99, slope ~ 2.9-3.0 ns/level (band `[1.84, 4.30]`); Fenwick `prefix` R^2 ~ 0.97, slope ~ 2.6-2.7 ns/level (band `[1.76, 4.10]`); SegmentTree `update` R^2 ~ 0.99, slope ~ 3.2 ns/level (band `[2.29, 5.35]`); SegmentTree `query` R^2 ~ 0.99, slope ~ 7 ns/level (band `[4.30, 10.04]`); SkipList `get` R^2 ~ 0.97-0.99, slope ~ 9 ns/level (band `[5.27, 12.30]`, sweep `[2^11, 2^17]`); SkipList `set` R^2 ~ 0.97-0.99, slope ~ 14 ns/level (band `[8.36, 19.50]`, cache-resident sweep `[2^9, 2^14]`); Treap `get` R^2 ~ 0.99, slope ~ 4 ns/level (band `[2.55, 5.95]`, sweep `[2^11, 2^17]`). The allocation table is extended per member as each lands.
+Gated witness numbers (this machine, shared R^2 floor 0.958): BinaryHeap `pop` R^2 ~ 0.99, slope ~ 8-10 ns/level; Fenwick `update` R^2 ~ 0.98-0.99, slope ~ 2.9-3.0 ns/level (band `[1.84, 4.30]`); Fenwick `prefix` R^2 ~ 0.97, slope ~ 2.6-2.7 ns/level (band `[1.76, 4.10]`); SegmentTree `update` R^2 ~ 0.99, slope ~ 3.2 ns/level (band `[2.29, 5.35]`); SegmentTree `query` R^2 ~ 0.99, slope ~ 7 ns/level (band `[4.30, 10.04]`); SkipList `get` R^2 ~ 0.97-0.99, slope ~ 9 ns/level (band `[5.27, 12.30]`, sweep `[2^11, 2^17]`); SkipList `set` R^2 ~ 0.97-0.99, slope ~ 14 ns/level (band `[8.36, 19.50]`, cache-resident sweep `[2^9, 2^14]`); Treap `get` R^2 ~ 0.99, slope ~ 4 ns/level (band `[2.55, 5.95]`, sweep `[2^11, 2^17]`); Scapegoat `get` R^2 ~ 0.99, slope ~ 3.8-4.0 ns/level (band `[2.41, 5.63]`, sweep `[2^11, 2^17]`) -- WORST-case (deterministic), with the AMORTIZED `set` rebuild spike proven by the amortized-trace assertion (ratio `< 4x`), not a per-op line. The allocation table is extended per member as each lands.
 
 ## Testing
 

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-logn
 
-Version: 0.5.0
+Version: 0.6.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -19,8 +19,8 @@ FLAT ops/ms line on a log-x axis), lite-logn holds the logarithm (a STRAIGHT
 line on that same axis, one added level per doubling of n).
 
 v0.1.0 shipped BinaryHeap; v0.2.0 adds Fenwick; v0.3.0 adds SegmentTree; v0.4.0
-adds SkipList; v0.5.0 adds Treap. The roster (one member per session, each landing
-append-only):
+adds SkipList; v0.5.0 adds Treap; v0.6.0 adds Scapegoat. The roster (one member per
+session, each landing append-only):
 
 - BinaryHeap (v0.1.0)  -- an INDEXED binary heap (addressable priority queue): a
   min|max binary heap over three parallel typed arrays (`_key` Float64Array,
@@ -59,6 +59,22 @@ append-only):
   value in place. split / merge REWIRE in place (O(log n)) so the two treaps SHARE a
   backing arena and CONSUME their inputs. EXPECTED, not worst-case: the MAX single
   insert (rotation chain) is DISCLOSED, never gated. Zero allocation on every hot op.
+- Scapegoat (v0.6.0) -- a DETERMINISTIC, weight-balanced AUGMENTED ordered map (key ->
+  value) that is also an order-statistic tree -- the honest PAIR to Treap. get is
+  WORST-case O(log n) (a hard height bound <= log_{1/alpha}(n) + 1, never merely
+  expected); set / delete are AMORTIZED O(log n) (an occasional subtree rebuild absorbs
+  the imbalance). A subtree-size column adds rank(x) / select(k), O(log n). NO priorities,
+  NO RNG anywhere: the shape is a deterministic function of the insert / delete order.
+  Nodes are slot INDICES in flat typed-array columns (_key / _value / _left / _right /
+  _size) over the SAME private free-list (NodePool); the ZERO-GC rebuild reuses ONE
+  preallocated scratch buffer (_flat) + ONE preallocated index-stack (_stack) -- an
+  iterative Morris-free flatten + a bounded log-depth balanced rebuild on the native
+  stack -- so even a rebuild-heavy trace is 0 B/op. alpha is frozen at construction in the
+  OPEN interval (0.55, 0.75) (both ends throw); default 2/3. Unlike Treap there is NO
+  split / merge (no priority heap to merge by; an honest deterministic split/merge would
+  be O(n) rebuilds) -- the documented asymmetry vs Treap. set updates an existing key's
+  value in place. The amortized-trace witness shows cumulative insert cost/op tracks log n
+  despite the rebuild spikes. Zero allocation on every hot op.
 
 ## Exports (from the single main file LogN.js)
 
@@ -189,6 +205,39 @@ append-only):
     < every key of b; O(log n) EXPECTED, CONSUMES both. Non-Treap inputs, treaps from
     different arenas, or an overlapping key range each throw.
 
+- `Scapegoat` -- class. A DETERMINISTIC, weight-balanced AUGMENTED ordered map (key ->
+  value) that is also an order-statistic tree -- the honest PAIR to Treap. A BST on
+  `_key` kept alpha-weight-balanced (get WORST-case O(log n); set / delete AMORTIZED
+  O(log n) via an occasional subtree rebuild); a `_size` subtree-count column adds O(log n)
+  order statistics. NO priorities, NO RNG. Nodes are slot INDICES in flat typed-array
+  columns (`_key` / `_value` Float64, `_left` / `_right` / `_size` Uint32, `NIL = 0`) over
+  a PRIVATE free-list (NodePool); the zero-GC rebuild reuses ONE preallocated `_flat`
+  scratch + ONE `_stack` index-stack (iterative Morris-free flatten + bounded log-depth
+  balanced rebuild on the native stack) -- no heap object, no fresh array, 0 B/op even
+  under a rebuild storm. Keys and values are finite numbers (typeof-guarded before
+  coercion; Symbol / BigInt / NaN / +-Infinity fail closed).
+  - `new Scapegoat(capacity, alpha?)` -- capacity an integer in [1, 2^31-1] (slot indices
+    + subtree counts are Uint32, `NIL = 0` reserves slot 0); alpha the weight-balance
+    factor in the OPEN interval (0.55, 0.75) (both ends throw), frozen at construction;
+    default 2/3. Allocates five columns + a free-list + two rebuild scratch buffers once.
+  - `get(key)` -> value | undefined. Absent -> undefined (no throw).
+  - `has(key)` -> boolean.
+  - `set(key, value)` -> this. Insert, or update the value in place if key exists (no new
+    node, no rebuild). Non-finite key/value throws; a full pool throws.
+  - `delete(key)` -> boolean. Idempotent: false if absent, true if removed.
+  - `rank(x)` -> number. Count of stored keys STRICTLY LESS than x, in [0, size].
+  - `select(k)` -> key | undefined. The k-th smallest key (0-based); undefined if k is out
+    of [0, size). Non-integer k throws.
+  - `successor(key)` -> key | undefined. Smallest key STRICTLY greater than key.
+  - `predecessor(key)` -> key | undefined. Largest key STRICTLY less than key.
+  - `rangeIter(lo, hi)` -> iterator of keys in [lo, hi] INCLUSIVE, ascending; VERSION-
+    STAMPED (structural OR value mutation mid-iteration throws). Bounds may be +-Infinity;
+    NaN or lo > hi throws.
+  - `size` / `capacity` / `alpha` getters; `clear()` -> this (empty, keep capacity);
+    `forEach(fn)` visits (key, value, tree) ascending.
+  - There is deliberately NO `split` / `merge` (the documented asymmetry vs Treap: no
+    priority heap to merge by; an honest deterministic split/merge would be O(n) rebuilds).
+
 Member exports (one tree-shakeable class each) are appended here as each member
 ships.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zakkster/lite-logn",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "0.5.0",
-  "description": "Zero-dependency, zero-GC family of O(log n) data structures that proves its logarithm: BinaryHeap (array-embedded O(log n) push/pop min-heap), Fenwick/BIT (O(log n) point-update AND prefix-sum via the i & -i walk), SegmentTree (O(log n) associative range-query + point-update), SkipList (pointer-free expected-O(log n) ordered map over a private free-list node pool), and Treap (randomized-balanced augmented ordered map with O(log n) rank/select/split/merge) with a log-linear O(log n) Witness harness that fits nsPerOp = intercept + slope*log2(n) and shows the straight log line while an O(n) foil leaves it. Tree-shakeable named exports.",
+  "version": "0.6.0",
+  "description": "Zero-dependency, zero-GC family of O(log n) data structures that proves its logarithm: BinaryHeap (array-embedded O(log n) push/pop min-heap), Fenwick/BIT (O(log n) point-update AND prefix-sum via the i & -i walk), SegmentTree (O(log n) associative range-query + point-update), SkipList (pointer-free expected-O(log n) ordered map over a private free-list node pool), Treap (randomized-balanced augmented ordered map with O(log n) rank/select/split/merge), and Scapegoat (DETERMINISTIC weight-balanced augmented ordered map: worst-case-O(log n) get, amortized-O(log n) set/delete, zero-GC rebuild) with a log-linear O(log n) Witness harness that fits nsPerOp = intercept + slope*log2(n) and shows the straight log line while an O(n) foil leaves it. Tree-shakeable named exports.",
   "type": "module",
   "main": "./LogN.js",
   "module": "./LogN.js",
@@ -49,6 +49,9 @@
     "range-sum",
     "skip-list",
     "treap",
+    "scapegoat",
+    "scapegoat-tree",
+    "weight-balanced",
     "ordered-set",
     "ordered-map",
     "balanced-bst",