@optimystic/db-core 0.25.0 → 0.26.0

package/src/transactor/transactor-source.ts

@@ -1,172 +1,170 @@
-import { randomBytes } from '@noble/hashes/utils.js'
-import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
-import type { IBlock, BlockId, BlockHeader, ITransactor, ActionId, StaleFailure, ActionContext, BlockType, BlockSource, ReadPurpose, Transforms, BlockContentDigests } from "../index.js";
-import { 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.
-	 *  Defaults to a private instance so internal log-walk sources (which never need a
-	 *  transaction read set) work standalone. */
-	private readonly collector: ReadDependencyCollector;
-	/** Last revision observed per id, so CacheSource can learn the revision on a miss-load
-	 *  (it calls {@link getReadRevision} right after this source serves the block). */
-	private readRevisions = new Map<BlockId, number>();
-
-	constructor(
-		private readonly collectionId: BlockId,
-		private readonly transactor: ITransactor,
-		public actionContext: ActionContext | undefined,
-		collector?: ReadDependencyCollector,
-	) {
-		this.collector = collector ?? new ReadDependencyCollector();
-	}
-
-	createBlockHeader(type: BlockType, newId?: BlockId): BlockHeader {
-		return {
-			type,
-			id: newId ?? this.generateId(),
-			collectionId: this.collectionId,
-		};
-	}
-
-	generateId(): BlockId {
-		// 256-bits to fully utilize DHT address space
-		return uint8ArrayToString(randomBytes(32), 'base64url')
-	}
-
-	async tryGet(id: BlockId, purpose: ReadPurpose = 'value'): Promise<TBlock | undefined> {
-		const result = await this.transactor.get({ blockIds: [id], context: this.actionContext });
-		// Guard the per-key entry: some transactors return a sparse result that omits `id`
-		// entirely (e.g. block genuinely not found), so `result` is a truthy object but
-		// `result[id]` is undefined. Destructuring that would throw a TypeError.
-		const entry = result?.[id];
-		if (entry) {
-			const { block, state, materialized, unavailable, unconfirmedAheadRev } = entry;
-			// An entry flagged `unavailable` with no block is the repo saying "I could not find
-			// out whether this exists" — an answer that must not be read as absent. Throw rather
-			// than return undefined, and record no read dependency (dependencies are recorded
-			// only for blocks that actually exist). A repo that omits the flag stays authoritative.
-			if (!block && unavailable) {
-				throw new BlockUnavailableError(id, unavailable);
-			}
-			// A read whose surviving answer is marked possibly-behind (`unconfirmedAheadRev`
-			// outlived the transactor's retry round: every reachable coordinator served content it
-			// could not confirm current) must not pose as an answer for a view that should CONTAIN
-			// the claimed revision. Two such views, the same test the coordinator applies when it
-			// stamps: an UNPINNED "give me latest" read — the tail read is the one seam where a
-			// lagging collection can learn the truth (Collection.bootstrapContext), and silently
-			// serving doubted content there is exactly how a collection view freezes forever — and
-			// a read PINNED AT OR ABOVE the claim, whose snapshot is missing a revision the cohort
-			// says exists inside it. A read pinned strictly BELOW the claim keeps working: it
-			// legitimately asks for an older view, which is being served correctly.
-			// No read dependency is recorded: the throw means nothing was read.
-			// NOTE: accepted tradeoff — this converts a silent wrong answer into a loud failure. A
-			// node partitioned from every coordinator able to confirm currency used to read (stale)
-			// data indefinitely without any signal; it now raises BlockPossiblyStaleError on the
-			// reads that should contain the claim, until the partition heals or the claim is
-			// settled. Deliberate: the
-			// silent alternative is a collection view that forks and freezes with no report
-			// (ticket coordinator-serves-stale-data-as-if-confirmed). Revisit only if a
-			// degraded-read mode (serve-with-warning) becomes a product requirement.
-			if (unconfirmedAheadRev !== undefined
-				&& (this.actionContext === undefined || this.actionContext.rev >= unconfirmedAheadRev)) {
-				throw new BlockPossiblyStaleError(id, unconfirmedAheadRev);
-			}
-			// 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
-			// dependency for a nonexistent block. This makes the "absent reads nothing" contract uniform
-			// with the sparse-result case (entry omitted) — see transactor-source.spec.ts sparse test.
-			if (block) {
-				// Record read dependency for optimistic concurrency control, carrying the caller's
-				// read purpose (default `value`) so a purely-structural navigation read can later be
-				// dropped from the conflict set (see ReadDependencyCollector / Theorem 5).
-				// Record the revision the content was MATERIALIZED at, not the newest the repo holds —
-				// see {@link GetBlockResult.materialized} for why `state.latest` is the wrong number
-				// and why the fallback preserves today's behaviour for repos that omit the field.
-				// Both sinks must take the SAME value: CacheSource learns it via getReadRevision on a
-				// miss-load and re-emits it on every later hit, so a split would stamp the cache
-				// differently from the collector.
-				const rev = materialized?.rev ?? state.latest?.rev ?? 0;
-				this.collector.record(id, rev, purpose);
-				this.readRevisions.set(id, rev);
-			}
-			// TODO: if the state reports that there is a pending action, record this so that we are sure to update before syncing
-			//state.pendings
-			return block as TBlock;
-		}
-	}
-
-	/** The revision observed the last time this source served {@link id} (from its committed
-	 *  state), or undefined if this source has never served it. CacheSource reads this on a
-	 *  miss-load to learn the revision to record and store. */
-	getReadRevision(id: BlockId): number | undefined {
-		return this.readRevisions.get(id);
-	}
-
-	getReadDependencies(): ReadDependency[] {
-		return this.collector.getReadDependencies();
-	}
-
-	/** The collector this source records into — the one shared with the collection's
-	 *  CacheSource. Exposed ONLY so a pinned read view built with `recordReads: true`
-	 *  can feed the same per-transaction read set (see Collection.createReadTracker);
-	 *  every other consumer should go through {@link getReadDependencies}. */
-	getCollector(): ReadDependencyCollector {
-		return this.collector;
-	}
-
-	clearReadDependencies(): void {
-		this.collector.clear();
-	}
-
-	/**
-	 * Attempts to apply the given transforms in a transactional manner.
-	 * @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.  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, 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;
-		}
-		const isNew = transform.inserts && Object.hasOwn(transform.inserts, headerId);
-		try {
-			const commitResult = await this.transactor.commit({
-				headerId: isNew ? headerId : undefined,
-				tailId,
-				blockIds: pendResult.blockIds,
-				actionId,
-				rev,
-				...blockDigestsField(blockDigests)
-			});
-			if (!commitResult.success) {
-				await this.transactor.cancel({ actionId, blockIds: pendResult.blockIds });
-				return commitResult;
-			}
-		} catch (e) {
-			await this.transactor.cancel({ actionId, blockIds: pendResult.blockIds });
-			throw e;
-		}
-	}
-}
-
+import { randomBytes } from '@noble/hashes/utils.js'
+import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
+import type { IBlock, BlockId, BlockHeader, ITransactor, ActionId, StaleFailure, ActionContext, BlockType, BlockSource, ReadPurpose, Transforms, BlockContentDigests } from "../index.js";
+import { 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.
+	 *  Defaults to a private instance so internal log-walk sources (which never need a
+	 *  transaction read set) work standalone. */
+	private readonly collector: ReadDependencyCollector;
+	/** Last revision observed per id, so CacheSource can learn the revision on a miss-load
+	 *  (it calls {@link getReadRevision} right after this source serves the block). */
+	private readRevisions = new Map<BlockId, number>();
+
+	constructor(
+		private readonly collectionId: BlockId,
+		private readonly transactor: ITransactor,
+		public actionContext: ActionContext | undefined,
+		collector?: ReadDependencyCollector,
+	) {
+		this.collector = collector ?? new ReadDependencyCollector();
+	}
+
+	createBlockHeader(type: BlockType, newId?: BlockId): BlockHeader {
+		return {
+			type,
+			id: newId ?? this.generateId(),
+			collectionId: this.collectionId,
+		};
+	}
+
+	generateId(): BlockId {
+		// 256-bits to fully utilize DHT address space
+		return uint8ArrayToString(randomBytes(32), 'base64url')
+	}
+
+	async tryGet(id: BlockId, purpose: ReadPurpose = 'value'): Promise<TBlock | undefined> {
+		const result = await this.transactor.get({ blockIds: [id], context: this.actionContext });
+		// Guard the per-key entry: some transactors return a sparse result that omits `id`
+		// entirely (e.g. block genuinely not found), so `result` is a truthy object but
+		// `result[id]` is undefined. Destructuring that would throw a TypeError.
+		const entry = result?.[id];
+		if (entry) {
+			const { block, state, materialized, unavailable, unconfirmedAheadRev } = entry;
+			// An entry flagged `unavailable` with no block is the repo saying "I could not find
+			// out whether this exists" — an answer that must not be read as absent. Throw rather
+			// than return undefined, and record no read dependency (dependencies are recorded
+			// only for blocks that actually exist). A repo that omits the flag stays authoritative.
+			if (!block && unavailable) {
+				throw new BlockUnavailableError(id, unavailable);
+			}
+			// A read whose surviving answer is marked possibly-behind (`unconfirmedAheadRev`
+			// outlived the transactor's retry round: every reachable coordinator served content it
+			// could not confirm current) must not pose as an answer for a view that should CONTAIN
+			// the claimed revision. Two such views, the same test the coordinator applies when it
+			// stamps: an UNPINNED "give me latest" read — the tail read is the one seam where a
+			// lagging collection can learn the truth (Collection.bootstrapContext), and silently
+			// serving doubted content there is exactly how a collection view freezes forever — and
+			// a read PINNED AT OR ABOVE the claim, whose snapshot is missing a revision the cohort
+			// says exists inside it. A read pinned strictly BELOW the claim keeps working: it
+			// legitimately asks for an older view, which is being served correctly.
+			// No read dependency is recorded: the throw means nothing was read.
+			// NOTE: accepted tradeoff — this converts a silent wrong answer into a loud failure. A
+			// node partitioned from every coordinator able to confirm currency used to read (stale)
+			// data indefinitely without any signal; it now raises BlockPossiblyStaleError on the
+			// reads that should contain the claim, until the partition heals or the claim is
+			// settled. Deliberate: the
+			// silent alternative is a collection view that forks and freezes with no report
+			// (ticket coordinator-serves-stale-data-as-if-confirmed). Revisit only if a
+			// degraded-read mode (serve-with-warning) becomes a product requirement.
+			if (unconfirmedAheadRev !== undefined
+				&& (this.actionContext === undefined || this.actionContext.rev >= unconfirmedAheadRev)) {
+				throw new BlockPossiblyStaleError(id, unconfirmedAheadRev);
+			}
+			// 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
+			// dependency for a nonexistent block. This makes the "absent reads nothing" contract uniform
+			// with the sparse-result case (entry omitted) — see transactor-source.spec.ts sparse test.
+			if (block) {
+				// Record read dependency for optimistic concurrency control, carrying the caller's
+				// read purpose (default `value`) so a purely-structural navigation read can later be
+				// dropped from the conflict set (see ReadDependencyCollector / Theorem 5).
+				// Record the revision the content was MATERIALIZED at, not the newest the repo holds —
+				// see {@link GetBlockResult.materialized} for why `state.latest` is the wrong number
+				// and why the fallback preserves today's behaviour for repos that omit the field.
+				// Both sinks must take the SAME value: CacheSource learns it via getReadRevision on a
+				// miss-load and re-emits it on every later hit, so a split would stamp the cache
+				// differently from the collector.
+				const rev = materialized?.rev ?? state.latest?.rev ?? 0;
+				this.collector.record(id, rev, purpose);
+				this.readRevisions.set(id, rev);
+			}
+			// TODO: if the state reports that there is a pending action, record this so that we are sure to update before syncing
+			//state.pendings
+			return block as TBlock;
+		}
+	}
+
+	/** The revision observed the last time this source served {@link id} (from its committed
+	 *  state), or undefined if this source has never served it. CacheSource reads this on a
+	 *  miss-load to learn the revision to record and store. */
+	getReadRevision(id: BlockId): number | undefined {
+		return this.readRevisions.get(id);
+	}
+
+	getReadDependencies(): ReadDependency[] {
+		return this.collector.getReadDependencies();
+	}
+
+	/** The collector this source records into — the one shared with the collection's
+	 *  CacheSource. Exposed ONLY so a pinned read view built with `recordReads: true`
+	 *  can feed the same per-transaction read set (see Collection.createReadTracker);
+	 *  every other consumer should go through {@link getReadDependencies}. */
+	getCollector(): ReadDependencyCollector {
+		return this.collector;
+	}
+
+	clearReadDependencies(): void {
+		this.collector.clear();
+	}
+
+	/**
+	 * Attempts to apply the given transforms in a transactional manner.
+	 * @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. Forwarded to the commit only when the header is a
+	 * fresh insert, so the collection-identifying metadata (see `CommitRequest.headerId`) is present on the commit
+	 * that creates it.
+	 * @param tailId - The Id of the collection's log tail block.  This block's transform is committed FIRST
+	 * (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, 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;
+		}
+		const isNew = transform.inserts && Object.hasOwn(transform.inserts, headerId);
+		try {
+			const commitResult = await this.transactor.commit({
+				headerId: isNew ? headerId : undefined,
+				tailId,
+				blockIds: pendResult.blockIds,
+				actionId,
+				rev,
+				...blockDigestsField(blockDigests)
+			});
+			if (!commitResult.success) {
+				await this.transactor.cancel({ actionId, blockIds: pendResult.blockIds });
+				return commitResult;
+			}
+		} catch (e) {
+			await this.transactor.cancel({ actionId, blockIds: pendResult.blockIds });
+			throw e;
+		}
+	}
+}
+

package/src/transform/atomic.ts

@@ -8,6 +8,12 @@ export class Atomic<TBlock extends IBlock> extends Tracker<TBlock> {
 	}
 
 	commit() {
+		// Hand the bases pinned inside this atomic to the parent tracker BEFORE reset() wipes this
+		// store — without this, a single act() carrying more actions than the read cache holds loses
+		// digest coverage, because by the flush below the cache has already evicted the early bases.
+		// The parent gets a COPY (adopt), not this store itself: sharing the store would let the
+		// reset() below wipe the parent's pins a line before flushing into it.
+		if (this.store instanceof Tracker) this.store.pins.adopt(this.pins);
 		const transform = this.reset();
 		applyTransformToStore(transform, this.store);
 	}

package/src/transform/base-pins.ts

@@ -0,0 +1,83 @@
+import type { BlockId, IBlock } from "../index.js";
+
+/** The committed base of one block, captured at the moment an update for it was staged. */
+export type PinnedBase = {
+	/** Cloned base content. Callers MUST clone again before applying a transform — applyTransform
+	 *  mutates, and the same pin is re-used by every retry attempt's digest pass. */
+	block: IBlock;
+	/** Committed revision of that base (CacheSource.getCachedRevision at pin time). */
+	rev: number;
+	/** Source drift generation at pin time (CacheSource.getGeneration). A pin whose generation no
+	 *  longer matches the source's is STALE and must not be used. */
+	gen: number;
+};
+
+/** Per-transaction map of block id -> {@link PinnedBase}. Owned by a {@link Tracker}, shared by
+ * reference across the trackers of one transaction (the collection's live tracker and each
+ * per-attempt snapshot tracker), so a base pinned when an update was staged is still available
+ * when the digest pass runs — regardless of whether the read cache has since evicted it.
+ *
+ * NOTE: memory shape — one cloned base block per update-carrying block, held from the first
+ * update staged for it until the owning tracker's next reset(). Peak retention is proportional
+ * to the transaction's own write footprint (the same set of blocks whose ids and ops the commit
+ * request already carries), and every transaction boundary reclaims it via reset(). */
+export class BasePins {
+	private pins = new Map<BlockId, PinnedBase>();
+	/** The base source every `rev`/`gen` in here was read from — see {@link bindAuthority}. */
+	private authority: unknown;
+	private bound = false;
+
+	/** Claim this store for `source`, the base source at the bottom of the binding tracker's stack.
+	 * A fresh store binds; a store being joined must present the same source. Both `rev` and `gen`
+	 * are counters private to one source — a second CacheSource numbers generations from 0 for the
+	 * same ids — so a store shared across two sources would let a pin taken from one pass the
+	 * freshness check against the other and declare the wrong content. Throwing here makes that
+	 * mistake impossible to make quietly. */
+	bindAuthority(source: unknown): void {
+		if (!this.bound) {
+			this.authority = source;
+			this.bound = true;
+		} else if (this.authority !== source) {
+			throw new Error('BasePins shared between trackers over different base sources: pin revisions and generations are per-source counters and are not comparable across them.');
+		}
+	}
+
+	get(id: BlockId): PinnedBase | undefined {
+		return this.pins.get(id);
+	}
+
+	set(id: BlockId, pin: PinnedBase): void {
+		this.pins.set(id, pin);
+	}
+
+	delete(id: BlockId): void {
+		this.pins.delete(id);
+	}
+
+	/** Drop every pin whose id is not in `keep`. Called from Tracker.reset with the ids still
+	 * carried by the new transforms' `updates`, so a rollback keeps its pins and a plain reset
+	 * clears them. */
+	retainOnly(keep: Iterable<BlockId>): void {
+		const keepSet = new Set(keep);
+		for (const id of this.pins.keys()) {
+			if (!keepSet.has(id)) this.pins.delete(id);
+		}
+	}
+
+	/** Copy every entry of `other` in, overwriting. Called from Atomic.commit so pins captured
+	 * inside the atomic survive into the parent tracker's store. Overwriting is deliberate: the
+	 * atomic's pin is the later observation of the same base chain, and the use-time freshness
+	 * check re-validates it anyway. */
+	adopt(other: BasePins): void {
+		if (other.authority !== this.authority) {
+			throw new Error('BasePins.adopt across different base sources: pin revisions and generations are not comparable across them.');
+		}
+		for (const [id, pin] of other.pins) {
+			this.pins.set(id, pin);
+		}
+	}
+
+	get size(): number {
+		return this.pins.size;
+	}
+}

package/src/transform/digest.ts

@@ -8,28 +8,23 @@ 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).
+ * from the source. An id whose base is neither pinned nor cached is omitted rather than fetched —
+ * an omitted id never fails the commit, it only forfeits what a declaration buys (an undeclared
+ * block retains no durable `BlockCommitProof` and so can never GAIN a holder by push; stated once,
+ * canonically, at {@link CommitRequest.blockDigests} in `network/struct.ts`).
  * 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.
+// NOTE: declarability follows what the transaction read and staged, not read-cache residency. Each
+// updated block's committed base is pinned at the moment its update is staged (Tracker.update ->
+// BasePins) and held until the transaction boundary, so a commit of any size declares 100% of the
+// blocks whose bases it read — verified through the production path (`Collection.act`/`sync`) in
+// `test/digest-cache-coverage.spec.ts` at 2x and 4x the cache capacity. The two remaining
+// legitimate omissions: a delete (materializes to nothing) and a blind update to a block this node
+// never read whose base is not cached (nothing to declare, and a commit must never pay a network
+// read to describe itself). Residual gap: read-far-then-update — a block read, then evicted by
+// 128+ other reads, and only then updated, finds nothing to pin; see the NOTE at the pin site in
+// `tracker.ts`.
 export async function computeBlockContentDigests<T extends IBlock>(
 	tracker: Tracker<T>,
 	blockIds: BlockId[]