@frostpillar/frostpillar-btree 0.2.4 → 0.2.6

package/README-JA.md

@@ -280,7 +280,7 @@ const last = tree.popLast();
 // { entryId: ..., key: 20, value: 'twenty' } または null（ツリーが空の場合）
 ```
 
-**`clear()`** -- 全エントリを削除し、ツリーを空の状態に O(1) でリセットします。内部シーケンスカウンタもリセットされるため、新しい `EntryId` はゼロから始まります。`clear()` 前に取得した `EntryId` は無効になります。
+**`clear()`** -- 全エントリを削除し、ツリーを空の状態に O(1) でリセットします。内部シーケンスカウンタはリセット**されない**ため、`EntryId` はインスタンスの存続期間中単調増加し、再利用されません。
 
 ```ts
 tree.clear();
@@ -429,7 +429,7 @@ tree.assertInvariants(); // 不正な場合はスロー
 
 #### クローンとシリアライズ
 
-**`clone()`** -- 構造的に独立したディープコピーを作成します。
+**`clone()`** -- 構造的に独立したコピーを作成します。ツリー構造（ノード、リンク、エントリID）は完全に独立しますが、格納されたキーと値の参照は元のツリーと共有されます。
 
 ```ts
 const copy = tree.clone();
@@ -437,6 +437,8 @@ copy.put(99, 'new');
 tree.hasKey(99); // false -- 元のツリーには影響しない
 ```
 
+注意: `EntryId` の値はクローン内で再割り当てされます — 元のツリーの ID はクローンに対して有効ではありません。
+
 **`toJSON()` / `fromJSON()`** -- ツリーをシリアライズ・復元します。
 
 ```ts
@@ -501,7 +503,9 @@ const tree = new InMemoryBTree<number, string>({
 - **`getLogEntriesSince(version)`** -- 指定バージョン以降のすべてのミューテーションを返し、各インスタンスが最新状態へキャッチアップできるようにします。
 - **`append(expectedVersion, mutations)`** -- バージョンが一致する場合にミューテーションをアトミックに追加します（compare-and-swap）。`{ applied, version }` を返します。
 
-ストアの実装は自由です。インメモリ配列、データベーステーブル、Redis stream など何でも使えます。以下はインメモリの参考実装です。
+`getLogEntriesSince` で過去のミューテーションを返すストアは**マルチインスタンス・キャッチアップ**を実現します。各インスタンスが未受信のミューテーションをリプレイし、同一状態に収束します。ミューテーションをリプレイしないストア（空の `mutations` 配列と更新された `version` を返す）もサポートされています。この場合、各インスタンスは自身のローカル書き込みとバージョン進行のみを認識します。一貫性要件に応じてリプレイ戦略を選択してください。
+
+ストアの実装は自由です。インメモリ配列、データベーステーブル、Redis stream など何でも使えます。以下はリプレイ対応のインメモリ参考実装です。
 
 **Node.js / TypeScript：**
 
@@ -754,6 +758,23 @@ try {
 
 ---
 
+#### 共有ストアのセキュリティ前提
+
+`ConcurrentInMemoryBTree` は共有ストアが**信頼されている**ことを前提としています。悪意を持って細工されたミューテーションペイロードや、異常に大きなペイロードに対する防御機能はありません。
+
+**信頼境界：**
+- ストアはあなたのアプリケーションの管理下にあること。
+- 同一ストアを共有するすべてのインスタンスは同一の設定を使用すること（最初の書き込み時に `init` ミューテーションの設定フィンガープリントで検証されますが、リプレイバッチに `init` が含まれている場合に限ります）。
+- ミューテーションはリプレイ前に構造的に検証されますが、セマンティックな正確性（キー型の整合性など）は呼び出し側の責任です。
+
+**共有・マルチテナントデプロイメントにおける堅牢化の推奨事項：**
+- 認可レイヤーなしに `append` や `getLogEntriesSince` を信頼されていないクライアントに公開しないこと。
+- 格納するミューテーションペイロードのサイズ制限をストアレベルで適用してから `ConcurrentInMemoryBTree` に渡すこと。
+- `maxSyncMutationsPerBatch` を使用して、1回の sync 呼び出しで適用するミューテーション数を制限すること（デフォルト：100,000）。
+- リプレイ失敗により `sync()` が `BTreeConcurrencyError` をスローした場合、インスタンスは永続的に汚染されます。そのインスタンスを破棄し、新しいインスタンスを作成してください。
+
+---
+
 ## API リファレンス
 
 ### InMemoryBTree
@@ -791,7 +812,7 @@ try {
 | `size`               | `() => number`                                                                        | エントリ数を返す。                                                                |
 | `getStats`           | `() => BTreeStats`                                                                    | 構造統計を返す。                                                                  |
 | `assertInvariants`   | `() => void`                                                                          | B+ tree の構造的な整合性を検証する。不正な場合はスローする。                      |
-| `clone`              | `() => InMemoryBTree<TKey, TValue>`                                                   | 構造的に独立したディープコピーを返す。                                            |
+| `clone`              | `() => InMemoryBTree<TKey, TValue>`                                                   | 構造的に独立したコピーを返す（キー・値参照は共有）。                              |
 | `toJSON`             | `() => BTreeJSON<TKey, TValue>`                                                       | バージョン付き JSON 互換ペイロードにシリアライズする。                            |
 | `fromJSON` (静的)    | `(json, compareKeys) => InMemoryBTree<TKey, TValue>`                                  | `toJSON` ペイロードからツリーを再構築する。                                       |
 
@@ -803,18 +824,21 @@ new InMemoryBTree<TKey, TValue>(config: InMemoryBTreeConfig<TKey>)
 
 ### ConcurrentInMemoryBTree
 
-`InMemoryBTree` メソッドのサブセットを `Promise` を返す非同期版として提供します。書き込みは shared store を介して協調し、`readMode` が `'strong'`（デフォルト）の場合は読み取り前に同期します。`readMode` が `'local'` の場合、読み取りは同期なしでローカルツリーに対して実行されます。`putMany`・`deleteRange`・イテレータ・`clear`・`clone`・`toJSON`/`fromJSON` は現在未対応です。
+`InMemoryBTree` メソッドを `Promise` を返す非同期版として提供します。書き込みは shared store を介して協調し、`readMode` が `'strong'`（デフォルト）の場合は読み取り前に同期します。`readMode` が `'local'` の場合、読み取りは同期なしでローカルツリーに対して実行されます。
 
 | メソッド             | シグネチャ                                                                                     | 説明                                               |
 | -------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------- |
 | `sync`               | `() => Promise<void>`                                                                          | shared store の最新ログを取得して適用する。        |
 | `put`                | `(key: TKey, value: TValue) => Promise<EntryId>`                                               | 楽観的並行制御で挿入する。                         |
+| `putMany`            | `(entries: readonly { key: TKey; value: TValue }[]) => Promise<EntryId[]>`                     | 楽観的並行制御で一括挿入する。                     |
 | `remove`             | `(key: TKey) => Promise<BTreeEntry<TKey, TValue> \| null>`                                     | 指定キーに一致する最初のエントリを削除する。       |
 | `removeById`         | `(entryId: EntryId) => Promise<BTreeEntry<TKey, TValue> \| null>`                              | ID でエントリを削除する。                          |
 | `peekById`           | `(entryId: EntryId) => Promise<BTreeEntry<TKey, TValue> \| null>`                              | ID でエントリを参照する（事前に同期）。            |
 | `updateById`         | `(entryId: EntryId, value: TValue) => Promise<BTreeEntry<TKey, TValue> \| null>`               | 楽観的並行制御で ID のエントリ値を更新する。       |
 | `popFirst`           | `() => Promise<BTreeEntry<TKey, TValue> \| null>`                                              | 最小キーのエントリを削除して返す。                 |
 | `popLast`            | `() => Promise<BTreeEntry<TKey, TValue> \| null>`                                              | 最大キーのエントリを削除して返す。                 |
+| `deleteRange`        | `(startKey: TKey, endKey: TKey, options?: RangeBounds) => Promise<number>`                     | 楽観的並行制御で範囲内のエントリを削除する。       |
+| `clear`              | `() => Promise<void>`                                                                          | 楽観的並行制御で全エントリを削除する。             |
 | `peekFirst`          | `() => Promise<BTreeEntry<TKey, TValue> \| null>`                                              | 最小キーのエントリを返す（事前に同期）。           |
 | `peekLast`           | `() => Promise<BTreeEntry<TKey, TValue> \| null>`                                              | 最大キーのエントリを返す（事前に同期）。           |
 | `findFirst`          | `(key: TKey) => Promise<BTreeEntry<TKey, TValue> \| null>`                                     | キーに一致する最初のエントリを返す（事前に同期）。 |
@@ -826,10 +850,19 @@ new InMemoryBTree<TKey, TValue>(config: InMemoryBTreeConfig<TKey>)
 | `nextHigherKey`      | `(key: TKey) => Promise<TKey \| null>`                                                         | 指定キーより大きい次のキー（事前に同期）。         |
 | `nextLowerKey`       | `(key: TKey) => Promise<TKey \| null>`                                                         | 指定キーより小さい次のキー（事前に同期）。         |
 | `getPairOrNextLower` | `(key: TKey) => Promise<BTreeEntry<TKey, TValue> \| null>`                                     | 一致または次に小さいエントリ（事前に同期）。       |
+| `entries`            | `() => Promise<BTreeEntry<TKey, TValue>[]>`                                                    | 全エントリを配列で返す（事前に同期）。             |
+| `entriesReversed`    | `() => Promise<BTreeEntry<TKey, TValue>[]>`                                                    | 全エントリを逆順で配列として返す（事前に同期）。   |
+| `keys`               | `() => Promise<TKey[]>`                                                                        | 全キーを配列で返す（事前に同期）。                 |
+| `values`             | `() => Promise<TValue[]>`                                                                      | 全値を配列で返す（事前に同期）。                   |
+| `forEach`            | `(callback: (entry: BTreeEntry<TKey, TValue>) => void) => Promise<void>`                      | 全エントリを反復する（事前に同期）。               |
 | `snapshot`           | `() => Promise<BTreeEntry<TKey, TValue>[]>`                                                    | 全エントリを返す（事前に同期）。                   |
 | `size`               | `() => Promise<number>`                                                                        | エントリ数を返す（事前に同期）。                   |
 | `getStats`           | `() => Promise<BTreeStats>`                                                                    | 構造統計を返す（事前に同期）。                     |
 | `assertInvariants`   | `() => Promise<void>`                                                                          | 構造的な整合性を検証する（事前に同期）。           |
+| `clone`              | `() => Promise<InMemoryBTree<TKey, TValue>>`                                                   | 独立したローカルコピーを返す（事前に同期）。       |
+| `toJSON`             | `() => Promise<BTreeJSON<TKey, TValue>>`                                                       | JSON にシリアライズする（事前に同期）。            |
+| `fromJSON` (static)  | `(json: BTreeJSON<TKey, TValue>, compareKeys: KeyComparator<TKey>) => InMemoryBTree<TKey, TValue>` | JSON からデシリアライズする（ローカルツリーを返す）。 |
+| `[Symbol.asyncIterator]` | `() => AsyncIterableIterator<BTreeEntry<TKey, TValue>>`                                    | 全エントリを非同期反復する（事前に同期）。         |
 
 **コンストラクタ：**
 
@@ -853,7 +886,7 @@ new ConcurrentInMemoryBTree<TKey, TValue>(config: ConcurrentInMemoryBTreeConfig<
 | `ConcurrentInMemoryBTreeConfig<TKey, TValue>` | `InMemoryBTreeConfig<TKey>` を拡張し、`store: SharedTreeStore<TKey, TValue>`、`maxRetries?: number`、`maxSyncMutationsPerBatch?: number`、`readMode?: ReadMode` を追加。            |
 | `SharedTreeStore<TKey, TValue>`               | `getLogEntriesSince(version)` と `append(expectedVersion, mutations)` を持つインターフェース。                                                                                      |
 | `SharedTreeLog<TKey, TValue>`                 | `{ version: bigint; mutations: BTreeMutation<TKey, TValue>[] }`                                                                                                                     |
-| `BTreeMutation<TKey, TValue>`                 | 判別共用体: `init`、`put`、`remove`、`removeById`、`updateById`、`popFirst`、`popLast`。                                                                                            |
+| `BTreeMutation<TKey, TValue>`                 | 判別共用体: `init`、`put`、`putMany`、`remove`、`removeById`、`updateById`、`popFirst`、`popLast`、`deleteRange`、`clear`。                                                         |
 | `BTreeValidationError`                        | コンパレータや設定の違反でスローされるエラー。                                                                                                                                      |
 | `BTreeInvariantError`                         | ツリー構造の整合性違反でスローされるエラー。                                                                                                                                        |
 | `BTreeConcurrencyError`                       | 並行処理コンフリクトやストア契約違反でスローされるエラー。                                                                                                                          |

package/README.md

@@ -280,7 +280,7 @@ const last = tree.popLast();
 // { entryId: ..., key: 20, value: 'twenty' } or null if empty
 ```
 
-**`clear()`** -- remove all entries and reset the tree to its empty state in O(1). The internal sequence counter is also reset, so new `EntryId` values start from zero. Any `EntryId` obtained before `clear()` becomes invalid.
+**`clear()`** -- remove all entries and reset the tree to its empty state in O(1). The internal sequence counter is **not** reset, so `EntryId` values continue to increase monotonically and are never reused within the lifetime of the instance.
 
 ```ts
 tree.clear();
@@ -429,7 +429,7 @@ tree.assertInvariants(); // throws if invalid
 
 #### Clone and Serialization
 
-**`clone()`** -- create a structurally independent deep copy:
+**`clone()`** -- create a structurally independent copy. The tree structure (nodes, links, entry IDs) is fully independent, but stored key and value references are shared with the source tree:
 
 ```ts
 const copy = tree.clone();
@@ -437,6 +437,8 @@ copy.put(99, 'new');
 tree.hasKey(99); // false — original is unaffected
 ```
 
+Note: `EntryId` values are reassigned in the clone — IDs from the source tree are not valid for the clone.
+
 **`toJSON()` / `fromJSON()`** -- serialize and reconstruct:
 
 ```ts
@@ -501,7 +503,9 @@ const tree = new InMemoryBTree<number, string>({
 - **`getLogEntriesSince(version)`** -- returns all mutations since a given version, so each instance can catch up.
 - **`append(expectedVersion, mutations)`** -- atomically appends mutations if the version matches (compare-and-swap). Returns `{ applied, version }`.
 
-The store can be backed by anything: an in-memory array, a database table, a Redis stream, etc. Below is a complete in-memory reference implementation.
+A store that returns historical mutations from `getLogEntriesSince` enables **multi-instance catch-up**: any instance can replay missed mutations to converge on the same state. Stores that do not replay mutations (returning an empty `mutations` array with an updated `version`) are also supported — in this mode, each instance only sees its own local writes and version advancement. Choose the replay strategy that matches your consistency requirements.
+
+The store can be backed by anything: an in-memory array, a database table, a Redis stream, etc. Below is a complete in-memory reference implementation with replay support.
 
 **Node.js / TypeScript:**
 
@@ -754,6 +758,23 @@ try {
 
 ---
 
+#### Shared Store Security Assumptions
+
+`ConcurrentInMemoryBTree` assumes the shared store is **trusted**. It does not defend against a store that returns maliciously crafted or arbitrarily large mutation payloads.
+
+**Trust boundary:**
+- The store is under your control or the control of your application.
+- All instances sharing a store must use identical configuration (enforced via config fingerprint on the first write, but only when an `init` mutation is present in the replayed batch).
+- Mutations are structurally validated before replay, but semantic correctness (e.g., key type consistency) is the caller's responsibility.
+
+**Hardening recommendations for shared or multi-tenant deployments:**
+- Do not expose `append` or `getLogEntriesSince` to untrusted clients without an authorization layer.
+- Apply size limits to stored mutation payloads at the store level before they reach `ConcurrentInMemoryBTree`.
+- Use `maxSyncMutationsPerBatch` to cap the number of mutations applied per sync call (default: 100,000).
+- If a `sync()` throws `BTreeConcurrencyError` due to a replay failure, the instance is permanently poisoned. Discard it and create a new one.
+
+---
+
 ## API Reference
 
 ### InMemoryBTree
@@ -791,7 +812,7 @@ try {
 | `size`               | `() => number`                                                                        | Return the total number of entries.                                                     |
 | `getStats`           | `() => BTreeStats`                                                                    | Return structural statistics.                                                           |
 | `assertInvariants`   | `() => void`                                                                          | Assert B+ tree structural integrity. Throws if invalid.                                 |
-| `clone`              | `() => InMemoryBTree<TKey, TValue>`                                                   | Return a structurally independent deep copy.                                            |
+| `clone`              | `() => InMemoryBTree<TKey, TValue>`                                                   | Return a structurally independent copy (shared key/value refs).                         |
 | `toJSON`             | `() => BTreeJSON<TKey, TValue>`                                                       | Serialize to a versioned JSON-safe payload.                                             |
 | `fromJSON` (static)  | `(json, compareKeys) => InMemoryBTree<TKey, TValue>`                                  | Reconstruct a tree from a `toJSON` payload.                                             |
 
@@ -803,18 +824,21 @@ new InMemoryBTree<TKey, TValue>(config: InMemoryBTreeConfig<TKey>)
 
 ### ConcurrentInMemoryBTree
 
-Exposes a subset of `InMemoryBTree` methods as async equivalents returning `Promise`. Writes coordinate through the shared store; reads sync before returning when `readMode` is `'strong'` (the default). When `readMode` is `'local'`, reads execute against the local tree without syncing. Methods such as `putMany`, iterators, `clear`, `clone`, `deleteRange`, and `toJSON`/`fromJSON` are not yet available on the concurrent wrapper.
+Exposes `InMemoryBTree` methods as async equivalents returning `Promise`. Writes coordinate through the shared store; reads sync before returning when `readMode` is `'strong'` (the default). When `readMode` is `'local'`, reads execute against the local tree without syncing.
 
 | Method               | Signature                                                                                      | Description                                                   |
 | -------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
 | `sync`               | `() => Promise<void>`                                                                          | Fetch and apply the latest log entries from the shared store. |
 | `put`                | `(key: TKey, value: TValue) => Promise<EntryId>`                                               | Insert with optimistic concurrency.                           |
+| `putMany`            | `(entries: readonly { key: TKey; value: TValue }[]) => Promise<EntryId[]>`                     | Batch insert with optimistic concurrency.                     |
 | `remove`             | `(key: TKey) => Promise<BTreeEntry<TKey, TValue> \| null>`                                     | Remove the first matching entry by key.                       |
 | `removeById`         | `(entryId: EntryId) => Promise<BTreeEntry<TKey, TValue> \| null>`                              | Remove a specific entry by ID.                                |
 | `peekById`           | `(entryId: EntryId) => Promise<BTreeEntry<TKey, TValue> \| null>`                              | Look up an entry by ID (syncs first).                         |
 | `updateById`         | `(entryId: EntryId, value: TValue) => Promise<BTreeEntry<TKey, TValue> \| null>`               | Update an entry by ID with optimistic concurrency.            |
 | `popFirst`           | `() => Promise<BTreeEntry<TKey, TValue> \| null>`                                              | Remove and return the smallest entry.                         |
 | `popLast`            | `() => Promise<BTreeEntry<TKey, TValue> \| null>`                                              | Remove and return the largest entry.                          |
+| `deleteRange`        | `(startKey: TKey, endKey: TKey, options?: RangeBounds) => Promise<number>`                     | Delete entries in range with optimistic concurrency.          |
+| `clear`              | `() => Promise<void>`                                                                          | Remove all entries with optimistic concurrency.               |
 | `peekFirst`          | `() => Promise<BTreeEntry<TKey, TValue> \| null>`                                              | Return the smallest entry (syncs first).                      |
 | `peekLast`           | `() => Promise<BTreeEntry<TKey, TValue> \| null>`                                              | Return the largest entry (syncs first).                       |
 | `findFirst`          | `(key: TKey) => Promise<BTreeEntry<TKey, TValue> \| null>`                                     | Return the first entry matching key (syncs first).            |
@@ -826,10 +850,19 @@ Exposes a subset of `InMemoryBTree` methods as async equivalents returning `Prom
 | `nextHigherKey`      | `(key: TKey) => Promise<TKey \| null>`                                                         | Next key strictly greater (syncs first).                      |
 | `nextLowerKey`       | `(key: TKey) => Promise<TKey \| null>`                                                         | Next key strictly less (syncs first).                         |
 | `getPairOrNextLower` | `(key: TKey) => Promise<BTreeEntry<TKey, TValue> \| null>`                                     | Exact match or next lower (syncs first).                      |
+| `entries`            | `() => Promise<BTreeEntry<TKey, TValue>[]>`                                                    | Return all entries as array (syncs first).                    |
+| `entriesReversed`    | `() => Promise<BTreeEntry<TKey, TValue>[]>`                                                    | Return all entries in reverse as array (syncs first).         |
+| `keys`               | `() => Promise<TKey[]>`                                                                        | Return all keys as array (syncs first).                       |
+| `values`             | `() => Promise<TValue[]>`                                                                      | Return all values as array (syncs first).                     |
+| `forEach`            | `(callback: (entry: BTreeEntry<TKey, TValue>) => void) => Promise<void>`                      | Iterate all entries (syncs first).                            |
 | `snapshot`           | `() => Promise<BTreeEntry<TKey, TValue>[]>`                                                    | Return all entries (syncs first).                             |
 | `size`               | `() => Promise<number>`                                                                        | Return entry count (syncs first).                             |
 | `getStats`           | `() => Promise<BTreeStats>`                                                                    | Return structural statistics (syncs first).                   |
 | `assertInvariants`   | `() => Promise<void>`                                                                          | Assert structural integrity (syncs first).                    |
+| `clone`              | `() => Promise<InMemoryBTree<TKey, TValue>>`                                                   | Return an independent local copy (syncs first).               |
+| `toJSON`             | `() => Promise<BTreeJSON<TKey, TValue>>`                                                       | Serialize to JSON (syncs first).                              |
+| `fromJSON` (static)  | `(json: BTreeJSON<TKey, TValue>, compareKeys: KeyComparator<TKey>) => InMemoryBTree<TKey, TValue>` | Deserialize from JSON (returns local tree).                |
+| `[Symbol.asyncIterator]` | `() => AsyncIterableIterator<BTreeEntry<TKey, TValue>>`                                    | Async iteration over all entries (syncs first).               |
 
 **Constructor:**
 
@@ -853,7 +886,7 @@ new ConcurrentInMemoryBTree<TKey, TValue>(config: ConcurrentInMemoryBTreeConfig<
 | `ConcurrentInMemoryBTreeConfig<TKey, TValue>` | Extends `InMemoryBTreeConfig<TKey>` with `store: SharedTreeStore<TKey, TValue>`, `maxRetries?: number`, `maxSyncMutationsPerBatch?: number`, and `readMode?: ReadMode`.             |
 | `SharedTreeStore<TKey, TValue>`               | Interface with `getLogEntriesSince(version)` and `append(expectedVersion, mutations)`.                                                                                              |
 | `SharedTreeLog<TKey, TValue>`                 | `{ version: bigint; mutations: BTreeMutation<TKey, TValue>[] }`                                                                                                                     |
-| `BTreeMutation<TKey, TValue>`                 | Discriminated union: `init`, `put`, `remove`, `removeById`, `updateById`, `popFirst`, `popLast`.                                                                                    |
+| `BTreeMutation<TKey, TValue>`                 | Discriminated union: `init`, `put`, `putMany`, `remove`, `removeById`, `updateById`, `popFirst`, `popLast`, `deleteRange`, `clear`.                                                |
 | `BTreeValidationError`                        | Error thrown for comparator or config violations.                                                                                                                                   |
 | `BTreeInvariantError`                         | Error thrown for tree structural integrity violations.                                                                                                                              |
 | `BTreeConcurrencyError`                       | Error thrown for concurrency conflicts or store contract violations.                                                                                                                |

package/dist/InMemoryBTree.d.ts

@@ -22,11 +22,37 @@ export declare class InMemoryBTree<TKey, TValue> {
     get(key: TKey): TValue | null;
     hasKey(key: TKey): boolean;
     findFirst(key: TKey): BTreeEntry<TKey, TValue> | null;
+    /**
+     * 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: TKey): BTreeEntry<TKey, TValue> | null;
+    /**
+     * Returns the smallest key in the tree that is strictly greater than `key`,
+     * or `null` if no such key exists.
+     */
     nextHigherKey(key: TKey): TKey | null;
+    /**
+     * Returns the largest key in the tree that is strictly less than `key`,
+     * or `null` if no such key exists.
+     */
     nextLowerKey(key: TKey): TKey | null;
+    /**
+     * 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: TKey): BTreeEntry<TKey, TValue> | null;
+    /**
+     * Returns the number of entries whose keys fall within [`startKey`, `endKey`].
+     * Pass `options` to make either bound exclusive.
+     */
     count(startKey: TKey, endKey: TKey, options?: RangeBounds): number;
+    /**
+     * Deletes all entries whose keys fall within [`startKey`, `endKey`].
+     * Pass `options` to make either bound exclusive.
+     * @returns The number of entries deleted.
+     */
     deleteRange(startKey: TKey, endKey: TKey, options?: RangeBounds): number;
     range(startKey: TKey, endKey: TKey, options?: RangeBounds): BTreeEntry<TKey, TValue>[];
     entries(): IterableIterator<BTreeEntry<TKey, TValue>>;
@@ -36,6 +62,13 @@ export declare class InMemoryBTree<TKey, TValue> {
     [Symbol.iterator](): IterableIterator<BTreeEntry<TKey, TValue>>;
     forEach(callback: (entry: BTreeEntry<TKey, TValue>) => void, thisArg?: unknown): void;
     snapshot(): BTreeEntry<TKey, TValue>[];
+    /**
+     * 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(): InMemoryBTree<TKey, TValue>;
     toJSON(): BTreeJSON<TKey, TValue>;
     static fromJSON<TKey, TValue>(json: BTreeJSON<TKey, TValue>, compareKeys: KeyComparator<TKey>): InMemoryBTree<TKey, TValue>;

package/dist/btree/autoScale.d.ts

@@ -1,4 +1,5 @@
 import { type BTreeState, type InMemoryBTreeConfig } from './types.js';
+export declare const minOccupancy: (max: number) => number;
 export declare const computeAutoScaleTier: (entryCount: number) => {
     readonly maxLeaf: number;
     readonly maxBranch: number;

package/dist/btree/node-ops.d.ts

@@ -0,0 +1,15 @@
+import type { BranchNode, BTreeNode, LeafEntry, LeafNode, NodeKey } from './types.js';
+export declare const createLeafNode: <TKey, TValue>(entries: LeafEntry<TKey, TValue>[], parent: BranchNode<TKey, TValue> | null) => LeafNode<TKey, TValue>;
+export declare const createBranchNode: <TKey, TValue>(children: BTreeNode<TKey, TValue>[], parent: BranchNode<TKey, TValue> | null) => BranchNode<TKey, TValue>;
+export declare const leafEntryCount: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => number;
+export declare const leafEntryAt: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, i: number) => LeafEntry<TKey, TValue>;
+export declare const leafShiftEntry: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => LeafEntry<TKey, TValue> | undefined;
+export declare const leafPopEntry: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => LeafEntry<TKey, TValue> | undefined;
+export declare const leafUnshiftEntry: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, entry: LeafEntry<TKey, TValue>) => void;
+export declare const leafRemoveAt: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, logicalIndex: number) => void;
+export declare const leafInsertAt: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, logicalIndex: number, entry: LeafEntry<TKey, TValue>) => void;
+export declare const leafCompact: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => void;
+export declare const branchCompact: <TKey, TValue>(branch: BranchNode<TKey, TValue>) => void;
+export declare const branchChildCount: <TKey, TValue>(branch: BranchNode<TKey, TValue>) => number;
+export declare const branchInsertAt: <TKey, TValue>(branch: BranchNode<TKey, TValue>, logicalIndex: number, child: BTreeNode<TKey, TValue>, key: NodeKey<TKey>) => void;
+export declare const branchRemoveAt: <TKey, TValue>(branch: BranchNode<TKey, TValue>, physIndex: number) => void;

package/dist/btree/rangeQuery.d.ts

@@ -1,3 +1,4 @@
 import { type BTreeEntry, type BTreeState, type RangeBounds } from './types.js';
+export declare function isEmptyRange<TKey>(compare: (a: TKey, b: TKey) => number, startKey: TKey, endKey: TKey, options?: RangeBounds): boolean;
 export declare const countRangeEntries: <TKey, TValue>(state: BTreeState<TKey, TValue>, startKey: TKey, endKey: TKey, options?: RangeBounds) => number;
 export declare const rangeQueryEntries: <TKey, TValue>(state: BTreeState<TKey, TValue>, startKey: TKey, endKey: TKey, options?: RangeBounds) => BTreeEntry<TKey, TValue>[];

package/dist/btree/serialization.d.ts

@@ -10,10 +10,6 @@ export interface BTreeJSON<TKey, TValue> {
     };
     entries: [TKey, TValue][];
 }
-export declare const collectEntryPairs: <TKey, TValue>(state: BTreeState<TKey, TValue>) => {
-    key: TKey;
-    value: TValue;
-}[];
 export declare const buildConfigFromState: <TKey, TValue>(state: BTreeState<TKey, TValue>) => InMemoryBTreeConfig<TKey>;
 export declare const serializeToJSON: <TKey, TValue>(state: BTreeState<TKey, TValue>) => BTreeJSON<TKey, TValue>;
 export declare const validateBTreeJSON: <TKey, TValue>(json: BTreeJSON<TKey, TValue>) => void;

package/dist/btree/types.d.ts

@@ -6,8 +6,14 @@ export declare const NODE_LEAF: 0;
 export declare const NODE_BRANCH: 1;
 export type KeyComparator<TKey> = (left: TKey, right: TKey) => number;
 export type DuplicateKeyPolicy = 'allow' | 'reject' | 'replace';
+/**
+ * Defines the inclusivity of the lower and upper bounds for a key range scan.
+ * Both bounds default to `'inclusive'` when omitted.
+ */
 export interface RangeBounds {
+    /** Lower bound type. Defaults to `'inclusive'` when omitted. */
     lowerBound?: 'inclusive' | 'exclusive';
+    /** Upper bound type. Defaults to `'inclusive'` when omitted. */
     upperBound?: 'inclusive' | 'exclusive';
 }
 export declare const normalizeDuplicateKeyPolicy: (value: DuplicateKeyPolicy | undefined) => DuplicateKeyPolicy;
@@ -29,6 +35,11 @@ export interface LeafEntry<TKey, TValue> {
     key: TKey;
     value: TValue;
 }
+/**
+ * Shallow-copies a `LeafEntry` into a plain `BTreeEntry` for safe public API return.
+ * Prevents callers from holding a reference that mutates when `updateById` is called.
+ */
+export declare const toPublicEntry: <TKey, TValue>(entry: LeafEntry<TKey, TValue>) => BTreeEntry<TKey, TValue>;
 export interface LeafNode<TKey, TValue> {
     kind: typeof NODE_LEAF;
     entries: LeafEntry<TKey, TValue>[];
@@ -85,29 +96,4 @@ export interface BTreeStats {
 export declare const isLeafNode: <TKey, TValue>(node: BTreeNode<TKey, TValue>) => node is LeafNode<TKey, TValue>;
 export declare const writeMinKeyTo: <TKey, TValue>(node: BTreeNode<TKey, TValue>, target: NodeKey<TKey>) => boolean;
 export declare const normalizeNodeCapacity: (value: number | undefined, field: string, defaultValue: number) => number;
-export declare const createLeafNode: <TKey, TValue>(entries: LeafEntry<TKey, TValue>[], parent: BranchNode<TKey, TValue> | null) => LeafNode<TKey, TValue>;
-export declare const createBranchNode: <TKey, TValue>(children: BTreeNode<TKey, TValue>[], parent: BranchNode<TKey, TValue> | null) => BranchNode<TKey, TValue>;
-/** Number of logical entries in the leaf */
-export declare const leafEntryCount: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => number;
-/** Get logical entry at index i (0-based from the logical start) */
-export declare const leafEntryAt: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, i: number) => LeafEntry<TKey, TValue>;
-/** Remove and return the first logical entry. O(1) amortized — increments offset and compacts when dead slots reach half. */
-export declare const leafShiftEntry: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => LeafEntry<TKey, TValue> | undefined;
-/** Remove and return the last logical entry. O(1) — pops from the backing array tail. */
-export declare const leafPopEntry: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => LeafEntry<TKey, TValue> | undefined;
-/** Prepend entry to logical start. Falls back to unshift if no gap, otherwise fills gap. */
-export declare const leafUnshiftEntry: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, entry: LeafEntry<TKey, TValue>) => void;
-/** Remove logical entry at index. Shifts the smaller side to halve average cost. */
-export declare const leafRemoveAt: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, logicalIndex: number) => void;
-/** Insert entry at logical index. Uses entryOffset gap when inserting in the first half. */
-export declare const leafInsertAt: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, logicalIndex: number, entry: LeafEntry<TKey, TValue>) => void;
-/** Compact the backing array — remove dead slots before entryOffset. Call before splits/merges. */
-export declare const leafCompact: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => void;
-/** Compact branch arrays — remove dead slots before childOffset, keeping a small gap. */
-export declare const branchCompact: <TKey, TValue>(branch: BranchNode<TKey, TValue>) => void;
-/** Number of logical children in the branch. */
-export declare const branchChildCount: <TKey, TValue>(branch: BranchNode<TKey, TValue>) => number;
-/** Insert a child at a logical index. Shifts the smaller side to halve average cost. */
-export declare const branchInsertAt: <TKey, TValue>(branch: BranchNode<TKey, TValue>, logicalIndex: number, child: BTreeNode<TKey, TValue>, key: NodeKey<TKey>) => void;
-/** Remove a child at a physical index. Shifts the smaller side. */
-export declare const branchRemoveAt: <TKey, TValue>(branch: BranchNode<TKey, TValue>, physIndex: number) => void;
+export { createLeafNode, createBranchNode, leafEntryCount, leafEntryAt, leafShiftEntry, leafPopEntry, leafUnshiftEntry, leafRemoveAt, leafInsertAt, leafCompact, branchCompact, branchChildCount, branchInsertAt, branchRemoveAt, } from './node-ops.js';