@zakkster/lite-logn 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to `@zakkster/lite-logn` are documented here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-17
+
+### Added
+
+- **BinaryHeap** -- the first member: an indexed binary min|max heap (addressable
+  priority queue) over three parallel typed arrays (`_key` Float64Array, `_id`
+  Uint32Array, `_pos` Int32Array reverse map). Surface: `push` / `pop` / `peek` /
+  `topKey` / `keyOf` / `has` / `changeKey` / `remove`, `size` / `capacity` /
+  `kind` getters, `clear`, `forEach` / `[Symbol.iterator]` (unspecified order),
+  and a static `BinaryHeap.build(kind, ids, keys, capacity)` Floyd O(n) bulk
+  build. changeKey / remove address elements by caller-supplied entity id via the
+  reverse-index map. push / pop / changeKey / remove are O(log n) with
+  hole-punching sift; peek / topKey / keyOf / has are O(1). Fixed-capacity
+  fail-closed (overflow, duplicate id, non-member changeKey, out-of-range id, and
+  non-finite key all throw `[lite-logn]`; never a silent drop). Zero allocation on
+  every hot path.
+- **Scaffold release.** Stands up the repo for the O(log n) family, the sibling
+  of `@zakkster/lite-o1`. Ships the six `files[]` entries: `LogN.js` (header +
+  the `VERSION` const, no member yet), `LogN.d.ts`, `llms.txt`, `README.md`,
+  `CHANGELOG.md`, and `LICENSE`. Repo-only (not shipped): `GUIDE.md` and the
+  gate harnesses (`test/torture.mjs`, `test/witness.mjs`,
+  `test/perf/PerfGate.test.mjs`, `test/QaAudit.test.js`, `test/Bench.test.mjs`).
+  With zero members the harnesses run green and empty.
+- **The witness harness stub.** The log-linear fit machinery
+  (`nsPerOp = intercept + slope*log2(n)`, least-squares `R^2` + slope) and an
+  O(n) foil are in place; the `R^2` floor + slope band are deliberately NOT
+  gated yet -- they are calibrated in the BinaryHeap session (decision D-02).
+- **Design decisions on the record.** [`decisions/0001-nodepool.md`](./decisions/0001-nodepool.md)
+  (D-01: reconcile the pointer-free node pool against lite-o1's SlotPool, do not
+  fork), [`decisions/0002-spine.md`](./decisions/0002-spine.md) (D-03: the
+  ordered-collection spine reach -- offer where honest, force nowhere), and
+  [`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.1.0...HEAD
+[0.1.0]: https://github.com/PeshoVurtoleta/lite-logn/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LogN.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @zakkster/lite-logn -- ambient type surface.
+ *
+ * Hand-written to mirror EXACTLY the runtime exports of LogN.js. The three-place
+ * version sync (package.json / LogN.js VERSION / llms.txt) is enforced in review;
+ * at v0.1.0 (the scaffold release) the only export is `VERSION`. One ambient
+ * declaration block per member is appended here as each member ships. ASCII-only.
+ *
+ * @license MIT
+ */
+
+/** Package version string. */
+export const VERSION: string;
+
+// --- member type blocks land here, append-only, one per shipped member -------
+
+/**
+ * An indexed binary heap (addressable priority queue): a min|max binary heap over
+ * three parallel typed arrays plus a reverse-index map, giving O(log n)
+ * changeKey / remove by caller-supplied entity id. Entity ids are integers in
+ * [0, capacity); keys are finite numbers. Every hot op allocates zero bytes.
+ */
+export class BinaryHeap {
+    /** @param capacity exact max live entries; integer in [1, 2^31-1].
+     *  @param kind the frozen extreme this heap reports (default 'min'). */
+    constructor(capacity: number, kind?: 'min' | 'max');
+
+    /** Live entry count. */
+    readonly size: number;
+    /** The fixed capacity this heap was sized for. */
+    readonly capacity: number;
+    /** The frozen extreme this heap reports. */
+    readonly kind: 'min' | 'max';
+
+    /** Insert entity id with priority key. Throws on out-of-range/duplicate id,
+     *  non-finite key, or a full heap. */
+    push(id: number, key: number): void;
+    /** Remove and return the extremum's entity id, or undefined if empty. */
+    pop(): number | undefined;
+    /** The extremum's entity id, or undefined if empty. */
+    peek(): number | undefined;
+    /** The extremum's key, or undefined if empty. */
+    topKey(): number | undefined;
+    /** The key associated with id, or undefined if absent. Out-of-range id throws. */
+    keyOf(id: number): number | undefined;
+    /** True iff id is currently in the heap. Out-of-range id throws. */
+    has(id: number): boolean;
+    /** Reprioritize a present entity, auto-directing the sift. Non-member throws. */
+    changeKey(id: number, newKey: number): void;
+    /** Remove entity id; true if it was present, false if absent (idempotent). */
+    remove(id: number): boolean;
+    /** Empty the heap. */
+    clear(): void;
+    /** Visit every live (id, key) pair in unspecified (heap-array) order. */
+    forEach(fn: (id: number, key: number, heap: BinaryHeap) => void): void;
+    /** Iterate live entity ids in unspecified (heap-array) order (NOT sorted). */
+    [Symbol.iterator](): IterableIterator<number>;
+
+    /** Floyd O(n) bulk build from parallel ids/keys arrays. */
+    static build(
+        kind: 'min' | 'max',
+        ids: ArrayLike<number>,
+        keys: ArrayLike<number>,
+        capacity: number,
+    ): BinaryHeap;
+}

package/LogN.js

@@ -0,0 +1,394 @@
+/**
+ * @zakkster/lite-logn -- a tree-shakeable, zero-GC family of O(log n) data
+ * structures that doubles as a teachable textbook: each member solves a real
+ * problem AND proves its logarithm is real (the O(log n) Witness -- see
+ * test/witness.mjs).
+ *
+ * v0.1.0 ships its FIRST member: BinaryHeap, an INDEXED binary heap -- an
+ * addressable priority queue (a min|max binary heap over three parallel typed
+ * arrays plus a reverse-index map that makes changeKey / remove O(log n) by
+ * caller-supplied entity id). Members land append-only, leaving this header and
+ * the `VERSION` const the only prior lines that ever change. Planned roster:
+ * BinaryHeap (this release, 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 + point-update),
+ * and SkipList (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`).
+ *
+ * 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
+ * added level per doubling of n, slope > 0 within a per-member band). Every hot
+ * op each member ships is O(log n) worst-case (or expected/amortized where
+ * stated) and allocates ZERO bytes after construction. The witness harness
+ * (never imported here) fits `nsPerOp = intercept + slope * log2(n)` and shows
+ * the straight log line while an O(n) foil leaves it -- that line is the theorem
+ * made visible.
+ *
+ * @license MIT
+ */
+
+/** Package version. One of the three version sites (package.json / VERSION / llms.txt). */
+export const VERSION = '0.1.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)         -- O(log n) point-update + prefix-sum
+// SegmentTree (v0.3.0)         -- O(log n) associative range-query + point-update
+// SkipList    (v0.4.0)         -- pointer-free expected-O(log n) ordered map
+
+/** Max heap capacity: slot indices 0..cap-1 must fit the Int32Array _pos map. */
+const BH_MAX_CAPACITY = 0x7FFFFFFF; // 2^31 - 1
+
+/**
+ * An INDEXED binary heap: an addressable priority queue over three parallel,
+ * pointer-free typed arrays plus a reverse-index map. A plain binary heap gives
+ * O(log n) push / pop but cannot find an arbitrary element to reprioritize; the
+ * `_pos` map (entity id -> current heap slot, sentinel -1 == absent) buys
+ * O(log n) `changeKey` / `remove` by a caller-supplied entity id. Every hot op
+ * (push / pop / peek / topKey / keyOf / has / changeKey / remove) allocates ZERO
+ * bytes after construction.
+ *
+ * Storage (allocated once, sized to capacity):
+ *   - `_key` Float64Array -- the priority key at each heap SLOT (heap-ordered).
+ *   - `_id`  Uint32Array  -- the entity id at each heap SLOT (moves with its key).
+ *   - `_pos` Int32Array   -- reverse map id -> slot; -1 means "not in heap".
+ * `_pos` is initialised to -1 (fill), NOT 0, because slot 0 is a valid position
+ * -- null is not zero. Children of slot i are 2i+1 / 2i+2, parent (i-1)>>1.
+ *
+ * The sift is HOLE-PUNCHING (not a 3-write swap): the moving element is cached in
+ * locals once, the hole walks down / up writing ONE slot per level (updating
+ * `_pos` for each shifted id), then the cached element drops into the final hole.
+ *
+ * ID contract: entity ids are integers in [0, capacity). Any out-of-range id is a
+ * hard `[lite-logn]` throw (a programming error). A key must be a finite number
+ * where required; NaN / non-finite / non-number fail closed rather than corrupt
+ * heap order. Fixed capacity: overflow throws, never silently drops.
+ */
+export class BinaryHeap {
+    /**
+     * @param {number} capacity        exact max live entries; integer in [1, 2^31-1].
+     * @param {'min'|'max'} [kind]      the frozen extreme this heap reports (default 'min').
+     */
+    constructor(capacity, kind = 'min') {
+        // typeof guard BEFORE coercion (Number.isInteger is Symbol/BigInt-safe).
+        if (typeof capacity !== 'number' || !Number.isInteger(capacity) ||
+            capacity < 1 || capacity > BH_MAX_CAPACITY) {
+            throw new RangeError(
+                '[lite-logn] BinaryHeap capacity must be an integer in [1, 2^31-1], got ' +
+                String(capacity));
+        }
+        if (kind !== 'min' && kind !== 'max') {
+            throw new RangeError(
+                '[lite-logn] BinaryHeap kind must be "min" or "max", got ' + String(kind));
+        }
+        this._key = new Float64Array(capacity); // key at each heap slot
+        this._id = new Uint32Array(capacity);   // entity id at each heap slot
+        this._pos = new Int32Array(capacity);   // id -> slot; -1 == absent
+        this._pos.fill(-1);                      // slot 0 is valid: null is not zero
+        this._cap = capacity;                    // exact fixed capacity
+        this._n = 0;                             // live entries (heap size)
+        this._min = kind === 'min';              // ctor-frozen hot compare flag
+    }
+
+    /** Live entry count. O(1). */
+    get size() { return this._n; }
+
+    /** The fixed capacity this heap was sized for. O(1). */
+    get capacity() { return this._cap; }
+
+    /** The frozen extreme this heap reports, 'min' or 'max'. O(1). */
+    get kind() { return this._min ? 'min' : 'max'; }
+
+    /**
+     * Insert entity `id` with priority `key`. O(log n). Fails closed: an
+     * out-of-range id, an already-present id (no silent overwrite), a non-finite /
+     * non-number key, or a full heap each throw `[lite-logn]` as a no-op.
+     * @param {number} id   integer in [0, capacity), not already present
+     * @param {number} key  a finite number
+     */
+    push(id, key) {
+        if (typeof id !== 'number' || !Number.isInteger(id) || id < 0 || id >= this._cap) {
+            return this._badId(id);
+        }
+        if (typeof key !== 'number' || !Number.isFinite(key)) return this._badKey(key);
+        if (this._pos[id] !== -1) return this._dup(id);
+        const n = this._n;
+        if (n === this._cap) return this._full();
+        this._n = n + 1;
+        this._siftUp(n, key, id);
+    }
+
+    /**
+     * Remove and return the entity id at the extremum (min or max per kind), or
+     * `undefined` if empty (never throws on empty). O(log n).
+     * @returns {number|undefined}
+     */
+    pop() {
+        const n = this._n;
+        if (n === 0) return undefined;
+        const top = this._id[0];
+        this._pos[top] = -1;
+        const last = n - 1;
+        this._n = last;
+        if (last > 0) this._siftDown(0, this._key[last], this._id[last]);
+        return top;
+    }
+
+    /** The entity id at the extremum, or `undefined` if empty. Read-only. O(1). */
+    peek() { return this._n === 0 ? undefined : this._id[0]; }
+
+    /** The key at the extremum (root), or `undefined` if empty. O(1). */
+    topKey() { return this._n === 0 ? undefined : this._key[0]; }
+
+    /**
+     * The key currently associated with `id`, or `undefined` if id is not in the
+     * heap. O(1). An out-of-range id still throws.
+     * @param {number} id
+     * @returns {number|undefined}
+     */
+    keyOf(id) {
+        if (typeof id !== 'number' || !Number.isInteger(id) || id < 0 || id >= this._cap) {
+            return this._badId(id);
+        }
+        const slot = this._pos[id];
+        return slot === -1 ? undefined : this._key[slot];
+    }
+
+    /**
+     * True iff `id` is currently in the heap. O(1). An out-of-range id throws.
+     * @param {number} id
+     * @returns {boolean}
+     */
+    has(id) {
+        if (typeof id !== 'number' || !Number.isInteger(id) || id < 0 || id >= this._cap) {
+            return this._badId(id);
+        }
+        return this._pos[id] !== -1;
+    }
+
+    /**
+     * Reprioritize a present entity to `newKey`, auto-directing the sift. O(log n).
+     * Compares the new key against the current parent to pick the single direction
+     * that can violate order (up XOR down), then sifts that way with hole-punching.
+     * Fails closed: a non-member id throws `[lite-logn]` (never a silent no-op); an
+     * out-of-range id or non-finite key throws.
+     * @param {number} id      integer in [0, capacity), currently present
+     * @param {number} newKey  a finite number
+     */
+    changeKey(id, newKey) {
+        if (typeof id !== 'number' || !Number.isInteger(id) || id < 0 || id >= this._cap) {
+            return this._badId(id);
+        }
+        if (typeof newKey !== 'number' || !Number.isFinite(newKey)) return this._badKey(newKey);
+        const slot = this._pos[id];
+        if (slot === -1) return this._notMember(id);
+        if (slot > 0) {
+            const pk = this._key[(slot - 1) >> 1];
+            if (this._min ? (newKey < pk) : (newKey > pk)) {
+                this._siftUp(slot, newKey, id);
+                return;
+            }
+        }
+        this._siftDown(slot, newKey, id);
+    }
+
+    /**
+     * Remove entity `id`. O(log n). Idempotent: returns false if id is absent (no
+     * throw), true if it was present and removed. The last entry fills the vacated
+     * slot and sifts the single direction that can violate order. An out-of-range
+     * id throws.
+     * @param {number} id
+     * @returns {boolean}
+     */
+    remove(id) {
+        if (typeof id !== 'number' || !Number.isInteger(id) || id < 0 || id >= this._cap) {
+            return this._badId(id);
+        }
+        const slot = this._pos[id];
+        if (slot === -1) return false;
+        this._pos[id] = -1;
+        const last = this._n - 1;
+        this._n = last;
+        if (slot !== last) {
+            const mk = this._key[last];
+            const mid = this._id[last];
+            if (slot > 0) {
+                const pk = this._key[(slot - 1) >> 1];
+                if (this._min ? (mk < pk) : (mk > pk)) {
+                    this._siftUp(slot, mk, mid);
+                    return true;
+                }
+            }
+            this._siftDown(slot, mk, mid);
+        }
+        return true;
+    }
+
+    /** Empty the heap. O(capacity) cold path (resets size + the reverse map). */
+    clear() {
+        this._n = 0;
+        this._pos.fill(-1);
+    }
+
+    /**
+     * Visit every live (id, key) pair in UNSPECIFIED (heap-array) order -- NOT
+     * sorted / pop order. O(n) cold scan, allocation-free (pass a hoisted callback).
+     * @param {(id:number, key:number, heap:BinaryHeap)=>void} fn
+     */
+    forEach(fn) {
+        const id = this._id, key = this._key, n = this._n;
+        for (let i = 0; i < n; i++) fn(id[i], key[i], this);
+    }
+
+    /**
+     * Iterate live entity ids in UNSPECIFIED (heap-array) order -- NOT sorted. The
+     * one documented per-protocol allocator (a {value, done} per step); use forEach
+     * for the alloc-free scan.
+     */
+    *[Symbol.iterator]() {
+        const id = this._id, n = this._n;
+        for (let i = 0; i < n; i++) yield id[i];
+    }
+
+    /**
+     * Floyd O(n) bulk build: load every (ids[i], keys[i]) pair then heapify
+     * bottom-up in O(n), rather than n individual O(log n) pushes. COLD path;
+     * fails closed on any violation (duplicate / out-of-range id, non-finite key,
+     * count > capacity) before the heap is usable.
+     * @param {'min'|'max'} kind
+     * @param {ArrayLike<number>} ids   unique integers in [0, capacity)
+     * @param {ArrayLike<number>} keys  finite numbers, keys.length === ids.length
+     * @param {number} capacity
+     * @returns {BinaryHeap}
+     */
+    static build(kind, ids, keys, capacity) {
+        const heap = new BinaryHeap(capacity, kind);
+        if (ids == null || keys == null ||
+            typeof ids.length !== 'number' || typeof keys.length !== 'number') {
+            throw new TypeError('[lite-logn] BinaryHeap.build needs array-like ids and keys');
+        }
+        const count = ids.length;
+        if (keys.length !== count) {
+            throw new RangeError(
+                '[lite-logn] BinaryHeap.build ids/keys length mismatch (' +
+                count + ' vs ' + keys.length + ')');
+        }
+        if (count > capacity) {
+            throw new RangeError(
+                '[lite-logn] BinaryHeap.build count ' + count + ' exceeds capacity ' + capacity);
+        }
+        const K = heap._key, I = heap._id, P = heap._pos;
+        for (let i = 0; i < count; i++) {
+            const id = ids[i];
+            if (typeof id !== 'number' || !Number.isInteger(id) || id < 0 || id >= capacity) {
+                throw new RangeError(
+                    '[lite-logn] BinaryHeap.build id must be an integer in [0, capacity), got ' +
+                    String(id));
+            }
+            const key = keys[i];
+            if (typeof key !== 'number' || !Number.isFinite(key)) {
+                throw new TypeError(
+                    '[lite-logn] BinaryHeap.build key must be a finite number, got ' + String(key));
+            }
+            if (P[id] !== -1) {
+                throw new RangeError('[lite-logn] BinaryHeap.build duplicate id ' + id);
+            }
+            K[i] = key;
+            I[i] = id;
+            P[id] = i;
+        }
+        heap._n = count;
+        // Floyd: sift down every internal node, deepest-first. O(n).
+        for (let i = (count >> 1) - 1; i >= 0; i--) {
+            heap._siftDown(i, K[i], I[i]);
+        }
+        return heap;
+    }
+
+    // ---- private hole-punching sift (hot bodies) ---------------------------
+
+    /**
+     * Walk the hole UP from `hole`, pulling each larger (min) / smaller (max)
+     * parent down one level, then drop (key, id) into the settled hole. One write
+     * per level; `_pos` updated for every shifted id and for the placed id.
+     * @private
+     */
+    _siftUp(hole, key, id) {
+        const K = this._key, I = this._id, P = this._pos, min = this._min;
+        while (hole > 0) {
+            const parent = (hole - 1) >> 1;
+            const pk = K[parent];
+            if (min ? (key >= pk) : (key <= pk)) break;
+            K[hole] = pk;
+            const pid = I[parent];
+            I[hole] = pid;
+            P[pid] = hole;
+            hole = parent;
+        }
+        K[hole] = key;
+        I[hole] = id;
+        P[id] = hole;
+    }
+
+    /**
+     * Walk the hole DOWN from `hole`, pulling the extreme child up one level, then
+     * drop (key, id) into the settled hole. One write per level; `_pos` updated for
+     * every shifted id and for the placed id. Bound is the current `_n`.
+     * @private
+     */
+    _siftDown(hole, key, id) {
+        const K = this._key, I = this._id, P = this._pos, min = this._min;
+        const n = this._n;
+        const half = n >> 1; // nodes at index >= half are leaves
+        while (hole < half) {
+            let child = (hole << 1) + 1; // left child
+            const right = child + 1;
+            if (right < n && (min ? (K[right] < K[child]) : (K[right] > K[child]))) {
+                child = right;
+            }
+            const ck = K[child];
+            if (min ? (key <= ck) : (key >= ck)) break;
+            K[hole] = ck;
+            const cid = I[child];
+            I[hole] = cid;
+            P[cid] = hole;
+            hole = child;
+        }
+        K[hole] = key;
+        I[hole] = id;
+        P[id] = hole;
+    }
+
+    // ---- cold path only: throw builders (string concat off the hot body) ---
+
+    /** @private */
+    _badId(id) {
+        throw new RangeError(
+            '[lite-logn] BinaryHeap id must be an integer in [0, ' + this._cap + '), got ' +
+            String(id));
+    }
+
+    /** @private */
+    _badKey(key) {
+        throw new TypeError(
+            '[lite-logn] BinaryHeap key must be a finite number, got ' + String(key));
+    }
+
+    /** @private */
+    _dup(id) {
+        throw new RangeError(
+            '[lite-logn] BinaryHeap id ' + id + ' already present (no silent overwrite)');
+    }
+
+    /** @private */
+    _full() {
+        throw new RangeError('[lite-logn] BinaryHeap full (capacity ' + this._cap + ')');
+    }
+
+    /** @private */
+    _notMember(id) {
+        throw new RangeError(
+            '[lite-logn] BinaryHeap.changeKey: id ' + id + ' is not in the heap');
+    }
+}

package/README.md

@@ -0,0 +1,181 @@
+# @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.1.0 is the scaffold release; the planned roster is 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) -- 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)
+![Zero-GC](https://img.shields.io/badge/Zero--GC-Engine-00C853?style=for-the-badge&logo=leaf&logoColor=white)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-logn?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-logn)
+[![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-logn?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-logn)
+[![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-logn?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-logn)
+![Tree-Shakeable](https://img.shields.io/badge/tree--shakeable-yes-brightgreen)
+![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
+
+## The O(log n) toolkit the ecosystem was missing
+
+Almost no JavaScript data-structure library ships the evidence that its Big-O claim survives contact with a real engine -- megamorphic call sites, GC pauses, cache misses, deopts. `lite-logn` is a curated, tree-shakeable family of the O(log n) structures that actually matter, each zero-GC, each written to teach the trick that buys the logarithm, and each shipped with a harness that DEMONSTRATES the straight log line rather than asserting it. The complexity class IS the product.
+
+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.1.0 is the scaffold release.** It ships only the `VERSION` const -- there is no member yet. This first cut stands up the repo, the gates (torture / witness / perf), and the design decisions that outlive member 1 (see [`decisions/`](./decisions)). The planned roster below lands one member per session, each append-only so prior members stay byte-identical.
+
+```bash
+npm install @zakkster/lite-logn
+```
+
+```js
+import { VERSION } from '@zakkster/lite-logn';
+
+console.log(VERSION); // -> '0.1.0'  (scaffold release; members land per session)
+```
+
+Once BinaryHeap ships (v0.1.0 member session), the quick-start becomes a heap push / pop whose every op is O(log n) worst-case and allocates zero bytes after construction, and `npm run witness` proves it holds the straight log line while a sorted-array-insert foil (O(n) shift) leaves it.
+
+---
+
+## Table of contents
+
+- [Why this exists](#why-this-exists)
+- [What you get](#what-you-get)
+- [The planned roster](#the-planned-roster)
+- [The O(log n) Witness](#the-olog-n-witness)
+- [API reference](#api-reference)
+  - [Constants](#constants)
+- [Zero-GC design notes](#zero-gc-design-notes)
+- [Testing](#testing)
+- [What this is not](#what-this-is-not)
+- [Ecosystem](#ecosystem)
+- [License](#license)
+
+---
+
+## Why this exists
+
+A working programmer reaching for "keep the smallest element to hand" or "prefix sums that stay correct under updates" usually pays an O(n) cost hidden behind a friendly method name -- `Array.prototype.shift`, a full re-sum, a re-sort on every insert. The logarithm is the honest price of order, and it is cheap: one extra level of work per doubling of the data. But a naive O(log n) structure does `new Node` per insert, and that per-op allocation is a GC pause an engine will not honor -- it turns the clean logarithm into jitter.
+
+lite-logn ships the O(log n) structures that matter with the allocation removed (array-embedded members are naturally node-free; pointer-based members use a pointer-free node pool) and the logarithm proven (the witness fits a straight log line and shows an O(n) foil leaving it). The complexity class is the product: you get the structure AND the evidence its bound is real on a real engine.
+
+## What you get
+
+- **Zero runtime dependencies.** ESM only, ASCII-only source, one PascalCase main file (`LogN.js`), `sideEffects: false`.
+- **Zero allocation on every hot path.** Proven by `node --expose-gc test/torture.mjs` (`@zakkster/lite-leak` + `@zakkster/lite-gc-profiler`): 0 B/op, `gc major = 0`, leak tracker `size 0/0`.
+- **A logarithm you can see.** `npm run witness` fits `nsPerOp = intercept + slope*log2(n)` across a geometric `n` sweep, gates the `R^2` floor + slope band, and shows an O(n) foil departing the line.
+- **Tree-shakeable named exports.** Members share no mutable module state, so a bundler that imports one drops the others.
+- **Fail closed.** Fixed, preallocated capacity; a `typeof`-guard at the door of every mutating op; `null` is not zero; an unknown option key is an error with a hint, never a silent ignore.
+
+## The planned roster
+
+One member per session, each landing append-only (prior members stay byte-identical). At v0.1.0 none are shipped yet -- this is the scaffold.
+
+| Member | Version | Shape | Hot ops |
+| --- | --- | --- | --- |
+| **BinaryHeap** | 0.1.0 | array-embedded complete binary min-heap over a flat `Float64Array` | `push` / `pop` O(log n), `peek` O(1) |
+| **Fenwick** (BIT) | 0.2.0 | flat array, lowest-set-bit walk (`i & -i`) | `update` / `prefix` / `rangeSum` O(log n) |
+| **SegmentTree** | 0.3.0 | flat, array-embedded tree; associative fold chosen at construction | `rangeQuery` / `pointUpdate` O(log n) |
+| **SkipList** | 0.4.0 | pointer-free over a shared node pool; expected O(log n) | `get` / `set` / `delete` / `successor` |
+
+Later tiers (Treap / Scapegoat, OrderStatTree, IndexedHeap, SortedArray, MinMaxHeap, SplayTree, and presets) are queued in [`ROADMAP.md`](./ROADMAP.md).
+
+## The O(log n) Witness
+
+The family anchor. Time a fixed batch of the hot op at each `n` in a geometric sweep, fit `nsPerOp = intercept + slope * log2(n)` by least squares, and gate:
+
+- `R^2 >= floor` (a straight line fits -- genuinely logarithmic), AND
+- `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 + slope band are calibrated in BinaryHeap and become the shared FAMILY gate. At v0.1.0 the witness harness is a stub: with zero members it runs green and empty (there is no member to fit yet).
+
+## API reference
+
+### Constants
+
+| Export | Type | Value | Meaning |
+| --- | --- | --- | --- |
+| `VERSION` | `string` | `'0.1.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
+
+An **indexed binary heap** (an addressable priority queue): a min|max binary heap over three parallel, pointer-free typed arrays -- `_key` (`Float64Array`, the priority at each heap slot), `_id` (`Uint32Array`, the entity id at each slot), and `_pos` (`Int32Array`, the reverse map entity-id -> slot, sentinel `-1` == absent). A plain binary heap gives O(log n) `push` / `pop` but cannot find an arbitrary element to reprioritize; the reverse-index map buys O(log n) `changeKey` / `remove` by a caller-supplied entity id. Children of slot `i` are `2i+1` / `2i+2`. Entity ids are integers in `[0, capacity)`; keys are finite numbers. Every hot op allocates zero bytes after construction (hole-punching sift -- one write per level, no 3-write swap).
+
+```js
+import { BinaryHeap } from '@zakkster/lite-logn';
+
+const pq = new BinaryHeap(1024, 'min');   // capacity 1024, min-heap
+pq.push(7, 5.0);                          // entity 7 at priority 5.0
+pq.push(3, 2.5);
+pq.push(9, 8.0);
+pq.peek();        // -> 3   (id of the extremum)
+pq.topKey();      // -> 2.5 (its key)
+pq.changeKey(9, 1.0);   // reprioritize entity 9 to the front
+pq.pop();         // -> 9   (removes and returns the new extremum)
+pq.remove(7);     // -> true (addressable delete by id)
+
+// Floyd O(n) bulk build from parallel arrays:
+const heap = BinaryHeap.build('max', [0, 1, 2, 3], [4.0, 1.0, 9.0, 2.0], 16);
+heap.pop();       // -> 2   (the id whose key 9.0 is the max)
+```
+
+| Member | Signature | Complexity | Notes |
+| --- | --- | --- | --- |
+| constructor | `new BinaryHeap(capacity, kind = 'min')` | O(capacity) | `capacity` integer in `[1, 2^31-1]`; `kind` is `'min'` or `'max'`. Allocates the three typed arrays once; `_pos.fill(-1)`. |
+| `push` | `push(id, key) -> void` | O(log n) | id in `[0, capacity)`, not already present; key finite. Throws on out-of-range/duplicate id, non-finite key, or full heap. |
+| `pop` | `pop() -> number \| undefined` | O(log n) | Removes and returns the extremum's id; `undefined` if empty (no throw). |
+| `peek` | `peek() -> number \| undefined` | O(1) | The extremum's id; `undefined` if empty. |
+| `topKey` | `topKey() -> number \| undefined` | O(1) | The extremum's key; `undefined` if empty. |
+| `keyOf` | `keyOf(id) -> number \| undefined` | O(1) | The key associated with id; `undefined` if absent. Out-of-range id throws. |
+| `has` | `has(id) -> boolean` | O(1) | True iff id is resident. Out-of-range id throws. |
+| `changeKey` | `changeKey(id, newKey) -> void` | O(log n) | Reprioritize a present entity (auto-direction sift); a non-member id throws. |
+| `remove` | `remove(id) -> boolean` | O(log n) | Idempotent: `false` if absent, `true` if removed. |
+| `clear` | `clear() -> void` | O(capacity) | Resets size and the reverse map. |
+| `forEach` | `forEach(fn) -> void` | O(n) | Visits `(id, key)` in UNSPECIFIED (heap-array) order -- NOT sorted / pop order. |
+| `[Symbol.iterator]` | `for (const id of heap)` | O(n) | Yields live ids in UNSPECIFIED order. |
+| `size` / `capacity` / `kind` | getters | O(1) | Live count / fixed capacity / `'min'` \| `'max'`. |
+| `BinaryHeap.build` | `build(kind, ids, keys, capacity) -> BinaryHeap` | O(n) | Floyd bulk build from parallel arrays; fails closed on duplicate/out-of-range id, non-finite key, or `count > capacity`. |
+
+Member signatures for later members are appended here as each ships.
+
+## Zero-GC design notes
+
+- **Array-embedded members allocate no nodes.** BinaryHeap, Fenwick, and SegmentTree live in flat typed arrays; there is no `new Node` per op, so there is nothing to collect. The parent / child / sibling relationships are index arithmetic (`2i+1`, `i & -i`), not pointers.
+- **Pointer-based members use a pointer-free node pool.** SkipList and the later balanced-BST members allocate a slot INDEX from a free list over parallel `Uint32Array` link columns -- never a heap object. `NIL = 0`, slot 0 unused.
+- **Fixed, preallocated capacity.** Overflow fails closed (a `[lite-logn]`-tagged throw), never a silent grow + amortized resize -- a resize would break the worst-case bound the witness proves.
+
+| Op class | Allocation |
+| --- | --- |
+| `BinaryHeap` push / pop / peek / topKey / keyOf / has / changeKey / remove | 0 B/op |
+| `BinaryHeap` constructor / `build` / `clear` | O(capacity) typed arrays, once (cold) |
+
+The allocation table is filled in per member as each lands, with the gated `R^2` / slope numbers from its witness run.
+
+## Testing
+
+`node:test` only, zero runtime deps. At v0.1.0 the harnesses are scaffolds that run green and empty (no member to exercise yet); each member session fills its tier.
+
+- `npm test` -- per-member contract + boundary + fuzz-vs-oracle suites, plus the cross-member `QaAudit` block (VERSION trinity, author-spelling guard, ASCII-only source, the six-file pack).
+- `npm run torture` -- `node --expose-gc test/torture.mjs`: 0 B/op on every hot path, `gc major = 0`, leak tracker `size 0/0`.
+- `npm run witness` -- the O(log n) witness harness: log-linear `R^2` + slope fit, with an O(n) foil that must leave the line.
+- `npm run test:perf` -- `@zakkster/lite-perf-gate` zero-alloc scenarios, each with a must-fail teeth case that proves the instrument has teeth.
+- `npm run test:types` -- `tsc` over the ambient `LogN.d.ts` surface.
+- `npm run verify` -- all of the above in sequence.
+
+## What this is not
+
+- **Not a bounded-integer priority queue.** If your priorities are small bounded integers, a heap's O(log n) is the wrong tool -- use `@zakkster/lite-o1`'s `BucketQueue` (Dial, O(1)) or `@zakkster/lite-scheduler`'s `FastBitScheduler`. lite-logn's heap is the GENERAL comparator PQ at O(log n).
+- **Not an approximate-membership library.** Bloom / cuckoo / binary-fuse filters live in `@zakkster/lite-filter`. lite-logn owns exact ordered structures.
+- **Not a cache.** `@zakkster/lite-lru` uses ordering internally for eviction but is a cache, not an ordered-collection library.
+- **Not a grow-on-demand collection.** Capacity is fixed at construction and overflow fails closed.
+
+## Ecosystem
+
+Part of the `@zakkster/*` LiteLibrariesSuite of zero-GC, single-file ESM micro-libraries.
+
+- [`@zakkster/lite-o1`](https://www.npmjs.com/package/@zakkster/lite-o1) -- the O(1) sibling and intended pair. lite-o1 holds the constant; lite-logn holds the logarithm. Keep the witnesses kin: a flat line vs a straight-log line.
+- [`@zakkster/lite-filter`](https://www.npmjs.com/package/@zakkster/lite-filter) -- approximate / probabilistic membership.
+- [`@zakkster/lite-lru`](https://www.npmjs.com/package/@zakkster/lite-lru) -- zero-GC cache family.
+
+## License
+
+MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>

package/llms.txt

@@ -0,0 +1,83 @@
+# @zakkster/lite-logn
+
+Version: 0.1.0
+License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
+Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
+Node: >= 18.
+
+## What it is
+
+A tree-shakeable, zero-GC family of O(log n) data structures that PROVES its
+logarithm instead of asserting it. The complexity class is the product: every
+hot op is O(log n) worst-case (or expected / amortized where stated) and
+allocates zero bytes after construction, and a shipped witness harness fits
+`nsPerOp = intercept + slope * log2(n)` and demonstrates the straight log line
+against a built-in O(n) foil that leaves it.
+
+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 ships its first member, BinaryHeap. The planned 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,
+  `_id` Uint32Array, `_pos` Int32Array reverse map) with children at 2i+1 / 2i+2.
+  push / pop / changeKey / remove are O(log n); peek / topKey / keyOf / has are
+  O(1); nothing allocated per op. The reverse-index map makes changeKey / remove
+  addressable by a caller-supplied entity id. The cleanest witness in the family
+  and the one that calibrates the shared R^2 floor + slope band gate (pop).
+- Fenwick / BIT (v0.2.0) -- BOTH point-update AND prefix-sum in O(log n) over a
+  single flat array via the lowest-set-bit walk (`i & -i`); rangeSum is two
+  prefix queries. Two straight log lines.
+- SegmentTree (v0.3.0) -- general associative range-query (min / max / sum / gcd)
+  + point-update over a flat, array-embedded tree, O(log n) worst-case; the fold
+  is chosen once at construction.
+- 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.
+
+## Exports (from the single main file LogN.js)
+
+- `VERSION` -- string. The package version; one of the three version sites
+  (package.json / LogN.js VERSION const / this file's `Version:` header).
+- `BinaryHeap` -- class. An indexed binary heap (addressable priority queue).
+  - `new BinaryHeap(capacity, kind = 'min')` -- capacity is an integer in
+    [1, 2^31-1]; kind is 'min' or 'max'. Allocates the three typed arrays once.
+  - `push(id, key)` -> void. id integer in [0, capacity), not already present;
+    key finite. Throws on out-of-range/duplicate id, non-finite key, full heap.
+  - `pop()` -> id | undefined. Removes the extremum; undefined if empty (no throw).
+  - `peek()` -> id | undefined. `topKey()` -> key | undefined. Read-only.
+  - `keyOf(id)` -> key | undefined. `has(id)` -> boolean. Out-of-range id throws.
+  - `changeKey(id, newKey)` -> void. Reprioritize a present entity (auto-direction
+    sift); a non-member id throws (never a silent no-op).
+  - `remove(id)` -> boolean. Idempotent: false if absent, true if removed.
+  - `size` / `capacity` / `kind` getters; `clear()`; `forEach(fn)` and
+    `[Symbol.iterator]()` yield live ids in UNSPECIFIED (heap-array) order -- NOT
+    sorted / pop order.
+  - `BinaryHeap.build(kind, ids, keys, capacity)` -> BinaryHeap. Floyd O(n) bulk
+    build from parallel arrays; fails closed on duplicate/out-of-range id,
+    non-finite key, or count > capacity.
+
+Member exports (one tree-shakeable class each) are appended here as each member
+ships.
+
+## Design bounds
+
+- Zero runtime deps; node:test only; ASCII-only source.
+- Single PascalCase main file LogN.js; sideEffects: false; tree-shakeable named
+  exports, no barrel.
+- Fixed, preallocated capacity (node / element count, not bytes). Fail closed on
+  every unverified state; `null` is not zero.
+- typeof-guard FIRST, before any coercion, at the door of every mutating op.
+- Zero allocation on every steady-state hot path (0 B/op), proven by
+  `node --expose-gc test/torture.mjs`.
+
+## Cross-package boundaries
+
+- @zakkster/lite-o1 -- the O(1) sibling and intended pair. Any BOUNDED-INTEGER
+  priority queue is O(1) and belongs there (Dial's bucket queue); lite-logn's
+  heap is the GENERAL comparator PQ at O(log n).
+- @zakkster/lite-filter -- owns approximate / probabilistic membership;
+  lite-logn owns exact ordered structures. No overlap.

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@zakkster/lite-logn",
+  "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
+  "version": "0.1.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.",
+  "type": "module",
+  "main": "./LogN.js",
+  "module": "./LogN.js",
+  "types": "./LogN.d.ts",
+  "exports": {
+    ".": {
+      "types": "./LogN.d.ts",
+      "node": "./LogN.js",
+      "import": "./LogN.js",
+      "default": "./LogN.js"
+    }
+  },
+  "files": [
+    "LogN.js",
+    "LogN.d.ts",
+    "llms.txt",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js test/Bench.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",
+    "verify": "npm test && npm run test:types && npm run torture && npm run witness && npm run test:perf"
+  },
+  "keywords": [
+    "binary-heap",
+    "heap",
+    "priority-queue",
+    "d-ary-heap",
+    "fenwick",
+    "bit",
+    "binary-indexed-tree",
+    "prefix-sum",
+    "segment-tree",
+    "range-query",
+    "range-sum",
+    "skip-list",
+    "ordered-set",
+    "balanced-bst",
+    "bst",
+    "log-n",
+    "logarithmic",
+    "order-statistics",
+    "rank-select",
+    "data-structures",
+    "zero-gc",
+    "gc",
+    "typed-array",
+    "soa",
+    "tree-shakeable",
+    "witness",
+    "performance",
+    "lightweight",
+    "zero-dependency"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@zakkster/lite-gc-profiler": "^1.16.0",
+    "@zakkster/lite-leak": "^1.10.0",
+    "@zakkster/lite-perf-gate": "^1.4.2",
+    "esbuild": "^0.28.2",
+    "typescript": "^7.0.2"
+  },
+  "homepage": "https://github.com/PeshoVurtoleta/lite-logn#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeshoVurtoleta/lite-logn.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PeshoVurtoleta/lite-logn/issues",
+    "email": "shinikchiev@yahoo.com"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/PeshoVurtoleta"
+  },
+  "sideEffects": false
+}