@optimystic/db-core 1.0.0-beta.3 → 1.1.0

package/dist/src/collection/collection.js

@@ -2,12 +2,13 @@ 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 { computeBlockContentDigests, baseRevsField } 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 { TransactorSource, answeredBlock, servedRevision } from "../transactor/transactor-source.js";
+import { BlockFloors } from "../transactor/block-floors.js";
+import { mergeDurability } from "../network/durability.js";
 import { highestStaleAt } from "../network/stale-failure.js";
-import { CollectionHeaderVanishedError, SyncRetryExhaustedError, SyncRevisionStalledError } from "./struct.js";
+import { CollectionHeaderVanishedError, SyncRetryExhaustedError, SyncRevisionStalledError, TornActionError } from "./struct.js";
 import { actionIdAt } from "./action.js";
 import { clampPriority } from "../transaction/transaction.js";
 import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
@@ -39,42 +40,73 @@ export class Collection {
     source;
     sourceCache;
     tracker;
+    floors;
     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.
+     * under this id, that action's LOG TAIL landed despite the failure answer that sent us back here
+     * — `NetworkTransactor.commit` commits the log tail BEFORE sweeping the remaining blocks, and
+     * reports failure both when the tail itself was refused after landing on a minority
+     * (`commit-not-durable`, in which case the sweep never ran) and when a later sweep block
+     * confirmed a conflict. Such an entry is never REPLAYED, because replaying re-appends content
+     * the committed tail already carries, producing a duplicate entry under one action id at two
+     * revisions. But it is not proof the write is saved either: the entry proves only that the tail
+     * landed, and the writer's own cancel has since dropped the pending records of every block that
+     * did not. So the refresh first FINISHES the action ({@link completeOwnEntry}) — landing the
+     * remaining blocks at the same action id and revision, from {@link inFlightAttempt} — and only
+     * then consumes the entry ({@link consumeOwnEntry}).
      *
      * 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.
+     * coordinator held the very id it was retrying. (It now goes through {@link refreshInFlight},
+     * which differs from `update()` only in reporting what the refresh saved — the field, not the
+     * method, is still what makes the refresh recognise the entry.)
      *
      * 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
+     * `TransactionCoordinator.commit` the inter-attempt refresh 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;
+    /** The most recent FAILED attempt made under {@link inFlightActionId} — exactly what it sent,
+     * kept so a refresh that finds that attempt's own log entry can finish the action instead of
+     * assuming it is finished (see {@link completeOwnEntry}). Set by {@link retainInFlightAttempt},
+     * cleared with the mark by {@link beginInFlightAction}'s disposer, and meaningless without it.
+     *
+     * The transforms are retained VERBATIM, not rebuilt: a rebuilt attempt re-appends the log entry
+     * with a fresh timestamp, so its log tail would differ byte-for-byte from the one already
+     * stored under the same action id and revision — and any replica that had not yet stored the
+     * tail would then store the second version, leaving two contents under one `(action, revision)`.
+     *
+     * Only the latest attempt is kept. An own entry can only be visible at the revision of an
+     * attempt whose tail landed, and a later attempt at a DIFFERENT revision is only made after a
+     * refresh adopted somebody else's entry at the earlier one — which is proof the earlier tail did
+     * not land. {@link completeOwnEntry} still checks the revision and refuses on a mismatch. */
+    inFlightAttempt;
+    /** The log tail block id the most recent header read named. A refresh asks for this block in the
+     * same request as the header ({@link readLogEnds}): the tail id only changes when the tail block
+     * fills, so an idle refresh is one request rather than two. A stale value costs one extra request
+     * and nothing else. */
+    logTailId;
     constructor(id, transactor, handlers, source, 
     /** Cache of unmodified blocks from the source */
     sourceCache, 
     /** Tracked Changes */
-    tracker, filterConflict, 
+    tracker, 
+    /** What each block named by a walked log entry must be at least as new as — raised by
+     * {@link updateInternal}, and shared with every read source this handle builds (see
+     * {@link BlockFloors}). */
+    floors, 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. */
@@ -85,6 +117,7 @@ export class Collection {
         this.source = source;
         this.sourceCache = sourceCache;
         this.tracker = tracker;
+        this.floors = floors;
         this.filterConflict = filterConflict;
         this.instanceTag = instanceTag;
         // Instance-scoped, deliberately NOT shared across instances of one collection id. The
@@ -119,17 +152,20 @@ export class Collection {
      * would instead stage a fresh empty collection, and reads through it would report an
      * absent dataset as a legitimately empty one. */
     static async open(transactor, id, init) {
-        const { source, sourceCache, tracker, header } = await Collection.probeHeader(transactor, id);
+        // Generated BEFORE anything reads, so every diagnostic of this handle — the floors the probe
+        // wires up and the log-attach-time lines included — names the instance the same way
+        // post-construction ones do.
+        const instanceTag = Collection.newInstanceTag();
+        const { source, sourceCache, tracker, floors, header } = await Collection.probeHeader(transactor, id, instanceTag);
         if (!header) {
             // Return before anything is staged: the tracker's transforms stay empty, so a caller
             // that ignores the undefined cannot later sync a phantom collection into existence.
             return undefined;
         }
-        // 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);
+        const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, instanceTag);
+        collection.logTailId = header.tailId;
+        return collection;
     }
     /** 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}.
@@ -138,9 +174,9 @@ export class Collection {
      * bootstrap path. The create branch logs `collection:invented`; prefer {@link open} on
      * 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();
+        const { source, sourceCache, tracker, floors, header } = await Collection.probeHeader(transactor, id, instanceTag);
         if (header) { // Collection already exists
             await Collection.attachToLog(source, transactor, tracker, id, instanceTag, header);
         }
@@ -151,20 +187,34 @@ export class Collection {
             source.actionContext = undefined;
             await Log.open(tracker, id);
         }
-        return new Collection(id, transactor, init.modules, source, sourceCache, tracker, init.filterConflict, instanceTag);
+        const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, instanceTag);
+        collection.logTailId = header?.tailId;
+        return collection;
     }
     /** 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. */
-    static async probeHeader(transactor, id) {
+    static async probeHeader(transactor, id, instanceTag) {
         // Start with a context that has an infinite revision number to ensure that we always fetch the latest log information.
         // One shared read-dependency collector feeds both the source (direct structural reads) and the cache (every
         // cache hit/miss), so a block read from either layer records a dependency — cache hits included.
         const collector = new ReadDependencyCollector();
-        const source = new TransactorSource(id, transactor, undefined, collector);
+        const floors = Collection.newFloors(id, instanceTag);
+        const source = new TransactorSource(id, transactor, undefined, collector, floors);
         const sourceCache = new CacheSource(source, undefined, collector);
         const tracker = new Tracker(sourceCache);
         const header = await source.tryGet(id);
-        return { source, sourceCache, tracker, header };
+        return { source, sourceCache, tracker, floors, header };
+    }
+    /** A new handle's floors: none yet (opening walks no entries), wired to report every below-floor
+     * answer any of the handle's read sources receives. The line is the only trace such an answer
+     * leaves — the read itself succeeds (see the accepted-tradeoff NOTE at
+     * `TransactorSource.mayRetain`) — so repeated lines for one block with `servedRev` short of
+     * `floorRev` are how an operator sees a machine that has not caught up, and lines that never
+     * stop are how they see a log entry whose blocks never landed. */
+    static newFloors(id, instanceTag) {
+        return new BlockFloors(({ blockId, floor, servedRev }) => {
+            log('collection:block-below-floor id=%s tag=%s block=%s floorRev=%d floorAction=%s servedRev=%d', id, instanceTag, blockId, floor.rev, floor.actionId, servedRev);
+        });
     }
     /** Walk an existing collection's log and point the source at its latest action context.
      * A header we just probed successfully but whose log will not open is a fault, not an
@@ -176,7 +226,7 @@ export class Collection {
     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);
+        Collection.bootstrapContext(source, header.tailId === undefined ? undefined : await Collection.readLogTail(transactor, header.tailId));
         const collectionLog = await Log.open(tracker, id);
         if (!collectionLog) {
             throw new Error(`Log not found for collection ${id}`);
@@ -366,14 +416,213 @@ export class Collection {
     async update() {
         const release = await Latches.acquire(this.latchId);
         try {
-            await this.updateInternal();
+            await this.updateInternal({});
+        }
+        finally {
+            release();
+        }
+    }
+    /** The refresh `TransactionCoordinator.commit` runs between attempts: exactly {@link update},
+     * plus a report of whether it finished the write in flight on this instance's behalf (see
+     * {@link RefreshReport}). The coordinator needs that fact to tell its caller which participants
+     * are already saved when the commit later fails; a reader's `update()` has no write in flight
+     * and nothing to report.
+     *
+     * `report` is REQUIRED so a write path cannot refresh without learning what the refresh saved.
+     * It is filled in as the refresh goes, so it is accurate when this throws too.
+     *
+     * `lastChance` is REQUIRED for the same reason: only the caller knows whether its retry budget
+     * ends with this round, and a round that is the last must settle a half-landed write rather than
+     * ask for another (see {@link completeOwnEntry}). */
+    async refreshInFlight(report, lastChance) {
+        const release = await Latches.acquire(this.latchId);
+        try {
+            await this.updateInternal(report, lastChance);
         }
         finally {
             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}).
+    /** Finishes a half-landed write BEFORE its own log entry is consumed, so that consuming never
+     * reports a write as saved on the strength of its log entry alone.
+     *
+     * THE RULE: a write may be reported saved only if EVERY block its log entry names holds the
+     * write — at the write's own revision, or at a later revision that was BUILT FROM it. Finding the
+     * entry proves only that the log tail landed (see {@link inFlightActionId} for the two ways
+     * `NetworkTransactor.commit` answers failure over a stored tail). The writer's cancel has since
+     * removed the pending records of every block that did not land, so nothing else will ever land
+     * them — if this does not, the entry stands in the log, the blocks stay at their previous
+     * revision on every node, and readers materialize blocks, not log entries: the write is
+     * silently gone.
+     *
+     * Finishing is a plain re-send of the retained failed attempt ({@link inFlightAttempt}) — the
+     * SAME transforms, action id, revision and tail. Every storage tier treats a block that already
+     * holds exactly this action at exactly this revision as satisfied rather than as a rival
+     * (`isOwnRevision`: `StorageRepo.pend`/`.commit`, `ClusterMember`, `CoordinatorRepo`), so the
+     * re-send rolls forward precisely the blocks that are missing and is a no-op for the rest,
+     * including when nothing is missing at all. It is never sent at a new revision: the refresh has
+     * already seen the entry at this one, and a second revision would record the entry twice.
+     *
+     * A refused re-send is NOT yet an answer. Storage refuses it whenever any block has moved past
+     * the write's revision — and every later commit to the collection moves the log tail past it —
+     * which says a rival was there, not whether the rival built on this write or over it. That is
+     * asked separately, of the blocks' own history ({@link settleUnfinished}).
+     *
+     * Runs at the top of {@link updateInternal}, before that method has changed anything on this
+     * instance, so every throw from here leaves the collection exactly as the failed attempt left
+     * it — staged actions and transforms intact, revision not advanced.
+     *
+     * @param lastChance - the caller will not refresh again for this write (its retry budget ends
+     * with this round), so a refusal that could clear is settled now instead of asking for another
+     * round: the error that escapes then says whether the write can still land.
+     * @returns who holds the finished write, for the sync to report.
+     * @throws TornActionError — see {@link TornActionReason} for the three causes. Only an unsettled
+     * `completion-refused` (always `final: false`) is retried by the write paths.
+     *
+     * NOTE: the re-send costs a full pend and commit round even when every block had in fact landed
+     * (a lost or masked success). That is deliberate — it is the source of the durability the sync
+     * reports when nothing has superseded the write — and the case is rare: after a returned failure
+     * the network transactor has, by construction, NOT swept every block. If own-entry refreshes ever
+     * show up as a cost, ask `getLineage` first and skip the re-send when every block contains the
+     * write. */
+    async completeOwnEntry(entry, entryRev, lastChance) {
+        const attempt = this.inFlightAttempt;
+        const rev = entryRev ?? attempt?.rev;
+        if (attempt === undefined || rev === undefined || attempt.rev !== rev) {
+            // Nothing to finish the action WITH. That is only acceptable if there is nothing to
+            // finish. `getStatus` is the cheap first question; it judges a block by who holds its
+            // LATEST revision, so a block this action landed and a later action has since built on
+            // reads there as not committed — those are asked again, properly, by settleUnfinished.
+            // Both write paths retain an attempt before any refresh can run, so production only
+            // reaches this branch when the entry sits at a revision the retained attempt was not
+            // made at — a forked lineage.
+            const [status] = await this.transactor.getStatus([{ actionId: entry.actionId, blockIds: entry.blockIds }]);
+            if (entry.blockIds.every((_, i) => status?.statuses[i] === 'committed')) {
+                // Whole, and saved: the refresh reports it as finished (see RefreshReport), so the
+                // coordinator counts this participant as committed. Only WHO holds it is unknown.
+                // NOTE: a sync whose only commit was recognised here therefore answers `undefined` —
+                // the "nothing was written" answer — for a write that is saved, because the sync reads
+                // the report's durability, not the finished flag. Reachable only on the forked-lineage
+                // path above; if that path ever becomes ordinary, take the durability from
+                // `getLineage` (as settleUnfinished does) instead of stopping at the status read.
+                return undefined;
+            }
+            return await this.settleUnfinished(entry, rev, undefined, 'transforms-not-held', attempt === undefined
+                ? 'no failed attempt is retained for this action'
+                : `the retained attempt was made at rev ${attempt.rev}`);
+        }
+        // NOTE: priority 0. The attempt's aged retry priority is a fairness hint for a race over a
+        // free revision; this revision is already this action's own, so there is no race to rank in.
+        // NOTE: this is a plain pend. When the failed attempt came from `TransactionCoordinator`, its
+        // pend carried `validation` (the transaction and its operations hash) and
+        // `superclusterNominees`; neither is retained, so the re-send carries neither. Harmless while
+        // no deployment hands members a transaction validator (and nothing reads the nominees on
+        // the receiving side at all). Once a validator is wired, members approve these
+        // blocks unchecked under `unvalidatablePendPolicy: 'accept'` and refuse them under `'reject'`
+        // (surfacing as a `completion-refused` TornActionError). Simply retaining and re-sending the
+        // pair is not obviously right either: a member re-executing the transaction after a sibling
+        // participant has landed no longer sees the state it was staged against. Tracked as an arm
+        // of tickets/backlog/feat-no-deployment-validates-transactions-at-pend.
+        const result = await this.source.transact(attempt.transforms, entry.actionId, rev, this.id, attempt.tailId, 0, attempt.blockDigests, attempt.baseRevs);
+        if (result.success) {
+            return result.durability;
+        }
+        // A refusal that CONFIRMS a committed revision under another action — `staleAt`, which every
+        // producer sets only after reading it out of its own storage and never for this action's own
+        // revision, or a non-empty `missing` list of committed rival transforms — will be repeated by
+        // every later re-send. Anything else (a rival merely PENDING on a block, a revision not yet
+        // held by a majority, a bare reason) can clear, and is worth the caller's next round.
+        // NOTE: `staleAt` is read here as "a rival committed", which is a second consumer of a field
+        // documented as never a retryability signal (docs/internals.md). It is the same kind of use
+        // `syncAttempts`' stall check makes: it can only END a retry, never start one.
+        const rivalConfirmed = result.staleAt !== undefined || (result.missing?.length ?? 0) > 0;
+        // NOTE: a confirmed rival settles at once, even with retry budget left: re-sending is
+        // pointless, but the lineage question is asked only this once, so a member that is silent
+        // just now makes the answer `final: false`. If unsettled outcomes ever show up often under
+        // contention, spend the remaining rounds re-asking `getLineage` before giving up.
+        if (!rivalConfirmed && !lastChance) {
+            // The refusal does not say which blocks lack the revision, so name every block the entry
+            // lists other than the tail — the entry being visible is what proves the tail holds it.
+            return this.throwTorn(entry, rev, entry.blockIds.filter(blockId => blockId !== attempt.tailId), 'completion-refused', false, result.reason ?? 'the re-send was refused');
+        }
+        return await this.settleUnfinished(entry, rev, attempt.tailId, rivalConfirmed ? 'rival-holds-revision' : 'completion-refused', result.reason ?? (rivalConfirmed ? 'a different action holds a later revision' : 'the re-send was refused'), result.staleAt);
+    }
+    /** Decides what a write that can no longer be finished BY RE-SENDING amounts to, and answers
+     * one of exactly three things — never a guess between them:
+     *
+     * - SAVED (returns): every block the entry names holds content built from the write, on a
+     *   strict majority of its cohort (`ITransactor.getLineage`). The rival that refused the re-send
+     *   had read this write and added to it. Returns who holds it.
+     * - TORN AND FINAL (throws, `final: true`): every block still missing the write answered, for its
+     *   whole cohort, that it does not hold it — and the write's pending records were confirmed gone
+     *   BEFORE the blocks were asked. The order is the point: a pending record left standing can be
+     *   promoted by any later read that knows this write's log entry is committed
+     *   (`StorageRepo.get`), so a block that answered "not reached" could still take the write
+     *   afterwards. With the records gone first, nothing is left that could land it.
+     * - TORN, OUTCOME NOT ESTABLISHED (throws, `final: false`): anything else — the transactor
+     *   cannot answer for lineage, a cohort did not all answer or contradicted itself, fewer than a
+     *   majority hold the write, or the cancel could not be confirmed.
+     *
+     * `tailId` is the log block this write's entry was appended to, when known. It is never asked
+     * about: the refresh has just READ the entry out of it, which is direct evidence that the
+     * block's current content was built from the write, whatever any member's records can prove.
+     *
+     * NOTE: a write recognised as saved here reports the durability `getLineage` assembled. When
+     * the log block's own cohort could not vouch for it (members that took it as a replica), that is
+     * absent and the sync answers `undefined` for a saved write — the same wart the status-read
+     * branch of {@link completeOwnEntry} documents. If it is ever seen, fold the data blocks'
+     * reports alone rather than inventing one for the log block. */
+    async settleUnfinished(entry, rev, tailId, reason, detail, staleAt) {
+        const discharged = await this.dischargeOwnPendings(entry);
+        const lineage = rev === undefined ? undefined : await this.lineageOfOwnEntry(entry, rev);
+        const unsaved = entry.blockIds.filter((blockId, i) => blockId !== tailId && lineage?.blocks[i] !== 'contains');
+        if (lineage !== undefined && unsaved.length === 0) {
+            log('collection:own-entry-superseded-but-saved id=%s tag=%s action=%s rev=%d blocks=%d', this.id, this.instanceTag, entry.actionId, rev, entry.blockIds.length);
+            return lineage.durability;
+        }
+        const cannotLand = lineage !== undefined && unsaved.every(blockId => {
+            const answer = lineage.blocks[entry.blockIds.indexOf(blockId)];
+            return answer === 'excludes' || answer === 'behind';
+        });
+        return this.throwTorn(entry, rev ?? -1, unsaved, reason, discharged && cannotLand, detail, staleAt);
+    }
+    /** Cancels every pending record this write may have left, and says whether that is CONFIRMED.
+     * `ITransactor.cancel` returns only once the records are gone and throws otherwise; a throw here
+     * is reported as "not confirmed" rather than raised, because the caller is already reporting a
+     * torn write and that must not be displaced. Cancelling a block that holds no record is a no-op,
+     * so naming every block the entry lists is safe. */
+    async dischargeOwnPendings(entry) {
+        try {
+            await this.transactor.cancel({ actionId: entry.actionId, blockIds: entry.blockIds });
+            return true;
+        }
+        catch (err) {
+            log('collection:torn-cancel-unconfirmed id=%s tag=%s action=%s error=%s', this.id, this.instanceTag, entry.actionId, err instanceof Error ? err.message : String(err));
+            return false;
+        }
+    }
+    /** What the blocks' own history says about this write, or `undefined` when nothing can say: the
+     * transactor (or a wrapper around it) does not offer `getLineage`, or the question failed. */
+    async lineageOfOwnEntry(entry, rev) {
+        if (this.transactor.getLineage === undefined) {
+            return undefined;
+        }
+        try {
+            return await this.transactor.getLineage({ actionId: entry.actionId, blockIds: entry.blockIds, rev });
+        }
+        catch (err) {
+            log('collection:lineage-unanswered id=%s tag=%s action=%s rev=%d error=%s', this.id, this.instanceTag, entry.actionId, rev, err instanceof Error ? err.message : String(err));
+            return undefined;
+        }
+    }
+    throwTorn(entry, rev, blockIds, reason, final, detail, staleAt) {
+        log('collection:torn id=%s tag=%s action=%s rev=%d reason=%s final=%s blocks=%o', this.id, this.instanceTag, entry.actionId, rev, reason, final, blockIds);
+        throw new TornActionError(this.id, entry.actionId, rev, blockIds, reason, final, detail, staleAt);
+    }
+    /** Drops the pending actions this sync's OWN committed entry made durable, instead of replaying
+     * them into a duplicate entry (see {@link inFlightActionId}). Only ever called once
+     * {@link completeOwnEntry} has returned for this entry — the entry alone is not proof the write
+     * is saved.
      *
      * `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
@@ -420,55 +669,100 @@ export class Collection {
      *
      * 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() {
+     * by omission.
+     *
+     * @param report - Filled in as the refresh goes (see {@link RefreshReport}): its
+     * `ownEntryFinished` is set the moment the refresh has found this write's own log entry and
+     * finished it ({@link completeOwnEntry}) — before the entry is consumed, so a later throw from
+     * here still leaves it set. Never set on a reader's refresh. A caller with no use for it passes `{}`.
+     * @param lastChance - Whether the write in flight will get no further refresh (see
+     * {@link completeOwnEntry}). Meaningless, and left false, on a reader's refresh.
+     * @throws TornActionError when it found that entry and could not finish the action — thrown
+     * before anything on this instance changed, and with `report` untouched. */
+    async updateInternal(report, lastChance = false) {
         // Start with a context that can see to the end of the log
         const source = new TransactorSource(this.id, this.transactor, undefined);
-        const tracker = new Tracker(source);
-        // Bootstrap context from committed tail so pending blocks are accessible.
-        // Read through tracker so Chain.open inside Log.open reuses the cached header.
         // A header the storage layer could not retrieve throws BlockUnavailableError out of
         // this read (it is not a StaleFailure, so sync's retry loop does not absorb it).
-        const header = await tracker.tryGet(this.id);
-        if (header) {
-            await Collection.bootstrapContext(source, this.transactor, header);
-        }
-        else if (this.source.actionContext) {
-            // An absent header is only believable for a collection that has never committed.
-            // We hold a committed revision, so the two answers contradict each other — surface it
-            // as a fault instead of no-opping into a forgotten revision and a rev-1 retry spin.
-            // NOTE: this aborts every caller of update(), including TransactionCoordinator's
-            // blanket refresh of ALL registered collections between commit retries — a
-            // non-participant with a momentarily-absent header now fails the whole retry rather
-            // than being skipped. That is the intended loud failure; if it ever shows up as
-            // otherwise-healthy transactions aborting, narrow that refresh to the transaction's
-            // participants (see the note at coordinator.ts's update loop) rather than softening
-            // this throw.
-            throw new CollectionHeaderVanishedError(this.id, this.source.actionContext.rev);
-        }
-        // 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.
+        const ends = await Collection.readLogEnds(this.transactor, this.id, this.logTailId);
+        if (!ends) {
+            if (this.source.actionContext) {
+                // An absent header is only believable for a collection that has never committed.
+                // We hold a committed revision, so the two answers contradict each other — surface it
+                // as a fault instead of no-opping into a forgotten revision and a rev-1 retry spin.
+                // NOTE: this aborts every caller of update(), including TransactionCoordinator's
+                // blanket refresh of ALL registered collections between commit retries — a
+                // non-participant with a momentarily-absent header now fails the whole retry rather
+                // than being skipped (the coordinator still refreshes the remaining collections first,
+                // so a participant that can be finished is). That is the intended loud failure; if it ever shows up as
+                // otherwise-healthy transactions aborting, narrow that refresh to the transaction's
+                // participants (see the note at coordinator.ts's update loop) rather than softening
+                // this throw.
+                throw new CollectionHeaderVanishedError(this.id, this.source.actionContext.rev);
+            }
+            // The header is genuinely absent AND we hold no revision: nothing was ever committed under
+            // this id, so there is no log to walk and nothing to adopt — correct here, rather than a
+            // masked failure.
+            return;
+        }
+        this.logTailId = ends.header.tailId;
+        // Bootstrap context from committed tail so pending blocks are accessible.
+        Collection.bootstrapContext(source, ends.tail);
         // 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.
+        // {@link reportShortfall} call after advanceContext). Stays undefined when there is no
+        // tail, or a tail with no `latest` — both 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;
+        // A write's retry refresh always walks. Not needed for soundness — the write's own entry would
+        // sit above the held revision, which the tail test already refuses — but losing that entry
+        // loses the write, and a retry refresh is rare enough that the walk costs nothing that matters.
+        if (this.inFlightActionId === undefined && Collection.tailShowsNothingNewer(actionContext, ends.tail)) {
+            return;
+        }
+        // One block cache for the whole refresh, seeded with the header and tail just read: Log.open,
+        // the entry walk and the invalidation walk each start again from the header and the tail, and
+        // would otherwise fetch both every time. The seed came from UNPINNED reads and is served to
+        // reads pinned at the tail's claim, which is sound: the tail's content at its own claimed
+        // revision is that pinned view, and the header changes only when the tail block fills, which
+        // Chain.getTail already tolerates by following `nextId` from whichever tail the header names.
+        // NOTE: the cache keeps its default size (128 blocks, about 4,000 log entries). The entry walk
+        // reads every log block back to the head (no checkpoints), newest first, so past that size
+        // the newest blocks are evicted first and the invalidation walk fetches them again. If logs
+        // get that long before checkpoints land, walk entries and invalidations in one pass.
+        const tracker = new Tracker(new CacheSource(source, undefined, undefined, ends.served));
+        // Get the latest entries from the log, starting from where we left off
         const collectionLog = await Log.open(tracker, this.id);
         const latest = collectionLog ? await collectionLog.getFrom(actionContext?.rev ?? 0) : undefined;
+        // This write's own entry, if its log tail landed despite the failure that sent us here.
+        // Decided ONCE, here: the mark can be cleared latch-free while the completion below is
+        // awaiting (see {@link inFlightActionId}), and an entry that was finished as our own must
+        // not then be run through the conflict filter as a stranger's and replayed.
+        const inFlightActionId = this.inFlightActionId;
+        const ownEntry = inFlightActionId === undefined
+            ? undefined
+            : latest?.entries.find(entry => entry.actionId === inFlightActionId);
+        // Finish it BEFORE anything below changes this instance — see {@link completeOwnEntry}. A
+        // throw from here (the action cannot be finished, or not yet) therefore abandons the refresh
+        // with the staged actions, the tracker and the held revision exactly as they were.
+        // The entry's revision comes from the context the same walk built; an entry older than a
+        // checkpoint is not restated there, and completeOwnEntry falls back to the attempt's own.
+        const entryRevs = Collection.revisionsByAction(latest?.context);
+        if (ownEntry !== undefined) {
+            const durability = await this.completeOwnEntry(ownEntry, entryRevs.get(ownEntry.actionId), lastChance);
+            // Saved from here on, whatever below throws — record it before anything else can.
+            report.ownEntryFinished = { durability };
+        }
         // Process the entries and track the blocks they affect
         let anyConflicts = false;
         for (const entry of latest?.entries ?? []) {
-            const isOwnEntry = this.inFlightActionId !== undefined && entry.actionId === this.inFlightActionId;
+            const isOwnEntry = entry === ownEntry;
             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;
         }
         // React to durable invalidations that landed since we last synced. getFrom intentionally skips
@@ -478,33 +772,212 @@ export class Collection {
         // base (docs/right-is-right.md §Client notification). De-duped across cascade children by reverted
         // block; over-inclusive by design (over-invalidation just resubmits — it never wrongly retains).
         const invalidations = collectionLog ? await collectionLog.getInvalidationsFrom(actionContext?.rev ?? 0) : [];
-        if (invalidations.length > 0) {
-            const revertedBlockIds = [...new Set(invalidations.flatMap(inv => inv.reverted.map(r => r.blockId)))];
-            this.sourceCache.clear(revertedBlockIds);
-            if (this.pending.length > 0) {
-                anyConflicts = true;
-            }
+        const revertedBlockIds = [...new Set(invalidations.flatMap(inv => inv.reverted.map(r => r.blockId)))];
+        if (invalidations.length > 0 && this.pending.length > 0) {
+            anyConflicts = true;
         }
-        // Update our context to the latest — monotonically. An empty/unopenable log yields no
-        // context at all, and a log read that lags what we already committed yields an older one;
-        // neither is grounds for forgetting the revision we hold. This must happen BEFORE
-        // replayActions below: replay re-reads blocks through this.source, which materializes
-        // 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, this.instanceTag, 'refresh', latest?.context);
+        this.forgetAndAdopt(latest, entryRevs, revertedBlockIds);
         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
+        // 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.
         // NOTE: a throw out of replayActions leaves the tracker holding only the transforms
         // replayed so far while `pending` still lists them all; the caller's error handling is
-        // expected to abort/reset the collection rather than keep staging. If replay ever gains a
+        // expected to abort/reset the collection rather than keep staging. The coordinator's partial
+        // report after a refresh-saved sibling does not (backlog: debt-a-failed-refresh-can-leave-a-
+        // collection-half-restaged). If replay ever gains a
         // routinely-throwing read path, rebuild into a scratch tracker and swap on success.
-        if (anyConflicts) {
+        if (this.mustReplay(anyConflicts, actionContext)) {
             await this.replayActions();
         }
     }
+    /** Forget every block the refresh saw change, floor the ones a log entry names, and adopt the
+     * revision the log is at — ONE synchronous step, which must stay free of any `await`.
+     *
+     * Reads are not latched, so one can run while a refresh is under way. Forgetting a block while
+     * this handle still reads at the revision it is LEAVING invites exactly the wrong re-read: the
+     * block comes back as it was at that revision (correctly — that is what was asked for, and no
+     * floor applies to a read below it), the cache keeps it, and the advance that follows turns it
+     * into old content nothing will ever clear, the entry that named it having been consumed. That
+     * needs no lagging machine; storage can be perfectly current. With no gap between the forgetting
+     * and the adopting, a concurrent read either lands before both and is forgotten with the rest,
+     * or lands after both and is judged at the adopted revision — against the floor
+     * ({@link TransactorSource.tryGet} reads its context when the answer arrives, not when it was
+     * asked for) and against the generation the clear moved (`CacheSource.stillWanted`).
+     *
+     * The advance is monotonic (see {@link advanceContext}): an empty or unopenable log yields no
+     * context at all, and a log read that lags what this handle already committed yields an older
+     * one; neither is grounds for forgetting the revision held. It also has to precede
+     * {@link replayActions}, which re-reads blocks through `this.source` at whatever revision the
+     * context names — replaying first would refill the cache at the revision being left. */
+    forgetAndAdopt(latest, entryRevs, revertedBlockIds) {
+        for (const entry of latest?.entries ?? []) {
+            this.sourceCache.clear(entry.blockIds);
+            this.raiseFloors(entry, entryRevs.get(entry.actionId));
+        }
+        this.sourceCache.clear(revertedBlockIds);
+        Collection.advanceContext(this.source, this.id, this.instanceTag, 'refresh', latest?.context);
+    }
+    /** The revision each action in `context` committed at, keyed by action id. `Log.getFrom` returns
+     * entries without their revisions; the context the same walk built is where they are restated. */
+    static revisionsByAction(context) {
+        return new Map((context?.committed ?? []).map(({ actionId, rev }) => [actionId, rev]));
+    }
+    /** Records that the walked `entry` changed the blocks it names, so a later answer for one of
+     * them that is older than the entry is recognised and never remembered (see {@link BlockFloors}).
+     * Beside the cache clear on purpose (see {@link forgetAndAdopt}): the clear is what sends the next
+     * read of these blocks back to storage, and that read is the one a lagging machine can answer too
+     * old — after which nothing would clear the block again, this entry having been consumed.
+     *
+     * NOTE: an entry whose revision the walk did not restate sets no floor. That is an entry older
+     * than the log's most recent checkpoint, and no checkpoint is written today
+     * (tickets/backlog/debt-the-collection-log-never-writes-a-checkpoint). Once they are, such an
+     * entry's blocks go unguarded unless `Log.getFrom` starts returning each entry's revision. */
+    raiseFloors(entry, rev) {
+        if (rev !== undefined) {
+            this.floors.raise(entry.blockIds, { rev, actionId: entry.actionId });
+        }
+    }
+    /** Whether the log tail a refresh just read proves the log holds nothing newer than `held` —
+     * the test that lets a refresh with nothing to find stop after one request instead of walking
+     * the log.
+     *
+     * Sound because every commit and every invalidation appends a log entry, and entries only ever
+     * go on the tail block. A tail block that is still the end of the chain (no `nextId`), whose
+     * newest entry is at the held revision and names the action `held` names there — and whose own
+     * claim (`state.latest`) says the same — has nothing above `held`. The walk would then find no
+     * entries, no invalidations, and a context {@link advanceContext} adopts at an unchanged
+     * revision, so it would change nothing.
+     *
+     * Says "no" — sending the refresh down the full walk — whenever the tail and the held context
+     * disagree in any way, so everything that walk reports still fires:
+     * - a claim above `held` (ordinary catch-up) or below it (a lagging read);
+     * - a newest entry that is not the claimed action, or not an action at all: the entries lag the
+     *   claim (`collection:context-short-of-tail`, or `collection:context-not-lowered` for a handle
+     *   pinned by an over-claiming tail), or an invalidation or checkpoint took the newest slot;
+     * - any action entry in the tail block naming a different action than `held` names at the same
+     *   revision (`collection:lineage-divergence`, and the walk's adoption of the log's list).
+     *
+     * NOTE: the lineage comparison sees only the entries the tail block holds. A fork below them, on
+     * a log that has not moved, is not looked at again until a refresh finds something new — that
+     * walk compares the whole list. Walking every time to look is exactly the cost this avoids.
+     *
+     * NOTE: an invalidation entry in the newest slot never matches (it names no action), so every
+     * refresh after one walks the log until the next commit lands. Fine while disputes are rare; if
+     * they are not, match an invalidation slot against the held revision too. */
+    static tailShowsNothingNewer(held, tail) {
+        const claim = tail?.state.latest;
+        const block = tail?.block;
+        if (held === undefined || claim === undefined || !block || block.nextId !== undefined) {
+            return false;
+        }
+        const newest = block.entries[block.entries.length - 1];
+        return claim.rev === held.rev
+            && newest?.rev === claim.rev
+            && newest.action?.actionId === claim.actionId
+            && actionIdAt(held, held.rev) === claim.actionId
+            && !Collection.disagreesWithHeld(held, block.entries);
+    }
+    /** Whether any action entry in `entries` names a different action than `held` names at the same
+     * revision. A revision only one side names is missing evidence, not disagreement — the rule
+     * {@link earliestFork} applies too. */
+    static disagreesWithHeld(held, entries) {
+        const logged = new Map(entries.flatMap(entry => entry.action ? [[entry.rev, entry.action.actionId]] : []));
+        return held.committed.some(entry => {
+            const loggedAction = logged.get(entry.rev);
+            return loggedAction !== undefined && loggedAction !== entry.actionId;
+        });
+    }
+    /** Whether {@link updateInternal} must re-stage `pending` after adopting `latest`, given the
+     * context it held BEFORE the refresh.
+     *
+     * The answer is deliberately NOT just "a conflict was found". A conflict is detected by an
+     * incoming log entry naming a block this tracker already holds a transform for — so an action
+     * that changed NO block can never register one. A staged delete of a key this instance cannot
+     * see is exactly that action: the tree's `replace` handler misses on `find` and `deleteAt`
+     * returns false without writing. Gated on conflicts alone, such an action stayed in `pending`
+     * unapplied until the commit wrote a log entry listing it whose transforms did nothing — and
+     * readers materialize blocks, not log entries, so the action was lost on every node, silently
+     * and permanently. The invariant that has to hold is that **a pending action was applied
+     * against the revision it commits over**, so a mere revision advance is reason enough.
+     *
+     * The advance test rests on {@link advanceContext} being monotonic (it refuses to lower), which
+     * is what makes "the adopted rev differs from the held one" mean "it went up".
+     *
+     * The second conjunct is `pending.length` and deliberately NOT {@link hasUnsyncedChanges},
+     * which also counts tracker transforms. A collection {@link createOrOpen} just INVENTED holds
+     * its staged header/root in the tracker with NO pending action naming them, and
+     * {@link replayActions} resets the tracker before re-staging — so counting transforms here
+     * would drop those blocks and leave a brand-new collection unreadable (the same hazard
+     * {@link snapshotPending} documents). Nothing to re-stage means nothing to replay.
+     *
+     * NOTE: this makes a refresh that adopts a newer revision O(pending) rather than free, so a
+     * read taken mid-transaction while a rival keeps committing re-stages every action staged so
+     * far, on each such read. Measured as no change to the storage-op budgets
+     * (`index-backfill-cost.spec.ts`, `cold-apply-cost.spec.ts`), because the replay's reads are
+     * served from `sourceCache`. If a long transaction's reads ever show up as slow, narrow the
+     * replay to the actions whose reads the adopted entries actually invalidated — NOT back to
+     * conflicts alone, which is the defect above. */
+    mustReplay(anyConflicts, priorContext) {
+        if (anyConflicts) {
+            return true;
+        }
+        const adoptedRev = this.source.actionContext?.rev;
+        if (adoptedRev !== undefined && adoptedRev !== priorContext?.rev && this.pending.length > 0) {
+            return true;
+        }
+        // Third reason: a staged block's base has MOVED — the read cache no longer describes it at
+        // the revision its operations were computed against (see `Tracker.movedBases`). A refresh
+        // that adopted nothing and found no conflict can still be standing over such a block: a
+        // concurrent read served content the cache then kept at a newer revision, say. Re-staging
+        // is the only repair; declaring the pinned revision on the pend would merely get it refused.
+        return this.pending.length > 0 && this.logMovedBases(this.tracker.movedBases()) > 0;
+    }
+    /** Re-judge every staged update's pinned base against the read cache and re-stage the pending
+     * queue if any has moved. Runs immediately before each pend attempt — {@link syncAttempts} and
+     * the coordinator's commit span both call it — because that is the last moment before the
+     * base the pend declares is put on the wire, and nothing between a refused attempt and the
+     * re-pend reads the block again (the refresh may have moved nothing and so replayed nothing).
+     *
+     * Two steps. First, one read for each pinned block the cache does NOT retain — content handed
+     * through unkept (a below-floor answer, which the cache re-asks for on every read anyway): the
+     * pin names the revision last served, storage may have caught up since without the log moving,
+     * and only a read can tell. An evicted-but-kept base needs no read: its content met every floor
+     * the handle knows, so storage cannot have moved it without a log entry the next refresh will
+     * walk (and the pend would be refused as stale on revision alone). Then, one cache probe per
+     * pinned block ({@link Tracker.movedBases}) and a replay if any moved.
+     *
+     * Latch-free by contract, like {@link snapshotPending}: the caller holds this instance's latch
+     * ({@link replayActions} is always run under it).
+     *
+     * NOTE: reads are not latched, so a concurrent read can still move a base between this check
+     * and the pend. The pend then declares the pin's (old) revision, storage refuses it, and the
+     * next attempt's call here re-stages — one wasted round trip, never a wrong base. If that
+     * refusal ever shows up in practice, the closure is to hold the pend under the read latch.
+     *
+     * @returns whether the pending queue was re-staged. */
+    async restageIfBasesMoved() {
+        for (const id of this.tracker.unretainedBases()) {
+            // `navigation` never upgrades the purpose the original read recorded (value-wins), and
+            // the revision recorded is the one returned, which the replay below re-records anyway.
+            await this.sourceCache.tryGet(id, 'navigation');
+        }
+        if (this.pending.length === 0 || this.logMovedBases(this.tracker.movedBases()) === 0) {
+            return false;
+        }
+        await this.replayActions();
+        return true;
+    }
+    /** Report each moved base, naming the revision the operations were computed against and the
+     * one the cache describes now, and return how many there were. */
+    logMovedBases(moved) {
+        if (log.enabled) {
+            for (const blockId of moved) {
+                log('collection:restage-moved-base id=%s tag=%s block=%s pinnedRev=%s currentRev=%s', this.id, this.instanceTag, blockId, this.tracker.stagedBaseRevs([blockId])[blockId] ?? 'none', this.sourceCache.getCachedRevision(blockId) ?? 'none');
+            }
+        }
+        return moved.length;
+    }
     /** Capture the current staged state — tracker transforms plus the pending
      * action queue — so it can be restored later via {@link restorePending}.
      *
@@ -521,6 +994,7 @@ export class Collection {
     snapshotPending() {
         return {
             transforms: copyTransforms(this.tracker.transforms),
+            pins: this.tracker.pins.copy(),
             pending: [...this.pending],
             context: structuredClone(this.source.actionContext),
         };
@@ -547,7 +1021,10 @@ export class Collection {
      * rival's commit) still restores verbatim below — rebasing it would require an async
      * replay this synchronous method cannot run. That shape predates this guard and
      * keeps its old behaviour; if it is ever observed producing stale reads, the rebase
-     * belongs in an async caller that can replay the pending queue (see replayActions). */
+     * belongs in an async caller that can replay the pending queue (see replayActions).
+     * The WRITE side of that shape is closed here: the snapshot's base pins are restored with
+     * its transforms, so the restored operations name the bases they were computed on, and the
+     * pre-pend re-validation (restageIfBasesMoved) finds those bases moved and re-stages. */
     restorePending(snapshot) {
         const capturedRev = snapshot.context?.rev;
         const currentRev = this.source.actionContext?.rev;
@@ -558,6 +1035,8 @@ export class Collection {
             return;
         }
         this.tracker.reset(copyTransforms(snapshot.transforms));
+        if (snapshot.pins)
+            this.tracker.pins.replaceWith(snapshot.pins);
         this.pending = [...snapshot.pending];
     }
     /** A read-only {@link Tracker} pinned to this collection's committed state AS OF the
@@ -613,7 +1092,9 @@ export class Collection {
             // pin does not occur on the paths that reach here.
             seed = seed.filter(([, , revision]) => revision <= pinRev);
         }
-        const pinnedSource = new TransactorSource(this.id, this.transactor, structuredClone(pinContext), collector);
+        // The view shares this handle's floors, so a block the last refresh saw change is not kept
+        // too old by the view either. A view pinned below a floor is untouched by it.
+        const pinnedSource = new TransactorSource(this.id, this.transactor, structuredClone(pinContext), collector, this.floors);
         const pinnedCache = new CacheSource(pinnedSource, undefined, collector, seed);
         return new Tracker(pinnedCache, copyTransforms(transforms));
     }
@@ -791,18 +1272,47 @@ export class Collection {
      * 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) {
+        if (this.inFlightActionId !== actionId) {
+            // A different action's failed attempt cannot finish this one. Re-marking the SAME id (a
+            // coordinator re-marks on every attempt) keeps what the previous attempt retained — that
+            // is the attempt the next refresh may need.
+            this.inFlightAttempt = undefined;
+        }
         this.inFlightActionId = actionId;
         return () => {
             if (this.inFlightActionId === actionId) {
                 this.inFlightActionId = undefined;
+                this.inFlightAttempt = undefined;
             }
         };
     }
-    /** Push our pending actions to the transactor */
+    /** Keep what a FAILED attempt under `actionId` sent, so that if the refresh before its retry
+     * finds that attempt's own log entry it can finish the action rather than assume it finished
+     * (see {@link inFlightAttempt} and {@link completeOwnEntry}). Every write path that marks an
+     * action in flight must call this for each attempt that fails, BEFORE the refresh that follows —
+     * a path that does not still never reports a half-landed write as saved (the refresh then
+     * refuses with a `transforms-not-held` {@link TornActionError}), but it cannot recover from one.
+     *
+     * A no-op unless `actionId` is the action currently marked, so a late call from an attempt whose
+     * cycle has already ended cannot plant transforms under somebody else's mark. Latch-free and
+     * synchronous, like the mark itself: `TransactionCoordinator` calls it from inside its commit
+     * span, where it already holds this instance's latch. */
+    retainInFlightAttempt(actionId, attempt) {
+        if (this.inFlightActionId === actionId) {
+            this.inFlightAttempt = attempt;
+        }
+    }
+    /** Push our pending actions to the transactor.
+     *
+     * @returns who holds what this sync committed, or `undefined` when NOTHING WAS WRITTEN — a sync
+     * with no staged changes does no pend and no commit, so there is no durability to report and none
+     * is fabricated. That is the one case a caller must handle; every other outcome either returns a
+     * class or throws ({@link SyncRetryExhaustedError} for a write that never landed). Present a change
+     * as saved only via `isFullyDurable`, never by comparing `quorum`. */
     async sync(options) {
         const release = await Latches.acquire(this.latchId);
         try {
-            await this.syncInternal(options);
+            return await this.syncInternal(options);
         }
         finally {
             release();
@@ -818,13 +1328,16 @@ export class Collection {
         const actionId = uint8ArrayToString(bytes, 'base64url');
         const endInFlight = this.beginInFlightAction(actionId);
         try {
-            await this.syncAttempts(actionId, options);
+            return await this.syncAttempts(actionId, options);
         }
         finally {
             endInFlight();
         }
     }
-    /** The retry loop behind {@link syncInternal}, run with `actionId` already marked in flight. */
+    /** The retry loop behind {@link syncInternal}, run with `actionId` already marked in flight.
+     *
+     * @returns the durability of what this sync committed, or `undefined` when the loop never ran a
+     * commit (nothing staged). See {@link sync}. */
     async syncAttempts(actionId, options) {
         const maxAttempts = options?.maxAttempts ?? DefaultMaxAttempts;
         const baseBackoffMs = options?.baseBackoffMs ?? PendingRetryDelayMs;
@@ -852,6 +1365,11 @@ export class Collection {
         // The revision the PREVIOUS iteration would have requested, so the stall check can tell a
         // refresh that moved nowhere from one that is still climbing toward the confirmed number.
         let previousRequestedRev;
+        // Who holds what this sync has committed so far. Stays `undefined` while nothing has been
+        // committed, which is also the answer when the loop never runs at all — a sync with nothing
+        // staged writes nothing, and there is no durability to fabricate for it. Failed attempts never
+        // contribute: a refused attempt left nothing behind, so the answer is the committing attempt's.
+        let durability;
         while (this.hasUnsyncedChanges()) {
             if (signal?.aborted) {
                 throw makeAbortError(signal);
@@ -904,6 +1422,9 @@ export class Collection {
                 // Else: the responder told us nothing new this round. No strike, and no reset either
                 // — the budget stays bounded by maxAttempts.
             }
+            // A pending action is never pended over a base that has moved under it — before EVERY
+            // attempt, first and retries alike (see restageIfBasesMoved for why the retry needs it).
+            await this.restageIfBasesMoved();
             // 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.
@@ -935,47 +1456,118 @@ export class Collection {
             // 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());
+            // The base each update-only block's operations were computed against, for the pend (see
+            // `PendRequest.baseRevs`): the tracker's pinned revisions, which `restageIfBasesMoved` at the
+            // top of this iteration has just re-judged, so a moved base was re-staged before it is named.
+            const baseRevs = tracker.stagedBaseRevs(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), blockDigests);
-            if (staleFailure) {
+            const attempt = await this.source.transact(tracker.transforms, actionId, newRev, this.id, addResult.tailPath.block.header.id, clampPriority(consecutiveFailures), blockDigests, baseRevs);
+            if (!attempt.success) {
                 consecutiveFailures++;
-                lastReason = staleFailure.reason ?? lastReason;
+                lastReason = attempt.reason ?? lastReason;
                 // Highest-wins, not last-wins: the next request has to clear EVERY holder, so a later
                 // responder reporting a LOWER number understates the binding constraint. Same rule the
                 // producers and the transactor's aggregation already use.
-                lastStaleAt = highestStaleAt([lastStaleAt, staleFailure.staleAt]);
-                lastFailureConfirmedStaleAt = staleFailure.staleAt !== undefined;
+                lastStaleAt = highestStaleAt([lastStaleAt, attempt.staleAt]);
+                lastFailureConfirmedStaleAt = attempt.staleAt !== undefined;
                 // Give up once the consecutive no-progress budget is exhausted, so a transactor that
                 // persistently rejects the sync can no longer hold the collection latch forever.
                 // NOTE: this also bounds the legitimate `pending`-wait case (retrying the same action
                 // while another commit is in flight), which used to retry indefinitely. Default 10
                 // attempts ≈ 21s of exponential backoff. If a high-contention workload legitimately
                 // needs to wait longer for a pending commit to clear, raise maxAttempts for that caller.
+                // NOTE: no refresh follows the LAST budgeted attempt, so if that attempt's log tail
+                // landed nobody finds out: the caller gets plain exhaustion over a log that holds an
+                // entry for this write. The write is still never reported saved, which is the rule; what
+                // is lost is the more specific name (TornActionError). The leftover entry itself is
+                // tracked in tickets/backlog/bug-a-refused-write-can-leave-its-log-entry-behind.
                 if (consecutiveFailures >= maxAttempts) {
                     throw new SyncRetryExhaustedError(this.id, consecutiveFailures, lastReason, lastStaleAt);
                 }
-                // Back off before every retry (any stale failure — reason/missing/pending), growing
-                // exponentially from the base delay up to the cap, with proportional random jitter so a
-                // herd of clients that lost the same race does not re-collide on the next tick (see
-                // utility/backoff.ts). The abortable sleep lets an aborted sync reject promptly instead
-                // of finishing the sleep.
-                // NOTE: the `missing`/`reason` conflict paths now pay this backoff too (they previously
-                // retried with zero delay); that is what stops the persistent-`reason` hot spin. If a
-                // high-contention workload ever shows this base delay as recovery latency, lower
-                // 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.
-                // 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();
+                // Keep exactly what this attempt sent. A refused commit is not proof nothing landed:
+                // the log tail is committed first and can be stored while the answer is still a
+                // failure, and `transact` has just cancelled every block that did not land. If the
+                // refresh below finds this attempt's own entry, these are the transforms that finish
+                // the action (see completeOwnEntry). The snapshot tracker is abandoned after this
+                // iteration, so its transforms are handed over as-is, uncopied.
+                this.retainInFlightAttempt(actionId, {
+                    rev: newRev,
+                    transforms: tracker.transforms,
+                    tailId: addResult.tailPath.block.header.id,
+                    ...(blockDigests === undefined ? {} : { blockDigests }),
+                    ...baseRevsField(baseRevs),
+                });
+                // Refresh, and keep refreshing while it reports that this write's own half-landed
+                // action could not be finished YET. It must not fall through to a new attempt in that
+                // state: a new attempt rebuilds the log entry (fresh timestamp) and would send a second
+                // version of a log tail that is already stored under this action and revision. Each
+                // round is a failure against the same no-progress budget as a refused attempt.
+                for (;;) {
+                    // Back off before every retry (any stale failure — reason/missing/pending), growing
+                    // exponentially from the base delay up to the cap, with proportional random jitter so a
+                    // herd of clients that lost the same race does not re-collide on the next tick (see
+                    // utility/backoff.ts). The abortable sleep lets an aborted sync reject promptly instead
+                    // of finishing the sleep.
+                    // NOTE: the `missing`/`reason` conflict paths now pay this backoff too (they previously
+                    // retried with zero delay); that is what stops the persistent-`reason` hot spin. If a
+                    // high-contention workload ever shows this base delay as recovery latency, lower
+                    // 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);
+                    try {
+                        // 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 (its log tail landed but
+                        // the commit answered failure), FINISHES that action from the attempt retained
+                        // above, and only then consumes the entry rather than replaying it into a duplicate.
+                        // The round that would spend the last of the budget settles a half-landed write
+                        // instead of asking for another round, so the error that escapes below says
+                        // whether the write can still land. (A deadline cannot be foreseen the same
+                        // way; a write given up on it escapes unsettled, as `final: false`.)
+                        const report = {};
+                        await this.updateInternal(report, consecutiveFailures + 1 >= maxAttempts);
+                        const completed = report.ownEntryFinished?.durability;
+                        if (completed !== undefined) {
+                            // The refresh made this sync's write durable: that is a commit, and it is
+                            // reported and counted exactly like one made by an attempt (see the success
+                            // branch below for why batches fold to the weakest).
+                            durability = durability === undefined ? completed : mergeDurability([durability, completed]);
+                            consecutiveFailures = 0;
+                            lastReason = undefined;
+                            lastStaleAt = undefined;
+                            lastFailureConfirmedStaleAt = false;
+                            consecutiveStalls = 0;
+                        }
+                        break;
+                    }
+                    catch (err) {
+                        if (!(err instanceof TornActionError) || err.reason !== 'completion-refused') {
+                            throw err;
+                        }
+                        // Refused for a cause that can clear. The error already names the write as torn,
+                        // which is the truth if the budget ends here — so it, not a plain exhaustion,
+                        // is what escapes: the log holds an entry for a write that was not saved.
+                        consecutiveFailures++;
+                        lastReason = err.detail;
+                        if (consecutiveFailures >= maxAttempts
+                            || (deadlineMs !== undefined && Date.now() - startedAt >= deadlineMs)) {
+                            throw err;
+                        }
+                    }
+                }
             }
             else {
+                // This attempt's commit landed, so its durability is the one to report. A sync that
+                // commits ONCE — every sync that has a caller today — reports exactly that answer,
+                // untouched. A sync whose loop commits more than one batch (the `hasUnsyncedChanges`
+                // condition re-entering after a successful commit) folds the batches with
+                // `mergeDurability`, whose scalar answer is the WEAKEST of them: one batch that only
+                // reached the writer makes the whole sync only-on-the-writer, and reporting the last
+                // batch's class instead would show such a write as saved.
+                durability = durability === undefined ? attempt.durability : mergeDurability([durability, attempt.durability]);
                 // Forward progress: reset the no-progress budget.
                 consecutiveFailures = 0;
                 lastReason = undefined;
@@ -1003,17 +1595,81 @@ export class Collection {
                     : { committed: [{ actionId, rev: newRev }], rev: newRev };
             }
         }
+        return durability;
     }
+    /** Refresh from the transactor, then push. Same return contract as {@link sync}: the durability of
+     * what was committed, or `undefined` when nothing was staged and so nothing was written. */
     async updateAndSync(options) {
         const release = await Latches.acquire(this.latchId);
         try {
-            await this.updateInternal();
-            await this.syncInternal(options);
+            await this.updateInternal({});
+            return await this.syncInternal(options);
+        }
+        finally {
+            release();
+        }
+    }
+    /** Stage `actions` and flush them as one call that either takes effect or leaves NOTHING behind:
+     * when the flush throws, the actions this call staged are unstaged again before the error escapes.
+     *
+     * For callers that own both halves of a write (`Tree.replace`, `Diary.append`). Staging with
+     * {@link act} and flushing separately leaves a failed write's actions staged — deliberate for a
+     * caller that means to call {@link sync} again, and a trap for one that does not: the actions
+     * ride along, unasked, with its NEXT write, so a change the caller was told had failed shows up
+     * later, and a caller that reacted to the failure by submitting it again stores it twice. That
+     * is how a write reported torn was seen to "appear one write later" (the pending-record route
+     * first suspected was ruled out: with the failed writer's collection discarded, 0 of 17 torn
+     * rows ever appeared).
+     *
+     * One latch hold spans staging and flushing, so no other {@link act} on this instance can land
+     * between them and the actions to take back are exactly the ones this call put there.
+     *
+     * The error is rethrown untouched. Unstaging says nothing about storage: a
+     * {@link TornActionError} with `final: false` still means the write may be saved or may yet
+     * land, and only the staged copy is gone. */
+    async actAndSync(actions, options) {
+        const release = await Latches.acquire(this.latchId);
+        try {
+            const stagedBefore = copyTransforms(this.tracker.transforms);
+            const revBefore = this.source.actionContext?.rev;
+            await this.actInternal(...actions);
+            try {
+                await this.updateInternal({});
+                return await this.syncInternal(options);
+            }
+            catch (err) {
+                await this.unstage(actions, stagedBefore, revBefore);
+                throw err;
+            }
         }
         finally {
             release();
         }
     }
+    /** Takes `actions` back out of the staged queue and rebuilds the tracker without them (always
+     * called under latch). `stagedBefore` / `revBefore` are the tracker's transforms and the held
+     * revision from before the actions were staged.
+     *
+     * While the held revision has not moved, the earlier transforms are reinstated verbatim rather
+     * than rebuilt by replay: an INVENTED collection keeps its header and root in the tracker with
+     * no staged action naming them, and a replay (which resets the tracker first) would drop them —
+     * the hazard {@link mustReplay} and {@link snapshotPending} document. Once the revision has
+     * moved those transforms describe blocks at a revision this handle has left, so what remains is
+     * re-staged against the adopted one, exactly as a refresh would have done. */
+    async unstage(actions, stagedBefore, revBefore) {
+        // NOTE: matched by identity, which is what `filterAgainstEntry` promises for a kept action.
+        // A `filterConflict` hook that answers a REPLACEMENT instance for one of these actions would
+        // leave the replacement staged here. No collection installs such a hook today (`Tree` and
+        // `Diary` install none); if one ever does, carry a per-call token on the staged actions and
+        // match on that instead.
+        this.pending = this.pending.filter(staged => !actions.includes(staged));
+        if (this.source.actionContext?.rev === revBefore) {
+            this.tracker.reset(stagedBefore);
+        }
+        else {
+            await this.replayActions();
+        }
+    }
     async *selectLog(forward = true) {
         const collectionLog = await Log.open(this.tracker, this.id);
         if (!collectionLog) {
@@ -1049,54 +1705,93 @@ export class Collection {
     doFilterConflict(action, potential) {
         return this.filterConflict ? this.filterConflict(action, potential) : action;
     }
+    /** The two blocks every refresh starts from — the collection header and the log tail block it
+     * names — read unpinned ("latest"), in ONE request when `knownTailId` is the tail the header
+     * names. Only when the header names a different tail (the known one filled, or none was known)
+     * is that tail fetched in a second request; the out-of-date block's answer is dropped rather
+     * than kept, because nothing proves it is current at the revision the refresh will pin to.
+     *
+     * Both answers pass {@link answeredBlock}'s checks as unpinned reads, header first, so a doubted
+     * header or tail throws exactly as it would through {@link TransactorSource.tryGet}.
+     *
+     * NOTE: a batched get fails as a whole when any block in it gets no answer
+     * (`NetworkTransactor.get` throws on a missing id), so an unreachable out-of-date tail fails a
+     * refresh that would not have needed it. Harmless today: the log has no checkpoints, so a
+     * refresh that finds a new tail walks back through the old one anyway. If checkpoints start
+     * letting that walk stop short, read the known tail in its own request instead.
+     *
+     * @returns undefined when the header is authoritatively absent. */
+    static async readLogEnds(transactor, id, knownTailId) {
+        const results = await transactor.get({ blockIds: knownTailId === undefined ? [id] : [id, knownTailId] });
+        const headerEntry = results?.[id];
+        if (headerEntry === undefined) {
+            return undefined;
+        }
+        const header = answeredBlock(id, headerEntry, undefined);
+        if (!header) {
+            return undefined;
+        }
+        const served = [[id, header, servedRevision(headerEntry)]];
+        const tailId = header.tailId;
+        if (tailId === undefined) {
+            return { header, served };
+        }
+        const tail = tailId === knownTailId
+            ? Collection.checkedLogTail(tailId, results[tailId])
+            : await Collection.readLogTail(transactor, tailId);
+        if (tail?.block) {
+            served.push([tailId, tail.block, servedRevision(tail)]);
+        }
+        return { header, tail, served };
+    }
+    /** An unpinned read of the log tail block, checked as {@link checkedLogTail} describes. */
+    static async readLogTail(transactor, tailId) {
+        return Collection.checkedLogTail(tailId, (await transactor.get({ blockIds: [tailId] }))?.[tailId]);
+    }
+    /** The repo's answer for the log tail, once it has passed {@link answeredBlock}'s unpinned-read
+     * checks. The raw entry, not just the block, is what a refresh needs — {@link bootstrapContext}
+     * reads `state.latest` off it — which is why the tail is read around {@link TransactorSource}
+     * and has to be checked here.
+     *
+     * Both checks matter at this seam in particular. A tail the repo could not retrieve must not
+     * degrade into "no context", which would leave the chain walk unable to see pending non-tail
+     * blocks and the collection reading as if they did not exist. And this unpinned tail read is
+     * the ONE seam where a lagging collection can learn a newer revision exists — every later data
+     * read is pinned to the context seeded from it — so seeding from a tail the repo could not
+     * confirm is current would freeze the collection at the stale revision with nothing ever
+     * reporting a problem. A tail with no `state.latest` and no flag is a real answer (nothing
+     * committed yet). */
+    static checkedLogTail(tailId, entry) {
+        if (entry) {
+            answeredBlock(tailId, entry, undefined);
+        }
+        return entry;
+    }
     /** Bootstrap ActionContext from the committed tail block's state.
      * The tail is always committed first (commit protocol guarantee), so it's readable
      * with context=undefined. Its state.latest contains the ActionRev of the most recent
      * committed action — exactly the proof needed for the transactor to serve pending
-     * non-tail blocks during chain walks.
-     *
-     * This read goes to the transactor directly rather than through {@link TransactorSource},
-     * so it has to honour the `unavailable` flag itself: a tail the repo could not retrieve
-     * must not degrade into "no context", which would leave the chain walk unable to see
-     * pending non-tail blocks and the collection reading as if they did not exist. A tail
-     * with no `state.latest` and NO flag is a real answer (nothing committed yet) and still
-     * no-ops.
-     *
-     * The same goes for `unconfirmedAheadRev`: this unpinned tail read is the ONE seam where a
-     * lagging collection can learn a newer revision exists — every later data read is pinned to
-     * the context seeded here. Silently seeding from a tail the repo could not confirm is
-     * current would freeze the collection at the stale revision with nothing ever reporting a
-     * problem, so it throws the same way TransactorSource.tryGet does for its unpinned reads
-     * (see the tradeoff NOTE there).
+     * non-tail blocks during chain walks. A tail with no `latest` (or no tail) no-ops.
+     *
+     * 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 (the claim's newest
+     * entry never matches, so {@link tailShowsNothingNewer} never lets it skip), 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.
      */
-    static async bootstrapContext(source, transactor, header) {
-        const tailId = header.tailId;
-        if (tailId) {
-            const tailResult = await transactor.get({ blockIds: [tailId] });
-            const tailEntry = tailResult?.[tailId];
-            if (tailEntry?.unavailable !== undefined && tailEntry.block == null) {
-                throw new BlockUnavailableError(tailId, tailEntry.unavailable);
-            }
-            if (tailEntry?.unconfirmedAheadRev !== undefined) {
-                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 }],
-                    rev: tailState.latest.rev,
-                };
-            }
+    static bootstrapContext(source, tail) {
+        const latest = tail?.state.latest;
+        if (latest) {
+            source.actionContext = {
+                committed: [{ actionId: latest.actionId, rev: latest.rev }],
+                rev: latest.rev,
+            };
         }
     }
 }