@optimystic/db-core 0.24.2 → 0.25.1

package/src/transaction/operations-hash.ts

@@ -176,7 +176,7 @@ export function canonicalOperationsPayload(operations: readonly Operation[]): st
  * stringify, SHA-256 (base64url) via {@link hashString}, then prefix the versioned
  * {@link OPS_HASH_PREFIX} token (`ops.v1:`) so the wire string is self-describing.
  *
- * This is the fingerprint the coordinator sends in PendRequest.operationsHash and
+ * This is the fingerprint the coordinator sends in PendRequest.validation.operationsHash and
  * the validator recomputes; equality of this string is the cross-node agreement
  * that a transaction's operations match.
  *

package/src/transaction/transaction.ts

@@ -392,8 +392,10 @@ export type ValidationResult = {
  * Transaction validator interface.
  * Pluggable validators implement this to verify transaction integrity.
  *
- * Validators are invoked when a node receives a PendRequest with a transaction.
- * They re-execute the transaction and verify the operations match.
+ * Validators are invoked when a node receives a PendRequest carrying a `validation`
+ * payload (the transaction plus its operations hash). They re-execute the transaction
+ * and verify the operations match. A throw out of {@link validate} is treated by
+ * callers as a rejection ("validator-fault: …"), never as an approval or an abstain.
  */
 export interface ITransactionValidator {
 	/**

package/src/transactor/network-transactor.ts

@@ -2,10 +2,11 @@ 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 } from "../index.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 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 { CacheSource } from "../transform/cache-source.js";
 import { TransactorSource } from "./transactor-source.js";
 import { Log } from "../log/log.js";
@@ -237,13 +238,13 @@ 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: `materializedRev` is not part of the ranking, so two peers answering the same
+		// 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 materializedRev among top-rank entries.
+		// the HIGHEST `materialized.rev` 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
@@ -687,29 +688,84 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		// consensus commit op → each committing node's StorageRepo.commit stamps it onto the emitted
 		// 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).
+		// `request.blockDigests` (when present) is the FULL per-block declaration map for the action;
+		// it is threaded whole through commitBlock/commitBlocks and subset per batch at send time (see
+		// commitBlocks) so each cohort only signs for the blocks it is actually driving.
 		if (request.headerId && !request.blockIds.includes(request.headerId)) {
-			const headerResult = await this.commitBlock(request.headerId, request.actionId, request.rev, request.tailId);
+			const headerResult = await this.commitBlock(request.headerId, request.actionId, request.rev, request.tailId, request.blockDigests);
 			if (!headerResult.success) {
 				return headerResult;
 			}
 		}
 
 		// Commit the tail block
-		const tailResult = await this.commitBlock(request.tailId, request.actionId, request.rev, request.tailId);
+		const tailResult = await this.commitBlock(request.tailId, request.actionId, request.rev, request.tailId, request.blockDigests);
 		if (!tailResult.success) {
 			return tailResult;
 		}
 
-		// Commit all remaining block ids (excluding tail and header if it was already handled)
-		const remainingBlocks = request.blockIds.filter(bid =>
-			bid !== request.tailId &&
-			!(request.headerId && bid === request.headerId && !request.blockIds.includes(request.headerId))
-		);
+		// Sweep every non-tail block. The tail is the ONLY exclusion needed: the header-first commit
+		// above fires only when the header is NOT in `blockIds`, so a header that IS in `blockIds`
+		// belongs here, in this sweep. (The removed second filter clause tested
+		// `!blockIds.includes(headerId)` against a `bid` drawn from `blockIds` — unsatisfiable
+		// whenever `bid === headerId`, so it never excluded anything.)
+		//
+		// NOTE: measured, not assumed — the header-first branch above is currently UNREACHABLE from
+		// the only production producer of `headerId`. `TransactorSource.transact` sets it solely when
+		// the header is a fresh insert, and an inserted id is by construction in the pend's
+		// `blockIds`, so `!blockIds.includes(headerId)` is never true there. Instrumenting the branch
+		// and running both suites: 0 hits across every db-p2p mesh test, 2 hits in db-core, both from
+		// `commit-digest-threading.spec.ts` requests hand-built with the header held out of
+		// `blockIds`. So the order that actually runs in production is tail -> sweep, with the header
+		// (when the action touches it) inside the sweep — i.e. after the tail. Whether to wire the
+		// branch up or delete it, along with the three contracts that still describe it as live, is
+		// `tickets/backlog/debt-commit-header-first-branch-is-unreachable`.
+		//
+		// The tail -> sweep half of that order IS load-bearing; do not reorder it to put the
+		// contested blocks first. `Collection.bootstrapContext` documents the guarantee it rests on:
+		// "The tail is always committed first (commit protocol guarantee), so it's readable with
+		// context=undefined" — that bootstrap is what makes pending non-tail blocks visible to a
+		// chain walk. Sweeping before the tail would also let a committed header point at a
+		// never-committed tail: a dangling pointer, strictly worse than an orphaned block.
+		const remainingBlocks = request.blockIds.filter(bid => bid !== request.tailId);
 		if (remainingBlocks.length > 0) {
-			const { error } = await this.commitBlocks({ blockIds: remainingBlocks, actionId: request.actionId, rev: request.rev, tailId: request.tailId });
+			const { batches, error } = await this.commitBlocks({ blockIds: remainingBlocks, actionId: request.actionId, rev: request.rev, tailId: request.tailId, blockDigests: request.blockDigests });
 			if (error) {
-				// Non-tail block commit failures should not fail the overall action once the tail has committed.
-				// Proceed and rely on reconciliation paths (e.g. reads with context) to finalize state on lagging peers.
+				// 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
+				// (post conversion-arms, coordinators only return non-success for confirmed conflicts) —
+				// a rival holds one of these blocks' revisions, no reconciliation will ever apply OUR
+				// transform there, and proceeding would acknowledge a torn action (tail committed, the
+				// conflicted block permanently pointing elsewhere — the acknowledged-but-absent write).
+				// Surface it so the caller cancels and re-drives at a fresh revision.
+				const stale = this.staleFromBatches(batches);
+				if (stale) {
+					return stale;
+				}
+				// The tail (and header) already committed durably when this returns — a torn action.
+				// Refusing is still right, and must NOT be softened back into a blanket tolerance:
+				// acknowledging a torn action would report a write as durable while one of its blocks
+				// permanently points somewhere else. The two consequences that used to make the refusal
+				// itself harmful are now handled upstream, so the writer recovers on its own:
+				//   - its re-pend no longer meets its OWN durable revision as if a rival held it. All
+				//     three pend-tier checks carve out `latest.rev === request.rev &&
+				//     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.
+				//
+				// Transport-shaped failures (throws, no returned refusal) keep the tolerance: the commit
+				// consensus for these blocks exists, so lagging peers converge via reconciliation paths
+				// (e.g. reads with context).
 				try { log('WARN: non-tail commit had errors; proceeding after tail commit: %s', error.message); } catch { /* ignore */ }
 			}
 		}
@@ -718,36 +774,57 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		return { success: true };
 	}
 
-	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 });
+	private async commitBlock(blockId: BlockId, actionId: ActionId, rev: number, tailId?: BlockId, blockDigests?: BlockContentDigests): Promise<CommitResult> {
+		const { batches: tailBatches, error: tailError } = await this.commitBlocks({ blockIds: [blockId], actionId, rev, tailId, blockDigests });
 		if (tailError) {
 			// commit is a pure attempt: stale → { success:false }, transient → throw. Cancellation
 			// is the CALLER's responsibility (coordinator cancelPhase; TransactorSource.transact),
 			// which owns the retry budget and the committed-vs-pending picture — self-cancelling here
 			// would tear down a pend a caller's retry loop is still working against, and double-cancel.
 			// Collect and return any active stale failures
-			const stale = Array.from(allBatches(tailBatches, b => b.request?.isResponse as boolean && !b.request!.response!.success));
-			if (stale.length > 0) {
-				// NOTE: a reason-only StaleFailure (success:false, no `missing`) lands here too and
-				// returns { missing: [], success:false } — the `reason` PROSE is still dropped rather
-				// than surfaced via `throw tailError`. `staleAt` is carried, so the one machine-readable
-				// fact in that prose (which block is at which revision) now survives; only the free-form
-				// wording is lost. If the wording itself is ever needed, gate this branch on non-empty
-				// missing rather than reinstating it unconditionally.
-				const staleAt = highestStaleAt(stale.map(b => (b.request!.response! as StaleFailure).staleAt));
-				return {
-					missing: distinctBlockActionTransforms(stale.flatMap(b => (b.request!.response! as StaleFailure).missing).filter((x): x is ActionTransforms => x !== undefined)),
-					...(staleAt === undefined ? {} : { staleAt }),
-					success: false as const
-				};
+			const stale = this.staleFromBatches(tailBatches);
+			if (stale) {
+				return stale;
 			}
 			throw tailError;
 		}
 		return { success: true };
 	}
 
-	/** Attempts to commit a set of blocks, and handles failures and errors */
-	private async commitBlocks({ blockIds, actionId, rev, tailId }: RepoCommitRequest) {
+	/**
+	 * Merge the RETURNED `success:false` responses out of a set of commit batches into one
+	 * {@link StaleFailure}, or `undefined` when every failure was transport-shaped (thrown, no
+	 * response). Shared by {@link commitBlock} (tail/header) and {@link commit}'s non-tail sweep —
+	 * 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.
+	 */
+	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));
+		return {
+			missing: distinctBlockActionTransforms(stale.flatMap(b => (b.request!.response! as StaleFailure).missing).filter((x): x is ActionTransforms => x !== undefined)),
+			...(staleAt === undefined ? {} : { staleAt }),
+			success: false as const
+		};
+	}
+
+	/** Attempts to commit a set of blocks, and handles failures and errors.
+	 *
+	 * `blockDigests` arrives as the action's FULL declaration map and is narrowed to each batch's own
+	 * block ids inside the send callback below — never up front. Each batch's message becomes its own
+	 * cluster record, so shipping the whole map would make one cohort sign for blocks it is not
+	 * responsible for; and `processBatches` re-batches failed blocks onto different coordinators, so
+	 * only a send-time subset stays correct across retries. */
+	private async commitBlocks({ blockIds, actionId, rev, tailId, blockDigests }: RepoCommitRequest) {
 		const expiration = Date.now() + this.timeoutMs;
 		// Thread the transaction's actionId so both the initial batch assembly and any
 		// per-block retry re-resolution prefer the coordinator pend already resolved.
@@ -757,7 +834,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		try {
 			await processBatches(
 				batches,
-				(batch) => this.getRepo(batch.peerId).commit({ actionId, blockIds: batch.payload, rev, tailId }, { expiration, dialTimeoutMs: this.dialTimeoutMs }),
+				(batch) => this.getRepo(batch.peerId).commit({ actionId, blockIds: batch.payload, rev, tailId, ...digestsFor(blockDigests, batch.payload) }, { expiration, dialTimeoutMs: this.dialTimeoutMs }),
 				batch => batch.payload,
 				mergeBlocks,
 				expiration,
@@ -898,6 +975,20 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 }
 
 
+/** 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);
+}
+
 /**
  * The owning collection id for an action ref, read from any fetched block's header. A
  * committed-then-invalidated action still has a materialized (compensating) block whose header carries

package/src/transactor/transactor-source.ts

@@ -1,9 +1,10 @@
 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 type { IBlock, BlockId, BlockHeader, ITransactor, ActionId, StaleFailure, ActionContext, BlockType, BlockSource, ReadPurpose, Transforms, BlockContentDigests } from "../index.js";
 import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struct.js";
 import type { ReadDependency } from "../transaction/transaction.js";
 import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
+import { blockDigestsField } from "../transform/digest.js";
 
 export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlock> {
 	/** Shared with this collection's CacheSource so cache hits also record dependencies.
@@ -43,7 +44,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, unconfirmedAheadRev } = entry;
+			const { block, state, materialized, unavailable, unconfirmedAheadRev } = entry;
 			// An entry flagged `unavailable` with no block is the repo saying "I could not find
 			// out whether this exists" — an answer that must not be read as absent. Throw rather
 			// than return undefined, and record no read dependency (dependencies are recorded
@@ -84,12 +85,12 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 				// read purpose (default `value`) so a purely-structural navigation read can later be
 				// dropped from the conflict set (see ReadDependencyCollector / Theorem 5).
 				// Record the revision the content was MATERIALIZED at, not the newest the repo holds —
-				// see {@link GetBlockResult.materializedRev} for why `state.latest` is the wrong number
+				// see {@link GetBlockResult.materialized} for why `state.latest` is the wrong number
 				// and why the fallback preserves today's behaviour for repos that omit the field.
 				// Both sinks must take the SAME value: CacheSource learns it via getReadRevision on a
 				// miss-load and re-emits it on every later hit, so a split would stamp the cache
 				// differently from the collector.
-				const rev = materializedRev ?? state.latest?.rev ?? 0;
+				const rev = materialized?.rev ?? state.latest?.rev ?? 0;
 				this.collector.record(id, rev, purpose);
 				this.readRevisions.set(id, rev);
 			}
@@ -127,17 +128,23 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 	 * @param transform - The transforms to apply.
 	 * @param actionId - The action id.
 	 * @param rev - The revision number.
-	 * @param headerId - The Id of the collection's header block.  If specified, this block's transform is performed first,
-	 * in the event that there is a race to create the collection itself, or in the event that the tail block is full and
-	 * is transitioning to a new block.  Ignored if the given headerId is not present in the transforms.
+	 * @param headerId - The Id of the collection's header block.  Forwarded to the commit only when the header is a
+	 * fresh insert, which is the create-the-collection race this was meant to order.  NOTE: that forwarding no longer
+	 * has any effect — `NetworkTransactor.commit` runs its header-first step only for a header held OUT of `blockIds`,
+	 * and an inserted id is always IN it, so the header commits inside the ordinary sweep (after the tail) like any
+	 * other touched block.  Wire it up or drop it: `tickets/backlog/debt-commit-header-first-branch-is-unreachable`.
 	 * @param tailId - The Id of the collection's log tail block.  If specified, this block's transform is performed next
 	 * (prior to the rest of the block operations), to resolve the "winner" of a race to commit to the collection.
 	 * @param priority - Aged, advisory retry priority (default 0). Rides on the pend so a repeatedly-losing
 	 * single-collection sync out-ranks fresh rivals in a concurrent race (`resolveRace`); fairness-only, never
 	 * affects validity. Omitted from the pend when 0 so the common first-attempt pend serializes exactly as before.
+	 * @param blockDigests - Optional per-block content declarations for this commit (see {@link BlockContentDigests}),
+	 * computed by the caller from the same tracker that produced `transform`. Omitted from the commit request when
+	 * undefined, so a caller that declares nothing produces exactly the request shape as before — the field rides
+	 * inside every cohort signature's hash preimage, so keeping the shape clean keeps those preimages clean.
 	 * @returns A promise that resolves to undefined if the action is successful, or a StaleFailure if the action is stale.
 	 */
-	async transact(transform: Transforms, actionId: ActionId, rev: number, headerId: BlockId, tailId: BlockId, priority = 0): Promise<undefined | StaleFailure> {
+	async transact(transform: Transforms, actionId: ActionId, rev: number, headerId: BlockId, tailId: BlockId, priority = 0, blockDigests?: BlockContentDigests): Promise<undefined | StaleFailure> {
 		const pendResult = await this.transactor.pend({ transforms: transform, actionId, rev, policy: 'r', ...(priority > 0 ? { priority } : {}) });
 		if (!pendResult.success) {
 			return pendResult;
@@ -149,7 +156,8 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 				tailId,
 				blockIds: pendResult.blockIds,
 				actionId,
-				rev
+				rev,
+				...blockDigestsField(blockDigests)
 			});
 			if (!commitResult.success) {
 				await this.transactor.cancel({ actionId, blockIds: pendResult.blockIds });

package/src/transform/cache-source.ts

@@ -100,6 +100,26 @@ export class CacheSource<T extends IBlock> implements BlockSource<T> {
 		return structuredClone(block);
 	}
 
+	/** The block currently cached for `id`, without consulting the source. Cloned (callers apply ops
+	 *  to it) and recency-neutral ({@link LruMap.peek}) — an observation pass must neither pay a
+	 *  network read nor reshape eviction order. Records no read dependency: the caller that peeks
+	 *  already read the block through {@link tryGet} (that is how it got cached), so the dependency
+	 *  exists; a digest pass merely re-describes it. */
+	peek(id: BlockId): T | undefined {
+		const block = this.cache.peek(id);
+		return block === undefined ? undefined : structuredClone(block);
+	}
+
+	/** The committed revision of the content currently cached for `id` — the source-reported
+	 *  materialized revision learned on miss-load (see {@link revisions}), NOT the block's own
+	 *  `state.latest.rev`. An LRU-evicted id can leave a stale entry here (see the NOTE on
+	 *  {@link revisions}); callers must therefore require BOTH {@link peek} and this to be present —
+	 *  {@link peek} returns `undefined` for the evicted id, so a stale revision never pairs with a
+	 *  peeked block. */
+	getCachedRevision(id: BlockId): number | undefined {
+		return this.revisions.get(id);
+	}
+
 	/** Upgrade an already-captured read of `id` to a `value` read in the shared collector,
 	 *  retaining it in the conflict set. The B-tree point-lookup descent calls this (through the
 	 *  Tracker, which forwards) to pin the terminal leaf after recording the interior nodes as

package/src/transform/digest.ts

@@ -0,0 +1,72 @@
+import type { BlockId, IBlock } from "../index.js";
+import type { BlockContentDigests } from "../network/struct.js";
+import { canonicalBlockHash } from "../blocks/helpers.js";
+import { createLogger } from "../logger.js";
+import { isRecordEmpty } from "../utility/is-record-empty.js";
+import type { Tracker } from "./tracker.js";
+
+const log = createLogger('digest');
+
+/** Digests for the blocks the tracker's staged transforms touch, computed WITHOUT loading anything
+ * from the source. An id whose base is not already cached is omitted rather than fetched — an
+ * omitted id never fails the commit, it only forfeits what a declaration buys (see the NOTE below).
+ * Each digest is the {@link canonicalBlockHash} of what {@link Tracker.peekMaterialized} says the
+ * block will contain at the committing revision; `baseRev` rides along except for base-independent
+ * (inserted) blocks. */
+// NOTE: coverage is bounded by the read cache, not by the transaction. A commit whose update-carrying
+// blocks outnumber the CacheSource capacity (default 128) silently digests only the ids still
+// resident, and the declared count does not merely thin out — it CAPS. Measured through the
+// production path (`Collection.act`/`sync`) in `test/digest-cache-coverage.spec.ts`: with N
+// update-carrying blocks the declared count is 32/32 at N=32, then 126 at N=128, 200, 256 AND 512
+// (126 = the 128 slots less the collection header and log tail), i.e. 100%, 98.4%, 63.0%, 49.2%,
+// 24.6%. Coverage therefore decays as 1/N and an arbitrarily large commit declares an arbitrarily
+// small fraction of itself. The survivors are the newest contiguous run, exactly as LRU eviction
+// predicts.
+// Omission also costs MORE than it used to: it still degrades gracefully on the read path, but an
+// undeclared block retains no durable `BlockCommitProof` and so can never GAIN a holder by push.
+// That consequence is stated once, canonically, at {@link CommitRequest.blockDigests} in
+// `network/struct.ts`; do not restate it here.
+// Still accepted here rather than fixed in place: both remedies are larger than this function —
+// size the cache to the transaction, or carry the base revision alongside the staged updates instead
+// of re-reading it here. Tracked as `debt-digest-coverage-capped-by-read-cache`. Revisit when a
+// workload legitimately commits more update-carrying blocks than the cache holds.
+export async function computeBlockContentDigests<T extends IBlock>(
+	tracker: Tracker<T>,
+	blockIds: BlockId[]
+): Promise<BlockContentDigests> {
+	const digests: BlockContentDigests = {};
+	for (const id of blockIds) {
+		const peeked = peekOrSkip(tracker, id);
+		if (!peeked) continue;
+		digests[id] = {
+			digest: await canonicalBlockHash(peeked.block),
+			...(peeked.baseRev !== undefined ? { baseRev: peeked.baseRev } : {}),
+		};
+	}
+	return digests;
+}
+
+/** Wraps `blockDigests` so it spreads onto a request only when there is something to declare. The
+ * empty map omits the key entirely rather than sending `{}`: the request is hashed verbatim into
+ * every cohort signature preimage, so a commit that declares nothing must serialize exactly as it
+ * did before this field existed. Every producer of the field goes through here. */
+export function blockDigestsField(digests: BlockContentDigests | undefined): { blockDigests?: BlockContentDigests } {
+	return digests && !isRecordEmpty(digests) ? { blockDigests: digests } : {};
+}
+
+/** {@link Tracker.peekMaterialized}, degraded to "undeclared" when materializing throws.
+ *
+ * Declaring content must never break committing it. Materializing replays the staged ops against the
+ * LOCALLY CACHED base, which can legitimately fail — e.g. another action's commit folded into the
+ * cache (`CacheSource.transformCache`) shrank an array a staged splice indexes into. That transaction
+ * is doomed, but it must die as a retryable stale failure from the pend/commit round trip, not as a
+ * TypeError thrown out of `sync()` before the pend. The failure is logged rather than silently eaten,
+ * because the same swallow would also hide a genuine `applyTransform` bug. */
+function peekOrSkip<T extends IBlock>(tracker: Tracker<T>, id: BlockId): { block: IBlock; baseRev?: number } | undefined {
+	try {
+		return tracker.peekMaterialized(id);
+	} catch (e) {
+		log('block %s left undeclared: materializing against the cached base failed: %o', id, e);
+		return undefined;
+	}
+}

package/src/transform/index.ts

@@ -1,6 +1,7 @@
 export * from "./atomic.js";
 export * from "./atomic-proxy.js";
 export * from "./cache-source.js";
+export * from "./digest.js";
 export * from "./helpers.js";
 export * from "./struct.js";
 export * from "./tracker.js";

package/src/transform/tracker.ts

@@ -1,5 +1,5 @@
 import type { IBlock, BlockId, BlockStore as IBlockStore, BlockHeader, BlockOperation, BlockType, BlockSource as IBlockSource, ReadPurpose } from "../index.js";
-import { applyOperation, applyOperations, emptyTransforms, blockIdsForTransforms } from "./helpers.js";
+import { applyOperation, applyOperations, applyTransform, emptyTransforms, blockIdsForTransforms, transformForBlockId } from "./helpers.js";
 import { ensured } from "../utility/ensured.js";
 
 /** A block store that collects transformations, without applying them to the underlying source.
@@ -65,6 +65,47 @@ export class Tracker<T extends IBlock> implements IBlockStore<T> {
 		return block;                                    // no-ops path unchanged (source already cloned)
 	}
 
+	/** The block `id` materializes to under the staged transforms, computed WITHOUT loading from the
+	 * source, plus the committed revision of the base used. `undefined` when not computable here —
+	 * nothing staged for the id, the result is a delete, or an update's base is not locally cached
+	 * (a commit must not pay a network round trip to describe itself).
+	 *
+	 * Materializes with the canonical {@link applyTransform} — the exact function the member side
+	 * uses at commit — so client and member can never disagree on semantics (insert replaces the
+	 * block, then updates apply, then delete wins). An insert makes the result base-independent, so
+	 * `baseRev` is absent; updates-only returns the base's cached committed revision, probed from the
+	 * source via `peek`/`getCachedRevision` (duck-typed like {@link sourceGeneration}, because Tracker
+	 * layers over test doubles; `peek` must return a clone — CacheSource's does). Recency-neutral and
+	 * memo-neutral: observably changes no tracker or source state. */
+	peekMaterialized(id: BlockId): { block: IBlock; baseRev?: number } | undefined {
+		const transform = transformForBlockId(this.transforms, id);
+		if (transform.insert === undefined && transform.updates === undefined && transform.delete === undefined) {
+			return undefined;                              // nothing staged for this id
+		}
+		if (transform.delete) {
+			return undefined;                              // delete-last-wins: materializes to nothing
+		}
+		if (transform.insert) {
+			// applyTransform mutates the insert in place when updates ride along; transformForBlockId
+			// clones `updates` but NOT `insert`, so clone here to keep the staged transform pristine.
+			transform.insert = structuredClone(transform.insert);
+			const block = applyTransform(undefined, transform);
+			return block ? { block } : undefined;
+		}
+		const src = this.source as {
+			peek?: (id: BlockId) => T | undefined;
+			getCachedRevision?: (id: BlockId) => number | undefined;
+		};
+		if (typeof src.peek !== 'function' || typeof src.getCachedRevision !== 'function') return undefined;
+		const base = src.peek(id);
+		const baseRev = src.getCachedRevision(id);
+		// Require BOTH: an LRU-evicted id can leave a stale cached revision behind (see the NOTE on
+		// CacheSource's revisions map); peek returning undefined keeps it from pairing with a block.
+		if (base === undefined || baseRev === undefined) return undefined;
+		const block = applyTransform(base, transform);   // base already a clone (peek contract)
+		return block ? { block, baseRev } : undefined;
+	}
+
 	/** Forward a leaf-value upgrade down to the source's read collector (duck-typed: only the
 	 *  CacheSource layer implements it). Lets the B-tree point-lookup descent, which reads through
 	 *  this tracker, pin its terminal leaf as a `value` read after tagging interior nodes

package/src/utility/canonical-json.ts

@@ -0,0 +1,16 @@
+/**
+ * Deterministic JSON: sorts object keys so the encoding — and therefore any hash over it — is
+ * independent of key insertion order. Arrays keep their order (position is meaning).
+ *
+ * The ONE implementation behind every db-core agreement hash: block content
+ * ({@link canonicalBlockHash}) and cluster record/membership hashes ({@link membershipDigest},
+ * `computeMessageHash` and friends). Two nodes that encode differently disagree on honest data, so
+ * a second copy is a correctness hazard, not a style nit — import this rather than re-deriving it.
+ */
+export function canonicalJson(value: unknown): string {
+	return JSON.stringify(value, (_, v) =>
+		v && typeof v === 'object' && !Array.isArray(v)
+			? Object.keys(v).sort().reduce((o: Record<string, unknown>, k) => { o[k] = v[k]; return o; }, {})
+			: v
+	);
+}

package/src/utility/lru-map.ts

@@ -20,6 +20,11 @@ export class LruMap<K, V> {
 		return value;
 	}
 
+	/** Read without refreshing recency — for observation passes that must not reshape eviction order. */
+	peek(key: K): V | undefined {
+		return this.map.get(key);
+	}
+
 	set(key: K, value: V): this {
 		// If already present, delete first to refresh position
 		if (this.map.has(key)) {