@optimystic/db-core 0.13.4 → 0.14.0

package/src/cohort-topic/wire/validate.ts

@@ -0,0 +1,478 @@
+/**
+ * Cohort-topic substrate — per-message structural validation.
+ *
+ * Each validator narrows an already-parsed `unknown` (the output of `JSON.parse` on a decoded
+ * frame) to a concrete V1 interface, throwing {@link CohortWireError} on any structural defect:
+ * missing required field, wrong `v`, out-of-enum discriminant, a byte field that does not decode
+ * as base64url, or an out-of-range numeric. Validators never return partial data — they either
+ * narrow cleanly or throw.
+ */
+
+import { b64urlToBytes } from "./codec.js";
+import type {
+	CohortGossipV1,
+	CohortTopicSummary,
+	DemotionNoticeV1,
+	GossipRecordRefV1,
+	GossipRecordV1,
+	MembershipCertV1,
+	PromotionNoticeV1,
+	RegisterReplyV1,
+	RegisterResult,
+	RegisterV1,
+	RenewReplyV1,
+	RenewV1,
+	SignKind,
+	SignRequestV1,
+	SignReplyV1,
+	TopicTrafficV1,
+} from "./types.js";
+
+/** Thrown for any malformed, oversized, or structurally invalid cohort-topic frame. */
+export class CohortWireError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "CohortWireError";
+	}
+}
+
+function fail(message: string): never {
+	throw new CohortWireError(message);
+}
+
+/** Set `obj[key]` only when `value` is defined — keeps absent optionals off the decoded object. */
+function assignDefined<T extends object, K extends keyof T>(obj: T, key: K, value: T[K] | undefined): void {
+	if (value !== undefined) {
+		obj[key] = value;
+	}
+}
+
+function asObject(value: unknown, what: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		fail(`${what}: expected an object`);
+	}
+	return value as Record<string, unknown>;
+}
+
+function requireV1(obj: Record<string, unknown>, what: string): void {
+	if (obj["v"] !== 1) {
+		fail(`${what}: expected v === 1, got ${JSON.stringify(obj["v"])}`);
+	}
+}
+
+function reqString(obj: Record<string, unknown>, key: string, what: string): string {
+	const value = obj[key];
+	if (typeof value !== "string") {
+		fail(`${what}: field "${key}" must be a string`);
+	}
+	return value;
+}
+
+function optString(obj: Record<string, unknown>, key: string, what: string): string | undefined {
+	const value = obj[key];
+	if (value === undefined) {
+		return undefined;
+	}
+	if (typeof value !== "string") {
+		fail(`${what}: field "${key}" must be a string when present`);
+	}
+	return value;
+}
+
+function reqFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number {
+	const value = obj[key];
+	if (typeof value !== "number" || !Number.isFinite(value)) {
+		fail(`${what}: field "${key}" must be a finite number`);
+	}
+	return value;
+}
+
+function optFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number | undefined {
+	const value = obj[key];
+	if (value === undefined) {
+		return undefined;
+	}
+	if (typeof value !== "number" || !Number.isFinite(value)) {
+		fail(`${what}: field "${key}" must be a finite number when present`);
+	}
+	return value;
+}
+
+function reqBool(obj: Record<string, unknown>, key: string, what: string): boolean {
+	const value = obj[key];
+	if (typeof value !== "boolean") {
+		fail(`${what}: field "${key}" must be a boolean`);
+	}
+	return value;
+}
+
+function optBool(obj: Record<string, unknown>, key: string, what: string): boolean | undefined {
+	const value = obj[key];
+	if (value === undefined) {
+		return undefined;
+	}
+	if (typeof value !== "boolean") {
+		fail(`${what}: field "${key}" must be a boolean when present`);
+	}
+	return value;
+}
+
+function reqStringArray(obj: Record<string, unknown>, key: string, what: string): string[] {
+	const value = obj[key];
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+		fail(`${what}: field "${key}" must be an array of strings`);
+	}
+	return value as string[];
+}
+
+function optStringArray(obj: Record<string, unknown>, key: string, what: string): string[] | undefined {
+	if (obj[key] === undefined) {
+		return undefined;
+	}
+	return reqStringArray(obj, key, what);
+}
+
+function tier(value: number, what: string): number {
+	if (!Number.isInteger(value) || value < 0 || value > 3) {
+		fail(`${what}: tier must be an integer in 0..3, got ${value}`);
+	}
+	return value;
+}
+
+/** Assert a base64url string decodes cleanly; returns it unchanged. */
+function b64urlField(value: string, key: string, what: string): string {
+	try {
+		b64urlToBytes(value);
+	} catch {
+		fail(`${what}: field "${key}" is not valid base64url`);
+	}
+	return value;
+}
+
+function reqEnum<T extends string>(obj: Record<string, unknown>, key: string, allowed: readonly T[], what: string): T {
+	const value = obj[key];
+	if (typeof value !== "string" || !(allowed as readonly string[]).includes(value)) {
+		fail(`${what}: field "${key}" must be one of ${allowed.join(" | ")}`);
+	}
+	return value as T;
+}
+
+const REGISTER_RESULTS: readonly RegisterResult[] = [
+	"accepted",
+	"no_state",
+	"promoted",
+	"unwilling_member",
+	"unwilling_cohort",
+];
+
+export function validateRegisterV1(value: unknown): RegisterV1 {
+	const what = "RegisterV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	const out: RegisterV1 = {
+		v: 1,
+		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
+		tier: tier(reqFiniteNumber(obj, "tier", what), what),
+		treeTier: reqFiniteNumber(obj, "treeTier", what),
+		participantCoord: b64urlField(reqString(obj, "participantCoord", what), "participantCoord", what),
+		ttl: reqFiniteNumber(obj, "ttl", what),
+		timestamp: reqFiniteNumber(obj, "timestamp", what),
+		correlationId: b64urlField(reqString(obj, "correlationId", what), "correlationId", what),
+		signature: b64urlField(reqString(obj, "signature", what), "signature", what),
+	};
+	const bootstrap = optBool(obj, "bootstrap", what);
+	if (bootstrap !== undefined) {
+		out.bootstrap = bootstrap;
+	}
+	const probe = optBool(obj, "probe", what);
+	if (probe !== undefined) {
+		out.probe = probe;
+	}
+	const appPayload = optString(obj, "appPayload", what);
+	if (appPayload !== undefined) {
+		out.appPayload = b64urlField(appPayload, "appPayload", what);
+	}
+	// Bootstrap-evidence envelope (base64url; present only on a `bootstrap: true` register). A non-string
+	// is rejected as malformed; an empty string is treated as absent so it normalizes to the same signed
+	// image placeholder as a missing field (see `registerSigningPayload`'s `normalizeEvidence`).
+	const bootstrapEvidence = optString(obj, "bootstrapEvidence", what);
+	if (bootstrapEvidence !== undefined && bootstrapEvidence !== "") {
+		out.bootstrapEvidence = b64urlField(bootstrapEvidence, "bootstrapEvidence", what);
+	}
+	return out;
+}
+
+function validateTopicTrafficV1(value: unknown): TopicTrafficV1 {
+	const what = "TopicTrafficV1";
+	const obj = asObject(value, what);
+	return {
+		windowSeconds: reqFiniteNumber(obj, "windowSeconds", what),
+		arrivalsPerMin: reqFiniteNumber(obj, "arrivalsPerMin", what),
+		queriesPerMin: reqFiniteNumber(obj, "queriesPerMin", what),
+		directParticipants: reqFiniteNumber(obj, "directParticipants", what),
+		childCohortCount: reqFiniteNumber(obj, "childCohortCount", what),
+	};
+}
+
+export function validateRegisterReplyV1(value: unknown): RegisterReplyV1 {
+	const what = "RegisterReplyV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	const out: RegisterReplyV1 = {
+		v: 1,
+		result: reqEnum(obj, "result", REGISTER_RESULTS, what),
+	};
+	assignDefined(out, "primary", optString(obj, "primary", what));
+	assignDefined(out, "backups", optStringArray(obj, "backups", what));
+	const cohortEpoch = optString(obj, "cohortEpoch", what);
+	if (cohortEpoch !== undefined) {
+		out.cohortEpoch = b64urlField(cohortEpoch, "cohortEpoch", what);
+	}
+	assignDefined(out, "cohortMembers", optStringArray(obj, "cohortMembers", what));
+	if (obj["topicTraffic"] !== undefined) {
+		out.topicTraffic = validateTopicTrafficV1(obj["topicTraffic"]);
+	}
+	assignDefined(out, "targetTier", optFiniteNumber(obj, "targetTier", what));
+	assignDefined(out, "candidateMembers", optStringArray(obj, "candidateMembers", what));
+	assignDefined(out, "retryAfterMs", optFiniteNumber(obj, "retryAfterMs", what));
+	assignDefined(out, "reason", optString(obj, "reason", what));
+	return out;
+}
+
+export function validateRenewV1(value: unknown): RenewV1 {
+	const what = "RenewV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	const out: RenewV1 = {
+		v: 1,
+		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
+		participantId: reqString(obj, "participantId", what),
+		correlationId: b64urlField(reqString(obj, "correlationId", what), "correlationId", what),
+		timestamp: reqFiniteNumber(obj, "timestamp", what),
+		signature: b64urlField(reqString(obj, "signature", what), "signature", what),
+	};
+	assignDefined(out, "reattach", optBool(obj, "reattach", what));
+	assignDefined(out, "withdraw", optBool(obj, "withdraw", what));
+	return out;
+}
+
+export function validateRenewReplyV1(value: unknown): RenewReplyV1 {
+	const what = "RenewReplyV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	const out: RenewReplyV1 = {
+		v: 1,
+		result: reqEnum(obj, "result", ["ok", "unknown_registration", "primary_moved", "withdrawn"] as const, what),
+	};
+	assignDefined(out, "newPrimary", optString(obj, "newPrimary", what));
+	assignDefined(out, "newBackups", optStringArray(obj, "newBackups", what));
+	const cohortEpoch = optString(obj, "cohortEpoch", what);
+	if (cohortEpoch !== undefined) {
+		out.cohortEpoch = b64urlField(cohortEpoch, "cohortEpoch", what);
+	}
+	return out;
+}
+
+export function validatePromotionNoticeV1(value: unknown): PromotionNoticeV1 {
+	const what = "PromotionNoticeV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	return {
+		v: 1,
+		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
+		fromTier: tier(reqFiniteNumber(obj, "fromTier", what), what),
+		toTier: tier(reqFiniteNumber(obj, "toTier", what), what),
+		effectiveAt: reqFiniteNumber(obj, "effectiveAt", what),
+		thresholdSig: b64urlField(reqString(obj, "thresholdSig", what), "thresholdSig", what),
+		signers: reqStringArray(obj, "signers", what),
+		cohortEpoch: b64urlField(reqString(obj, "cohortEpoch", what), "cohortEpoch", what),
+	};
+}
+
+export function validateDemotionNoticeV1(value: unknown): DemotionNoticeV1 {
+	const what = "DemotionNoticeV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	return {
+		v: 1,
+		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
+		tier: tier(reqFiniteNumber(obj, "tier", what), what),
+		parentCohortCoord: b64urlField(reqString(obj, "parentCohortCoord", what), "parentCohortCoord", what),
+		effectiveAt: reqFiniteNumber(obj, "effectiveAt", what),
+		thresholdSig: b64urlField(reqString(obj, "thresholdSig", what), "thresholdSig", what),
+		signers: reqStringArray(obj, "signers", what),
+		cohortEpoch: b64urlField(reqString(obj, "cohortEpoch", what), "cohortEpoch", what),
+	};
+}
+
+function validateCohortTopicSummary(value: unknown): CohortTopicSummary {
+	const what = "CohortTopicSummary";
+	const obj = asObject(value, what);
+	return {
+		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
+		tier: tier(reqFiniteNumber(obj, "tier", what), what),
+		directParticipants: reqFiniteNumber(obj, "directParticipants", what),
+		arrivalsPerMin: reqFiniteNumber(obj, "arrivalsPerMin", what),
+		queriesPerMin: reqFiniteNumber(obj, "queriesPerMin", what),
+		promoted: reqBool(obj, "promoted", what),
+		childCohortCount: reqFiniteNumber(obj, "childCohortCount", what),
+	};
+}
+
+function validateGossipRecordV1(value: unknown): GossipRecordV1 {
+	const what = "GossipRecordV1";
+	const obj = asObject(value, what);
+	const out: GossipRecordV1 = {
+		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
+		participantId: b64urlField(reqString(obj, "participantId", what), "participantId", what),
+		tier: tier(reqFiniteNumber(obj, "tier", what), what),
+		primary: b64urlField(reqString(obj, "primary", what), "primary", what),
+		backups: reqStringArray(obj, "backups", what).map((b) => b64urlField(b, "backups", what)),
+		attachedAt: reqFiniteNumber(obj, "attachedAt", what),
+		lastPing: reqFiniteNumber(obj, "lastPing", what),
+		ttl: reqFiniteNumber(obj, "ttl", what),
+	};
+	const appState = optString(obj, "appState", what);
+	if (appState !== undefined) {
+		out.appState = b64urlField(appState, "appState", what);
+	}
+	return out;
+}
+
+function validateGossipRecordRefV1(value: unknown): GossipRecordRefV1 {
+	const what = "GossipRecordRefV1";
+	const obj = asObject(value, what);
+	return {
+		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
+		participantId: b64urlField(reqString(obj, "participantId", what), "participantId", what),
+	};
+}
+
+/** `willingnessBits` carries exactly 4 bits (T0..T3) as a single hex nibble. */
+const WILLINGNESS_RE = /^[0-9a-fA-F]$/;
+
+export function validateCohortGossipV1(value: unknown): CohortGossipV1 {
+	const what = "CohortGossipV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	const willingnessBits = reqString(obj, "willingnessBits", what);
+	if (!WILLINGNESS_RE.test(willingnessBits)) {
+		fail(`${what}: field "willingnessBits" must be a single hex nibble (4 bits)`);
+	}
+	const loadBuckets = obj["loadBuckets"];
+	if (!Array.isArray(loadBuckets) || loadBuckets.length !== 4) {
+		fail(`${what}: field "loadBuckets" must be an array of length 4`);
+	}
+	for (const bucket of loadBuckets) {
+		if (typeof bucket !== "number" || !Number.isInteger(bucket) || bucket < 0 || bucket > 7) {
+			fail(`${what}: each loadBuckets entry must be an integer in 0..7`);
+		}
+	}
+	const summaries = obj["topicSummaries"];
+	if (!Array.isArray(summaries)) {
+		fail(`${what}: field "topicSummaries" must be an array`);
+	}
+	const out: CohortGossipV1 = {
+		v: 1,
+		fromMember: reqString(obj, "fromMember", what),
+		coord: b64urlField(reqString(obj, "coord", what), "coord", what),
+		cohortEpoch: b64urlField(reqString(obj, "cohortEpoch", what), "cohortEpoch", what),
+		willingnessBits,
+		loadBuckets: loadBuckets as number[],
+		windowSeconds: reqFiniteNumber(obj, "windowSeconds", what),
+		topicSummaries: summaries.map(validateCohortTopicSummary),
+		timestamp: reqFiniteNumber(obj, "timestamp", what),
+		signature: b64urlField(reqString(obj, "signature", what), "signature", what),
+	};
+	const records = obj["records"];
+	if (records !== undefined) {
+		if (!Array.isArray(records)) {
+			fail(`${what}: field "records" must be an array when present`);
+		}
+		out.records = records.map(validateGossipRecordV1);
+	}
+	const evicted = obj["evicted"];
+	if (evicted !== undefined) {
+		if (!Array.isArray(evicted)) {
+			fail(`${what}: field "evicted" must be an array when present`);
+		}
+		out.evicted = evicted.map(validateGossipRecordRefV1);
+	}
+	return out;
+}
+
+const SIGN_KINDS: readonly SignKind[] = ["membership", "promotion", "demotion", "rotation"];
+
+export function validateSignRequestV1(value: unknown): SignRequestV1 {
+	const what = "SignRequestV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	return {
+		v: 1,
+		kind: reqEnum(obj, "kind", SIGN_KINDS, what),
+		coord: b64urlField(reqString(obj, "coord", what), "coord", what),
+		cohortEpoch: b64urlField(reqString(obj, "cohortEpoch", what), "cohortEpoch", what),
+		payload: b64urlField(reqString(obj, "payload", what), "payload", what),
+	};
+}
+
+export function validateSignReplyV1(value: unknown): SignReplyV1 {
+	const what = "SignReplyV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	// Discriminated by `refused`: a refusal carries a reason; an endorsement carries signer + signature.
+	if (obj["refused"] !== undefined) {
+		if (obj["refused"] !== true) {
+			fail(`${what}: field "refused" must be true when present`);
+		}
+		return { v: 1, refused: true, reason: reqString(obj, "reason", what) };
+	}
+	return {
+		v: 1,
+		signer: b64urlField(reqString(obj, "signer", what), "signer", what),
+		signature: b64urlField(reqString(obj, "signature", what), "signature", what),
+	};
+}
+
+export function validateMembershipCertV1(value: unknown): MembershipCertV1 {
+	const what = "MembershipCertV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	const out: MembershipCertV1 = {
+		v: 1,
+		cohortCoord: b64urlField(reqString(obj, "cohortCoord", what), "cohortCoord", what),
+		cohortEpoch: b64urlField(reqString(obj, "cohortEpoch", what), "cohortEpoch", what),
+		members: reqStringArray(obj, "members", what),
+		stabilizedAt: reqFiniteNumber(obj, "stabilizedAt", what),
+		thresholdSig: b64urlField(reqString(obj, "thresholdSig", what), "thresholdSig", what),
+		signers: reqStringArray(obj, "signers", what),
+	};
+	const attestation = optString(obj, "fretAttestation", what);
+	if (attestation !== undefined) {
+		out.fretAttestation = b64urlField(attestation, "fretAttestation", what);
+	}
+	validateRotationAttestation(obj, out, what);
+	return out;
+}
+
+/**
+ * Validate the optional rotation attestation as an all-or-nothing group: either all three of
+ * `prevEpoch`/`rotationSig`/`rotationSigners` are present (and well-formed) or all are absent. A
+ * partial set is a {@link CohortWireError}. `rotationSigners` is validated only as a string array (its
+ * elements are decoded per-element later, mirroring `signers`).
+ */
+function validateRotationAttestation(obj: Record<string, unknown>, out: MembershipCertV1, what: string): void {
+	const prevEpoch = optString(obj, "prevEpoch", what);
+	const rotationSig = optString(obj, "rotationSig", what);
+	const rotationSigners = optStringArray(obj, "rotationSigners", what);
+	const presentCount = [prevEpoch, rotationSig, rotationSigners].filter((v) => v !== undefined).length;
+	if (presentCount === 0) {
+		return;
+	}
+	if (presentCount !== 3) {
+		fail(`${what}: rotation attestation requires all of prevEpoch, rotationSig, rotationSigners — or none`);
+	}
+	out.prevEpoch = b64urlField(prevEpoch!, "prevEpoch", what);
+	out.rotationSig = b64urlField(rotationSig!, "rotationSig", what);
+	out.rotationSigners = rotationSigners!;
+}

package/src/collection/collection.ts

@@ -1,4 +1,4 @@
-import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, BlockStore } from "../index.js";
+import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, BlockStore, Transforms } from "../index.js";
 import { Log, Atomic, Tracker, copyTransforms, CacheSource, isTransformsEmpty, TransactorSource } from "../index.js";
 import type { CollectionHeaderBlock, CollectionId, ICollection } from "./index.js";
 import type { ReadDependency } from "../transaction/transaction.js";
@@ -20,6 +20,15 @@ export type CollectionInitOptions<TAction> = {
 	filterConflict?: (action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined
 }
 
+/** A point-in-time copy of a collection's staged (un-synced) state, produced by
+ * {@link Collection.snapshotPending} and consumed by {@link Collection.restorePending}. */
+export interface CollectionSnapshot<TAction> {
+	/** Deep-cloned tracker transforms at snapshot time. */
+	transforms: Transforms;
+	/** Pending actions queued at snapshot time. */
+	pending: Action<TAction>[];
+}
+
 export class Collection<TAction> implements ICollection<TAction> {
 	private pending: Action<TAction>[] = [];
 	private readonly latchId: string;
@@ -127,6 +136,21 @@ export class Collection<TAction> implements ICollection<TAction> {
 			anyConflicts = anyConflicts || this.tracker.conflicts(new Set(entry.blockIds)).length > 0;
 		}
 
+		// React to durable invalidations that landed since we last synced. getFrom intentionally skips
+		// invalidation entries (they are not pending/committed actions), so surface them separately: an
+		// invalidation reverted committed content this client may have read, so treat it like a stale
+		// read — drop the reverted blocks from the read cache and replay pending work against the reverted
+		// base (docs/right-is-right.md §Client notification). De-duped across cascade children by reverted
+		// block; over-inclusive by design (over-invalidation just resubmits — it never wrongly retains).
+		const invalidations = log ? await log.getInvalidationsFrom(actionContext?.rev ?? 0) : [];
+		if (invalidations.length > 0) {
+			const revertedBlockIds = [...new Set(invalidations.flatMap(inv => inv.reverted.map(r => r.blockId)))];
+			this.sourceCache.clear(revertedBlockIds);
+			if (this.pending.length > 0) {
+				anyConflicts = true;
+			}
+		}
+
 		// On conflicts, clear related caching and block-tracking and replay logical operations
 		if (anyConflicts) {
 			await this.replayActions();
@@ -136,6 +160,74 @@ export class Collection<TAction> implements ICollection<TAction> {
 		this.source.actionContext = latest?.context;
 	}
 
+	/** Capture the current staged state — tracker transforms plus the pending
+	 * action queue — so it can be restored later via {@link restorePending}.
+	 *
+	 * Use to bracket a unit of staged DML that may need to be rolled back. Unlike
+	 * a blanket "reset to empty", restoring this snapshot preserves any structural
+	 * baseline that predates the staged DML — most importantly a brand-new
+	 * collection's header/root blocks, which live in the tracker (uncommitted)
+	 * until the first sync. Resetting such a collection to empty would leave it
+	 * unreadable; restoring the snapshot returns it to its prior (readable) state.
+	 *
+	 * The returned snapshot is deep-cloned and independent of subsequent mutations.
+	 * Synchronous and latch-free: intended to bracket transaction-scoped staging,
+	 * when no concurrent act/sync is in flight. */
+	snapshotPending(): CollectionSnapshot<TAction> {
+		return { transforms: copyTransforms(this.tracker.transforms), pending: [...this.pending] };
+	}
+
+	/** Restore the staged state captured by {@link snapshotPending}, discarding any
+	 * mutations staged since. Reads through the collection then observe exactly the
+	 * snapshot state again; storage is untouched because nothing was ever synced. */
+	restorePending(snapshot: CollectionSnapshot<TAction>): void {
+		this.tracker.reset(copyTransforms(snapshot.transforms));
+		this.pending = [...snapshot.pending];
+	}
+
+	/** A read-only {@link Tracker} over this collection's committed source cache,
+	 * seeded with a (deep-copied) set of pre-transaction transforms. Reads through it
+	 * observe committed state plus exactly those transforms — and crucially NOT the
+	 * mutations staged into this collection's live tracker afterward. Used to build a
+	 * committed read view (see {@link Tree.readView}) that excludes a transaction's
+	 * own in-flight rows. The returned tracker shares the source cache (committed
+	 * blocks) but has its own independent transform set; it is never sync()'d. */
+	createReadTracker(transforms: Transforms): Tracker<IBlock> {
+		return new Tracker(this.sourceCache, copyTransforms(transforms));
+	}
+
+	/** The staged (not-yet-synced) actions queued by {@link act}.
+	 *
+	 * Exposed so a {@link TransactionCoordinator} can append them to the log at
+	 * commit time — mirroring what {@link sync} does internally — when the actions
+	 * were staged directly into this collection (e.g. through a Tree's stage())
+	 * rather than applied via the coordinator's own action path. */
+	getPendingActions(): Action<TAction>[] {
+		return this.pending;
+	}
+
+	/** Drop the staged actions after they have been committed through a
+	 * coordinator. Counterpart to {@link getPendingActions}; {@link sync} clears
+	 * its own pending inline, so this is only needed when commit was orchestrated
+	 * externally. */
+	clearPendingActions(): void {
+		this.pending = [];
+	}
+
+	/** Fold a just-committed set of transforms into this collection's read cache
+	 * so subsequent reads (and stages) through THIS instance observe the committed
+	 * state, mirroring what {@link sync} does inline after a successful transact.
+	 *
+	 * Needed when commit was orchestrated externally (a coordinator): the tracker
+	 * is reset to empty, but the cache still holds the pre-commit blocks. Without
+	 * this, a collection that already had committed state (e.g. a pre-synced index
+	 * tree, or any collection on its second commit) keeps serving the stale prior
+	 * revision because {@link update} sees its rev is already current and refetches
+	 * nothing. Call BEFORE resetting the tracker (the transforms are read live). */
+	applyCommittedToCache(transforms: Transforms): void {
+		this.sourceCache.transformCache(transforms);
+	}
+
 	/** Push our pending actions to the transactor */
 	async sync() {
 		const release = await Latches.acquire(this.latchId);