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

package/dist/src/transactor/network-transactor.js

@@ -1,14 +1,16 @@
 import { peerIdFromString } from "../network/types.js";
 import { highestStaleAt, isConflictFailure } from "../network/stale-failure.js";
 import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struct.js";
+import { mergeDurability, withTornBlocks } from "../network/durability.js";
+import { judgeCohortLineage } from "../network/lineage.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 { makeBatchesByPeer, incompleteBatches, everyBatch, allBatches, mergeBlocks, processBatches, createBatchesForPayload } from "../utility/batch-coordinator.js";
 import { abortableDelay, jitteredBackoffMs } from "../utility/backoff.js";
@@ -29,6 +31,8 @@ export class NetworkTransactor {
     dialTimeoutMs;
     getRepo;
     localChangeNotifier;
+    /** `NetworkTransactorInit.localPeerId` as a string, the form cohort peer ids arrive in. */
+    localPeerId;
     /**
      * Per-transaction coordinator cache: `actionId → (blockId → resolved coordinator)`.
      * {@link pend} populates it from its final (retry-adjusted) batch assignment; commit
@@ -59,6 +63,7 @@ export class NetworkTransactor {
             : (init.dialTimeoutMs > 0 ? init.dialTimeoutMs : undefined);
         this.getRepo = init.getRepo;
         this.localChangeNotifier = init.localChangeNotifier;
+        this.localPeerId = init.localPeerId?.toString();
     }
     /**
      * Subscribe to commits landing on the local node for `collectionId`, delegating
@@ -85,7 +90,7 @@ export class NetworkTransactor {
         const expiration = Date.now() + this.timeoutMs;
         let error;
         try {
-            await processBatches(batches, (batch) => this.getRepo(batch.peerId).get({ blockIds: batch.payload, context: blockGets.context }, { expiration, dialTimeoutMs: this.dialTimeoutMs }), 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' }));
+            await processBatches(batches, (batch) => this.getRepo(batch.peerId).get({ blockIds: batch.payload, context: blockGets.context }, { expiration, dialTimeoutMs: this.dialTimeoutMs }), batch => batch.payload, (gets, blockId, mergeWithGets) => [...(mergeWithGets ?? []), ...gets.filter(bid => bid === blockId)], expiration, (blockId, options) => this.keyNetwork.findCoordinator(routingKeyForBlock(blockId), { ...options, intent: 'read' }));
         }
         catch (e) {
             error = e;
@@ -99,30 +104,53 @@ export class NetworkTransactor {
         // 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) => {
             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, entry) => {
+            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) => {
             if (!hasValidResponse(b))
                 return false;
             const resp = b.request.response;
             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
         // absent answer is not retried.
@@ -132,6 +160,13 @@ export class NetworkTransactor {
         // 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));
         if (retryable.length > 0 && Date.now() < expiration) {
             log('get:retry retryable=%d', retryable.length);
@@ -140,10 +175,10 @@ export class NetworkTransactor {
             // independent per root and safe to run in parallel.
             const retryOutcomes = await Promise.allSettled(retryable.map(async (b) => {
                 const excluded = new Set([b.peerId, ...(b.excludedPeers ?? [])]);
-                const retries = await createBatchesForPayload(b.payload, 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' }));
+                const retries = await createBatchesForPayload(b.payload, b.payload, (gets, blockId, mergeWithGets) => [...(mergeWithGets ?? []), ...gets.filter(id => id === blockId)], Array.from(excluded), (blockId, options) => this.keyNetwork.findCoordinator(routingKeyForBlock(blockId), { ...options, intent: 'read' }));
                 if (retries.length > 0) {
                     b.subsumedBy = [...(b.subsumedBy ?? []), ...retries];
-                    await processBatches(retries, (batch) => this.getRepo(batch.peerId).get({ blockIds: batch.payload, context: blockGets.context }, { expiration, dialTimeoutMs: this.dialTimeoutMs }), 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' }));
+                    await processBatches(retries, (batch) => this.getRepo(batch.peerId).get({ blockIds: batch.payload, context: blockGets.context }, { expiration, dialTimeoutMs: this.dialTimeoutMs }), batch => batch.payload, (gets, blockId, mergeWithGets) => [...(mergeWithGets ?? []), ...gets.filter(id => id === blockId)], expiration, (blockId, options) => this.keyNetwork.findCoordinator(routingKeyForBlock(blockId), { ...options, intent: 'read' }));
                 }
             }));
             // First-error-wins: keep any pre-existing error, otherwise adopt the first
@@ -166,13 +201,20 @@ export class NetworkTransactor {
         // — 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
@@ -193,13 +235,39 @@ export class NetworkTransactor {
                 return unavailableRank(entry.unavailable);
             return entry.unconfirmedAheadRev === undefined ? 4 : 3;
         };
+        const carriesBlock = (r) => !!r && typeof r === 'object' && r.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, held) => {
+            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();
         for (const batch of completedBatches) {
             const resp = batch.request.response;
             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);
                 }
             }
@@ -333,6 +401,56 @@ export class NetworkTransactor {
             return false;
         }
     }
+    /**
+     * 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) {
+        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. */
+    async cohortLineage(blockId, target, expiration) {
+        let cohort;
+        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) => {
+            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);
+    }
     async consolidateCoordinators(blockIds, transforms, transformForBlock) {
         // Use cluster intersections to minimize the number of coordinators.
         // For each block, find its full cluster, then greedily assign blocks to
@@ -343,7 +461,7 @@ export class NetworkTransactor {
         const fallbackBlocks = [];
         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 {
@@ -363,20 +481,11 @@ export class NetworkTransactor {
         const uncovered = new Set(blockClusterPeerIds.keys());
         const assignments = new Map(); // peerIdStr → assigned blockIds
         while (uncovered.size > 0) {
-            let bestPeer;
-            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)
+            const best = bestCoveringPeer(peerBlocks, uncovered, this.localPeerId);
+            if (!best)
                 break;
-            const covered = peerBlocks.get(bestPeer).filter(bid => uncovered.has(bid));
-            assignments.set(bestPeer, covered);
-            for (const bid of covered)
+            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
@@ -384,7 +493,7 @@ export class NetworkTransactor {
             fallbackBlocks.push(bid);
         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) {
             const key = coordinator.toString();
@@ -436,15 +545,15 @@ export class NetworkTransactor {
         let error;
         try {
             // Process all batches, noting all outstanding peers
-            await processBatches(batches, (batch) => this.getRepo(batch.peerId).pend({ ...blockAction, transforms: batch.payload }, {
+            await processBatches(batches, (batch) => this.getRepo(batch.peerId).pend(pendRequestForBatch(blockAction, batch.payload), {
                 expiration,
                 dialTimeoutMs: this.dialTimeoutMs,
                 coordinatingBlockIds: batch.coordinatingBlockIds
-            }), batch => blockIdsForTransforms(batch.payload), transformForBlock, expiration, async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options));
+            }), batch => blockIdsForTransforms(batch.payload), transformForBlock, expiration, (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) {
@@ -546,7 +655,15 @@ export class NetworkTransactor {
         return {
             success: true,
             pending: completed.flatMap(b => b.request.response.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.durability))
         };
     }
     /**
@@ -565,8 +682,8 @@ export class NetworkTransactor {
         await this.dischargeCancel(actionRef);
     }
     async queryClusterNominees(blockId) {
-        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 };
     }
@@ -583,8 +700,25 @@ export class NetworkTransactor {
         // 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 = [tailResult.durability];
+        let torn = [];
         // 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.
         //
@@ -597,6 +731,7 @@ export class NetworkTransactor {
         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
@@ -620,16 +755,17 @@ export class NetworkTransactor {
                 //     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
@@ -639,11 +775,15 @@ export class NetworkTransactor {
                     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) };
     }
     /**
      * Cancels every sweep block whose commit batch never confirmed success, so an acknowledged
@@ -674,6 +814,9 @@ export class NetworkTransactor {
      * `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.
      */
     async cancelAbandonedSweepBlocks(actionId, sweptBlocks, batches) {
         // NOTE: `confirmed` is only ever non-empty when the sweep spans MORE THAN ONE batch, and it
@@ -693,7 +836,7 @@ export class NetworkTransactor {
         }
         const abandoned = sweptBlocks.filter(bid => !confirmed.has(bid));
         if (abandoned.length === 0) {
-            return;
+            return abandoned;
         }
         try {
             await this.cancel({ actionId, blockIds: abandoned });
@@ -704,6 +847,7 @@ export class NetworkTransactor {
             }
             catch { /* ignore */ }
         }
+        return abandoned;
     }
     async commitBlock(blockId, actionId, rev, tailId, blockDigests) {
         const { batches: tailBatches, error: tailError } = await this.commitBlocks({ blockIds: [blockId], actionId, rev, tailId, blockDigests });
@@ -719,7 +863,7 @@ export class NetworkTransactor {
             }
             throw tailError;
         }
-        return { success: true };
+        return { success: true, durability: mergeDurability(confirmedDurabilities(tailBatches)) };
     }
     /**
      * Merge the RETURNED `success:false` responses out of a set of commit batches into one
@@ -728,21 +872,26 @@ export class NetworkTransactor {
      * 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.
      */
     staleFromBatches(batches) {
         const stale = Array.from(allBatches(batches, b => b.request?.isResponse && !b.request.response.success));
         if (stale.length === 0) {
             return undefined;
         }
-        const staleAt = highestStaleAt(stale.map(b => b.request.response.staleAt));
+        const responses = stale.map(b => b.request.response);
+        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.missing).filter((x) => x !== undefined)),
+            missing: distinctBlockActionTransforms(responses.flatMap(r => r.missing).filter((x) => x !== undefined)),
             ...(staleAt === undefined ? {} : { staleAt }),
+            ...(reason === undefined ? {} : { reason }),
+            conflict: responses.some(isConflictFailure),
             success: false
         };
     }
@@ -805,7 +954,7 @@ export class NetworkTransactor {
                 return cached;
             }
         }
-        return this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), { ...options, intent });
+        return this.keyNetwork.findCoordinator(routingKeyForBlock(blockId), { ...options, intent });
     }
     /**
      * Get (creating if absent) the per-transaction coordinator map for `actionId`,
@@ -923,7 +1072,7 @@ export class NetworkTransactor {
                 roundBatches = round === 0 && seedBatches
                     ? seedBatches
                     : await this.batchesForPayload(outstanding, outstanding, mergeBlocks, []);
-                await processBatches(roundBatches, (batch) => this.getRepo(batch.peerId).cancel({ actionId: actionRef.actionId, blockIds: batch.payload }, { expiration: deadline, dialTimeoutMs: this.dialTimeoutMs }), batch => batch.payload, mergeBlocks, deadline, async (blockId, options) => this.keyNetwork.findCoordinator(await blockIdToBytes(blockId), options));
+                await processBatches(roundBatches, (batch) => this.getRepo(batch.peerId).cancel({ actionId: actionRef.actionId, blockIds: batch.payload }, { expiration: deadline, dialTimeoutMs: this.dialTimeoutMs }), batch => batch.payload, mergeBlocks, deadline, (blockId, options) => this.keyNetwork.findCoordinator(routingKeyForBlock(blockId), options));
             }
             catch (e) {
                 lastError = asError(e);
@@ -968,6 +1117,28 @@ export class NetworkTransactor {
         return details;
     }
 }
+/**
+ * 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, uncovered, localPeerId) {
+    let best;
+    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
@@ -982,20 +1153,47 @@ function dischargedBlocks(batches) {
     }
     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) {
+    return Array.from(allBatches(batches, b => b.request?.isResponse === true && b.request.response.success))
+        .map(b => b.request.response.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(all, batchBlockIds) {
+    const subset = {};
+    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, batchBlockIds) {
-    if (!all)
-        return {};
-    const subset = {};
-    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, batchBlockIds) {
+    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, payload) {
+    const { baseRevs, ...rest } = action;
+    return { ...rest, transforms: payload, ...baseRevsFor(baseRevs, blockIdsForTransforms(payload)) };
 }
 /**
  * The owning collection id for an action ref, read from any fetched block's header. A