@zakkster/lite-logn 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,58 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-20
+
+### Added
+
+- **MinMaxHeap** -- the seventh member and the family's DOUBLE-ENDED priority queue
+  (DEPQ): a single array-embedded binary heap whose levels ALTERNATE min / max (Atkinson,
+  Sack, Santoro & Strothotte 1986). Even depth (the root is depth 0) is a MIN level, odd
+  depth a MAX level, so the global minimum sits at the root and the global maximum is the
+  LARGER of the root's up-to-two children. `peekMin` / `peekMax` / `peekMinKey` /
+  `peekMaxKey` are O(1); `push` / `popMin` / `popMax` are all WORST-case O(log n) from that
+  ONE heap (no second heap, no paired-heap correspondence). Surface: `push(id, key)` /
+  `popMin` / `popMax` / `peekMin` / `peekMax` / `peekMinKey` / `peekMaxKey` / `clear` /
+  `forEach` / `[Symbol.iterator]`, and `size` / `capacity` getters, plus a Floyd O(n)
+  `MinMaxHeap.build(ids, keys, capacity)` (deepest-first, level-aware sift-down). Keys are
+  finite numbers (typeof-guarded before coercion -- Symbol / BigInt / NaN / +-Infinity fail
+  closed with a `[lite-logn]` throw, key checked FIRST, then the id, then a full heap).
+- **id + key payload, NON-addressable (the asymmetry vs BinaryHeap).** Two parallel
+  pointer-free typed-array columns (`_id` Uint32Array + `_key` Float64Array), the BinaryHeap
+  id+key idiom -- but with NO `_pos` reverse map, and therefore deliberately NO `changeKey` /
+  `remove`. The id is an OPAQUE Uint32 payload (NOT unique; the full [0, 2^32) domain, wider
+  than BinaryHeap's [0, capacity)). A DEPQ's job is the two extremes; addressability is the
+  separable concern BinaryHeap already carries. There is also NO `kind` argument / getter (a
+  DEPQ has both ends; a kind getter would be a lie).
+- **Classic one-element-per-node min-max heap only.** The interval-heap DEPQ (two elements
+  per node) is a deliberately deferred alternative -- named, never silently omitted (see
+  `decisions/0009-minmaxheap.md` and "What this is not").
+- **Level parity, computed zero-alloc.** Slot i is a MIN level iff
+  `((31 - Math.clz32(i + 1)) & 1) === 0`. The sifts are hole-punching (one write per level,
+  only local scalar temporaries): `push` compares to the parent to pick the own-level vs
+  other-level chain then bubbles by grandparents; `popMin` / `popMax` trickle down over the
+  up-to-six descendants (children + grandchildren), bound-checking every grandchild index
+  against the live size (the classic min-max off-by-one, verified at n = 1, 2, 3, 4).
+
+### Verified
+
+- **Witness (D-M5).** `MinMaxHeap.popMin` is the gated O(log n) witness op (the full-height
+  level-aware trickle-down). It inherits the FROZEN family R^2 floor 0.958 and calibrates its
+  OWN slope band by the shared ADR-0004 method: median-of-15 popMin fit-runs = 10.30 ns/level
+  (runs spanned 9.38..10.59, R^2 0.9897..0.9991), band = median x `[0.6, 1.4]` = `[6.18, 14.42]`.
+  A DEPQ whose push / popMin / popMax are ALL worst-case, so there is NO max-single-op line.
+  The O(n) foil is a linear min-scan-and-splice extract-min (R^2 ~ 0.77, OFF the line).
+- **Zero-GC.** `node --expose-gc test/torture.mjs` -- 0 B/op on the popMin / popMax / mixed
+  push+popMin+popMax churn and the peek read lanes, gc major = 0, the deliberately-allocating
+  control lane still non-zero (teeth), arrayBuffers do not grow across fill/clear soak cycles.
+  `npm run test:perf` -- 0 scavenges + `grows === 0` on every MinMaxHeap scenario.
+
+### Notes
+
+- `LogN.js` gains `MMH_MAX_CAPACITY` (`0x7FFFFFFF`) + the `MinMaxHeap` class, appended after
+  Scapegoat; the prior six classes stay BYTE-IDENTICAL (only the `VERSION` const changes above
+  the append point). Version bumped to 0.7.0 across `package.json`, `LogN.js`, and `llms.txt`.
+
 ## [0.6.0] - 2026-09-20
 
 ### Added
@@ -312,7 +364,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.4.0...HEAD
+[Unreleased]: https://github.com/PeshoVurtoleta/lite-logn/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/PeshoVurtoleta/lite-logn/compare/v0.6.0...v0.7.0
 [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

package/LogN.d.ts

@@ -280,3 +280,52 @@ export class Scapegoat {
     /** Empty the tree, keeping capacity. */
     clear(): this;
 }
+
+/**
+ * A min-max heap: a DOUBLE-ENDED priority queue (DEPQ) in ONE array-embedded binary heap
+ * whose levels ALTERNATE min / max (Atkinson et al. 1986). The minimum is the root; the
+ * maximum is the larger of the root's up-to-two children. peekMin / peekMax are O(1);
+ * push / popMin / popMax are O(log n) WORST-case. Two parallel typed-array columns (_key
+ * Float64, _id Uint32); the id is an OPAQUE Uint32 payload in [0, 2^32) (not unique, no
+ * reverse map), so there is deliberately NO changeKey / remove (the asymmetry vs
+ * BinaryHeap). Keys are finite numbers (typeof-guarded before coercion; Symbol / BigInt /
+ * NaN / +-Infinity fail closed). Fixed capacity: a full heap throws. Every hot op
+ * allocates zero bytes.
+ */
+export class MinMaxHeap {
+    /** @param capacity exact max live entries; integer in [1, 2^31-1]. */
+    constructor(capacity: number);
+
+    /** Live entry count. */
+    readonly size: number;
+    /** The fixed capacity this heap was sized for. */
+    readonly capacity: number;
+
+    /** Insert id with priority key. Throws on non-finite key, out-of-range id, or a full heap. */
+    push(id: number, key: number): void;
+    /** Remove and return the id at the minimum key, or undefined if empty. */
+    popMin(): number | undefined;
+    /** Remove and return the id at the maximum key, or undefined if empty. */
+    popMax(): number | undefined;
+    /** The id at the minimum key, or undefined if empty. */
+    peekMin(): number | undefined;
+    /** The id at the maximum key, or undefined if empty. */
+    peekMax(): number | undefined;
+    /** The minimum key, or undefined if empty. */
+    peekMinKey(): number | undefined;
+    /** The maximum key, or undefined if empty. */
+    peekMaxKey(): number | undefined;
+    /** Empty the heap, keeping capacity. */
+    clear(): void;
+    /** Visit every live (id, key) pair in unspecified (heap-array) order. */
+    forEach(fn: (id: number, key: number, heap: MinMaxHeap) => 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 (level-aware sift-down). */
+    static build(
+        ids: ArrayLike<number>,
+        keys: ArrayLike<number>,
+        capacity: number,
+    ): MinMaxHeap;
+}

package/LogN.js

@@ -39,7 +39,7 @@
  */
 
 /** Package version. One of the three version sites (package.json / VERSION / llms.txt). */
-export const VERSION = '0.6.0';
+export const VERSION = '0.7.0';
 
 // --- members land here, append-only, one tree-shakeable class each -----------
 // BinaryHeap  (v0.1.0 session) -- indexed O(log n) min|max heap  (BELOW)
@@ -2496,3 +2496,379 @@ export class Scapegoat {
         throw new RangeError('[lite-logn] Scapegoat full (capacity ' + this._cap + ')');
     }
 }
+
+// MinMaxHeap (v0.7.0 session) -- a DEPQ (double-ended priority queue), array-embedded min-max heap (BELOW).
+
+/**
+ * Max MinMaxHeap capacity: slot indices 0..cap-1 index the two parallel, pointer-free
+ * typed-array columns (`_key` Float64Array, `_id` Uint32Array). Children of slot i are
+ * `2i+1` / `2i+2` and grandchildren `4i+3 .. 4i+6`, so the deepest index arithmetic a
+ * hot op performs is `4*i + 6`; capping capacity at 2^31-1 keeps every derived index a
+ * positive int32. The index arithmetic, not the byte count, is the hard ceiling -- the
+ * same "the arithmetic caps it" reasoning as BinaryHeap's BH_MAX_CAPACITY.
+ */
+const MMH_MAX_CAPACITY = 0x7FFFFFFF; // 2^31 - 1
+
+/**
+ * A MIN-MAX HEAP: a DOUBLE-ENDED priority queue (DEPQ) held in ONE array-embedded binary
+ * heap whose levels ALTERNATE min / max (Atkinson, Sack, Santoro & Strothotte 1986). Even
+ * depth (the root is depth 0) is a MIN level, odd depth is a MAX level, so the global
+ * minimum sits at the root and the global maximum is the LARGER of the root's up-to-two
+ * children. That single alternating heap answers BOTH ends: `peekMin` / `peekMax` are
+ * O(1); `push` / `popMin` / `popMax` are O(log n) WORST-case. It is the family's DEPQ --
+ * where BinaryHeap fixes one extreme at construction, a min-max heap serves both from one
+ * structure without a second heap or a paired-heap correspondence to maintain.
+ *
+ * Storage (allocated once, sized to capacity), the BinaryHeap id+key idiom:
+ *   - `_key` Float64Array -- the priority key at each heap SLOT (min-max-ordered).
+ *   - `_id`  Uint32Array  -- the opaque payload id at each heap SLOT (moves with its key).
+ * There is NO reverse-index map (`_pos`) and so NO addressable `changeKey` / `remove`: the
+ * id is an OPAQUE Uint32 payload, NOT a unique handle -- duplicate ids are allowed, and the
+ * id domain is the full Uint32 range [0, 2^32) (a wider domain than BinaryHeap's [0,
+ * capacity), which only that member's `_pos` map constrains). See decisions/0009.
+ *
+ * Level parity is computed zero-alloc: slot i (0-based) is a MIN level iff
+ * `((31 - Math.clz32(i + 1)) & 1) === 0` (the depth `31 - clz32(i+1)` is even). The sift
+ * is HOLE-PUNCHING (not a 3-write swap chain): the moving element is cached in locals once
+ * and the hole walks writing ONE slot per level.
+ *   - push: append at the tail, compare the new element to its PARENT to pick the own-level
+ *     vs other-level chain, then bubble by GRANDPARENT comparisons up the min-or-max chain.
+ *   - popMin / popMax: open a hole at the root (min) or at the max-of-{slot1,slot2} (max),
+ *     move the last element into it, and trickle DOWN over CHILDREN + GRANDCHILDREN (a min
+ *     level sinks toward the smallest of the up-to-six descendants, a max level toward the
+ *     largest); a GRANDCHILD move does the extra parent re-check that keeps the alternating
+ *     order intact. Every one of the four grandchild indices is bound-checked against the
+ *     live size (the classic min-max off-by-one). Zero bytes allocated after construction.
+ *
+ * Keys are FINITE numbers (typeof-guarded BEFORE coercion -- Symbol / BigInt / NaN /
+ * +-Infinity fail closed with a `[lite-logn]` throw); ids are integers in [0, 2^32). A key
+ * guard fires FIRST, then the id guard, then the full-heap guard -- any throw leaves `size`
+ * unchanged. Every peek / pop on an EMPTY heap returns `undefined` and NEVER throws. Fixed
+ * capacity: overflow throws, never silently drops.
+ *
+ * This is the classic ONE-element-per-node min-max heap ONLY; the interval-heap DEPQ (two
+ * elements per node) is a deliberately deferred alternative -- see decisions/0009 + NOT FOR.
+ */
+export class MinMaxHeap {
+    /**
+     * @param {number} capacity  exact max live entries; integer in [1, 2^31-1].
+     */
+    constructor(capacity) {
+        // typeof guard BEFORE coercion (Number.isInteger is Symbol/BigInt-safe).
+        if (typeof capacity !== 'number' || !Number.isInteger(capacity) ||
+            capacity < 1 || capacity > MMH_MAX_CAPACITY) {
+            throw new RangeError(
+                '[lite-logn] MinMaxHeap capacity must be an integer in [1, 2^31-1], got ' +
+                String(capacity));
+        }
+        this._key = new Float64Array(capacity); // key at each heap slot
+        this._id = new Uint32Array(capacity);   // opaque payload id at each heap slot
+        this._cap = capacity;                    // exact fixed capacity
+        this._n = 0;                             // live entries (heap size)
+    }
+
+    /** 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; }
+
+    /**
+     * Insert entity `id` with priority `key`. O(log n). Fails closed: a non-finite /
+     * non-number key (checked FIRST), a non-integer / out-of-range id, or a full heap each
+     * throw `[lite-logn]` as a no-op (size unchanged).
+     * @param {number} id   integer in [0, 2^32), an OPAQUE payload (not required unique)
+     * @param {number} key  a finite number
+     */
+    push(id, key) {
+        if (typeof key !== 'number' || !Number.isFinite(key)) return this._badKey(key);
+        if (typeof id !== 'number' || !Number.isInteger(id) || id < 0 || id > 0xFFFFFFFF) {
+            return this._badId(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 id at the MINIMUM key (the root), or `undefined` if empty
+     * (never throws on empty). O(log n).
+     * @returns {number|undefined}
+     */
+    popMin() {
+        const n = this._n;
+        if (n === 0) return undefined;
+        const top = this._id[0];
+        const last = n - 1;
+        this._n = last;
+        if (last > 0) this._siftDownMin(0, this._key[last], this._id[last]);
+        return top;
+    }
+
+    /**
+     * Remove and return the id at the MAXIMUM key (the larger of the root's up-to-two
+     * children, or the root itself when the heap holds one element), or `undefined` if
+     * empty (never throws on empty). O(log n).
+     * @returns {number|undefined}
+     */
+    popMax() {
+        const n = this._n;
+        if (n === 0) return undefined;
+        if (n === 1) { this._n = 0; return this._id[0]; }
+        const K = this._key;
+        // Max is at slot 1, unless slot 2 exists (n > 2) and holds a larger key.
+        let mi = 1;
+        if (n > 2 && K[2] > K[1]) mi = 2;
+        const top = this._id[mi];
+        const last = n - 1;
+        this._n = last;
+        // If the max WAS the last element, dropping the tail already removed it.
+        if (mi !== last) this._siftDownMax(mi, K[last], this._id[last]);
+        return top;
+    }
+
+    /** The id at the minimum key (root), or `undefined` if empty. Read-only. O(1). */
+    peekMin() { return this._n === 0 ? undefined : this._id[0]; }
+
+    /** The minimum key (root), or `undefined` if empty. O(1). */
+    peekMinKey() { return this._n === 0 ? undefined : this._key[0]; }
+
+    /** The id at the maximum key, or `undefined` if empty. Read-only. O(1). */
+    peekMax() {
+        const n = this._n;
+        if (n === 0) return undefined;
+        if (n === 1) return this._id[0];
+        const K = this._key;
+        return (n > 2 && K[2] > K[1]) ? this._id[2] : this._id[1];
+    }
+
+    /** The maximum key, or `undefined` if empty. O(1). */
+    peekMaxKey() {
+        const n = this._n;
+        if (n === 0) return undefined;
+        if (n === 1) return this._key[0];
+        const K = this._key;
+        return (n > 2 && K[2] > K[1]) ? K[2] : K[1];
+    }
+
+    /** Empty the heap. O(1) (resets size; the columns are kept). */
+    clear() { this._n = 0; }
+
+    /**
+     * Visit every live (id, key) pair in UNSPECIFIED (heap-array) order -- NOT sorted /
+     * not pop order. O(n) cold scan, allocation-free (pass a hoisted callback).
+     * @param {(id:number, key:number, heap:MinMaxHeap)=>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) (deepest-first, level-aware sift-down), rather than n individual O(log n)
+     * pushes. COLD path; fails closed on any violation (non-array-like / length mismatch,
+     * count > capacity, non-integer / out-of-range id, non-finite key) before use.
+     * @param {ArrayLike<number>} ids   integers in [0, 2^32) (not required unique)
+     * @param {ArrayLike<number>} keys  finite numbers, keys.length === ids.length
+     * @param {number} capacity
+     * @returns {MinMaxHeap}
+     */
+    static build(ids, keys, capacity) {
+        const heap = new MinMaxHeap(capacity);
+        if (ids == null || keys == null ||
+            typeof ids.length !== 'number' || typeof keys.length !== 'number') {
+            throw new TypeError('[lite-logn] MinMaxHeap.build needs array-like ids and keys');
+        }
+        const count = ids.length;
+        if (keys.length !== count) {
+            throw new RangeError(
+                '[lite-logn] MinMaxHeap.build ids/keys length mismatch (' +
+                count + ' vs ' + keys.length + ')');
+        }
+        if (count > capacity) {
+            throw new RangeError(
+                '[lite-logn] MinMaxHeap.build count ' + count + ' exceeds capacity ' + capacity);
+        }
+        const K = heap._key, I = heap._id;
+        for (let i = 0; i < count; i++) {
+            const id = ids[i];
+            if (typeof id !== 'number' || !Number.isInteger(id) || id < 0 || id > 0xFFFFFFFF) {
+                throw new RangeError(
+                    '[lite-logn] MinMaxHeap.build id must be an integer in [0, 2^32), got ' +
+                    String(id));
+            }
+            const key = keys[i];
+            if (typeof key !== 'number' || !Number.isFinite(key)) {
+                throw new TypeError(
+                    '[lite-logn] MinMaxHeap.build key must be a finite number, got ' + String(key));
+            }
+            K[i] = key;
+            I[i] = id;
+        }
+        heap._n = count;
+        // Floyd: sift down every internal node, deepest-first, level-aware. O(n).
+        for (let i = (count >> 1) - 1; i >= 0; i--) {
+            if (((31 - Math.clz32(i + 1)) & 1) === 0) heap._siftDownMin(i, K[i], I[i]);
+            else heap._siftDownMax(i, K[i], I[i]);
+        }
+        return heap;
+    }
+
+    // ---- private hole-punching sifts (hot bodies) --------------------------
+
+    /**
+     * Sift UP from `hole` after an append: compare to the PARENT to decide whether the new
+     * element belongs on its own level's chain or the other level's, then bubble it up by
+     * GRANDPARENT comparisons. One write per level; zero temporaries.
+     * @private
+     */
+    _siftUp(hole, key, id) {
+        const K = this._key, I = this._id;
+        if (hole === 0) { K[0] = key; I[0] = id; return; }
+        const parent = (hole - 1) >> 1;
+        // Depth parity of `hole`: MIN level iff (31 - clz32(hole+1)) is even.
+        if (((31 - Math.clz32(hole + 1)) & 1) === 0) { // hole is on a MIN level
+            if (key > K[parent]) {                     // parent is a MAX node: element belongs above it
+                K[hole] = K[parent]; I[hole] = I[parent];
+                this._bubbleUpMax(parent, key, id);
+            } else {
+                this._bubbleUpMin(hole, key, id);
+            }
+        } else {                                       // hole is on a MAX level
+            if (key < K[parent]) {                     // parent is a MIN node: element belongs above it
+                K[hole] = K[parent]; I[hole] = I[parent];
+                this._bubbleUpMin(parent, key, id);
+            } else {
+                this._bubbleUpMax(hole, key, id);
+            }
+        }
+    }
+
+    /** Bubble a MIN-level hole up by grandparents while the element is smaller. @private */
+    _bubbleUpMin(hole, key, id) {
+        const K = this._key, I = this._id;
+        while (hole > 2) {                    // has a grandparent (hole >= 3)
+            const gp = (hole - 3) >> 2;       // (((hole-1)>>1)-1)>>1
+            if (key < K[gp]) { K[hole] = K[gp]; I[hole] = I[gp]; hole = gp; }
+            else break;
+        }
+        K[hole] = key; I[hole] = id;
+    }
+
+    /** Bubble a MAX-level hole up by grandparents while the element is larger. @private */
+    _bubbleUpMax(hole, key, id) {
+        const K = this._key, I = this._id;
+        while (hole > 2) {                    // has a grandparent (hole >= 3)
+            const gp = (hole - 3) >> 2;       // (((hole-1)>>1)-1)>>1
+            if (key > K[gp]) { K[hole] = K[gp]; I[hole] = I[gp]; hole = gp; }
+            else break;
+        }
+        K[hole] = key; I[hole] = id;
+    }
+
+    /**
+     * Trickle a MIN-level hole DOWN toward the SMALLEST of its up-to-six descendants
+     * (children `2h+1`/`2h+2`, grandchildren `4h+3..4h+6`). A grandchild move does the
+     * extra max-parent re-check that keeps the alternating order. Every grandchild index
+     * is bound-checked against the live size. One write per level; zero temporaries.
+     * @private
+     */
+    _siftDownMin(hole, key, id) {
+        const K = this._key, I = this._id, n = this._n;
+        for (;;) {
+            const c1 = (hole << 1) + 1;
+            if (c1 >= n) break;                       // leaf: no children -> settle here
+            const c2 = c1 + 1;
+            let m = c1, mGrand = false;               // smallest descendant so far
+            if (c2 < n && K[c2] < K[m]) m = c2;
+            const gEnd = (c2 << 1) + 2;               // 4h+6, the last grandchild index
+            for (let g = (c1 << 1) + 1; g < n && g <= gEnd; g++) { // grandchildren 4h+3..4h+6
+                if (K[g] < K[m]) { m = g; mGrand = true; }
+            }
+            if (K[m] >= key) break;                   // element is <= every descendant -> settle
+            if (!mGrand) {                            // smallest is a direct child (a leaf) -> place, done
+                K[hole] = K[m]; I[hole] = I[m];
+                hole = m;
+                break;
+            }
+            // smallest is a grandchild: pull it up, then reconcile with its MAX-level parent.
+            K[hole] = K[m]; I[hole] = I[m];
+            const p = (m - 1) >> 1;
+            if (key > K[p]) {                         // element too big under max parent p: settle it at p,
+                const pk = K[p], pid = I[p];          // carry p's (smaller) value on down from m.
+                K[p] = key; I[p] = id;
+                key = pk; id = pid;
+            }
+            hole = m;
+        }
+        K[hole] = key; I[hole] = id;
+    }
+
+    /**
+     * Trickle a MAX-level hole DOWN toward the LARGEST of its up-to-six descendants. Mirror
+     * of `_siftDownMin`: a grandchild move re-checks the MIN-level parent. Every grandchild
+     * index is bound-checked. One write per level; zero temporaries.
+     * @private
+     */
+    _siftDownMax(hole, key, id) {
+        const K = this._key, I = this._id, n = this._n;
+        for (;;) {
+            const c1 = (hole << 1) + 1;
+            if (c1 >= n) break;                       // leaf: no children -> settle here
+            const c2 = c1 + 1;
+            let m = c1, mGrand = false;               // largest descendant so far
+            if (c2 < n && K[c2] > K[m]) m = c2;
+            const gEnd = (c2 << 1) + 2;               // 4h+6, the last grandchild index
+            for (let g = (c1 << 1) + 1; g < n && g <= gEnd; g++) { // grandchildren 4h+3..4h+6
+                if (K[g] > K[m]) { m = g; mGrand = true; }
+            }
+            if (K[m] <= key) break;                   // element is >= every descendant -> settle
+            if (!mGrand) {                            // largest is a direct child (a leaf) -> place, done
+                K[hole] = K[m]; I[hole] = I[m];
+                hole = m;
+                break;
+            }
+            // largest is a grandchild: pull it up, then reconcile with its MIN-level parent.
+            K[hole] = K[m]; I[hole] = I[m];
+            const p = (m - 1) >> 1;
+            if (key < K[p]) {                         // element too small under min parent p: settle it at p,
+                const pk = K[p], pid = I[p];          // carry p's (larger) value on down from m.
+                K[p] = key; I[p] = id;
+                key = pk; id = pid;
+            }
+            hole = m;
+        }
+        K[hole] = key; I[hole] = id;
+    }
+
+    // ---- cold path only: throw builders (string concat off the hot body) ---
+
+    /** @private */
+    _badId(id) {
+        throw new RangeError(
+            '[lite-logn] MinMaxHeap id must be an integer in [0, 2^32), got ' + String(id));
+    }
+
+    /** @private */
+    _badKey(key) {
+        throw new TypeError(
+            '[lite-logn] MinMaxHeap key must be a finite number, got ' + String(key));
+    }
+
+    /** @private */
+    _full() {
+        throw new RangeError('[lite-logn] MinMaxHeap 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.6.0 ships six members: BinaryHeap (array-embedded O(log n) push / pop min|max heap), Fenwick / BIT (O(log n) point-update AND prefix-sum via the `i & -i` walk), SegmentTree (O(log n) associative range-query -- min / max / sum / gcd -- plus point-update over a flat 2n array), SkipList (pointer-free expected-O(log n) ordered map over a private free-list node pool), Treap (a randomized-balanced augmented ordered map with O(log n) rank / select / split / merge), and Scapegoat (a DETERMINISTIC weight-balanced augmented ordered map: worst-case-O(log n) get, amortized-O(log n) set / delete, zero-GC rebuild) -- 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.7.0 ships seven members: BinaryHeap (array-embedded O(log n) push / pop min|max heap), Fenwick / BIT (O(log n) point-update AND prefix-sum via the `i & -i` walk), SegmentTree (O(log n) associative range-query -- min / max / sum / gcd -- plus point-update over a flat 2n array), SkipList (pointer-free expected-O(log n) ordered map over a private free-list node pool), Treap (a randomized-balanced augmented ordered map with O(log n) rank / select / split / merge), Scapegoat (a DETERMINISTIC weight-balanced augmented ordered map: worst-case-O(log n) get, amortized-O(log n) set / delete, zero-GC rebuild), and MinMaxHeap (an array-embedded double-ended priority queue: O(1) peekMin / peekMax, O(log n) push / popMin / popMax) -- 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.6.0 ships six members: BinaryHeap, Fenwick, SegmentTree, SkipList, Treap and Scapegoat.** Members land one per session, each append-only so prior members stay byte-identical. The planned roster below fills in per release.
+**v0.7.0 ships seven members: BinaryHeap, Fenwick, SegmentTree, SkipList, Treap, Scapegoat and MinMaxHeap.** 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
@@ -62,6 +62,7 @@ Every hot op allocates zero bytes after construction, and `npm run witness` prov
   - [SkipList](#skiplist)
   - [Treap](#treap)
   - [Scapegoat](#scapegoat)
+  - [MinMaxHeap](#minmaxheap)
 - [Zero-GC design notes](#zero-gc-design-notes)
 - [Testing](#testing)
 - [What this is not](#what-this-is-not)
@@ -86,7 +87,7 @@ lite-logn ships the O(log n) structures that matter with the allocation removed
 
 ## The roster
 
-One member per session, each landing append-only (prior members stay byte-identical). At v0.6.0, BinaryHeap, Fenwick, SegmentTree, SkipList, Treap and Scapegoat are shipped.
+One member per session, each landing append-only (prior members stay byte-identical). At v0.7.0, BinaryHeap, Fenwick, SegmentTree, SkipList, Treap, Scapegoat and MinMaxHeap are shipped.
 
 | Member | Version | Status | Shape | Hot ops |
 | --- | --- | --- | --- | --- |
@@ -96,6 +97,7 @@ One member per session, each landing append-only (prior members stay byte-identi
 | **SkipList** | 0.4.0 | shipped | pointer-free over a private free-list node pool; expected O(log n) | `get` / `set` / `delete` / `successor` / `predecessor` |
 | **Treap** | 0.5.0 | shipped | randomized-balanced augmented BST over the same node pool; expected O(log n) | `get` / `has` / `set` / `delete` / `rank` / `select` / `successor` / `predecessor` / `forEach` / `rangeIter` / `split` + `merge` |
 | **Scapegoat** | 0.6.0 | shipped | DETERMINISTIC weight-balanced augmented BST over the same node pool; worst-case O(log n) get, amortized O(log n) set/delete (zero-GC rebuild) | `get` / `has` / `set` / `delete` / `rank` / `select` / `successor` / `predecessor` / `forEach` / `rangeIter` (NO split/merge) |
+| **MinMaxHeap** | 0.7.0 | shipped | array-embedded double-ended PQ (DEPQ): one binary heap whose levels alternate min/max, two flat columns (`_key`/`_id`) | `push` / `popMin` / `popMax` O(log n), `peekMin` / `peekMax` / `peekMinKey` / `peekMaxKey` O(1) (non-addressable: NO changeKey/remove) |
 
 Later tiers (OrderStatTree, IndexedHeap, SortedArray, MinMaxHeap, SplayTree, and presets) are queued in [`ROADMAP.md`](./ROADMAP.md).
 
@@ -107,7 +109,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.6.0 the witness gates nine ops: BinaryHeap `pop` (R^2 ~ 0.99, slope ~ 8-10 ns/level), Fenwick `update` (R^2 ~ 0.98-0.99, slope ~ 2.9-3.0 ns/level) and `prefix` (R^2 ~ 0.97, slope ~ 2.6-2.7 ns/level), SegmentTree `update` (R^2 ~ 0.99, slope ~ 3.2 ns/level, band `[2.29, 5.35]`) and `query` (R^2 ~ 0.99, slope ~ 7 ns/level, band `[4.30, 10.04]`), SkipList `get` (R^2 ~ 0.97-0.99, slope ~ 9 ns/level, band `[5.27, 12.30]`) and `set` (R^2 ~ 0.97-0.99, slope ~ 14 ns/level, band `[8.36, 19.50]`), Treap `get` (R^2 ~ 0.99, slope ~ 4 ns/level, band `[2.55, 5.95]`), and Scapegoat `get` (R^2 ~ 0.99, slope ~ 4 ns/level, band `[2.41, 5.63]`) all ON the line. Scapegoat is DETERMINISTIC, so its `get` is WORST-case (not expected) O(log n); its rebuild spike lives on the AMORTIZED `set` path and is proven not by a per-op line but by an amortized-trace assertion -- the cumulative ascending-insert (rebuild-heavy) cost/op tracks a LOG curve (last/first ratio ~1.5x over `[2^11, 2^17]`, gated `< 4x`) where a rebuild-less BST would degenerate to an O(n)-amortized chain and blow the ratio to ~64x. Treap's descent touches one node per level, so its per-level slope is lower than SkipList's tower search -- expected, which is why only the R^2 floor is shared and each op calibrates its own band. SkipList's two ops are gated over DIFFERENT sweeps -- each measured where its logarithm is visible, not where the cache wall is: `get` (a clean search with no per-op randomness) over `[2^11, 2^17]` for dynamic range; `set` (a heavier insert+delete churn whose per-insert tower height is random) over the smaller, fully cache-resident `[2^9, 2^14]` so the fit sees the structural level count, not DRAM latency. Because SkipList is EXPECTED (not worst-case) O(log n), the witness also prints the MAX single insert over a realistic randomized build trace -- the unlucky-tower tail a mean hides. Each op's O(n) foil fits well below the floor: the sorted-array insert (BinaryHeap / SkipList) foil runs R^2 ~ 0.77-0.87, the Fenwick foils (prefix-array rebuild, naive re-sum) and SkipList's linear-scan search foil hold at R^2 ~ 0.75-0.82, and SegmentTree's foils (whole-tree rebuild per update, scan-fold per query) fit at R^2 ~ 0.72-0.85 -- all foil families sit comfortably under the 0.958 floor.
+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.7.0 the witness gates ten ops: BinaryHeap `pop` (R^2 ~ 0.99, slope ~ 8-10 ns/level), Fenwick `update` (R^2 ~ 0.98-0.99, slope ~ 2.9-3.0 ns/level) and `prefix` (R^2 ~ 0.97, slope ~ 2.6-2.7 ns/level), SegmentTree `update` (R^2 ~ 0.99, slope ~ 3.2 ns/level, band `[2.29, 5.35]`) and `query` (R^2 ~ 0.99, slope ~ 7 ns/level, band `[4.30, 10.04]`), SkipList `get` (R^2 ~ 0.97-0.99, slope ~ 9 ns/level, band `[5.27, 12.30]`) and `set` (R^2 ~ 0.97-0.99, slope ~ 14 ns/level, band `[8.36, 19.50]`), Treap `get` (R^2 ~ 0.99, slope ~ 4 ns/level, band `[2.55, 5.95]`), Scapegoat `get` (R^2 ~ 0.99, slope ~ 4 ns/level, band `[2.41, 5.63]`), and MinMaxHeap `popMin` (R^2 ~ 0.99, slope ~ 10.3 ns/level, band `[6.18, 14.42]`) all ON the line. Scapegoat is DETERMINISTIC, so its `get` is WORST-case (not expected) O(log n); its rebuild spike lives on the AMORTIZED `set` path and is proven not by a per-op line but by an amortized-trace assertion -- the cumulative ascending-insert (rebuild-heavy) cost/op tracks a LOG curve (last/first ratio ~1.5x over `[2^11, 2^17]`, gated `< 4x`) where a rebuild-less BST would degenerate to an O(n)-amortized chain and blow the ratio to ~64x. Treap's descent touches one node per level, so its per-level slope is lower than SkipList's tower search -- expected, which is why only the R^2 floor is shared and each op calibrates its own band. SkipList's two ops are gated over DIFFERENT sweeps -- each measured where its logarithm is visible, not where the cache wall is: `get` (a clean search with no per-op randomness) over `[2^11, 2^17]` for dynamic range; `set` (a heavier insert+delete churn whose per-insert tower height is random) over the smaller, fully cache-resident `[2^9, 2^14]` so the fit sees the structural level count, not DRAM latency. Because SkipList is EXPECTED (not worst-case) O(log n), the witness also prints the MAX single insert over a realistic randomized build trace -- the unlucky-tower tail a mean hides. Each op's O(n) foil fits well below the floor: the sorted-array insert (BinaryHeap / SkipList) foil runs R^2 ~ 0.77-0.87, the Fenwick foils (prefix-array rebuild, naive re-sum) and SkipList's linear-scan search foil hold at R^2 ~ 0.75-0.82, and SegmentTree's foils (whole-tree rebuild per update, scan-fold per query) fit at R^2 ~ 0.72-0.85 -- all foil families sit comfortably under the 0.958 floor.
 
 ## Benchmarks
 
@@ -148,6 +150,7 @@ Each op fits `nsPerOp = intercept + slope*log2(n)`. ON-LINE = `R^2 >= 0.958` (th
 | `SkipList.set` | 0.985 | 12.1 | `[8.36, 19.50]` | ON | sorted-array insert | 0.77 | off |
 | `Treap.get` | 0.988 | 4.0 | `[2.55, 5.95]` | ON | linear scan | 0.79 | off |
 | `Scapegoat.get` | 0.988 | 3.8 | `[2.41, 5.63]` | ON | linear scan | 0.79 | off |
+| `MinMaxHeap.popMin` | 0.99 | 10.3 | `[6.18, 14.42]` | ON | linear min-scan-and-splice | 0.77 | off |
 
 **Scapegoat amortized-trace (the rebuild honesty).** Scapegoat's `get` is WORST-case O(log n) (a deterministic weight-balance height bound), so it carries no expected-op MAX-single-op disclosure. The rebuild spike lives on the AMORTIZED `set` path; D1 proves the amortization not with a per-op line but with an amortized-trace assertion -- the cumulative ascending-insert (rebuild-heavy) cost/op tracks a LOG curve (last/first ratio `~1.5x` over `[2^11, 2^17]`, gated `< 4x`) where a rebuild-less BST would blow to `~64x`.
 
@@ -183,8 +186,8 @@ All seven gated op-rows report **0 B/op** across the `n = 1e3..1e6` sweep, with
 
 - **D2 amortized cost** -- cumulative ns/op stays bounded over a `~1M`-op mixed trace (drift `< 1.0` here: the trace speeds up as the JIT warms, never degrades).
 - **D4 cache (PROXY, labelled)** -- dense `forEach` iteration vs random single-element lookup; the random/dense gap is `~1.9x` (SegmentTree) to `~2.9x` (SkipList). No native perf counters.
-- **D7 scalability** -- numeric substrates: string + object keys read `n/a`. Load factors `0.3/0.5/0.7/0.9`; insertion order (sorted / random / adversarial-reverse) applies to the comparison-ordered BinaryHeap + SkipList + Treap + Scapegoat, `n/a` for the index-addressed Fenwick + SegmentTree.
-- **D8 workloads** -- churn (all members) + an ordered scan (`successor` + `rangeIter`, SkipList + Treap + Scapegoat; `n/a` elsewhere).
+- **D7 scalability** -- numeric substrates: string + object keys read `n/a`. Load factors `0.3/0.5/0.7/0.9`; insertion order (sorted / random / adversarial-reverse) applies to the comparison-ordered BinaryHeap + SkipList + Treap + Scapegoat + MinMaxHeap, `n/a` for the index-addressed Fenwick + SegmentTree.
+- **D8 workloads** -- churn (all members) + an ordered scan (`successor` + `rangeIter`, SkipList + Treap + Scapegoat; `n/a` elsewhere, including MinMaxHeap -- a DEPQ, not an ordered map).
 
 ## API reference
 
@@ -415,6 +418,41 @@ sg.successor(20);      // -> 50   (smallest key strictly greater)
 
 Member signatures for later members are appended here as each ships.
 
+### MinMaxHeap
+
+A **min-max heap**: a **double-ended priority queue (DEPQ)** held in ONE array-embedded binary heap whose levels **alternate min / max** (Atkinson, Sack, Santoro & Strothotte 1986). Even depth (the root is depth 0) is a **MIN** level, odd depth a **MAX** level, so the global minimum is the root and the global maximum is the **larger of the root's up-to-two children**. That single alternating heap answers BOTH ends: `peekMin` / `peekMax` / `peekMinKey` / `peekMaxKey` are **O(1)**; `push` / `popMin` / `popMax` are all **worst-case O(log n)** -- no second heap, no paired-heap correspondence to maintain. It uses the BinaryHeap **id + key** idiom (two parallel pointer-free columns: `_id` `Uint32Array`, `_key` `Float64Array`), so it carries an opaque payload per entry with no object nodes. Keys are finite numbers (typeof-guarded before coercion; Symbol / BigInt / NaN / +-Infinity fail closed -- the key is checked FIRST, then the id, then a full heap). Every hot op allocates zero bytes after construction.
+
+The asymmetry vs BinaryHeap: MinMaxHeap is **non-addressable**. There is no `_pos` reverse map and therefore deliberately **no `changeKey` / `remove`**; the id is an OPAQUE `Uint32` payload (NOT unique -- duplicates allowed -- over the full `[0, 2^32)` domain, wider than BinaryHeap's `[0, capacity)`). A DEPQ's job is the two extremes; addressability is the separable concern BinaryHeap already carries. There is also **no `kind` argument / getter** (a DEPQ has both ends; a kind getter would be a lie). This is the classic **one-element-per-node** min-max heap; the interval-heap DEPQ (two elements per node) is a deliberately deferred alternative (see [`decisions/0009-minmaxheap.md`](./decisions/0009-minmaxheap.md)). Level parity is computed zero-alloc as `((31 - Math.clz32(i + 1)) & 1) === 0` (min iff even depth); the sifts are hole-punching (one write per level) and every grandchild index is bound-checked against the live size (the classic min-max off-by-one, verified at n = 1, 2, 3, 4).
+
+```js
+import { MinMaxHeap } from '@zakkster/lite-logn';
+
+const h = new MinMaxHeap(1000);   // capacity 1000 (no kind: a DEPQ serves both ends)
+h.push(1, 5.0);                   // push id 1 with key 5.0
+h.push(2, 1.0);
+h.push(3, 9.0);
+h.peekMinKey();        // -> 1.0                                  -- O(1)
+h.peekMaxKey();        // -> 9.0                                  -- O(1)
+h.popMin();            // -> 2   (the id at the minimum key)      -- worst-case O(log n)
+h.popMax();            // -> 3   (the id at the maximum key)      -- worst-case O(log n)
+```
+
+| Member | Signature | Complexity | Notes |
+| --- | --- | --- | --- |
+| constructor | `new MinMaxHeap(capacity)` | O(capacity) | `capacity` integer in `[1, 2^31-1]`. Allocates two typed arrays (`_key` `Float64`, `_id` `Uint32`) once. NO `kind` argument. |
+| `push` | `push(id, key) -> void` | worst-case O(log n) | `id` integer in `[0, 2^32)` (opaque, not required unique); `key` finite. Key checked FIRST, then id, then a full heap -- each throws `[lite-logn]` as a no-op (size unchanged). |
+| `popMin` | `popMin() -> number \| undefined` | worst-case O(log n) | Removes and returns the id at the minimum key; `undefined` if empty (no throw). |
+| `popMax` | `popMax() -> number \| undefined` | worst-case O(log n) | Removes and returns the id at the maximum key; `undefined` if empty (no throw). |
+| `peekMin` / `peekMax` | `-> number \| undefined` | O(1) | The id at the minimum / maximum key; `undefined` if empty (never throw). |
+| `peekMinKey` / `peekMaxKey` | `-> number \| undefined` | O(1) | The minimum / maximum key; `undefined` if empty (never throw). |
+| `clear` | `clear() -> void` | O(1) | Empties the heap, keeps capacity. |
+| `forEach` | `forEach(fn) -> void` | O(n) | Visits `(id, key, heap)` in UNSPECIFIED (heap-array) order -- NOT sorted / pop order. |
+| `[Symbol.iterator]` | `-> IterableIterator<number>` | O(n) | Yields live ids in UNSPECIFIED (heap-array) order. |
+| `size` / `capacity` | getters | O(1) | Live entry count / fixed capacity. |
+| `MinMaxHeap.build` | `build(ids, keys, capacity) -> MinMaxHeap` | O(n) | Floyd bulk build from parallel arrays (deepest-first, level-aware sift-down); fails closed on non-array-like / length mismatch, count > capacity, out-of-range id, or non-finite key. |
+
+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.
@@ -444,8 +482,11 @@ Member signatures for later members are appended here as each ships.
 | `Scapegoat` constructor / `clear` | O(capacity) five columns + pool + two rebuild scratch buffers, once (cold) |
 | `Scapegoat` forEach | 0 B/op in the loop body (recursive in-order walk, hoisted callback) |
 | `Scapegoat` rangeIter | one iterator + `{value, done}` per step (the documented per-protocol allocator; transient, not retained) |
+| `MinMaxHeap` push / popMin / popMax / peekMin / peekMax / peekMinKey / peekMaxKey | 0 B/op (two flat columns; the hole-punching sifts use only local scalar temporaries) |
+| `MinMaxHeap` constructor / `build` / `clear` | O(capacity) two typed arrays, once (cold) |
+| `MinMaxHeap` forEach | 0 B/op in the loop body (pass a hoisted callback) |
 
-Gated witness numbers (this machine, shared R^2 floor 0.958): BinaryHeap `pop` R^2 ~ 0.99, slope ~ 8-10 ns/level; Fenwick `update` R^2 ~ 0.98-0.99, slope ~ 2.9-3.0 ns/level (band `[1.84, 4.30]`); Fenwick `prefix` R^2 ~ 0.97, slope ~ 2.6-2.7 ns/level (band `[1.76, 4.10]`); SegmentTree `update` R^2 ~ 0.99, slope ~ 3.2 ns/level (band `[2.29, 5.35]`); SegmentTree `query` R^2 ~ 0.99, slope ~ 7 ns/level (band `[4.30, 10.04]`); SkipList `get` R^2 ~ 0.97-0.99, slope ~ 9 ns/level (band `[5.27, 12.30]`, sweep `[2^11, 2^17]`); SkipList `set` R^2 ~ 0.97-0.99, slope ~ 14 ns/level (band `[8.36, 19.50]`, cache-resident sweep `[2^9, 2^14]`); Treap `get` R^2 ~ 0.99, slope ~ 4 ns/level (band `[2.55, 5.95]`, sweep `[2^11, 2^17]`); Scapegoat `get` R^2 ~ 0.99, slope ~ 3.8-4.0 ns/level (band `[2.41, 5.63]`, sweep `[2^11, 2^17]`) -- WORST-case (deterministic), with the AMORTIZED `set` rebuild spike proven by the amortized-trace assertion (ratio `< 4x`), not a per-op line. The allocation table is extended per member as each lands.
+Gated witness numbers (this machine, shared R^2 floor 0.958): BinaryHeap `pop` R^2 ~ 0.99, slope ~ 8-10 ns/level; Fenwick `update` R^2 ~ 0.98-0.99, slope ~ 2.9-3.0 ns/level (band `[1.84, 4.30]`); Fenwick `prefix` R^2 ~ 0.97, slope ~ 2.6-2.7 ns/level (band `[1.76, 4.10]`); SegmentTree `update` R^2 ~ 0.99, slope ~ 3.2 ns/level (band `[2.29, 5.35]`); SegmentTree `query` R^2 ~ 0.99, slope ~ 7 ns/level (band `[4.30, 10.04]`); SkipList `get` R^2 ~ 0.97-0.99, slope ~ 9 ns/level (band `[5.27, 12.30]`, sweep `[2^11, 2^17]`); SkipList `set` R^2 ~ 0.97-0.99, slope ~ 14 ns/level (band `[8.36, 19.50]`, cache-resident sweep `[2^9, 2^14]`); Treap `get` R^2 ~ 0.99, slope ~ 4 ns/level (band `[2.55, 5.95]`, sweep `[2^11, 2^17]`); Scapegoat `get` R^2 ~ 0.99, slope ~ 3.8-4.0 ns/level (band `[2.41, 5.63]`, sweep `[2^11, 2^17]`) -- WORST-case (deterministic), with the AMORTIZED `set` rebuild spike proven by the amortized-trace assertion (ratio `< 4x`), not a per-op line; MinMaxHeap `popMin` R^2 ~ 0.99, slope ~ 10.3 ns/level (band `[6.18, 14.42]`, sweep `[1e4, 1e6]`) -- WORST-case (a DEPQ whose push / popMin / popMax are all worst-case, so no MAX-single-op line), a touch ABOVE BinaryHeap.pop because a min-max trickle-down compares against up to six descendants per level. The allocation table is extended per member as each lands.
 
 ## Testing
 
@@ -463,6 +504,7 @@ Gated witness numbers (this machine, shared R^2 floor 0.958): BinaryHeap `pop` R
 - **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 an addressable double-ended queue.** MinMaxHeap is a DEPQ, but it is NON-addressable: its id is an opaque, non-unique payload (no reverse map), so it has no `changeKey` / `remove`. For an addressable single-ended priority queue (reprioritize / remove by entity id) use **BinaryHeap**. MinMaxHeap also ships the classic one-element-per-node min-max heap only -- the interval-heap DEPQ (two elements per node) is a deliberately deferred alternative (see [`decisions/0009-minmaxheap.md`](./decisions/0009-minmaxheap.md)).
 - **Not a grow-on-demand collection.** Capacity is fixed at construction and overflow fails closed.
 
 ## Ecosystem

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-logn
 
-Version: 0.6.0
+Version: 0.7.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -19,8 +19,8 @@ FLAT ops/ms line on a log-x axis), lite-logn holds the logarithm (a STRAIGHT
 line on that same axis, one added level per doubling of n).
 
 v0.1.0 shipped BinaryHeap; v0.2.0 adds Fenwick; v0.3.0 adds SegmentTree; v0.4.0
-adds SkipList; v0.5.0 adds Treap; v0.6.0 adds Scapegoat. The roster (one member per
-session, each landing append-only):
+adds SkipList; v0.5.0 adds Treap; v0.6.0 adds Scapegoat; v0.7.0 adds MinMaxHeap. 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,
@@ -75,6 +75,19 @@ session, each landing append-only):
   be O(n) rebuilds) -- the documented asymmetry vs Treap. set updates an existing key's
   value in place. The amortized-trace witness shows cumulative insert cost/op tracks log n
   despite the rebuild spikes. Zero allocation on every hot op.
+- MinMaxHeap (v0.7.0) -- a DOUBLE-ENDED priority queue (DEPQ) held in ONE array-embedded
+  binary heap whose levels ALTERNATE min / max (Atkinson et al. 1986). Even depth is a MIN
+  level, odd depth a MAX level, so the minimum is the root and the maximum is the LARGER of
+  the root's up-to-two children: peekMin / peekMax are O(1); push / popMin / popMax are all
+  WORST-case O(log n) from that single heap (no second heap, no paired-heap correspondence).
+  Two parallel typed-array columns (`_key` Float64, `_id` Uint32) in the BinaryHeap id+key
+  idiom; the id is an OPAQUE Uint32 payload in [0, 2^32) (NOT unique, no reverse map), so
+  there is deliberately NO changeKey / remove -- the documented asymmetry vs BinaryHeap.
+  Level parity is `((31 - Math.clz32(i + 1)) & 1) === 0` (min iff even depth), computed
+  zero-alloc; the sifts are hole-punching (one write per level). Keys are finite numbers
+  (typeof-guarded before coercion; Symbol / BigInt / NaN / +-Infinity fail closed). This is
+  the classic one-element-per-node min-max heap only; the interval-heap DEPQ is deferred.
+  Zero allocation on every hot op.
 
 ## Exports (from the single main file LogN.js)
 
@@ -238,6 +251,26 @@ session, each landing append-only):
   - There is deliberately NO `split` / `merge` (the documented asymmetry vs Treap: no
     priority heap to merge by; an honest deterministic split/merge would be O(n) rebuilds).
 
+- `MinMaxHeap` -- class. A DOUBLE-ENDED priority queue (DEPQ) in ONE array-embedded binary
+  heap whose levels ALTERNATE min / max (Atkinson et al. 1986). The minimum is the root; the
+  maximum is the larger of the root's up-to-two children. Two parallel typed-array columns
+  (`_key` Float64, `_id` Uint32); the id is an OPAQUE Uint32 payload in [0, 2^32) (not unique,
+  no reverse map). Keys are finite numbers (typeof-guarded before coercion; Symbol / BigInt /
+  NaN / +-Infinity fail closed). Non-addressable: deliberately NO changeKey / remove.
+  - `new MinMaxHeap(capacity)` -- capacity an integer in [1, 2^31-1]. Allocates the two typed
+    arrays once. NO `kind` argument (a DEPQ serves both ends).
+  - `push(id, key)` -> void. id integer in [0, 2^32); key finite. The key is checked FIRST,
+    then the id, then a full heap; each throws `[lite-logn]` as a no-op (size unchanged).
+  - `popMin()` -> id | undefined. Removes the minimum; undefined if empty (no throw).
+  - `popMax()` -> id | undefined. Removes the maximum; undefined if empty (no throw).
+  - `peekMin()` / `peekMax()` -> id | undefined. `peekMinKey()` / `peekMaxKey()` -> key |
+    undefined. All O(1), read-only, undefined if empty (never throw).
+  - `size` / `capacity` getters; `clear()`; `forEach(fn)` and `[Symbol.iterator]()` yield
+    live ids in UNSPECIFIED (heap-array) order -- NOT sorted / pop order.
+  - `MinMaxHeap.build(ids, keys, capacity)` -> MinMaxHeap. Floyd O(n) bulk build from parallel
+    arrays (deepest-first, level-aware sift-down); fails closed on non-array-like / length
+    mismatch, count > capacity, out-of-range id, or non-finite key.
+
 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.6.0",
-  "description": "Zero-dependency, zero-GC family of O(log n) data structures that proves its logarithm: BinaryHeap (array-embedded O(log n) push/pop min-heap), Fenwick/BIT (O(log n) point-update AND prefix-sum via the i & -i walk), SegmentTree (O(log n) associative range-query + point-update), SkipList (pointer-free expected-O(log n) ordered map over a private free-list node pool), Treap (randomized-balanced augmented ordered map with O(log n) rank/select/split/merge), and Scapegoat (DETERMINISTIC weight-balanced augmented ordered map: worst-case-O(log n) get, amortized-O(log n) set/delete, zero-GC rebuild) 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.7.0",
+  "description": "Zero-dependency, zero-GC family of O(log n) data structures that proves its logarithm: BinaryHeap (array-embedded O(log n) push/pop min-heap), Fenwick/BIT (O(log n) point-update AND prefix-sum via the i & -i walk), SegmentTree (O(log n) associative range-query + point-update), SkipList (pointer-free expected-O(log n) ordered map over a private free-list node pool), Treap (randomized-balanced augmented ordered map with O(log n) rank/select/split/merge), Scapegoat (DETERMINISTIC weight-balanced augmented ordered map: worst-case-O(log n) get, amortized-O(log n) set/delete, zero-GC rebuild), and MinMaxHeap (array-embedded double-ended priority queue: O(1) peekMin/peekMax, O(log n) push/popMin/popMax) 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",
@@ -39,6 +39,9 @@
     "binary-heap",
     "heap",
     "priority-queue",
+    "min-max-heap",
+    "double-ended-priority-queue",
+    "depq",
     "d-ary-heap",
     "fenwick",
     "bit",