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

package/src/transactor/transactor-source.ts

@@ -1,14 +1,65 @@
 import { randomBytes } from '@noble/hashes/utils.js'
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
-import type { IBlock, BlockId, BlockHeader, ITransactor, ActionId, StaleFailure, ActionContext, BlockType, BlockSource, ReadPurpose, Transforms, BlockContentDigests } from "../index.js";
+import type { IBlock, BlockId, BlockHeader, ITransactor, ActionId, CommitResult, ActionContext, BlockType, BlockSource, ReadPurpose, Transforms, BlockContentDigests, BlockBaseRevs, GetBlockResult } from "../index.js";
 import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struct.js";
 import type { ReadDependency } from "../transaction/transaction.js";
 import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
-import { blockDigestsField } from "../transform/digest.js";
+import { blockDigestsField, baseRevsField } from "../transform/digest.js";
+import type { BlockFloorCheck } from "./block-floors.js";
 import { createLogger } from "../logger.js";
 
 const log = createLogger('transactor-source');
 
+/** The block `entry` answers for `id`, for a read at `context` (`undefined` for an unpinned "give me
+ * latest" read) — `undefined` when the block is absent — or a throw when the entry is not an answer
+ * that read may use. Every read that consumes a raw {@link GetBlockResult} goes through here, so a
+ * doubted answer cannot be treated differently depending on which path fetched it.
+ *
+ * An entry flagged `unavailable` with no block is the repo saying "I could not find out whether this
+ * exists" — an answer that must not be read as absent. A repo that omits the flag stays authoritative.
+ *
+ * A read whose surviving answer is marked possibly-behind (`unconfirmedAheadRev` outlived the
+ * transactor's retry round: every reachable coordinator served content it could not confirm current)
+ * must not pose as an answer for a view that should CONTAIN the claimed revision. Two such views, the
+ * same test the coordinator applies when it stamps: an UNPINNED read — the tail read is the one seam
+ * where a lagging collection can learn the truth (Collection.checkedLogTail), and silently serving
+ * doubted content there is exactly how a collection view freezes forever — and a read PINNED AT OR
+ * ABOVE the claim, whose snapshot is missing a revision the cohort says exists inside it. A read pinned
+ * strictly BELOW the claim keeps working: it legitimately asks for an older view, which is being
+ * served correctly.
+ *
+ * NOTE: accepted tradeoff — this converts a silent wrong answer into a loud failure. A node partitioned
+ * from every coordinator able to confirm currency used to read (stale) data indefinitely without any
+ * signal; it now raises BlockPossiblyStaleError on the reads that should contain the claim, until the
+ * partition heals or the claim is settled. Deliberate: the silent alternative is a collection view that
+ * forks and freezes with no report (ticket coordinator-serves-stale-data-as-if-confirmed). Revisit only
+ * if a degraded-read mode (serve-with-warning) becomes a product requirement. */
+export function answeredBlock(id: BlockId, entry: GetBlockResult, context: ActionContext | undefined): IBlock | undefined {
+	const { block, unavailable, unconfirmedAheadRev } = entry;
+	if (!block && unavailable) {
+		throw new BlockUnavailableError(id, unavailable);
+	}
+	if (unconfirmedAheadRev !== undefined && (context === undefined || context.rev >= unconfirmedAheadRev)) {
+		throw new BlockPossiblyStaleError(id, unconfirmedAheadRev);
+	}
+	return block;
+}
+
+/** The revision a served block's content IS: its materialized revision, falling back to the repo's
+ * latest for repos that omit the field (see {@link GetBlockResult.materialized} for why `state.latest`
+ * alone is the wrong number). */
+export function servedRevision(entry: GetBlockResult): number {
+	return entry.materialized?.rev ?? entry.state.latest?.rev ?? 0;
+}
+
+/** What a source knows about one block it returned — see {@link TransactorSource.describeServed}. */
+export type ServedBlock = {
+	/** The revision the content is ({@link servedRevision} of the answer it came from). */
+	rev: number;
+	/** Whether a cache may keep the block and serve it again without re-asking. */
+	mayRetain: boolean;
+};
+
 export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlock> {
 	/** Shared with this collection's CacheSource so cache hits also record dependencies.
 	 *  Defaults to a private instance so internal log-walk sources (which never need a
@@ -17,12 +68,20 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 	/** Last revision observed per id, so CacheSource can learn the revision on a miss-load
 	 *  (it calls {@link getReadRevision} right after this source serves the block). */
 	private readRevisions = new Map<BlockId, number>();
+	/** What this source knows about each block OBJECT it returned, for {@link describeServed}. Keyed
+	 *  by the object rather than by id because a cache reads it after an `await`: with two reads of
+	 *  one id in flight, a by-id record holds whichever answer was processed last, and would pair one
+	 *  answer's content with the other's revision and verdict. Weak, so it holds nothing alive. */
+	private served = new WeakMap<IBlock, ServedBlock>();
 
 	constructor(
 		private readonly collectionId: BlockId,
 		private readonly transactor: ITransactor,
 		public actionContext: ActionContext | undefined,
 		collector?: ReadDependencyCollector,
+		/** The owning collection's floors, shared with every other read source it builds. Omitted by
+		 *  sources that walk the log or are built standalone: their answers are judged against nothing. */
+		private readonly floors?: BlockFloorCheck,
 	) {
 		this.collector = collector ?? new ReadDependencyCollector();
 	}
@@ -41,43 +100,22 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 	}
 
 	async tryGet(id: BlockId, purpose: ReadPurpose = 'value'): Promise<TBlock | undefined> {
-		const result = await this.transactor.get({ blockIds: [id], context: this.actionContext });
+		// Carry the floor that applies to THIS read, so a transactor with more than one machine to
+		// ask can re-ask when the first answers under it (`BlockGets.floors`). Advisory: the verdict
+		// that matters is still `mayRetain` below, on whatever answer comes back.
+		const floor = this.floors?.applicableTo(id, this.actionContext);
+		const result = await this.transactor.get({
+			blockIds: [id],
+			context: this.actionContext,
+			...(floor !== undefined ? { floors: { [id]: floor.rev } } : {}),
+		});
 		// Guard the per-key entry: some transactors return a sparse result that omits `id`
 		// entirely (e.g. block genuinely not found), so `result` is a truthy object but
 		// `result[id]` is undefined. Destructuring that would throw a TypeError.
 		const entry = result?.[id];
 		if (entry) {
-			const { block, state, materialized, unavailable, unconfirmedAheadRev } = entry;
-			// An entry flagged `unavailable` with no block is the repo saying "I could not find
-			// out whether this exists" — an answer that must not be read as absent. Throw rather
-			// than return undefined, and record no read dependency (dependencies are recorded
-			// only for blocks that actually exist). A repo that omits the flag stays authoritative.
-			if (!block && unavailable) {
-				throw new BlockUnavailableError(id, unavailable);
-			}
-			// A read whose surviving answer is marked possibly-behind (`unconfirmedAheadRev`
-			// outlived the transactor's retry round: every reachable coordinator served content it
-			// could not confirm current) must not pose as an answer for a view that should CONTAIN
-			// the claimed revision. Two such views, the same test the coordinator applies when it
-			// stamps: an UNPINNED "give me latest" read — the tail read is the one seam where a
-			// lagging collection can learn the truth (Collection.bootstrapContext), and silently
-			// serving doubted content there is exactly how a collection view freezes forever — and
-			// a read PINNED AT OR ABOVE the claim, whose snapshot is missing a revision the cohort
-			// says exists inside it. A read pinned strictly BELOW the claim keeps working: it
-			// legitimately asks for an older view, which is being served correctly.
-			// No read dependency is recorded: the throw means nothing was read.
-			// NOTE: accepted tradeoff — this converts a silent wrong answer into a loud failure. A
-			// node partitioned from every coordinator able to confirm currency used to read (stale)
-			// data indefinitely without any signal; it now raises BlockPossiblyStaleError on the
-			// reads that should contain the claim, until the partition heals or the claim is
-			// settled. Deliberate: the
-			// silent alternative is a collection view that forks and freezes with no report
-			// (ticket coordinator-serves-stale-data-as-if-confirmed). Revisit only if a
-			// degraded-read mode (serve-with-warning) becomes a product requirement.
-			if (unconfirmedAheadRev !== undefined
-				&& (this.actionContext === undefined || this.actionContext.rev >= unconfirmedAheadRev)) {
-				throw new BlockPossiblyStaleError(id, unconfirmedAheadRev);
-			}
+			// A throw here records no read dependency: it means nothing was read.
+			const block = answeredBlock(id, entry, this.actionContext);
 			// Record a read dependency only for a block that actually exists. A transactor may return a
 			// populated entry with `block: undefined` for a genuinely-missing block (TestTransactor does;
 			// the Network transactor always populates the key); recording there would add a phantom
@@ -87,15 +125,14 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 				// Record read dependency for optimistic concurrency control, carrying the caller's
 				// read purpose (default `value`) so a purely-structural navigation read can later be
 				// dropped from the conflict set (see ReadDependencyCollector / Theorem 5).
-				// Record the revision the content was MATERIALIZED at, not the newest the repo holds —
-				// see {@link GetBlockResult.materialized} for why `state.latest` is the wrong number
-				// and why the fallback preserves today's behaviour for repos that omit the field.
+				// Record the revision the content was MATERIALIZED at, not the newest the repo holds.
 				// Both sinks must take the SAME value: CacheSource learns it via getReadRevision on a
 				// miss-load and re-emits it on every later hit, so a split would stamp the cache
 				// differently from the collector.
-				const rev = materialized?.rev ?? state.latest?.rev ?? 0;
+				const rev = servedRevision(entry);
 				this.collector.record(id, rev, purpose);
 				this.readRevisions.set(id, rev);
+				this.served.set(block, { rev, mayRetain: this.mayRetain(id, rev) });
 			}
 			// TODO: if the state reports that there is a pending action, record this so that we are sure to update before syncing
 			//state.pendings
@@ -110,6 +147,46 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 		return this.readRevisions.get(id);
 	}
 
+	/** What this source knows about `block`, an object it returned from {@link tryGet}: the revision
+	 *  its content is, and whether a cache may keep it. `undefined` for any other object. CacheSource
+	 *  asks this on a miss-load, in preference to the by-id {@link getReadRevision}. */
+	describeServed(block: IBlock): ServedBlock | undefined {
+		return this.served.get(block);
+	}
+
+	/** Whether a cache may keep the block just served for `id` and serve it again without re-asking:
+	 * `false` exactly for a below-floor answer — content older than a log entry the collection has
+	 * already walked says the block is (see {@link BlockFloorCheck}). The block is handed to the
+	 * reader either way.
+	 *
+	 * NOTE: accepted tradeoff — a below-floor answer is RETURNED (uncached, and reported through the
+	 * floors as `collection:block-below-floor`), not refused with BlockPossiblyStaleError. A log entry
+	 * is not proof its blocks landed: a refused write can leave its entry in the log while the blocks
+	 * it names never take that revision on any machine
+	 * (tickets/backlog/bug-a-refused-write-can-leave-its-log-entry-behind). For such an entry the
+	 * below-floor content is the CORRECT content and no machine can ever meet the floor, so a throw
+	 * would make the block unreadable through every handle that refreshed past the entry — until the
+	 * block is next written, which cannot happen through a handle that cannot read it. A throw would
+	 * also land inside `Collection.updateInternal`'s replay and leave the tracker half re-staged.
+	 * Returning uncached instead restores the bound the storage layer already documents
+	 * (docs/transactions.md § Lazy read-repair window): the next read re-asks, so a lagging replica is
+	 * seen through within one read-repair window rather than never. Revisit if log entries ever become
+	 * proof that their blocks landed (abandoned entries made distinguishable): then an answer still
+	 * below its floor after every machine was asked should throw.
+	 *
+	 * NOTE: while a floor is unmet, every read of that block costs a transactor request instead of a
+	 * memory hit — and, since the floor now rides out on the request (`BlockGets.floors`), that
+	 * request costs a SECOND coordinator round too, because `NetworkTransactor.get` re-asks a
+	 * different machine for a below-floor answer. Both last at most one read-repair window for a
+	 * lagging replica, but until the block is next written (or the handle reopened) for an abandoned
+	 * entry, whose floor no machine can ever meet. Unmeasured. If it ever shows up, drop a floor
+	 * after some number of consecutive below-floor answers from a coordinator other than this node,
+	 * which retires the extra round with it (floors are otherwise never dropped — see
+	 * `BlockFloors`). */
+	private mayRetain(id: BlockId, servedRev: number): boolean {
+		return !this.floors?.answeredBelowFloor(id, this.actionContext, servedRev);
+	}
+
 	getReadDependencies(): ReadDependency[] {
 		return this.collector.getReadDependencies();
 	}
@@ -143,10 +220,22 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 	 * computed by the caller from the same tracker that produced `transform`. Omitted from the commit request when
 	 * undefined, so a caller that declares nothing produces exactly the request shape as before — the field rides
 	 * inside every cohort signature's hash preimage, so keeping the shape clean keeps those preimages clean.
-	 * @returns A promise that resolves to undefined if the action is successful, or a StaleFailure if the action is stale.
+	 * @param baseRevs - Optional per-block base revisions for the pend (see {@link PendRequest.baseRevs}): the
+	 * committed revision each update-only block's operations were computed against, from the same tracker
+	 * (`Tracker.stagedBaseRevs`). Omitted from the pend request when empty, for the same preimage reason.
+	 * @returns The transactor's own verdict, unflattened: a {@link CommitSuccess} carrying the
+	 * {@link WriteDurability} of the committed revision, or a {@link StaleFailure} if the pend or the commit
+	 * was refused. Success is deliberately NOT collapsed to `undefined` — the durability is the only thing
+	 * that tells a write every machine holds from one only this machine holds, and a caller that wants the
+	 * old boolean reads `result.success`. Test "is this completely saved" through `isFullyDurable`, never
+	 * by comparing `quorum` (see {@link WriteDurability}).
 	 */
-	async transact(transform: Transforms, actionId: ActionId, rev: number, headerId: BlockId, tailId: BlockId, priority = 0, blockDigests?: BlockContentDigests): Promise<undefined | StaleFailure> {
-		const pendResult = await this.transactor.pend({ transforms: transform, actionId, rev, policy: 'r', ...(priority > 0 ? { priority } : {}) });
+	async transact(transform: Transforms, actionId: ActionId, rev: number, headerId: BlockId, tailId: BlockId, priority = 0, blockDigests?: BlockContentDigests, baseRevs?: BlockBaseRevs): Promise<CommitResult> {
+		const pendResult = await this.transactor.pend({
+			transforms: transform, actionId, rev, policy: 'r',
+			...(priority > 0 ? { priority } : {}),
+			...baseRevsField(baseRevs)
+		});
 		if (!pendResult.success) {
 			return pendResult;
 		}
@@ -166,8 +255,8 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 				// rebase — letting the cancel's own failure throw over it would turn a routine,
 				// recoverable race into a hard failure. So the cancel fault is logged, not raised.
 				await this.dischargePend(actionId, pendResult.blockIds);
-				return commitResult;
 			}
+			return commitResult;
 		} catch (e) {
 			// `e` is the real cause — a transport fault, the thing the caller needs to see. A cancel
 			// that also fails must not silently take its place, but it must not be lost either: the

package/src/transactor/transactor.ts

@@ -1,4 +1,4 @@
-import type { GetBlockResults, ActionBlocks, BlockActionStatus, PendResult, CommitResult, PendRequest, CommitRequest, BlockGets, BlockId } from "../index.js";
+import type { GetBlockResults, ActionBlocks, ActionLineage, BlockActionStatus, PendResult, CommitResult, PendRequest, CommitRequest, BlockGets, BlockId } from "../index.js";
 import type { PeerId } from "../network/types.js";
 
 export type ClusterNomineesResult = {
@@ -46,4 +46,16 @@ export type ITransactor = {
 		- Used to build the supercluster for multi-collection transaction consensus
 	 */
 	queryClusterNominees?(blockId: BlockId): Promise<ClusterNomineesResult>;
+
+	/** Whether a COMMITTED action is part of what each named block holds now — the question a
+		writer asks when its own write was superseded before it could confirm it (see `BlockLineage`).
+		- `getStatus` cannot answer this: it judges a block by who holds its LATEST revision, so a
+		  write that landed and was then built upon reads there as not committed.
+		- `contains` is an acknowledgement and meets the same bar as a commit's: a strict majority of
+		  the block's cohort holds content built from the action.
+		- Read-only. It promotes nothing, so asking can never be what makes a write land.
+		- Optional: a transactor (or a wrapper around one) that does not offer it leaves the writer
+		  unable to establish the outcome, which it reports as such rather than guessing either way.
+	 */
+	getLineage?(ref: ActionBlocks & { rev: number }): Promise<ActionLineage>;
 }

package/src/transform/atomic.ts

@@ -1,22 +1,25 @@
-import { Tracker } from "./tracker.js";
-import type { IBlock, BlockStore } from "../index.js";
-import { applyTransformToStore } from "./helpers.js";
-
-export class Atomic<TBlock extends IBlock> extends Tracker<TBlock> {
-	constructor(public readonly store: BlockStore<TBlock>) {
-		super(store);
-	}
-
-	commit() {
-		// Hand the bases pinned inside this atomic to the parent tracker BEFORE reset() wipes this
-		// store — without this, a single act() carrying more actions than the read cache holds loses
-		// digest coverage, because by the flush below the cache has already evicted the early bases.
-		// The parent gets a COPY (adopt), not this store itself: sharing the store would let the
-		// reset() below wipe the parent's pins a line before flushing into it.
-		if (this.store instanceof Tracker) this.store.pins.adopt(this.pins);
-		const transform = this.reset();
-		applyTransformToStore(transform, this.store);
-	}
-
-	// rollback = reset
-}
+import { Tracker } from "./tracker.js";
+import type { IBlock, BlockStore } from "../index.js";
+import { applyTransformToStore } from "./helpers.js";
+
+export class Atomic<TBlock extends IBlock> extends Tracker<TBlock> {
+	constructor(public readonly store: BlockStore<TBlock>) {
+		super(store);
+	}
+
+	commit() {
+		// A parent tracker takes the staged transform AND the bases pinned inside this atomic
+		// (Tracker.absorb): without the pins, a single act() carrying more actions than the read
+		// cache holds would lose digest coverage, the cache having evicted the early bases by the
+		// flush; and without absorb keeping them as the bases of the flushed operations, a base the
+		// cache moved on from between the pin and the flush would be re-pinned at the newer revision.
+		// Any other store just receives the transform.
+		if (this.store instanceof Tracker) {
+			this.store.absorb(this);
+		} else {
+			applyTransformToStore(this.reset(), this.store);
+		}
+	}
+
+	// rollback = reset
+}

package/src/transform/base-pins.ts

@@ -1,15 +1,27 @@
 import type { BlockId, IBlock } from "../index.js";
 
-/** The committed base of one block, captured at the moment an update for it was staged. */
+/** The committed base of one block, fixed at the moment the FIRST update for it was staged in a
+ * tracker. `rev` is the number the staged operations were computed against, and it never changes
+ * while those operations remain staged: a later change to what the source holds for the id marks
+ * the pin {@link moved} rather than replacing it (see {@link Tracker.revalidatePin}). */
 export type PinnedBase = {
-	/** Cloned base content. Callers MUST clone again before applying a transform — applyTransform
-	 *  mutates, and the same pin is re-used by every retry attempt's digest pass. */
-	block: IBlock;
-	/** Committed revision of that base (CacheSource.getCachedRevision at pin time). */
+	/** Cloned base content. Absent for a REV-ONLY pin: the block was evicted from the read cache
+	 *  between the read that computed the update and the update itself, so the revision is known
+	 *  (the cache's per-id revision outlives the block) but the content is not — the base can be
+	 *  declared, its digest cannot. Filled in if the same revision is later re-read.
+	 *  Callers MUST clone before applying a transform — applyTransform mutates, and the same pin is
+	 *  re-used by every retry attempt's digest pass. */
+	block?: IBlock;
+	/** Committed revision of the base (CacheSource.getCachedRevision at pin time). */
 	rev: number;
-	/** Source drift generation at pin time (CacheSource.getGeneration). A pin whose generation no
-	 *  longer matches the source's is STALE and must not be used. */
+	/** Source drift generation at the last validation (CacheSource.getGeneration). A generation
+	 *  that no longer matches the source's means the source's content for the id changed hands
+	 *  since; whether the BASE moved is decided by comparing revisions, not generations. */
 	gen: number;
+	/** The source no longer describes this id at `rev`: the staged operations were computed on
+	 *  content that is not the content any commit would now apply them to. Never repaired in
+	 *  place — only a re-stage (which resets the owning tracker) clears it. */
+	moved?: true;
 };
 
 /** Per-transaction map of block id -> {@link PinnedBase}. Owned by a {@link Tracker}, shared by
@@ -17,10 +29,11 @@ export type PinnedBase = {
  * per-attempt snapshot tracker), so a base pinned when an update was staged is still available
  * when the digest pass runs — regardless of whether the read cache has since evicted it.
  *
- * NOTE: memory shape — one cloned base block per update-carrying block, held from the first
- * update staged for it until the owning tracker's next reset(). Peak retention is proportional
- * to the transaction's own write footprint (the same set of blocks whose ids and ops the commit
- * request already carries), and every transaction boundary reclaims it via reset(). */
+ * NOTE: memory shape — one cloned base block per update-carrying block (one number per block for
+ * a rev-only pin), held from the first update staged for it until the owning tracker's next
+ * reset(). Peak retention is proportional to the transaction's own write footprint (the same set
+ * of blocks whose ids and ops the commit request already carries), and every transaction boundary
+ * reclaims it via reset(). */
 export class BasePins {
 	private pins = new Map<BlockId, PinnedBase>();
 	/** The base source every `rev`/`gen` in here was read from — see {@link bindAuthority}. */
@@ -46,6 +59,10 @@ export class BasePins {
 		return this.pins.get(id);
 	}
 
+	ids(): IterableIterator<BlockId> {
+		return this.pins.keys();
+	}
+
 	set(id: BlockId, pin: PinnedBase): void {
 		this.pins.set(id, pin);
 	}
@@ -54,9 +71,16 @@ export class BasePins {
 		this.pins.delete(id);
 	}
 
+	/** Record that the base under `id`'s staged operations has moved (see {@link PinnedBase.moved}).
+	 * No-op for an unpinned id: with no pin there is no base to have moved from. */
+	markMoved(id: BlockId): void {
+		const pin = this.pins.get(id);
+		if (pin) pin.moved = true;
+	}
+
 	/** Drop every pin whose id is not in `keep`. Called from Tracker.reset with the ids still
-	 * carried by the new transforms' `updates`, so a rollback keeps its pins and a plain reset
-	 * clears them. */
+	 * carried by the new transforms' `updates`, so a rollback keeps its pins — moved marks
+	 * included, the operations being the same operations — and a plain reset clears them. */
 	retainOnly(keep: Iterable<BlockId>): void {
 		const keepSet = new Set(keep);
 		for (const id of this.pins.keys()) {
@@ -64,17 +88,51 @@ export class BasePins {
 		}
 	}
 
-	/** Copy every entry of `other` in, overwriting. Called from Atomic.commit so pins captured
-	 * inside the atomic survive into the parent tracker's store. Overwriting is deliberate: the
-	 * atomic's pin is the later observation of the same base chain, and the use-time freshness
-	 * check re-validates it anyway. */
+	/** Fold every entry of `other` in. Called from Tracker.absorb (Atomic.commit) so pins captured
+	 * inside the atomic survive into the parent tracker's store.
+	 *
+	 * An id the parent does not pin takes the atomic's pin. An id it pins at the SAME revision takes
+	 * the atomic's too — the later observation of the same committed content — except that a clone
+	 * the parent holds is never traded for a rev-only pin (same revision, same content; the clone is
+	 * what makes the digest declarable). An id it pins at a DIFFERENT revision is a base that MOVED
+	 * between the two actions: the parent's operations were computed on one content and the
+	 * atomic's on another, and the combined list has no single base. The parent's pin is kept (its
+	 * revision is what the earlier operations were built on) and marked moved, and a mark on either
+	 * side survives the fold. */
 	adopt(other: BasePins): void {
 		if (other.authority !== this.authority) {
 			throw new Error('BasePins.adopt across different base sources: pin revisions and generations are not comparable across them.');
 		}
 		for (const [id, pin] of other.pins) {
-			this.pins.set(id, pin);
+			const existing = this.pins.get(id);
+			if (existing === undefined || (existing.rev === pin.rev && !existing.moved)) {
+				this.pins.set(id, pin.block === undefined && existing?.block !== undefined ? { ...pin, block: existing.block } : pin);
+			} else {
+				existing.moved = true;
+			}
+		}
+	}
+
+	/** A copy for a staged-state snapshot (Collection.snapshotPending): the same entries, bound to
+	 * the same source, in a store of its own. Entries are shared, not cloned — a pin's content is
+	 * never mutated in place (every consumer clones before applying), and a moved mark set on a
+	 * shared entry after the copy is a fact about the same operations. */
+	copy(): BasePins {
+		const copy = new BasePins();
+		if (this.bound) copy.bindAuthority(this.authority);
+		for (const [id, pin] of this.pins) copy.pins.set(id, pin);
+		return copy;
+	}
+
+	/** Make this store hold exactly `other`'s entries — the restore half of {@link copy}
+	 * (Collection.restorePending), applied in place because the live tracker's store is shared by
+	 * reference with every per-attempt tracker of the transaction. */
+	replaceWith(other: BasePins): void {
+		if (other.bound && other.authority !== this.authority) {
+			throw new Error('BasePins.replaceWith across different base sources: pin revisions and generations are not comparable across them.');
 		}
+		this.pins.clear();
+		for (const [id, pin] of other.pins) this.pins.set(id, pin);
 	}
 
 	get size(): number {