@frostpillar/frostpillar-btree 0.2.4 → 0.2.6

package/dist/core.cjs

@@ -42,54 +42,10 @@ var BTreeInvariantError = class extends Error {
   }
 };
 
-// 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;
-};
+// src/btree/node-ops.ts
 var createLeafNode = (entries, parent) => {
   return {
-    kind: NODE_LEAF,
+    kind: 0,
     entries,
     entryOffset: 0,
     parent,
@@ -101,7 +57,7 @@ var createLeafNode = (entries, parent) => {
 var createBranchNode = (children, parent) => {
   const keys = [];
   const branch = {
-    kind: NODE_BRANCH,
+    kind: 1,
     children,
     keys,
     childOffset: 0,
@@ -240,6 +196,56 @@ var branchRemoveAt = (branch, physIndex) => {
   }
 };
 
+// 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 normalizeDuplicateKeyPolicy = (value) => {
+  if (value === void 0) {
+    return "replace";
+  }
+  if (value !== "allow" && value !== "reject" && value !== "replace") {
+    throw new BTreeValidationError(
+      `Invalid duplicateKeys option.`
+    );
+  }
+  return value;
+};
+var toPublicEntry = (entry) => ({
+  entryId: entry.entryId,
+  key: entry.key,
+  value: entry.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;
+};
+
 // src/btree/navigation.ts
 var selectBranchChild = (compare, branch, userKey, sequence) => {
   const off = branch.childOffset;
@@ -253,7 +259,7 @@ var selectBranchChild = (compare, branch, userKey, sequence) => {
     const mid = lower + upper >>> 1;
     const k = branch.keys[mid];
     const cmp = compare(k.key, userKey);
-    if ((cmp !== 0 ? cmp : k.sequence - sequence) <= 0) {
+    if ((cmp !== 0 ? cmp : k.sequence < sequence ? -1 : k.sequence > sequence ? 1 : 0) <= 0) {
       selectedIndex = mid;
       lower = mid + 1;
     } else {
@@ -278,7 +284,7 @@ var lowerBoundInLeaf = (state, leaf, userKey, sequence) => {
     const mid = lower + upper >>> 1;
     const e = leaf.entries[mid];
     const cmp = compare(e.key, userKey);
-    if ((cmp !== 0 ? cmp : e.entryId - sequence) < 0) {
+    if ((cmp !== 0 ? cmp : e.entryId < sequence ? -1 : e.entryId > sequence ? 1 : 0) < 0) {
       lower = mid + 1;
     } else {
       upper = mid;
@@ -294,7 +300,7 @@ var upperBoundInLeaf = (state, leaf, userKey, sequence) => {
     const mid = lower + upper >>> 1;
     const e = leaf.entries[mid];
     const cmp = compare(e.key, userKey);
-    if ((cmp !== 0 ? cmp : e.entryId - sequence) <= 0) {
+    if ((cmp !== 0 ? cmp : e.entryId < sequence ? -1 : e.entryId > sequence ? 1 : 0) <= 0) {
       lower = mid + 1;
     } else {
       upper = mid;
@@ -431,6 +437,114 @@ var findPairOrNextLower = (state, key) => {
   return null;
 };
 
+// src/btree/rangeQuery.ts
+function isEmptyRange(compare, startKey, endKey, options) {
+  const cmp = compare(startKey, endKey);
+  if (cmp > 0) return true;
+  const lowerExclusive = options?.lowerBound === "exclusive";
+  const upperExclusive = options?.upperBound === "exclusive";
+  return lowerExclusive && upperExclusive && cmp === 0;
+}
+var initRangeCursor = (state, startKey, endKey, options) => {
+  if (state.entryCount === 0) return null;
+  const compare = state.compareKeys;
+  if (isEmptyRange(compare, startKey, endKey, options)) return null;
+  const lowerExclusive = options?.lowerBound === "exclusive";
+  const upperExclusive = options?.upperBound === "exclusive";
+  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/rebalance.ts
 var updateMinKeyInAncestors = (node) => {
   let current = node;
@@ -656,16 +770,7 @@ var findRemoveEnd = (state, leaf, idx, endKey, upperExclusive) => {
   }
   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) => {
+var spliceLeafAndRebalance = (state, leaf, idx, removeCount) => {
   if (state.entryKeys !== null) {
     for (let i = idx; i < idx + removeCount; i += 1) {
       state.entryKeys.delete(leafEntryAt(leaf, i).entryId);
@@ -680,11 +785,11 @@ var spliceLeafAndRebalance = (state, leaf, idx, removeCount, maxRebalanceDepth)
     updateMinKeyInAncestors(leaf);
   }
   const countAfterSplice = leafEntryCount(leaf);
-  let maxIter = maxRebalanceDepth;
-  while (maxIter > 0 && leaf !== state.root && leafEntryCount(leaf) < state.minLeafEntries) {
+  let safetyGuard = state.minLeafEntries + 4;
+  while (safetyGuard > 0 && leaf !== state.root && leafEntryCount(leaf) < state.minLeafEntries) {
     rebalanceAfterLeafRemoval(state, leaf);
     if (leaf.parent !== null && leaf.parent.children[leaf.indexInParent] !== leaf) break;
-    maxIter -= 1;
+    safetyGuard -= 1;
   }
   if (leafEmptied && leafEntryCount(leaf) > 0 && leaf.parent !== null && leaf.parent.children[leaf.indexInParent] === leaf) {
     updateMinKeyInAncestors(leaf);
@@ -694,12 +799,9 @@ var spliceLeafAndRebalance = (state, leaf, idx, removeCount, maxRebalanceDepth)
 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;
+  if (isEmptyRange(state.compareKeys, startKey, endKey, options)) 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;
@@ -717,7 +819,7 @@ var deleteRangeEntries = (state, startKey, endKey, options) => {
     const removeEnd = findRemoveEnd(state, leaf, idx, endKey, upperExclusive);
     const removeCount = removeEnd - idx;
     if (removeCount === 0) break;
-    const countAfterSplice = spliceLeafAndRebalance(state, leaf, idx, removeCount, treeHeight);
+    const countAfterSplice = spliceLeafAndRebalance(state, leaf, idx, removeCount);
     deleted += removeCount;
     if (removeEnd < count) break;
     if (!isLeafStillValid(state, leaf)) {
@@ -736,6 +838,7 @@ var deleteRangeEntries = (state, startKey, endKey, options) => {
 };
 
 // src/btree/autoScale.ts
+var minOccupancy = (max) => Math.ceil(max / 2);
 var AUTO_SCALE_TIERS = [
   { threshold: 0, maxLeaf: 32, maxBranch: 32 },
   { threshold: 1e3, maxLeaf: 64, maxBranch: 64 },
@@ -787,8 +890,8 @@ var createInitialState = (config) => {
     maxLeafEntries,
     maxBranchChildren,
     duplicateKeys,
-    minLeafEntries: Math.ceil(maxLeafEntries / 2),
-    minBranchChildren: Math.ceil(maxBranchChildren / 2),
+    minLeafEntries: minOccupancy(maxLeafEntries),
+    minBranchChildren: minOccupancy(maxBranchChildren),
     root: emptyLeaf,
     leftmostLeaf: emptyLeaf,
     rightmostLeaf: emptyLeaf,
@@ -805,11 +908,11 @@ var maybeAutoScale = (state) => {
   const { maxLeaf, maxBranch } = computeAutoScaleTier(state.entryCount);
   if (maxLeaf > state.maxLeafEntries) {
     state.maxLeafEntries = maxLeaf;
-    state.minLeafEntries = Math.ceil(maxLeaf / 2);
+    state.minLeafEntries = minOccupancy(maxLeaf);
   }
   if (maxBranch > state.maxBranchChildren) {
     state.maxBranchChildren = maxBranch;
-    state.minBranchChildren = Math.ceil(maxBranch / 2);
+    state.minBranchChildren = minOccupancy(maxBranch);
   }
   state._nextAutoScaleThreshold = computeNextAutoScaleThreshold(state.entryCount);
 };
@@ -835,8 +938,8 @@ var applyAutoScaleCapacitySnapshot = (state, maxLeafEntries, maxBranchChildren)
   }
   state.maxLeafEntries = normalizedLeaf;
   state.maxBranchChildren = normalizedBranch;
-  state.minLeafEntries = Math.ceil(normalizedLeaf / 2);
-  state.minBranchChildren = Math.ceil(normalizedBranch / 2);
+  state.minLeafEntries = minOccupancy(normalizedLeaf);
+  state.minBranchChildren = minOccupancy(normalizedBranch);
 };
 
 // src/btree/bulkLoad.ts
@@ -1061,6 +1164,9 @@ var findLeafEntryBySequence = (state, userKey, sequence) => {
   return { leaf: targetLeaf, index };
 };
 var removeEntryById = (state, entryId) => {
+  if (state.entryKeys === null) {
+    throw new BTreeInvariantError("entryKeys lookup map is not enabled on this tree.");
+  }
   const userKey = state.entryKeys.get(entryId);
   if (userKey === void 0) return null;
   const found = findLeafEntryBySequence(state, userKey, entryId);
@@ -1078,6 +1184,9 @@ var removeEntryById = (state, entryId) => {
   return entry;
 };
 var peekEntryById = (state, entryId) => {
+  if (state.entryKeys === null) {
+    throw new BTreeInvariantError("entryKeys lookup map is not enabled on this tree.");
+  }
   const userKey = state.entryKeys.get(entryId);
   if (userKey === void 0) return null;
   const found = findLeafEntryBySequence(state, userKey, entryId);
@@ -1086,6 +1195,9 @@ var peekEntryById = (state, entryId) => {
   return entry;
 };
 var updateEntryById = (state, entryId, newValue) => {
+  if (state.entryKeys === null) {
+    throw new BTreeInvariantError("entryKeys lookup map is not enabled on this tree.");
+  }
   const userKey = state.entryKeys.get(entryId);
   if (userKey === void 0) return null;
   const found = findLeafEntryBySequence(state, userKey, entryId);
@@ -1099,9 +1211,12 @@ var putManyEntries = (state, entries) => {
   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) {
+    if (cmp > 0) {
+      throw new BTreeValidationError("putMany: entries not in ascending order.");
+    }
+    if (strictlyAscending && cmp === 0) {
       throw new BTreeValidationError(
-        strictlyAscending ? "putMany: not sorted in strict ascending order." : "putMany: not sorted in non-descending order."
+        state.duplicateKeys === "reject" ? "putMany: duplicate key rejected." : "putMany: equal keys not allowed in strict mode."
       );
     }
   }
@@ -1119,109 +1234,6 @@ var putManyEntries = (state, entries) => {
   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 = {
@@ -1351,7 +1363,7 @@ var compareNodeKeys = (comparator, leftKey, leftSeq, rightKey, rightSeq) => {
   if (cmp !== 0) {
     return cmp;
   }
-  return leftSeq - rightSeq;
+  return leftSeq < rightSeq ? -1 : leftSeq > rightSeq ? 1 : 0;
 };
 var getNodeMaxKey = (node) => {
   if (isLeafNode(node)) {
@@ -1684,44 +1696,56 @@ var InMemoryBTree = class _InMemoryBTree {
     return putManyEntries(this.state, entries);
   }
   remove(key) {
-    return removeFirstMatchingEntry(this.state, key);
+    const entry = removeFirstMatchingEntry(this.state, key);
+    if (entry === null) return null;
+    return toPublicEntry(entry);
   }
   removeById(entryId) {
     if (this.state.entryKeys === null) {
       throw new BTreeValidationError("Requires enableEntryIdLookup: true.");
     }
-    return removeEntryById(this.state, entryId);
+    const entry = removeEntryById(this.state, entryId);
+    if (entry === null) return null;
+    return toPublicEntry(entry);
   }
   peekById(entryId) {
     if (this.state.entryKeys === null) {
       throw new BTreeValidationError("Requires enableEntryIdLookup: true.");
     }
-    return peekEntryById(this.state, entryId);
+    const entry = peekEntryById(this.state, entryId);
+    if (entry === null) return null;
+    return toPublicEntry(entry);
   }
   updateById(entryId, value) {
     if (this.state.entryKeys === null) {
       throw new BTreeValidationError("Requires enableEntryIdLookup: true.");
     }
-    return updateEntryById(this.state, entryId, value);
+    const entry = updateEntryById(this.state, entryId, value);
+    if (entry === null) return null;
+    return toPublicEntry(entry);
   }
   popFirst() {
-    return popFirstEntry(this.state);
+    const entry = popFirstEntry(this.state);
+    if (entry === null) return null;
+    return toPublicEntry(entry);
   }
   peekFirst() {
     if (this.state.entryCount === 0) {
       return null;
     }
-    return leafEntryAt(this.state.leftmostLeaf, 0);
+    return toPublicEntry(leafEntryAt(this.state.leftmostLeaf, 0));
   }
   peekLast() {
     if (this.state.entryCount === 0) {
       return null;
     }
     const leaf = this.state.rightmostLeaf;
-    return leafEntryAt(leaf, leafEntryCount(leaf) - 1);
+    return toPublicEntry(leafEntryAt(leaf, leafEntryCount(leaf) - 1));
   }
   popLast() {
-    return popLastEntry(this.state);
+    const entry = popLastEntry(this.state);
+    if (entry === null) return null;
+    return toPublicEntry(entry);
   }
   clear() {
     const emptyLeaf = createLeafNode([], null);
@@ -1738,8 +1762,8 @@ var InMemoryBTree = class _InMemoryBTree {
       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.minLeafEntries = minOccupancy(tier.maxLeaf);
+      this.state.minBranchChildren = minOccupancy(tier.maxBranch);
       this.state._nextAutoScaleThreshold = computeNextAutoScaleThreshold(0);
     }
   }
@@ -1754,39 +1778,65 @@ var InMemoryBTree = class _InMemoryBTree {
   findFirst(key) {
     const found = findFirstMatchingUserKey(this.state, key);
     if (found === null) return null;
-    return leafEntryAt(found.leaf, found.index);
+    return toPublicEntry(leafEntryAt(found.leaf, found.index));
   }
+  /**
+   * Returns the last entry whose key matches `key`, or `null` if not found.
+   * Useful when `duplicateKeys` is `'allow'` and multiple entries share the same key.
+   */
   findLast(key) {
     const found = findLastMatchingUserKey(this.state, key);
     if (found === null) return null;
-    return leafEntryAt(found.leaf, found.index);
+    return toPublicEntry(leafEntryAt(found.leaf, found.index));
   }
+  /**
+   * Returns the smallest key in the tree that is strictly greater than `key`,
+   * or `null` if no such key exists.
+   */
   nextHigherKey(key) {
     return findNextHigherKey(this.state, key);
   }
+  /**
+   * Returns the largest key in the tree that is strictly less than `key`,
+   * or `null` if no such key exists.
+   */
   nextLowerKey(key) {
     return findNextLowerKey(this.state, key);
   }
+  /**
+   * Returns the entry for `key` if it exists; otherwise returns the entry with
+   * the largest key strictly less than `key`. Returns `null` when the tree is
+   * empty or every key is greater than `key`.
+   */
   getPairOrNextLower(key) {
     const found = findPairOrNextLower(this.state, key);
     if (found === null) return null;
-    return leafEntryAt(found.leaf, found.index);
+    return toPublicEntry(leafEntryAt(found.leaf, found.index));
   }
+  /**
+   * Returns the number of entries whose keys fall within [`startKey`, `endKey`].
+   * Pass `options` to make either bound exclusive.
+   */
   count(startKey, endKey, options) {
     return countRangeEntries(this.state, startKey, endKey, options);
   }
+  /**
+   * Deletes all entries whose keys fall within [`startKey`, `endKey`].
+   * Pass `options` to make either bound exclusive.
+   * @returns The number of entries deleted.
+   */
   deleteRange(startKey, endKey, options) {
     return deleteRangeEntries(this.state, startKey, endKey, options);
   }
   range(startKey, endKey, options) {
-    return rangeQueryEntries(this.state, startKey, endKey, options);
+    return rangeQueryEntries(this.state, startKey, endKey, options).map(toPublicEntry);
   }
   *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);
+        yield toPublicEntry(leafEntryAt(leaf, i));
       }
       leaf = leaf.next;
     }
@@ -1796,29 +1846,19 @@ var InMemoryBTree = class _InMemoryBTree {
     while (leaf !== null) {
       const count = leafEntryCount(leaf);
       for (let i = count - 1; i >= 0; i -= 1) {
-        yield leafEntryAt(leaf, i);
+        yield toPublicEntry(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;
+    for (const entry of this.entries()) {
+      yield entry.key;
     }
   }
   *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;
+    for (const entry of this.entries()) {
+      yield entry.value;
     }
   }
   [Symbol.iterator]() {
@@ -1829,7 +1869,7 @@ var InMemoryBTree = class _InMemoryBTree {
     while (leaf !== null) {
       const count = leafEntryCount(leaf);
       for (let i = 0; i < count; i += 1) {
-        callback.call(thisArg, leafEntryAt(leaf, i));
+        callback.call(thisArg, toPublicEntry(leafEntryAt(leaf, i)));
       }
       leaf = leaf.next;
     }
@@ -1841,12 +1881,19 @@ var InMemoryBTree = class _InMemoryBTree {
     while (leaf !== null) {
       const count = leafEntryCount(leaf);
       for (let i = 0; i < count; i += 1) {
-        result[writeIdx++] = leafEntryAt(leaf, i);
+        result[writeIdx++] = toPublicEntry(leafEntryAt(leaf, i));
       }
       leaf = leaf.next;
     }
     return result;
   }
+  /**
+   * Returns a structurally independent `InMemoryBTree` with identical
+   * configuration and entries. The tree structure (nodes, links, entry IDs)
+   * is fully independent, but stored key and value references are shared
+   * with the source tree.
+   * Note: `EntryId` values are reassigned in the clone — IDs from the source tree are not valid for the clone.
+   */
   clone() {
     const cloned = new _InMemoryBTree(buildConfigFromState(this.state));
     applyAutoScaleCapacitySnapshot(