@optimystic/db-core 0.24.2 → 0.25.1

package/dist/src/collection/collection.js

@@ -2,10 +2,12 @@ import { Log } from "../log/log.js";
 import { Atomic } from "../transform/atomic.js";
 import { Tracker } from "../transform/tracker.js";
 import { CacheSource } from "../transform/cache-source.js";
+import { computeBlockContentDigests } from "../transform/digest.js";
 import { copyTransforms, isTransformsEmpty } from "../transform/helpers.js";
 import { TransactorSource } from "../transactor/transactor-source.js";
 import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struct.js";
 import { CollectionHeaderVanishedError, SyncRetryExhaustedError } from "./struct.js";
+import { actionIdAt } from "./action.js";
 import { clampPriority } from "../transaction/transaction.js";
 import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
 import { randomBytes } from '@noble/hashes/utils.js';
@@ -28,13 +30,45 @@ export class Collection {
     sourceCache;
     tracker;
     filterConflict;
+    instanceTag;
     pending = [];
     latchId;
+    /** The action id of a write currently in flight ON THIS INSTANCE'S BEHALF, or `undefined`
+     * outside a write. Read by {@link updateInternal}: if the committed log now carries an entry
+     * under this id, that action's work is already durable despite the failure answer that sent us
+     * back here — `NetworkTransactor.commit` commits the collection header and log tail BEFORE
+     * sweeping the remaining blocks, so a later sweep block confirming a conflict reports failure
+     * over an action whose log entry already landed. Such an entry is CONSUMED
+     * ({@link consumeOwnEntry}) rather than replayed, because replaying re-appends content the
+     * committed tail already carries, producing a duplicate entry under one action id at two
+     * revisions.
+     *
+     * The collection owns this fact rather than taking it as a `updateInternal` argument so that no
+     * refresh path can forget to supply it — {@link update} and {@link updateAndSync} are refreshes
+     * on behalf of a READER, the field is unset for them, and the consume branch cannot fire. Before
+     * this was a field, `TransactionCoordinator.commit`'s inter-attempt refresh went through
+     * `update()` and was therefore indistinguishable from a reader refresh even though the
+     * coordinator held the very id it was retrying.
+     *
+     * LIFETIME is the whole attempt CYCLE, not the latched span: it must survive the refresh
+     * BETWEEN a failed attempt and its retry, which is the only moment it is ever read. In
+     * {@link syncInternal} that cycle is contained inside the collection latch `sync()` holds; in
+     * `TransactionCoordinator.commit` the inter-attempt `update()` runs OUTSIDE the commit latch
+     * span by design (`Latches` is non-reentrant), so the coordinator's clear necessarily runs
+     * latch-free. That is safe: this is a single field write, {@link beginInFlightAction}'s
+     * disposer only clears an id it still owns, and the only reader runs under the latch — so the
+     * worst a foreign concurrent refresh can see is a cleared field (it stops consuming), never a
+     * field it should not have consumed. */
+    inFlightActionId;
     constructor(id, transactor, handlers, source, 
     /** Cache of unmodified blocks from the source */
     sourceCache, 
     /** Tracked Changes */
-    tracker, filterConflict) {
+    tracker, filterConflict, 
+    /** Short random tag naming THIS instance (see {@link newInstanceTag}). Open paths generate
+     * it BEFORE construction (so pre-construction diagnostics such as attachToLog can carry it);
+     * the default covers direct construction in tests. */
+    instanceTag = Collection.newInstanceTag()) {
         this.id = id;
         this.transactor = transactor;
         this.handlers = handlers;
@@ -42,7 +76,25 @@ export class Collection {
         this.sourceCache = sourceCache;
         this.tracker = tracker;
         this.filterConflict = filterConflict;
-        this.latchId = `Collection:${this.id}`;
+        this.instanceTag = instanceTag;
+        // Instance-scoped, deliberately NOT shared across instances of one collection id. The
+        // latch protects per-instance state only — the tracker, the pending queue, and
+        // source.actionContext, none of which two instances over the same id share — while
+        // cross-instance races are resolved by the transactor's optimistic concurrency (that is
+        // the design; the old process-global `Collection:${id}` key serialized instances by
+        // accident). Instance scope is also what lets TransactionCoordinator hold this latch
+        // across its whole commit span: `Latches` is a non-reentrant FIFO mutex, and a rival
+        // writer driving a SECOND instance of the same id from inside transactor.pend (see
+        // CompetingWriterTransactor) would otherwise wait on the very latch the parked commit
+        // holds — a deadlock, not contention.
+        this.latchId = `Collection:${this.id}#${this.instanceTag}`;
+    }
+    /** A fresh instance tag: four random bytes rendered base64url — six characters, enough that
+     * two instances over one collection id do not collide by accident, short enough to ride on
+     * every trace line (same shape as the node tag in quereus-plugin-optimystic's
+     * collection-factory). Scopes {@link latchId} per instance and labels diagnostics. */
+    static newInstanceTag() {
+        return uint8ArrayToString(randomBytes(4), 'base64url');
     }
     /** Open an EXISTING collection.
      *
@@ -63,8 +115,11 @@ export class Collection {
             // that ignores the undefined cannot later sync a phantom collection into existence.
             return undefined;
         }
-        await Collection.attachToLog(source, transactor, tracker, id, header);
-        return new Collection(id, transactor, init.modules, source, sourceCache, tracker, init.filterConflict);
+        // Generated BEFORE attachToLog so log-attach-time diagnostics can name the instance
+        // the same way post-construction ones do.
+        const instanceTag = Collection.newInstanceTag();
+        await Collection.attachToLog(source, transactor, tracker, id, instanceTag, header);
+        return new Collection(id, transactor, init.modules, source, sourceCache, tracker, init.filterConflict, instanceTag);
     }
     /** Open an existing collection, or stage a fresh empty one in the local tracker when the
      * header is authoritatively absent. Nothing is written to storage until {@link sync}.
@@ -74,8 +129,10 @@ export class Collection {
      * any pure read path. */
     static async createOrOpen(transactor, id, init) {
         const { source, sourceCache, tracker, header } = await Collection.probeHeader(transactor, id);
+        // Pre-construction for the same reason as in open(): see the comment there.
+        const instanceTag = Collection.newInstanceTag();
         if (header) { // Collection already exists
-            await Collection.attachToLog(source, transactor, tracker, id, header);
+            await Collection.attachToLog(source, transactor, tracker, id, instanceTag, header);
         }
         else { // Collection does not exist
             log('collection:invented id=%s — no committed header found; staging a fresh empty collection', id);
@@ -84,7 +141,7 @@ export class Collection {
             source.actionContext = undefined;
             await Log.open(tracker, id);
         }
-        return new Collection(id, transactor, init.modules, source, sourceCache, tracker, init.filterConflict);
+        return new Collection(id, transactor, init.modules, source, sourceCache, tracker, init.filterConflict, instanceTag);
     }
     /** The per-instance read wiring every open path needs, plus the header probe result.
      * Shared by {@link open} and {@link createOrOpen} so the two cannot drift. */
@@ -103,7 +160,10 @@ export class Collection {
      * A header we just probed successfully but whose log will not open is a fault, not an
      * absence — throw rather than let the collection read as empty. (The re-read goes through
      * the tracker/cache, so it can disagree with the probe when storage is flaky mid-open.) */
-    static async attachToLog(source, transactor, tracker, id, header) {
+    static async attachToLog(source, transactor, tracker, id, 
+    /** The tag the calling open path minted for the Collection it is ABOUT to construct, so a
+     * diagnostic emitted here carries the same instance name as every post-construction one. */
+    instanceTag, header) {
         // Bootstrap ActionContext from the committed tail before walking the chain.
         // This allows the transactor to serve pending non-tail blocks during Log.open.
         await Collection.bootstrapContext(source, transactor, header);
@@ -114,7 +174,7 @@ export class Collection {
         // Monotonic, not an overwrite: getActionContext resolves undefined when the chain has no
         // tail or the tail block carries zero entries, and that must not erase the revision
         // bootstrapContext just read off the committed tail.
-        Collection.advanceContext(source, id, await collectionLog.getActionContext());
+        Collection.advanceContext(source, id, instanceTag, 'attach', await collectionLog.getActionContext());
     }
     /** Adopt a freshly-read action context WITHOUT ever lowering the revision already held.
      *
@@ -124,18 +184,150 @@ export class Collection {
      * repeats the same doomed request because each retry re-runs the same losing read.
      *
      * Equal revisions still adopt `next`: the rev is unchanged but its `committed` list may be
-     * more complete than what we hold. */
-    static advanceContext(source, id, next) {
+     * more complete than what we hold.
+     *
+     * This is also the one seam where lineage divergence is observable: at every revision BOTH
+     * sides name an action for, the two ids must agree. Revision
+     * numbers are per-collection counters, so two separately-built copies under one id can each
+     * occupy the same revision with DIFFERENT actions while each stays internally self-consistent
+     * — {@link reportShortfall} structurally cannot see that (its two numbers come from one
+     * chain), and this is the only place two `committed` lists meet. Naming different actions at
+     * one revision proves the two sides are different lineages (`collection:lineage-divergence`;
+     * see docs/debugging.md § "Did the refresh itself fail to close the gap?"). WHICH two sides
+     * depends on the caller, and the line says so in `site=` — see {@link DivergenceSite}, which
+     * defines the two values and what each one indicts.
+     *
+     * Every line from here also carries `tag=`, the {@link Collection.instanceTag} of the handle
+     * reporting. One process routinely holds several handles on one collection id; without the
+     * tag, two handles' lines interleave into what reads like one handle contradicting itself.
+     *
+     * Logs, does not throw — same reasoning as {@link reportShortfall}: `update()` runs
+     * blanket-style over every registered collection between commit retries, and aborting here
+     * would promote a diagnosis to production behaviour before the line has ever been seen to
+     * fire in the wild. Adoption then proceeds unchanged, which means the line is a PER-DISCOVERY
+     * report, not a per-refresh one: adopting `next` overwrites the held lineage marker with the
+     * log's, so the next refresh of this instance compares log-to-log and stays silent — even
+     * though block content materialized under the old lineage may still be in caches. The line
+     * marks the refresh that first observed the disagreement.
+     *
+     * NOTE: adoption resolves the CONTEXT disagreement, not the content one — the read caches on
+     * this instance still hold blocks materialized under the old lineage, and since the revision
+     * did not change nothing re-reads them. Conditional today: no fork has been reproduced (see
+     * the still-open upstream reproducer), so this instrument exists to find out whether one
+     * happens at all. If the line is ever seen firing in the field, decide then whether a
+     * divergence should also drop the read cache (and whether to keep re-reporting per refresh)
+     * — that is a behaviour change, and this seam deliberately makes none.
+     *
+     * The comparison is {@link earliestFork}, not a single lookup at the current revision: the
+     * two `committed` lists overlap across several revisions, and the LOWEST one they disagree at
+     * is where the lineages actually parted — a fork below the current revision was previously
+     * silent. `forkRev=` names it, `heldAction=`/`readAction=` are the two ids AT it, and
+     * `heldRev=`/`readRev=` are the two contexts' own revisions, so the line says both where the
+     * split began and how far each side has since travelled.
+     *
+     * The refusal line reports its two action ids at `readRev=` — the read's revision — on BOTH
+     * sides, because that is the only revision the two can be compared at: `next` never names an
+     * action above its own revision, so looking each side up at its own revision would compare
+     * different revisions and print two different ids for one honest lineage. Equal ids there mean
+     * the read is an older view of THIS lineage (ordinary lag, correctly refused); different ids
+     * mean a fork; `none` on the held side means this handle's own list does not reach back to the
+     * read's revision — the signature of a context bootstrapped from an over-claiming tail (see
+     * the NOTE in {@link bootstrapContext}), which is exactly the case {@link earliestFork} has no
+     * shared revision to report on.
+     *
+     * Gated on `log.enabled`, like every {@link actionIdAt} caller: the comparison buys nothing
+     * when the line has no sink, and the lists — one entry per commit between context reads,
+     * truncated at each checkpoint — are only walked on a run that has the namespace turned on.
+     * Silence proves nothing either way, because a revision is only comparable when BOTH sides
+     * name an action for it: an invented collection has no context at all, a revision slot the log
+     * gave to a checkpoint or invalidation entry names none, and a revision older than the read
+     * log's most recent checkpoint has already fallen off the read side's list. */
+    static advanceContext(source, id, instanceTag, site, next) {
         const current = source.actionContext;
         if (next === undefined) {
             return; // The read learned nothing — keep what we already know.
         }
+        if (current !== undefined && log.enabled) {
+            const fork = Collection.earliestFork(current, next);
+            if (fork !== undefined) {
+                log('collection:lineage-divergence id=%s tag=%s site=%s forkRev=%d heldAction=%s readAction=%s heldRev=%d readRev=%d', id, instanceTag, site, fork.rev, fork.heldAction, fork.readAction, current.rev, next.rev);
+            }
+        }
         if (current !== undefined && next.rev < current.rev) {
-            log('collection:context-not-lowered id=%s held=%d read=%d', id, current.rev, next.rev);
+            // The refusal itself is unconditional; only the id lookups that explain it are gated.
+            if (log.enabled) {
+                log('collection:context-not-lowered id=%s tag=%s site=%s heldRev=%d readRev=%d heldAction=%s readAction=%s', id, instanceTag, site, current.rev, next.rev, actionIdAt(current, next.rev) ?? 'none', actionIdAt(next, next.rev) ?? 'none');
+            }
             return;
         }
         source.actionContext = next;
     }
+    /** The EARLIEST revision the two contexts provably disagree about: the lowest revision both
+     * `committed` lists name an action for, where the two ids differ.
+     *
+     * Comparing only at the holder's current revision — what this used to do — misses a fork that
+     * began earlier and has since been overtaken by same-numbered commits on both sides, which is
+     * the shape a replica that forked and kept writing actually has. Taking the lowest disagreeing
+     * revision instead names the split point rather than an arbitrary later symptom of it.
+     *
+     * Revisions only one side names are skipped, not treated as disagreement: {@link actionIdAt}'s
+     * `undefined` is legitimate (checkpoint/invalidation slots, and revisions that predate the
+     * other side's most recent checkpoint), so a one-sided entry is missing evidence, not evidence
+     * of a fork.
+     *
+     * NOTE: linear in the two lists, which hold one entry per commit between context reads and
+     * truncate at each checkpoint. Every caller is `log.enabled`-gated, so this does not run at
+     * all on a normal run; if a non-diagnostic caller ever appears, index by revision instead. */
+    static earliestFork(held, read) {
+        // NOTE: a `committed` list carrying TWO entries at one revision would be a defect in its own
+        // right, and this keeps the last of them arbitrarily. Harmless while every caller is a
+        // diagnostic; if such a list is ever seen, report the duplicate rather than silently
+        // picking one.
+        const readIds = new Map(read.committed.map(entry => [entry.rev, entry.actionId]));
+        let earliest;
+        for (const entry of held.committed) {
+            const readAction = readIds.get(entry.rev);
+            if (readAction === undefined || readAction === entry.actionId) {
+                continue;
+            }
+            if (earliest === undefined || entry.rev < earliest.rev) {
+                earliest = { rev: entry.rev, heldAction: entry.actionId, readAction };
+            }
+        }
+        return earliest;
+    }
+    /** Report a refresh that failed to move FORWARDS past a revision it had already read for
+     * itself — the sibling of {@link advanceContext}'s `collection:context-not-lowered`, which
+     * reports a collection declining to move BACKWARDS.
+     *
+     * `tailRev` is what the committed log tail claimed is committed under this id; `after` is
+     * where a SEPARATE read path (the chain walk) actually landed. Landing below the claim means
+     * this refresh closed nothing, which from outside the class is otherwise indistinguishable
+     * from "there was nothing newer to adopt".
+     *
+     * This detects LAG, and only lag. It CANNOT see lineage divergence: both of its numbers
+     * come from the same chain — `tailRev` off the tail block this collection's own header
+     * names, `after` from a walk of that same chain — and a forked replica is internally
+     * self-consistent, its tail claiming exactly what its own walk reaches. Two copies of one
+     * collection id holding the same revision under different actions therefore keep this line
+     * silent forever. That case is `collection:lineage-divergence`, reported from
+     * {@link advanceContext}, which compares action ids — the one value comparable across
+     * copies — rather than revision counters.
+     *
+     * Carries the same `tag=` as {@link advanceContext}'s lines, and for the same reason: several
+     * handles on one collection id otherwise read as one self-contradicting handle.
+     *
+     * Logs, does not throw: `update()` is called blanket-style over every registered collection
+     * between commit retries, and a shortfall is not yet known to be illegitimate — an abort here
+     * would promote an unproven diagnosis to production behaviour. Deliberately does NOT adopt
+     * `tailRev` either: the two numbers come from different read paths, and papering over the
+     * disagreement destroys the evidence this line exists to produce. */
+    static reportShortfall(id, instanceTag, tailRev, before, after) {
+        if (tailRev === undefined || (after !== undefined && after >= tailRev)) {
+            return;
+        }
+        log('collection:context-short-of-tail id=%s tag=%s before=%s after=%s tail=%d', id, instanceTag, before ?? 'none', after ?? 'none', tailRev);
+    }
     async act(...actions) {
         const release = await Latches.acquire(this.latchId);
         try {
@@ -170,6 +362,55 @@ export class Collection {
             release();
         }
     }
+    /** Drops the pending actions this sync's OWN committed entry already made durable, instead of
+     * replaying them into a duplicate entry (see {@link inFlightActionId}).
+     *
+     * `addActions` wrote exactly the snapshot pending list under this action id, and the entry's
+     * actions are therefore the LEADING `entry.actions.length` items of `this.pending` — anything
+     * staged since is behind them, because {@link actInternal} appends. Under
+     * {@link syncInternal} nothing can even be staged mid-cycle (`act()` shares the collection
+     * latch); under `TransactionCoordinator.commit` the mark spans a latch-free inter-attempt
+     * window, so an `act()` there CAN grow `pending` — still only at the tail, so the slice stays
+     * right.
+     *
+     * The guard below is the load-bearing part: `slice` fails SILENTLY if that correspondence ever
+     * breaks, dropping actions that were never committed, so an entry longer than `pending` throws
+     * instead of losing work. (See the sibling note on `syncInternal`'s post-commit replay, which
+     * rests on the same invariant.) */
+    consumeOwnEntry(entry) {
+        if (entry.actions.length > this.pending.length) {
+            throw new Error(`Collection ${this.id}: own committed entry for action ${entry.actionId} holds `
+                + `${entry.actions.length} actions but only ${this.pending.length} are pending; `
+                + `consuming it would drop actions that were never committed`);
+        }
+        // `mutated` is unconditional, even for a zero-action entry: the tracker still holds this
+        // action's staged transforms, and only the replay at the end of `updateInternal` — which
+        // resets the tracker and re-stages just what remains — drops them. That reset is what turns
+        // `hasUnsyncedChanges()` false so the sync loop exits reporting the success the writer is
+        // owed (the action IS durable).
+        return { after: this.pending.slice(entry.actions.length), mutated: true };
+    }
+    /** Maps each pending action to its effective form against a remote entry: the original, a
+     * replacement, or dropped. A replacement or a discard changes the pending set; the tracker still
+     * holds the pre-filter transforms, so report it as mutated to force a replay that re-stages
+     * against the effective actions. Identity comparison per the contract: keep => same instance,
+     * replace => new instance.
+     * NOTE: a filterConflict hook that always allocates a fresh (but equal) instance instead of
+     * returning the same one forces a replay on every update — if that ever shows up as a hot path,
+     * compare by value/id here instead of by reference. */
+    filterAgainstEntry(entry) {
+        const before = this.pending;
+        const after = before
+            .map(p => this.doFilterConflict(p, entry.actions))
+            .filter((a) => a !== undefined);
+        return { after, mutated: after.length !== before.length || after.some((a, i) => a !== before[i]) };
+    }
+    /** Refresh this instance against the stored log: adopt the latest committed revision, resolve
+     * pending actions against everything that landed since, and replay them if anything conflicts.
+     *
+     * Takes no in-flight action id — it reads {@link inFlightActionId} off `this`, which is set for
+     * exactly the write attempt cycles that own one (see that field). Callers cannot get this wrong
+     * by omission. */
     async updateInternal() {
         // Start with a context that can see to the end of the log
         const source = new TransactorSource(this.id, this.transactor, undefined);
@@ -198,6 +439,13 @@ export class Collection {
         // Falling through means the header is genuinely absent AND we hold no revision: nothing
         // was ever committed under this id. Log.open reads the same block id, so it too resolves
         // undefined and everything below no-ops — correct here, rather than a masked failure.
+        // The revision the committed tail just claimed, captured before anything else can touch
+        // the local source. This is the authoritative "latest committed under this id" number,
+        // read straight off the tail block's state; the chain walk below arrives at its own
+        // number by a different path, and the two disagreeing is worth saying out loud (see the
+        // {@link reportShortfall} call after advanceContext). Stays undefined when there is no header, no
+        // tail, or a tail with no `latest` — all legitimate "nothing committed yet" states.
+        const tailRev = source.actionContext?.rev;
         // Get the latest entries from the log, starting from where we left off
         const actionContext = this.source.actionContext;
         const collectionLog = await Log.open(tracker, this.id);
@@ -205,19 +453,10 @@ export class Collection {
         // Process the entries and track the blocks they affect
         let anyConflicts = false;
         for (const entry of latest?.entries ?? []) {
-            // Filter any pending actions that conflict with the remote actions. Each pending
-            // action maps to its effective form: the original, a replacement, or dropped.
-            const before = this.pending;
-            const after = before
-                .map(p => this.doFilterConflict(p, entry.actions))
-                .filter((a) => a !== undefined);
-            // A replacement or a discard changes the pending set; the tracker still holds the
-            // pre-filter transforms, so force a replay to re-stage against the effective actions.
-            // Identity comparison per the contract: keep => same instance, replace => new instance.
-            // NOTE: a filterConflict hook that always allocates a fresh (but equal) instance instead
-            // of returning the same one forces a replay on every update — if that ever shows up as a
-            // hot path, compare by value/id here instead of by reference.
-            const mutated = after.length !== before.length || after.some((a, i) => a !== before[i]);
+            const isOwnEntry = this.inFlightActionId !== undefined && entry.actionId === this.inFlightActionId;
+            const { after, mutated } = isOwnEntry
+                ? this.consumeOwnEntry(entry)
+                : this.filterAgainstEntry(entry);
             this.pending = after;
             this.sourceCache.clear(entry.blockIds);
             anyConflicts = anyConflicts || mutated || this.tracker.conflicts(new Set(entry.blockIds)).length > 0;
@@ -243,7 +482,8 @@ export class Collection {
         // content at this.actionContext.rev — if the cursor hasn't advanced yet, replay re-reads
         // at the revision we're leaving and refills the cache with stale content that nothing
         // will invalidate again (the log entry that would have cleared it was already consumed).
-        Collection.advanceContext(this.source, this.id, latest?.context);
+        Collection.advanceContext(this.source, this.id, this.instanceTag, 'refresh', latest?.context);
+        Collection.reportShortfall(this.id, this.instanceTag, tailRev, actionContext?.rev, this.source.actionContext?.rev);
         // On conflicts, re-stage the pending actions against the adopted revision. The affected
         // blocks were already dropped from sourceCache above (per log entry / per invalidation),
         // so the replay's reads re-materialize from the transactor.
@@ -367,6 +607,53 @@ export class Collection {
     hasUnsyncedChanges() {
         return this.pending.length > 0 || !isTransformsEmpty(this.tracker.transforms);
     }
+    /** The committed revision this collection currently READS at, or `undefined` for an
+     * INVENTED collection that has never adopted a committed revision
+     * ({@link createOrOpen} found no header and staged a fresh empty one).
+     *
+     * Not the revision a pending write will land at: {@link getNextRev} is this plus one
+     * (`undefined` counting as 0), so a diagnostic that prints this value BEFORE a commit
+     * is naming the revision the commit will supersede, not the one it produces.
+     *
+     * DIAGNOSTIC ONLY — do not branch on this. Every block this collection reads is
+     * materialized at this revision ({@link TransactorSource.tryGet} passes it as the
+     * read context), and the revision advances ONLY through an explicit call on THIS
+     * instance — {@link update} or {@link sync} on the single-node path, or
+     * {@link recordCommitted} when a {@link TransactionCoordinator} commits this
+     * collection (the session/consensus path, where no `update()` is involved at all).
+     * Nothing moves it passively — not time, not another collection's
+     * commit, not a peer's notification. So a collection sitting here at a lagging
+     * revision silently serves an old root with no error, and two collections in one
+     * process can be at different revisions at the same instant. That gap is invisible
+     * from outside the class without this accessor, which is the whole reason it
+     * exists: `docs/debugging.md` (§ "Which revision did a read descend?") explains
+     * how an operator reads the difference. */
+    committedRevision() {
+        return this.source.actionContext?.rev;
+    }
+    /** The id of the action that PRODUCED the revision {@link committedRevision} reports —
+     * this collection's lineage marker at that revision — or `undefined` when the action
+     * context holds no entry at the current revision.
+     *
+     * `undefined` is legitimate, not an error: an INVENTED collection has no context at
+     * all, and otherwise {@link actionIdAt} resolves nothing at the current revision for
+     * the reasons listed there. A caller printing this must therefore carry a placeholder
+     * rather than invent an id. The contexts this class writes itself
+     * ({@link recordCommitted}, the inline bump in `syncInternal`,
+     * {@link bootstrapContext}) always do hold one.
+     *
+     * DIAGNOSTIC ONLY — do not branch on this. Its value is the one thing about a revision
+     * that IS comparable across collections and across nodes: a revision number is
+     * per-collection and says nothing on its own, so two nodes reporting the same
+     * collection id at the same revision are indistinguishable between "one collection,
+     * one node lagging" and "two separately-built collections each counting from 1". Equal
+     * action ids mean one lineage; different action ids at the same revision mean two.
+     * `docs/debugging.md` (§ "Which revision did a read descend?") spells out how an
+     * operator reads the pair. */
+    committedActionId() {
+        const context = this.source.actionContext;
+        return context === undefined ? undefined : actionIdAt(context, context.rev);
+    }
     /** Fold a just-committed set of transforms into this collection's read cache
      * so subsequent reads (and stages) through THIS instance observe the committed
      * state, mirroring what {@link sync} does inline after a successful transact.
@@ -389,15 +676,76 @@ export class Collection {
     }
     /** Record a just-committed action: append its ActionRev to the committed list
      *  and advance the revision. Returns the new revision. Mirrors the inline bump
-     *  in {@link syncInternal}. */
-    recordCommitted(actionId) {
-        const rev = this.getNextRev();
+     *  in {@link syncInternal} — which needs no such rev check because it computes and
+     *  uses its `newRev` inside one latched span.
+     *
+     *  @param rev - the revision this action was PENDED at, captured once (at the log
+     *  append in `TransactionCoordinator.applyActionsToCollection`) and threaded through
+     *  the pend/commit round trips. Storage assigned the action THAT number; recording it
+     *  at any other would fork this instance's revision counter from storage permanently
+     *  (context adoption is one-way — see {@link advanceContext}). With the coordinator
+     *  holding this instance's latch across the whole commit span the mismatch cannot
+     *  happen; the throw is the tripwire for any path that still bypasses the latch. */
+    recordCommitted(actionId, rev) {
+        const expected = this.getNextRev();
+        if (rev !== expected) {
+            throw new Error(`Collection ${this.id}: action ${actionId} was pended at rev ${rev} ` +
+                `but the collection now expects rev ${expected} — the collection was refreshed mid-commit`);
+        }
         this.source.actionContext = {
             committed: [...(this.source.actionContext?.committed ?? []), { actionId, rev }],
             rev,
         };
         return rev;
     }
+    /** Acquire this instance's latch — the same mutex {@link act}, {@link update},
+     * {@link sync}, and {@link updateAndSync} serialize behind — returning its release.
+     * Exists so a TransactionCoordinator can hold the latch across its WHOLE commit span
+     * (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`. */
+    acquireLatch() {
+        return Latches.acquire(this.latchId);
+    }
+    /** Bracket a write attempt cycle on this instance under `actionId`, so a refresh taken between
+     * a failed attempt and its retry recognises that action's own already-durable log entry (see
+     * {@link inFlightActionId} for why, and for the lifetime this must span).
+     *
+     * The returned disposer clears the mark and MUST be called in a `finally` covering every exit
+     * from the retry cycle — return, retry exhaustion, partial commit, hard error, abort. A mark
+     * left behind would let a LATER, unrelated refresh consume a foreign entry that happens to
+     * carry the same id. The clear is id-guarded, so a disposer whose mark has since been replaced
+     * by another attempt is a no-op rather than wiping the newer one; disposers may therefore be
+     * called out of order and more than once. Shaped like {@link acquireLatch} deliberately: a
+     * disposer is harder to forget than a paired `end…` call.
+     *
+     * A concurrent READER's refresh landing in that latch-free window is fine, and is reachable
+     * today (`OptimysticModule` declares `concurrencyMode = 'reentrant-reads'`, so scans inside a
+     * transaction share one instance and only serialize on the latch). Consuming is a property of
+     * the (instance, action id) pair, not of who calls: whoever refreshes first drops exactly the
+     * durable entry's actions and the write's own later refresh then finds nothing new. The leading
+     * slice stays right because {@link actInternal} APPENDS, so anything staged after the entry was
+     * written survives it.
+     *
+     * NOTE: a concurrent WRITER is the hazard. The mark deliberately outlives the latch (see
+     * {@link inFlightActionId}), so two writes overlapping on ONE instance can trample each other's:
+     * a second write that acquires the latch between the first's failed attempt and its
+     * retry-refresh replaces the id, and the first's refresh then reads the SECOND write's id —
+     * consuming that write's durable entry and dropping pending actions of its own that never
+     * landed. Not reachable today: a coordinator commit and a `sync()` both run on one session call
+     * path, which is the same assumption the participant selection in
+     * `TransactionCoordinator.commitOnce` and its `rollback` already rest on. If a second writer is
+     * ever allowed to drive the SAME instance concurrently, this must become a per-attempt token (a
+     * mark object compared by identity, refusing to replace a live one) rather than a bare id. */
+    beginInFlightAction(actionId) {
+        this.inFlightActionId = actionId;
+        return () => {
+            if (this.inFlightActionId === actionId) {
+                this.inFlightActionId = undefined;
+            }
+        };
+    }
     /** Push our pending actions to the transactor */
     async sync(options) {
         const release = await Latches.acquire(this.latchId);
@@ -408,9 +756,24 @@ export class Collection {
             release();
         }
     }
+    /** Mints the one action id this sync reuses across all of its retry attempts, and owns it for
+     * the WHOLE cycle — including the inter-attempt refresh, which is the only thing that reads it
+     * (see {@link inFlightActionId}). `sync()`/`updateAndSync()` hold the collection latch across
+     * all of this, so the mark's lifetime is contained inside the latched span here; the disposer
+     * runs on every exit, including a throw out of retry exhaustion or an abort. */
     async syncInternal(options) {
         const bytes = randomBytes(16);
         const actionId = uint8ArrayToString(bytes, 'base64url');
+        const endInFlight = this.beginInFlightAction(actionId);
+        try {
+            await this.syncAttempts(actionId, options);
+        }
+        finally {
+            endInFlight();
+        }
+    }
+    /** The retry loop behind {@link syncInternal}, run with `actionId` already marked in flight. */
+    async syncAttempts(actionId, options) {
         const maxAttempts = options?.maxAttempts ?? DefaultMaxAttempts;
         const baseBackoffMs = options?.baseBackoffMs ?? PendingRetryDelayMs;
         const maxBackoffMs = options?.maxBackoffMs ?? DefaultMaxBackoffMs;
@@ -445,11 +808,21 @@ export class Collection {
             }
             const newRev = (this.source.actionContext?.rev ?? 0) + 1;
             const addResult = await collectionLog.addActions(pending, actionId, newRev, () => tracker.transformedBlockIds());
+            // Declare what each touched block will contain once committed, computed from this snapshot
+            // tracker (which layers over `this.sourceCache`, so the peek/getCachedRevision probes are
+            // live). Purely local — an id whose base is not already cached is simply omitted and falls
+            // back to corroboration on the member side. Computed AFTER the log append so the log tail
+            // and header transforms this attempt just staged are digested too.
+            // NOTE: recomputed from scratch on every retry attempt (the snapshot tracker is rebuilt each
+            // iteration), so a sync that loses N races pays N full hashing passes over its touched
+            // blocks. Unmeasured and cheap relative to the round trips it is retrying; if a
+            // high-contention sync ever shows digest hashing in a profile, memoize per (id, staged ops).
+            const blockDigests = await computeBlockContentDigests(tracker, tracker.transformedBlockIds());
             // Commit the action to the transactor. Carry the aged retry priority derived from the
             // consecutive-failure count so a sync that keeps losing concurrent races out-ranks fresh
             // (priority-0) rivals in the cluster's resolveRace (fairness-only; capped at MaxPriority).
             // First attempt has consecutiveFailures == 0, so priority 0 — the common pend is unchanged.
-            const staleFailure = await this.source.transact(tracker.transforms, actionId, newRev, this.id, addResult.tailPath.block.header.id, clampPriority(consecutiveFailures));
+            const staleFailure = await this.source.transact(tracker.transforms, actionId, newRev, this.id, addResult.tailPath.block.header.id, clampPriority(consecutiveFailures), blockDigests);
             if (staleFailure) {
                 consecutiveFailures++;
                 lastReason = staleFailure.reason ?? lastReason;
@@ -474,7 +847,11 @@ export class Collection {
                 // baseBackoffMs for that caller rather than reintroducing the zero-delay retry.
                 const delay = jitteredBackoffMs(consecutiveFailures - 1, { baseMs: baseBackoffMs, capMs: maxBackoffMs }, options?.rand);
                 await abortableDelay(delay, signal);
-                // Fetch latest state - updateInternal() will call replayActions() if there are conflicts
+                // Fetch latest state - updateInternal() will call replayActions() if there are conflicts.
+                // This sync's actionId is marked in flight for the whole cycle (see syncInternal), so
+                // the refresh recognizes a log entry written by THIS action (a commit that landed
+                // durably but answered stale — see the entry loop in updateInternal) and consumes it
+                // rather than replaying it into a duplicate entry.
                 await this.updateInternal();
             }
             else {
@@ -486,6 +863,16 @@ export class Collection {
                 this.pending = this.pending.slice(pending.length);
                 // Reset cache and replay any actions that were added during the action
                 const transforms = tracker.reset();
+                // NOTE: this replay runs BEFORE the cache fold and the context bump below — the
+                // inverse of the order `updateInternal` and `TransactionCoordinator.commitOnce`
+                // both document as required, where the newly committed state must be visible
+                // before anything re-reads. Dormant today: `act()` and `syncInternal` take the
+                // same collection latch, so `this.pending` cannot grow during the transact above
+                // and the slice always leaves it empty, making this replay a no-op reset. If a
+                // path ever stages outside that latch, move the transformCache + actionContext
+                // lines above this replay — otherwise the replay re-reads at the superseded
+                // revision over a cache that has not yet seen the commit, and re-stages onto a
+                // root the commit already replaced.
                 await this.replayActions();
                 this.sourceCache.transformCache(transforms, newRev);
                 this.source.actionContext = this.source.actionContext
@@ -571,6 +958,16 @@ export class Collection {
                 throw new BlockPossiblyStaleError(tailId, tailEntry.unconfirmedAheadRev);
             }
             const tailState = tailEntry?.state;
+            // NOTE: this number is adopted on trust, and adoption is one-way (advanceContext never
+            // lowers it). A tail that over-claims therefore pins the collection at a revision its
+            // own log can never reach, permanently: every later refresh walks the log, reads the
+            // real (lower) revision, and is refused — so the instance emits
+            // `collection:context-not-lowered` forever while `collection:context-short-of-tail`
+            // stays silent (the held revision is at or above what the tail claims). No condition
+            // that makes a real tail over-claim has been demonstrated; this was seen only through a
+            // test double built to lie (see collection.spec.ts, 'a refresh that lands short of the
+            // tail it just read'). If an over-claiming tail is ever observed in the field, the fix
+            // belongs here — validate the claim against the log before pinning — not in the refresh.
             if (tailState?.latest) {
                 source.actionContext = {
                     committed: [{ actionId: tailState.latest.actionId, rev: tailState.latest.rev }],