@zakkster/lite-logn 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,63 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-17
+
+### Added
+
+- **SkipList** -- the fourth member and the family's FIRST randomized, pointer-based
+  member: a pointer-free ordered map (key -> value) whose `get` / `set` / `delete` /
+  `successor` / `predecessor` are EXPECTED O(log n) via a probabilistic tower of
+  forward links stored as slot INDICES in a SINGLE flat `Uint32Array` of
+  `columns * (capacity + 1)` cells (stride-indexed `lvl*(capacity + 1) + slot`,
+  `NIL = 0`, slot 0 the head sentinel) over a private free-list (`NodePool`) -- never
+  a heap object per op. Surface: `get` / `set` (updates the value in place on an
+  existing key) / `delete` (idempotent) / `successor` (strictly greater) /
+  `predecessor` (strictly less) / `rangeIter(lo, hi)` (a VERSION-STAMPED iterator
+  over `[lo, hi]` inclusive, ascending; `+-Infinity` bounds allowed, mutation
+  mid-iteration throws) / `forEach` / `clear`, and `size` / `capacity` getters. Keys
+  are finite numbers (typeof-guarded before coercion -- Symbol / BigInt / NaN /
+  +-Infinity fail closed with a `[lite-logn]` throw); values are finite numbers.
+  Level generation is ONE step of the repo's Numerical-Recipes LCG whose HIGH bits
+  draw a geometric height (`1 + clz32(word)`), instance-local seed, deterministic (a
+  fixed seed replays an identical structure; the low bits of the LCG are periodic, so
+  the high bits are used -- validated by a deterministic chi-square test, df = 15,
+  p > 0.001, over ~1e6 levels). `SL_MAX_CAPACITY = 0x03FFFFFF` (2^26 - 1: slot
+  indices fit a `Uint32`, `NIL = 0` reserves slot 0, and the column stride stays an
+  addressable length). Level columns are sized to `ceil(log2 cap) + 1` up front (NOT
+  grown lazily), so `_next` never reallocates -- trivially 0 B/op. `get` / `set` /
+  `delete` / `successor` / `predecessor` allocate zero bytes after construction.
+  Verified: torture 0 B/op on every hot lane (+ a 32 B/op control lane proving the
+  instrument has teeth), the private-pool conservation invariant `activeSlots +
+  freeListLength === capacity` after every soak cycle, leak `size 0/0`,
+  `gc major = 0`.
+- **Witness: two more log lines.** `test/witness.mjs` gains SkipList's `get` and
+  `set` entries. Measured on this machine (shared R^2 floor 0.958): `get` R^2 ~
+  0.97-0.99, slope ~ 9 ns/level (band `[5.27, 12.30]`, median 8.78 x [0.6, 1.4]),
+  gated over `[2^11, 2^17]` for dynamic range; `set` R^2 ~ 0.97-0.99, slope ~ 14
+  ns/level (band `[8.36, 19.50]`, median 13.93 x [0.6, 1.4]), gated over the
+  cache-resident `[2^9, 2^14]` so the fit sees the structural level count, not DRAM
+  latency (each op is measured where its logarithm is visible, not where the cache
+  wall is). Both O(n) foils leave the line: the linear-scan search foil (O(n) per
+  search) and the sorted-array insert foil (O(n) shift), each below the floor.
+  Because the member 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.
+- **ADR.** [`decisions/0006-skiplist.md`](./decisions/0006-skiplist.md) (D-06):
+  binds D-01 to an IN-FILE PRIVATE `NodePool` as DESIGN-PARITY with lite-o1's private
+  pools (identical free-list contract + conservation invariant), NOT a runtime dep on
+  lite-o1 (rejected: zero-runtime-deps law; SlotPool never shipped); records the PRNG
+  choice (NR LCG, high bits for the level), the randomized-honesty note (MAX
+  single-op + chi-square df), and the level-column memory decision (size up front,
+  never grow lazily, to protect the 0-B/op gate).
+
+### Unchanged
+
+- **BinaryHeap, Fenwick and SegmentTree are byte-identical.** The v0.1.0 / v0.2.0 /
+  v0.3.0 member class bodies are untouched; only the file header roster, the
+  `VERSION` const, and the appended SkipList block (plus the `_lcgNext` / `NodePool`
+  / `_levelCap` helpers) changed in `LogN.js`.
+
 ## [0.3.0] - 2026-09-17
 
 ### Added
@@ -125,7 +182,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   [`decisions/0003-pack.md`](./decisions/0003-pack.md) (D-07: `files[]` ships the
   six files only; `test/`, `benchmark/`, `decisions/`, `demo/` are repo-only).
 
-[Unreleased]: https://github.com/PeshoVurtoleta/lite-logn/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/PeshoVurtoleta/lite-logn/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/PeshoVurtoleta/lite-logn/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/PeshoVurtoleta/lite-logn/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/PeshoVurtoleta/lite-logn/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/PeshoVurtoleta/lite-logn/releases/tag/v0.1.0

package/LogN.d.ts

@@ -130,3 +130,44 @@ export class SegmentTree {
     /** O(n) bottom-up bulk build from a finite-number array-like and a fold kind. */
     static build(values: ArrayLike<number>, kind: 'min' | 'max' | 'sum' | 'gcd'): SegmentTree;
 }
+
+/**
+ * A skip list: a pointer-free ordered map (key -> value) whose get / set / delete /
+ * successor / predecessor are EXPECTED O(log n) via a probabilistic tower of forward
+ * links stored as slot INDICES in flat Uint32Array columns over a private free-list
+ * (no heap objects per op). Keys are finite numbers (typeof-guarded before coercion;
+ * Symbol / BigInt / NaN / +-Infinity fail closed); values are finite numbers. set on
+ * an existing key updates the value in place. An unsupplied seed defaults to a fixed
+ * constant; a fixed seed replays an identical structure. Fixed capacity: a full pool
+ * throws. Every hot op allocates zero bytes.
+ */
+export class SkipList {
+    /** @param capacity exact max live entries; integer in [1, 2^26-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 list 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;
+    /** 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;
+    /** 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, list: SkipList) => void): void;
+    /** Empty the list, keeping capacity (resets the PRNG to its initial seed). */
+    clear(): this;
+}

package/LogN.js

@@ -12,15 +12,19 @@
  * the lowest-set-bit walk (`i & -i`). v0.3.0 adds the THIRD member: SegmentTree,
  * a flat `Float64Array(2n)` (leaves at n..2n-1) whose range-query AND point-update
  * are BOTH O(log n) via iterative bottom-up walks, with the associative fold
- * (min / max / sum / gcd) chosen ONCE at construction. Members land append-only,
- * leaving this header and the `VERSION` const the only prior lines that ever
- * change. Roster: BinaryHeap (v0.1.0, array-embedded O(log n) push / pop min|max
- * heap), Fenwick / BIT (v0.2.0, O(log n) point-update AND prefix-sum via the
- * `i & -i` walk), SegmentTree (v0.3.0, O(log n) associative range-query +
- * point-update over a flat 2n array, fold chosen at construction), and
- * SkipList (planned, pointer-free expected-O(log n) ordered map). Members are
- * independent (no shared mutable module state), so a bundler that imports one
- * drops the others (`sideEffects: false`).
+ * (min / max / sum / gcd) chosen ONCE at construction. v0.4.0 adds the FOURTH
+ * member: SkipList, a pointer-free ordered map (get / set / delete / successor /
+ * predecessor / rangeIter) whose links are slot INDICES in flat `Uint32Array`
+ * columns over a private free-list (NodePool), giving EXPECTED O(log n) with zero
+ * per-op allocation and a deterministic instance-local PRNG. Members land
+ * append-only, leaving this header and the `VERSION` const the only prior lines
+ * that ever change. Roster: BinaryHeap (v0.1.0, array-embedded O(log n) push / pop
+ * min|max heap), Fenwick / BIT (v0.2.0, O(log n) point-update AND prefix-sum via
+ * the `i & -i` walk), SegmentTree (v0.3.0, O(log n) associative range-query +
+ * point-update over a flat 2n array, fold chosen at construction), and SkipList
+ * (v0.4.0, pointer-free expected-O(log n) ordered map over a private free-list
+ * node pool). Members are independent (no shared mutable module state), so a
+ * bundler that imports one drops the others (`sideEffects: false`).
  *
  * The family delta: 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
@@ -35,13 +39,13 @@
  */
 
 /** Package version. One of the three version sites (package.json / VERSION / llms.txt). */
-export const VERSION = '0.3.0';
+export const VERSION = '0.4.0';
 
 // --- members land here, append-only, one tree-shakeable class each -----------
 // BinaryHeap  (v0.1.0 session) -- indexed O(log n) min|max heap  (BELOW)
 // Fenwick     (v0.2.0 session) -- O(log n) point-update + prefix-sum  (BELOW)
 // SegmentTree (v0.3.0 session) -- O(log n) associative range-query + point-update  (BELOW)
-// SkipList    (v0.4.0)         -- pointer-free expected-O(log n) ordered map
+// SkipList    (v0.4.0 session) -- pointer-free expected-O(log n) ordered map  (BELOW)
 
 /** Max heap capacity: slot indices 0..cap-1 must fit the Int32Array _pos map. */
 const BH_MAX_CAPACITY = 0x7FFFFFFF; // 2^31 - 1
@@ -932,3 +936,477 @@ export class SegmentTree {
             '[lite-logn] SegmentTree gcd value must be a nonnegative integer, got ' + String(value));
     }
 }
+
+/**
+ * Advance a 32-bit Numerical-Recipes LCG one step: `s' = (s*1664525 + 1013904223)
+ * mod 2^32`, kept as a SIGNED int32. The repo's single PRNG -- deterministic,
+ * instance-local, no Math.random, no module state, no new generator. Two integer
+ * disciplines keep it zero-alloc:
+ *   - `Math.imul` does the multiply as a 32-bit integer op (the low 32 bits of the
+ *     product), so no large intermediate double is ever formed (`s * 1664525` would
+ *     reach ~7.1e15); and
+ *   - the result is folded with `| 0` (a SIGNED int32), NOT `>>> 0`: a `>>> 0`
+ *     Uint32 exceeds the Smi range (2^31) about half the time and would box as a
+ *     transient HeapNumber every step (the perf-gate scavenge counter catches it),
+ *     whereas an `| 0` signed int32 always stays an unboxed Smi.
+ * The 32-BIT WORD is identical either way, so the sequence is unchanged: `Math.imul`
+ * gives the same low 32 bits as the plain multiply, and mod-2^32 addition is
+ * sign-agnostic. SkipList draws a node level from the HIGH bits via `Math.clz32`,
+ * which does ToUint32 internally -- so the signed int32 and its Uint32 twin yield
+ * the IDENTICAL level. The LOW bits of any power-of-two-modulus LCG are periodic
+ * (here the lowest bit strictly alternates, since a is odd and c is odd), so
+ * counting halvings from the low end would be non-random -- the high bits are the
+ * well-mixed ones.
+ * @param {number} s current state, a signed 32-bit integer
+ * @returns {number} the next state, a signed 32-bit integer (same 32-bit word)
+ */
+function _lcgNext(s) {
+    return (Math.imul(s, 1664525) + 1013904223) | 0;
+}
+
+/** SkipList tower-height ceiling: at most this many parallel `_next` columns. */
+const SL_MAXLEVEL = 32;
+
+/**
+ * Column count actually allocated for a `capacity`-slot SkipList: `ceil(log2 cap)`
+ * plus one column of headroom for the geometric tail, clamped to SL_MAXLEVEL.
+ * Fixed at construction so `_next` NEVER reallocates -- the memory risk (a full
+ * cap * 32 column set) is avoided by sizing to the capacity's real need, and level
+ * generation clamps to it, so there is no lazy grow to threaten the 0-B/op gate
+ * (decisions/0006-skiplist.md). The clamp only ever bites the extreme geometric
+ * tail (probability ~ 2^-log2(cap)), which cannot change ordering or membership --
+ * a node merely stops gaining express lanes above the ceiling.
+ * @param {number} capacity data-slot count
+ * @returns {number} column count in [1, SL_MAXLEVEL]
+ */
+function _levelCap(capacity) {
+    let l = 1;
+    while ((1 << l) < capacity && l < SL_MAXLEVEL) l++;
+    l += 1; // one column of headroom above ceil(log2 cap)
+    return l > SL_MAXLEVEL ? SL_MAXLEVEL : l;
+}
+
+/** SkipList default PRNG seed when the caller does not supply one. */
+const SL_DEFAULT_SEED = 0x9E3779B9;
+
+/**
+ * A private, pointer-free slot allocator: a free-list (a LIFO free-stack over a
+ * `Uint32Array`) that hands out a slot INDEX in [1, capacity] rather than a heap
+ * object, so nothing is collected per insert. `NIL = 0`; slot 0 is RESERVED (the
+ * SkipList head sentinel) and is never allocatable. `alloc()` returns 0 when the
+ * pool is exhausted so the caller can fail closed. The conservation invariant
+ * `activeSlots + freeListLength === capacity` holds after every operation.
+ *
+ * D-01 bind (decisions/0006-skiplist.md): this is DESIGN-PARITY with
+ * `@zakkster/lite-o1`'s private pools (FreqO1 / BucketQueue / TimerWheel) and its
+ * deferred `SlotPool` -- the identical free-list contract (allocate an index,
+ * `NIL = 0`, slot 0 reserved) and the same conservation invariant -- NOT shared
+ * code. A runtime dependency on lite-o1 was REJECTED: the suite's zero-runtime-deps
+ * law forbids it, and lite-o1's `SlotPool` was never made public. Shaped so a later
+ * pointer member (Treap) can reuse it, without over-engineering it now.
+ */
+class NodePool {
+    /** @param {number} capacity allocatable data-slot count (excludes slot 0). */
+    constructor(capacity) {
+        this._cap = capacity;
+        this._free = new Uint32Array(capacity);      // free-stack of slot indices
+        this._freeLen = capacity;
+        for (let i = 0; i < capacity; i++) this._free[i] = capacity - i; // top = slot 1
+        this._active = 0;
+    }
+
+    /** Allocatable data-slot count (excludes the reserved slot 0). O(1). */
+    get capacity() { return this._cap; }
+    /** Slots currently handed out and not yet freed. O(1). */
+    get activeSlots() { return this._active; }
+    /** Slots currently on the free-stack. O(1). */
+    get freeListLength() { return this._freeLen; }
+
+    /**
+     * Hand out a free slot INDEX in [1, capacity], or 0 (NIL) if exhausted. O(1),
+     * zero allocation.
+     * @returns {number}
+     */
+    alloc() {
+        const n = this._freeLen;
+        if (n === 0) return 0;                       // NIL: exhausted -> caller fails closed
+        const slot = this._free[n - 1];
+        this._freeLen = n - 1;
+        this._active++;
+        return slot;
+    }
+
+    /**
+     * Return a slot INDEX to the free-stack. O(1), zero allocation. The caller owns
+     * correctness: a slot must be live and freed at most once (the SkipList only
+     * frees a node it just unlinked).
+     * @param {number} slot a slot previously returned by alloc()
+     */
+    free(slot) {
+        const n = this._freeLen;
+        this._free[n] = slot;
+        this._freeLen = n + 1;
+        this._active--;
+    }
+
+    /** Reset to all-free (O(capacity) cold path), restoring the conservation invariant. */
+    clear() {
+        const cap = this._cap, free = this._free;
+        for (let i = 0; i < cap; i++) free[i] = cap - i;
+        this._freeLen = cap;
+        this._active = 0;
+    }
+}
+
+/**
+ * Max SkipList capacity: `0x03FFFFFF` (2^26 - 1). Every node is addressed by a slot
+ * INDEX stored in `Uint32Array` link columns, so an index must fit an unsigned
+ * 32-bit word; `NIL = 0` reserves slot 0 as the head sentinel, so live slots run
+ * [1, capacity]. The backing `_next` is a SINGLE flat `Uint32Array` of
+ * `columns * (capacity + 1)` cells, stride-indexed `lvl*(capacity + 1) + slot`; the
+ * 2^26 ceiling keeps `columns * (capacity + 1)` an addressable typed-array length
+ * (at most ~27 columns for the largest capacity) and every stride offset an exact
+ * integer. The index arithmetic (Uint32 slot indices + `NIL = 0` + the MAXLEVEL
+ * column width), not the byte count, is the hard ceiling -- the same "the
+ * arithmetic caps it" reasoning as the array-embedded members, one column-set wider.
+ */
+const SL_MAX_CAPACITY = 0x03FFFFFF; // 2^26 - 1
+
+/**
+ * A SKIP LIST: a pointer-free ordered map (key -> value) whose get / set / delete /
+ * successor / predecessor are EXPECTED O(log n) via a probabilistic tower of
+ * forward links -- the family's first randomized member and its first pointer-based
+ * one. Where BinaryHeap / Fenwick / SegmentTree embed a FIXED-shape tree in index
+ * arithmetic, a skip list's shape is random, so it needs real per-node links; the
+ * trick that keeps it zero-GC is storing those links as slot INDICES in flat
+ * `Uint32Array` columns over a private free-list (NodePool), never as heap objects.
+ *
+ * Storage (allocated once, sized to capacity):
+ *   - `_key` / `_val` `Float64Array(capacity + 1)` -- key and value at each slot.
+ *   - `_next` a SINGLE flat `Uint32Array(columns * (capacity + 1))`, stride-indexed
+ *     `lvl*(capacity + 1) + slot`: the forward link of `slot` at level `lvl`, or
+ *     `NIL = 0` for end-of-list. Slot 0 is the HEAD sentinel (its links are the
+ *     first node at each level); no real node's link ever points AT the head, so a
+ *     link value of 0 unambiguously means NIL.
+ *   - `_pool` NodePool -- the free-list handing out slot indices [1, capacity].
+ *   - `_update` `Uint32Array(columns)` -- reused predecessor scratch for the ONE
+ *     structural descent (`_find`); preallocated so set / delete allocate nothing.
+ *
+ * Level generation is one LCG step (the repo's NR generator) whose HIGH bits pick a
+ * geometric height: `level = 1 + clz32(word)`, clamped to the allocated column
+ * count (the low bits of a power-of-two LCG are periodic -- see `_lcgNext`). The
+ * seed is instance-local, so a fixed seed replays an IDENTICAL structure and a
+ * different seed diverges -- deterministic, never Math.random.
+ *
+ * Honesty (randomized member): a hot op is EXPECTED O(log n), not worst-case. An
+ * unlucky seed can build a tall thin tower and spike a single op; the witness prints
+ * that MAX single-op alongside the fitted line so the expectation never masquerades
+ * as a worst-case guarantee (decisions/0006-skiplist.md).
+ *
+ * Keys are FINITE numbers (typeof-guarded BEFORE coercion -- Symbol / BigInt / NaN /
+ * +-Infinity fail closed with a `[lite-logn]` throw); values are Float64 (zero-GC).
+ * `set` on an EXISTING key updates its value in place (no new node). An empty or
+ * missing query returns `undefined` (never throws). Fixed capacity: a full pool
+ * throws, never silently drops. `rangeIter` is a VERSION-STAMPED iterator -- any
+ * structural mutation mid-iteration throws `[lite-logn]` rather than yield garbage.
+ */
+export class SkipList {
+    /**
+     * @param {number} capacity  exact max live entries; integer in [1, 2^26-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 > SL_MAX_CAPACITY) {
+            throw new RangeError(
+                '[lite-logn] SkipList capacity must be an integer in [1, 2^26-1], got ' +
+                String(capacity));
+        }
+        let s;
+        if (seed === undefined) {
+            s = SL_DEFAULT_SEED;
+        } else if (typeof seed !== 'number' || !Number.isInteger(seed) ||
+            seed < 0 || seed > 0xFFFFFFFF) {
+            throw new RangeError(
+                '[lite-logn] SkipList 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
+        const cols = _levelCap(capacity);
+        this._cap = capacity;                        // max live entries
+        this._stride = capacity + 1;                 // slots 0..capacity (0 = head)
+        this._maxLevel = cols;                       // allocated column count
+        this._key = new Float64Array(capacity + 1);  // key at each slot
+        this._val = new Float64Array(capacity + 1);  // value at each slot
+        this._next = new Uint32Array(cols * (capacity + 1)); // links; all NIL (0)
+        this._update = new Uint32Array(cols);        // reused predecessor scratch
+        this._pool = new NodePool(capacity);         // free-list over slots [1, capacity]
+        this._level = 1;                             // current live tower height
+        this._size = 0;                              // live entries
+        this._version = 0;                           // iterator invalidation stamp
+        this._seed0 = s;                             // initial seed (clear resets to it)
+        this._seed = s;                              // live LCG state
+    }
+
+    /** Live entry count. O(1). */
+    get size() { return this._size; }
+
+    /** The fixed capacity this list 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 top-down descent that at each
+     * level advances while the next key is strictly less than `key`. Fails closed:
+     * a non-number / non-finite key (typeof-guarded first) throws `[lite-logn]`.
+     * @param {number} key  a finite number
+     * @returns {number|undefined}
+     */
+    get(key) {
+        if (typeof key !== 'number' || !Number.isFinite(key)) return this._badKey(key);
+        const next = this._next, K = this._key, stride = this._stride;
+        let slot = 0; // head
+        for (let lvl = this._level - 1; lvl >= 0; lvl--) {
+            const base = lvl * stride;
+            let nx = next[base + slot];
+            while (nx !== 0 && K[nx] < key) { slot = nx; nx = next[base + slot]; }
+        }
+        const cand = next[slot]; // level-0 next (base 0)
+        return (cand !== 0 && K[cand] === key) ? this._val[cand] : undefined;
+    }
+
+    /**
+     * Insert `key -> value`, or UPDATE the value in place if `key` already exists
+     * (no new node). EXPECTED O(log n). 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 cand = this._find(key); // fills _update with per-level predecessors
+        const K = this._key;
+        if (cand !== 0 && K[cand] === key) { // existing key: update value in place
+            this._val[cand] = value;
+            this._version = (this._version + 1) | 0;
+            return this;
+        }
+        const slot = this._pool.alloc();
+        if (slot === 0) return this._full();
+        // One LCG step; HIGH bits pick a geometric height, clamped to the columns.
+        const word = this._seed = _lcgNext(this._seed);
+        let nl = 1 + Math.clz32(word);
+        if (nl > this._maxLevel) nl = this._maxLevel;
+        const upd = this._update, next = this._next, stride = this._stride;
+        if (nl > this._level) {
+            for (let lvl = this._level; lvl < nl; lvl++) upd[lvl] = 0; // head is predecessor
+            this._level = nl;
+        }
+        K[slot] = key;
+        this._val[slot] = value;
+        for (let lvl = 0; lvl < nl; lvl++) {
+            const base = lvl * stride;
+            const p = upd[lvl];
+            next[base + slot] = next[base + p]; // splice slot after predecessor p
+            next[base + p] = slot;
+        }
+        this._size++;
+        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. Fails closed on a
+     * non-finite key (typeof-guarded first) with a `[lite-logn]` throw.
+     * @param {number} key  a finite number
+     * @returns {boolean}
+     */
+    delete(key) {
+        if (typeof key !== 'number' || !Number.isFinite(key)) return this._badKey(key);
+        const cand = this._find(key); // fills _update
+        const K = this._key;
+        if (cand === 0 || K[cand] !== key) return false; // absent (no throw)
+        const next = this._next, stride = this._stride, upd = this._update;
+        for (let lvl = 0; lvl < this._level; lvl++) {
+            const base = lvl * stride;
+            const p = upd[lvl];
+            if (next[base + p] === cand) next[base + p] = next[base + cand];
+        }
+        // Shrink the live height while the top levels are empty (head link == NIL).
+        let lv = this._level;
+        while (lv > 1 && next[(lv - 1) * stride] === 0) lv--;
+        this._level = lv;
+        this._pool.free(cand);
+        this._size--;
+        this._version = (this._version + 1) | 0;
+        return true;
+    }
+
+    /**
+     * 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 next = this._next, K = this._key, stride = this._stride;
+        let slot = 0;
+        for (let lvl = this._level - 1; lvl >= 0; lvl--) {
+            const base = lvl * stride;
+            let nx = next[base + slot];
+            while (nx !== 0 && K[nx] <= key) { slot = nx; nx = next[base + slot]; }
+        }
+        const cand = next[slot];
+        return cand !== 0 ? K[cand] : undefined;
+    }
+
+    /**
+     * 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 next = this._next, K = this._key, stride = this._stride;
+        let slot = 0;
+        for (let lvl = this._level - 1; lvl >= 0; lvl--) {
+            const base = lvl * stride;
+            let nx = next[base + slot];
+            while (nx !== 0 && K[nx] < key) { slot = nx; nx = next[base + slot]; }
+        }
+        return slot !== 0 ? K[slot] : undefined; // slot = largest key < key, or head
+    }
+
+    /**
+     * A VERSION-STAMPED iterator over the keys in `[lo, hi]` INCLUSIVE, in ascending
+     * order. Bounds may be any number INCLUDING +-Infinity (an unbounded end);
+     * `NaN` (unordered) fails closed, as does `lo > hi`. The generator captures the
+     * list's version and throws `[lite-logn]` if any STRUCTURAL mutation (set of a
+     * new key, delete, clear -- or any value update) happens mid-iteration, rather
+     * than yield stale / recycled data. The one documented per-protocol allocator
+     * (a {value, done} per step); the loop body itself allocates nothing.
+     * @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;
+        const next = this._next, K = this._key, stride = this._stride;
+        let slot = 0;
+        for (let lvl = this._level - 1; lvl >= 0; lvl--) {
+            const base = lvl * stride;
+            let nx = next[base + slot];
+            while (nx !== 0 && K[nx] < lo) { slot = nx; nx = next[base + slot]; }
+        }
+        slot = next[slot]; // first slot with key >= lo
+        while (slot !== 0 && K[slot] <= hi) {
+            if (this._version !== ver) {
+                throw new Error('[lite-logn] SkipList mutated during iteration');
+            }
+            yield K[slot];
+            slot = next[slot]; // level-0 next (base 0)
+        }
+    }
+
+    /**
+     * Visit every live `(key, value)` pair in ASCENDING key order. O(n) cold scan,
+     * 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' forEach).
+     * @param {(key:number, value:number, list:SkipList)=>void} fn
+     */
+    forEach(fn) {
+        const next = this._next, K = this._key, V = this._val;
+        let slot = next[0]; // level-0 first (base 0, head)
+        while (slot !== 0) {
+            fn(K[slot], V[slot], this);
+            slot = next[slot];
+        }
+    }
+
+    /**
+     * Empty the list, keeping the fixed capacity. O(capacity) cold path: returns
+     * every node to the pool, points the head's links at NIL, resets the live
+     * height, and restores the PRNG to its initial seed (a cleared list replays a
+     * fresh one). @returns {this}
+     */
+    clear() {
+        this._pool.clear();
+        const next = this._next, stride = this._stride, cols = this._maxLevel;
+        for (let lvl = 0; lvl < cols; lvl++) next[lvl * stride] = 0; // head links -> NIL
+        this._level = 1;
+        this._size = 0;
+        this._seed = this._seed0;
+        this._version = (this._version + 1) | 0;
+        return this;
+    }
+
+    // ---- private structural descent (hot body) -----------------------------
+
+    /**
+     * The ONE structural descent (set / delete): walk top-down, at each level
+     * advancing while the next key is strictly less than `key`, recording the
+     * predecessor per level in the reused `_update` scratch. Returns the level-0
+     * candidate (first slot with key >= `key`, or NIL). Zero allocation.
+     * @private
+     */
+    _find(key) {
+        const next = this._next, K = this._key, stride = this._stride, upd = this._update;
+        let slot = 0; // head
+        for (let lvl = this._level - 1; lvl >= 0; lvl--) {
+            const base = lvl * stride;
+            let nx = next[base + slot];
+            while (nx !== 0 && K[nx] < key) { slot = nx; nx = next[base + slot]; }
+            upd[lvl] = slot;
+        }
+        return next[slot]; // level-0 next (base 0)
+    }
+
+    // ---- cold path only: throw builders (string concat off the hot body) ----
+
+    /** @private */
+    _badKey(key) {
+        throw new TypeError(
+            '[lite-logn] SkipList key must be a finite number, got ' + String(key));
+    }
+
+    /** @private */
+    _badValue(value) {
+        throw new TypeError(
+            '[lite-logn] SkipList value must be a finite number, got ' + String(value));
+    }
+
+    /** @private */
+    _badBound(b) {
+        throw new TypeError(
+            '[lite-logn] SkipList rangeIter bound must be a number (not NaN), got ' + String(b));
+    }
+
+    /** @private */
+    _badRange(lo, hi) {
+        throw new RangeError(
+            '[lite-logn] SkipList rangeIter needs lo <= hi, got lo=' + String(lo) +
+            ' hi=' + String(hi));
+    }
+
+    /** @private */
+    _full() {
+        throw new RangeError('[lite-logn] SkipList 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.3.0 ships three 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), and 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) is planned -- 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.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.
 
 [![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.3.0 ships three members: BinaryHeap, Fenwick and SegmentTree.** Members land one per session, each append-only so prior members stay byte-identical. The planned roster below fills in per release.
+**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.
 
 ```bash
 npm install @zakkster/lite-logn
@@ -58,6 +58,7 @@ Every hot op allocates zero bytes after construction, and `npm run witness` prov
   - [BinaryHeap](#binaryheap)
   - [Fenwick](#fenwick)
   - [SegmentTree](#segmenttree)
+  - [SkipList](#skiplist)
 - [Zero-GC design notes](#zero-gc-design-notes)
 - [Testing](#testing)
 - [What this is not](#what-this-is-not)
@@ -82,14 +83,14 @@ 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.3.0, BinaryHeap, Fenwick and SegmentTree are shipped; SkipList is planned.
+One member per session, each landing append-only (prior members stay byte-identical). At v0.4.0, BinaryHeap, Fenwick, SegmentTree and SkipList are shipped.
 
 | Member | Version | Status | Shape | Hot ops |
 | --- | --- | --- | --- | --- |
 | **BinaryHeap** | 0.1.0 | shipped | array-embedded complete binary min|max heap over a flat `Float64Array` | `push` / `pop` O(log n), `peek` O(1) |
 | **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 | planned | pointer-free over a shared node pool; expected O(log n) | `get` / `set` / `delete` / `successor` |
+| **SkipList** | 0.4.0 | shipped | pointer-free over a private free-list node pool; expected O(log n) | `get` / `set` / `delete` / `successor` / `predecessor` |
 
 Later tiers (Treap / Scapegoat, OrderStatTree, IndexedHeap, SortedArray, MinMaxHeap, SplayTree, and presets) are queued in [`ROADMAP.md`](./ROADMAP.md).
 
@@ -101,7 +102,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.3.0 the witness gates five 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), and 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]`) all ON the line. SegmentTree's gated sweep is pinned to EXACT powers of two in `[2^10, 2^16]` (a segment-tree op touches a node per level spread across the `2n` array, so above ~2^16 the tree leaves the steady cache band, and exact powers keep the range decomposition a regular node count). Each op's O(n) foil fits well below the floor: the sorted-array insert (BinaryHeap) foil runs R^2 ~ 0.77-0.84, the Fenwick foils (prefix-array rebuild, naive re-sum) hold steadier at R^2 ~ 0.75-0.76, and SegmentTree's foils (whole-tree rebuild per update, scan-fold per query) fit at R^2 ~ 0.75-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.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.
 
 ## API reference
 
@@ -109,7 +110,7 @@ For amortized / randomized members the witness also prints the MAX single-op tim
 
 | Export | Type | Value | Meaning |
 | --- | --- | --- | --- |
-| `VERSION` | `string` | `'0.3.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.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. |
 
 ### BinaryHeap
 
@@ -221,6 +222,40 @@ The iterative `2n` layout is **order-agnostic** -- `query` mixes left- and right
 | `length` / `kind` | getters | O(1) | Element count / the frozen fold `'min'` \| `'max'` \| `'sum'` \| `'gcd'`. |
 | `SegmentTree.build` | `build(values, kind) -> SegmentTree` | O(n) | Bottom-up bulk build (seed leaves, then fold each internal node once deepest-first -- NOT n incremental updates); fails closed on a non-array-like, any non-finite value, or (gcd) any negative / non-integer. |
 
+### SkipList
+
+A **skip list**: a pointer-free **ordered map** (key -> value) whose `get` / `set` / `delete` / `successor` / `predecessor` are **expected O(log n)** via a probabilistic tower of forward links -- the family's first randomized member and its first pointer-based one. Where the array-embedded members bury a fixed-shape tree in index arithmetic, a skip list's shape is random, so it needs real per-node links; the trick that keeps it zero-GC is storing those links as slot **indices** in flat `Uint32Array` columns over a private free-list (`NodePool`), never as heap objects. `NIL = 0`, slot 0 is the head sentinel, and level generation is one step of the repo's Numerical-Recipes LCG whose high bits draw a geometric height (`1 + clz32(word)`) -- deterministic from an instance-local seed, no `Math.random`. Keys are finite numbers (typeof-guarded before coercion; Symbol / BigInt / NaN / +-Infinity fail closed); values are finite numbers; `set` on an existing key updates the value in place (no new node). Every hot op allocates zero bytes after construction.
+
+Honesty note: the hot ops are **expected** O(log n), not worst-case -- an unlucky seed can build a tall thin tower and spike a single op. The witness fits the clean average line **and** separately prints the MAX single insert over a realistic randomized build trace, so the expectation is never sold as a guarantee.
+
+```js
+import { SkipList } from '@zakkster/lite-logn';
+
+const sl = new SkipList(1000, 42);   // capacity 1000, seed 42 (deterministic)
+sl.set(50, 500);                     // insert key 50 -> value 500
+sl.set(20, 200);
+sl.set(80, 800);
+sl.get(20);            // -> 200
+sl.set(20, 222);       // update value in place (no new node)
+sl.successor(20);      // -> 50   (smallest key strictly greater)
+sl.predecessor(80);    // -> 50   (largest key strictly less)
+[...sl.rangeIter(20, 60)];  // -> [20, 50]  (keys in [lo, hi], ascending)
+sl.delete(50);         // -> true (idempotent: false if absent)
+```
+
+| Member | Signature | Complexity | Notes |
+| --- | --- | --- | --- |
+| constructor | `new SkipList(capacity, seed?)` | O(capacity) | `capacity` integer in `[1, 2^26-1]` (slot indices are `Uint32`, `NIL = 0` reserves slot 0, the `MAXLEVEL`-column stride must stay addressable); `seed` an unsigned 32-bit integer (default fixed). Allocates the typed-array 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. |
+| `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. |
+| `successor` | `successor(key) -> number \| undefined` | expected O(log n) | The smallest key STRICTLY greater than `key`, or `undefined`. `key` need not be present. |
+| `predecessor` | `predecessor(key) -> number \| undefined` | expected O(log n) | The largest key STRICTLY less than `key`, or `undefined`. `key` need not be present. |
+| `rangeIter` | `rangeIter(lo, hi) -> IterableIterator<number>` | O(log n + k) | Version-stamped iterator over keys in `[lo, hi]` INCLUSIVE, ascending. Bounds may be `+-Infinity` (unbounded ends); `NaN` or `lo > hi` throws; a structural mutation mid-iteration throws. |
+| `forEach` | `forEach(fn) -> void` | O(n) | Visits `(key, value, list)` in ascending key order. |
+| `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. |
+
 Member signatures for later members are appended here as each ships.
 
 ## Zero-GC design notes
@@ -239,8 +274,12 @@ Member signatures for later members are appended here as each ships.
 | `SegmentTree` query / update / at | 0 B/op |
 | `SegmentTree` constructor / `build` / `clear` | O(length) typed array (`2n` cells), once (cold) |
 | `SegmentTree` forEach | 0 B/op in the loop body (pass a hoisted callback) |
+| `SkipList` get / set / delete / successor / predecessor | 0 B/op (links are slot indices from a private free-list, never heap objects) |
+| `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) |
 
-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]`). 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]`). The allocation table is extended per member as each lands.
 
 ## Testing
 

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-logn
 
-Version: 0.3.0
+Version: 0.4.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -18,8 +18,8 @@ It is the O(log n) sibling of @zakkster/lite-o1: lite-o1 holds the constant (a
 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. The
-roster (one member per session, each landing append-only):
+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):
 
 - BinaryHeap (v0.1.0)  -- an INDEXED binary heap (addressable priority queue): a
   min|max binary heap over three parallel typed arrays (`_key` Float64Array,
@@ -38,9 +38,15 @@ roster (one member per session, each landing append-only):
   construction (ctor-cached small-int `_k` combined by an inline switch). The
   complement to Fenwick: Fenwick's rangeSum needs an INVERSE (subtraction), so it
   is sum-only; SegmentTree folds any associative + commutative op over a range.
-- SkipList (v0.4.0) -- the ordered map (get / set / delete / successor /
-  rangeIter), pointer-free over a shared node pool (parallel Uint32Array `next`
-  columns), expected O(log n), deterministic seed, tail reported.
+- SkipList (v0.4.0) -- a pointer-free ordered map (key -> value): get / set /
+  delete / successor / predecessor / rangeIter, EXPECTED O(log n) via a
+  probabilistic tower of forward links stored as slot INDICES in flat Uint32Array
+  columns (`NIL = 0`, slot 0 the head sentinel) over a PRIVATE free-list (NodePool,
+  design-parity with lite-o1's private pools, NOT a runtime dep). Level generation
+  is one NR-LCG step, HIGH bits -> geometric height (`1 + clz32`), instance-local
+  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.
 
 ## Exports (from the single main file LogN.js)
 
@@ -112,6 +118,29 @@ roster (one member per session, each landing append-only):
     incremental updates); fails closed on a non-array-like, any non-finite value,
     or (gcd) any negative / non-integer.
 
+- `SkipList` -- class. A pointer-free ordered map (key -> value) whose get / set /
+  delete / successor / predecessor are EXPECTED O(log n) via a probabilistic tower
+  of forward links stored as slot INDICES in a single flat `Uint32Array` of
+  `columns * (capacity + 1)` cells (`NIL = 0`, slot 0 the head sentinel) over a
+  PRIVATE free-list (NodePool) -- no heap object per op. Keys are finite numbers
+  (typeof-guarded before coercion; Symbol / BigInt / NaN / +-Infinity fail closed);
+  values are finite numbers. EXPECTED, not worst-case (an unlucky seed can spike one
+  op; the witness prints the MAX single insert).
+  - `new SkipList(capacity, seed?)` -- capacity an integer in [1, 2^26-1] (slot
+    indices are Uint32, `NIL = 0` reserves slot 0); seed an unsigned 32-bit integer
+    (default fixed). Level columns sized to ceil(log2 cap)+1 up front (never grown).
+  - `get(key)` -> value | undefined. Absent -> undefined (no throw).
+  - `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.
+  - `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 (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, list) ascending.
+
 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.3.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) -- planned -- 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.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.",
   "type": "module",
   "main": "./LogN.js",
   "module": "./LogN.js",