@optimystic/db-core 0.25.0 → 0.26.0

package/src/collection/collection.ts

@@ -835,7 +835,14 @@ export class Collection<TAction> implements ICollection<TAction> {
 	 * (log append → pend → commit → local fold), keeping any refresh of this instance from
 	 * interleaving with a mid-flight commit. `Latches` is non-reentrant: while holding this,
 	 * the holder must not call any of those latched methods on this instance. The caller
-	 * MUST call the release exactly once, in a `finally`. */
+	 * MUST call the release exactly once, in a `finally`.
+	 *
+	 * NOTE: the commit paths are the ONLY callers — {@link act}, {@link update} and {@link sync}
+	 * take the same mutex through `Latches.acquire` directly, never through here. The acquisition
+	 * -order cases in `test/coordinator-latch-span.spec.ts` rely on that: they shadow this method
+	 * to record the span's order, so routing a refresh path through it would silently fold
+	 * refreshes into those recordings and weaken the assertions rather than fail them. Route a new
+	 * refresh caller here only alongside a filter in that spy. */
 	acquireLatch(): Promise<() => void> {
 		return Latches.acquire(this.latchId);
 	}
@@ -936,9 +943,18 @@ export class Collection<TAction> implements ICollection<TAction> {
 			// Snapshot the pending actions so that any new actions aren't assumed to be part of this action
 			const pending = [...this.pending];
 
-			// Create a snapshot tracker for the action, so that we can ditch the log changes if we have to retry the action
+			// Create a snapshot tracker for the action, so that we can ditch the log changes if we have to retry the action.
+			// It SHARES the live tracker's pin store: the snapshot inherits transforms by copy and never
+			// stages the data-block updates itself, so without the shared pins the digest pass below
+			// could only describe bases still resident in the read cache.
+			// NOTE: an attempt that ends in a stale failure is abandoned WITHOUT reset(), so the log
+			// tail/header bases its append pinned stay in the shared store until the live tracker's
+			// next reset. Bounded and harmless — a few log blocks per attempt, capped by maxAttempts,
+			// each re-validated against the source generation before any use — but if this loop ever
+			// grows a per-attempt footprint beyond the log blocks, reset the abandoned tracker on the
+			// stale-failure branch instead of letting the residue ride to the end of the sync.
 			const snapshot = copyTransforms(this.tracker.transforms);
-			const tracker = new Tracker(this.sourceCache, snapshot);
+			const tracker = new Tracker(this.sourceCache, snapshot, this.tracker.pins);
 
 			// Add the action to the log (in local tracking space)
 			const collectionLog = await Log.open<Action<TAction>>(tracker, this.id);