max-priority-queue-typed 2.4.0 → 2.4.1

package/src/data-structures/binary-tree/red-black-tree.ts

@@ -7,10 +7,10 @@
  */
 
 import type {
-  BinaryTreeDeleteResult,
+  BinaryTreeDeleteResult, BTNRep,
   CRUD,
   EntryCallback,
-  FamilyPosition,
+  FamilyPosition, NodePredicate,
   OptNode,
   RBTNColor,
   RedBlackTreeOptions
@@ -24,12 +24,11 @@ export class RedBlackTreeNode<K = any, V = any> {
   parent?: RedBlackTreeNode<K, V> = undefined;
 
   /**
-   * Create a Red-Black Tree and optionally bulk-insert items.
-   * @remarks Time O(n log n), Space O(n)
-   * @param key - See parameter type for details.
-   * @param [value]- See parameter type for details.
-   * @param color - See parameter type for details.
-   * @returns New RedBlackTree instance.
+   * Create a Red-Black Tree node.
+   * @remarks Time O(1), Space O(1)
+   * @param key - Node key.
+   * @param [value] - Node value (unused in map mode trees).
+   * @param color - Node color.
    */
 
   constructor(key: K, value?: V, color: RBTNColor = 'BLACK') {
@@ -179,7 +178,7 @@ export class RedBlackTreeNode<K = any, V = any> {
 
 /**
  * Represents a Red-Black Tree (self-balancing BST) supporting map-like mode and stable O(log n) updates.
- * @remarks Time O(1), Space O(1)
+ * @remarks Operation complexity depends on the method; see each method's docs.
  * @template K
  * @template V
  * @template R
@@ -287,10 +286,18 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     > = [],
     options?: RedBlackTreeOptions<K, V, R>
   ) {
+
     super([], options);
 
     this._root = this.NIL;
 
+    // Not part of the actual tree; used only as an internal cache hub.
+    this._header = new RedBlackTreeNode<K, V>(undefined as K, undefined, 'BLACK');
+    this._header.parent = this.NIL;
+    // Avoid using accessors here: they would set NIL.parent and can corrupt sentinel invariants.
+    this._header._left = this.NIL;
+    this._header._right = this.NIL;
+
     if (keysNodesEntriesOrRaws) {
       this.setMany(keysNodesEntriesOrRaws);
     }
@@ -298,6 +305,26 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
 
   protected override _root: RedBlackTreeNode<K, V> | undefined;
 
+  /**
+   * (Internal) Header sentinel:
+   * - header.parent -> root
+   * - header._left  -> min (or NIL)
+   * - header._right -> max (or NIL)
+   *
+   * IMPORTANT:
+   * - This header is NOT part of the actual tree.
+   * - Do NOT use `header.left` / `header.right` accessors for wiring: those setters update `NIL.parent`
+   *   and can corrupt sentinel invariants / cause hangs. Only touch `header._left/_right`.
+   */
+  protected _header: RedBlackTreeNode<K, V>;
+
+  /**
+   * (Internal) Cache of the current minimum and maximum nodes.
+   * Used for fast-path insert/update when keys are monotonic or near-boundary.
+   */
+  protected _minNode: RedBlackTreeNode<K, V> | undefined;
+  protected _maxNode: RedBlackTreeNode<K, V> | undefined;
+
   /**
    * Get the current root node.
    * @remarks Time O(1), Space O(1)
@@ -316,7 +343,7 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
    * @returns A new RedBlackTreeNode instance.
    */
   override createNode(key: K, value?: V, color: RBTNColor = 'BLACK'): RedBlackTreeNode<K, V> {
-    return new RedBlackTreeNode<K, V>(key, this._isMapMode ? undefined : value, color);
+    return new RedBlackTreeNode<K, V>(key, value, color);
   }
 
   /**
@@ -338,22 +365,421 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
    * @returns void
    */
 
+  /**
+   * Remove all nodes and clear internal caches.
+   * @remarks Time O(n) average, Space O(1)
+   */
   override clear() {
     super.clear();
     this._root = this.NIL;
+    this._header.parent = this.NIL;
+    this._setMinCache(undefined);
+    this._setMaxCache(undefined);
+  }
+
+
+  /**
+   * (Internal) Find a node by key using a tight BST walk (no allocations).
+   *
+   * NOTE: This uses `header.parent` as the canonical root pointer.
+   * @remarks Time O(log n) average, Space O(1)
+   */
+  protected _findNodeByKey(key: K): RedBlackTreeNode<K, V> | undefined {
+    const NIL = this.NIL;
+    const cmp = this._compare.bind(this);
+
+    let cur = (this._header.parent) ?? NIL;
+    while (cur !== NIL) {
+      const c = cmp(key, cur.key);
+      if (c < 0) cur = cur.left ?? NIL;
+      else if (c > 0) cur = cur.right ?? NIL;
+      else return cur;
+    }
+    return undefined;
+  }
+
+  /**
+   * (Internal) In-order predecessor of a node in a BST.
+   * @remarks Time O(log n) average, Space O(1)
+   */
+  protected _predecessorOf(node: RedBlackTreeNode<K, V>): RedBlackTreeNode<K, V> | undefined {
+    const NIL = this.NIL;
+    if (node.left && node.left !== NIL) {
+      let cur = node.left;
+      while (cur.right && cur.right !== NIL) cur = cur.right;
+      return cur;
+    }
+    let cur: RedBlackTreeNode<K, V> | undefined = node;
+    let p = node.parent;
+    while (p && cur === p.left) {
+      cur = p;
+      p = p.parent;
+    }
+    return p;
+  }
+
+  /**
+   * (Internal) In-order successor of a node in a BST.
+   * @remarks Time O(log n) average, Space O(1)
+   */
+  protected _successorOf(node: RedBlackTreeNode<K, V>): RedBlackTreeNode<K, V> | undefined {
+    const NIL = this.NIL;
+    if (node.right && node.right !== NIL) {
+      let cur = node.right;
+      while (cur.left && cur.left !== NIL) cur = cur.left;
+      return cur;
+    }
+    let cur: RedBlackTreeNode<K, V> | undefined = node;
+    let p = node.parent;
+    while (p && cur === p.right) {
+      cur = p;
+      p = p.parent;
+    }
+    return p;
+  }
+
+  /**
+   * (Internal) Attach a new node directly under a known parent/side (no search).
+   *
+   * This is a performance-oriented helper used by boundary fast paths and hinted insertion.
+   * It will:
+   * - wire parent/child pointers (using accessors, so parent pointers are updated)
+   * - initialize children to NIL
+   * - mark the new node RED, then run insert fix-up
+   *
+   * Precondition: the chosen slot (parent.left/parent.right) is empty (NIL/null/undefined).
+   * @remarks Time O(log n) average, Space O(1)
+   */
+  protected _attachNewNode(parent: RedBlackTreeNode<K, V>, side: 'left' | 'right', node: RedBlackTreeNode<K, V>): void {
+    const NIL = this.NIL;
+    node.parent = parent;
+    if (side === 'left') parent.left = node;
+    else parent.right = node;
+    node.left = NIL;
+    node.right = NIL;
+    node.color = 'RED';
+    this._insertFixup(node);
+    if (this.isRealNode(this._root)) this._root.color = 'BLACK';
+  }
+
+  /**
+   * (Internal) a single source of truth for min/max is header._left/_right.
+   * Keep legacy _minNode/_maxNode mirrored for compatibility.
+   * @remarks Time O(1), Space O(1)
+   */
+  /**
+   * (Internal) Update min cache pointers (header._left is the canonical min pointer).
+   * @remarks Time O(1), Space O(1)
+   */
+  protected _setMinCache(node: RedBlackTreeNode<K, V> | undefined): void {
+    this._minNode = node;
+    this._header._left = node ?? this.NIL;
+  }
+
+  /**
+   * (Internal) Update max cache pointers (header._right is the canonical max pointer).
+   * @remarks Time O(1), Space O(1)
+   */
+  protected _setMaxCache(node: RedBlackTreeNode<K, V> | undefined): void {
+    this._maxNode = node;
+    this._header._right = node ?? this.NIL;
+  }
+
+  /**
+   * (Internal) Core set implementation returning the affected node.
+   *
+   * Hot path goals:
+   * - Avoid double walks (search+insert): do a single traversal that either updates or inserts.
+   * - Use header min/max caches to fast-path boundary inserts.
+   * - Keep header._left/_right as canonical min/max pointers.
+   *
+   * Return value:
+   * - `{ node, created:false }` when an existing key is updated
+   * - `{ node, created:true }` when a new node is inserted
+   * - `undefined` only on unexpected internal failure.
+   * @remarks Time O(log n) average, Space O(1)
+   */
+  protected _setKVNode(key: K, nextValue?: V): { node: RedBlackTreeNode<K, V>; created: boolean } | undefined {
+    const NIL = this.NIL;
+    const comparator = this._comparator;
+
+    // Read via header to avoid undefined checks (header uses NIL when empty).
+    const header = this._header;
+    const minN = header._left ?? NIL;
+    if (minN !== NIL) {
+      const cMin = comparator(key, minN.key);
+      if (cMin === 0) {
+        minN.value = nextValue as V;
+        if (this._isMapMode) this._store.set(key, minN);
+        return { node: minN, created: false };
+      }
+      // Boundary attach: if key is smaller than current min and min has no left child.
+      // Inline NIL/null/undefined check to avoid isRealNode overhead on hot path.
+      const minL = minN.left;
+      if (cMin < 0 && (minL === NIL || minL === null || minL === undefined)) {
+        const newNode = this.createNode(key, nextValue);
+        this._attachNewNode(minN, 'left', newNode);
+        if (this._isMapMode) this._store.set(newNode.key, newNode);
+        this._size++;
+        this._setMinCache(newNode);
+        // If max is not initialized yet (tree had 0/1 nodes), mirror max too.
+        if (header._right  === NIL) this._setMaxCache(newNode);
+        return { node: newNode, created: true };
+      }
+
+      // Only touch max when key is not less than min.
+      if (cMin > 0) {
+        const maxN = header._right ?? NIL;
+        // Boundary attach: if key is greater than current max and max has no right child.
+        const cMax = comparator(key, maxN.key);
+        if (cMax === 0) {
+          maxN.value = nextValue as V;
+          if (this._isMapMode) this._store.set(key, maxN);
+          return { node: maxN, created: false };
+        }
+        const maxR = maxN.right;
+        if (cMax > 0 && (maxR === NIL || maxR === null || maxR === undefined)) {
+          const newNode = this.createNode(key, nextValue);
+          this._attachNewNode(maxN, 'right', newNode);
+          if (this._isMapMode) this._store.set(newNode.key, newNode);
+          this._size++;
+          this._setMaxCache(newNode);
+          if (header._left === NIL) this._setMinCache(newNode);
+          return { node: newNode, created: true };
+        }
+      }
+    }
+
+    // Normal path: single-pass search + insert/update (avoid double-walking the tree).
+    const cmp = comparator;
+    const isMapMode = this._isMapMode;
+    const store = this._store;
+    let current = this._header.parent ?? NIL;
+    let parent: RedBlackTreeNode<K, V> | undefined;
+    let lastCompared = 0;
+
+    while (current !== NIL) {
+      parent = current;
+      lastCompared = cmp(key, current.key);
+      if (lastCompared < 0) current = current.left ?? NIL;
+      else if (lastCompared > 0) current = current.right ?? NIL;
+      else {
+        // Update existing.
+        current.value = nextValue as V;
+        if (isMapMode) store.set(key, current);
+        return { node: current, created: false };
+      }
+    }
+
+    // Insert new.
+    const newNode = this.createNode(key, nextValue);
+    // createNode always returns a real node in RedBlackTree.
+    newNode.parent = parent;
+
+    if (!parent) {
+      this._setRoot(newNode);
+    } else if (lastCompared < 0) {
+      parent.left = newNode;
+    } else {
+      parent.right = newNode;
+    }
+
+    newNode.left = NIL;
+    newNode.right = NIL;
+    newNode.color = 'RED';
+
+    this._insertFixup(newNode);
+    if (this.isRealNode(this._root)) this._root.color = 'BLACK';
+    else return undefined;
+
+    if (isMapMode) store.set(newNode.key, newNode);
+    this._size++;
+
+    // Maintain min/max caches on insertion (header.left/right are canonical).
+    const hMin = this._header._left ?? NIL;
+    const hMax = this._header._right ?? NIL;
+
+    // Fast-path: empty tree or attaching directly to an extreme.
+    if (hMin === NIL || hMax === NIL) {
+      this._setMinCache(newNode);
+      this._setMaxCache(newNode);
+    } else if (parent === hMax && lastCompared > 0) {
+      this._setMaxCache(newNode);
+    } else if (parent === hMin && lastCompared < 0) {
+      this._setMinCache(newNode);
+    } else {
+      if (cmp(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
+      if (cmp(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
+    }
+
+    return { node: newNode, created: true };
   }
 
   /**
-   * Insert or replace an entry using BST order and red-black fix-up.
-   * @remarks Time O(log n), Space O(1)
-   * @param keyNodeOrEntry - Key, node, or [key, value] entry to insert.
-   * @param [value]- See parameter type for details.
-   * @returns True if inserted or updated; false if ignored.
+   * (Internal) Boolean wrapper around `_setKVNode`.
+   *
+   * Includes a map-mode update fast-path:
+   * - If `isMapMode=true` and the key already exists in `_store`, then updating the value does not
+   *   require any tree search/rotation (tree shape depends only on key).
+   * - This path is intentionally limited to `nextValue !== undefined` to preserve existing
+   *   semantics for `undefined` values.
+   * @remarks Time O(log n) average, Space O(1)
+   */
+  protected _setKV(key: K, nextValue?: V): boolean {
+    if (this._isMapMode) {
+      const store = this._store;
+      const node = store.get(key);
+      if (node) {
+        node.value = nextValue as V;
+        return true;
+      }
+    }
+
+    return this._setKVNode(key, nextValue) !== undefined;
+  }
+
+  /**
+   * Insert/update using a hint node to speed up nearby insertions.
+   *
+   * close to the expected insertion position (often the previously returned node in a loop).
+   *
+   * When the hint is a good fit (sorted / nearly-sorted insertion), this can avoid most of the
+   * normal root-to-leaf search and reduce constant factors.
+   *
+   * When the hint does not match (random workloads), this will fall back to the normal set path.
+   * @remarks Time O(log n) average, Space O(1)
+   */
+  setWithHintNode(key: K, value: V, hint?: RedBlackTreeNode<K, V>): RedBlackTreeNode<K, V> | undefined {
+    if (!hint || !this.isRealNode(hint)) {
+      return this._setKVNode(key, value)?.node;
+    }
+
+    const cmp = this._compare.bind(this);
+    const c0 = cmp(key, hint.key);
+    if (c0 === 0) {
+      hint.value = value;
+      if (this._isMapMode) this._store.set(key, hint);
+      return hint;
+    }
+
+    if (c0 < 0) {
+      // Ultra-fast path: direct attach if the target slot is empty.
+      if (!this.isRealNode(hint.left)) {
+        const newNode = this.createNode(key, value);
+        if (!this.isRealNode(newNode)) return undefined;
+        this._attachNewNode(hint, 'left', newNode);
+        if (this._isMapMode) this._store.set(key, newNode);
+        this._size++;
+        // Maintain header/min/max caches.
+        const NIL = this.NIL;
+        const hMin = this._header._left ?? NIL;
+        if (hMin === NIL || this._compare(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
+        const hMax = this._header._right ?? NIL;
+        if (hMax === NIL || this._compare(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
+        return newNode;
+      }
+
+      const pred = this._predecessorOf(hint);
+      if (pred && cmp(pred.key, key) >= 0) {
+        return this._setKVNode(key, value)?.node;
+      }
+
+      // Try attach as right of pred.
+      if (pred && !this.isRealNode(pred.right)) {
+        const newNode = this.createNode(key, value);
+        if (!this.isRealNode(newNode)) return undefined;
+        this._attachNewNode(pred, 'right', newNode);
+        if (this._isMapMode) this._store.set(key, newNode);
+        this._size++;
+        // Maintain header/min/max caches.
+        const NIL = this.NIL;
+        const hMin = this._header._left ?? NIL;
+        if (hMin === NIL || this._compare(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
+        const hMax = this._header._right ?? NIL;
+        if (hMax === NIL || this._compare(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
+        return newNode;
+      }
+
+      return this._setKVNode(key, value)?.node;
+    }
+
+    // c0 > 0
+    // Ultra-fast path: direct attach if the target slot is empty.
+    if (!this.isRealNode(hint.right)) {
+      const newNode = this.createNode(key, value);
+      if (!this.isRealNode(newNode)) return undefined;
+      this._attachNewNode(hint, 'right', newNode);
+      if (this._isMapMode) this._store.set(key, newNode);
+      this._size++;
+      // Maintain header/min/max caches.
+      const NIL = this.NIL;
+      const hMin = this._header._left ?? NIL;
+      if (hMin === NIL || this._compare(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
+      const hMax = this._header._right ?? NIL;
+      if (hMax === NIL || this._compare(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
+      return newNode;
+    }
+
+    const succ = this._successorOf(hint);
+    if (succ && cmp(succ.key, key) <= 0) {
+      return this._setKVNode(key, value)?.node;
+    }
+
+    if (succ && !this.isRealNode(succ.left)) {
+      const newNode = this.createNode(key, value);
+      if (!this.isRealNode(newNode)) return undefined;
+      this._attachNewNode(succ, 'left', newNode);
+      if (this._isMapMode) this._store.set(key, newNode);
+      this._size++;
+      // Maintain header/min/max caches.
+      const NIL = this.NIL;
+      const hMin = this._header._left ?? NIL;
+      if (hMin === NIL || this._compare(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
+      const hMax = this._header._right ?? NIL;
+      if (hMax === NIL || this._compare(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
+      return newNode;
+    }
+
+    return this._setKVNode(key, value)?.node;
+  }
+
+  /**
+   * Boolean wrapper for setWithHintNode.
+   * @remarks Time O(log n) average, Space O(1)
+   */
+  setWithHint(key: K, value: V, hint?: RedBlackTreeNode<K, V>): boolean {
+    return this.setWithHintNode(key, value, hint) !== undefined;
+  }
+
+  /**
+   * Insert or update a key/value (map mode) or key-only (set mode).
+   *
+   * This method is optimized for:
+   * - monotonic inserts via min/max boundary fast paths
+   * - updates via a single-pass search (no double walk)
+   *
+   * @remarks Time O(log n) average, Space O(1)
    */
   override set(
     keyNodeOrEntry: K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
     value?: V
   ): boolean {
+    // Common path: tree.set(key, value) or tree.set([key, value]).
+    if (!this.isNode(keyNodeOrEntry)) {
+      if (keyNodeOrEntry === null || keyNodeOrEntry === undefined) return false;
+
+      if (this.isEntry(keyNodeOrEntry)) {
+        const key = keyNodeOrEntry[0];
+        if (key === null || key === undefined) return false;
+        const nextValue = value ?? keyNodeOrEntry[1];
+        return this._setKV(key, nextValue);
+      }
+
+      // key-only
+      return this._setKV(keyNodeOrEntry, value);
+    }
+
+    // Node insertion path (advanced usage)
     const [newNode, newValue] = this._keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value);
     if (!this.isRealNode(newNode)) return false;
 
@@ -365,12 +791,24 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
       } else {
         return false;
       }
-      if (this._isMapMode) this._setValue(newNode.key, newValue);
+      if (this._isMapMode) {
+        const n = this.getNode(newNode.key);
+        if (this.isRealNode(n)) {
+          n.value = newValue as V;
+          this._store.set(n.key, n);
+        }
+      }
       this._size++;
       return true;
     }
     if (insertStatus === 'UPDATED') {
-      if (this._isMapMode) this._setValue(newNode.key, newValue);
+      if (this._isMapMode) {
+        const n = this.getNode(newNode.key);
+        if (this.isRealNode(n)) {
+          n.value = newValue as V;
+          this._store.set(n.key, n);
+        }
+      }
       return true;
     }
     return false;
@@ -378,25 +816,30 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
 
   /**
    * Delete a node by key/node/entry and rebalance as needed.
-   * @remarks Time O(log n), Space O(1)
-   * @param keyNodeOrEntry - Key, node, or [key, value] entry identifying the node to delete.
+   * @remarks Time O(log n) average, Space O(1)
+   * @param keyNodeEntryRawOrPredicate - Key, node, or [key, value] entry identifying the node to delete.
    * @returns Array with deletion metadata (removed node, rebalancing hint if any).
    */
-
   override delete(
-    keyNodeOrEntry: K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined
+    keyNodeEntryRawOrPredicate: BTNRep<K, V, RedBlackTreeNode<K, V>> | NodePredicate<RedBlackTreeNode<K, V> | null>
   ): BinaryTreeDeleteResult<RedBlackTreeNode<K, V>>[] {
-    if (keyNodeOrEntry === null) return [];
+    if (keyNodeEntryRawOrPredicate === null) return [];
 
     const results: BinaryTreeDeleteResult<RedBlackTreeNode<K, V>>[] = [];
     let nodeToDelete: OptNode<RedBlackTreeNode<K, V>>;
-    if (this._isPredicate(keyNodeOrEntry)) nodeToDelete = this.getNode(keyNodeOrEntry);
-    else nodeToDelete = this.isRealNode(keyNodeOrEntry) ? keyNodeOrEntry : this.getNode(keyNodeOrEntry);
+    if (this._isPredicate(keyNodeEntryRawOrPredicate)) nodeToDelete = this.getNode(keyNodeEntryRawOrPredicate);
+    else nodeToDelete = this.isRealNode(keyNodeEntryRawOrPredicate) ? keyNodeEntryRawOrPredicate : this.getNode(keyNodeEntryRawOrPredicate);
 
     if (!nodeToDelete) {
       return results;
     }
 
+    // Track min/max cache updates before structural modifications.
+    const willDeleteMin = nodeToDelete === this._minNode;
+    const willDeleteMax = nodeToDelete === this._maxNode;
+    const nextMin = willDeleteMin ? this._successorOf(nodeToDelete) : undefined;
+    const nextMax = willDeleteMax ? this._predecessorOf(nodeToDelete) : undefined;
+
     let originalColor = nodeToDelete.color;
     let replacementNode: RedBlackTreeNode<K, V> | undefined;
 
@@ -439,6 +882,22 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     if (this._isMapMode) this._store.delete(nodeToDelete.key);
     this._size--;
 
+    // Update min/max caches.
+    if (this._size <= 0) {
+      this._setMinCache(undefined);
+      this._setMaxCache(undefined);
+    } else {
+      if (willDeleteMin) this._setMinCache(nextMin);
+      if (willDeleteMax) this._setMaxCache(nextMax);
+      // Fallback if successor/predecessor was unavailable.
+      if (!this._minNode || !this.isRealNode(this._minNode)) {
+        this._setMinCache(this.isRealNode(this._root) ? this.getLeftMost(n => n, this._root) : undefined);
+      }
+      if (!this._maxNode || !this.isRealNode(this._maxNode)) {
+        this._setMaxCache(this.isRealNode(this._root) ? this.getRightMost(n => n, this._root) : undefined);
+      }
+    }
+
     if (originalColor === 'BLACK') {
       this._deleteFixup(replacementNode);
     }
@@ -450,7 +909,7 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
 
   /**
    * Transform entries into a like-kind red-black tree with possibly different key/value types.
-   * @remarks Time O(n), Space O(n)
+   * @remarks Time O(n) average, Space O(n)
    * @template MK
    * @template MV
    * @template MR
@@ -459,7 +918,6 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
    * @param [thisArg] - See parameter type for details.
    * @returns A new RedBlackTree with mapped entries.
    */
-
   override map<MK = K, MV = V, MR = any>(
     callback: EntryCallback<K, V | undefined, [MK, MV]>,
     options?: Partial<RedBlackTreeOptions<MK, MV, MR>>,
@@ -474,6 +932,10 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     return out;
   }
 
+  /**
+   * (Internal) Create an empty instance of the same concrete tree type.
+   * @remarks Time O(1) average, Space O(1)
+   */
   protected override _createInstance<TK = K, TV = V, TR = R>(options?: Partial<RedBlackTreeOptions<TK, TV, TR>>): this {
     const Ctor = this.constructor as unknown as new (
       iter?: Iterable<TK | RedBlackTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>,
@@ -482,6 +944,10 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     return new Ctor([], { ...this._snapshotOptions<TK, TV, TR>(), ...(options ?? {}) }) as unknown as this;
   }
 
+  /**
+   * (Internal) Create a like-kind tree (same concrete class) populated from an iterable.
+   * @remarks Time O(m log m) average (m = iterable length), Space O(m)
+   */
   protected override _createLike<TK = K, TV = V, TR = R>(
     iter: Iterable<
       TK | RedBlackTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR
@@ -495,13 +961,25 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     return new Ctor(iter, { ...this._snapshotOptions<TK, TV, TR>(), ...(options ?? {}) });
   }
 
+  /**
+   * (Internal) Set the root pointer and keep header.parent in sync.
+   * @remarks Time O(1), Space O(1)
+   */
   protected override _setRoot(v: RedBlackTreeNode<K, V> | undefined) {
+    const NIL = this.NIL;
     if (v) {
       v.parent = undefined;
     }
     this._root = v;
+    // Keep header root pointer in sync even for internal operations (rotations/transplants)
+    // and for subclasses that may bypass _setKVNode.
+    this._header.parent = v ?? NIL;
   }
 
+  /**
+   * (Internal) Replace a node in place while preserving its color.
+   * @remarks Time O(1) average, Space O(1)
+   */
   protected override _replaceNode(
     oldNode: RedBlackTreeNode<K, V>,
     newNode: RedBlackTreeNode<K, V>
@@ -513,22 +991,25 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
 
   /**
    * (Protected) Standard BST insert followed by red-black fix-up.
-   * @remarks Time O(log n), Space O(1)
+   * @remarks Time O(log n) average, Space O(1)
    * @param node - Node to insert.
    * @returns Status string: 'CREATED' or 'UPDATED'.
    */
-
   protected _insert(node: RedBlackTreeNode<K, V>): CRUD {
-    let current = this.root ?? this.NIL;
-    let parent: RedBlackTreeNode<K, V> | undefined = undefined;
+    const NIL = this.NIL;
+    const cmp = this._compare.bind(this);
 
-    while (current !== this.NIL) {
+    let current = this._header.parent ?? NIL;
+    let parent: RedBlackTreeNode<K, V> | undefined;
+    let lastCompared = 0;
+
+    while (current !== NIL) {
       parent = current;
-      const compared = this._compare(node.key, current.key);
-      if (compared < 0) {
-        current = current.left ?? this.NIL;
-      } else if (compared > 0) {
-        current = current.right ?? this.NIL;
+      lastCompared = cmp(node.key, current.key);
+      if (lastCompared < 0) {
+        current = current.left ?? NIL;
+      } else if (lastCompared > 0) {
+        current = current.right ?? NIL;
       } else {
         this._replaceNode(current, node);
         return 'UPDATED';
@@ -539,14 +1020,14 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
 
     if (!parent) {
       this._setRoot(node);
-    } else if (this._compare(node.key, parent.key) < 0) {
+    } else if (lastCompared < 0) {
       parent.left = node;
     } else {
       parent.right = node;
     }
 
-    node.left = this.NIL;
-    node.right = this.NIL;
+    node.left = NIL;
+    node.right = NIL;
     node.color = 'RED';
 
     this._insertFixup(node);
@@ -560,7 +1041,6 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
    * @param v - Replacement subtree root (may be undefined).
    * @returns void
    */
-
   protected _transplant(u: RedBlackTreeNode<K, V>, v: RedBlackTreeNode<K, V> | undefined): void {
     if (!u.parent) {
       this._setRoot(v);
@@ -577,53 +1057,68 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
 
   /**
    * (Protected) Restore red-black properties after insertion (recolor/rotate).
-   * @remarks Time O(log n), Space O(1)
+   * @remarks Time O(log n) average, Space O(1)
    * @param z - Recently inserted node.
    * @returns void
    */
-
   protected _insertFixup(z: RedBlackTreeNode<K, V> | undefined): void {
-    while (z?.parent?.color === 'RED') {
-      if (z.parent === z.parent.parent?.left) {
-        const y = z.parent.parent.right;
+    const leftRotate = this._leftRotate.bind(this);
+    const rightRotate = this._rightRotate.bind(this);
+
+    while (z) {
+      const p = z.parent;
+      if (!p || p.color !== 'RED') break;
+
+      const gp = p.parent;
+      if (!gp) break;
+
+      if (p === gp.left) {
+        const y = gp.right;
         if (y?.color === 'RED') {
-          z.parent.color = 'BLACK';
+          p.color = 'BLACK';
           y.color = 'BLACK';
-          z.parent.parent.color = 'RED';
+          gp.color = 'RED';
+          z = gp;
+          continue;
+        }
 
-          z = z.parent.parent;
-        } else {
-          if (z === z.parent.right) {
-            z = z.parent;
-            this._leftRotate(z);
-          }
+        if (z === p.right) {
+          z = p;
+          leftRotate(z);
+        }
 
-          if (z && z.parent && z.parent.parent) {
-            z.parent.color = 'BLACK';
-            z.parent.parent.color = 'RED';
-            this._rightRotate(z.parent.parent);
-          }
+        const p2 = z?.parent;
+        const gp2 = p2?.parent;
+        if (p2 && gp2) {
+          p2.color = 'BLACK';
+          gp2.color = 'RED';
+          rightRotate(gp2);
         }
       } else {
-        const y: RedBlackTreeNode<K, V> | undefined = z?.parent?.parent?.left ?? undefined;
+        const y = gp.left;
         if (y?.color === 'RED') {
-          z.parent.color = 'BLACK';
+          p.color = 'BLACK';
           y.color = 'BLACK';
-          z.parent.parent!.color = 'RED';
-          z = z.parent.parent;
-        } else {
-          if (z === z.parent.left) {
-            z = z.parent;
-            this._rightRotate(z);
-          }
+          gp.color = 'RED';
+          z = gp;
+          continue;
+        }
 
-          if (z && z.parent && z.parent.parent) {
-            z.parent.color = 'BLACK';
-            z.parent.parent.color = 'RED';
-            this._leftRotate(z.parent.parent);
-          }
+        if (z === p.left) {
+          z = p;
+          rightRotate(z);
+        }
+
+        const p2 = z?.parent;
+        const gp2 = p2?.parent;
+        if (p2 && gp2) {
+          p2.color = 'BLACK';
+          gp2.color = 'RED';
+          leftRotate(gp2);
         }
       }
+
+      break;
     }
 
     if (this.isRealNode(this._root)) this._root.color = 'BLACK';
@@ -631,11 +1126,10 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
 
   /**
    * (Protected) Restore red-black properties after deletion (recolor/rotate).
-   * @remarks Time O(log n), Space O(1)
+   * @remarks Time O(log n) average, Space O(1)
    * @param node - Child that replaced the deleted node (may be undefined).
    * @returns void
    */
-
   protected _deleteFixup(node: RedBlackTreeNode<K, V> | undefined): void {
     if (!node || node === this.root || node.color === 'BLACK') {
       if (node) {
@@ -705,7 +1199,6 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
    * @param x - Pivot node to rotate around.
    * @returns void
    */
-
   protected _leftRotate(x: RedBlackTreeNode<K, V> | undefined): void {
     if (!x || !x.right) {
       return;
@@ -738,7 +1231,6 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
    * @param y - Pivot node to rotate around.
    * @returns void
    */
-
   protected _rightRotate(y: RedBlackTreeNode<K, V> | undefined): void {
     if (!y || !y.left) {
       return;