@zakkster/lite-logn 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,74 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-20
+
+### Added
+
+- **Treap** -- the fifth member and the family's balanced BST: a randomized,
+  self-balancing binary search tree that is ALSO an order-statistic tree (an AUGMENTED
+  ordered map key -> value). A BST order on `_key` x a MAX-HEAP order on a per-node
+  random priority `_prio` gives EXPECTED O(log n) height, and a subtree-size column
+  `_size` (maintained in the SAME pass as every link rewrite) adds O(log n) order
+  statistics + set surgery. 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` / `split`,
+  the static `Treap.merge(a, b)`, and `size` / `capacity` getters. Keys and values are
+  finite numbers (typeof-guarded before coercion -- Symbol / BigInt / NaN / +-Infinity
+  fail closed with a `[lite-logn]` throw).
+- **Pointer-free, zero-GC, second bind of the shared NodePool.** Nodes are slot
+  INDICES in six flat columns (`_key` / `_value` Float64; `_left` / `_right` / `_prio`
+  / `_size` Uint32, `NIL = 0`) over the SAME private free-list (`NodePool`) SkipList
+  ships -- design-parity, not a fork or a runtime dep (decisions/0007-treap.md). The
+  conservation invariant `activeSlots + freeListLength === capacity` holds after every
+  op. `TR_MAX_CAPACITY = 0x7FFFFFFF` (2^31 - 1: slot indices + subtree counts fit a
+  `Uint32`). Rotations rewrite one child link pair + two `_size` cells; `set` / `delete`
+  / `split` / `merge` recurse over slot indices on the native CALL STACK (not the GC
+  heap), so every hot op is 0 B/op.
+- **Priority via the repo LCG.** One instance-local Numerical-Recipes LCG draw per
+  inserted node; a fixed seed replays an identical structure, ties break by key, so the
+  tree shape is a deterministic function of the (key, priority) set.
+- **split / merge are O(log n) EXPECTED (arena-sharing).** `split(key)` returns
+  `[left (keys < key), right (keys >= key)]` by rewiring in place, so the two treaps
+  SHARE the source's backing arena and the source is CONSUMED (left empty);
+  `Treap.merge(a, b)` requires `a` / `b` to share an arena (all keys of a < all of b)
+  and consumes both. Fails closed on non-Treap inputs, cross-arena treaps, or an
+  overlapping key range.
+- **EXPECTED, not worst-case.** A hot op is EXPECTED O(log n) (the randomized
+  priority heap); the MAX single insert (rotation chain) is DISCLOSED by the witness,
+  never gated -- the same honesty contract as SkipList.
+- **Witness: one more log line.** `test/witness.mjs` gains `Treap.get` (a BST descent)
+  against a linear-scan O(n) foil. Measured on this machine (shared, FROZEN R^2 floor
+  0.958, the four prior members' bands UNTOUCHED): `get` R^2 ~ 0.988, slope ~ 4.03
+  ns/level, in its OWN band `[2.55, 5.95]` = median-of-15 fit-runs (median 4.25) x
+  `[0.6, 1.4]`, centered on the median (ADR-0004). A treap descent touches one node per
+  level, so its per-level slope is lower than SkipList.get's (~8.78) -- expected, which
+  is why only the R^2 floor is shared. The linear-scan foil MISSES the floor
+  (R^2 ~ 0.79). All EIGHT gated op-rows are ON-LINE; MAX single insert disclosed
+  (~54 us on the cold shuffled build trace).
+- **Types + docs.** `LogN.d.ts` gains the `Treap` ambient block; `llms.txt` gains the
+  Treap roster entry + full export surface; `decisions/0007-treap.md` records D-06/D-07
+  (the balanced-BST pick, the augmentation, the NodePool reuse, the arena-sharing
+  split/merge, and the recursion-depth disclosure).
+
+### Verified
+
+- Torture: 0 B/op on every Treap hot lane (get / set / delete / rank / select /
+  successor / forEach / rangeIter) + the mixed steady-state churn; `gc major = 0`;
+  leak `size 0/0`; the private-pool conservation invariant after every soak cycle; a
+  32 B/op control lane proving the instrument has teeth. Prior four members still green.
+- `test/perf/PerfGate.test.mjs`: four Treap scenarios (get / set / delete / rank-select-
+  successor mix) at 0 scavenges, backing buffers fixed (the `grows` counter reads 0).
+- `test/Treap.test.mjs`: a >= 1e5 mixed-op differential fuzz vs a Map + sorted-array
+  oracle (0 divergences), the three treap invariants checked throughout (BST order,
+  heap order, subtree-size correctness), rank/select/split/merge correctness, the
+  fail-closed doors ([lite-logn] tag pinned), determinism, and conservation.
+- `LogN.js`: the prior four classes are BYTE-IDENTICAL; only the `VERSION` const and
+  the appended `Treap` section changed.
+
 ## [0.4.0] - 2026-09-17
 
 ### Added

package/LogN.d.ts

@@ -171,3 +171,58 @@ export class SkipList {
     /** Empty the list, keeping capacity (resets the PRNG to its initial seed). */
     clear(): this;
 }
+
+/**
+ * A treap: a randomized, self-balancing BST that is also an order-statistic tree (an
+ * AUGMENTED ordered map key -> value). BST order on keys x max-heap order on a per-node
+ * random priority gives EXPECTED O(log n) height; a subtree-size column adds O(log n)
+ * rank / select / split / merge. Nodes are slot INDICES in flat typed-array columns
+ * over a private free-list (no heap object 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. EXPECTED, not worst-case (an unlucky
+ * priority draw can spike one op; the MAX single insert is disclosed, not gated). Fixed
+ * capacity: a full pool throws. Every hot op allocates zero bytes.
+ */
+export class Treap {
+    /** @param capacity exact max live entries; integer in [1, 2^31-1].
+     *  @param seed PRNG seed; unsigned 32-bit integer (default fixed). */
+    constructor(capacity: number, seed?: number);
+
+    /** Live entry count. */
+    readonly size: number;
+    /** The fixed capacity this treap was sized for. */
+    readonly capacity: 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, treap: Treap) => void): void;
+    /** Empty the treap, keeping capacity (resets the PRNG to its initial seed). */
+    clear(): this;
+
+    /** Split at key into [left (keys < key), right (keys >= key)]; CONSUMES this and
+     *  returns two treaps SHARING this treap's backing arena. Non-finite key throws. */
+    split(key: number): [Treap, Treap];
+    /** Merge two arena-sharing treaps where every key of a < every key of b, CONSUMING
+     *  both. Non-Treap inputs, different arenas, or an overlapping range throw. */
+    static merge(a: Treap, b: Treap): Treap;
+}

package/LogN.js

@@ -39,7 +39,7 @@
  */
 
 /** Package version. One of the three version sites (package.json / VERSION / llms.txt). */
-export const VERSION = '0.4.0';
+export const VERSION = '0.5.0';
 
 // --- members land here, append-only, one tree-shakeable class each -----------
 // BinaryHeap  (v0.1.0 session) -- indexed O(log n) min|max heap  (BELOW)
@@ -1410,3 +1410,576 @@ export class SkipList {
         throw new RangeError('[lite-logn] SkipList full (capacity ' + this._cap + ')');
     }
 }
+
+// Treap (v0.5.0 session) -- an AUGMENTED randomized-balanced ordered map (BELOW).
+
+/** Treap default PRNG seed when the caller does not supply one. */
+const TR_DEFAULT_SEED = 0x9E3779B9;
+
+/**
+ * Max Treap capacity: `0x7FFFFFFF` (2^31 - 1). Every node is addressed by a slot
+ * INDEX stored in `Uint32Array` link columns (`_left` / `_right`), and each subtree
+ * count lives in a `Uint32Array` (`_size`); 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 TR_MAX_CAPACITY = 0x7FFFFFFF; // 2^31 - 1
+
+/**
+ * A TREAP: a randomized, self-balancing BINARY SEARCH TREE that is ALSO an order-
+ * statistic tree (an AUGMENTED ordered map key -> value). It is the family's second
+ * randomized member and its second pointer-based one; where SkipList threads a
+ * probabilistic tower of forward links, a treap keeps a single BST whose SHAPE is
+ * randomized by a per-node priority, giving EXPECTED O(log n) height. The trick that
+ * keeps it zero-GC is the SkipList one: nodes are slot INDICES in flat typed-array
+ * columns over the same private free-list (NodePool), never heap objects.
+ *
+ * Two orders held at once (the treap invariant):
+ *   - BST order on `_key` (an in-order walk is ascending by key); and
+ *   - MAX-HEAP order on `_prio` (every parent's priority >= its children's), where
+ *     `_prio` is one instance-local NR-LCG draw per inserted node. A random priority
+ *     heap over a BST is provably balanced IN EXPECTATION.
+ * 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` (how many
+ * keys are < x) and `select` (the k-th smallest key) are O(log n) via subtree counts.
+ *
+ * Storage (allocated once, sized to capacity + 1; slot 0 is the NIL sentinel whose
+ * `_size` is a permanent 0 -- null is not zero: slot 0 is "no subtree", never data):
+ *   - `_key` / `_value` `Float64Array` -- key and value at each slot.
+ *   - `_left` / `_right` `Uint32Array` -- child slot indices, `NIL = 0`.
+ *   - `_prio` `Uint32Array` -- the random heap priority at each slot.
+ *   - `_size` `Uint32Array` -- the subtree node count at each slot.
+ *   - `_pool` NodePool -- the free-list handing out slot indices [1, capacity].
+ *
+ * Honesty (randomized member): a hot op is EXPECTED O(log n), not worst-case -- the
+ * same contract as SkipList. An unlucky priority draw can build a tall thin tree and
+ * spike a single op; the MAX single insert (the rotation chain) is DISCLOSED, never
+ * gated (decisions/0007-treap.md, D-06). RECURSION DEPTH: `set` / `delete` / `split`
+ * / `merge` recurse over slot indices; the recursion depth equals the tree height,
+ * which is O(log n) EXPECTED and O(n) worst-case on a pathological priority draw.
+ * Because priorities come from the instance-local LCG (NOT caller-controlled), an
+ * adversary cannot force the worst case with chosen keys, so the expected bound holds
+ * for the fixed public surface -- this matches the EXPECTED contract and is DISCLOSED
+ * here + in the ADR, not silently shipped. The recursion uses the native call stack,
+ * not the GC heap, so every hot op is 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). 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.
+ *
+ * `split` / `merge` are O(log n) EXPECTED because they REWIRE nodes in place rather
+ * than copy: the two treaps a `split` returns (and the two a `merge` consumes) SHARE
+ * the source's backing arena (columns + free-list). `split` and `merge` therefore
+ * CONSUME their inputs (leaving them empty) and hand back views over the same store
+ * -- the only way to keep the structural ops sub-linear under a pooled allocator.
+ */
+export class Treap {
+    /**
+     * @param {number} capacity  exact max live entries; integer in [1, 2^31-1].
+     * @param {number} [seed]    PRNG seed; unsigned 32-bit integer (default fixed).
+     */
+    constructor(capacity, seed) {
+        // typeof guard BEFORE coercion (Number.isInteger is Symbol/BigInt-safe).
+        if (typeof capacity !== 'number' || !Number.isInteger(capacity) ||
+            capacity < 1 || capacity > TR_MAX_CAPACITY) {
+            throw new RangeError(
+                '[lite-logn] Treap capacity must be an integer in [1, 2^31-1], got ' +
+                String(capacity));
+        }
+        let s;
+        if (seed === undefined) {
+            s = TR_DEFAULT_SEED;
+        } else if (typeof seed !== 'number' || !Number.isInteger(seed) ||
+            seed < 0 || seed > 0xFFFFFFFF) {
+            throw new RangeError(
+                '[lite-logn] Treap seed must be an unsigned 32-bit integer, got ' +
+                String(seed));
+        } else {
+            s = seed >>> 0;
+        }
+        s = s | 0; // store the LCG state as a SIGNED int32 (an unboxed Smi) -- see _lcgNext
+        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._prio = new Uint32Array(capacity + 1);   // random heap priority
+        this._size = new Uint32Array(capacity + 1);   // subtree node count; _size[0] = 0
+        this._pool = new NodePool(capacity);          // free-list over slots [1, capacity]
+        this._root = 0;                               // NIL == empty tree
+        this._seed0 = s;                              // initial seed (clear resets to it)
+        this._seed = s;                               // live LCG state
+        this._version = 0;                            // iterator invalidation stamp
+        this._sr = 0;                                 // split scratch (the "right" root)
+    }
+
+    /** Live entry count. O(1) (the root subtree count). */
+    get size() { return this._root === 0 ? 0 : this._size[this._root]; }
+
+    /** The fixed capacity this treap was sized for. O(1). */
+    get capacity() { return this._cap; }
+
+    /**
+     * The value stored under `key`, or `undefined` if absent (never throws on a
+     * missing / empty query). EXPECTED O(log n): a plain BST descent. Fails closed on
+     * a non-number / non-finite key (typeof-guarded first) with a `[lite-logn]` throw.
+     * @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 treap. EXPECTED O(log n). 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). EXPECTED O(log n): a descent to check membership, then (on insert) a
+     * recursive splice that rotates the new node up until heap order is restored,
+     * fixing `_size` on the unwind. 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 L = this._left, R = this._right, K = this._key;
+        let t = this._root;
+        while (t !== 0) { // update in place if present -- no new node, no rebalance
+            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;
+        this._size[slot] = 1;
+        this._seed = _lcgNext(this._seed);
+        this._prio[slot] = this._seed; // stored unsigned in the Uint32 column
+        this._root = this._insert(this._root, slot);
+        this._version = (this._version + 1) | 0;
+        return this;
+    }
+
+    /**
+     * Remove `key`. EXPECTED O(log n). Idempotent: returns `false` if `key` is absent
+     * (no throw), `true` if it was present and removed. Deletion MERGES the removed
+     * node's two subtrees (priority-ordered) then frees its slot, fixing `_size` on
+     * the unwind. Fails closed on a non-finite key (typeof-guarded first).
+     * @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;
+        return true;
+    }
+
+    /**
+     * The number of stored keys STRICTLY LESS than `x` (its rank / position). EXPECTED
+     * O(log n) via subtree counts: at each node, when the node's key is < `x`, its
+     * whole left subtree plus itself precede `x`. `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). EXPECTED 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` (matching the soft-miss of `get`).
+     * @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);
+        if (k < 0 || k >= this.size) 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. EXPECTED
+     * 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. EXPECTED
+     * 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 treap'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] Treap 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), 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, treap:Treap)=>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 treap, keeping the fixed capacity. O(capacity) cold path: returns
+     * every node to the pool, points the root at NIL, and restores the PRNG to its
+     * initial seed (a cleared treap replays a fresh one). @returns {this}
+     */
+    clear() {
+        this._pool.clear();
+        this._root = 0;
+        this._seed = this._seed0;
+        this._version = (this._version + 1) | 0;
+        return this;
+    }
+
+    /**
+     * SPLIT `this` at `key` into two treaps: `[left, right]` where `left` holds every
+     * key STRICTLY LESS than `key` and `right` holds every key >= `key`. EXPECTED
+     * O(log n) -- it REWIRES nodes in place (no copy), so the returned treaps SHARE
+     * this treap's backing arena, and `this` is CONSUMED (left empty). Fails closed on
+     * a non-finite key.
+     * @param {number} key  a finite number
+     * @returns {[Treap, Treap]}  [keys < key, keys >= key]
+     */
+    split(key) {
+        if (typeof key !== 'number' || !Number.isFinite(key)) return this._badKey(key);
+        const l = this._split(this._root, key);
+        const r = this._sr;
+        const left = Treap._view(this, l);
+        const right = Treap._view(this, r);
+        this._root = 0; // consumed: its nodes now belong to left / right
+        this._version = (this._version + 1) | 0;
+        return [left, right];
+    }
+
+    /**
+     * MERGE two treaps `a` and `b` -- where EVERY key of `a` is STRICTLY LESS than
+     * every key of `b` -- into one, returning it. EXPECTED O(log n): it rewires nodes
+     * in place, so `a` and `b` MUST share a backing arena (i.e. both came from a prior
+     * `split`), and BOTH are CONSUMED. Fails closed: non-Treap inputs, treaps from
+     * different arenas, or an overlapping key range each throw `[lite-logn]`.
+     * @param {Treap} a  all keys strictly less than every key of b
+     * @param {Treap} b  all keys strictly greater than every key of a
+     * @returns {Treap}
+     */
+    static merge(a, b) {
+        if (!(a instanceof Treap) || !(b instanceof Treap)) {
+            throw new TypeError('[lite-logn] Treap.merge needs two Treap instances');
+        }
+        if (a._key !== b._key) {
+            throw new Error(
+                '[lite-logn] Treap.merge requires two treaps sharing an arena (from the same split)');
+        }
+        if (a._root !== 0 && b._root !== 0) {
+            let m = a._root; while (a._right[m] !== 0) m = a._right[m]; // max key of a
+            let n = b._root; while (b._left[n] !== 0) n = b._left[n];   // min key of b
+            if (a._key[m] >= b._key[n]) {
+                throw new Error(
+                    '[lite-logn] Treap.merge requires all keys of a < all keys of b');
+            }
+        }
+        const root = a._merge(a._root, b._root);
+        const out = Treap._view(a, root);
+        a._root = 0; b._root = 0; // both consumed
+        a._version = (a._version + 1) | 0;
+        b._version = (b._version + 1) | 0;
+        return out;
+    }
+
+    // ---- private rotations + recursive structure (hot bodies) ---------------
+
+    /**
+     * @private true iff node `a` outranks node `b` in the priority MAX-heap. Priority
+     * ties (astronomically rare across 32-bit LCG draws) break by key, so the tree
+     * shape is a deterministic function of the (key, priority) set -- never ambiguous.
+     */
+    _higher(a, b) {
+        const pa = this._prio[a], pb = this._prio[b];
+        return pa > pb || (pa === pb && this._key[a] < this._key[b]);
+    }
+
+    /**
+     * @private right rotation: `y`'s left child `x` becomes the subtree root. Rewrites
+     * two child links and recomputes the two affected `_size` cells. Returns `x`.
+     */
+    _rotR(y) {
+        const L = this._left, R = this._right, S = this._size;
+        const x = L[y];
+        L[y] = R[x];
+        R[x] = y;
+        S[y] = S[L[y]] + S[R[y]] + 1;
+        S[x] = S[L[x]] + S[R[x]] + 1;
+        return x;
+    }
+
+    /**
+     * @private left rotation: `y`'s right child `x` becomes the subtree root. Rewrites
+     * two child links and recomputes the two affected `_size` cells. Returns `x`.
+     */
+    _rotL(y) {
+        const L = this._left, R = this._right, S = this._size;
+        const x = R[y];
+        R[y] = L[x];
+        L[x] = y;
+        S[y] = S[L[y]] + S[R[y]] + 1;
+        S[x] = S[L[x]] + S[R[x]] + 1;
+        return x;
+    }
+
+    /** @private recursive BST insert of leaf slot `s`, rotating up to fix heap order. */
+    _insert(t, s) {
+        if (t === 0) return s; // s already has size 1, NIL children, its priority set
+        const L = this._left, R = this._right, S = this._size, K = this._key;
+        if (K[s] < K[t]) {
+            L[t] = this._insert(L[t], s);
+            S[t] = S[L[t]] + S[R[t]] + 1;
+            if (this._higher(L[t], t)) return this._rotR(t);
+        } else {
+            R[t] = this._insert(R[t], s);
+            S[t] = S[L[t]] + S[R[t]] + 1;
+            if (this._higher(R[t], t)) return this._rotL(t);
+        }
+        return t;
+    }
+
+    /** @private recursive delete of `key` from subtree `t`; frees the removed slot. */
+    _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;
+        }
+        const merged = this._merge(L[t], R[t]); // t removed: fuse its two subtrees
+        this._pool.free(t);
+        return merged;
+    }
+
+    /** @private recursive priority merge of two subtrees (all keys in a < all in b). */
+    _merge(a, b) {
+        if (a === 0) return b;
+        if (b === 0) return a;
+        const L = this._left, R = this._right, S = this._size;
+        if (this._higher(a, b)) {
+            R[a] = this._merge(R[a], b);
+            S[a] = S[L[a]] + S[R[a]] + 1;
+            return a;
+        }
+        L[b] = this._merge(a, L[b]);
+        S[b] = S[L[b]] + S[R[b]] + 1;
+        return b;
+    }
+
+    /**
+     * @private recursive split of subtree `t` by `key`. Returns the LEFT root (keys <
+     * key); the RIGHT root (keys >= key) is left in `this._sr` (read by the caller
+     * immediately, before any sibling recursion, so a single scratch field suffices).
+     */
+    _split(t, key) {
+        if (t === 0) { this._sr = 0; return 0; }
+        const L = this._left, R = this._right, K = this._key, S = this._size;
+        if (K[t] < key) {
+            const l1 = this._split(R[t], key); // this._sr := the right part
+            R[t] = l1;
+            S[t] = S[L[t]] + S[R[t]] + 1;
+            return t;                          // pair (t, this._sr)
+        }
+        const l1 = this._split(L[t], key);     // this._sr := R1 ; l1 := L1
+        L[t] = this._sr;
+        S[t] = S[L[t]] + S[R[t]] + 1;
+        this._sr = t;
+        return l1;                             // pair (l1, 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;
+    }
+
+    /** @private build a Treap VIEW sharing `src`'s arena with a given root (split/merge). */
+    static _view(src, root) {
+        const t = Object.create(Treap.prototype);
+        t._cap = src._cap;
+        t._key = src._key; t._value = src._value;
+        t._left = src._left; t._right = src._right;
+        t._prio = src._prio; t._size = src._size;
+        t._pool = src._pool;
+        t._root = root;
+        t._seed0 = src._seed0; t._seed = src._seed;
+        t._version = 0; t._sr = 0;
+        return t;
+    }
+
+    // ---- cold path only: throw builders (string concat off the hot body) ----
+
+    /** @private */
+    _badKey(key) {
+        throw new TypeError(
+            '[lite-logn] Treap key must be a finite number, got ' + String(key));
+    }
+
+    /** @private */
+    _badValue(value) {
+        throw new TypeError(
+            '[lite-logn] Treap value must be a finite number, got ' + String(value));
+    }
+
+    /** @private */
+    _badRank(k) {
+        throw new TypeError(
+            '[lite-logn] Treap select index must be an integer, got ' + String(k));
+    }
+
+    /** @private */
+    _badBound(b) {
+        throw new TypeError(
+            '[lite-logn] Treap rangeIter bound must be a number (not NaN), got ' + String(b));
+    }
+
+    /** @private */
+    _badRange(lo, hi) {
+        throw new RangeError(
+            '[lite-logn] Treap rangeIter needs lo <= hi, got lo=' + String(lo) +
+            ' hi=' + String(hi));
+    }
+
+    /** @private */
+    _full() {
+        throw new RangeError('[lite-logn] Treap 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.4.0 ships four 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), and SkipList (pointer-free expected-O(log n) ordered map over a private free-list node pool) -- 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.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.
 
 [![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.4.0 ships four members: BinaryHeap, Fenwick, SegmentTree and SkipList.** Members land one per session, each append-only so prior members stay byte-identical. The planned roster below fills in per release.
+**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.
 
 ```bash
 npm install @zakkster/lite-logn
@@ -53,12 +53,14 @@ Every hot op allocates zero bytes after construction, and `npm run witness` prov
 - [What you get](#what-you-get)
 - [The roster](#the-roster)
 - [The O(log n) Witness](#the-olog-n-witness)
+- [Benchmarks](#benchmarks)
 - [API reference](#api-reference)
   - [Constants](#constants)
   - [BinaryHeap](#binaryheap)
   - [Fenwick](#fenwick)
   - [SegmentTree](#segmenttree)
   - [SkipList](#skiplist)
+  - [Treap](#treap)
 - [Zero-GC design notes](#zero-gc-design-notes)
 - [Testing](#testing)
 - [What this is not](#what-this-is-not)
@@ -83,7 +85,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.4.0, BinaryHeap, Fenwick, SegmentTree and SkipList are shipped.
+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.
 
 | Member | Version | Status | Shape | Hot ops |
 | --- | --- | --- | --- | --- |
@@ -91,8 +93,9 @@ One member per session, each landing append-only (prior members stay byte-identi
 | **Fenwick** (BIT) | 0.2.0 | shipped | flat `Float64Array`, lowest-set-bit walk (`i & -i`) | `update` / `prefix` / `rangeSum` / `at` / `set` O(log n) |
 | **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` |
 
-Later tiers (Treap / Scapegoat, OrderStatTree, IndexedHeap, SortedArray, MinMaxHeap, SplayTree, and presets) are queued in [`ROADMAP.md`](./ROADMAP.md).
+Later tiers (Scapegoat, OrderStatTree, IndexedHeap, SortedArray, MinMaxHeap, SplayTree, and presets) are queued in [`ROADMAP.md`](./ROADMAP.md).
 
 ## The O(log n) Witness
 
@@ -102,7 +105,81 @@ 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.4.0 the witness gates seven 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]`), and 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]`) all ON the line. 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.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.
+
+## Benchmarks
+
+A repo-only, eight-dimension benchmark suite (`benchmark/`, ADOPTED field-for-field from `@zakkster/lite-o1`'s "Bench v2") surrounds the witness anchor. It is dev infra: NOT in the published tarball, imports NOTHING from the package but `LogN.js`, and spawns one child process per `(member x dimension)` cell for a clean GC/JIT state. **D1 is the O(log n) Witness itself** -- it DELEGATES to the shipped `test/witness.mjs` (the same frozen kernels, per-op sweeps, `R^2` floor and slope bands), so the headline dimension never re-implements the fit. Run it yourself:
+
+```sh
+npm run bench            # 32 cells -> benchmark/results.json + summary tables
+npm run bench:report     # the above, then benchmark/report.html (hand-rolled inline-SVG graphs)
+```
+
+Numbers below are one run on an Apple M4 Pro (arm64), Node v26 -- machine-specific, reproducible from a fixed seed (`0x9e3779b1`). Every applicable cell is a positive number; every inapplicable cell is the string `n/a` (never a numeric 0).
+
+### D1 -- the O(log n) Witness fit (per gated op-row)
+
+Each op fits `nsPerOp = intercept + slope*log2(n)`. ON-LINE = `R^2 >= 0.958` (the frozen family floor) AND `slope` inside the member's per-op band; the O(n) foil MUST leave the line (`foil R^2 < 0.958`). All eight op-rows sit ON the line; all eight foils leave it.
+
+<svg width="640" height="200" viewBox="0 0 640 200" role="img" aria-label="D1 slope per op-row (ns/level)" xmlns="http://www.w3.org/2000/svg">
+  <text x="8" y="16" font-size="12" fill="#475569">D1 slope (ns/level) -- lower is a cheaper per-level cost</text>
+  <g font-size="10" fill="#334155" text-anchor="middle">
+    <rect x="24"  y="84"  width="60" height="96"  fill="#2563eb"/><text x="54"  y="194">BH.pop 8.4</text>
+    <rect x="112" y="148" width="60" height="32"  fill="#059669"/><text x="142" y="194">Fen.upd 2.8</text>
+    <rect x="200" y="150" width="60" height="30"  fill="#059669"/><text x="230" y="194">Fen.pre 2.6</text>
+    <rect x="288" y="145" width="60" height="35"  fill="#d97706"/><text x="318" y="194">Seg.upd 3.1</text>
+    <rect x="376" y="99"  width="60" height="81"  fill="#d97706"/><text x="406" y="194">Seg.qry 7.0</text>
+    <rect x="464" y="88"  width="60" height="92"  fill="#7c3aed"/><text x="494" y="194">SL.get 8.0</text>
+    <rect x="552" y="40"  width="60" height="140" fill="#7c3aed"/><text x="582" y="194">SL.set 12.1</text>
+  </g>
+</svg>
+
+| op-row | `R^2` | slope (ns/level) | slope band | on line? | foil | foil `R^2` | foil off? |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `BinaryHeap.pop` | 0.996 | 8.4 | `[5.76, 13.44]` | ON | sorted-array insert | 0.83 | off |
+| `Fenwick.update` | 0.980 | 2.8 | `[1.84, 4.30]` | ON | prefix-array rebuild | 0.76 | off |
+| `Fenwick.prefix` | 0.968 | 2.6 | `[1.76, 4.10]` | ON | naive re-sum | 0.75 | off |
+| `SegmentTree.update` | 0.989 | 3.1 | `[2.29, 5.35]` | ON | whole-tree rebuild | 0.82 | off |
+| `SegmentTree.query` | 0.998 | 7.0 | `[4.30, 10.04]` | ON | scan-fold | 0.73 | off |
+| `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 |
+
+**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).
+
+### D3 -- memory (bytes / live vs a theoretical floor)
+
+| member | peak bytes @ 64Ki | B/live | theo min | overhead x | note |
+| --- | --- | --- | --- | --- | --- |
+| BinaryHeap | 1,048,576 | 16.0 | 12 | 1.33 | key (8) + id (4) dense; `_pos` reverse map is the universe overhead |
+| Fenwick | 524,296 | 8.0 | 8 | 1.00 | one `Float64` tree cell per element -- exact |
+| SegmentTree | 1,048,576 | 16.0 | 16 | 1.00 | the `2n` array -- exact |
+| SkipList | 5,767,320 | 88.0 | 16 | 5.50 | key + value dense; the `ceil(log2 cap)+1` link columns are the tower overhead |
+
+The overhead-x load-factor curve RISES as load falls for BinaryHeap + SkipList (fixed backing over fewer live) and is FLAT for the INDEX-ADDRESSED Fenwick + SegmentTree (every cell is always live) -- another honest `n/a` where insertion order does not apply.
+
+### D5 -- bundle size + tree-shaking (esbuild min + gzip)
+
+A single-member import must be `< 40%` of the all-member import. Three of four clear it; SkipList (the heaviest lone member) is the ONE honest exception at `~41%` -- stated, not rounded down, and never by moving the budget. The median lone-import ratio is `~0.32 (< 0.40)`; every member's lone import still drops the majority of the others (`< 0.50`).
+
+| member | single gz (B) | all gz (B) | ratio | `< 40%`? |
+| --- | --- | --- | --- | --- |
+| BinaryHeap | 1,365 | 3,758 | 0.363 | yes |
+| Fenwick | 826 | 3,758 | 0.220 | yes |
+| SegmentTree | 1,071 | 3,758 | 0.285 | yes |
+| SkipList | 1,546 | 3,758 | 0.411 | NO (the stated exception) |
+
+### D6 -- GC pressure (the 0 B/op gate as a curve, per op-row)
+
+All seven gated op-rows report **0 B/op** across the `n = 1e3..1e6` sweep, with `max major GC = 0`. The precise proof stays `node --expose-gc test/torture.mjs` (via `@zakkster/lite-gc-profiler`); D6 is the portable curve (min heap-delta over independent passes -- heap-accounting jitter only ADDS, so a truly-zero kernel hits 0 on its best pass while a per-op allocator stays positive on every pass).
+
+### The other dimensions
+
+- **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).
 
 ## API reference
 
@@ -110,7 +187,7 @@ For amortized / randomized members the witness also prints the MAX single-op tim
 
 | Export | Type | Value | Meaning |
 | --- | --- | --- | --- |
-| `VERSION` | `string` | `'0.4.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.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. |
 
 ### BinaryHeap
 
@@ -256,6 +333,45 @@ sl.delete(50);         // -> true (idempotent: false if absent)
 | `clear` | `clear() -> this` | O(capacity) | Empties the list, keeps capacity, resets the PRNG to its initial seed. |
 | `size` / `capacity` | getters | O(1) | Live entry count / fixed capacity. |
 
+### Treap
+
+A **treap**: a randomized, self-balancing **binary search tree** that is also an **order-statistic tree** -- an AUGMENTED ordered map (key -> value) -- the family's balanced BST. It holds two orders at once: a **BST order** on the key and a **max-heap order** on a per-node random priority; a random-priority heap over a BST is provably balanced **in expectation**, so `get` / `set` / `delete` are **expected O(log n)**. A third invariant, a subtree-size column maintained in the SAME pass as every link rewrite, adds `rank(x)` (how many keys are `< x`), `select(k)` (the k-th smallest key), and O(log n) `split` / `merge`. Nodes are slot **indices** in six flat columns (`_key` / `_value` `Float64`; `_left` / `_right` / `_prio` / `_size` `Uint32`, `NIL = 0`) over the SAME private free-list (`NodePool`) SkipList uses -- design-parity, never a heap object per op. Priority is one instance-local Numerical-Recipes LCG draw per insert (deterministic from a seed; ties break by key). 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.
+
+Honesty note: the hot ops are **expected** O(log n), not worst-case -- an unlucky priority draw can build a tall thin tree and spike a single op (the rotation chain). The witness fits the clean average line **and** separately prints the MAX single insert. `set` / `delete` / `split` / `merge` recurse to a depth equal to the tree height (O(log n) expected, O(n) worst-case) on the native call stack -- but priorities come from the instance-local LCG, NOT caller-chosen keys, so an adversary cannot force the worst case through the public surface; the recursion allocates zero heap bytes (see [`decisions/0007-treap.md`](./decisions/0007-treap.md)).
+
+```js
+import { Treap } from '@zakkster/lite-logn';
+
+const tr = new Treap(1000, 42);   // capacity 1000, seed 42 (deterministic)
+tr.set(50, 500);                  // insert key 50 -> value 500
+tr.set(20, 200);
+tr.set(80, 800);
+tr.get(20);            // -> 200
+tr.rank(50);           // -> 1    (one key, 20, is strictly less than 50)
+tr.select(0);          // -> 20   (the smallest key)
+tr.successor(20);      // -> 50   (smallest key strictly greater)
+const [lo, hi] = tr.split(50);    // lo: keys < 50; hi: keys >= 50 (share the arena; tr consumed)
+const whole = Treap.merge(lo, hi);// fuse back (all lo keys < all hi keys); both consumed
+```
+
+| Member | Signature | Complexity | Notes |
+| --- | --- | --- | --- |
+| constructor | `new Treap(capacity, seed?)` | O(capacity) | `capacity` integer in `[1, 2^31-1]` (slot indices + subtree counts are `Uint32`, `NIL = 0` reserves slot 0); `seed` an unsigned 32-bit integer (default fixed). Allocates the six columns + private pool once. |
+| `get` | `get(key) -> number \| undefined` | expected O(log n) | The value under `key`, or `undefined` if absent (no throw). Non-finite key throws. |
+| `has` | `has(key) -> boolean` | expected O(log n) | True iff `key` is stored. Non-finite key throws. |
+| `set` | `set(key, value) -> this` | expected O(log n) | Insert `key -> value`, or update the value in place if `key` exists. Non-finite key/value throws; a full pool throws. |
+| `delete` | `delete(key) -> boolean` | expected O(log n) | Idempotent: `false` if absent, `true` if removed. Non-finite key throws. |
+| `rank` | `rank(x) -> number` | expected 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` | expected 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` | expected O(log n) | The smallest key STRICTLY greater than `key`, or `undefined`. |
+| `predecessor` | `predecessor(key) -> number \| undefined` | expected 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, treap)` in ascending key order. |
+| `clear` | `clear() -> this` | O(capacity) | Empties the treap, keeps capacity, resets the PRNG to its initial seed. |
+| `split` | `split(key) -> [Treap, Treap]` | expected O(log n) | `[left (keys < key), right (keys >= key)]`; rewires in place, so the two treaps SHARE this treap's arena and this is CONSUMED (left empty). |
+| `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. |
+
 Member signatures for later members are appended here as each ships.
 
 ## Zero-GC design notes
@@ -278,8 +394,13 @@ Member signatures for later members are appended here as each ships.
 | `SkipList` constructor / `clear` | O(capacity) typed arrays + pool, once (cold) |
 | `SkipList` forEach | 0 B/op in the loop body (pass a hoisted callback) |
 | `SkipList` rangeIter | one iterator + `{value, done}` per step (the documented per-protocol allocator; transient, not retained) |
+| `Treap` get / has / set / delete / rank / select / successor / predecessor | 0 B/op (nodes are slot indices; the recursive set/delete run on the native call stack, not the heap) |
+| `Treap` constructor / `clear` | O(capacity) six columns + pool, once (cold) |
+| `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) |
 
-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]`). 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]`). The allocation table is extended per member as each lands.
 
 ## Testing
 

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-logn
 
-Version: 0.4.0
+Version: 0.5.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -19,7 +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. The roster (one member per session, each landing append-only):
+adds SkipList; v0.5.0 adds Treap. 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,
@@ -47,6 +48,17 @@ adds SkipList. The roster (one member per session, each landing append-only):
   seed, deterministic. set updates an existing key's value in place. EXPECTED (not
   worst-case) O(log n): the witness fits the average line AND prints the MAX single
   insert. Zero allocation on every hot op.
+- Treap (v0.5.0) -- an AUGMENTED ordered map (key -> value) that is also an order-
+  statistic tree: a randomized, self-balancing BST (BST order on keys x max-heap order
+  on a per-node random priority -> EXPECTED O(log n) height) with a subtree-size column
+  that adds rank(x) (count of keys < x) / select(k) (the k-th smallest key) / split(key)
+  / merge(a, b), all EXPECTED O(log n). Nodes are slot INDICES in flat typed-array
+  columns (_key / _value / _left / _right / _prio / _size) over the SAME private free-
+  list (NodePool) SkipList uses. Priority is one instance-local NR-LCG draw per insert
+  (deterministic, seed-reproducible; ties break by key). set updates an existing key's
+  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.
 
 ## Exports (from the single main file LogN.js)
 
@@ -141,6 +153,42 @@ adds SkipList. The roster (one member per session, each landing append-only):
   - `size` / `capacity` getters; `clear()` -> this (empty, keep capacity, reset the
     PRNG to its initial seed); `forEach(fn)` visits (key, value, list) ascending.
 
+- `Treap` -- class. A randomized-balanced AUGMENTED ordered map (key -> value) that is
+  also an order-statistic tree. A BST on `_key` x a max-heap on a per-node random
+  `_prio` gives EXPECTED O(log n) height; a `_size` subtree-count column adds O(log n)
+  order statistics. Nodes are slot INDICES in flat typed-array columns (`_key` /
+  `_value` Float64, `_left` / `_right` / `_prio` / `_size` Uint32, `NIL = 0`) over a
+  PRIVATE free-list (NodePool) -- no heap object per op. Keys and values are finite
+  numbers (typeof-guarded before coercion; Symbol / BigInt / NaN / +-Infinity fail
+  closed). EXPECTED, not worst-case (an unlucky priority draw can spike one op; the MAX
+  single insert is disclosed). set / delete / split / merge recurse to a depth = tree
+  height (O(log n) expected, O(n) worst-case on a pathological priority draw), on the
+  native call stack, so every hot op is still 0 B/op.
+  - `new Treap(capacity, seed?)` -- capacity an integer in [1, 2^31-1] (slot indices +
+    subtree counts are Uint32, `NIL = 0` reserves slot 0); seed an unsigned 32-bit
+    integer (default fixed). Allocates six columns + a free-list 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). 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` getters; `clear()` -> this (empty, keep capacity, reset the
+    PRNG to its initial seed); `forEach(fn)` visits (key, value, treap) ascending.
+  - `split(key)` -> [left, right]. left holds keys < key, right holds keys >= key;
+    O(log n) EXPECTED (rewires in place), so the two treaps SHARE this treap's arena
+    and this is CONSUMED (left empty).
+  - `Treap.merge(a, b)` -> Treap. Merge two arena-sharing treaps where every key of a
+    < every key of b; O(log n) EXPECTED, CONSUMES both. Non-Treap inputs, treaps from
+    different arenas, or an overlapping key range each throw.
+
 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.4.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), and SkipList (pointer-free expected-O(log n) ordered map over a private free-list node pool) 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.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.",
   "type": "module",
   "main": "./LogN.js",
   "module": "./LogN.js",
@@ -24,13 +24,15 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/*.test.js test/Bench.test.mjs",
+    "test": "node --test test/*.test.js test/*.test.mjs",
     "test:types": "tsc -p test/types/tsconfig.json",
     "torture": "node --expose-gc test/torture.mjs",
     "witness": "node test/witness.mjs",
     "test:perf": "node --expose-gc --max-semi-space-size=4 --test test/perf/PerfGate.test.mjs",
     "bench": "node benchmark/Bench.mjs",
     "bench:report": "node benchmark/Bench.mjs && node benchmark/Report.mjs",
+    "demo": "node --expose-gc --test demo/Demo.test.mjs",
+    "demo:serve": "node demo/serve.mjs",
     "verify": "npm test && npm run test:types && npm run torture && npm run witness && npm run test:perf"
   },
   "keywords": [
@@ -46,7 +48,9 @@
     "range-query",
     "range-sum",
     "skip-list",
+    "treap",
     "ordered-set",
+    "ordered-map",
     "balanced-bst",
     "bst",
     "log-n",