@optimystic/db-core 0.14.1 → 0.16.3

package/dist/src/blocks/block-store.d.ts

@@ -1,7 +1,24 @@
 import type { BlockType, IBlock, BlockId, BlockHeader, BlockOperation } from "./index.js";
+/** Why a block was read, used to filter the optimistic-concurrency conflict (read) set.
+ *
+ * - `value` — the transaction's result depends on this block's CONTENT (a leaf/entry, a log
+ *   entry, or an interior node whose keys/counts were used as data). Always retained.
+ * - `navigation` — an interior structural block (a B-tree branch) walked through ONLY to reach
+ *   a separately-captured `value` read further down the same descent. May be dropped from the
+ *   conflict set, because any concurrent restructuring that would change the queried result also
+ *   bumps the revision of a `value` block that stays in the set (the target leaf). See
+ *   docs/correctness.md Theorem 5.
+ *
+ * Defaults to `value` EVERYWHERE a read is captured, so an unclassified read is always retained
+ * (fail-safe): a forgotten tag can only cause an extra false-positive rejection, never a missed
+ * conflict. Only the B-tree point-lookup descent opts specific interior reads into `navigation`. */
+export type ReadPurpose = 'value' | 'navigation';
 export type BlockSource<T extends IBlock> = {
     createBlockHeader(type: BlockType, newId?: BlockId): BlockHeader;
-    tryGet(id: BlockId): Promise<T | undefined>;
+    /** Fetch a block by id. `purpose` classifies WHY the block is being read for OCC read-set
+     *  filtering (see {@link ReadPurpose}); it defaults to `value`, so existing callers that omit
+     *  it capture a retained read exactly as before. */
+    tryGet(id: BlockId, purpose?: ReadPurpose): Promise<T | undefined>;
     generateId(): BlockId;
 };
 export type BlockStore<T extends IBlock> = BlockSource<T> & {

package/dist/src/blocks/block-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"block-store.d.ts","sourceRoot":"","sources":["../../../src/blocks/block-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1F,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,IAAI;IAC3C,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IACjE,MAAM,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC5C,UAAU,IAAI,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG;IAC3D,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACvB,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CAAC;IACnD,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B,CAAC"}
+{"version":3,"file":"block-store.d.ts","sourceRoot":"","sources":["../../../src/blocks/block-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1F;;;;;;;;;;;;oGAYoG;AACpG,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,YAAY,CAAC;AAEjD,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,IAAI;IAC3C,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IACjE;;wDAEoD;IACpD,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACnE,UAAU,IAAI,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG;IAC3D,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACvB,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CAAC;IACnD,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B,CAAC"}

package/dist/src/blocks/helpers.d.ts

@@ -1,4 +1,4 @@
-import type { BlockOperation, IBlock, BlockId, BlockStore } from "../index.js";
-export declare function get<T extends IBlock>(store: BlockStore<T>, id: BlockId): Promise<T>;
+import type { BlockOperation, IBlock, BlockId, BlockStore, ReadPurpose } from "../index.js";
+export declare function get<T extends IBlock>(store: BlockStore<T>, id: BlockId, purpose?: ReadPurpose): Promise<T>;
 export declare function apply<T extends IBlock>(store: BlockStore<T>, block: IBlock, op: BlockOperation): void;
 //# sourceMappingURL=helpers.d.ts.map

package/dist/src/blocks/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/blocks/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG/E,wBAAsB,GAAG,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAIzF;AAED,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,QAG9F"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/blocks/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG5F,wBAAsB,GAAG,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAIhH;AAED,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,QAG9F"}

package/dist/src/blocks/helpers.js

@@ -1,6 +1,6 @@
 import { applyOperation } from "../transform/helpers.js";
-export async function get(store, id) {
-    const block = await store.tryGet(id);
+export async function get(store, id, purpose) {
+    const block = await store.tryGet(id, purpose);
     if (!block)
         throw Error(`Missing block (${id})`);
     return block;

package/dist/src/blocks/helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/blocks/helpers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD,MAAM,CAAC,KAAK,UAAU,GAAG,CAAmB,KAAoB,EAAE,EAAW;IAC5E,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACrC,IAAI,CAAC,KAAK;QAAE,MAAM,KAAK,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IACjD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,MAAM,UAAU,KAAK,CAAmB,KAAoB,EAAE,KAAa,EAAE,EAAkB;IAC9F,cAAc,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1B,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC"}
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/blocks/helpers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD,MAAM,CAAC,KAAK,UAAU,GAAG,CAAmB,KAAoB,EAAE,EAAW,EAAE,OAAqB;IACnG,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAC9C,IAAI,CAAC,KAAK;QAAE,MAAM,KAAK,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IACjD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,MAAM,UAAU,KAAK,CAAmB,KAAoB,EAAE,KAAa,EAAE,EAAkB;IAC9F,cAAc,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1B,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC"}

package/dist/src/btree/btree.d.ts

@@ -2,6 +2,7 @@ import { Path, type ITreeTrunk, type KeyRange, type getTrunkFunc } from "./index
 import type { BlockId, BlockStore } from "../blocks/index.js";
 import type { BranchNode, ITreeNode, LeafNode } from "./nodes.js";
 import type { TreeBlock } from "./tree-block.js";
+import { type AtomicScope } from "../transform/atomic-proxy.js";
 export declare const NodeCapacity = 64;
 /**
  * Represents a lightweight B+(ish)Tree (data at leaves, but no linked list of leaves).
@@ -14,24 +15,29 @@ export declare class BTree<TKey, TEntry> {
     readonly trunk: ITreeTrunk;
     readonly keyFromEntry: (entry: TEntry) => TKey;
     readonly compare: (a: TKey, b: TKey) => number;
+    readonly nodeCapacity: number;
     protected _version: number;
     private _proxy?;
     /**
      * @param [compare=(a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0] a comparison function for keys.  The default uses < and > operators.
      * @param [keyFromEntry=(entry: TEntry) => entry as unknown as TKey] a function to extract the key from an entry.  The default assumes the key is the entry itself.
      */
-    constructor(store: BlockStore<ITreeNode>, trunk: ITreeTrunk, keyFromEntry?: (entry: TEntry) => TKey, compare?: (a: TKey, b: TKey) => number);
+    constructor(store: BlockStore<ITreeNode>, trunk: ITreeTrunk, keyFromEntry?: (entry: TEntry) => TKey, compare?: (a: TKey, b: TKey) => number, nodeCapacity?: number);
     private atomic;
     static createRoot(store: BlockStore<ITreeNode>): LeafNode<never>;
-    static create<TKey, TEntry>(store: BlockStore<ITreeNode | TreeBlock>, createTrunk: getTrunkFunc, keyFromEntry?: (entry: TEntry) => TKey, compare?: (a: TKey, b: TKey) => 0 | 1 | -1, newId?: BlockId): BTree<TKey, TEntry>;
+    static create<TKey, TEntry>(store: BlockStore<ITreeNode | TreeBlock>, createTrunk: getTrunkFunc, keyFromEntry?: (entry: TEntry) => TKey, compare?: (a: TKey, b: TKey) => 0 | 1 | -1, nodeCapacity?: number, newId?: BlockId): BTree<TKey, TEntry>;
     /** @returns a path to the first entry (on = false if no entries) */
     first(): Promise<Path<TKey, TEntry>>;
     /** @returns a path to the last entry (on = false if no entries) */
     last(): Promise<Path<TKey, TEntry>>;
     /** Attempts to find the given key
      * @returns Path to the key or the "crack" before it.  If `on` is true on the resulting path, the key was found.
-     * 	If `on` is false, next() and prior() can attempt to move to the nearest match. */
-    find(key: TKey): Promise<Path<TKey, TEntry>>;
+     * 	If `on` is false, next() and prior() can attempt to move to the nearest match.
+     * @param navigate when true, the interior descent nodes are captured as droppable `navigation`
+     * 	reads (see {@link getPath}). DEFAULT false: `find` returns a Path a caller may use to seed a
+     * 	range scan (`ascending`/`next`), whose result depends on tree shape, so its structural reads
+     * 	must stay retained. Only {@link get} — a point lookup with no such escape — opts in. */
+    find(key: TKey, navigate?: boolean): Promise<Path<TKey, TEntry>>;
     /** Retrieves the entry for the given key.
      * Use find instead for a path to the key, the nearest match, or as a basis for navigation.
      * @returns the entry for the given key if found; undefined otherwise. */
@@ -44,6 +50,11 @@ export declare class BTree<TKey, TEntry> {
     range(range: KeyRange<TKey>): AsyncIterableIterator<Path<TKey, TEntry>>;
     /** @returns true if the given path remains valid; false if the tree has been mutated, invalidating the path. */
     isValid(path: Path<TKey, TEntry>): boolean;
+    /** Bump the version so every Path handed out before now reports invalid (see {@link isValid}).
+     * Needed when the tree's data was mutated through a DIFFERENT store binding than this instance —
+     * e.g. the tree collection's action handler writes through a per-action Atomic store, so this
+     * read-side btree never sees the mutation and must be told to invalidate outstanding paths. */
+    invalidatePaths(): void;
     /**
      * Adds a value to the tree.  Be sure to check the result, as the tree does not allow duplicate keys.
      * Added entries are frozen to ensure immutability
@@ -57,7 +68,7 @@ export declare class BTree<TKey, TEntry> {
      * 	* on = false if update/insert failed.
      * 		* wasUpdate = true, given path is not on an entry
      * 		* else newEntry's new key already present; returned path is "near" existing entry */
-    updateAt(path: Path<TKey, TEntry>, newEntry: TEntry): Promise<[path: Path<TKey, TEntry>, wasUpdate: boolean]>;
+    updateAt(path: Path<TKey, TEntry>, newEntry: TEntry, parent?: AtomicScope): Promise<[path: Path<TKey, TEntry>, wasUpdate: boolean]>;
     /** Inserts the entry if it doesn't exist, or updates it if it does.
      * The entry is frozen to ensure immutability.
      * @returns path to the new entry.  on = true if existing; on = false if new. */
@@ -104,7 +115,17 @@ export declare class BTree<TKey, TEntry> {
     private internalDescending;
     private findFirst;
     private findLast;
-    protected getPath(node: ITreeNode, key: TKey): Promise<Path<TKey, TEntry>>;
+    /** Descend from `node` toward `key`, building the path. When `navigate` is true this is a point
+     *  lookup (from {@link get}): each interior branch read below the root is captured as a droppable
+     *  `navigation` read, and the terminal leaf is upgraded back to a retained `value` read — the
+     *  result depends only on the leaf, and any concurrent restructuring that would change the result
+     *  also bumps the leaf's revision (Theorem 5), so the interior reads are redundant. When false
+     *  (find/range/scan/write descents) every read stays `value` (retained). */
+    protected getPath(node: ITreeNode, key: TKey, navigate?: boolean): Promise<Path<TKey, TEntry>>;
+    /** Upgrade a captured read of `id` to a retained `value` read via the store chain's read
+     *  collector (duck-typed — a no-op for stores without one, e.g. test doubles or log-walk
+     *  caches). Used by a point lookup to pin its terminal leaf. */
+    private markReadValue;
     private indexOfEntry;
     protected indexOfKey(keys: TKey[], key: TKey): number;
     private internalNext;

package/dist/src/btree/btree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"btree.d.ts","sourceRoot":"","sources":["../../../src/btree/btree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAc,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACjG,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAG9D,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B;;;;;GAKG;AACH,qBAAa,KAAK,CAAC,IAAI,EAAE,MAAM;aASb,KAAK,EAAE,UAAU,CAAC,SAAS,CAAC;aAC5B,KAAK,EAAE,UAAU;aACjB,YAAY,GAAI,OAAO,MAAM,KAAyB,IAAI;aAC1D,OAAO,GAAI,GAAG,IAAI,EAAE,GAAG,IAAI;IAX5C,SAAS,CAAC,QAAQ,SAAK;IACvB,OAAO,CAAC,MAAM,CAAC,CAAyB;IAExC;;;OAGG;gBAEc,KAAK,EAAE,UAAU,CAAC,SAAS,CAAC,EAC5B,KAAK,EAAE,UAAU,EACjB,YAAY,IAAI,OAAO,MAAM,KAAyB,IAAI,EAC1D,OAAO,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI,WAAyC;IAIrF,OAAO,CAAC,MAAM;IAId,MAAM,CAAC,UAAU,CAChB,KAAK,EAAE,UAAU,CAAC,SAAS,CAAC;IAK7B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EACzB,KAAK,EAAE,UAAU,CAAC,SAAS,GAAG,SAAS,CAAC,EACxC,WAAW,EAAE,YAAY,EACzB,YAAY,IAAI,OAAO,MAAM,KAAyB,IAAI,EAC1D,OAAO,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI,eAA+B,EAC1D,KAAK,CAAC,EAAE,OAAO;IAWhB,oEAAoE;IAC9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAI1C,mEAAmE;IAC7D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAIzC;;yFAEqF;IAC/E,IAAI,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAIlD;;6EAEyE;IACnE,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAIjD,iFAAiF;IACjF,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS;IAKhD;;MAEE;IACK,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IA4B9E,gHAAgH;IAChH,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;IAIhC;;;+EAG2E;IACrE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAWxD;;;;;;;6FAOyF;IACnF,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAcnH;;oFAEgF;IAC1E,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAcxD;;;;0GAIsG;IAChG,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAiBhI;;;MAGE;IACI,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAWpD,IAAI;IASV;;MAEE;IACF,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAK9E;;MAEE;IACF,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAK/E;;;OAGG;IACG,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBzF,yFAAyF;IACnF,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAMjE,8EAA8E;IACxE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;IAKvC,0FAA0F;IACpF,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAMlE,gFAAgF;IAC1E,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;IAKxC,wCAAwC;IACxC,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,IAAI;YAItC,iBAAiB;YAQjB,kBAAkB;YAQnB,SAAS;YAYT,QAAQ;cAYN,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAchF,OAAO,CAAC,YAAY;IAqBpB,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM;YAqBvC,YAAY;YAmCZ,aAAa;YA8Bb,cAAc;cAkBZ,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;YAqB5D,cAAc;YAWd,gBAAgB;IAe9B,iIAAiI;YACnH,WAAW;IAYzB,2HAA2H;YAC7G,UAAU;IAexB,kEAAkE;YACpD,QAAQ;IAYtB,qEAAqE;YACvD,OAAO;IAcrB,OAAO,CAAC,UAAU;YA+BJ,YAAY;cAqCV,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;cAmDtF,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAgExG,SAAS,CAAC,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI;IASlG,SAAS,CAAC,eAAe,CAAC,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,SAAI;IAK3G,SAAS,CAAC,eAAe,CAAC,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,SAAI;IAKjF,OAAO,CAAC,YAAY;IAMpB,iEAAiE;YAClD,OAAO;IAWtB,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM;IAIpD,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM;CAG7D"}
+{"version":3,"file":"btree.d.ts","sourceRoot":"","sources":["../../../src/btree/btree.ts"],"names":[],"mappings":"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"}

package/dist/src/btree/btree.js

@@ -14,30 +14,32 @@ export class BTree {
     trunk;
     keyFromEntry;
     compare;
+    nodeCapacity;
     _version = 0; // only for path invalidation
     _proxy;
     /**
      * @param [compare=(a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0] a comparison function for keys.  The default uses < and > operators.
      * @param [keyFromEntry=(entry: TEntry) => entry as unknown as TKey] a function to extract the key from an entry.  The default assumes the key is the entry itself.
      */
-    constructor(store, trunk, keyFromEntry = (entry) => entry, compare = (a, b) => a < b ? -1 : a > b ? 1 : 0) {
+    constructor(store, trunk, keyFromEntry = (entry) => entry, compare = (a, b) => a < b ? -1 : a > b ? 1 : 0, nodeCapacity = NodeCapacity) {
         this.store = store;
         this.trunk = trunk;
         this.keyFromEntry = keyFromEntry;
         this.compare = compare;
+        this.nodeCapacity = nodeCapacity;
     }
-    atomic(fn) {
-        return this._proxy ? this._proxy.atomic(fn) : fn();
+    atomic(fn, parent) {
+        return this._proxy ? this._proxy.atomic(fn, parent) : fn(parent);
     }
     static createRoot(store) {
         return newLeafNode(store, []);
     }
-    static create(store, createTrunk, keyFromEntry = (entry) => entry, compare = (a, b) => a < b ? -1 : a > b ? 1 : 0, newId) {
+    static create(store, createTrunk, keyFromEntry = (entry) => entry, compare = (a, b) => a < b ? -1 : a > b ? 1 : 0, nodeCapacity = NodeCapacity, newId) {
         const proxy = new AtomicProxy(store);
         const root = BTree.createRoot(proxy);
         proxy.insert(root);
         const trunk = createTrunk(proxy, root.header.id, newId);
-        const tree = new BTree(proxy, trunk, keyFromEntry, compare);
+        const tree = new BTree(proxy, trunk, keyFromEntry, compare, nodeCapacity);
         tree._proxy = proxy;
         return tree;
     }
@@ -51,15 +53,23 @@ export class BTree {
     }
     /** Attempts to find the given key
      * @returns Path to the key or the "crack" before it.  If `on` is true on the resulting path, the key was found.
-     * 	If `on` is false, next() and prior() can attempt to move to the nearest match. */
-    async find(key) {
-        return await this.getPath(await this.trunk.get(), key);
+     * 	If `on` is false, next() and prior() can attempt to move to the nearest match.
+     * @param navigate when true, the interior descent nodes are captured as droppable `navigation`
+     * 	reads (see {@link getPath}). DEFAULT false: `find` returns a Path a caller may use to seed a
+     * 	range scan (`ascending`/`next`), whose result depends on tree shape, so its structural reads
+     * 	must stay retained. Only {@link get} — a point lookup with no such escape — opts in. */
+    async find(key, navigate = false) {
+        return await this.getPath(await this.trunk.get(), key, navigate);
     }
     /** Retrieves the entry for the given key.
      * Use find instead for a path to the key, the nearest match, or as a basis for navigation.
      * @returns the entry for the given key if found; undefined otherwise. */
     async get(key) {
-        return this.at(await this.find(key));
+        // Value-of-key point lookup: the result depends ONLY on the terminal leaf's content, so the
+        // interior descent nodes are pure navigation and are dropped from the OCC conflict set. The
+        // returned Path is consumed by `at` and discarded — it never seeds a scan — so navigate=true
+        // is safe here (unlike the public `find`).
+        return this.at(await this.find(key, /* navigate */ true));
     }
     /** @returns the entry for the given path if on an entry; undefined otherwise. */
     at(path) {
@@ -97,6 +107,13 @@ export class BTree {
     isValid(path) {
         return path.version === this._version;
     }
+    /** Bump the version so every Path handed out before now reports invalid (see {@link isValid}).
+     * Needed when the tree's data was mutated through a DIFFERENT store binding than this instance —
+     * e.g. the tree collection's action handler writes through a per-action Atomic store, so this
+     * read-side btree never sees the mutation and must be told to invalidate outstanding paths. */
+    invalidatePaths() {
+        ++this._version;
+    }
     /**
      * Adds a value to the tree.  Be sure to check the result, as the tree does not allow duplicate keys.
      * Added entries are frozen to ensure immutability
@@ -119,7 +136,7 @@ export class BTree {
      * 	* on = false if update/insert failed.
      * 		* wasUpdate = true, given path is not on an entry
      * 		* else newEntry's new key already present; returned path is "near" existing entry */
-    async updateAt(path, newEntry) {
+    async updateAt(path, newEntry, parent) {
         return this.atomic(async () => {
             this.validatePath(path);
             if (path.on) {
@@ -130,7 +147,7 @@ export class BTree {
                 result[0].version = ++this._version;
             }
             return result;
-        });
+        }, parent);
     }
     /** Inserts the entry if it doesn't exist, or updates it if it does.
      * The entry is frozen to ensure immutability.
@@ -155,11 +172,13 @@ export class BTree {
      * @returns path to new entry and whether an update or insert attempted.
      * If getUpdated callback returns a row that is already present, the resulting path will not be on. */
     async merge(newEntry, getUpdated) {
-        return this.atomic(async () => {
-            const newKey = await this.keyFromEntry(newEntry);
+        return this.atomic(async (scope) => {
+            const newKey = this.keyFromEntry(newEntry);
             const path = await this.find(newKey);
             if (path.on) {
-                const result = await this.updateAt(path, getUpdated(this.getEntry(path))); // Don't use internalUpdate - need to freeze and check for mutation
+                // Thread this scope into updateAt so the nested call joins this atomic batch
+                // (reuses the tracker) rather than opening/committing a second scope.
+                const result = await this.updateAt(path, getUpdated(this.getEntry(path)), scope); // Don't use internalUpdate - need to freeze and check for mutation
                 // Note: updateAt already increments version, so don't double-increment here
                 return result;
             }
@@ -244,7 +263,7 @@ export class BTree {
     /** @returns a path one step backward.  on will be true if the path hasn't hit the end. */
     async prior(path) {
         const newPath = path.clone();
-        this.movePrior(newPath);
+        await this.movePrior(newPath);
         return newPath;
     }
     /** Attempts to advance the given path one step backwards. (mutates the path) */
@@ -294,20 +313,39 @@ export class BTree {
         }
         return endPath;
     }
-    async getPath(node, key) {
+    /** Descend from `node` toward `key`, building the path. When `navigate` is true this is a point
+     *  lookup (from {@link get}): each interior branch read below the root is captured as a droppable
+     *  `navigation` read, and the terminal leaf is upgraded back to a retained `value` read — the
+     *  result depends only on the leaf, and any concurrent restructuring that would change the result
+     *  also bumps the leaf's revision (Theorem 5), so the interior reads are redundant. When false
+     *  (find/range/scan/write descents) every read stays `value` (retained). */
+    async getPath(node, key, navigate = false) {
         if (node.header.type === TreeLeafBlockType) {
             const leaf = node;
+            if (navigate) {
+                // The leaf ends a point-lookup descent: its content is the load-bearing VALUE read.
+                // Its parent fetched it as `navigation` (a child's type is unknown before reading);
+                // upgrade it (value-wins) so it is retained while the interior nodes above are dropped.
+                this.markReadValue(leaf.header.id);
+            }
             const [on, index] = this.indexOfEntry(leaf.entries, key);
             return new Path([], leaf, index, on, this._version);
         }
         else {
             const branch = node;
             const index = this.indexOfKey(branch.partitions, key);
-            const path = await this.getPath(await get(this.store, branch.nodes[index]), key);
+            const child = await get(this.store, branch.nodes[index], navigate ? 'navigation' : 'value');
+            const path = await this.getPath(child, key, navigate);
             path.branches.unshift(new PathBranch(branch, index));
             return path;
         }
     }
+    /** Upgrade a captured read of `id` to a retained `value` read via the store chain's read
+     *  collector (duck-typed — a no-op for stores without one, e.g. test doubles or log-walk
+     *  caches). Used by a point lookup to pin its terminal leaf. */
+    markReadValue(id) {
+        this.store.markReadValue?.(id);
+    }
     indexOfEntry(entries, key) {
         let lo = 0;
         let hi = entries.length - 1;
@@ -346,35 +384,36 @@ export class BTree {
         if (!path.on) { // Attempt to move off of crack
             path.on = path.branches.every(branch => branch.index >= 0 && branch.index < branch.node.nodes.length)
                 && path.leafIndex >= 0 && path.leafIndex < path.leafNode.entries.length;
-            if (path.on) {
-                return;
+            if (path.on || path.leafIndex < path.leafNode.entries.length) {
+                return; // got on an entry, or an interior crack — nothing to advance into
             }
+            // end-of-leaf crack (leafIndex === entries.length): fall through to branch-popping leaf-advance
         }
-        else if (path.leafIndex >= path.leafNode.entries.length - 1) {
-            let popCount = 0;
-            let found = false;
-            const last = path.branches.length - 1;
-            while (popCount <= last && !found) {
-                const branch = path.branches[last - popCount];
-                if (branch.index === branch.node.partitions.length) // last node in branch
-                    ++popCount;
-                else
-                    found = true;
-            }
-            if (!found) {
-                path.leafIndex = path.leafNode.entries.length; // after last row = end crack
-                path.on = false;
-            }
-            else {
-                path.branches.splice(-popCount, popCount);
-                const branch = path.branches.at(-1);
-                ++branch.index;
-                this.moveToFirst(await get(this.store, branch.node.nodes[branch.index]), path);
-            }
-        }
-        else {
+        else if (path.leafIndex < path.leafNode.entries.length - 1) {
             ++path.leafIndex;
             path.on = true;
+            return;
+        }
+        // on the last entry of the leaf, or off an end-of-leaf crack: advance into the next leaf
+        let popCount = 0;
+        let found = false;
+        const last = path.branches.length - 1;
+        while (popCount <= last && !found) {
+            const branch = path.branches[last - popCount];
+            if (branch.index === branch.node.partitions.length) // last node in branch
+                ++popCount;
+            else
+                found = true;
+        }
+        if (!found) {
+            path.leafIndex = path.leafNode.entries.length; // after last row = end crack
+            path.on = false;
+        }
+        else {
+            path.branches.splice(-popCount, popCount);
+            const branch = path.branches.at(-1);
+            ++branch.index;
+            await this.moveToFirst(await get(this.store, branch.node.nodes[branch.index]), path);
         }
     }
     async internalPrior(path) {
@@ -413,7 +452,7 @@ export class BTree {
             if (this.compare(oldKey, newKey) !== 0) { // if key changed, delete and re-insert
                 let newPath = await this.internalInsert(newEntry);
                 if (newPath.on) { // insert succeeded
-                    this.internalDelete(await this.find(oldKey)); // Re-find - the prior insert invalidated the path
+                    await this.internalDelete(await this.find(oldKey)); // Re-find - the prior insert invalidated the path
                     newPath = await this.find(newKey); // Re-find- delete invalidated path
                 }
                 return [newPath, false];
@@ -463,7 +502,7 @@ export class BTree {
         }
         if (split) {
             const newBranch = newBranchNode(this.store, [split.key], [await this.trunk.getId(), split.right.header.id]);
-            await this.store.insert(newBranch);
+            this.store.insert(newBranch);
             await this.trunk.set(newBranch);
             path.branches.unshift(new PathBranch(newBranch, split.indexDelta));
         }
@@ -527,7 +566,7 @@ export class BTree {
     }
     leafInsert(path, entry) {
         const { leafNode: leaf, leafIndex: index } = path;
-        if (leaf.entries.length < NodeCapacity) { // No split needed
+        if (leaf.entries.length < this.nodeCapacity) { // No split needed
             apply(this.store, leaf, [entries$, index, 0, [entry]]);
             return undefined;
         }
@@ -555,7 +594,7 @@ export class BTree {
         const pathBranch = path.branches[branchIndex];
         const { index: splitIndex, node } = pathBranch;
         pathBranch.index += split.indexDelta;
-        if (node.nodes.length < NodeCapacity) { // no split needed
+        if (node.nodes.length < this.nodeCapacity) { // no split needed
             apply(this.store, node, [partitions$, splitIndex, 0, [split.key]]);
             apply(this.store, node, [nodes$, splitIndex + 1, 0, [split.right.header.id]]);
             return undefined;
@@ -572,6 +611,7 @@ export class BTree {
             newNodes.splice(pathBranch.index + 1, 0, split.right.header.id);
         }
         const newBranch = newBranchNode(this.store, newPartitions, newNodes);
+        this.store.insert(newBranch);
         // Delete partitions and nodes
         const newPartition = node.partitions[midIndex - 1];
         apply(this.store, node, [partitions$, midIndex - 1, newPartitions.length + 1, []]);
@@ -583,7 +623,7 @@ export class BTree {
         return new Split(newPartition, newBranch, delta);
     }
     async rebalanceLeaf(path, depth) {
-        if (depth === 0 || path.leafNode.entries.length >= (NodeCapacity >>> 1)) {
+        if (depth === 0 || path.leafNode.entries.length >= (this.nodeCapacity >>> 1)) {
             return undefined;
         }
         const leaf = path.leafNode;
@@ -592,16 +632,16 @@ export class BTree {
         const pNode = parent.node;
         const rightSibId = pNode.nodes[pIndex + 1];
         const rightSib = rightSibId ? (await get(this.store, rightSibId)) : undefined;
-        if (rightSib && rightSib.entries.length > (NodeCapacity >>> 1)) { // Attempt to borrow from right sibling
+        if (rightSib && rightSib.entries.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from right sibling
             const entry = rightSib.entries[0];
             apply(this.store, rightSib, [entries$, 0, 1, []]);
             apply(this.store, leaf, [entries$, leaf.entries.length, 0, [entry]]);
-            this.updatePartition(pIndex + 1, path, depth - 1, this.keyFromEntry(entry));
+            this.updatePartition(pIndex + 1, path, depth - 1, this.keyFromEntry(rightSib.entries[0]));
             return undefined;
         }
         const leftSibId = pNode.nodes[pIndex - 1];
         const leftSib = leftSibId ? (await get(this.store, leftSibId)) : undefined;
-        if (leftSib && leftSib.entries.length > (NodeCapacity >>> 1)) { // Attempt to borrow from left sibling
+        if (leftSib && leftSib.entries.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from left sibling
             const entry = leftSib.entries[leftSib.entries.length - 1];
             apply(this.store, leftSib, [entries$, leftSib.entries.length - 1, 1, []]);
             apply(this.store, leaf, [entries$, 0, 0, [entry]]);
@@ -609,7 +649,7 @@ export class BTree {
             path.leafIndex += 1;
             return undefined;
         }
-        if (rightSib && rightSib.entries.length + leaf.entries.length <= NodeCapacity) { // Attempt to merge right sibling into leaf (right sib deleted)
+        if (rightSib && rightSib.entries.length + leaf.entries.length <= this.nodeCapacity) { // Attempt to merge right sibling into leaf (right sib deleted)
             apply(this.store, leaf, [entries$, leaf.entries.length, 0, rightSib.entries]);
             this.deletePartition(pNode, pIndex);
             if (pIndex === 0) { // 0th node of parent, update parent key
@@ -618,7 +658,12 @@ export class BTree {
             this.store.delete(rightSib.header.id);
             return await this.rebalanceBranch(path, depth - 1);
         }
-        if (leftSib && leftSib.entries.length + leaf.entries.length <= NodeCapacity) { // Attempt to merge into left sibling (leaf deleted)
+        if (leftSib && leftSib.entries.length + leaf.entries.length <= this.nodeCapacity) { // Attempt to merge into left sibling (leaf deleted)
+            // NOTE: this fixes leafIndex, but the parent-branch index up the path is left pointing at
+            // the now-deleted leaf's old slot (same tolerated-staleness class as rebalanceBranch's
+            // left-merge, part c). Harmless today because deleteAt version-bumps and abandons the
+            // returned path. A future path-reuse consumer must audit BOTH left-merge sites, not just
+            // rebalanceBranch.
             path.leafNode = leftSib;
             path.leafIndex += leftSib.entries.length;
             apply(this.store, leftSib, [entries$, leftSib.entries.length, 0, leaf.entries]);
@@ -633,7 +678,7 @@ export class BTree {
         if (depth === 0 && branch.partitions.length === 0) { // last node... collapse child into root
             return path.branches[depth + 1]?.node ?? path.leafNode;
         }
-        if (depth === 0 || (branch.nodes.length >= NodeCapacity >>> 1)) {
+        if (depth === 0 || (branch.nodes.length >= this.nodeCapacity >>> 1)) {
             return undefined;
         }
         const parent = path.branches.at(depth - 1);
@@ -641,7 +686,7 @@ export class BTree {
         const pNode = parent.node;
         const rightSibId = pNode.nodes[pIndex + 1];
         const rightSib = rightSibId ? (await get(this.store, rightSibId)) : undefined;
-        if (rightSib && rightSib.nodes.length > (NodeCapacity >>> 1)) { // Attempt to borrow from right sibling
+        if (rightSib && rightSib.nodes.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from right sibling
             const node = rightSib.nodes[0];
             const rightKey = rightSib.partitions[0];
             this.insertPartition(branch, branch.partitions.length, pNode.partitions[pIndex], node);
@@ -651,7 +696,7 @@ export class BTree {
         }
         const leftSibId = pNode.nodes[pIndex - 1];
         const leftSib = leftSibId ? (await get(this.store, leftSibId)) : undefined;
-        if (leftSib && leftSib.nodes.length > (NodeCapacity >>> 1)) { // Attempt to borrow from left sibling
+        if (leftSib && leftSib.nodes.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from left sibling
             const node = leftSib.nodes[leftSib.nodes.length - 1];
             const pKey = leftSib.partitions[leftSib.partitions.length - 1];
             this.insertPartition(branch, 0, pNode.partitions[pIndex - 1], node, 0);
@@ -660,26 +705,24 @@ export class BTree {
             this.updatePartition(pIndex, path, depth - 1, pKey);
             return undefined;
         }
-        if (rightSib && rightSib.nodes.length + branch.nodes.length <= NodeCapacity) { // Attempt to merge right sibling into self
+        if (rightSib && rightSib.nodes.length + branch.nodes.length <= this.nodeCapacity) { // Attempt to merge right sibling into self
             const pKey = pNode.partitions[pIndex];
             this.deletePartition(pNode, pIndex);
             apply(this.store, branch, [partitions$, branch.partitions.length, 0, [pKey]]);
             apply(this.store, branch, [partitions$, branch.partitions.length, 0, rightSib.partitions]);
             apply(this.store, branch, [nodes$, branch.nodes.length, 0, rightSib.nodes]);
-            if (pIndex === 0 && pNode.partitions.length > 0) { // if parent is left edge, new right sibling is now the first partition
-                this.updatePartition(pIndex, path, depth - 1, pNode.partitions[0]);
-            }
             this.store.delete(rightSib.header.id);
             return this.rebalanceBranch(path, depth - 1);
         }
-        if (leftSib && leftSib.nodes.length + branch.nodes.length <= NodeCapacity) { // Attempt to merge self into left sibling
+        if (leftSib && leftSib.nodes.length + branch.nodes.length <= this.nodeCapacity) { // Attempt to merge self into left sibling
+            const leftLen = leftSib.nodes.length; // capture BEFORE the appends below shift it (see leaf path at rebalanceLeaf)
             const pKey = pNode.partitions[pIndex - 1];
             this.deletePartition(pNode, pIndex - 1);
             apply(this.store, leftSib, [partitions$, leftSib.partitions.length, 0, [pKey]]);
             apply(this.store, leftSib, [partitions$, leftSib.partitions.length, 0, branch.partitions]);
             apply(this.store, leftSib, [nodes$, leftSib.nodes.length, 0, branch.nodes]);
             pathBranch.node = leftSib;
-            pathBranch.index += leftSib.nodes.length;
+            pathBranch.index += leftLen; // branch's children now sit after leftSib's original children
             this.store.delete(branch.header.id);
             return this.rebalanceBranch(path, depth - 1);
         }