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

package/src/transactor/network-transactor.ts

@@ -2,16 +2,18 @@ import { peerIdFromString } from "../network/types.js";
 import type { PeerId } from "../network/types.js";
 import { highestStaleAt, isConflictFailure } from "../network/stale-failure.js";
 import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struct.js";
-import type { ActionTransforms, ActionBlocks, BlockActionStatus, ITransactor, PendSuccess, StaleFailure, IKeyNetwork, BlockId, GetBlockResults, PendResult, CommitResult, PendRequest, IRepo, BlockGets, Transforms, CommitRequest, ActionId, RepoCommitRequest, ClusterNomineesResult, CollectionId, IBlock, CoordinatorIntent, BlockUnavailableReason, BlockContentDigests } from "../index.js";
+import { mergeDurability, withTornBlocks } from "../network/durability.js";
+import { judgeCohortLineage, type CohortLineage, type MemberLineage } from "../network/lineage.js";
+import type { ActionTransforms, ActionBlocks, ActionLineage, BlockActionStatus, ITransactor, PendSuccess, CommitSuccess, StaleFailure, IKeyNetwork, BlockId, GetBlockResults, PendResult, CommitResult, PendRequest, IRepo, BlockGets, Transforms, CommitRequest, ActionId, RepoCommitRequest, ClusterNomineesResult, CollectionId, IBlock, GetBlockResult, CoordinatorIntent, BlockUnavailableReason, BlockContentDigests, BlockBaseRevs, WriteDurability } from "../index.js";
 import type { IBlockChangeNotifier, CollectionChangeListener } from "./change-notifier.js";
 import { transformForBlockId, concatTransforms, concatTransform, transformsFromTransform, blockIdsForTransforms } from "../transform/helpers.js";
 import { Tracker } from "../transform/tracker.js";
-import { blockDigestsField } from "../transform/digest.js";
+import { blockDigestsField, baseRevsField } from "../transform/digest.js";
 import { CacheSource } from "../transform/cache-source.js";
-import { TransactorSource } from "./transactor-source.js";
+import { TransactorSource, servedRevision } from "./transactor-source.js";
 import { Log } from "../log/log.js";
 import { groupBy } from "../utility/groupby.js";
-import { blockIdToBytes } from "../utility/block-id-to-bytes.js";
+import { routingKeyForBlock } from "../network/routing-key.js";
 import { isRecordEmpty } from "../utility/is-record-empty.js";
 import { type CoordinatorBatch, makeBatchesByPeer, incompleteBatches, everyBatch, allBatches, mergeBlocks, processBatches, createBatchesForPayload } from "../utility/batch-coordinator.js";
 import { abortableDelay, jitteredBackoffMs } from "../utility/backoff.js";
@@ -41,6 +43,17 @@ type NetworkTransactorInit = {
 	 * absent, `onCollectionChange` is a logged no-op.
 	 */
 	localChangeNotifier?: IBlockChangeNotifier;
+	/**
+	 * The peer id of the node this transactor runs on, when `getRepo` hands that id the node's own
+	 * co-located repo rather than a network client — the same "co-located node" idea as
+	 * `localChangeNotifier`. It only breaks ties when a pend's blocks are grouped onto coordinators:
+	 * among cohort members covering equally many blocks, this node wins, so a write it is responsible
+	 * for is coordinated without a network hop. It never wins over a member covering more blocks
+	 * (fewer batches come first), and it never makes this node a coordinator for a block whose cohort
+	 * does not include it. Omit when nothing is co-located; ties then go to the member seen first,
+	 * which is the nearest.
+	 */
+	localPeerId?: PeerId;
 }
 
 /**
@@ -59,6 +72,8 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 	private readonly dialTimeoutMs: number | undefined;
 	private readonly getRepo: (peerId: PeerId) => IRepo;
 	private readonly localChangeNotifier: IBlockChangeNotifier | undefined;
+	/** `NetworkTransactorInit.localPeerId` as a string, the form cohort peer ids arrive in. */
+	private readonly localPeerId: string | undefined;
 
 	/**
 	 * Per-transaction coordinator cache: `actionId → (blockId → resolved coordinator)`.
@@ -93,6 +108,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 			: (init.dialTimeoutMs > 0 ? init.dialTimeoutMs : undefined);
 		this.getRepo = init.getRepo;
 		this.localChangeNotifier = init.localChangeNotifier;
+		this.localPeerId = init.localPeerId?.toString();
 	}
 
 	/**
@@ -137,7 +153,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 				batch => batch.payload,
 				(gets, blockId, mergeWithGets) => [...(mergeWithGets ?? []), ...gets.filter(bid => bid === blockId)],
 				expiration,
-				async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), { ...options, intent: 'read' })
+				(blockId, options) => this.keyNetwork.findCoordinator(routingKeyForBlock(blockId), { ...options, intent: 'read' })
 			);
 		} catch (e) {
 			error = e as Error;
@@ -152,30 +168,53 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		// present and unflagged) — retrying it doubles the round-trips on the common
 		// createOrOpen "does this block exist?" probe. Cross-member reconciliation for a
 		// missing block has already happened one layer down: CoordinatorRepo.get detects
-		// `isMissing` and consults cluster peers before it responds — and when that
-		// consult FAILS, the entry now says so via `unavailable` instead of posing as an
-		// authoritative absent. So by the time an unflagged absent reaches here there is
-		// nothing left for a transactor-level retry to discover, while a flagged entry
-		// earns the retry against a different peer that an absent deliberately does not.
+		// `isMissing` and consults cluster peers on every such read before it responds —
+		// and when that consult FAILS, the entry now says so via `unavailable` instead of
+		// posing as an authoritative absent. So by the time an unflagged absent reaches
+		// here there is nothing left for a transactor-level retry to discover, while a
+		// flagged entry earns the retry against a different peer that an absent
+		// deliberately does not. (The coordinator never remembers an absence across reads:
+		// one that did served a just-committed block as never created — GitHub issue #20.)
 		// See tickets txn-perf-authoritative-notfound and repo-reports-unavailable-vs-absent.
 		const hasValidResponse = (b: CoordinatorBatch<BlockId[], GetBlockResults>) => {
 			return b.request?.isResponse === true && b.request.response != null;
 		};
 
+		// Content the CALLER can prove is too old, from the floor it carried on the request
+		// (see {@link BlockGets.floors}): the caller walked a log entry saying this block changed at
+		// that revision, so anything below it is not the view the read asked for, however current
+		// the answering repo honestly believes its copy to be. Only a block-carrying entry can be
+		// below a floor — an absent answer is judged by its own rules above, and treating one as
+		// below-floor would put the one-round `createOrOpen` probe back on the retry path.
+		// Reported here rather than left to the reader: `TransactorSource` reports
+		// `collection:block-below-floor` from the MERGED answer, so a read the retry below repaired
+		// is the one case that leaves no trace anywhere else — the extra round would show up in a
+		// field log as an unexplained second consult. Costs nothing on an unfloored read, which
+		// leaves on the first clause.
+		const belowFloor = (bid: BlockId, entry: GetBlockResult): boolean => {
+			const floor = blockGets.floors?.[bid];
+			if (floor === undefined || entry.block == null || servedRevision(entry) >= floor) return false;
+			log('get:below-floor blockId=%s served=%d floor=%d', bid, servedRevision(entry), floor);
+			return true;
+		};
+
 		// A batch is answered when its response carries an entry for EVERY requested
-		// block id and none of those entries carries a doubt marker. An entry present
-		// with only `state` (no `block`) is an authoritative "absent", which counts as
-		// answered — not a gap. An `unavailable` entry is the peer saying it could not
-		// find out whether the block EXISTS; an `unconfirmedAheadRev` entry is the peer
-		// saying it could not confirm the content it served is CURRENT (a cohort claim
-		// sits ahead of it, unsettled). Neither counts as answered, so both earn the
-		// second-chance retry against a different coordinator.
+		// block id and none of those entries carries a doubt marker or falls below the
+		// caller's floor. An entry present with only `state` (no `block`) is an
+		// authoritative "absent", which counts as answered — not a gap. An `unavailable`
+		// entry is the peer saying it could not find out whether the block EXISTS; an
+		// `unconfirmedAheadRev` entry is the peer saying it could not confirm the content
+		// it served is CURRENT (a cohort claim sits ahead of it, unsettled); a below-floor
+		// entry is the CALLER knowing the content is behind a revision it has already seen
+		// the log commit. None counts as answered, so each earns the second-chance retry
+		// against a different coordinator.
 		const isAuthoritative = (b: CoordinatorBatch<BlockId[], GetBlockResults>) => {
 			if (!hasValidResponse(b)) return false;
 			const resp = b.request!.response! as GetBlockResults;
 			return b.payload.every(bid => resp[bid] !== undefined
 				&& resp[bid]!.unavailable === undefined
-				&& resp[bid]!.unconfirmedAheadRev === undefined);
+				&& resp[bid]!.unconfirmedAheadRev === undefined
+				&& !belowFloor(bid, resp[bid]!));
 		};
 
 		// Retry only genuine no-response / partial-response batches. An authoritative
@@ -186,6 +225,13 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		// today — one extra bounded consult on an already failing read. If isolated-node
 		// read latency ever matters, skip the retry for that reason rather than widening
 		// isAuthoritative.
+		// This is ONE extra round, not a loop: a below-floor answer that every reachable
+		// coordinator repeats survives the merge below as the highest revision anyone
+		// served, UNFLAGGED. Deliberate — a log entry is not proof its blocks landed, so a
+		// floor no machine can meet may simply describe an abandoned write, in which case
+		// the below-floor content is the correct content and every machine agrees on it
+		// (see the accepted-tradeoff NOTE at `TransactorSource.mayRetain`). The reader
+		// judges it again and returns it uncached.
 		const retryable = Array.from(allBatches(batches)).filter(b =>
 			!isAuthoritative(b as any)
 		) as CoordinatorBatch<BlockId[], GetBlockResults>[];
@@ -202,7 +248,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 					b.payload,
 					(gets, blockId, mergeWithGets) => [...(mergeWithGets ?? []), ...gets.filter(id => id === blockId)],
 					Array.from(excluded),
-					async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), { ...options, intent: 'read' })
+					(blockId, options) => this.keyNetwork.findCoordinator(routingKeyForBlock(blockId), { ...options, intent: 'read' })
 				);
 				if (retries.length > 0) {
 					b.subsumedBy = [...(b.subsumedBy ?? []), ...retries];
@@ -212,7 +258,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 						batch => batch.payload,
 						(gets, blockId, mergeWithGets) => [...(mergeWithGets ?? []), ...gets.filter(id => id === blockId)],
 						expiration,
-						async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), { ...options, intent: 'read' })
+						(blockId, options) => this.keyNetwork.findCoordinator(routingKeyForBlock(blockId), { ...options, intent: 'read' })
 					);
 				}
 			}));
@@ -239,13 +285,20 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		// — and only strictly-greater rank replaces, so first-arrival (the stale one)
 		// would win the very merge the retry exists to fix. Non-object junk ranks below
 		// everything so any real entry replaces it.
-		// NOTE: `materialized` (the revision the content actually is) is not part of the ranking, so two peers answering the same
-		// pinned get with block-carrying entries at DIFFERENT materialized revisions resolve
-		// to whichever arrived first. Not a concern today — cohort peers share the block's
-		// revision log, so they agree on the highest committed rev at or below a pin — and the
-		// failure direction is safe (a lower recorded revision spuriously stale-rejects rather
-		// than wrongly accepting). If peers are ever seen to disagree here, break the tie on
-		// the HIGHEST `materialized.rev` among top-rank entries.
+		// Rank alone does not order two peers that both served content: a confirmed block ranks 6
+		// whatever revision it is. Cohort peers were expected to agree — they share the block's
+		// revision log, so they agree on the highest committed revision at or below a pin — but a
+		// peer inside its read-repair window answers from its own copy without consulting anyone,
+		// and two cohort members answered one pinned read at revisions 6 and 7. Since only a
+		// strictly greater rank replaces, first arrival (the stale one) would win the very merge a
+		// below-floor retry exists to fix. So equally-ranked entries that BOTH carry a block break
+		// the tie on the newer content, measured by `servedRevision` — the same number the floor is
+		// judged against and the same number the reader records as its read dependency, so the
+		// merge cannot prefer one revision while the reader believes it read another. The tie-break
+		// is deliberately inside a rank rather than across ranks: a confirmed older block still
+		// beats an unconfirmed newer one, because "the peer could not confirm this is current" is
+		// a statement about the ANSWER, not about the revision, and adopting the unconfirmed one
+		// would re-open the doubt the rank split exists to resolve.
 		// `unavailable` answers rank among THEMSELVES by how much they establish, so the merged
 		// entry never presents a weaker doubt than some peer actually returned. This matters
 		// because the reason travels out verbatim on `BlockUnavailableError` and callers act on
@@ -264,6 +317,33 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 			if (entry.unavailable !== undefined) return unavailableRank(entry.unavailable);
 			return entry.unconfirmedAheadRev === undefined ? 4 : 3;
 		};
+		const carriesBlock = (r: unknown): r is GetBlockResult =>
+			!!r && typeof r === 'object' && (r as GetBlockResult).block != null;
+		/** Whether `candidate` displaces the entry already held for the same block: a strictly
+		 *  better rank, or — at equal rank, both carrying content — strictly newer content.
+		 *
+		 *  NOTE: `servedRevision` falls back to `state.latest` for a producer that omits
+		 *  `materialized`, and on a PINNED read that fallback overstates — `state.latest` is the
+		 *  newest revision the repo holds, not the revision it served. Every in-tree producer
+		 *  populates `materialized` (`StorageRepo`, `TestTransactor`; `CoordinatorRepo` forwards it
+		 *  verbatim), so the fallback only reaches a third-party `IRepo`, and `belowFloor` above
+		 *  reads the same number, so the two stay consistent. If such a repo ever answers pinned
+		 *  reads beside one that does report `materialized`, it can win this tie with a number
+		 *  describing content it did not serve: cap the comparison at `blockGets.context.rev` then
+		 *  (a correct answer to a pinned read is never above the pin), in both places at once.
+		 *
+		 *  NOTE: `servedRevision` also reads `state`, which the type requires but a decoded wire
+		 *  response could still omit. Ranking never touched it, so an entry like that used to fault
+		 *  only the reader of ITS block; it now faults the whole `get`, siblings included. Left
+		 *  alone because the reader called `servedRevision` on such an entry anyway — this widens
+		 *  the blast radius, it does not create the fault. If a third-party `IRepo` ever makes it
+		 *  real, make `servedRevision` tolerate a missing `state` rather than guarding here. */
+		const beats = (candidate: unknown, held: unknown): boolean => {
+			const byRank = rankOf(candidate) - rankOf(held);
+			return byRank !== 0
+				? byRank > 0
+				: carriesBlock(candidate) && carriesBlock(held) && servedRevision(candidate) > servedRevision(held);
+		};
 
 		// Create a lookup map from successful responses only
 		const resultEntries = new Map<string, any>();
@@ -271,7 +351,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 			const resp = batch.request!.response! as any;
 			for (const [bid, res] of Object.entries(resp)) {
 				const existing = resultEntries.get(bid);
-				if (!existing || rankOf(res) > rankOf(existing)) {
+				if (!existing || beats(res, existing)) {
 					resultEntries.set(bid, res);
 				}
 			}
@@ -420,6 +500,57 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		}
 	}
 
+	/**
+	 * See {@link ITransactor.getLineage}. Asks EVERY member of each block's cohort, directly, and
+	 * folds their answers with {@link judgeCohortLineage} — not the coordinator round {@link get}
+	 * runs, because no single member can answer for the cohort: a member that took a later revision
+	 * as a replica cannot say what it was built from, while the member it came from can.
+	 *
+	 * The per-member `get` carries no context, so it pins nothing and promotes nothing; asking is
+	 * never what makes a write land.
+	 *
+	 * NOTE: one request per cohort member per block. Reached only when a writer's own half-landed
+	 * write was refused as superseded, which is rare, so the fan-out is not batched by member. If a
+	 * write path ever calls this routinely, group the blocks a member is in the cohort of into one
+	 * request per member.
+	 */
+	async getLineage(ref: ActionBlocks & { rev: number }): Promise<ActionLineage> {
+		const target = { actionId: ref.actionId, rev: ref.rev };
+		const expiration = Date.now() + this.timeoutMs;
+		const answers = await Promise.all(ref.blockIds.map(blockId => this.cohortLineage(blockId, target, expiration)));
+		const durabilities = answers.flatMap(answer => answer.durability === undefined ? [] : [answer.durability]);
+		const saved = answers.length > 0 && durabilities.length === answers.length;
+		log('getLineage actionId=%s rev=%d blocks=%o', ref.actionId, ref.rev, answers.map(answer => answer.lineage));
+		return {
+			blocks: answers.map(answer => answer.lineage),
+			...(saved ? { durability: mergeDurability(durabilities) } : {})
+		};
+	}
+
+	/** One block's cohort answer: every member asked in parallel, a member that cannot be reached
+	 *  (or whose cohort cannot be resolved at all) counted as `unknown` rather than left out. */
+	private async cohortLineage(blockId: BlockId, target: { actionId: ActionId; rev: number }, expiration: number): Promise<CohortLineage> {
+		let cohort: string[];
+		try {
+			cohort = Object.keys(await this.keyNetwork.findCluster(routingKeyForBlock(blockId)));
+		} catch (err) {
+			log('getLineage:cohort-unresolved blockId=%s error=%s', blockId, errorMessage(err));
+			return { lineage: 'unknown' };
+		}
+		const members = await Promise.all(cohort.map(async (peerId): Promise<MemberLineage> => {
+			try {
+				const results = await this.getRepo(peerIdFromString(peerId)).get(
+					{ blockIds: [blockId], lineageOf: target }, { expiration, dialTimeoutMs: this.dialTimeoutMs });
+				const entry = results?.[blockId];
+				return { peerId, lineage: entry?.lineage ?? 'unknown', ...(entry?.state?.latest ? { latest: entry.state.latest } : {}) };
+			} catch (err) {
+				log('getLineage:member-silent blockId=%s peer=%s error=%s', blockId, peerId, errorMessage(err));
+				return { peerId, lineage: 'unknown' };
+			}
+		}));
+		return judgeCohortLineage(members);
+	}
+
 	private async consolidateCoordinators(
 		blockIds: BlockId[],
 		transforms: Transforms,
@@ -436,7 +567,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 
 		await Promise.all(blockIds.map(async bid => {
 			try {
-				const clusterPeers = await this.keyNetwork.findCluster(await blockIdToBytes(bid));
+				const clusterPeers = await this.keyNetwork.findCluster(routingKeyForBlock(bid));
 				blockClusterPeerIds.set(bid, new Set(Object.keys(clusterPeers)));
 			} catch {
 				fallbackBlocks.push(bid);
@@ -458,22 +589,10 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		const assignments = new Map<string, BlockId[]>(); // peerIdStr → assigned blockIds
 
 		while (uncovered.size > 0) {
-			let bestPeer: string | undefined;
-			let bestCount = 0;
-
-			for (const [peerId, blocks] of peerBlocks) {
-				const coverCount = blocks.filter(bid => uncovered.has(bid)).length;
-				if (coverCount > bestCount) {
-					bestCount = coverCount;
-					bestPeer = peerId;
-				}
-			}
-
-			if (!bestPeer || bestCount === 0) break;
-
-			const covered = peerBlocks.get(bestPeer)!.filter(bid => uncovered.has(bid));
-			assignments.set(bestPeer, covered);
-			for (const bid of covered) uncovered.delete(bid);
+			const best = bestCoveringPeer(peerBlocks, uncovered, this.localPeerId);
+			if (!best) break;
+			assignments.set(best.peerId, best.covered);
+			for (const bid of best.covered) uncovered.delete(bid);
 		}
 
 		// Step 4: Any remaining uncovered blocks fall back to findCoordinator
@@ -482,7 +601,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		const fallbackCoordinators = await Promise.all(
 			fallbackBlocks.map(async bid => ({
 				blockId: bid,
-				coordinator: await this.keyNetwork.findCoordinator(await blockIdToBytes(bid), { excludedPeers: [] })
+				coordinator: await this.keyNetwork.findCoordinator(routingKeyForBlock(bid), { excludedPeers: [] })
 			}))
 		);
 		for (const { blockId, coordinator } of fallbackCoordinators) {
@@ -544,7 +663,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 			await processBatches(
 				batches,
 				(batch) => this.getRepo(batch.peerId).pend(
-					{ ...blockAction, transforms: batch.payload },
+					pendRequestForBatch(blockAction, batch.payload),
 					{
 						expiration,
 						dialTimeoutMs: this.dialTimeoutMs,
@@ -554,12 +673,12 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 				batch => blockIdsForTransforms(batch.payload),
 				transformForBlock,
 				expiration,
-				async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options)
+				(blockId, options) => this.keyNetwork.findCoordinator(routingKeyForBlock(blockId), options)
 			);
 			// Cache resolved coordinators for follow-up commit to hit the same peers
 			try {
 				for (const b of Array.from(allBatches(batches))) {
-					this.keyNetwork.recordCoordinator?.(await blockIdToBytes(b.blockId), b.peerId);
+					this.keyNetwork.recordCoordinator?.(routingKeyForBlock(b.blockId), b.peerId);
 				}
 			} catch (e) { log('WARN: Failed to record coordinator hint %o', e); }
 		} catch (e) {
@@ -662,7 +781,15 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		return {
 			success: true,
 			pending: completed.flatMap(b => (b.request!.response! as PendSuccess).pending),
-			blockIds: blockIdsForTransforms(blockAction.transforms)
+			blockIds: blockIdsForTransforms(blockAction.transforms),
+			// The weakest coordinator's answer is the action's answer (`mergeDurability`). A pend has
+			// no torn case: a batch that did not succeed fails the whole pend above.
+			// NOTE: a pend naming NO blocks now throws here (`mergeDurability` refuses an empty input rather
+			// than fabricate a class), where it used to answer success. No caller produces one today —
+			// `Collection.sync` skips an empty change set, and the multi-collection coordinator pends only
+			// collections that appended a log entry. If one ever appears, decide what an empty write's
+			// durability means at that caller; do not make the merge invent one.
+			durability: mergeDurability(completed.map(b => (b.request!.response! as PendSuccess).durability))
 		};
 	}
 
@@ -683,8 +810,8 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 	}
 
 	async queryClusterNominees(blockId: BlockId): Promise<ClusterNomineesResult> {
-		const blockIdBytes = await blockIdToBytes(blockId);
-		const clusterPeers = await this.keyNetwork.findCluster(blockIdBytes);
+		const routingKey = routingKeyForBlock(blockId);
+		const clusterPeers = await this.keyNetwork.findCluster(routingKey);
 		const nominees = Object.keys(clusterPeers).map(idStr => peerIdFromString(idStr));
 		return { nominees };
 	}
@@ -704,8 +831,25 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		// Commit the tail block
 		const tailResult = await this.commitBlock(request.tailId, request.actionId, request.rev, request.tailId, request.blockDigests);
 		if (!tailResult.success) {
+			// NOTE: a refused tail is NOT an absent tail. The coordinator's durability gate answers
+			// `commit-not-durable` whenever fewer than a majority hold the revision — even though
+			// some members stored it — and this return means the sweep below never runs, so every
+			// other block of the action is left uncommitted while the log entry may already be
+			// readable. This layer cannot tell "tail absent" from "tail present on a minority", so it
+			// does not sweep anyway (that would commit data blocks under a tail that may never reach
+			// a majority). The writer closes the gap instead: its retry keeps the SAME action id,
+			// and if its refresh finds this action's own log entry it re-sends this attempt — same
+			// transforms, same revision — to land what was left behind before treating the write as
+			// saved (`Collection.completeOwnEntry`). A write is saved only when every block its log
+			// entry names holds its revision; the entry alone proves nothing but the tail.
 			return tailResult;
 		}
+		// Every coordinator that confirmed part of this action reports who holds its part; the
+		// action-level answer is the WEAKEST of them (`mergeDurability`), so a caller reading only the
+		// scalar fields reads the binding constraint. The blocks a torn sweep abandons are on nobody,
+		// and `torn` names them: they never heal by replication, only by re-driving the action.
+		const cohortReports: WriteDurability[] = [tailResult.durability];
+		let torn: BlockId[] = [];
 
 		// Sweep every non-tail block (the header, when the action touches it, lands here too — after
 		// the tail, like any other touched block). The tail is the only exclusion needed.
@@ -719,6 +863,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		const remainingBlocks = request.blockIds.filter(bid => bid !== request.tailId);
 		if (remainingBlocks.length > 0) {
 			const { batches, error } = await this.commitBlocks({ blockIds: remainingBlocks, actionId: request.actionId, rev: request.rev, tailId: request.tailId, blockDigests: request.blockDigests });
+			cohortReports.push(...confirmedDurabilities(batches));
 			if (error) {
 				// Split by the failure's NATURE, exactly as commitBlock does for the tail: a RETURNED
 				// `success:false` from a cohort coordinator is a confirmed optimistic-concurrency loss
@@ -742,28 +887,33 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 				//     latest.actionId === request.actionId` (StorageRepo.pend, which also skips saving
 				//     a pending record for such a block; ClusterMember.validatePendOperations; and
 				//     CoordinatorRepo's stale classification). The retry no longer wedges.
-				//   - its retry consumes its own already-committed log entry instead of replaying it
-				//     (Collection.updateInternal's `inFlightActionId` arm, threaded by syncInternal,
-				//     which reuses one actionId across all of a sync's attempts). It no longer appends
-				//     a duplicate entry.
-				// NOTE: that second half covers the single-collection path only. The multi-collection
-				// path (TransactionCoordinator's retry loop) still refreshes without telling the
-				// collection which of its own actions is in flight, so a torn multi-collection commit
-				// can still record its entry twice — tracked as
-				// tickets/fix/refresh-must-always-know-its-own-in-flight-action, and to be fixed there
-				// rather than by tolerating the failure here.
+				//   - its retry recognises its own already-committed log entry instead of replaying it
+				//     (Collection.updateInternal's `inFlightActionId` arm, set by both write paths —
+				//     syncInternal and TransactionCoordinator.commitOnce — which reuse one action id
+				//     across all of a write's attempts). It no longer appends a duplicate entry.
+				//   - and before consuming that entry it FINISHES the action: the blocks this return
+				//     abandons are on nobody (the caller cancels their pending records next), so the
+				//     refresh re-sends the refused attempt verbatim at the same revision, which the
+				//     carve-outs above turn into "land exactly what is missing"
+				//     (Collection.completeOwnEntry). The entry alone never counts as saved. If a rival
+				//     has since taken a revision one of those blocks needed, the writer is told so by
+				//     name (TornActionError) rather than acknowledged.
 				//
 				// Transport-shaped failures (throws, no returned refusal) keep the tolerance for the
 				// RESULT — the tail committed durably, and reporting failure now would disown an
 				// acknowledged write — but NOT for the state the sweep abandoned, which
 				// `cancelAbandonedSweepBlocks` below repairs before this returns.
 				try { log('WARN: non-tail commit had errors; cancelling unconfirmed blocks, proceeding after tail commit: %s', error.message); } catch { /* ignore */ }
-				await this.cancelAbandonedSweepBlocks(request.actionId, remainingBlocks, batches);
+				torn = await this.cancelAbandonedSweepBlocks(request.actionId, remainingBlocks, batches);
 			}
 		}
 
-		log('commit:done actionId=%s ms=%d', request.actionId, Date.now() - t0);
-		return { success: true };
+		log('commit:done actionId=%s ms=%d torn=%d', request.actionId, Date.now() - t0, torn.length);
+		// `withTornBlocks` clamps the class below `full` when the sweep abandoned anything — a cohort
+		// can hold every block it was asked for while the action as a whole is incomplete — and never
+		// raises it. `isFullyDurable` then answers false; a consumer that needs to know WHICH blocks
+		// reads `torn`.
+		return { success: true, durability: withTornBlocks(mergeDurability(cohortReports), torn) };
 	}
 
 	/**
@@ -795,8 +945,11 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 	 * `debt-unpromotable-pending-records-need-a-sweep`); and this covers only the sweep's abandonment
 	 * — `StorageRepo.commit`'s genuine-fault arm deliberately KEEPS a failed batch's pendings for a
 	 * retry, so it is a second producer of the same durable state whenever that retry never comes.
+	 *
+	 * @returns the abandoned block ids — exactly the set cancelled here — so {@link commit} can name
+	 * them as `torn` on the acknowledgement without re-deriving the set by a second rule.
 	 */
-	private async cancelAbandonedSweepBlocks(actionId: ActionId, sweptBlocks: BlockId[], batches: CoordinatorBatch<BlockId[], CommitResult>[]): Promise<void> {
+	private async cancelAbandonedSweepBlocks(actionId: ActionId, sweptBlocks: BlockId[], batches: CoordinatorBatch<BlockId[], CommitResult>[]): Promise<BlockId[]> {
 		// NOTE: `confirmed` is only ever non-empty when the sweep spans MORE THAN ONE batch, and it
 		// does so only when no single peer covers every swept block — `consolidateCoordinators`'
 		// greedy set cover collapses the pend onto one coordinator otherwise, and commit reuses that
@@ -813,13 +966,14 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		}
 		const abandoned = sweptBlocks.filter(bid => !confirmed.has(bid));
 		if (abandoned.length === 0) {
-			return;
+			return abandoned;
 		}
 		try {
 			await this.cancel({ actionId, blockIds: abandoned });
 		} catch (cancelError) {
 			try { log('WARN: cancel of abandoned sweep blocks failed — pending records may wedge until the node-side sweep lands: %o', cancelError); } catch { /* ignore */ }
 		}
+		return abandoned;
 	}
 
 	private async commitBlock(blockId: BlockId, actionId: ActionId, rev: number, tailId?: BlockId, blockDigests?: BlockContentDigests): Promise<CommitResult> {
@@ -836,7 +990,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 			}
 			throw tailError;
 		}
-		return { success: true };
+		return { success: true, durability: mergeDurability(confirmedDurabilities(tailBatches)) };
 	}
 
 	/**
@@ -846,21 +1000,26 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 	 * both must distinguish a confirmed conflict (return it; the caller cancels and re-drives) from
 	 * a transient fault (throw / tolerate).
 	 *
-	 * NOTE: a reason-only StaleFailure (success:false, no `missing`) lands here too and returns
-	 * `{ missing: [], success:false }` — the `reason` PROSE is dropped rather than surfaced.
-	 * `staleAt` is carried, so the one machine-readable fact in that prose (which block is at which
-	 * revision) survives; only the free-form wording is lost. If the wording itself is ever needed,
-	 * gate this on non-empty missing rather than reinstating it unconditionally.
+	 * Rebuilt the same way {@link pend}'s aggregate is: `reason` is the first one any batch gave
+	 * (the only diagnostic that survives into the coordinator's error text — a refusal whose reason
+	 * is `commit-not-durable` must not read as "stale commit", a rival's win), `conflict` holds when
+	 * any batch was a classified conflict, and `staleAt` is the highest confirmed revision. A
+	 * reason-only StaleFailure (success:false, no `missing`) lands here too and comes out with
+	 * `missing: []` and its reason intact.
 	 */
 	private staleFromBatches(batches: CoordinatorBatch<BlockId[], CommitResult>[]): StaleFailure | undefined {
 		const stale = Array.from(allBatches(batches, b => b.request?.isResponse as boolean && !b.request!.response!.success));
 		if (stale.length === 0) {
 			return undefined;
 		}
-		const staleAt = highestStaleAt(stale.map(b => (b.request!.response! as StaleFailure).staleAt));
+		const responses = stale.map(b => b.request!.response! as StaleFailure);
+		const staleAt = highestStaleAt(responses.map(r => r.staleAt));
+		const reason = responses.map(r => r.reason).find(r => r !== undefined);
 		return {
-			missing: distinctBlockActionTransforms(stale.flatMap(b => (b.request!.response! as StaleFailure).missing).filter((x): x is ActionTransforms => x !== undefined)),
+			missing: distinctBlockActionTransforms(responses.flatMap(r => r.missing).filter((x): x is ActionTransforms => x !== undefined)),
 			...(staleAt === undefined ? {} : { staleAt }),
+			...(reason === undefined ? {} : { reason }),
+			conflict: responses.some(isConflictFailure),
 			success: false as const
 		};
 	}
@@ -949,7 +1108,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 				return cached;
 			}
 		}
-		return this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), { ...options, intent });
+		return this.keyNetwork.findCoordinator(routingKeyForBlock(blockId), { ...options, intent });
 	}
 
 	/**
@@ -1086,7 +1245,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 					batch => batch.payload,
 					mergeBlocks,
 					deadline,
-					async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options)
+					(blockId, options) => this.keyNetwork.findCoordinator(routingKeyForBlock(blockId), options)
 				);
 			} catch (e) {
 				lastError = asError(e);
@@ -1141,6 +1300,28 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 }
 
 
+/**
+ * One round of `consolidateCoordinators`' greedy cover: the cohort member covering the most still-uncovered
+ * blocks, with the blocks it covers, or undefined when no member covers any.
+ *
+ * A tie goes to `localPeerId` when it is among the tied members, otherwise to the member seen first. Cohorts
+ * arrive in proximity order, so "seen first" is the nearest; without the local preference a node that is in
+ * a block's cohort but not nearest would send its own write over the network, and on a network no wider than
+ * a cohort (every node in every cohort) that would be nearly every write.
+ */
+function bestCoveringPeer(peerBlocks: Map<string, BlockId[]>, uncovered: Set<BlockId>, localPeerId: string | undefined): { peerId: string; covered: BlockId[] } | undefined {
+	let best: { peerId: string; covered: BlockId[] } | undefined;
+	for (const [peerId, blocks] of peerBlocks) {
+		const covered = blocks.filter(bid => uncovered.has(bid));
+		if (covered.length === 0) continue;
+		const bestCount = best?.covered.length ?? 0;
+		if (covered.length > bestCount || (covered.length === bestCount && peerId === localPeerId)) {
+			best = { peerId, covered };
+		}
+	}
+	return best;
+}
+
 /**
  * The block ids some batch in the tree got an ANSWER for. A cancel batch that errored, or never
  * responded, discharged nothing — its blocks' pending records are still standing. Batch payloads
@@ -1155,18 +1336,50 @@ function dischargedBlocks(batches: CoordinatorBatch<BlockId[], void>[]): Set<Blo
 	return discharged;
 }
 
+/**
+ * The durability report off every commit batch in the tree that answered `success: true` — the
+ * coordinators' own answers for the blocks they drove, one per confirmed batch. Retry batches
+ * (`subsumedBy`) are included, so a block re-homed after a failed first attempt reports through the
+ * peer that actually committed it. Batches that threw or returned a refusal contribute nothing.
+ */
+function confirmedDurabilities(batches: CoordinatorBatch<BlockId[], CommitResult>[]): WriteDurability[] {
+	return Array.from(allBatches(batches, b => b.request?.isResponse === true && b.request!.response!.success))
+		.map(b => (b.request!.response! as CommitSuccess).durability);
+}
+
+/** The entries of `all` whose ids appear in `batchBlockIds` — the per-batch narrowing both
+ * per-block declarations share ({@link digestsFor}, {@link baseRevsFor}). */
+function subsetOf<T>(all: Record<BlockId, T>, batchBlockIds: BlockId[]): Record<BlockId, T> {
+	const subset: Record<BlockId, T> = {};
+	for (const id of batchBlockIds) {
+		const entry = all[id];
+		if (entry !== undefined) subset[id] = entry;
+	}
+	return subset;
+}
+
 /** The subset of `all` whose ids appear in `batchBlockIds`, wrapped (via {@link blockDigestsField})
  * so it spreads to nothing when the batch declares no digests. Called at SEND time, once per attempt,
  * because `processBatches` re-batches failed blocks onto different coordinators — a subset computed
  * up front would follow the wrong batch on retry. */
 function digestsFor(all: BlockContentDigests | undefined, batchBlockIds: BlockId[]): { blockDigests?: BlockContentDigests } {
-	if (!all) return {};
-	const subset: BlockContentDigests = {};
-	for (const id of batchBlockIds) {
-		const digest = all[id];
-		if (digest !== undefined) subset[id] = digest;
-	}
-	return blockDigestsField(subset);
+	return all ? blockDigestsField(subsetOf(all, batchBlockIds)) : {};
+}
+
+/** The pend-side sibling of {@link digestsFor}: the subset of `all` whose ids appear in
+ * `batchBlockIds`, wrapped (via {@link baseRevsField}) so it spreads to nothing when no block in the
+ * batch names a base. Same send-time rule, for the same reason. */
+function baseRevsFor(all: BlockBaseRevs | undefined, batchBlockIds: BlockId[]): { baseRevs?: BlockBaseRevs } {
+	return all ? baseRevsField(subsetOf(all, batchBlockIds)) : {};
+}
+
+/** `action` re-scoped to one coordinator batch: the batch's own transforms, and the bases for the
+ * blocks in it alone (see {@link PendRequest.baseRevs}). The action-wide `baseRevs` key is dropped
+ * BEFORE the subset is spread, so a batch none of whose blocks names a base carries no key at all
+ * rather than the whole action's map — and no cohort signs for a block it is not responsible for. */
+function pendRequestForBatch(action: PendRequest, payload: Transforms): PendRequest {
+	const { baseRevs, ...rest } = action;
+	return { ...rest, transforms: payload, ...baseRevsFor(baseRevs, blockIdsForTransforms(payload)) };
 }
 
 /**