@optimystic/db-core 0.21.0 → 0.24.0

package/src/transaction/read-dependency-collector.ts

@@ -1,78 +1,78 @@
-import type { BlockId, ReadPurpose } from "../blocks/index.js";
-import type { ReadDependency } from "./transaction.js";
-
-/** One captured read: the highest revision observed for the block, plus its {@link ReadPurpose}. */
-type ReadEntry = { revision: number; purpose: ReadPurpose };
-
-/** Accumulates the read dependencies of one transaction. Keyed by block id. For each id it keeps:
- *
- *  - the HIGHEST revision observed (never downgrades — a re-read from cache must not overwrite a
- *    higher revision seen earlier), and
- *  - the read's PURPOSE with value-wins semantics: once a block is recorded as a `value` read from
- *    ANY path it stays `value`; `navigation` sticks only for a block that was never read as a value.
- *    This is the exact analogue of the max-wins rule on revision, and it makes the classification
- *    order-independent (so it is deterministic regardless of cache/timing — required for the
- *    transaction id and client signature to match across a re-executing validator; Theorem 4).
- *
- *  {@link getReadDependencies} returns only the CONFLICT set (value reads); purely-structural
- *  `navigation` reads — interior B-tree branches walked through to reach a captured leaf — are
- *  dropped. See {@link markValue} and docs/correctness.md Theorem 5.
- *
- *  One instance is shared by a collection's {@link TransactorSource} (direct structural reads —
- *  bootstrap, header) and its {@link CacheSource} (every cache hit/miss), so a block read from
- *  either layer produces a dependency. Because both feed the same collector, a cache miss records
- *  the id once from each layer at the same revision/purpose; the merge collapses those to one
- *  entry. Cleared at each txn boundary. */
-export class ReadDependencyCollector {
-	private reads = new Map<BlockId, ReadEntry>();
-
-	/** Record a read of `blockId` at `revision`. `purpose` defaults to `value` (retained); pass
-	 *  `navigation` for an interior structural read that a later {@link markValue} may or may not
-	 *  upgrade. Revision is max-wins; purpose is value-wins (see class doc). */
-	record(blockId: BlockId, revision: number, purpose: ReadPurpose = 'value'): void {
-		const prev = this.reads.get(blockId);
-		if (prev === undefined) {
-			this.reads.set(blockId, { revision, purpose });
-			return;
-		}
-		if (revision > prev.revision) {
-			prev.revision = revision;
-		}
-		// value-wins: a value read anywhere pins the block as value; navigation never downgrades it.
-		if (purpose === 'value') {
-			prev.purpose = 'value';
-		}
-	}
-
-	/** Upgrade an already-recorded read to `value` (keeping its revision), retaining it in the
-	 *  conflict set. The B-tree point-lookup path uses this to mark the terminal leaf — the
-	 *  load-bearing read whose content the result depends on — after its interior descent nodes
-	 *  were recorded as `navigation`. No-op if the id was never recorded (e.g. a leaf served from
-	 *  an uncommitted staged insert, which records no dependency at all). */
-	markValue(blockId: BlockId): void {
-		const prev = this.reads.get(blockId);
-		if (prev) {
-			prev.purpose = 'value';
-		}
-	}
-
-	/** The optimistic-concurrency conflict (read) set: every `value` read, with `navigation`
-	 *  reads excluded. Dropping a covered navigation read cannot admit a lost update — any
-	 *  concurrent change to the queried result also bumps a retained value read (the target
-	 *  leaf) — but it removes the false-positive stale rejections that structural block reads
-	 *  otherwise caused (Theorem 5 Bound). Deterministic in query shape, so a coordinator and a
-	 *  re-executing validator derive the identical set. */
-	getReadDependencies(): ReadDependency[] {
-		const result: ReadDependency[] = [];
-		for (const [blockId, entry] of this.reads) {
-			if (entry.purpose === 'value') {
-				result.push({ blockId, revision: entry.revision });
-			}
-		}
-		return result;
-	}
-
-	clear(): void {
-		this.reads.clear();
-	}
-}
+import type { BlockId, ReadPurpose } from "../blocks/index.js";
+import type { ReadDependency } from "./transaction.js";
+
+/** One captured read: the highest revision observed for the block, plus its {@link ReadPurpose}. */
+type ReadEntry = { revision: number; purpose: ReadPurpose };
+
+/** Accumulates the read dependencies of one transaction. Keyed by block id. For each id it keeps:
+ *
+ *  - the HIGHEST revision observed (never downgrades — a re-read from cache must not overwrite a
+ *    higher revision seen earlier), and
+ *  - the read's PURPOSE with value-wins semantics: once a block is recorded as a `value` read from
+ *    ANY path it stays `value`; `navigation` sticks only for a block that was never read as a value.
+ *    This is the exact analogue of the max-wins rule on revision, and it makes the classification
+ *    order-independent (so it is deterministic regardless of cache/timing — required for the
+ *    transaction id and client signature to match across a re-executing validator; Theorem 4).
+ *
+ *  {@link getReadDependencies} returns only the CONFLICT set (value reads); purely-structural
+ *  `navigation` reads — interior B-tree branches walked through to reach a captured leaf — are
+ *  dropped. See {@link markValue} and docs/correctness.md Theorem 5.
+ *
+ *  One instance is shared by a collection's {@link TransactorSource} (direct structural reads —
+ *  bootstrap, header) and its {@link CacheSource} (every cache hit/miss), so a block read from
+ *  either layer produces a dependency. Because both feed the same collector, a cache miss records
+ *  the id once from each layer at the same revision/purpose; the merge collapses those to one
+ *  entry. Cleared at each txn boundary. */
+export class ReadDependencyCollector {
+	private reads = new Map<BlockId, ReadEntry>();
+
+	/** Record a read of `blockId` at `revision`. `purpose` defaults to `value` (retained); pass
+	 *  `navigation` for an interior structural read that a later {@link markValue} may or may not
+	 *  upgrade. Revision is max-wins; purpose is value-wins (see class doc). */
+	record(blockId: BlockId, revision: number, purpose: ReadPurpose = 'value'): void {
+		const prev = this.reads.get(blockId);
+		if (prev === undefined) {
+			this.reads.set(blockId, { revision, purpose });
+			return;
+		}
+		if (revision > prev.revision) {
+			prev.revision = revision;
+		}
+		// value-wins: a value read anywhere pins the block as value; navigation never downgrades it.
+		if (purpose === 'value') {
+			prev.purpose = 'value';
+		}
+	}
+
+	/** Upgrade an already-recorded read to `value` (keeping its revision), retaining it in the
+	 *  conflict set. The B-tree point-lookup path uses this to mark the terminal leaf — the
+	 *  load-bearing read whose content the result depends on — after its interior descent nodes
+	 *  were recorded as `navigation`. No-op if the id was never recorded (e.g. a leaf served from
+	 *  an uncommitted staged insert, which records no dependency at all). */
+	markValue(blockId: BlockId): void {
+		const prev = this.reads.get(blockId);
+		if (prev) {
+			prev.purpose = 'value';
+		}
+	}
+
+	/** The optimistic-concurrency conflict (read) set: every `value` read, with `navigation`
+	 *  reads excluded. Dropping a covered navigation read cannot admit a lost update — any
+	 *  concurrent change to the queried result also bumps a retained value read (the target
+	 *  leaf) — but it removes the false-positive stale rejections that structural block reads
+	 *  otherwise caused (Theorem 5 Bound). Deterministic in query shape, so a coordinator and a
+	 *  re-executing validator derive the identical set. */
+	getReadDependencies(): ReadDependency[] {
+		const result: ReadDependency[] = [];
+		for (const [blockId, entry] of this.reads) {
+			if (entry.purpose === 'value') {
+				result.push({ blockId, revision: entry.revision });
+			}
+		}
+		return result;
+	}
+
+	clear(): void {
+		this.reads.clear();
+	}
+}

package/src/transaction/transaction.ts

@@ -128,7 +128,7 @@ export const DEFAULT_TRANSACTION_TTL_MS = 30_000;
  * Upper bound on a transaction's aged {@link Transaction.priority}. Capping is essential: it
  * bounds the fairness effect (an aged transaction cannot accrue unlimited advantage) and bounds
  * the throughput cost (it can impose at most `MaxPriority` extra race-losses on rivals before it
- * commits). Two transactions capped out at `MaxPriority` fall back to the existing promise-count /
+ * commits). Two transactions capped out at `MaxPriority` fall back to the existing approval-count /
  * message-hash tiebreak, so behavior degrades gracefully to the pre-priority status quo.
  */
 export const MaxPriority = 8;

package/src/transactor/change-notifier.ts

@@ -1,80 +1,80 @@
-import type { BlockId, CollectionId } from '../index.js';
-import type { ActionId } from '../collection/action.js';
-
-/** A commit landed on this node mutating one collection's blocks. */
-export type CollectionChangeEvent = {
-	/** Header/collection id of the affected collection (block.header.collectionId). */
-	readonly collectionId: CollectionId;
-	/** Blocks within that collection mutated by this commit. */
-	readonly blockIds: readonly BlockId[];
-	readonly actionId: ActionId;
-	readonly rev: number;
-	/**
-	 * The collection's chain tail block id at the time of this commit (the `CommitRequest.tailId`).
-	 * Anchors the rotating reactivity topic `H(tailId ‖ "reactivity")`. Present on commit-driven
-	 * events; `undefined` on read-driven promotions (the `StorageRepo.get` path has no commit tail —
-	 * those never originate anyway, and are cert-gated out downstream).
-	 */
-	readonly tailId?: BlockId;
-	/**
-	 * `true` iff this change event is a durable **invalidation** — a compensating revision + appended
-	 * `InvalidationEntry` reversing a previously-committed action proven invalid by dispute
-	 * (`docs/right-is-right.md` §Durable Invalidation), rather than an ordinary commit. An invalidation
-	 * is a committed collection change like any other, so it flows through the same notification path;
-	 * this flag lets a subscriber distinguish it (drop derived results + resubmit) from a plain commit
-	 * (refresh). A hint only — correctness never depends on it: the subscriber always re-reads the
-	 * authoritative reverted state. Absent (falsy) on ordinary commits.
-	 */
-	readonly invalidation?: boolean;
-	/**
-	 * When {@link invalidation} is set, the `actionId` of the original committed action that was
-	 * reversed (the `InvalidationEntry.invalidatedActionId`). Lets an invalidation-aware client
-	 * dedup/coalesce multiple cascade notifications by the action they reverse, and resubmit exactly
-	 * the affected work. Absent on ordinary commits.
-	 */
-	readonly invalidatedActionId?: ActionId;
-};
-
-export type CollectionChangeListener = (event: CollectionChangeEvent) => void;
-
-/**
- * The cluster-consensus commit certificate for a committed action — the **authoritative** proof
- * that the cohort agreed the commit. It is the cross-package currency the local change-notifier
- * bridge forwards into the cohort-topic substrate (`CohortTopicService.onLocalCommit`) so reactivity
- * can originate notifications **without re-signing**: a notification's signature is bit-for-bit this
- * `thresholdSig`. The bridge and every downstream consumer treat the bytes as opaque and pass them
- * through unchanged — only the cluster layer that produced consensus ever mints one.
- *
- * Peer ids are carried as their string form (the cluster keys signatures by peer-id string); db-core
- * stays cross-platform and never references a libp2p `PeerId` type here.
- */
-export type CommitCert = {
-	/** Threshold signature bytes proving `signers` agreed the commit. Forwarded UNCHANGED; never re-signed. */
-	readonly thresholdSig: Uint8Array;
-	/** Peer-id strings whose signatures compose {@link thresholdSig} (a distinct set of size ≥ {@link minSigs}). */
-	readonly signers: readonly string[];
-	/** Threshold the signer set satisfies (the cluster super-majority / cohort `k − x`). */
-	readonly minSigs: number;
-	/**
-	 * The exact byte preimage each `signers[i]` signed to produce its 64-byte chunk of
-	 * {@link thresholdSig} — the cluster's per-member commit-vote payload `utf8(commitHash + ":approve")`,
-	 * identical across all approving signers. Reactivity sets a notification's `digest` to
-	 * base64url(signedPayload) so a subscriber's threshold-verify over `digest` reproduces the exact
-	 * signed image. Opaque to db-core; minted only by the cluster layer.
-	 */
-	readonly signedPayload: Uint8Array;
-};
-
-export interface IBlockChangeNotifier {
-	/**
-	 * Subscribe to commits that mutate the given collection. Returns an
-	 * idempotent unsubscribe. Listeners are invoked AFTER the commit's critical
-	 * section (locks released), synchronously in commit order; a throwing
-	 * listener must not break the commit or other listeners (log + continue).
-	 */
-	onCollectionChange(collectionId: CollectionId, listener: CollectionChangeListener): () => void;
-}
-
-export function isBlockChangeNotifier(x: unknown): x is IBlockChangeNotifier {
-	return !!x && typeof (x as IBlockChangeNotifier).onCollectionChange === 'function';
-}
+import type { BlockId, CollectionId } from '../index.js';
+import type { ActionId } from '../collection/action.js';
+
+/** A commit landed on this node mutating one collection's blocks. */
+export type CollectionChangeEvent = {
+	/** Header/collection id of the affected collection (block.header.collectionId). */
+	readonly collectionId: CollectionId;
+	/** Blocks within that collection mutated by this commit. */
+	readonly blockIds: readonly BlockId[];
+	readonly actionId: ActionId;
+	readonly rev: number;
+	/**
+	 * The collection's chain tail block id at the time of this commit (the `CommitRequest.tailId`).
+	 * Anchors the rotating reactivity topic `H(tailId ‖ "reactivity")`. Present on commit-driven
+	 * events; `undefined` on read-driven promotions (the `StorageRepo.get` path has no commit tail —
+	 * those never originate anyway, and are cert-gated out downstream).
+	 */
+	readonly tailId?: BlockId;
+	/**
+	 * `true` iff this change event is a durable **invalidation** — a compensating revision + appended
+	 * `InvalidationEntry` reversing a previously-committed action proven invalid by dispute
+	 * (`docs/right-is-right.md` §Durable Invalidation), rather than an ordinary commit. An invalidation
+	 * is a committed collection change like any other, so it flows through the same notification path;
+	 * this flag lets a subscriber distinguish it (drop derived results + resubmit) from a plain commit
+	 * (refresh). A hint only — correctness never depends on it: the subscriber always re-reads the
+	 * authoritative reverted state. Absent (falsy) on ordinary commits.
+	 */
+	readonly invalidation?: boolean;
+	/**
+	 * When {@link invalidation} is set, the `actionId` of the original committed action that was
+	 * reversed (the `InvalidationEntry.invalidatedActionId`). Lets an invalidation-aware client
+	 * dedup/coalesce multiple cascade notifications by the action they reverse, and resubmit exactly
+	 * the affected work. Absent on ordinary commits.
+	 */
+	readonly invalidatedActionId?: ActionId;
+};
+
+export type CollectionChangeListener = (event: CollectionChangeEvent) => void;
+
+/**
+ * The cluster-consensus commit certificate for a committed action — the **authoritative** proof
+ * that the cohort agreed the commit. It is the cross-package currency the local change-notifier
+ * bridge forwards into the cohort-topic substrate (`CohortTopicService.onLocalCommit`) so reactivity
+ * can originate notifications **without re-signing**: a notification's signature is bit-for-bit this
+ * `thresholdSig`. The bridge and every downstream consumer treat the bytes as opaque and pass them
+ * through unchanged — only the cluster layer that produced consensus ever mints one.
+ *
+ * Peer ids are carried as their string form (the cluster keys signatures by peer-id string); db-core
+ * stays cross-platform and never references a libp2p `PeerId` type here.
+ */
+export type CommitCert = {
+	/** Threshold signature bytes proving `signers` agreed the commit. Forwarded UNCHANGED; never re-signed. */
+	readonly thresholdSig: Uint8Array;
+	/** Peer-id strings whose signatures compose {@link thresholdSig} (a distinct set of size ≥ {@link minSigs}). */
+	readonly signers: readonly string[];
+	/** Threshold the signer set satisfies (the cluster super-majority / cohort `k − x`). */
+	readonly minSigs: number;
+	/**
+	 * The exact byte preimage each `signers[i]` signed to produce its 64-byte chunk of
+	 * {@link thresholdSig} — the cluster's per-member commit-vote payload `utf8(commitHash + ":approve")`,
+	 * identical across all approving signers. Reactivity sets a notification's `digest` to
+	 * base64url(signedPayload) so a subscriber's threshold-verify over `digest` reproduces the exact
+	 * signed image. Opaque to db-core; minted only by the cluster layer.
+	 */
+	readonly signedPayload: Uint8Array;
+};
+
+export interface IBlockChangeNotifier {
+	/**
+	 * Subscribe to commits that mutate the given collection. Returns an
+	 * idempotent unsubscribe. Listeners are invoked AFTER the commit's critical
+	 * section (locks released), synchronously in commit order; a throwing
+	 * listener must not break the commit or other listeners (log + continue).
+	 */
+	onCollectionChange(collectionId: CollectionId, listener: CollectionChangeListener): () => void;
+}
+
+export function isBlockChangeNotifier(x: unknown): x is IBlockChangeNotifier {
+	return !!x && typeof (x as IBlockChangeNotifier).onCollectionChange === 'function';
+}

package/src/transactor/index.ts

@@ -1,5 +1,5 @@
-export * from "./change-notifier.js";
-export * from "./network-transactor.js";
-export * from "./transactor-source.js";
-export * from "./transactor.js";
-
+export * from "./change-notifier.js";
+export * from "./network-transactor.js";
+export * from "./transactor-source.js";
+export * from "./transactor.js";
+

package/src/transactor/network-transactor.ts

@@ -1,10 +1,15 @@
 import { peerIdFromString } from "../network/types.js";
 import type { PeerId } from "../network/types.js";
 import { highestStaleAt, isConflictFailure } from "../network/stale-failure.js";
-import { BlockUnavailableError } 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 } from "../index.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 } from "../index.js";
 import type { IBlockChangeNotifier, CollectionChangeListener } from "./change-notifier.js";
-import { transformForBlockId, groupBy, concatTransforms, concatTransform, transformsFromTransform, blockIdsForTransforms, Log, Tracker, CacheSource, TransactorSource } from "../index.js";
+import { transformForBlockId, concatTransforms, concatTransform, transformsFromTransform, blockIdsForTransforms } from "../transform/helpers.js";
+import { Tracker } from "../transform/tracker.js";
+import { CacheSource } from "../transform/cache-source.js";
+import { TransactorSource } 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 { isRecordEmpty } from "../utility/is-record-empty.js";
 import { type CoordinatorBatch, makeBatchesByPeer, incompleteBatches, everyBatch, allBatches, mergeBlocks, processBatches, createBatchesForPayload } from "../utility/batch-coordinator.js";
@@ -156,18 +161,29 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		};
 
 		// A batch is answered when its response carries an entry for EVERY requested
-		// block id and none of those entries is flagged `unavailable`. An entry present
+		// 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 its own answer
-		// is a guess, so it does NOT count as answered.
+		// 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.
 		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);
+			return b.payload.every(bid => resp[bid] !== undefined
+				&& resp[bid]!.unavailable === undefined
+				&& resp[bid]!.unconfirmedAheadRev === undefined);
 		};
 
 		// Retry only genuine no-response / partial-response batches. An authoritative
 		// absent answer is not retried.
+		// NOTE: a 'cohort-unreachable' entry earns this retry like any other flagged entry,
+		// and on a genuinely isolated node the retry re-picks the same node (the
+		// findCoordinator:all-excluded path) and repeats the same futile consult. Fine
+		// 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.
 		const retryable = Array.from(allBatches(batches)).filter(b =>
 			!isAuthoritative(b as any)
 		) as CoordinatorBatch<BlockId[], GetBlockResults>[];
@@ -211,22 +227,40 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		// Cache the completed batches that had actual responses (not just coordinator not found)
 		const completedBatches = Array.from(allBatches(batches, b => b.request?.isResponse as boolean && !isRecordEmpty(b.request!.response!)));
 
-		// Three-way ranking per block id: a materialized block beats an authoritative
-		// absent, which beats an `unavailable` guess — one peer that positively knows the
-		// block is absent outranks another that could not find out. Non-object junk ranks
-		// below everything so any real entry replaces it.
+		// Ranking per block id: a block the answering repo could confirm is current beats
+		// one it marked possibly-behind (`unconfirmedAheadRev`), which beats an
+		// authoritative absent, which beats an absent marked possibly-behind (a doubted
+		// tombstone), which beats an `unavailable` guess. Content still beats absence at
+		// every confidence level, and one peer that positively knows outranks another
+		// that could not find out. Without the confirmed-over-unconfirmed split, a stale
+		// flagged block and the fresh confirmed block fetched by its own retry round tie
+		// — 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: `materializedRev` 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 materializedRev among rank-2 entries.
+		// the HIGHEST materializedRev among top-rank entries.
+		// `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
+		// it: 'cohort-unreachable' is the one reason a caller may treat permissively (the
+		// answering node reached nobody, so its own view is all it has), and a partitioned
+		// coordinator answering first must not mask a well-connected one that positively
+		// established the block EXISTS ('claimed-elsewhere', or 'unmaterializable' — records
+		// held here). 'peers-unreachable' sits between: it establishes that some of the cohort
+		// was reachable, without settling existence.
+		const unavailableRank = (reason: BlockUnavailableReason): number =>
+			reason === 'cohort-unreachable' ? 0 : reason === 'peers-unreachable' ? 1 : 2;
 		const rankOf = (r: unknown): number => {
 			if (!r || typeof r !== 'object') return -1;
 			const entry = r as GetBlockResults[BlockId];
-			if (entry.block != null) return 2;
-			return entry.unavailable === undefined ? 1 : 0;
+			if (entry.block != null) return entry.unconfirmedAheadRev === undefined ? 6 : 5;
+			if (entry.unavailable !== undefined) return unavailableRank(entry.unavailable);
+			return entry.unconfirmedAheadRev === undefined ? 4 : 3;
 		};
 
 		// Create a lookup map from successful responses only
@@ -275,12 +309,18 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		// A block whose repo could not determine whether it exists carries no status either:
 		// its empty `state` would read below as `aborted`, turning "I could not find out" into
 		// a definite verdict on someone's action. Fail loudly instead, like every other read of
-		// an unavailable block (see BlockUnavailableError).
+		// an unavailable block (see BlockUnavailableError). The same goes for a state the repo
+		// could not confirm is CURRENT (`unconfirmedAheadRev`, surviving the retry round above):
+		// an action committed at the claimed-ahead revision would read out of the stale state as
+		// a definite `aborted` — this read is unpinned, so the doubt always applies.
 		for (const blockId of allBlockIds) {
 			const entry = blockStates[blockId];
 			if (entry?.unavailable !== undefined && entry.block == null) {
 				throw new BlockUnavailableError(blockId, entry.unavailable);
 			}
+			if (entry?.unconfirmedAheadRev !== undefined) {
+				throw new BlockPossiblyStaleError(blockId, entry.unconfirmedAheadRev);
+			}
 		}
 
 		// Determine status for each action ref
@@ -641,7 +681,6 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 	async commit(request: CommitRequest): Promise<CommitResult> {
 		const t0 = Date.now();
 		log('commit actionId=%s rev=%d blockIds=%d', request.actionId, request.rev, request.blockIds.length);
-		const allBlockIds = [...new Set([...request.blockIds, request.tailId])];
 
 		// Commit the header block if provided and not already in blockIds.
 		// `request.tailId` is threaded into every per-block commit so the coordinator carries it into the
@@ -649,14 +688,14 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		// CollectionChangeEvent (the reactivity topic anchor). Without this the per-block RepoCommitRequest
 		// drops the collection tail and reactivity origination is gated off (undefined tail → non-member).
 		if (request.headerId && !request.blockIds.includes(request.headerId)) {
-			const headerResult = await this.commitBlock(request.headerId, allBlockIds, request.actionId, request.rev, request.tailId);
+			const headerResult = await this.commitBlock(request.headerId, request.actionId, request.rev, request.tailId);
 			if (!headerResult.success) {
 				return headerResult;
 			}
 		}
 
 		// Commit the tail block
-		const tailResult = await this.commitBlock(request.tailId, allBlockIds, request.actionId, request.rev, request.tailId);
+		const tailResult = await this.commitBlock(request.tailId, request.actionId, request.rev, request.tailId);
 		if (!tailResult.success) {
 			return tailResult;
 		}
@@ -679,7 +718,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		return { success: true };
 	}
 
-	private async commitBlock(blockId: BlockId, blockIds: BlockId[], actionId: ActionId, rev: number, tailId?: BlockId): Promise<CommitResult> {
+	private async commitBlock(blockId: BlockId, actionId: ActionId, rev: number, tailId?: BlockId): Promise<CommitResult> {
 		const { batches: tailBatches, error: tailError } = await this.commitBlocks({ blockIds: [blockId], actionId, rev, tailId });
 		if (tailError) {
 			// commit is a pure attempt: stale → { success:false }, transient → throw. Cancellation

package/src/transactor/transactor-source.ts

@@ -1,7 +1,7 @@
 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 } from "../index.js";
-import { BlockUnavailableError } from "../network/struct.js";
+import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struct.js";
 import type { ReadDependency } from "../transaction/transaction.js";
 import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
 
@@ -43,7 +43,7 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 		// `result[id]` is undefined. Destructuring that would throw a TypeError.
 		const entry = result?.[id];
 		if (entry) {
-			const { block, state, materializedRev, unavailable } = entry;
+			const { block, state, materializedRev, 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
@@ -51,6 +51,29 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 			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);
+			}
 			// 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