@zakkster/lite-logn 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,131 @@ 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
+
+- **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 +250,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,99 @@ 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;
+}
+
+/**
+ * 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;
+}