@frostpillar/frostpillar-btree 0.2.4 → 0.2.6

package/dist/index.cjs

@@ -51,54 +51,10 @@ var BTreeConcurrencyError = 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,
@@ -110,7 +66,7 @@ var createLeafNode = (entries, parent) => {
 var createBranchNode = (children, parent) => {
   const keys = [];
   const branch = {
-    kind: NODE_BRANCH,
+    kind: 1,
     children,
     keys,
     childOffset: 0,
@@ -249,6 +205,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;
@@ -262,7 +268,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 {
@@ -287,7 +293,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;
@@ -303,7 +309,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;
@@ -440,6 +446,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;
@@ -665,16 +779,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);
@@ -689,11 +794,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);
@@ -703,12 +808,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;
@@ -726,7 +828,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)) {
@@ -745,6 +847,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 },
@@ -796,8 +899,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,
@@ -814,11 +917,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);
 };
@@ -844,8 +947,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
@@ -1070,6 +1173,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);
@@ -1087,6 +1193,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);
@@ -1095,6 +1204,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);
@@ -1108,9 +1220,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."
       );
     }
   }
@@ -1128,109 +1243,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 = {
@@ -1360,7 +1372,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)) {
@@ -1693,44 +1705,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);
@@ -1747,8 +1771,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);
     }
   }
@@ -1763,39 +1787,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;
     }
@@ -1805,29 +1855,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]() {
@@ -1838,7 +1878,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;
     }
@@ -1850,12 +1890,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(
@@ -1943,6 +1990,81 @@ var assertNeverMutation = (mutation) => {
     `Unsupported mutation type from shared store: ${String(unknownMutation.type)}`
   );
 };
+var validatePutManyEntries = (entries) => {
+  for (const entry of entries) {
+    if (typeof entry !== "object" || entry === null || !("key" in entry) || !("value" in entry)) {
+      throw new BTreeConcurrencyError("Malformed putMany mutation: each entry must have key and value.");
+    }
+  }
+};
+var validateInitMutation = (m, expectedConfigFingerprint) => {
+  if (typeof m.configFingerprint !== "string") {
+    throw new BTreeConcurrencyError("Malformed init mutation: missing configFingerprint.");
+  }
+  if (expectedConfigFingerprint !== void 0 && m.configFingerprint !== expectedConfigFingerprint) {
+    throw new BTreeConcurrencyError(
+      "Config mismatch: store peers must share identical tree config."
+    );
+  }
+};
+var validateSingleMutation = (m, expectedConfigFingerprint) => {
+  switch (m.type) {
+    case "init":
+      validateInitMutation(m, expectedConfigFingerprint);
+      break;
+    case "put":
+      if (!("key" in m) || !("value" in m)) {
+        throw new BTreeConcurrencyError("Malformed put mutation: missing key or value.");
+      }
+      break;
+    case "remove":
+      if (!("key" in m)) {
+        throw new BTreeConcurrencyError("Malformed remove mutation: missing key.");
+      }
+      break;
+    case "removeById":
+      if (!("entryId" in m)) {
+        throw new BTreeConcurrencyError("Malformed removeById mutation: missing entryId.");
+      }
+      break;
+    case "updateById":
+      if (!("entryId" in m) || !("value" in m)) {
+        throw new BTreeConcurrencyError("Malformed updateById mutation: missing entryId or value.");
+      }
+      break;
+    case "popFirst":
+    case "popLast":
+      break;
+    case "putMany":
+      if (!("entries" in m) || !Array.isArray(m.entries)) {
+        throw new BTreeConcurrencyError("Malformed putMany mutation: missing entries array.");
+      }
+      validatePutManyEntries(m.entries);
+      break;
+    case "deleteRange":
+      if (!("startKey" in m) || !("endKey" in m)) {
+        throw new BTreeConcurrencyError("Malformed deleteRange mutation: missing startKey or endKey.");
+      }
+      break;
+    case "clear":
+      break;
+    default:
+      throw new BTreeConcurrencyError(
+        `Unsupported mutation type from shared store: ${String(m.type)}`
+      );
+  }
+};
+var validateMutationBatch = (mutations, expectedConfigFingerprint) => {
+  for (const mutation of mutations) {
+    if (typeof mutation !== "object" || mutation === null) {
+      throw new BTreeConcurrencyError("Malformed mutation: expected an object.");
+    }
+    validateSingleMutation(
+      mutation,
+      expectedConfigFingerprint
+    );
+  }
+};
 var normalizeMaxRetries = (value) => {
   if (value === void 0) {
     return DEFAULT_MAX_RETRIES;
@@ -2001,10 +2123,110 @@ function assertAppendVersionContract(expectedVersion, appendResult) {
   }
 }
 
+// src/concurrency/writeOps.ts
+var applyMutationLocal = (tree, mutation, onInit) => {
+  switch (mutation.type) {
+    case "init":
+      onInit();
+      return null;
+    case "put":
+      return tree.put(mutation.key, mutation.value);
+    case "putMany":
+      return tree.putMany(mutation.entries);
+    case "remove":
+      return tree.remove(mutation.key);
+    case "removeById":
+      return tree.removeById(mutation.entryId);
+    case "updateById":
+      return tree.updateById(mutation.entryId, mutation.value);
+    case "popFirst":
+      return tree.popFirst();
+    case "popLast":
+      return tree.popLast();
+    case "deleteRange":
+      return tree.deleteRange(mutation.startKey, mutation.endKey, mutation.options);
+    case "clear":
+      tree.clear();
+      return null;
+    default:
+      return assertNeverMutation(mutation);
+  }
+};
+var createPutEvaluator = (duplicateKeys, key, value) => {
+  return (tree) => {
+    if (duplicateKeys === "reject" && tree.hasKey(key)) {
+      throw new BTreeValidationError("Duplicate key rejected.");
+    }
+    return { type: "put", key, value };
+  };
+};
+var createRemoveEvaluator = (key) => {
+  return (tree) => {
+    return tree.hasKey(key) ? { type: "remove", key } : null;
+  };
+};
+var createRemoveByIdEvaluator = (entryId) => {
+  return (tree) => {
+    return tree.peekById(entryId) !== null ? { type: "removeById", entryId } : null;
+  };
+};
+var createUpdateByIdEvaluator = (entryId, value) => {
+  return (tree) => {
+    return tree.peekById(entryId) !== null ? { type: "updateById", entryId, value } : null;
+  };
+};
+var createPopFirstEvaluator = () => {
+  return (tree) => {
+    return tree.peekFirst() !== null ? { type: "popFirst" } : null;
+  };
+};
+var createPopLastEvaluator = () => {
+  return (tree) => {
+    return tree.peekLast() !== null ? { type: "popLast" } : null;
+  };
+};
+var createPutManyEvaluator = (entries, duplicateKeys, compareKeys) => {
+  return (tree) => {
+    const strictlyAscending = duplicateKeys !== "allow";
+    for (let i = 1; i < entries.length; i += 1) {
+      const cmp = compareKeys(entries[i - 1].key, entries[i].key);
+      if (cmp > 0) {
+        throw new BTreeValidationError("putMany: entries not in ascending order.");
+      }
+      if (strictlyAscending && cmp === 0) {
+        throw new BTreeValidationError(
+          duplicateKeys === "reject" ? "putMany: duplicate key rejected." : "putMany: equal keys not allowed in strict mode."
+        );
+      }
+    }
+    if (duplicateKeys === "reject") {
+      for (const entry of entries) {
+        if (tree.hasKey(entry.key)) {
+          throw new BTreeValidationError("Duplicate key rejected.");
+        }
+      }
+    }
+    return { type: "putMany", entries };
+  };
+};
+var createDeleteRangeEvaluator = (startKey, endKey, options) => {
+  return (tree) => {
+    const count = tree.count(startKey, endKey, options);
+    if (count === 0) {
+      return null;
+    }
+    return { type: "deleteRange", startKey, endKey, options };
+  };
+};
+var createClearEvaluator = () => {
+  return () => ({ type: "clear" });
+};
+
 // src/concurrency/ConcurrentInMemoryBTree.ts
 var ConcurrentInMemoryBTree = class {
   constructor(config) {
     this.store = config.store;
+    this.compareKeys = config.compareKeys;
     this.maxRetries = normalizeMaxRetries(config.maxRetries);
     this.maxSyncMutationsPerBatch = normalizeMaxSyncMutationsPerBatch(
       config.maxSyncMutationsPerBatch
@@ -2023,6 +2245,7 @@ var ConcurrentInMemoryBTree = class {
     this.currentVersion = 0n;
     this.operationQueue = Promise.resolve();
     this.initSeen = false;
+    this.corrupted = false;
   }
   async sync() {
     await this.runExclusive(async () => {
@@ -2045,39 +2268,31 @@ var ConcurrentInMemoryBTree = class {
     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);
+    validateMutationBatch(log.mutations, this.configFingerprint);
+    try {
+      for (const mutation of log.mutations) {
+        applyMutationLocal(this.tree, mutation, () => {
+          this.initSeen = true;
+        });
+      }
+      this.currentVersion = log.version;
+    } catch (error) {
+      this.corrupted = true;
+      const cause = error instanceof Error ? error.message : String(error);
+      throw new BTreeConcurrencyError(
+        `Replay failure: instance is permanently corrupted. Discard and create a new instance. Cause: ${cause}`
+      );
     }
   }
   runExclusive(operation) {
-    const run = async () => operation();
+    const run = async () => {
+      if (this.corrupted) {
+        throw new BTreeConcurrencyError(
+          "Instance is permanently corrupted. Discard and create a new instance."
+        );
+      }
+      return operation();
+    };
     const result = this.operationQueue.then(run, run);
     this.operationQueue = result.then(
       () => void 0,
@@ -2105,13 +2320,29 @@ var ConcurrentInMemoryBTree = class {
       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);
+        try {
+          for (const m of mutations) {
+            if (m === mutation) break;
+            applyMutationLocal(this.tree, m, () => {
+              this.initSeen = true;
+            });
+          }
+          const localResult = applyMutationLocal(
+            this.tree,
+            mutation,
+            () => {
+              this.initSeen = true;
+            }
+          );
+          this.currentVersion = appendResult.version;
+          return localResult;
+        } catch (error) {
+          this.corrupted = true;
+          const cause = error instanceof Error ? error.message : String(error);
+          throw new BTreeConcurrencyError(
+            `Local apply failure after successful append: instance is permanently corrupted. Discard and create a new instance. Cause: ${cause}`
+          );
         }
-        const localResult = this.applyMutationLocal(mutation);
-        this.currentVersion = appendResult.version;
-        return localResult;
       }
     }
     throw new BTreeConcurrencyError(
@@ -2121,47 +2352,56 @@ var ConcurrentInMemoryBTree = class {
   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 };
-        }
+        createPutEvaluator(this.duplicateKeys, key, value)
       );
     });
   }
   async remove(key) {
     return this.runExclusive(async () => {
-      return this.appendMutationAndApplyUnlocked(
-        (tree) => {
-          return tree.hasKey(key) ? { type: "remove", key } : null;
-        }
-      );
+      return this.appendMutationAndApplyUnlocked(createRemoveEvaluator(key));
     });
   }
   async removeById(entryId) {
     return this.runExclusive(async () => {
-      return this.appendMutationAndApplyUnlocked(
-        (tree) => {
-          return tree.peekById(entryId) !== null ? { type: "removeById", entryId } : null;
-        }
-      );
+      return this.appendMutationAndApplyUnlocked(createRemoveByIdEvaluator(entryId));
     });
   }
   async updateById(entryId, value) {
+    return this.runExclusive(async () => {
+      return this.appendMutationAndApplyUnlocked(createUpdateByIdEvaluator(entryId, value));
+    });
+  }
+  async popFirst() {
+    return this.runExclusive(async () => {
+      return this.appendMutationAndApplyUnlocked(createPopFirstEvaluator());
+    });
+  }
+  async popLast() {
+    return this.runExclusive(async () => {
+      return this.appendMutationAndApplyUnlocked(createPopLastEvaluator());
+    });
+  }
+  async putMany(entries) {
+    if (entries.length === 0) {
+      return [];
+    }
     return this.runExclusive(async () => {
       return this.appendMutationAndApplyUnlocked(
-        (tree) => {
-          return tree.peekById(entryId) !== null ? { type: "updateById", entryId, value } : null;
-        }
+        createPutManyEvaluator(entries, this.duplicateKeys, this.compareKeys)
       );
     });
   }
-  async popFirst() {
+  async deleteRange(startKey, endKey, options) {
     return this.runExclusive(async () => {
-      return this.appendMutationAndApplyUnlocked((tree) => {
-        return tree.peekFirst() !== null ? { type: "popFirst" } : null;
-      });
+      const result = await this.appendMutationAndApplyUnlocked(
+        createDeleteRangeEvaluator(startKey, endKey, options)
+      );
+      return result ?? 0;
+    });
+  }
+  async clear() {
+    await this.runExclusive(async () => {
+      await this.appendMutationAndApplyUnlocked(createClearEvaluator());
     });
   }
   async get(key) {
@@ -2197,13 +2437,6 @@ var ConcurrentInMemoryBTree = class {
   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));
   }
@@ -2219,6 +2452,38 @@ var ConcurrentInMemoryBTree = class {
   async getPairOrNextLower(key) {
     return this.readOp((tree) => tree.getPairOrNextLower(key));
   }
+  async entries() {
+    return this.readOp((tree) => Array.from(tree.entries()));
+  }
+  async entriesReversed() {
+    return this.readOp((tree) => Array.from(tree.entriesReversed()));
+  }
+  async keys() {
+    return this.readOp((tree) => Array.from(tree.keys()));
+  }
+  async values() {
+    return this.readOp((tree) => Array.from(tree.values()));
+  }
+  async forEach(callback) {
+    await this.readOp((tree) => {
+      tree.forEach(callback);
+    });
+  }
+  async *[Symbol.asyncIterator]() {
+    const all = await this.entries();
+    for (const entry of all) {
+      yield entry;
+    }
+  }
+  async clone() {
+    return this.readOp((tree) => tree.clone());
+  }
+  async toJSON() {
+    return this.readOp((tree) => tree.toJSON());
+  }
+  static fromJSON(json, compareKeys) {
+    return InMemoryBTree.fromJSON(json, compareKeys);
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {