@optimystic/db-core 0.14.1 → 0.16.3

package/dist/src/transform/tracker.js.map

@@ -1 +1 @@
-{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../../../src/transform/tracker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../../../src/transform/tracker.ts"],"names":[],"mappings":"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"}

package/dist/src/utility/backoff.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Jittered exponential backoff shared by the retry loops in db-core
+ * ({@link Collection.sync} and {@link TransactionCoordinator.commit}).
+ *
+ * The point of the jitter is fairness under contention: when many clients lose the SAME
+ * optimistic-concurrency race at t=0, a bare exponential curve makes them all re-attempt at the
+ * identical next tick — a thundering herd that just re-collides. Multiplying the exponential value
+ * by a random factor spreads those re-attempts across a window so offered load per tick sheds
+ * instead of cascading. This is the same shape as `cohort-topic`'s `backoffRetryMs`, with the
+ * proportional-jitter term added.
+ */
+/** A source of uniform randomness in [0, 1). Injected in tests so a deterministic sequence can be
+ * asserted; production uses {@link cryptoRand}. */
+export type RandFn = () => number;
+/** Uniform value in [0, 1) drawn from the same CSPRNG (`@noble/hashes` `randomBytes`) the rest of
+ * db-core uses — deliberately NOT `Math.random`, so backoff jitter shares the package's randomness
+ * source rather than introducing a second, weaker one. */
+export declare function cryptoRand(): number;
+export interface JitteredBackoffConfig {
+    /** Base delay (ms) for attempt 0, before jitter. */
+    baseMs: number;
+    /** Hard ceiling (ms) on the pre-jitter exponential value. */
+    capMs: number;
+    /** Geometric growth per attempt. Default 2 (doubling). */
+    factor?: number;
+    /** Fraction of the exponential value that jitter may subtract, in [0, 1]. Default 0.5, so the
+     * returned delay lands uniformly in `((1 - jitterFraction) · exp, exp]` — i.e. `(0.5·exp, exp]`. */
+    jitterFraction?: number;
+}
+/**
+ * Delay (ms) for retry `attempt` (0-based):
+ *
+ *   exp   = min(baseMs · factor^attempt, capMs)
+ *   delay = exp · (1 - jitterFraction · rand())     // rand() ∈ [0, 1)
+ *
+ * With the defaults (factor 2, jitterFraction 0.5) the delay is uniform in `(0.5·exp, exp]`: never
+ * zero (as long as `baseMs > 0`) and never above `capMs`. `attempt` must be a non-negative integer
+ * — pass `consecutiveFailures - 1` so the first retry backs off by ~`baseMs`.
+ */
+export declare function jitteredBackoffMs(attempt: number, config: JitteredBackoffConfig, rand?: RandFn): number;
+/** Build an AbortError for a cooperatively-aborted wait. Prefers the signal's own reason when it is
+ * an Error (so callers who passed a custom abort reason see it), otherwise a `name='AbortError'`
+ * Error. */
+export declare function makeAbortError(signal?: AbortSignal): Error;
+/** Sleep for `ms`, resolving early (rejecting with an AbortError) if `signal` aborts — so a retry
+ * loop waiting out a backoff rejects promptly instead of finishing the sleep. */
+export declare function abortableDelay(ms: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/src/utility/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../../src/utility/backoff.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH;mDACmD;AACnD,MAAM,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC;AAElC;;0DAE0D;AAC1D,wBAAgB,UAAU,IAAI,MAAM,CAKnC;AAED,MAAM,WAAW,qBAAqB;IACrC,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;wGACoG;IACpG,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,qBAAqB,EAC7B,IAAI,GAAE,MAAmB,GACvB,MAAM,CAQR;AAED;;YAEY;AACZ,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAO1D;AAED;iFACiF;AACjF,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB9E"}

package/dist/src/utility/backoff.js

@@ -0,0 +1,60 @@
+import { randomBytes } from '@noble/hashes/utils.js';
+/** Uniform value in [0, 1) drawn from the same CSPRNG (`@noble/hashes` `randomBytes`) the rest of
+ * db-core uses — deliberately NOT `Math.random`, so backoff jitter shares the package's randomness
+ * source rather than introducing a second, weaker one. */
+export function cryptoRand() {
+    const b = randomBytes(4);
+    // Assemble a uint32 (>>> 0 clears the sign bit the shifts would otherwise set), then normalise.
+    const u = (((b[0] << 24) | (b[1] << 16) | (b[2] << 8) | b[3]) >>> 0);
+    return u / 0x1_0000_0000;
+}
+/**
+ * Delay (ms) for retry `attempt` (0-based):
+ *
+ *   exp   = min(baseMs · factor^attempt, capMs)
+ *   delay = exp · (1 - jitterFraction · rand())     // rand() ∈ [0, 1)
+ *
+ * With the defaults (factor 2, jitterFraction 0.5) the delay is uniform in `(0.5·exp, exp]`: never
+ * zero (as long as `baseMs > 0`) and never above `capMs`. `attempt` must be a non-negative integer
+ * — pass `consecutiveFailures - 1` so the first retry backs off by ~`baseMs`.
+ */
+export function jitteredBackoffMs(attempt, config, rand = cryptoRand) {
+    if (!Number.isInteger(attempt) || attempt < 0) {
+        throw new RangeError(`attempt must be a non-negative integer, got ${attempt}`);
+    }
+    const factor = config.factor ?? 2;
+    const jitterFraction = config.jitterFraction ?? 0.5;
+    const exp = Math.min(config.baseMs * factor ** attempt, config.capMs);
+    return exp * (1 - jitterFraction * rand());
+}
+/** Build an AbortError for a cooperatively-aborted wait. Prefers the signal's own reason when it is
+ * an Error (so callers who passed a custom abort reason see it), otherwise a `name='AbortError'`
+ * Error. */
+export function makeAbortError(signal) {
+    if (signal && signal.reason instanceof Error) {
+        return signal.reason;
+    }
+    const err = new Error('The operation was aborted');
+    err.name = 'AbortError';
+    return err;
+}
+/** Sleep for `ms`, resolving early (rejecting with an AbortError) if `signal` aborts — so a retry
+ * loop waiting out a backoff rejects promptly instead of finishing the sleep. */
+export function abortableDelay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(makeAbortError(signal));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(makeAbortError(signal));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=backoff.js.map

package/dist/src/utility/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../../src/utility/backoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAkBrD;;0DAE0D;AAC1D,MAAM,UAAU,UAAU;IACzB,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IACzB,gGAAgG;IAChG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAE,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IACzE,OAAO,CAAC,GAAG,aAAa,CAAC;AAC1B,CAAC;AAcD;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAChC,OAAe,EACf,MAA6B,EAC7B,OAAe,UAAU;IAEzB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,UAAU,CAAC,+CAA+C,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;IAClC,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,IAAI,GAAG,CAAC;IACpD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,IAAI,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IACtE,OAAO,GAAG,GAAG,CAAC,CAAC,GAAG,cAAc,GAAG,IAAI,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED;;YAEY;AACZ,MAAM,UAAU,cAAc,CAAC,MAAoB;IAClD,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,YAAY,KAAK,EAAE,CAAC;QAC9C,OAAO,MAAM,CAAC,MAAM,CAAC;IACtB,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IACnD,GAAG,CAAC,IAAI,GAAG,YAAY,CAAC;IACxB,OAAO,GAAG,CAAC;AACZ,CAAC;AAED;iFACiF;AACjF,MAAM,UAAU,cAAc,CAAC,EAAU,EAAE,MAAoB;IAC9D,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC5C,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACrB,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;YAC/B,OAAO;QACR,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,EAAE;YACpB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,cAAc,CAAC,MAAO,CAAC,CAAC,CAAC;QACjC,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC7B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9C,OAAO,EAAE,CAAC;QACX,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;AACJ,CAAC"}

package/dist/src/utility/pending.d.ts

@@ -2,6 +2,7 @@ export declare class Pending<T> {
     promise: Promise<T>;
     response?: T;
     error?: unknown;
+    private _responded;
     t1: number;
     duration?: number;
     get isResponse(): boolean;

package/dist/src/utility/pending.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pending.d.ts","sourceRoot":"","sources":["../../../src/utility/pending.ts"],"names":[],"mappings":"AAAA,qBAAa,OAAO,CAAC,CAAC;IA6Bb,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IA5B3B,QAAQ,CAAC,EAAE,CAAC,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,EAAE,SAAc;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAEK,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC;gBAWlB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;CAW3B"}
+{"version":3,"file":"pending.d.ts","sourceRoot":"","sources":["../../../src/utility/pending.ts"],"names":[],"mappings":"AAAA,qBAAa,OAAO,CAAC,CAAC;IA8Bb,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IA7B3B,QAAQ,CAAC,EAAE,CAAC,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,UAAU,CAAS;IAC3B,EAAE,SAAc;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAEK,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC;gBAWlB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;CAY3B"}

package/dist/src/utility/pending.js

@@ -2,10 +2,11 @@ export class Pending {
     promise;
     response;
     error;
+    _responded = false;
     t1 = Date.now();
     duration;
     get isResponse() {
-        return this.response !== undefined;
+        return this._responded;
     }
     get isError() {
         return this.error !== undefined;
@@ -27,6 +28,7 @@ export class Pending {
         promise.then(response => {
             this.duration = Date.now() - this.t1;
             this.response = response;
+            this._responded = true;
             return response;
         }, error => {
             this.duration = Date.now() - this.t1;

package/dist/src/utility/pending.js.map

@@ -1 +1 @@
-{"version":3,"file":"pending.js","sourceRoot":"","sources":["../../../src/utility/pending.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,OAAO;IA6BX;IA5BR,QAAQ,CAAK;IACb,KAAK,CAAW;IAChB,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAChB,QAAQ,CAAU;IAElB,IAAI,UAAU;QACb,OAAO,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC;IACpC,CAAC;IAED,IAAI,OAAO;QACV,OAAO,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC;IACjC,CAAC;IAED,IAAI,UAAU;QACb,OAAO,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,MAAM;QACX,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC,QAAS,CAAC;QACvB,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,CAAC,KAAM,CAAC;QACnB,CAAC;QACD,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC;IAC3B,CAAC;IAED,YACQ,OAAmB;QAAnB,YAAO,GAAP,OAAO,CAAY;QAE1B,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE;YACvB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;YACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;YACzB,OAAO,QAAQ,CAAC;QACjB,CAAC,EAAE,KAAK,CAAC,EAAE;YACV,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;YACrC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACpB,CAAC,CAAC,CAAC;IACJ,CAAC;CACD"}
+{"version":3,"file":"pending.js","sourceRoot":"","sources":["../../../src/utility/pending.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,OAAO;IA8BX;IA7BR,QAAQ,CAAK;IACb,KAAK,CAAW;IACR,UAAU,GAAG,KAAK,CAAC;IAC3B,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAChB,QAAQ,CAAU;IAElB,IAAI,UAAU;QACb,OAAO,IAAI,CAAC,UAAU,CAAC;IACxB,CAAC;IAED,IAAI,OAAO;QACV,OAAO,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC;IACjC,CAAC;IAED,IAAI,UAAU;QACb,OAAO,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,MAAM;QACX,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC,QAAS,CAAC;QACvB,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,CAAC,KAAM,CAAC;QACnB,CAAC;QACD,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC;IAC3B,CAAC;IAED,YACQ,OAAmB;QAAnB,YAAO,GAAP,OAAO,CAAY;QAE1B,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE;YACvB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;YACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;YACzB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,OAAO,QAAQ,CAAC;QACjB,CAAC,EAAE,KAAK,CAAC,EAAE;YACV,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;YACrC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACpB,CAAC,CAAC,CAAC;IACJ,CAAC;CACD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optimystic/db-core",
-  "version": "0.14.1",
+  "version": "0.16.3",
   "type": "module",
   "description": "Core database functionality for Optimystic",
   "main": "dist/src/index.js",
@@ -17,8 +17,8 @@
       "import": "./dist/src/index.js"
     },
     "./test": {
-      "types": "./dist/test/test-transactor.d.ts",
-      "import": "./dist/test/test-transactor.js"
+      "types": "./dist/src/testing/index.d.ts",
+      "import": "./dist/src/testing/index.js"
     }
   },
   "repository": {
@@ -68,6 +68,6 @@
     "@noble/hashes": "^2.0.1",
     "debug": "^4.4.3",
     "multiformats": "^13.4.2",
-    "uint8arrays": "^5.1.0"
+    "uint8arrays": "^6.1.1"
   }
 }

package/src/blocks/block-store.ts

@@ -1,8 +1,26 @@
 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;
 };
 

package/src/blocks/helpers.ts

@@ -1,8 +1,8 @@
-import type { BlockOperation, IBlock, BlockId, BlockStore } from "../index.js";
+import type { BlockOperation, IBlock, BlockId, BlockStore, ReadPurpose } from "../index.js";
 import { applyOperation } from "../transform/helpers.js";
 
-export async function get<T extends IBlock>(store: BlockStore<T>, id: BlockId): Promise<T> {
-	const block = await store.tryGet(id);
+export async function get<T extends IBlock>(store: BlockStore<T>, id: BlockId, purpose?: ReadPurpose): Promise<T> {
+	const block = await store.tryGet(id, purpose);
 	if (!block) throw Error(`Missing block (${id})`);
 	return block;
 }

package/src/btree/btree.ts

@@ -4,7 +4,7 @@ import { apply, get } from "../blocks/index.js";
 import { TreeLeafBlockType, TreeBranchBlockType, entries$, nodes$, partitions$ } from "./nodes.js";
 import type { BranchNode, ITreeNode, LeafNode } from "./nodes.js";
 import type { TreeBlock } from "./tree-block.js";
-import { AtomicProxy } from "../transform/atomic-proxy.js";
+import { AtomicProxy, type AtomicScope } from "../transform/atomic-proxy.js";
 
 export const NodeCapacity = 64;
 
@@ -27,11 +27,12 @@ export class BTree<TKey, TEntry> {
 		public readonly trunk: ITreeTrunk,
 		public readonly keyFromEntry = (entry: TEntry) => entry as unknown as TKey,
 		public readonly compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0 as number,
+		public readonly nodeCapacity = NodeCapacity,
 	) {
 	}
 
-	private atomic<T>(fn: () => Promise<T>): Promise<T> {
-		return this._proxy ? this._proxy.atomic(fn) : fn();
+	private atomic<T>(fn: (scope?: AtomicScope) => Promise<T>, parent?: AtomicScope): Promise<T> {
+		return this._proxy ? this._proxy.atomic(fn, parent) : fn(parent);
 	}
 
 	static createRoot(
@@ -45,13 +46,14 @@ export class BTree<TKey, TEntry> {
 		createTrunk: getTrunkFunc,
 		keyFromEntry = (entry: TEntry) => entry as unknown as TKey,
 		compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0,
+		nodeCapacity = NodeCapacity,
 		newId?: BlockId,
 	) {
 		const proxy = new AtomicProxy(store);
 		const root = BTree.createRoot(proxy as BlockStore<TreeBlock>);
 		proxy.insert(root);
 		const trunk = createTrunk(proxy as BlockStore<TreeBlock>, 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;
 	}
@@ -68,16 +70,24 @@ export class BTree<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. */
-	async find(key: TKey): Promise<Path<TKey, TEntry>> {
-		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: TKey, navigate = false): Promise<Path<TKey, TEntry>> {
+		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: TKey): Promise<TEntry | undefined> {
-		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. */
@@ -122,6 +132,14 @@ export class BTree<TKey, TEntry> {
 		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
@@ -145,7 +163,7 @@ export 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 */
-	async updateAt(path: Path<TKey, TEntry>, newEntry: TEntry): Promise<[path: Path<TKey, TEntry>, wasUpdate: boolean]> {
+	async updateAt(path: Path<TKey, TEntry>, newEntry: TEntry, parent?: AtomicScope): Promise<[path: Path<TKey, TEntry>, wasUpdate: boolean]> {
 		return this.atomic(async () => {
 			this.validatePath(path);
 			if (path.on) {
@@ -156,7 +174,7 @@ export class BTree<TKey, TEntry> {
 				result[0].version = ++this._version;
 			}
 			return result;
-		});
+		}, parent);
 	}
 
 	/** Inserts the entry if it doesn't exist, or updates it if it does.
@@ -182,11 +200,13 @@ export class BTree<TKey, TEntry> {
 	 * @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: TEntry, getUpdated: (existing: TEntry) => TEntry): Promise<[path: Path<TKey, TEntry>, wasUpdate: boolean]> {
-		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;
 			} else {
@@ -277,7 +297,7 @@ export class BTree<TKey, TEntry> {
 	/** @returns a path one step backward.  on will be true if the path hasn't hit the end. */
 	async prior(path: Path<TKey, TEntry>): Promise<Path<TKey, TEntry>> {
 		const newPath = path.clone();
-		this.movePrior(newPath);
+		await this.movePrior(newPath);
 		return newPath;
 	}
 
@@ -332,20 +352,40 @@ export class BTree<TKey, TEntry> {
 		return endPath;
 	}
 
-	protected async 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 async getPath(node: ITreeNode, key: TKey, navigate = false): Promise<Path<TKey, TEntry>> {
 		if (node.header.type === TreeLeafBlockType) {
 			const leaf = node as LeafNode<TEntry>;
+			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<TKey, TEntry>([], leaf, index, on, this._version);
 		} else {
 			const branch = node as BranchNode<TKey>;
 			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. */
+	private markReadValue(id: BlockId) {
+		(this.store as { markReadValue?: (id: BlockId) => void }).markReadValue?.(id);
+	}
+
 	private indexOfEntry(entries: TEntry[], key: TKey): [on: boolean, index: number] {
 		let lo = 0;
 		let hi = entries.length - 1;
@@ -392,34 +432,35 @@ export class BTree<TKey, TEntry> {
 		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;
-			}
-		} 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);
+			if (path.on || path.leafIndex < path.leafNode.entries.length) {
+				return;	// got on an entry, or an interior crack — nothing to advance into
 			}
-		}
-		else {
+			// end-of-leaf crack (leafIndex === entries.length): fall through to branch-popping leaf-advance
+		} 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);
 		}
 	}
 
@@ -460,7 +501,7 @@ export class BTree<TKey, TEntry> {
 			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];
@@ -512,7 +553,7 @@ export class BTree<TKey, TEntry> {
 		}
 		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));
 		}
@@ -577,7 +618,7 @@ export class BTree<TKey, TEntry> {
 
 	private leafInsert(path: Path<TKey, TEntry>, entry: TEntry): Split<TKey> | undefined {
 		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;
 		}
@@ -610,7 +651,7 @@ export class BTree<TKey, TEntry> {
 		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;
@@ -629,6 +670,7 @@ export class BTree<TKey, TEntry> {
 			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]!;
@@ -644,7 +686,7 @@ export class BTree<TKey, TEntry> {
 	}
 
 	protected async rebalanceLeaf(path: Path<TKey, TEntry>, depth: number): Promise<ITreeNode | undefined> {
-		if (depth === 0 || path.leafNode.entries.length >= (NodeCapacity >>> 1)) {
+		if (depth === 0 || path.leafNode.entries.length >= (this.nodeCapacity >>> 1)) {
 			return undefined;
 		}
 
@@ -653,19 +695,19 @@ export class BTree<TKey, TEntry> {
 		const pIndex = parent.index;
 		const pNode = parent.node;
 
-		const rightSibId = pNode.nodes[pIndex + 1]!;
+		const rightSibId = pNode.nodes[pIndex + 1];
 		const rightSib = rightSibId ? (await get(this.store, rightSibId)) as LeafNode<TEntry> : 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 leftSibId = pNode.nodes[pIndex - 1];
 		const leftSib = leftSibId ? (await get(this.store, leftSibId)) as LeafNode<TEntry> : 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]]);
@@ -674,7 +716,7 @@ export class BTree<TKey, TEntry> {
 			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
@@ -684,7 +726,12 @@ export class BTree<TKey, TEntry> {
 			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]);
@@ -701,7 +748,7 @@ export class BTree<TKey, TEntry> {
 			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;
 		}
 
@@ -709,9 +756,9 @@ export class BTree<TKey, TEntry> {
 		const pIndex = parent.index;
 		const pNode = parent.node;
 
-		const rightSibId = pNode.nodes[pIndex + 1]!;
+		const rightSibId = pNode.nodes[pIndex + 1];
 		const rightSib = rightSibId ? (await get(this.store, rightSibId)) as BranchNode<TKey> : 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);
@@ -722,7 +769,7 @@ export class BTree<TKey, TEntry> {
 
 		const leftSibId = pNode.nodes[pIndex - 1];
 		const leftSib = leftSibId ? (await get(this.store, leftSibId)) as BranchNode<TKey> : 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);
@@ -732,27 +779,25 @@ export class BTree<TKey, TEntry> {
 			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);
 		}