@optimystic/db-core 1.0.0-beta.2 → 1.0.0

package/dist/src/collection/collection.d.ts

@@ -1,10 +1,54 @@
-import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, BlockStore, Transforms, ActionId } from "../index.js";
+import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, BlockStore, Transforms, ActionId, BlockContentDigests } from "../index.js";
 import { Tracker } from "../transform/tracker.js";
+import type { BasePins } from "../transform/base-pins.js";
 import { CacheSource } from "../transform/cache-source.js";
+import type { BlockBaseRevs } from "../network/struct.js";
 import { TransactorSource } from "../transactor/transactor-source.js";
+import { BlockFloors } from "../transactor/block-floors.js";
+import type { WriteDurability } from "../network/struct.js";
 import type { CollectionId, ICollection, SyncOptions } from "./index.js";
 import type { ActionContext } from "./action.js";
 import type { ReadDependency } from "../transaction/transaction.js";
+/** Exactly what one failed write attempt sent to the transactor — enough to send the same thing
+ * again. Retained by {@link Collection.retainInFlightAttempt} so that a refresh which then finds
+ * this attempt's own log entry can land the blocks the attempt left behind, at the same action id
+ * and revision (see {@link Collection.completeOwnEntry}). */
+export type InFlightAttempt = {
+    /** The revision the attempt's log entry was stamped with, and pended and committed at. */
+    rev: number;
+    /** Every transform the attempt pended — the log blocks included. The caller hands over a copy
+     * it will not mutate; the collection keeps it as given. */
+    transforms: Transforms;
+    /** The attempt's log tail block, committed first. */
+    tailId: BlockId;
+    /** The per-block content declarations the attempt's commit carried, if any. */
+    blockDigests?: BlockContentDigests;
+    /** The per-block bases the attempt's pend carried, if any (see `PendRequest.baseRevs`). Kept
+     * with the transforms because they describe them: a re-send of these operations must name the
+     * same bases they were computed against. */
+    baseRevs?: BlockBaseRevs;
+};
+/** What one refresh ({@link Collection.refreshInFlight}, and the refresh inside a sync) found out
+ * about the write in flight on the instance's behalf. The caller hands in an empty report and the
+ * refresh fills it in AS IT GOES, rather than returning it at the end, so a refresh that throws
+ * after it saved the write still says so: the write is saved in storage whatever happens to this
+ * instance's local bookkeeping afterwards.
+ *
+ * NOTE: filled in, not returned, because a return value is lost on a throw — and a refresh CAN
+ * throw after finishing its own entry (the invalidation read and the replay both run later). */
+export type RefreshReport = {
+    /** Set once the refresh found the in-flight write's own log entry and FINISHED it
+     * ({@link Collection.completeOwnEntry}): every block the entry names holds the write, so it is
+     * saved. Left unset on every other refresh, including every reader's.
+     *
+     * `durability` is who holds the finished write, when the refresh learned it. It is absent when
+     * finishing found every block already holding the write without re-sending anything (the
+     * status-read fallback), which is still a saved write — so test the field, never `durability`,
+     * for "saved". */
+    ownEntryFinished?: {
+        durability?: WriteDurability;
+    };
+};
 export type CollectionInitOptions<TAction> = {
     modules: Record<ActionType, ActionHandler<TAction>>;
     createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => IBlock;
@@ -42,6 +86,12 @@ export interface ReadViewOptions {
 export interface CollectionSnapshot<TAction> {
     /** Deep-cloned tracker transforms at snapshot time. */
     transforms: Transforms;
+    /** The bases the transforms' update operations were computed against (see {@link BasePins}),
+     *  copied at snapshot time. Restored with the transforms, so a restore never pairs operations
+     *  with the bases of some later re-stage: the pend would then declare a base the operations
+     *  were not built on. Absent on a snapshot built by hand; such a restore keeps whatever pins
+     *  the tracker holds for the restored ids. */
+    pins?: BasePins;
     /** Pending actions queued at snapshot time. */
     pending: Action<TAction>[];
     /** The committed boundary (action context) the staged state sat on when captured.
@@ -61,6 +111,10 @@ export declare class Collection<TAction> implements ICollection<TAction> {
     private readonly sourceCache;
     /** Tracked Changes */
     readonly tracker: Tracker<IBlock>;
+    /** 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}). */
+    private readonly floors;
     private readonly 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);
@@ -70,36 +124,66 @@ export declare class Collection<TAction> implements ICollection<TAction> {
     private readonly 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. */
     private 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. */
+    private 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. */
+    private logTailId?;
     protected constructor(id: CollectionId, transactor: ITransactor, handlers: Record<ActionType, ActionHandler<TAction>>, source: TransactorSource<IBlock>, 
     /** Cache of unmodified blocks from the source */
     sourceCache: CacheSource<IBlock>, 
     /** Tracked Changes */
-    tracker: Tracker<IBlock>, filterConflict?: ((action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined) | undefined, 
+    tracker: Tracker<IBlock>, 
+    /** 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: BlockFloors, filterConflict?: ((action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined) | undefined, 
     /** 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. */
@@ -132,6 +216,13 @@ export declare class Collection<TAction> implements ICollection<TAction> {
     /** 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. */
     private static probeHeader;
+    /** 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. */
+    private static newFloors;
     /** 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
      * absence — throw rather than let the collection read as empty. (The re-read goes through
@@ -253,8 +344,102 @@ export declare class Collection<TAction> implements ICollection<TAction> {
     private internalTransact;
     /** Load external changes and update our context to the latest log revision - resolve any conflicts with our pending actions. */
     update(): Promise<void>;
-    /** Drops the pending actions this sync's OWN committed entry already made durable, instead of
-     * replaying them into a duplicate entry (see {@link inFlightActionId}).
+    /** 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}). */
+    refreshInFlight(report: RefreshReport, lastChance: boolean): Promise<void>;
+    /** 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. */
+    private completeOwnEntry;
+    /** 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. */
+    private settleUnfinished;
+    /** 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. */
+    private dischargeOwnPendings;
+    /** 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. */
+    private lineageOfOwnEntry;
+    private throwTorn;
+    /** 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
@@ -283,8 +468,141 @@ export declare class Collection<TAction> implements ICollection<TAction> {
      *
      * 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. */
+     * 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. */
     private updateInternal;
+    /** 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. */
+    private forgetAndAdopt;
+    /** 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. */
+    private static revisionsByAction;
+    /** 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. */
+    private raiseFloors;
+    /** 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. */
+    private static tailShowsNothingNewer;
+    /** 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. */
+    private static disagreesWithHeld;
+    /** 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. */
+    private mustReplay;
+    /** 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. */
+    restageIfBasesMoved(): Promise<boolean>;
+    /** 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. */
+    private logMovedBases;
     /** Capture the current staged state — tracker transforms plus the pending
      * action queue — so it can be restored later via {@link restorePending}.
      *
@@ -301,7 +619,30 @@ export declare class Collection<TAction> implements ICollection<TAction> {
     snapshotPending(): CollectionSnapshot<TAction>;
     /** Restore the staged state captured by {@link snapshotPending}, discarding any
      * mutations staged since. Reads through the collection then observe exactly the
-     * snapshot state again; storage is untouched because nothing was ever synced. */
+     * snapshot state again; storage is untouched because nothing was ever synced.
+     *
+     * A snapshot is only restorable VERBATIM onto the committed boundary it was captured
+     * on. If this collection has since ADOPTED a newer committed revision — a rival's
+     * commit folded in by a refresh while the snapshot's transaction was in flight, e.g.
+     * the conflict replay that refused a guarded insert (TreeKeyTakenError) — the
+     * snapshot's transforms describe block state at the OLD boundary, and reinstalling
+     * them would shadow committed blocks with stale structure. The observed case: an
+     * INVENTED collection's pre-commit header/root transforms restored over the rival's
+     * now-committed collection make every later read descend an empty tree, silently
+     * hiding the committed rows. When the snapshot's pending queue is empty (the
+     * transaction-rollback shape: the capture predates the transaction's first stage),
+     * the correct restore target IS the committed state — reset the tracker empty and
+     * let reads flow through to the adopted revision.
+     *
+     * NOTE: a snapshot that carries PENDING actions across a moved boundary (a
+     * mid-transaction savepoint captured before a mid-transaction refresh adopted a
+     * 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).
+     * 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: CollectionSnapshot<TAction>): void;
     /** A read-only {@link Tracker} pinned to this collection's committed state AS OF the
      * moment of this call, seeded with a (deep-copied) set of pre-transaction transforms.
@@ -387,7 +728,14 @@ export declare class Collection<TAction> implements ICollection<TAction> {
      * 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. */
+     * how an operator reads the difference.
+     *
+     * The one exception is `undefined` itself, which is a STATE rather than a revision:
+     * "this instance invented the collection and has never adopted a committed revision".
+     * For the same reason (only this instance moves it), it stays true until this instance
+     * updates, syncs or records a commit, so a caller holding a freshly opened instance may
+     * branch on it — the Quereus adapter does, to leave an invented, never-written index tree
+     * unflushed exactly as an unwritten table tree is left. Never branch on the NUMBER. */
     committedRevision(): number | undefined;
     /** 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
@@ -484,17 +832,70 @@ export declare class Collection<TAction> implements ICollection<TAction> {
      * 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: ActionId): () => void;
-    /** Push our pending actions to the transactor */
-    sync(options?: SyncOptions): Promise<void>;
+    /** 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: ActionId, attempt: InFlightAttempt): void;
+    /** 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`. */
+    sync(options?: SyncOptions): Promise<WriteDurability | undefined>;
     /** 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. */
     private syncInternal;
-    /** 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}. */
     private syncAttempts;
-    updateAndSync(options?: SyncOptions): Promise<void>;
+    /** 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. */
+    updateAndSync(options?: SyncOptions): Promise<WriteDurability | undefined>;
+    /** 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. */
+    actAndSync(actions: Action<TAction>[], options?: SyncOptions): Promise<WriteDurability | undefined>;
+    /** 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. */
+    private unstage;
     selectLog(forward?: boolean): AsyncIterableIterator<Action<TAction>>;
     private replayActions;
     getReadDependencies(): ReadDependency[];
@@ -506,25 +907,56 @@ export declare class Collection<TAction> implements ICollection<TAction> {
      * 	instance (applied instead of the original), or undefined to discard it.
      */
     protected doFilterConflict(action: Action<TAction>, potential: Action<TAction>[]): Action<TAction> | undefined;
+    /** 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. */
+    private static readLogEnds;
+    /** An unpinned read of the log tail block, checked as {@link checkedLogTail} describes. */
+    private static readLogTail;
+    /** 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). */
+    private static checkedLogTail;
     /** 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.
      */
     private static bootstrapContext;
 }