@frostpillar/frostpillar-btree 0.2.0

package/dist/index.cjs

@@ -0,0 +1,2230 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BTreeConcurrencyError: () => BTreeConcurrencyError,
+  BTreeInvariantError: () => BTreeInvariantError,
+  BTreeValidationError: () => BTreeValidationError,
+  ConcurrentInMemoryBTree: () => ConcurrentInMemoryBTree,
+  InMemoryBTree: () => InMemoryBTree
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var BTreeValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BTreeValidationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var BTreeInvariantError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BTreeInvariantError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var BTreeConcurrencyError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BTreeConcurrencyError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/btree/types.ts
+var DEFAULT_MAX_LEAF_ENTRIES = 64;
+var DEFAULT_MAX_BRANCH_CHILDREN = 64;
+var MIN_NODE_CAPACITY = 3;
+var MAX_NODE_CAPACITY = 16384;
+var NODE_LEAF = 0;
+var NODE_BRANCH = 1;
+var normalizeDuplicateKeyPolicy = (value) => {
+  if (value === void 0) {
+    return "replace";
+  }
+  if (value !== "allow" && value !== "reject" && value !== "replace") {
+    throw new BTreeValidationError(
+      `Invalid duplicateKeys option.`
+    );
+  }
+  return value;
+};
+var isLeafNode = (node) => {
+  return node.kind === NODE_LEAF;
+};
+var writeMinKeyTo = (node, target) => {
+  if (node.kind === NODE_LEAF) {
+    if (node.entryOffset >= node.entries.length) return false;
+    const e = node.entries[node.entryOffset];
+    target.key = e.key;
+    target.sequence = e.entryId;
+    return true;
+  }
+  if (node.childOffset >= node.keys.length) return false;
+  target.key = node.keys[node.childOffset].key;
+  target.sequence = node.keys[node.childOffset].sequence;
+  return true;
+};
+var normalizeNodeCapacity = (value, field, defaultValue) => {
+  if (value === void 0) {
+    return defaultValue;
+  }
+  if (!Number.isInteger(value) || value < MIN_NODE_CAPACITY || value > MAX_NODE_CAPACITY) {
+    throw new BTreeValidationError(
+      `${field}: integer ${MIN_NODE_CAPACITY}\u2013${MAX_NODE_CAPACITY} required.`
+    );
+  }
+  return value;
+};
+var createLeafNode = (entries, parent) => {
+  return {
+    kind: NODE_LEAF,
+    entries,
+    entryOffset: 0,
+    parent,
+    indexInParent: 0,
+    prev: null,
+    next: null
+  };
+};
+var createBranchNode = (children, parent) => {
+  const keys = [];
+  const branch = {
+    kind: NODE_BRANCH,
+    children,
+    keys,
+    childOffset: 0,
+    parent,
+    indexInParent: 0
+  };
+  for (let i = 0; i < children.length; i += 1) {
+    const child = children[i];
+    child.parent = branch;
+    child.indexInParent = i;
+    const target = { key: void 0, sequence: 0 };
+    if (!writeMinKeyTo(child, target)) {
+      throw new BTreeInvariantError(
+        "branch child has no min key"
+      );
+    }
+    keys.push(target);
+  }
+  return branch;
+};
+var leafEntryCount = (leaf) => leaf.entries.length - leaf.entryOffset;
+var leafEntryAt = (leaf, i) => leaf.entries[leaf.entryOffset + i];
+var leafShiftEntry = (leaf) => {
+  if (leaf.entryOffset >= leaf.entries.length) return void 0;
+  const entry = leaf.entries[leaf.entryOffset];
+  leaf.entryOffset += 1;
+  if (leaf.entryOffset >= leaf.entries.length >>> 1) {
+    leaf.entries.copyWithin(0, leaf.entryOffset);
+    leaf.entries.length = leaf.entries.length - leaf.entryOffset;
+    leaf.entryOffset = 0;
+  }
+  return entry;
+};
+var leafPopEntry = (leaf) => {
+  if (leaf.entryOffset >= leaf.entries.length) return void 0;
+  return leaf.entries.pop();
+};
+var leafUnshiftEntry = (leaf, entry) => {
+  if (leaf.entryOffset > 0) {
+    leaf.entryOffset -= 1;
+    leaf.entries[leaf.entryOffset] = entry;
+  } else {
+    leaf.entries.unshift(entry);
+  }
+};
+var leafRemoveAt = (leaf, logicalIndex) => {
+  const count = leaf.entries.length - leaf.entryOffset;
+  const phys = leaf.entryOffset + logicalIndex;
+  if (logicalIndex < count - 1 - logicalIndex) {
+    leaf.entries.copyWithin(leaf.entryOffset + 1, leaf.entryOffset, phys);
+    leaf.entryOffset += 1;
+    if (leaf.entryOffset >= leaf.entries.length >>> 1) {
+      leaf.entries.copyWithin(0, leaf.entryOffset);
+      leaf.entries.length -= leaf.entryOffset;
+      leaf.entryOffset = 0;
+    }
+  } else {
+    leaf.entries.copyWithin(phys, phys + 1);
+    leaf.entries.length -= 1;
+  }
+};
+var leafInsertAt = (leaf, logicalIndex, entry) => {
+  const phys = leaf.entryOffset + logicalIndex;
+  if (leaf.entryOffset > 0 && logicalIndex < leaf.entries.length - leaf.entryOffset >>> 1) {
+    leaf.entries.copyWithin(leaf.entryOffset - 1, leaf.entryOffset, phys);
+    leaf.entryOffset -= 1;
+    leaf.entries[phys - 1] = entry;
+  } else {
+    leaf.entries.splice(phys, 0, entry);
+  }
+};
+var leafCompact = (leaf) => {
+  if (leaf.entryOffset > 0) {
+    leaf.entries.copyWithin(0, leaf.entryOffset);
+    leaf.entries.length = leaf.entries.length - leaf.entryOffset;
+    leaf.entryOffset = 0;
+  }
+};
+var BRANCH_COMPACT_GAP = 1;
+var branchCompact = (branch) => {
+  if (branch.childOffset > 0) {
+    const gap = branch.childOffset <= BRANCH_COMPACT_GAP ? 0 : BRANCH_COMPACT_GAP;
+    branch.children.copyWithin(gap, branch.childOffset);
+    branch.children.length -= branch.childOffset - gap;
+    branch.keys.copyWithin(gap, branch.childOffset);
+    branch.keys.length -= branch.childOffset - gap;
+    branch.childOffset = gap;
+    for (let i = gap; i < branch.children.length; i += 1) {
+      branch.children[i].indexInParent = i;
+    }
+  }
+};
+var branchChildCount = (branch) => branch.children.length - branch.childOffset;
+var branchInsertAt = (branch, logicalIndex, child, key) => {
+  const phys = branch.childOffset + logicalIndex;
+  const count = branch.children.length - branch.childOffset;
+  if (branch.childOffset > 0 && logicalIndex < count >>> 1) {
+    branch.children.copyWithin(branch.childOffset - 1, branch.childOffset, phys);
+    branch.keys.copyWithin(branch.childOffset - 1, branch.childOffset, phys);
+    branch.childOffset -= 1;
+    branch.children[phys - 1] = child;
+    branch.keys[phys - 1] = key;
+    for (let i = branch.childOffset; i < phys; i += 1) {
+      branch.children[i].indexInParent = i;
+    }
+    child.indexInParent = phys - 1;
+  } else {
+    branch.children.splice(phys, 0, child);
+    branch.keys.splice(phys, 0, key);
+    for (let i = phys; i < branch.children.length; i += 1) {
+      branch.children[i].indexInParent = i;
+    }
+  }
+};
+var branchRemoveAt = (branch, physIndex) => {
+  const logicalIndex = physIndex - branch.childOffset;
+  const count = branch.children.length - branch.childOffset;
+  if (logicalIndex < count - 1 - logicalIndex) {
+    branch.children.copyWithin(branch.childOffset + 1, branch.childOffset, physIndex);
+    branch.keys.copyWithin(branch.childOffset + 1, branch.childOffset, physIndex);
+    branch.childOffset += 1;
+    for (let i = branch.childOffset; i <= physIndex; i += 1) {
+      branch.children[i].indexInParent = i;
+    }
+    if (branch.childOffset >= branch.children.length >>> 1) {
+      branchCompact(branch);
+    }
+  } else {
+    branch.children.copyWithin(physIndex, physIndex + 1);
+    branch.keys.copyWithin(physIndex, physIndex + 1);
+    branch.children.length -= 1;
+    branch.keys.length -= 1;
+    for (let i = physIndex; i < branch.children.length; i += 1) {
+      branch.children[i].indexInParent = i;
+    }
+  }
+};
+
+// src/btree/navigation.ts
+var selectBranchChild = (compare, branch, userKey, sequence) => {
+  const off = branch.childOffset;
+  if (off >= branch.children.length) {
+    throw new BTreeInvariantError("branch has no children");
+  }
+  let selectedIndex = off;
+  let lower = off;
+  let upper = branch.keys.length - 1;
+  while (lower <= upper) {
+    const mid = lower + upper >>> 1;
+    const k = branch.keys[mid];
+    const cmp = compare(k.key, userKey);
+    if ((cmp !== 0 ? cmp : k.sequence - sequence) <= 0) {
+      selectedIndex = mid;
+      lower = mid + 1;
+    } else {
+      upper = mid - 1;
+    }
+  }
+  return branch.children[selectedIndex];
+};
+var findLeafForKey = (state, userKey, sequence) => {
+  const compare = state.compareKeys;
+  let cursor = state.root;
+  while (cursor.kind !== NODE_LEAF) {
+    cursor = selectBranchChild(compare, cursor, userKey, sequence);
+  }
+  return cursor;
+};
+var lowerBoundInLeaf = (state, leaf, userKey, sequence) => {
+  const compare = state.compareKeys;
+  let lower = leaf.entryOffset;
+  let upper = leaf.entries.length;
+  while (lower < upper) {
+    const mid = lower + upper >>> 1;
+    const e = leaf.entries[mid];
+    const cmp = compare(e.key, userKey);
+    if ((cmp !== 0 ? cmp : e.entryId - sequence) < 0) {
+      lower = mid + 1;
+    } else {
+      upper = mid;
+    }
+  }
+  return lower - leaf.entryOffset;
+};
+var upperBoundInLeaf = (state, leaf, userKey, sequence) => {
+  const compare = state.compareKeys;
+  let lower = leaf.entryOffset;
+  let upper = leaf.entries.length;
+  while (lower < upper) {
+    const mid = lower + upper >>> 1;
+    const e = leaf.entries[mid];
+    const cmp = compare(e.key, userKey);
+    if ((cmp !== 0 ? cmp : e.entryId - sequence) <= 0) {
+      lower = mid + 1;
+    } else {
+      upper = mid;
+    }
+  }
+  return lower - leaf.entryOffset;
+};
+var findLeafFromHint = (state, hint, userKey, sequence) => {
+  const compare = state.compareKeys;
+  let leaf = hint;
+  let budget = 32 - Math.clz32(state.entryCount + 1);
+  while (budget > 0 && leaf.next !== null && leafEntryCount(leaf.next) > 0) {
+    const first = leafEntryAt(leaf.next, 0);
+    const cmp = compare(first.key, userKey);
+    if (cmp > 0 || cmp === 0 && first.entryId > sequence) break;
+    leaf = leaf.next;
+    budget -= 1;
+  }
+  if (budget === 0 && leaf.next !== null && leafEntryCount(leaf.next) > 0) {
+    const first = leafEntryAt(leaf.next, 0);
+    const cmp = compare(first.key, userKey);
+    if (cmp < 0 || cmp === 0 && first.entryId <= sequence) {
+      return findLeafForKey(state, userKey, sequence);
+    }
+  }
+  return leaf;
+};
+var findFirstMatchingUserKey = (state, key) => {
+  if (state.entryCount === 0) return null;
+  let leaf = findLeafForKey(state, key, 0);
+  let idx = lowerBoundInLeaf(state, leaf, key, 0);
+  if (idx >= leafEntryCount(leaf)) {
+    if (leaf.next === null) return null;
+    leaf = leaf.next;
+    idx = lowerBoundInLeaf(state, leaf, key, 0);
+    if (idx >= leafEntryCount(leaf)) return null;
+  }
+  if (state.compareKeys(leafEntryAt(leaf, idx).key, key) !== 0) return null;
+  const cursor = state._cursor;
+  cursor.leaf = leaf;
+  cursor.index = idx;
+  return cursor;
+};
+var findLastMatchingUserKey = (state, key) => {
+  if (state.entryCount === 0) return null;
+  let leaf = findLeafForKey(state, key, Number.MAX_SAFE_INTEGER);
+  let idx = upperBoundInLeaf(state, leaf, key, Number.MAX_SAFE_INTEGER);
+  if (idx === 0) {
+    if (leaf.prev === null) return null;
+    leaf = leaf.prev;
+    idx = leafEntryCount(leaf);
+    if (idx === 0) return null;
+  }
+  idx -= 1;
+  if (state.compareKeys(leafEntryAt(leaf, idx).key, key) !== 0) return null;
+  const cursor = state._cursor;
+  cursor.leaf = leaf;
+  cursor.index = idx;
+  return cursor;
+};
+var hasKeyEntry = (state, key) => {
+  return findFirstMatchingUserKey(state, key) !== null;
+};
+var findNextHigherKey = (state, key) => {
+  if (state.entryCount === 0) return null;
+  const compare = state.compareKeys;
+  let leaf = findLeafForKey(state, key, Number.MAX_SAFE_INTEGER);
+  let idx = upperBoundInLeaf(state, leaf, key, Number.MAX_SAFE_INTEGER);
+  while (leaf !== null) {
+    if (idx < leafEntryCount(leaf)) {
+      const e = leafEntryAt(leaf, idx);
+      if (compare(e.key, key) > 0) return e.key;
+      idx += 1;
+    } else {
+      leaf = leaf.next;
+      idx = 0;
+    }
+  }
+  return null;
+};
+var findNextLowerKey = (state, key) => {
+  if (state.entryCount === 0) return null;
+  const compare = state.compareKeys;
+  const leaf = findLeafForKey(state, key, 0);
+  const idx = lowerBoundInLeaf(state, leaf, key, 0);
+  let scanLeaf = leaf;
+  let scanIdx = idx - 1;
+  while (scanLeaf !== null) {
+    while (scanIdx >= 0) {
+      const e = leafEntryAt(scanLeaf, scanIdx);
+      if (compare(e.key, key) < 0) return e.key;
+      scanIdx -= 1;
+    }
+    scanLeaf = scanLeaf.prev;
+    if (scanLeaf !== null) {
+      scanIdx = leafEntryCount(scanLeaf) - 1;
+    }
+  }
+  return null;
+};
+var findPairOrNextLower = (state, key) => {
+  if (state.entryCount === 0) return null;
+  const compare = state.compareKeys;
+  const leaf = findLeafForKey(state, key, 0);
+  const idx = lowerBoundInLeaf(state, leaf, key, 0);
+  const cursor = state._cursor;
+  if (idx < leafEntryCount(leaf)) {
+    if (compare(leafEntryAt(leaf, idx).key, key) === 0) {
+      cursor.leaf = leaf;
+      cursor.index = idx;
+      return cursor;
+    }
+  } else if (leaf.next !== null) {
+    const nextIdx = lowerBoundInLeaf(state, leaf.next, key, 0);
+    if (nextIdx < leafEntryCount(leaf.next) && compare(leafEntryAt(leaf.next, nextIdx).key, key) === 0) {
+      cursor.leaf = leaf.next;
+      cursor.index = nextIdx;
+      return cursor;
+    }
+  }
+  if (idx > 0) {
+    cursor.leaf = leaf;
+    cursor.index = idx - 1;
+    return cursor;
+  }
+  if (leaf.prev !== null) {
+    const prevCount = leafEntryCount(leaf.prev);
+    if (prevCount > 0) {
+      cursor.leaf = leaf.prev;
+      cursor.index = prevCount - 1;
+      return cursor;
+    }
+  }
+  return null;
+};
+
+// src/btree/rebalance.ts
+var updateMinKeyInAncestors = (node) => {
+  let current = node;
+  while (current.parent !== null) {
+    const idx = current.indexInParent;
+    if (!writeMinKeyTo(current, current.parent.keys[idx])) return;
+    if (idx !== current.parent.childOffset) return;
+    current = current.parent;
+  }
+};
+var requireParent = (node) => {
+  if (node.parent === null) {
+    throw new BTreeInvariantError("no parent during rebalance");
+  }
+  return node.parent;
+};
+var requireLeafNode = (node) => {
+  if (!isLeafNode(node)) throw new BTreeInvariantError("expected leaf, got branch");
+  return node;
+};
+var requireBranchNode = (node) => {
+  if (isLeafNode(node)) throw new BTreeInvariantError("expected branch, got leaf");
+  return node;
+};
+var removeChildFromBranch = (branch, childIndex) => {
+  if (childIndex < branch.childOffset || childIndex >= branch.children.length) {
+    throw new BTreeInvariantError("child index out of range");
+  }
+  branchRemoveAt(branch, childIndex);
+};
+var detachLeafFromChain = (state, leaf) => {
+  if (leaf.prev !== null) {
+    leaf.prev.next = leaf.next;
+  } else if (leaf.next !== null) {
+    state.leftmostLeaf = leaf.next;
+  }
+  if (leaf.next !== null) {
+    leaf.next.prev = leaf.prev;
+  } else if (leaf.prev !== null) {
+    state.rightmostLeaf = leaf.prev;
+  }
+  leaf.prev = null;
+  leaf.next = null;
+};
+var borrowFromLeftBranch = (branch, leftSibling, branchIndex) => {
+  const borrowedChild = leftSibling.children.pop();
+  if (borrowedChild === void 0) throw new BTreeInvariantError("left branch borrow failed");
+  leftSibling.keys.pop();
+  borrowedChild.parent = branch;
+  const borrowedMinKey = { key: void 0, sequence: 0 };
+  if (!writeMinKeyTo(borrowedChild, borrowedMinKey)) throw new BTreeInvariantError("borrowed child has no min key");
+  if (branch.childOffset > 0) {
+    branch.childOffset -= 1;
+    branch.children[branch.childOffset] = borrowedChild;
+    branch.keys[branch.childOffset] = borrowedMinKey;
+    borrowedChild.indexInParent = branch.childOffset;
+  } else {
+    branch.children.unshift(borrowedChild);
+    branch.keys.unshift(borrowedMinKey);
+    for (let i = 0; i < branch.children.length; i += 1) branch.children[i].indexInParent = i;
+  }
+  const parent = requireParent(branch);
+  parent.keys[branchIndex] = { key: borrowedMinKey.key, sequence: borrowedMinKey.sequence };
+  updateMinKeyInAncestors(branch);
+};
+var borrowFromRightBranch = (branch, rightSibling, branchIndex) => {
+  const shiftIdx = rightSibling.childOffset;
+  if (shiftIdx >= rightSibling.children.length) throw new BTreeInvariantError("right branch borrow failed");
+  const borrowedChild = rightSibling.children[shiftIdx];
+  rightSibling.childOffset += 1;
+  if (rightSibling.childOffset >= rightSibling.children.length >>> 1) {
+    branchCompact(rightSibling);
+  }
+  branch.children.push(borrowedChild);
+  borrowedChild.parent = branch;
+  const borrowedMinKey = { key: void 0, sequence: 0 };
+  if (!writeMinKeyTo(borrowedChild, borrowedMinKey)) throw new BTreeInvariantError("borrowed child has no min key");
+  branch.keys.push(borrowedMinKey);
+  borrowedChild.indexInParent = branch.children.length - 1;
+  const parent = requireParent(branch);
+  writeMinKeyTo(rightSibling, parent.keys[branchIndex + 1]);
+};
+var mergeBranchIntoLeft = (state, branch, leftSibling, branchIndex) => {
+  for (let i = branch.childOffset; i < branch.children.length; i += 1) {
+    const child = branch.children[i];
+    child.parent = leftSibling;
+    child.indexInParent = leftSibling.children.length;
+    leftSibling.children.push(child);
+    leftSibling.keys.push(branch.keys[i]);
+  }
+  const parent = requireParent(branch);
+  removeChildFromBranch(parent, branchIndex);
+  rebalanceAfterBranchRemoval(state, parent);
+};
+var mergeBranchIntoRight = (state, branch, rightSibling, branchIndex) => {
+  for (let i = rightSibling.childOffset; i < rightSibling.children.length; i += 1) {
+    const child = rightSibling.children[i];
+    child.parent = branch;
+    child.indexInParent = branch.children.length;
+    branch.children.push(child);
+    branch.keys.push(rightSibling.keys[i]);
+  }
+  const parent = requireParent(branch);
+  removeChildFromBranch(parent, branchIndex + 1);
+  rebalanceAfterBranchRemoval(state, parent);
+};
+var findBranchSiblings = (parent, branchIndex) => {
+  const left = branchIndex > parent.childOffset ? requireBranchNode(parent.children[branchIndex - 1]) : null;
+  const right = branchIndex + 1 < parent.children.length ? requireBranchNode(parent.children[branchIndex + 1]) : null;
+  return { left, right };
+};
+var rebalanceAfterBranchRemoval = (state, branch) => {
+  const liveCount = branchChildCount(branch);
+  if (branch === state.root) {
+    if (liveCount === 1) {
+      const onlyChild = branch.children[branch.childOffset];
+      onlyChild.parent = null;
+      state.root = onlyChild;
+      if (isLeafNode(onlyChild)) {
+        state.leftmostLeaf = onlyChild;
+        state.rightmostLeaf = onlyChild;
+      }
+    }
+    return;
+  }
+  if (liveCount >= state.minBranchChildren) return;
+  const parent = branch.parent;
+  if (parent === null) throw new BTreeInvariantError("branch has no parent");
+  const branchIndex = branch.indexInParent;
+  const { left: leftSibling, right: rightSibling } = findBranchSiblings(parent, branchIndex);
+  if (rightSibling !== null && branchChildCount(rightSibling) > state.minBranchChildren) {
+    borrowFromRightBranch(branch, rightSibling, branchIndex);
+    return;
+  }
+  if (leftSibling !== null && branchChildCount(leftSibling) > state.minBranchChildren) {
+    borrowFromLeftBranch(branch, leftSibling, branchIndex);
+    return;
+  }
+  if (leftSibling !== null) {
+    mergeBranchIntoLeft(state, branch, leftSibling, branchIndex);
+    return;
+  }
+  if (rightSibling !== null) {
+    mergeBranchIntoRight(state, branch, rightSibling, branchIndex);
+    return;
+  }
+  throw new BTreeInvariantError("no branch siblings to rebalance");
+};
+var mergeLeafEntries = (target, source) => {
+  if (target.entryOffset > 0) {
+    target.entries.copyWithin(0, target.entryOffset);
+    target.entries.length = target.entries.length - target.entryOffset;
+    target.entryOffset = 0;
+  }
+  const src = source.entries;
+  for (let i = source.entryOffset; i < src.length; i += 1) target.entries.push(src[i]);
+};
+var rebalanceAfterLeafRemoval = (state, leaf) => {
+  if (leaf === state.root) {
+    if (state.entryCount === 0) {
+      state.leftmostLeaf = leaf;
+      state.rightmostLeaf = leaf;
+    }
+    return;
+  }
+  if (leafEntryCount(leaf) >= state.minLeafEntries) return;
+  const parent = leaf.parent;
+  if (parent === null) throw new BTreeInvariantError("Leaf node has no parent during rebalance.");
+  const leafIndex = leaf.indexInParent;
+  const leftSibling = leafIndex > parent.childOffset ? requireLeafNode(parent.children[leafIndex - 1]) : null;
+  const rightSibling = leafIndex + 1 < parent.children.length ? requireLeafNode(parent.children[leafIndex + 1]) : null;
+  if (rightSibling !== null && leafEntryCount(rightSibling) > state.minLeafEntries) {
+    const borrowed = leafShiftEntry(rightSibling);
+    if (borrowed === void 0) throw new BTreeInvariantError("right leaf borrow failed");
+    leaf.entries.push(borrowed);
+    writeMinKeyTo(rightSibling, parent.keys[leafIndex + 1]);
+    return;
+  }
+  if (leftSibling !== null && leafEntryCount(leftSibling) > state.minLeafEntries) {
+    const borrowed = leftSibling.entries.pop();
+    if (borrowed === void 0) throw new BTreeInvariantError("left leaf borrow failed");
+    leafUnshiftEntry(leaf, borrowed);
+    parent.keys[leafIndex] = { key: borrowed.key, sequence: borrowed.entryId };
+    updateMinKeyInAncestors(leaf);
+    return;
+  }
+  if (leftSibling !== null) {
+    mergeLeafEntries(leftSibling, leaf);
+    detachLeafFromChain(state, leaf);
+    removeChildFromBranch(parent, leafIndex);
+    rebalanceAfterBranchRemoval(state, parent);
+    return;
+  }
+  if (rightSibling !== null) {
+    mergeLeafEntries(leaf, rightSibling);
+    detachLeafFromChain(state, rightSibling);
+    removeChildFromBranch(parent, leafIndex + 1);
+    rebalanceAfterBranchRemoval(state, parent);
+    return;
+  }
+  throw new BTreeInvariantError("no leaf siblings to rebalance");
+};
+
+// src/btree/deleteRange.ts
+var navigateToStart = (state, startKey, lowerExclusive) => {
+  const startSeq = lowerExclusive ? Number.MAX_SAFE_INTEGER : 0;
+  const leaf = findLeafForKey(state, startKey, startSeq);
+  const idx = lowerExclusive ? upperBoundInLeaf(state, leaf, startKey, Number.MAX_SAFE_INTEGER) : lowerBoundInLeaf(state, leaf, startKey, 0);
+  if (idx >= leafEntryCount(leaf)) {
+    if (leaf.next === null) return null;
+    return { leaf: leaf.next, idx: 0 };
+  }
+  return { leaf, idx };
+};
+var findRemoveEnd = (state, leaf, idx, endKey, upperExclusive) => {
+  const count = leafEntryCount(leaf);
+  let removeEnd = idx;
+  while (removeEnd < count) {
+    const e = leafEntryAt(leaf, removeEnd);
+    const cmpEnd = state.compareKeys(e.key, endKey);
+    if (upperExclusive ? cmpEnd >= 0 : cmpEnd > 0) break;
+    removeEnd += 1;
+  }
+  return removeEnd;
+};
+var computeTreeHeight = (state) => {
+  let h = 0;
+  let n = state.root;
+  while (!isLeafNode(n)) {
+    n = n.children[n.childOffset];
+    h += 1;
+  }
+  return h;
+};
+var spliceLeafAndRebalance = (state, leaf, idx, removeCount, maxRebalanceDepth) => {
+  if (state.entryKeys !== null) {
+    for (let i = idx; i < idx + removeCount; i += 1) {
+      state.entryKeys.delete(leafEntryAt(leaf, i).entryId);
+    }
+  }
+  const phys = leaf.entryOffset + idx;
+  leaf.entries.copyWithin(phys, phys + removeCount);
+  leaf.entries.length -= removeCount;
+  state.entryCount -= removeCount;
+  const leafEmptied = leafEntryCount(leaf) === 0;
+  if (idx === 0 && !leafEmptied && leaf.parent !== null) {
+    updateMinKeyInAncestors(leaf);
+  }
+  const countAfterSplice = leafEntryCount(leaf);
+  let maxIter = maxRebalanceDepth;
+  while (maxIter > 0 && leaf !== state.root && leafEntryCount(leaf) < state.minLeafEntries) {
+    rebalanceAfterLeafRemoval(state, leaf);
+    if (leaf.parent !== null && leaf.parent.children[leaf.indexInParent] !== leaf) break;
+    maxIter -= 1;
+  }
+  if (leafEmptied && leafEntryCount(leaf) > 0 && leaf.parent !== null && leaf.parent.children[leaf.indexInParent] === leaf) {
+    updateMinKeyInAncestors(leaf);
+  }
+  return countAfterSplice;
+};
+var isLeafStillValid = (state, leaf) => leaf.parent === null ? leaf === state.root : leaf.parent.children[leaf.indexInParent] === leaf;
+var deleteRangeEntries = (state, startKey, endKey, options) => {
+  if (state.entryCount === 0) return 0;
+  const boundCompared = state.compareKeys(startKey, endKey);
+  if (boundCompared > 0) return 0;
+  const lowerExclusive = options?.lowerBound === "exclusive";
+  const upperExclusive = options?.upperBound === "exclusive";
+  if (lowerExclusive && upperExclusive && boundCompared === 0) return 0;
+  const treeHeight = computeTreeHeight(state);
+  let deleted = 0;
+  let needsNavigate = true;
+  let leaf = null;
+  let idx = 0;
+  while (state.entryCount > 0) {
+    if (needsNavigate) {
+      const cursor = navigateToStart(state, startKey, lowerExclusive);
+      if (cursor === null) break;
+      leaf = cursor.leaf;
+      idx = cursor.idx;
+      needsNavigate = false;
+    }
+    if (idx >= leafEntryCount(leaf)) break;
+    const count = leafEntryCount(leaf);
+    const removeEnd = findRemoveEnd(state, leaf, idx, endKey, upperExclusive);
+    const removeCount = removeEnd - idx;
+    if (removeCount === 0) break;
+    const countAfterSplice = spliceLeafAndRebalance(state, leaf, idx, removeCount, treeHeight);
+    deleted += removeCount;
+    if (removeEnd < count) break;
+    if (!isLeafStillValid(state, leaf)) {
+      needsNavigate = true;
+      continue;
+    }
+    if (leafEntryCount(leaf) > countAfterSplice) {
+      needsNavigate = true;
+      continue;
+    }
+    if (leaf.next === null) break;
+    leaf = leaf.next;
+    idx = 0;
+  }
+  return deleted;
+};
+
+// src/btree/autoScale.ts
+var AUTO_SCALE_TIERS = [
+  { threshold: 0, maxLeaf: 32, maxBranch: 32 },
+  { threshold: 1e3, maxLeaf: 64, maxBranch: 64 },
+  { threshold: 1e4, maxLeaf: 128, maxBranch: 128 },
+  { threshold: 1e5, maxLeaf: 256, maxBranch: 128 },
+  { threshold: 1e6, maxLeaf: 512, maxBranch: 256 }
+];
+var computeAutoScaleTier = (entryCount) => {
+  let tier = AUTO_SCALE_TIERS[0];
+  for (let i = 1; i < AUTO_SCALE_TIERS.length; i += 1) {
+    if (entryCount >= AUTO_SCALE_TIERS[i].threshold) {
+      tier = AUTO_SCALE_TIERS[i];
+    } else {
+      break;
+    }
+  }
+  return tier;
+};
+var computeNextAutoScaleThreshold = (entryCount) => {
+  for (let i = 1; i < AUTO_SCALE_TIERS.length; i += 1) {
+    if (entryCount < AUTO_SCALE_TIERS[i].threshold) {
+      return AUTO_SCALE_TIERS[i].threshold;
+    }
+  }
+  return Number.MAX_SAFE_INTEGER;
+};
+var createInitialState = (config) => {
+  if (typeof config.compareKeys !== "function") {
+    throw new BTreeValidationError("compareKeys must be a function.");
+  }
+  const autoScale = config.autoScale === true;
+  if (autoScale && (config.maxLeafEntries !== void 0 || config.maxBranchChildren !== void 0)) {
+    throw new BTreeValidationError("autoScale conflicts with explicit capacity.");
+  }
+  let maxLeafEntries;
+  let maxBranchChildren;
+  if (autoScale) {
+    const tier = computeAutoScaleTier(0);
+    maxLeafEntries = tier.maxLeaf;
+    maxBranchChildren = tier.maxBranch;
+  } else {
+    maxLeafEntries = normalizeNodeCapacity(config.maxLeafEntries, "maxLeafEntries", DEFAULT_MAX_LEAF_ENTRIES);
+    maxBranchChildren = normalizeNodeCapacity(config.maxBranchChildren, "maxBranchChildren", DEFAULT_MAX_BRANCH_CHILDREN);
+  }
+  const duplicateKeys = normalizeDuplicateKeyPolicy(config.duplicateKeys);
+  const emptyLeaf = createLeafNode([], null);
+  return {
+    compareKeys: config.compareKeys,
+    maxLeafEntries,
+    maxBranchChildren,
+    duplicateKeys,
+    minLeafEntries: Math.ceil(maxLeafEntries / 2),
+    minBranchChildren: Math.ceil(maxBranchChildren / 2),
+    root: emptyLeaf,
+    leftmostLeaf: emptyLeaf,
+    rightmostLeaf: emptyLeaf,
+    entryCount: 0,
+    nextSequence: 0,
+    entryKeys: config.enableEntryIdLookup === true ? /* @__PURE__ */ new Map() : null,
+    autoScale,
+    _nextAutoScaleThreshold: autoScale ? computeNextAutoScaleThreshold(0) : Number.MAX_SAFE_INTEGER,
+    _cursor: { leaf: emptyLeaf, index: 0 }
+  };
+};
+var maybeAutoScale = (state) => {
+  if (state.entryCount < state._nextAutoScaleThreshold) return;
+  const { maxLeaf, maxBranch } = computeAutoScaleTier(state.entryCount);
+  if (maxLeaf > state.maxLeafEntries) {
+    state.maxLeafEntries = maxLeaf;
+    state.minLeafEntries = Math.ceil(maxLeaf / 2);
+  }
+  if (maxBranch > state.maxBranchChildren) {
+    state.maxBranchChildren = maxBranch;
+    state.minBranchChildren = Math.ceil(maxBranch / 2);
+  }
+  state._nextAutoScaleThreshold = computeNextAutoScaleThreshold(state.entryCount);
+};
+var applyAutoScaleCapacitySnapshot = (state, maxLeafEntries, maxBranchChildren) => {
+  if (!state.autoScale) {
+    return;
+  }
+  const baseTier = computeAutoScaleTier(0);
+  const normalizedLeaf = normalizeNodeCapacity(
+    maxLeafEntries,
+    "maxLeafEntries",
+    DEFAULT_MAX_LEAF_ENTRIES
+  );
+  const normalizedBranch = normalizeNodeCapacity(
+    maxBranchChildren,
+    "maxBranchChildren",
+    DEFAULT_MAX_BRANCH_CHILDREN
+  );
+  if (normalizedLeaf < baseTier.maxLeaf || normalizedBranch < baseTier.maxBranch) {
+    throw new BTreeValidationError(
+      "autoScale capacity snapshot must be >= tier-0 capacities."
+    );
+  }
+  state.maxLeafEntries = normalizedLeaf;
+  state.maxBranchChildren = normalizedBranch;
+  state.minLeafEntries = Math.ceil(normalizedLeaf / 2);
+  state.minBranchChildren = Math.ceil(normalizedBranch / 2);
+};
+
+// src/btree/bulkLoad.ts
+var computeChunkBoundaries = (total, max, min) => {
+  const boundaries = [];
+  let offset = 0;
+  while (offset < total) {
+    const remaining = total - offset;
+    if (remaining > max && remaining - max < min) {
+      const half = Math.ceil(remaining / 2);
+      boundaries.push(offset + half);
+      boundaries.push(total);
+      break;
+    }
+    const end = offset + max < total ? offset + max : total;
+    boundaries.push(end);
+    offset = end;
+  }
+  return boundaries;
+};
+var buildLeaves = (state, entries, ids, baseSequence) => {
+  const boundaries = computeChunkBoundaries(entries.length, state.maxLeafEntries, state.minLeafEntries);
+  const leaves = new Array(boundaries.length);
+  let chunkStart = 0;
+  for (let c = 0; c < boundaries.length; c += 1) {
+    const chunkEnd = boundaries[c];
+    const chunk = new Array(chunkEnd - chunkStart);
+    for (let i = chunkStart; i < chunkEnd; i += 1) {
+      const seq = baseSequence + i;
+      chunk[i - chunkStart] = { key: entries[i].key, entryId: seq, value: entries[i].value };
+      ids[i] = seq;
+      if (state.entryKeys !== null) {
+        state.entryKeys.set(seq, entries[i].key);
+      }
+    }
+    leaves[c] = createLeafNode(chunk, null);
+    chunkStart = chunkEnd;
+  }
+  return leaves;
+};
+var bulkLoadEntries = (state, entries) => {
+  if (state.entryCount !== 0) {
+    throw new BTreeInvariantError("bulk load requires empty tree");
+  }
+  const baseSequence = state.nextSequence;
+  if (baseSequence + entries.length > Number.MAX_SAFE_INTEGER) {
+    throw new BTreeValidationError("Sequence overflow.");
+  }
+  const ids = new Array(entries.length);
+  const leaves = buildLeaves(state, entries, ids, baseSequence);
+  state.nextSequence = baseSequence + entries.length;
+  state.entryCount = entries.length;
+  for (let i = 0; i < leaves.length; i += 1) {
+    if (i > 0) leaves[i].prev = leaves[i - 1];
+    if (i < leaves.length - 1) leaves[i].next = leaves[i + 1];
+  }
+  state.leftmostLeaf = leaves[0];
+  state.rightmostLeaf = leaves[leaves.length - 1];
+  if (leaves.length === 1) {
+    state.root = leaves[0];
+  } else {
+    let currentLevel = leaves;
+    while (currentLevel.length > 1) {
+      const bounds = computeChunkBoundaries(currentLevel.length, state.maxBranchChildren, state.minBranchChildren);
+      const nextLevel = new Array(bounds.length);
+      let start = 0;
+      for (let b = 0; b < bounds.length; b += 1) {
+        nextLevel[b] = createBranchNode(currentLevel.slice(start, bounds[b]), null);
+        start = bounds[b];
+      }
+      currentLevel = nextLevel;
+    }
+    state.root = currentLevel[0];
+  }
+  maybeAutoScale(state);
+  return ids;
+};
+
+// src/btree/mutations.ts
+var insertChildAfter = (state, parent, existingChild, childToInsert) => {
+  const newChildMinKey = { key: void 0, sequence: 0 };
+  if (!writeMinKeyTo(childToInsert, newChildMinKey)) {
+    throw new BTreeInvariantError("inserted child has no min key");
+  }
+  childToInsert.parent = parent;
+  const logicalIndex = existingChild.indexInParent - parent.childOffset + 1;
+  branchInsertAt(parent, logicalIndex, childToInsert, newChildMinKey);
+  if (branchChildCount(parent) > state.maxBranchChildren) {
+    splitBranch(state, parent);
+  }
+};
+var splitLeaf = (state, leaf) => {
+  leafCompact(leaf);
+  const splitAt = Math.ceil(leaf.entries.length / 2);
+  const sibling = {
+    kind: NODE_LEAF,
+    entries: leaf.entries.splice(splitAt),
+    entryOffset: 0,
+    parent: leaf.parent,
+    indexInParent: 0,
+    prev: leaf,
+    next: leaf.next
+  };
+  if (leaf.next !== null) {
+    leaf.next.prev = sibling;
+  } else {
+    state.rightmostLeaf = sibling;
+  }
+  leaf.next = sibling;
+  if (leaf.parent === null) {
+    state.root = createBranchNode([leaf, sibling], null);
+    return;
+  }
+  insertChildAfter(state, leaf.parent, leaf, sibling);
+};
+var splitBranch = (state, branch) => {
+  branchCompact(branch);
+  const splitAt = Math.ceil(branch.children.length / 2);
+  const sibling = createBranchNode(branch.children.splice(splitAt), branch.parent);
+  branch.keys.splice(splitAt);
+  if (branch.parent === null) {
+    state.root = createBranchNode([branch, sibling], null);
+    return;
+  }
+  insertChildAfter(state, branch.parent, branch, sibling);
+};
+var putEntryIntoLeaf = (state, targetLeaf, key, value) => {
+  const sequence = state.nextSequence;
+  const insertAt = upperBoundInLeaf(state, targetLeaf, key, sequence);
+  if (state.duplicateKeys !== "allow") {
+    let existingEntry = null;
+    if (insertAt > 0) {
+      const candidate = leafEntryAt(targetLeaf, insertAt - 1);
+      if (state.compareKeys(candidate.key, key) === 0) {
+        existingEntry = candidate;
+      }
+    } else if (targetLeaf.prev !== null && leafEntryCount(targetLeaf.prev) > 0) {
+      const prevLeaf = targetLeaf.prev;
+      const candidate = leafEntryAt(prevLeaf, leafEntryCount(prevLeaf) - 1);
+      if (state.compareKeys(candidate.key, key) === 0) {
+        existingEntry = candidate;
+      }
+    }
+    if (existingEntry !== null) {
+      if (state.duplicateKeys === "reject") {
+        throw new BTreeValidationError("Duplicate key rejected.");
+      }
+      existingEntry.value = value;
+      return existingEntry.entryId;
+    }
+  }
+  if (state.nextSequence >= Number.MAX_SAFE_INTEGER) {
+    throw new BTreeValidationError("Sequence overflow.");
+  }
+  state.nextSequence += 1;
+  leafInsertAt(targetLeaf, insertAt, { key, entryId: sequence, value });
+  state.entryCount += 1;
+  if (state.entryKeys !== null) {
+    state.entryKeys.set(sequence, key);
+  }
+  if (insertAt === 0 && targetLeaf.parent !== null) updateMinKeyInAncestors(targetLeaf);
+  if (leafEntryCount(targetLeaf) > state.maxLeafEntries) splitLeaf(state, targetLeaf);
+  maybeAutoScale(state);
+  return sequence;
+};
+var putEntry = (state, key, value) => {
+  const targetLeaf = findLeafForKey(state, key, state.nextSequence);
+  return putEntryIntoLeaf(state, targetLeaf, key, value);
+};
+var popFirstEntry = (state) => {
+  if (state.entryCount === 0) return null;
+  const firstEntry = leafShiftEntry(state.leftmostLeaf);
+  if (firstEntry === void 0) throw new BTreeInvariantError("leftmost leaf empty but count > 0");
+  state.entryCount -= 1;
+  if (state.entryKeys !== null) {
+    state.entryKeys.delete(firstEntry.entryId);
+  }
+  if (leafEntryCount(state.leftmostLeaf) > 0 && state.leftmostLeaf.parent !== null) {
+    updateMinKeyInAncestors(state.leftmostLeaf);
+  }
+  if (state.leftmostLeaf !== state.root && leafEntryCount(state.leftmostLeaf) < state.minLeafEntries) {
+    rebalanceAfterLeafRemoval(state, state.leftmostLeaf);
+  }
+  return firstEntry;
+};
+var popLastEntry = (state) => {
+  if (state.entryCount === 0) return null;
+  const lastEntry = leafPopEntry(state.rightmostLeaf);
+  if (lastEntry === void 0) throw new BTreeInvariantError("rightmost leaf empty but count > 0");
+  state.entryCount -= 1;
+  if (state.entryKeys !== null) {
+    state.entryKeys.delete(lastEntry.entryId);
+  }
+  if (state.rightmostLeaf !== state.root && leafEntryCount(state.rightmostLeaf) < state.minLeafEntries) {
+    rebalanceAfterLeafRemoval(state, state.rightmostLeaf);
+  }
+  return lastEntry;
+};
+var removeFirstMatchingEntry = (state, key) => {
+  const found = findFirstMatchingUserKey(state, key);
+  if (found === null) return null;
+  const targetLeaf = found.leaf;
+  const removeAt = found.index;
+  const targetEntry = leafEntryAt(targetLeaf, removeAt);
+  leafRemoveAt(targetLeaf, removeAt);
+  state.entryCount -= 1;
+  if (state.entryKeys !== null) {
+    state.entryKeys.delete(targetEntry.entryId);
+  }
+  if (removeAt === 0 && leafEntryCount(targetLeaf) > 0 && targetLeaf.parent !== null) updateMinKeyInAncestors(targetLeaf);
+  if (targetLeaf !== state.root && leafEntryCount(targetLeaf) < state.minLeafEntries) {
+    rebalanceAfterLeafRemoval(state, targetLeaf);
+  }
+  return targetEntry;
+};
+var findLeafEntryBySequence = (state, userKey, sequence) => {
+  const targetLeaf = findLeafForKey(state, userKey, sequence);
+  const index = lowerBoundInLeaf(state, targetLeaf, userKey, sequence);
+  if (index >= leafEntryCount(targetLeaf)) return null;
+  const entry = leafEntryAt(targetLeaf, index);
+  if (entry.entryId !== sequence) return null;
+  return { leaf: targetLeaf, index };
+};
+var removeEntryById = (state, entryId) => {
+  const userKey = state.entryKeys.get(entryId);
+  if (userKey === void 0) return null;
+  const found = findLeafEntryBySequence(state, userKey, entryId);
+  if (found === null) return null;
+  const entry = leafEntryAt(found.leaf, found.index);
+  leafRemoveAt(found.leaf, found.index);
+  state.entryCount -= 1;
+  state.entryKeys.delete(entryId);
+  if (found.index === 0 && leafEntryCount(found.leaf) > 0 && found.leaf.parent !== null) {
+    updateMinKeyInAncestors(found.leaf);
+  }
+  if (found.leaf !== state.root && leafEntryCount(found.leaf) < state.minLeafEntries) {
+    rebalanceAfterLeafRemoval(state, found.leaf);
+  }
+  return entry;
+};
+var peekEntryById = (state, entryId) => {
+  const userKey = state.entryKeys.get(entryId);
+  if (userKey === void 0) return null;
+  const found = findLeafEntryBySequence(state, userKey, entryId);
+  if (found === null) return null;
+  const entry = leafEntryAt(found.leaf, found.index);
+  return entry;
+};
+var updateEntryById = (state, entryId, newValue) => {
+  const userKey = state.entryKeys.get(entryId);
+  if (userKey === void 0) return null;
+  const found = findLeafEntryBySequence(state, userKey, entryId);
+  if (found === null) return null;
+  const entry = leafEntryAt(found.leaf, found.index);
+  entry.value = newValue;
+  return entry;
+};
+var putManyEntries = (state, entries) => {
+  if (entries.length === 0) return [];
+  const strictlyAscending = state.duplicateKeys !== "allow";
+  for (let i = 1; i < entries.length; i += 1) {
+    const cmp = state.compareKeys(entries[i - 1].key, entries[i].key);
+    if (strictlyAscending ? cmp >= 0 : cmp > 0) {
+      throw new BTreeValidationError(
+        strictlyAscending ? "putMany: not sorted in strict ascending order." : "putMany: not sorted in non-descending order."
+      );
+    }
+  }
+  if (state.entryCount > 0) {
+    const ids = new Array(entries.length);
+    let hintLeaf = findLeafForKey(state, entries[0].key, state.nextSequence);
+    for (let i = 0; i < entries.length; i += 1) {
+      const entry = entries[i];
+      const targetLeaf = findLeafFromHint(state, hintLeaf, entry.key, state.nextSequence);
+      ids[i] = putEntryIntoLeaf(state, targetLeaf, entry.key, entry.value);
+      hintLeaf = targetLeaf;
+    }
+    return ids;
+  }
+  return bulkLoadEntries(state, entries);
+};
+
+// src/btree/rangeQuery.ts
+var initRangeCursor = (state, startKey, endKey, options) => {
+  if (state.entryCount === 0) return null;
+  const compare = state.compareKeys;
+  const boundCompared = compare(startKey, endKey);
+  if (boundCompared > 0) return null;
+  const lowerExclusive = options?.lowerBound === "exclusive";
+  const upperExclusive = options?.upperBound === "exclusive";
+  if (lowerExclusive && upperExclusive && boundCompared === 0) return null;
+  const startSeq = lowerExclusive ? Number.MAX_SAFE_INTEGER : 0;
+  const leaf = findLeafForKey(state, startKey, startSeq);
+  const index = lowerExclusive ? upperBoundInLeaf(state, leaf, startKey, Number.MAX_SAFE_INTEGER) : lowerBoundInLeaf(state, leaf, startKey, 0);
+  return { leaf, index, compare, upperExclusive };
+};
+var countRangeEntries = (state, startKey, endKey, options) => {
+  const cursor = initRangeCursor(state, startKey, endKey, options);
+  if (cursor === null) return 0;
+  let cursorLeaf = cursor.leaf;
+  let cursorIndex = cursor.index;
+  const { compare, upperExclusive } = cursor;
+  let count = 0;
+  while (cursorLeaf !== null) {
+    const leafCount = leafEntryCount(cursorLeaf);
+    if (cursorIndex >= leafCount) {
+      cursorLeaf = cursorLeaf.next;
+      cursorIndex = 0;
+      continue;
+    }
+    const lastEntry = leafEntryAt(cursorLeaf, leafCount - 1);
+    const cmpLast = compare(lastEntry.key, endKey);
+    if (upperExclusive ? cmpLast < 0 : cmpLast <= 0) {
+      count += leafCount - cursorIndex;
+      cursorLeaf = cursorLeaf.next;
+      cursorIndex = 0;
+      continue;
+    }
+    const endSeq = upperExclusive ? 0 : Number.MAX_SAFE_INTEGER;
+    const endBound = upperExclusive ? lowerBoundInLeaf(state, cursorLeaf, endKey, endSeq) : upperBoundInLeaf(state, cursorLeaf, endKey, endSeq);
+    const limit = endBound < leafCount ? endBound : leafCount;
+    count += limit - cursorIndex;
+    return count;
+  }
+  return count;
+};
+var RANGE_PREALLOC_THRESHOLD = 200;
+var allocateRangeOutput = (state, cursorLeaf, cursorIndex, compare, upperExclusive, startKey, endKey, options) => {
+  const firstLeafCount = leafEntryCount(cursorLeaf);
+  const firstLeafRemainder = firstLeafCount - cursorIndex;
+  if (firstLeafRemainder >= RANGE_PREALLOC_THRESHOLD && cursorLeaf.next !== null) {
+    const lastEntry = leafEntryAt(cursorLeaf, firstLeafCount - 1);
+    const cmpLast = compare(lastEntry.key, endKey);
+    if (upperExclusive ? cmpLast < 0 : cmpLast <= 0) {
+      const total = countRangeEntries(state, startKey, endKey, options);
+      return new Array(total);
+    }
+  }
+  return [];
+};
+var appendLeafSlice = (leaf, from, to, output, useIndexed, writeIdx) => {
+  if (useIndexed) {
+    for (let i = from; i < to; i += 1) {
+      output[writeIdx++] = leafEntryAt(leaf, i);
+    }
+  } else {
+    for (let i = from; i < to; i += 1) {
+      output.push(leafEntryAt(leaf, i));
+    }
+  }
+  return writeIdx;
+};
+var rangeQueryEntries = (state, startKey, endKey, options) => {
+  const cursor = initRangeCursor(state, startKey, endKey, options);
+  if (cursor === null) return [];
+  let cursorLeaf = cursor.leaf;
+  let cursorIndex = cursor.index;
+  const { compare, upperExclusive } = cursor;
+  const output = allocateRangeOutput(state, cursorLeaf, cursorIndex, compare, upperExclusive, startKey, endKey, options);
+  let writeIdx = 0;
+  const useIndexed = output.length > 0;
+  while (cursorLeaf !== null) {
+    const leafCount = leafEntryCount(cursorLeaf);
+    if (cursorIndex >= leafCount) {
+      cursorLeaf = cursorLeaf.next;
+      cursorIndex = 0;
+      continue;
+    }
+    const lastEntry = leafEntryAt(cursorLeaf, leafCount - 1);
+    const cmpLast = compare(lastEntry.key, endKey);
+    if (upperExclusive ? cmpLast < 0 : cmpLast <= 0) {
+      writeIdx = appendLeafSlice(cursorLeaf, cursorIndex, leafCount, output, useIndexed, writeIdx);
+      cursorLeaf = cursorLeaf.next;
+      cursorIndex = 0;
+      continue;
+    }
+    const endSeq = upperExclusive ? 0 : Number.MAX_SAFE_INTEGER;
+    const endBound = upperExclusive ? lowerBoundInLeaf(state, cursorLeaf, endKey, endSeq) : upperBoundInLeaf(state, cursorLeaf, endKey, endSeq);
+    const limit = endBound < leafCount ? endBound : leafCount;
+    appendLeafSlice(cursorLeaf, cursorIndex, limit, output, useIndexed, writeIdx);
+    return output;
+  }
+  return output;
+};
+
+// src/btree/serialization.ts
+var buildConfigFromState = (state) => {
+  const config = {
+    compareKeys: state.compareKeys,
+    duplicateKeys: state.duplicateKeys,
+    enableEntryIdLookup: state.entryKeys !== null,
+    autoScale: state.autoScale
+  };
+  if (!state.autoScale) {
+    config.maxLeafEntries = state.maxLeafEntries;
+    config.maxBranchChildren = state.maxBranchChildren;
+  }
+  return config;
+};
+var serializeToJSON = (state) => {
+  const entries = new Array(state.entryCount);
+  let leaf = state.leftmostLeaf;
+  let writeIdx = 0;
+  while (leaf !== null) {
+    const count = leafEntryCount(leaf);
+    for (let i = 0; i < count; i += 1) {
+      const e = leafEntryAt(leaf, i);
+      entries[writeIdx++] = [e.key, e.value];
+    }
+    leaf = leaf.next;
+  }
+  return {
+    version: 1,
+    config: {
+      maxLeafEntries: state.maxLeafEntries,
+      maxBranchChildren: state.maxBranchChildren,
+      duplicateKeys: state.duplicateKeys,
+      enableEntryIdLookup: state.entryKeys !== null,
+      autoScale: state.autoScale
+    },
+    entries
+  };
+};
+var MAX_SERIALIZED_ENTRIES = 1e6;
+var validateStructure = (json) => {
+  if (typeof json !== "object" || json === null || json.version !== 1) {
+    throw new BTreeValidationError(
+      `BTreeJSON: expected version 1, got ${String(json?.version)}.`
+    );
+  }
+  if (typeof json.config !== "object" || json.config === null) {
+    throw new BTreeValidationError("BTreeJSON: invalid config.");
+  }
+  if (!Array.isArray(json.entries)) {
+    throw new BTreeValidationError("BTreeJSON: entries must be array.");
+  }
+  if (json.entries.length > MAX_SERIALIZED_ENTRIES) {
+    throw new BTreeValidationError("BTreeJSON: entry count exceeds maximum.");
+  }
+  for (let i = 0; i < json.entries.length; i += 1) {
+    const entry = json.entries[i];
+    if (!Array.isArray(entry) || entry.length !== 2) {
+      throw new BTreeValidationError(`BTreeJSON: bad entries[${i}].`);
+    }
+  }
+};
+var validateConfig = (cfg) => {
+  const validateCapacity = (field, value) => {
+    if (!Number.isInteger(value) || value < MIN_NODE_CAPACITY || value > MAX_NODE_CAPACITY) {
+      throw new BTreeValidationError(`BTreeJSON: invalid ${field}.`);
+    }
+  };
+  if (cfg.duplicateKeys !== "allow" && cfg.duplicateKeys !== "reject" && cfg.duplicateKeys !== "replace") {
+    throw new BTreeValidationError(
+      `BTreeJSON: invalid duplicateKeys: ${String(cfg.duplicateKeys)}.`
+    );
+  }
+  if (typeof cfg.enableEntryIdLookup !== "boolean") {
+    throw new BTreeValidationError("BTreeJSON: invalid enableEntryIdLookup.");
+  }
+  if (typeof cfg.autoScale !== "boolean") {
+    throw new BTreeValidationError("BTreeJSON: invalid autoScale.");
+  }
+  if (typeof cfg.maxLeafEntries !== "number") {
+    throw new BTreeValidationError("BTreeJSON: invalid maxLeafEntries.");
+  }
+  if (typeof cfg.maxBranchChildren !== "number") {
+    throw new BTreeValidationError("BTreeJSON: invalid maxBranchChildren.");
+  }
+  validateCapacity("maxLeafEntries", cfg.maxLeafEntries);
+  validateCapacity("maxBranchChildren", cfg.maxBranchChildren);
+  if (cfg.autoScale) {
+    const tier0 = computeAutoScaleTier(0);
+    if (cfg.maxLeafEntries < tier0.maxLeaf || cfg.maxBranchChildren < tier0.maxBranch) {
+      throw new BTreeValidationError(
+        "BTreeJSON: autoScale capacity below tier-0."
+      );
+    }
+  }
+};
+var validateBTreeJSON = (json) => {
+  validateStructure(json);
+  validateConfig(json.config);
+};
+var buildConfigFromJSON = (json, compareKeys) => {
+  const cfg = json.config;
+  const config = {
+    compareKeys,
+    duplicateKeys: cfg.duplicateKeys,
+    enableEntryIdLookup: cfg.enableEntryIdLookup,
+    autoScale: cfg.autoScale
+  };
+  if (!cfg.autoScale) {
+    config.maxLeafEntries = cfg.maxLeafEntries;
+    config.maxBranchChildren = cfg.maxBranchChildren;
+  }
+  return config;
+};
+
+// src/btree/integrity-helpers.ts
+var nodeMinKey = (node) => {
+  if (isLeafNode(node)) {
+    if (node.entryOffset >= node.entries.length) return null;
+    const e = node.entries[node.entryOffset];
+    return { key: e.key, sequence: e.entryId };
+  }
+  if (node.childOffset >= node.keys.length) return null;
+  return { key: node.keys[node.childOffset].key, sequence: node.keys[node.childOffset].sequence };
+};
+var compareNodeKeys = (comparator, leftKey, leftSeq, rightKey, rightSeq) => {
+  const cmp = comparator(leftKey, rightKey);
+  if (cmp !== 0) {
+    return cmp;
+  }
+  return leftSeq - rightSeq;
+};
+var getNodeMaxKey = (node) => {
+  if (isLeafNode(node)) {
+    if (node.entryOffset >= node.entries.length) return null;
+    const e = node.entries[node.entries.length - 1];
+    return { key: e.key, sequence: e.entryId };
+  }
+  if (node.childOffset >= node.children.length) {
+    return null;
+  }
+  return getNodeMaxKey(node.children[node.children.length - 1]);
+};
+var validateComparatorResult = (result) => {
+  if (!Number.isFinite(result)) {
+    throw new BTreeValidationError(
+      "compareKeys must return a finite number."
+    );
+  }
+  return result;
+};
+var assertComparatorReflexivity = (comparator, key) => {
+  const selfCompared = validateComparatorResult(comparator(key, key));
+  if (selfCompared !== 0) {
+    throw new BTreeValidationError(
+      "compareKeys must satisfy reflexivity: compare(x, x) must return 0."
+    );
+  }
+};
+var assertComparatorTransitivity = (comparator, first, second, third) => {
+  const firstToSecond = Math.sign(
+    validateComparatorResult(comparator(first, second))
+  );
+  const secondToThird = Math.sign(
+    validateComparatorResult(comparator(second, third))
+  );
+  if (firstToSecond < 0 && secondToThird < 0) {
+    const firstToThird = Math.sign(
+      validateComparatorResult(comparator(first, third))
+    );
+    if (firstToThird >= 0) {
+      throw new BTreeValidationError(
+        "compareKeys must satisfy transitivity for observed key triples."
+      );
+    }
+  }
+  if (firstToSecond > 0 && secondToThird > 0) {
+    const firstToThird = Math.sign(
+      validateComparatorResult(comparator(first, third))
+    );
+    if (firstToThird <= 0) {
+      throw new BTreeValidationError(
+        "compareKeys must satisfy transitivity for observed key triples."
+      );
+    }
+  }
+};
+var assertReflexivityAsInvariant = (state, key) => {
+  try {
+    assertComparatorReflexivity(state.compareKeys, key);
+  } catch (error) {
+    if (error instanceof BTreeValidationError) {
+      throw new BTreeInvariantError(error.message);
+    }
+    throw error;
+  }
+};
+var assertTransitivityAsInvariant = (state, first, second, third) => {
+  try {
+    assertComparatorTransitivity(state.compareKeys, first, second, third);
+  } catch (error) {
+    if (error instanceof BTreeValidationError) {
+      throw new BTreeInvariantError(error.message);
+    }
+    throw error;
+  }
+};
+var validateLeafChainStep = (state, cursor, previous, visited) => {
+  if (!isLeafNode(cursor)) {
+    throw new BTreeInvariantError("Leaf linkage cursor reached non-leaf node.");
+  }
+  if (visited.has(cursor)) {
+    throw new BTreeInvariantError("Cycle detected in leaf linkage.");
+  }
+  if (cursor.prev !== previous) {
+    throw new BTreeInvariantError("Leaf prev pointer mismatch.");
+  }
+  if (previous !== null && isLeafNode(previous)) {
+    const prevMax = getNodeMaxKey(previous);
+    const currentMin = nodeMinKey(cursor);
+    if (prevMax === null || currentMin === null) {
+      throw new BTreeInvariantError("Non-empty tree leaf chain contains empty leaf node.");
+    }
+    if (compareNodeKeys(state.compareKeys, prevMax.key, prevMax.sequence, currentMin.key, currentMin.sequence) > 0) {
+      throw new BTreeInvariantError("Adjacent leaf key ranges are out of order.");
+    }
+    const prevCount = leafEntryCount(previous);
+    const curCount = leafEntryCount(cursor);
+    if (state.duplicateKeys !== "allow" && prevCount > 0 && curCount > 0 && state.compareKeys(
+      leafEntryAt(previous, prevCount - 1).key,
+      leafEntryAt(cursor, 0).key
+    ) === 0) {
+      throw new BTreeInvariantError("Duplicate user key detected across adjacent leaves with uniqueness policy.");
+    }
+  }
+};
+var validateLeafLinks = (state, expectedLeafCount) => {
+  if (state.entryCount === 0) {
+    if (!isLeafNode(state.root)) {
+      throw new BTreeInvariantError("Empty tree root must be a leaf node.");
+    }
+    if (state.leftmostLeaf !== state.root || state.rightmostLeaf !== state.root) {
+      throw new BTreeInvariantError("Empty tree leaf pointers must reference root leaf.");
+    }
+    return;
+  }
+  if (state.leftmostLeaf.prev !== null) {
+    throw new BTreeInvariantError("Leftmost leaf prev pointer must be null.");
+  }
+  if (state.rightmostLeaf.next !== null) {
+    throw new BTreeInvariantError("Rightmost leaf next pointer must be null.");
+  }
+  const visited = /* @__PURE__ */ new Set();
+  let cursor = state.leftmostLeaf;
+  let previous = null;
+  let leafCount = 0;
+  while (cursor !== null) {
+    validateLeafChainStep(state, cursor, previous, visited);
+    visited.add(cursor);
+    previous = cursor;
+    cursor = cursor.next;
+    leafCount += 1;
+  }
+  if (previous !== state.rightmostLeaf) {
+    throw new BTreeInvariantError("Rightmost leaf pointer mismatch.");
+  }
+  if (leafCount !== expectedLeafCount) {
+    throw new BTreeInvariantError("Leaf chain count mismatch with tree traversal count.");
+  }
+};
+
+// src/btree/integrity.ts
+var validateLeafNodeOrdering = (state, node) => {
+  const count = leafEntryCount(node);
+  for (let i = 0; i < count; i += 1) {
+    assertReflexivityAsInvariant(state, leafEntryAt(node, i).key);
+  }
+  for (let index = 1; index < count; index += 1) {
+    if (compareNodeKeys(
+      state.compareKeys,
+      leafEntryAt(node, index - 1).key,
+      leafEntryAt(node, index - 1).entryId,
+      leafEntryAt(node, index).key,
+      leafEntryAt(node, index).entryId
+    ) >= 0) {
+      throw new BTreeInvariantError("Leaf entries are not strictly ordered.");
+    }
+  }
+  if (state.duplicateKeys !== "allow") {
+    for (let index = 1; index < count; index += 1) {
+      if (state.compareKeys(
+        leafEntryAt(node, index - 1).key,
+        leafEntryAt(node, index).key
+      ) === 0) {
+        throw new BTreeInvariantError("Duplicate user key detected in tree with uniqueness policy.");
+      }
+    }
+  }
+  for (let index = 2; index < count; index += 1) {
+    const first = leafEntryAt(node, index - 2);
+    const second = leafEntryAt(node, index - 1);
+    const third = leafEntryAt(node, index);
+    assertTransitivityAsInvariant(
+      state,
+      first.key,
+      second.key,
+      third.key
+    );
+  }
+  if (count > state.maxLeafEntries) {
+    throw new BTreeInvariantError("Leaf node exceeds maximum occupancy.");
+  }
+};
+var validateLeafNode = (state, node, depth) => {
+  validateLeafNodeOrdering(state, node);
+  const count = leafEntryCount(node);
+  const baseMinLeaf = state.autoScale ? Math.ceil(computeAutoScaleTier(0).maxLeaf / 2) : state.minLeafEntries;
+  if (node !== state.root && count < baseMinLeaf) {
+    throw new BTreeInvariantError("Non-root leaf node violates minimum occupancy.");
+  }
+  const first = count === 0 ? null : leafEntryAt(node, 0);
+  const last = count === 0 ? null : leafEntryAt(node, count - 1);
+  const minKey = first === null ? null : { key: first.key, sequence: first.entryId };
+  const maxKey = last === null ? null : { key: last.key, sequence: last.entryId };
+  return {
+    minKey,
+    maxKey,
+    leafDepth: count === 0 ? null : depth,
+    leafCount: 1,
+    branchCount: 0,
+    entryCount: count
+  };
+};
+var validateBranchStructure = (state, node) => {
+  const liveCount = node.children.length - node.childOffset;
+  if (liveCount === 0) {
+    throw new BTreeInvariantError("Branch node has zero children.");
+  }
+  const baseMinBranch = state.autoScale ? Math.ceil(computeAutoScaleTier(0).maxBranch / 2) : state.minBranchChildren;
+  if (node !== state.root && liveCount < baseMinBranch) {
+    throw new BTreeInvariantError("Non-root branch node violates minimum occupancy.");
+  }
+  if (liveCount > state.maxBranchChildren) {
+    throw new BTreeInvariantError("Branch node exceeds maximum occupancy.");
+  }
+  if (node.keys.length !== node.children.length) {
+    throw new BTreeInvariantError("Branch keys array length does not match children array length.");
+  }
+};
+var validateBranchChild = (state, node, childIndex, depth) => {
+  const child = node.children[childIndex];
+  if (child.parent !== node) {
+    throw new BTreeInvariantError("Child-parent pointer mismatch in branch node.");
+  }
+  if (child.indexInParent !== childIndex) {
+    throw new BTreeInvariantError("Child indexInParent does not match actual position in parent.");
+  }
+  const childValidation = validateNode(state, child, depth + 1);
+  if (childValidation.minKey === null || childValidation.maxKey === null) {
+    throw new BTreeInvariantError("Branch child must not be empty in non-root branch tree.");
+  }
+  const cachedMinKey = node.keys[childIndex];
+  const actualMinKey = nodeMinKey(child);
+  if (actualMinKey === null || compareNodeKeys(state.compareKeys, cachedMinKey.key, cachedMinKey.sequence, actualMinKey.key, actualMinKey.sequence) !== 0) {
+    throw new BTreeInvariantError("Branch cached key does not match actual child minimum key.");
+  }
+  return childValidation;
+};
+var validateNode = (state, node, depth) => {
+  if (isLeafNode(node)) {
+    return validateLeafNode(state, node, depth);
+  }
+  validateBranchStructure(state, node);
+  let leafDepth = null;
+  let leafCount = 0;
+  let branchCount = 1;
+  let entryCount = 0;
+  let minKey = null;
+  let maxKey = null;
+  let previousChildMax = null;
+  for (let childIndex = node.childOffset; childIndex < node.children.length; childIndex += 1) {
+    const childValidation = validateBranchChild(state, node, childIndex, depth);
+    if (leafDepth !== null && childValidation.leafDepth !== null && childValidation.leafDepth !== leafDepth) {
+      throw new BTreeInvariantError("Leaf depth mismatch detected in tree.");
+    }
+    if (leafDepth === null && childValidation.leafDepth !== null) {
+      leafDepth = childValidation.leafDepth;
+    }
+    if (previousChildMax !== null && compareNodeKeys(
+      state.compareKeys,
+      previousChildMax.key,
+      previousChildMax.sequence,
+      childValidation.minKey.key,
+      childValidation.minKey.sequence
+    ) >= 0) {
+      throw new BTreeInvariantError("Branch child key ranges are not strictly ordered.");
+    }
+    if (minKey === null) minKey = childValidation.minKey;
+    maxKey = childValidation.maxKey;
+    previousChildMax = childValidation.maxKey;
+    leafCount += childValidation.leafCount;
+    branchCount += childValidation.branchCount;
+    entryCount += childValidation.entryCount;
+  }
+  return { minKey, maxKey, leafDepth, leafCount, branchCount, entryCount };
+};
+var assertInvariants = (state) => {
+  const validation = validateNode(state, state.root, 0);
+  if (validation.entryCount !== state.entryCount) {
+    throw new BTreeInvariantError("Index entry count mismatch between tree traversal and tracked state.");
+  }
+  validateLeafLinks(state, validation.leafCount);
+};
+
+// src/btree/stats.ts
+var collectStats = (node) => {
+  if (isLeafNode(node)) {
+    return {
+      height: 1,
+      leafCount: 1,
+      branchCount: 0
+    };
+  }
+  let maxChildHeight = 0;
+  let leafCount = 0;
+  let branchCount = 1;
+  for (let ci = node.childOffset; ci < node.children.length; ci += 1) {
+    const child = node.children[ci];
+    const childStats = collectStats(child);
+    if (childStats.height > maxChildHeight) {
+      maxChildHeight = childStats.height;
+    }
+    leafCount += childStats.leafCount;
+    branchCount += childStats.branchCount;
+  }
+  return {
+    height: maxChildHeight + 1,
+    leafCount,
+    branchCount
+  };
+};
+var getStats = (state) => {
+  const stats = collectStats(state.root);
+  return {
+    height: stats.height,
+    leafCount: stats.leafCount,
+    branchCount: stats.branchCount,
+    entryCount: state.entryCount
+  };
+};
+
+// src/InMemoryBTree.ts
+var InMemoryBTree = class _InMemoryBTree {
+  constructor(config) {
+    this.state = createInitialState(config);
+  }
+  put(key, value) {
+    return putEntry(this.state, key, value);
+  }
+  putMany(entries) {
+    return putManyEntries(this.state, entries);
+  }
+  remove(key) {
+    return removeFirstMatchingEntry(this.state, key);
+  }
+  removeById(entryId) {
+    if (this.state.entryKeys === null) {
+      throw new BTreeValidationError("Requires enableEntryIdLookup: true.");
+    }
+    return removeEntryById(this.state, entryId);
+  }
+  peekById(entryId) {
+    if (this.state.entryKeys === null) {
+      throw new BTreeValidationError("Requires enableEntryIdLookup: true.");
+    }
+    return peekEntryById(this.state, entryId);
+  }
+  updateById(entryId, value) {
+    if (this.state.entryKeys === null) {
+      throw new BTreeValidationError("Requires enableEntryIdLookup: true.");
+    }
+    return updateEntryById(this.state, entryId, value);
+  }
+  popFirst() {
+    return popFirstEntry(this.state);
+  }
+  peekFirst() {
+    if (this.state.entryCount === 0) {
+      return null;
+    }
+    return leafEntryAt(this.state.leftmostLeaf, 0);
+  }
+  peekLast() {
+    if (this.state.entryCount === 0) {
+      return null;
+    }
+    const leaf = this.state.rightmostLeaf;
+    return leafEntryAt(leaf, leafEntryCount(leaf) - 1);
+  }
+  popLast() {
+    return popLastEntry(this.state);
+  }
+  clear() {
+    const emptyLeaf = createLeafNode([], null);
+    this.state.root = emptyLeaf;
+    this.state.leftmostLeaf = emptyLeaf;
+    this.state.rightmostLeaf = emptyLeaf;
+    this.state.entryCount = 0;
+    this.state._cursor.leaf = emptyLeaf;
+    this.state._cursor.index = 0;
+    if (this.state.entryKeys !== null) {
+      this.state.entryKeys.clear();
+    }
+    if (this.state.autoScale) {
+      const tier = computeAutoScaleTier(0);
+      this.state.maxLeafEntries = tier.maxLeaf;
+      this.state.maxBranchChildren = tier.maxBranch;
+      this.state.minLeafEntries = Math.ceil(tier.maxLeaf / 2);
+      this.state.minBranchChildren = Math.ceil(tier.maxBranch / 2);
+      this.state._nextAutoScaleThreshold = computeNextAutoScaleThreshold(0);
+    }
+  }
+  get(key) {
+    const found = findFirstMatchingUserKey(this.state, key);
+    if (found === null) return null;
+    return leafEntryAt(found.leaf, found.index).value;
+  }
+  hasKey(key) {
+    return hasKeyEntry(this.state, key);
+  }
+  findFirst(key) {
+    const found = findFirstMatchingUserKey(this.state, key);
+    if (found === null) return null;
+    return leafEntryAt(found.leaf, found.index);
+  }
+  findLast(key) {
+    const found = findLastMatchingUserKey(this.state, key);
+    if (found === null) return null;
+    return leafEntryAt(found.leaf, found.index);
+  }
+  nextHigherKey(key) {
+    return findNextHigherKey(this.state, key);
+  }
+  nextLowerKey(key) {
+    return findNextLowerKey(this.state, key);
+  }
+  getPairOrNextLower(key) {
+    const found = findPairOrNextLower(this.state, key);
+    if (found === null) return null;
+    return leafEntryAt(found.leaf, found.index);
+  }
+  count(startKey, endKey, options) {
+    return countRangeEntries(this.state, startKey, endKey, options);
+  }
+  deleteRange(startKey, endKey, options) {
+    return deleteRangeEntries(this.state, startKey, endKey, options);
+  }
+  range(startKey, endKey, options) {
+    return rangeQueryEntries(this.state, startKey, endKey, options);
+  }
+  *entries() {
+    let leaf = this.state.leftmostLeaf;
+    while (leaf !== null) {
+      const count = leafEntryCount(leaf);
+      for (let i = 0; i < count; i += 1) {
+        yield leafEntryAt(leaf, i);
+      }
+      leaf = leaf.next;
+    }
+  }
+  *entriesReversed() {
+    let leaf = this.state.rightmostLeaf;
+    while (leaf !== null) {
+      const count = leafEntryCount(leaf);
+      for (let i = count - 1; i >= 0; i -= 1) {
+        yield leafEntryAt(leaf, i);
+      }
+      leaf = leaf.prev;
+    }
+  }
+  *keys() {
+    let leaf = this.state.leftmostLeaf;
+    while (leaf !== null) {
+      const count = leafEntryCount(leaf);
+      for (let i = 0; i < count; i += 1) {
+        yield leafEntryAt(leaf, i).key;
+      }
+      leaf = leaf.next;
+    }
+  }
+  *values() {
+    let leaf = this.state.leftmostLeaf;
+    while (leaf !== null) {
+      const count = leafEntryCount(leaf);
+      for (let i = 0; i < count; i += 1) {
+        yield leafEntryAt(leaf, i).value;
+      }
+      leaf = leaf.next;
+    }
+  }
+  [Symbol.iterator]() {
+    return this.entries();
+  }
+  forEach(callback, thisArg) {
+    let leaf = this.state.leftmostLeaf;
+    while (leaf !== null) {
+      const count = leafEntryCount(leaf);
+      for (let i = 0; i < count; i += 1) {
+        callback.call(thisArg, leafEntryAt(leaf, i));
+      }
+      leaf = leaf.next;
+    }
+  }
+  snapshot() {
+    const result = new Array(this.state.entryCount);
+    let leaf = this.state.leftmostLeaf;
+    let writeIdx = 0;
+    while (leaf !== null) {
+      const count = leafEntryCount(leaf);
+      for (let i = 0; i < count; i += 1) {
+        result[writeIdx++] = leafEntryAt(leaf, i);
+      }
+      leaf = leaf.next;
+    }
+    return result;
+  }
+  clone() {
+    const cloned = new _InMemoryBTree(buildConfigFromState(this.state));
+    applyAutoScaleCapacitySnapshot(
+      cloned.state,
+      this.state.maxLeafEntries,
+      this.state.maxBranchChildren
+    );
+    if (this.state.entryCount > 0) {
+      const pairs = new Array(this.state.entryCount);
+      let leaf = this.state.leftmostLeaf;
+      let writeIdx = 0;
+      while (leaf !== null) {
+        const count = leafEntryCount(leaf);
+        for (let i = 0; i < count; i += 1) {
+          pairs[writeIdx++] = leafEntryAt(leaf, i);
+        }
+        leaf = leaf.next;
+      }
+      cloned.putMany(pairs);
+    }
+    return cloned;
+  }
+  toJSON() {
+    return serializeToJSON(this.state);
+  }
+  static fromJSON(json, compareKeys) {
+    validateBTreeJSON(json);
+    const strict = json.config.duplicateKeys !== "allow";
+    for (let i = 1; i < json.entries.length; i += 1) {
+      const cmp = compareKeys(json.entries[i - 1][0], json.entries[i][0]);
+      if (cmp > 0) {
+        throw new BTreeValidationError("fromJSON: entries not sorted.");
+      }
+      if (strict && cmp === 0) {
+        throw new BTreeValidationError(
+          'fromJSON: duplicate keys require duplicateKeys "allow".'
+        );
+      }
+    }
+    const tree = new _InMemoryBTree(buildConfigFromJSON(json, compareKeys));
+    applyAutoScaleCapacitySnapshot(
+      tree.state,
+      json.config.maxLeafEntries,
+      json.config.maxBranchChildren
+    );
+    if (json.entries.length > 0) {
+      const pairs = new Array(json.entries.length);
+      for (let i = 0; i < json.entries.length; i += 1) {
+        pairs[i] = { key: json.entries[i][0], value: json.entries[i][1] };
+      }
+      tree.putMany(pairs);
+    }
+    return tree;
+  }
+  size() {
+    return this.state.entryCount;
+  }
+  assertInvariants() {
+    assertInvariants(this.state);
+  }
+  getStats() {
+    return getStats(this.state);
+  }
+};
+
+// src/concurrency/helpers.ts
+var DEFAULT_MAX_RETRIES = 16;
+var MAX_RETRIES_LIMIT = 1024;
+var DEFAULT_MAX_SYNC_MUTATIONS_PER_BATCH = 1e5;
+var MAX_SYNC_MUTATIONS_PER_BATCH_LIMIT = 1e6;
+var computeConfigFingerprint = (config) => {
+  const isAutoScale = config.autoScale === true;
+  const tier0 = isAutoScale ? computeAutoScaleTier(0) : void 0;
+  return JSON.stringify({
+    duplicateKeys: config.duplicateKeys ?? "replace",
+    maxLeafEntries: config.maxLeafEntries ?? (tier0 ? tier0.maxLeaf : DEFAULT_MAX_LEAF_ENTRIES),
+    maxBranchChildren: config.maxBranchChildren ?? (tier0 ? tier0.maxBranch : DEFAULT_MAX_BRANCH_CHILDREN),
+    enableEntryIdLookup: config.enableEntryIdLookup === true,
+    autoScale: isAutoScale
+  });
+};
+var assertNeverMutation = (mutation) => {
+  const unknownMutation = mutation;
+  throw new BTreeConcurrencyError(
+    `Unsupported mutation type from shared store: ${String(unknownMutation.type)}`
+  );
+};
+var normalizeMaxRetries = (value) => {
+  if (value === void 0) {
+    return DEFAULT_MAX_RETRIES;
+  }
+  if (!Number.isInteger(value) || value < 1 || value > MAX_RETRIES_LIMIT) {
+    throw new BTreeConcurrencyError(
+      `maxRetries: integer 1\u2013${MAX_RETRIES_LIMIT} required.`
+    );
+  }
+  return value;
+};
+var normalizeMaxSyncMutationsPerBatch = (value) => {
+  if (value === void 0) {
+    return DEFAULT_MAX_SYNC_MUTATIONS_PER_BATCH;
+  }
+  if (!Number.isInteger(value) || value < 1 || value > MAX_SYNC_MUTATIONS_PER_BATCH_LIMIT) {
+    throw new BTreeConcurrencyError(
+      `maxSyncMutationsPerBatch: integer 1\u2013${MAX_SYNC_MUTATIONS_PER_BATCH_LIMIT} required.`
+    );
+  }
+  return value;
+};
+var normalizeReadMode = (value) => {
+  if (value === void 0) {
+    return "strong";
+  }
+  if (value !== "strong" && value !== "local") {
+    throw new BTreeConcurrencyError(
+      `readMode: must be 'strong' or 'local'.`
+    );
+  }
+  return value;
+};
+function assertAppendVersionContract(expectedVersion, appendResult) {
+  if (typeof appendResult !== "object" || appendResult === null) {
+    throw new BTreeConcurrencyError(
+      "Store contract: append() must return {applied, version}."
+    );
+  }
+  const candidate = appendResult;
+  if (typeof candidate.applied !== "boolean") {
+    throw new BTreeConcurrencyError("Store contract: applied must be boolean.");
+  }
+  if (typeof candidate.version !== "bigint") {
+    throw new BTreeConcurrencyError("Store contract: version must be bigint.");
+  }
+  if (candidate.applied && candidate.version <= expectedVersion) {
+    throw new BTreeConcurrencyError(
+      "Store contract: applied version must exceed expected."
+    );
+  }
+  if (!candidate.applied && candidate.version < expectedVersion) {
+    throw new BTreeConcurrencyError(
+      "Store contract: rejected version must be >= expected."
+    );
+  }
+}
+
+// src/concurrency/ConcurrentInMemoryBTree.ts
+var ConcurrentInMemoryBTree = class {
+  constructor(config) {
+    this.store = config.store;
+    this.maxRetries = normalizeMaxRetries(config.maxRetries);
+    this.maxSyncMutationsPerBatch = normalizeMaxSyncMutationsPerBatch(
+      config.maxSyncMutationsPerBatch
+    );
+    this.duplicateKeys = config.duplicateKeys ?? "replace";
+    this.readMode = normalizeReadMode(config.readMode);
+    this.configFingerprint = computeConfigFingerprint(config);
+    this.tree = new InMemoryBTree({
+      compareKeys: config.compareKeys,
+      maxLeafEntries: config.maxLeafEntries,
+      maxBranchChildren: config.maxBranchChildren,
+      duplicateKeys: config.duplicateKeys,
+      enableEntryIdLookup: config.enableEntryIdLookup,
+      autoScale: config.autoScale
+    });
+    this.currentVersion = 0n;
+    this.operationQueue = Promise.resolve();
+    this.initSeen = false;
+  }
+  async sync() {
+    await this.runExclusive(async () => {
+      await this.syncUnlocked();
+    });
+  }
+  async syncUnlocked() {
+    const log = await this.store.getLogEntriesSince(this.currentVersion);
+    if (typeof log.version !== "bigint") {
+      throw new BTreeConcurrencyError("Store contract: version must be bigint.");
+    }
+    if (!Array.isArray(log.mutations)) {
+      throw new BTreeConcurrencyError("Store contract: mutations must be an array.");
+    }
+    if (log.mutations.length > this.maxSyncMutationsPerBatch) {
+      throw new BTreeConcurrencyError(
+        `Sync batch exceeded limit (${String(this.maxSyncMutationsPerBatch)}).`
+      );
+    }
+    if (log.version <= this.currentVersion) {
+      return;
+    }
+    for (const mutation of log.mutations) {
+      this.applyMutationLocal(mutation);
+    }
+    this.currentVersion = log.version;
+  }
+  applyMutationLocal(mutation) {
+    switch (mutation.type) {
+      case "init":
+        if (mutation.configFingerprint !== this.configFingerprint) {
+          throw new BTreeConcurrencyError(
+            "Config mismatch: store peers must share identical tree config."
+          );
+        }
+        this.initSeen = true;
+        return null;
+      case "put":
+        return this.tree.put(mutation.key, mutation.value);
+      case "remove":
+        return this.tree.remove(mutation.key);
+      case "removeById":
+        return this.tree.removeById(mutation.entryId);
+      case "updateById":
+        return this.tree.updateById(mutation.entryId, mutation.value);
+      case "popFirst":
+        return this.tree.popFirst();
+      case "popLast":
+        return this.tree.popLast();
+      default:
+        return assertNeverMutation(mutation);
+    }
+  }
+  runExclusive(operation) {
+    const run = async () => operation();
+    const result = this.operationQueue.then(run, run);
+    this.operationQueue = result.then(
+      () => void 0,
+      () => void 0
+    );
+    return result;
+  }
+  readOp(fn) {
+    return this.runExclusive(async () => {
+      if (this.readMode === "strong") {
+        await this.syncUnlocked();
+      }
+      return fn(this.tree);
+    });
+  }
+  async appendMutationAndApplyUnlocked(evaluate) {
+    for (let attempt = 0; attempt < this.maxRetries; attempt += 1) {
+      await this.syncUnlocked();
+      const mutation = evaluate(this.tree);
+      if (mutation === null) {
+        return null;
+      }
+      const expectedVersion = this.currentVersion;
+      const mutations = this.initSeen ? [mutation] : [{ type: "init", configFingerprint: this.configFingerprint }, mutation];
+      const appendResult = await this.store.append(expectedVersion, mutations);
+      assertAppendVersionContract(expectedVersion, appendResult);
+      if (appendResult.applied) {
+        for (const m of mutations) {
+          if (m === mutation) break;
+          this.applyMutationLocal(m);
+        }
+        const localResult = this.applyMutationLocal(mutation);
+        this.currentVersion = appendResult.version;
+        return localResult;
+      }
+    }
+    throw new BTreeConcurrencyError(
+      `Mutation failed after ${String(this.maxRetries)} retries.`
+    );
+  }
+  async put(key, value) {
+    return this.runExclusive(async () => {
+      return this.appendMutationAndApplyUnlocked(
+        (tree) => {
+          if (this.duplicateKeys === "reject" && tree.hasKey(key)) {
+            throw new BTreeValidationError("Duplicate key rejected.");
+          }
+          return { type: "put", key, value };
+        }
+      );
+    });
+  }
+  async remove(key) {
+    return this.runExclusive(async () => {
+      return this.appendMutationAndApplyUnlocked(
+        (tree) => {
+          return tree.hasKey(key) ? { type: "remove", key } : null;
+        }
+      );
+    });
+  }
+  async removeById(entryId) {
+    return this.runExclusive(async () => {
+      return this.appendMutationAndApplyUnlocked(
+        (tree) => {
+          return tree.peekById(entryId) !== null ? { type: "removeById", entryId } : null;
+        }
+      );
+    });
+  }
+  async updateById(entryId, value) {
+    return this.runExclusive(async () => {
+      return this.appendMutationAndApplyUnlocked(
+        (tree) => {
+          return tree.peekById(entryId) !== null ? { type: "updateById", entryId, value } : null;
+        }
+      );
+    });
+  }
+  async popFirst() {
+    return this.runExclusive(async () => {
+      return this.appendMutationAndApplyUnlocked((tree) => {
+        return tree.peekFirst() !== null ? { type: "popFirst" } : null;
+      });
+    });
+  }
+  async get(key) {
+    return this.readOp((tree) => tree.get(key));
+  }
+  async hasKey(key) {
+    return this.readOp((tree) => tree.hasKey(key));
+  }
+  async findFirst(key) {
+    return this.readOp((tree) => tree.findFirst(key));
+  }
+  async findLast(key) {
+    return this.readOp((tree) => tree.findLast(key));
+  }
+  async range(startKey, endKey, options) {
+    return this.readOp((tree) => tree.range(startKey, endKey, options));
+  }
+  async snapshot() {
+    return this.readOp((tree) => tree.snapshot());
+  }
+  async size() {
+    return this.readOp((tree) => tree.size());
+  }
+  async assertInvariants() {
+    await this.readOp((tree) => tree.assertInvariants());
+  }
+  async getStats() {
+    return this.readOp((tree) => tree.getStats());
+  }
+  async peekFirst() {
+    return this.readOp((tree) => tree.peekFirst());
+  }
+  async peekLast() {
+    return this.readOp((tree) => tree.peekLast());
+  }
+  async popLast() {
+    return this.runExclusive(async () => {
+      return this.appendMutationAndApplyUnlocked((tree) => {
+        return tree.peekLast() !== null ? { type: "popLast" } : null;
+      });
+    });
+  }
+  async peekById(entryId) {
+    return this.readOp((tree) => tree.peekById(entryId));
+  }
+  async count(startKey, endKey, options) {
+    return this.readOp((tree) => tree.count(startKey, endKey, options));
+  }
+  async nextHigherKey(key) {
+    return this.readOp((tree) => tree.nextHigherKey(key));
+  }
+  async nextLowerKey(key) {
+    return this.readOp((tree) => tree.nextLowerKey(key));
+  }
+  async getPairOrNextLower(key) {
+    return this.readOp((tree) => tree.getPairOrNextLower(key));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BTreeConcurrencyError,
+  BTreeInvariantError,
+  BTreeValidationError,
+  ConcurrentInMemoryBTree,
+  InMemoryBTree
+});