@zakkster/lite-logn 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,136 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-20
+
+### Added
+
+- **Scapegoat** -- the sixth member and the family's DETERMINISTIC balanced BST, the
+  honest PAIR to Treap: a weight-balanced binary search tree that is ALSO an
+  order-statistic tree (an AUGMENTED ordered map key -> value). Where a treap randomizes
+  its shape to be balanced IN EXPECTATION, a scapegoat keeps a hard WORST-CASE height
+  bound -- so `get` is O(log n) WORST-case (never merely expected) -- and pays for it with
+  AMORTIZED O(log n) `set` / `delete`, where an occasional subtree rebuild absorbs the
+  imbalance. A subtree-size column `_size` (maintained in the same pass as every link
+  rewrite and every rebuild) adds O(log n) order statistics. Surface: `get` / `has` /
+  `set` (updates the value in place on an existing key) / `delete` (idempotent) /
+  `rank(x)` (count of keys STRICTLY less than x) / `select(k)` (the k-th smallest key,
+  0-based) / `successor` (strictly greater) / `predecessor` (strictly less) /
+  `rangeIter(lo, hi)` (a VERSION-STAMPED iterator over `[lo, hi]` inclusive, ascending;
+  `+-Infinity` bounds allowed, structural OR value mutation mid-iteration throws) /
+  `forEach` / `clear`, and `size` / `capacity` / `alpha` getters. Keys and values are
+  finite numbers (typeof-guarded before coercion -- Symbol / BigInt / NaN / +-Infinity
+  fail closed with a `[lite-logn]` throw).
+- **NO priorities, NO RNG (fully deterministic).** Unlike Treap, Scapegoat draws no random
+  priority and uses no LCG / `Math.random` anywhere: the tree shape is a deterministic
+  function of the insert / delete order. `alpha` (the weight-balance factor) is validated
+  to the OPEN interval `(0.55, 0.75)` -- both ends throw -- and frozen at construction
+  (default `2/3`); the alpha-derived depth constant `_invAlpha = 1/alpha` is ctor-cached so
+  the hot insert path uses no per-op `Math.log` (the depth test is `_invAlpha^d > size`).
+- **Zero-GC rebuild over preallocated scratch (the load-bearing design call).** No fresh
+  array per rebuild: ONE `_flat` (`Uint32Array(capacity)`) + ONE `_stack`
+  (`Uint32Array(capacity+1)`) are allocated at construction and reused every rebuild. An
+  ITERATIVE, Morris-free in-order flatten (via `_stack`) writes sorted slot indices into
+  `_flat`; a bounded log-depth balanced rebuild re-links `_left` / `_right` / `_size` on
+  the native call stack. Proven 0 B/op even under a rebuild-HEAVY ascending-insert trace by
+  the torture gate and a dedicated PerfGate scavenge-clean scenario
+  (decisions/0008-scapegoat.md).
+- **Third bind of the shared NodePool.** Nodes are slot INDICES in five flat columns
+  (`_key` / `_value` Float64; `_left` / `_right` / `_size` Uint32, `NIL = 0`) over the SAME
+  private free-list (`NodePool`) SkipList and Treap ship -- design-parity, not a fork or a
+  runtime dep. The conservation invariant `activeSlots + freeListLength === capacity` holds
+  after every op, INCLUDING across rebuild storms. `SG_MAX_CAPACITY = 0x7FFFFFFF` (2^31 - 1:
+  slot indices + subtree counts fit a `Uint32`).
+- **The documented asymmetry vs Treap: NO `split` / `merge`.** A scapegoat has no priority
+  heap to merge by, and an honest deterministic split/merge would be O(n) rebuilds
+  (forfeiting the sub-linear headline), so Scapegoat's surface is the ordered-map +
+  order-statistic core and split/merge are deliberately absent -- named on the public
+  surface (JSDoc + `llms.txt` + README + the `.d.ts`), not hidden.
+- **Witness: `Scapegoat.get` gated + the amortized-trace assertion.** `get` (a
+  deterministic weight-balanced descent) is gated ON the O(log n) line in its own
+  calibrated band `SCAPEGOAT_GET_SLOPE_LO/HI = [2.41, 5.63]` (median-of-15 slope 4.02
+  ns/level * [0.6, 1.4], MEDIAN-centered per ADR-0004), inheriting the FROZEN shared R^2
+  floor 0.958; its O(n) linear-scan foil leaves the line. The rebuild spike lives on the
+  AMORTIZED `set` path and is NEVER gated as a per-op line; instead the amortized-trace
+  assertion proves the amortization -- the cumulative ascending-insert (rebuild-heavy)
+  cost/op tracks a LOG curve (last/first ratio ~1.5x, gated `< 4x`) where a rebuild-less
+  BST would blow to ~64x. The five prior members' bands are UNTOUCHED.
+
+### Notes
+
+- Append-only: `LogN.js` gains `SG_MAX_CAPACITY` + the `Scapegoat` class after Treap;
+  BinaryHeap / Fenwick / SegmentTree / SkipList / Treap are BYTE-IDENTICAL (only the
+  `VERSION` const changes). The repo-only benchmark admits Scapegoat as the 6th SUBJECT
+  (matrix 5x8=40 -> 6x8=48, a new `OLOGN_AMORTIZED` honesty class for `set` / `delete`).
+
+## [0.5.0] - 2026-09-20
+
+### Added
+
+- **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,112 @@ 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;
+}
+
+/**
+ * A scapegoat tree: a DETERMINISTIC, weight-balanced BST that is also an order-statistic
+ * tree (an AUGMENTED ordered map key -> value) -- the honest pair to Treap. `get` is
+ * WORST-case O(log n) (a hard height bound, never merely expected); `set` / `delete` are
+ * AMORTIZED O(log n) (an occasional subtree rebuild absorbs the imbalance). A subtree-size
+ * column adds O(log n) rank / select. No priorities, no RNG: the shape is a deterministic
+ * function of the insert / delete order. Nodes are slot INDICES in flat typed-array columns
+ * over a private free-list, and every rebuild reuses ONE preallocated scratch buffer + index
+ * stack (no heap object, no fresh array per op). Keys and values are finite numbers (typeof-
+ * guarded before coercion; Symbol / BigInt / NaN / +-Infinity fail closed). set on an existing
+ * key updates the value in place. Fixed capacity: a full pool throws. Every hot op allocates
+ * zero bytes. There is deliberately NO split / merge (the treap's arena-sharing surgery has no
+ * honest deterministic O(log n) analogue here) -- the documented asymmetry vs Treap.
+ */
+export class Scapegoat {
+    /** @param capacity exact max live entries; integer in [1, 2^31-1].
+     *  @param alpha weight-balance factor in the OPEN interval (0.55, 0.75); default 2/3.
+     *         Both ends throw. Frozen after construction. */
+    constructor(capacity: number, alpha?: number);
+
+    /** Live entry count. */
+    readonly size: number;
+    /** The fixed capacity this tree was sized for. */
+    readonly capacity: number;
+    /** The frozen weight-balance factor. */
+    readonly alpha: number;
+
+    /** The value under key, or undefined if absent (no throw). Non-finite key throws. */
+    get(key: number): number | undefined;
+    /** True iff key is currently stored. Non-finite key throws. */
+    has(key: number): boolean;
+    /** Insert key -> value, or update the value in place if key exists. Non-finite
+     *  key/value throws; a full pool throws. */
+    set(key: number, value: number): this;
+    /** Remove key; true if it was present, false if absent (idempotent). Non-finite key throws. */
+    delete(key: number): boolean;
+    /** Count of stored keys strictly less than x (its rank), in [0, size]. Non-finite x throws. */
+    rank(x: number): number;
+    /** The k-th smallest key (0-based), or undefined if k is out of [0, size). Non-integer k throws. */
+    select(k: number): number | undefined;
+    /** The smallest key strictly greater than key, or undefined. Non-finite key throws. */
+    successor(key: number): number | undefined;
+    /** The largest key strictly less than key, or undefined. Non-finite key throws. */
+    predecessor(key: number): number | undefined;
+    /** A version-stamped iterator over keys in [lo, hi] inclusive, ascending. Bounds
+     *  may be +-Infinity (unbounded ends); NaN or lo > hi throws; mutation during
+     *  iteration throws. */
+    rangeIter(lo: number, hi: number): IterableIterator<number>;
+    /** Visit every (key, value) pair in ascending key order. */
+    forEach(fn: (key: number, value: number, tree: Scapegoat) => void): void;
+    /** Empty the tree, keeping capacity. */
+    clear(): this;
+}