@optimystic/db-core 0.13.5 → 0.14.0

package/src/reactivity/topic-anchor.ts

@@ -0,0 +1,71 @@
+/**
+ * Reactivity — rotating, tail-anchored topic.
+ *
+ * Transcribed from `docs/reactivity.md` §Anchor:
+ *
+ * ```
+ * topicId(collection C, tail T) = H(T.blockId ‖ "reactivity")
+ * ```
+ *
+ * Unlike matchmaking (whose anchor is a stable `(kind, label)`), the reactivity anchor **rotates** with
+ * the collection's tail block: when the tail fills and a new tail block is born, `topicId` changes and
+ * the cohort-topic layer treats it as an entirely new topic. The whole-tree migration that follows is
+ * the rotation ticket's concern; this module owns only the pure derivation.
+ *
+ * The resulting `topicId` is fed verbatim into cohort-topic tier addressing (`coord_d(self, topicId)`),
+ * so it is derived with the **same** {@link IRingHash} primitive cohort-topic uses for `coord_d` input —
+ * db-core's own SHA-256 truncated to the ring width, **not** a FRET import. The trailing `"reactivity"`
+ * literal domain-separates the reactivity tree from any other application anchoring on the same tail id.
+ *
+ * Concatenation is delimiter-free, exactly as the spec writes it; the constant suffix is unambiguous
+ * because no tail-id byte string can alias a `(tailId, "reactivity")` pair of a different length.
+ *
+ * `reactivityTopicId` is the small pure helper the ticket asks for once and the rotation ticket
+ * ([reactivity-rotation-backpressure-policy]) reuses per-emission — define it here, not at the call site.
+ */
+
+import { createRingHash } from "../cohort-topic/ring-hash.js";
+import type { IRingHash } from "../cohort-topic/ports.js";
+
+/** Domain-separation suffix mixed into every reactivity anchor. */
+const REACTIVITY_SUFFIX = "reactivity";
+
+const utf8 = new TextEncoder();
+
+/**
+ * `H(tailId ‖ "reactivity")` over the injected ring hash — the cohort-topic `topicId` for the
+ * reactivity tree anchored on `tailId` (the collection's current tail block id, as raw bytes).
+ *
+ * The shared helper consumed by subscriber attachment, origination, and (per-emission) the rotation
+ * ticket. `hash` defaults to db-core's own 256-bit SHA-256, byte-identical to the cohort-topic host's.
+ */
+export function reactivityTopicId(tailId: Uint8Array, hash: IRingHash = createRingHash()): Uint8Array {
+	const suffixBytes = utf8.encode(REACTIVITY_SUFFIX);
+	const input = new Uint8Array(tailId.length + suffixBytes.length);
+	input.set(tailId, 0);
+	input.set(suffixBytes, tailId.length);
+	return hash.H(input);
+}
+
+/** Derives the rotating `topicId` for a collection's current tail. */
+export interface ReactivityTopicAnchor {
+	/** `H(tailId ‖ "reactivity")` for the given tail block id (bytes). */
+	topicId(tailId: Uint8Array): Uint8Array;
+}
+
+class HashReactivityTopicAnchor implements ReactivityTopicAnchor {
+	constructor(private readonly hash: IRingHash) {}
+
+	topicId(tailId: Uint8Array): Uint8Array {
+		return reactivityTopicId(tailId, this.hash);
+	}
+}
+
+/**
+ * Build a {@link ReactivityTopicAnchor} over the injected hash. db-p2p passes the same {@link IRingHash}
+ * it binds to FRET's `RING_BITS` so the anchor and cohort-topic routing keys line up; the default
+ * constructs db-core's own {@link createRingHash} (256-bit SHA-256).
+ */
+export function createReactivityTopicAnchor(hash: IRingHash = createRingHash()): ReactivityTopicAnchor {
+	return new HashReactivityTopicAnchor(hash);
+}

package/src/reactivity/verify.ts

@@ -0,0 +1,73 @@
+/**
+ * Reactivity — subscriber/forwarder notification verification seam
+ * (`docs/reactivity.md` §Propagation, §Delivery, §Authentication).
+ *
+ * A forwarder and a subscriber both verify a notification's threshold signature against the **tail
+ * cohort's** `MembershipCertV1` before trusting it — forwarders never re-sign, so the same end-to-end
+ * signature is verified regardless of hop count. The standard cohort-topic membership-snapshot path
+ * ({@link MembershipVerifier}) already provides the **one fetch-and-retry** on a stale/missing cached
+ * cert, so this module is a thin adapter: derive the tail cohort's `coord_0(_, topicId)` from the
+ * notification's `tailId`, then hand `(signers, coord, tier, digest, sig)` to the verifier.
+ *
+ * The signed payload is the commit `digest` (the commit cert's threshold signature is over the commit
+ * hash — see {@link import("./notification.js").buildNotificationV1}). `signers` arrive base64url-encoded
+ * as the cohort member-id bytes the verifier compares against `cert.members`; a custom `signersToBytes`
+ * seam is exposed for bindings that carry signers in a different encoding.
+ */
+
+import { createTierAddressing, DEFAULT_FANOUT } from "../cohort-topic/addressing.js";
+import { createRingHash } from "../cohort-topic/ring-hash.js";
+import { b64urlToBytes } from "../cohort-topic/wire/codec.js";
+import { Tier } from "../cohort-topic/tiers.js";
+import type { IRingHash } from "../cohort-topic/ports.js";
+import type { MembershipVerifier, VerifyResult } from "../cohort-topic/membership/verifier.js";
+import { reactivityTopicId } from "./topic-anchor.js";
+import type { NotificationV1 } from "./wire.js";
+
+/** Verifies a {@link NotificationV1}'s threshold signature against the tail cohort's membership. */
+export interface NotificationVerifier {
+	/** `"verified"` iff `sig` is a valid `≥ minSigs` cohort signature over the commit digest. */
+	verify(n: NotificationV1): Promise<VerifyResult>;
+}
+
+/** Construction inputs for the default {@link NotificationVerifier}. */
+export interface NotificationVerifierDeps {
+	/** The cohort-topic participant-side membership verifier (owns the one fetch-and-retry). */
+	readonly verifier: MembershipVerifier;
+	/** Ring hash for `topicId` / `coord_0` derivation. Default db-core 256-bit SHA-256. */
+	readonly hash?: IRingHash;
+	/** Fan-out `F` for tier addressing. Default {@link DEFAULT_FANOUT}. */
+	readonly fanout?: number;
+	/** Reactivity runs at T3; overridable for tests. */
+	readonly tier?: Tier;
+	/** Map a wire signer string to the verifier's member-id bytes. Default base64url decode. */
+	readonly signersToBytes?: (signer: string) => Uint8Array;
+}
+
+class MembershipNotificationVerifier implements NotificationVerifier {
+	private readonly addressing: ReturnType<typeof createTierAddressing>;
+	private readonly hash: IRingHash;
+	private readonly tier: Tier;
+	private readonly signersToBytes: (signer: string) => Uint8Array;
+
+	constructor(private readonly deps: NotificationVerifierDeps) {
+		this.hash = deps.hash ?? createRingHash();
+		this.addressing = createTierAddressing(this.hash, deps.fanout ?? DEFAULT_FANOUT);
+		this.tier = deps.tier ?? Tier.T3;
+		this.signersToBytes = deps.signersToBytes ?? b64urlToBytes;
+	}
+
+	async verify(n: NotificationV1): Promise<VerifyResult> {
+		const topicId = reactivityTopicId(b64urlToBytes(n.tailId), this.hash);
+		const expectedCoord = this.addressing.coord0(topicId);
+		const signers = n.signers.map(this.signersToBytes);
+		const payload = b64urlToBytes(n.digest);
+		const sig = b64urlToBytes(n.sig);
+		return this.deps.verifier.verifyMessage(signers, expectedCoord, this.tier, payload, sig);
+	}
+}
+
+/** Build the default {@link NotificationVerifier} over the cohort-topic {@link MembershipVerifier}. */
+export function createNotificationVerifier(deps: NotificationVerifierDeps): NotificationVerifier {
+	return new MembershipNotificationVerifier(deps);
+}

package/src/reactivity/wire-validate.ts

@@ -0,0 +1,87 @@
+/**
+ * Reactivity — shared wire-validation primitives.
+ *
+ * The reactivity message codecs ({@link import("./wire.js")}, {@link import("./push-state.js")},
+ * {@link import("./backfill.js")}, {@link import("./resume.js")}) all decode untrusted JSON into
+ * validated V1 shapes with the same structural checks. Those primitives live here so each codec module
+ * narrows fields the same way (DRY) — every helper throws {@link CohortWireError} on a defect, matching
+ * the cohort-topic wire conventions (base64url byte fields, finite/integer numbers, `v: 1`).
+ */
+
+import { b64urlToBytes } from "../cohort-topic/wire/codec.js";
+import { CohortWireError } from "../cohort-topic/wire/validate.js";
+
+/** Throw a {@link CohortWireError} with `message`. */
+export function failWire(message: string): never {
+	throw new CohortWireError(message);
+}
+
+/** Narrow `value` to a plain object (not null, not an array), or throw. */
+export function asObject(value: unknown, what: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		failWire(`${what}: expected an object`);
+	}
+	return value as Record<string, unknown>;
+}
+
+/** Require `obj.v === 1`. */
+export function requireV1(obj: Record<string, unknown>, what: string): void {
+	if (obj["v"] !== 1) {
+		failWire(`${what}: expected v === 1, got ${JSON.stringify(obj["v"])}`);
+	}
+}
+
+/** Require `obj[key]` to be a string; returns it. */
+export function reqString(obj: Record<string, unknown>, key: string, what: string): string {
+	const value = obj[key];
+	if (typeof value !== "string") {
+		failWire(`${what}: field "${key}" must be a string`);
+	}
+	return value;
+}
+
+/** Require `obj[key]` to be a boolean; returns it. */
+export function reqBoolean(obj: Record<string, unknown>, key: string, what: string): boolean {
+	const value = obj[key];
+	if (typeof value !== "boolean") {
+		failWire(`${what}: field "${key}" must be a boolean`);
+	}
+	return value;
+}
+
+/** Require `obj[key]` to be a finite number; returns it. */
+export function reqFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number {
+	const value = obj[key];
+	if (typeof value !== "number" || !Number.isFinite(value)) {
+		failWire(`${what}: field "${key}" must be a finite number`);
+	}
+	return value;
+}
+
+/** Require `obj[key]` to be an integer `>= min` (and `<= max` when supplied); returns it. */
+export function reqIntInRange(obj: Record<string, unknown>, key: string, what: string, min: number, max?: number): number {
+	const value = reqFiniteNumber(obj, key, what);
+	if (!Number.isInteger(value) || value < min || (max !== undefined && value > max)) {
+		const bound = max === undefined ? `>= ${min}` : `in ${min}..${max}`;
+		failWire(`${what}: field "${key}" must be an integer ${bound}, got ${value}`);
+	}
+	return value;
+}
+
+/** Assert a base64url string decodes cleanly; returns it unchanged. */
+export function b64urlField(value: string, key: string, what: string): string {
+	try {
+		b64urlToBytes(value);
+	} catch {
+		failWire(`${what}: field "${key}" is not valid base64url`);
+	}
+	return value;
+}
+
+/** Require `value` to be an array of strings; returns it (callers map each element through {@link b64urlField}). */
+export function reqStringArray(value: unknown, key: string, what: string): string[] {
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+		failWire(`${what}: field "${key}" must be an array of strings`);
+	}
+	return value as string[];
+}

package/src/reactivity/wire.ts

@@ -0,0 +1,224 @@
+/**
+ * Reactivity — V1 wire types, codecs, and per-message validation.
+ *
+ * Transcribed from `docs/reactivity.md` §Wire formats. Reactivity reuses the cohort-topic `RegisterV1`
+ * / `RenewV1` envelopes **unchanged**; the reactivity-specific shapes live in two places:
+ *
+ *  1. **Subscribe app payload** ({@link SubscribeAppPayloadV1}) carried opaquely inside
+ *     `RegisterV1.appPayload`. Serialized to UTF-8 JSON bytes and handed to the cohort-topic
+ *     {@link import("../cohort-topic/service.js").RegisterRequest}`.appPayload` slot, which base64url-encodes
+ *     it on the wire. It is therefore **not** length-framed here — the cohort-topic `RegisterV1` frame
+ *     wraps it. The subscribe RPC's authentication (peer-key signature over `correlationId` + `timestamp`)
+ *     is the cohort-topic `RegisterV1` envelope's job, so the payload itself carries no signature.
+ *
+ *  2. **Notification** ({@link NotificationV1}) sent as a standalone RPC over the reactivity application
+ *     protocol. It rides the same length-prefixed UTF-8 JSON framing as cohort-topic messages
+ *     ({@link encodeCohortMessage}). Its `sig` is **bit-for-bit** the commit certificate's threshold
+ *     signature — reactivity never re-signs (`docs/reactivity.md` §Notification origination).
+ *
+ * Conventions (matching the cohort-topic wire conventions): all JSON, byte fields base64url (no
+ * padding), unix-millisecond timestamps, per-message structural validation on decode, byte-fidelity
+ * round-trips (encode→decode→encode is stable). `collectionId` / `tailId` travel as the collection's
+ * base64url block ids verbatim. The `BackfillV1` / `ResumeV1` codecs belong to the sibling tickets.
+ */
+
+import {
+	decodeCohortMessage,
+	encodeCohortMessage,
+	DEFAULT_MAX_MESSAGE_BYTES,
+} from "../cohort-topic/wire/codec.js";
+import {
+	asObject,
+	b64urlField,
+	failWire as fail,
+	reqBoolean,
+	reqFiniteNumber,
+	reqIntInRange,
+	reqString,
+	reqStringArray,
+	requireV1,
+} from "./wire-validate.js";
+
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+/** Ceiling for an opaque subscribe app payload, guarding decode allocation. */
+export const DEFAULT_MAX_SUBSCRIBE_PAYLOAD_BYTES = 64 * 1024;
+
+// --- Subscribe app payload (carried inside cohort-topic RegisterV1.appPayload) ---
+
+/** A subscriber's registration payload (`RegisterV1.appPayload`, `kind == "reactivity"`). */
+export interface SubscribeAppPayloadV1 {
+	kind: "reactivity";
+	/** Stable collection identity, base64url (the collection's id block id). */
+	collectionId: string;
+	/** Tail block id at registration time, base64url (the subscriber-side rotation detector). */
+	tailIdAtAttach: string;
+	/** Last revision the subscriber already holds; `0` for a fresh subscribe. */
+	lastKnownRev: number;
+	/** Max delta bytes the subscriber accepts; `0` declines delta payloads (Edge). */
+	deltaMaxBytes: number;
+}
+
+// --- Notification (length-framed RPC) ---
+
+/** The tail cohort's rotation pre-announce, carried inside (and signed by) a {@link NotificationV1}. */
+export interface RotationHintV1 {
+	/** New tail block id the topic anchor is rotating to, base64url. */
+	newTailId: string;
+	/** Revision at which the new tail becomes effective. */
+	effectiveAtRevision: number;
+}
+
+/** A signed change notification fanned out through the reactivity tree (`docs/reactivity.md` §Notification origination). */
+export interface NotificationV1 {
+	v: 1;
+	/** Collection id, base64url. */
+	collectionId: string;
+	/** Tail block id the reactivity topic is anchored on, base64url. */
+	tailId: string;
+	/** Per-collection monotonic revision. */
+	revision: number;
+	/**
+	 * The commit-vote **signed payload** `utf8(commitHash + ":approve")`, base64url — the exact bytes the
+	 * threshold signature {@link sig} was computed over. A subscriber threshold-verifies {@link sig} over
+	 * `b64urlToBytes(digest)`, so this reproduces the signed image against real Ed25519.
+	 */
+	digest: string;
+	/** Optional bounded delta, base64url; omitted when `delta_max == 0` or the collection declines it. */
+	delta?: string;
+	/** Unix ms. */
+	timestamp: number;
+	/** Threshold signature, base64url — **= the commit cert**, never re-signed. */
+	sig: string;
+	/** PeerIds contributing to {@link sig}, base64url of the cohort member-id bytes. */
+	signers: string[];
+	/** Tail-rotation pre-announce, when this notification carries one (rotation ticket fills it). */
+	rotationHint?: RotationHintV1;
+	/**
+	 * `true` iff this notification announces a durable **invalidation** (a reversal of a previously
+	 * committed action proven invalid by dispute) rather than an ordinary commit
+	 * (`docs/reactivity.md` §Notification origination, `docs/right-is-right.md` §Durable Invalidation).
+	 * An invalidation is a committed collection change like any other and rides the same notification
+	 * path, reusing the **invalidation's** commit cert as {@link sig} (never re-signed) — so it verifies
+	 * against the tail cohort exactly like a commit notification. The flag is a hint that lets a
+	 * subscriber react (drop derived results + resubmit) rather than merely refresh; a subscriber that
+	 * ignores it still re-reads the authoritative reverted state. Omitted (falsy) on commit notifications.
+	 */
+	invalidation?: boolean;
+	/**
+	 * When {@link invalidation} is set, the original action id that was reversed
+	 * (`InvalidationEntry.invalidatedActionId`). Lets a client dedup/coalesce the several cascade
+	 * notifications a single dispute can produce by the action they reverse. Omitted on commits.
+	 */
+	invalidatedActionId?: string;
+}
+
+// --- validation helpers ---
+// Generic primitives live in ./wire-validate.js (shared across the reactivity codecs); the
+// notification-specific narrowing stays here next to the type it produces.
+
+function validateRotationHint(value: unknown, what: string): RotationHintV1 {
+	const obj = asObject(value, what);
+	return {
+		newTailId: b64urlField(reqString(obj, "newTailId", what), "newTailId", what),
+		effectiveAtRevision: reqIntInRange(obj, "effectiveAtRevision", what, 0),
+	};
+}
+
+// --- Subscribe app payload (opaque RegisterV1.appPayload bytes) ---
+
+/** Narrow an already-parsed value to {@link SubscribeAppPayloadV1}, throwing on any defect. */
+export function validateSubscribeAppPayloadV1(value: unknown): SubscribeAppPayloadV1 {
+	const what = "SubscribeAppPayloadV1";
+	const obj = asObject(value, what);
+	if (obj["kind"] !== "reactivity") {
+		fail(`${what}: field "kind" must be exactly "reactivity"`);
+	}
+	return {
+		kind: "reactivity",
+		collectionId: b64urlField(reqString(obj, "collectionId", what), "collectionId", what),
+		tailIdAtAttach: b64urlField(reqString(obj, "tailIdAtAttach", what), "tailIdAtAttach", what),
+		lastKnownRev: reqIntInRange(obj, "lastKnownRev", what, 0),
+		deltaMaxBytes: reqIntInRange(obj, "deltaMaxBytes", what, 0),
+	};
+}
+
+/** Serialize a {@link SubscribeAppPayloadV1} to the opaque UTF-8 JSON bytes for `RegisterV1.appPayload`. */
+export function encodeSubscribeAppPayload(payload: SubscribeAppPayloadV1): Uint8Array {
+	return utf8Encoder.encode(JSON.stringify(validateSubscribeAppPayloadV1(payload)));
+}
+
+/** Decode opaque `RegisterV1.appPayload` bytes back to a validated {@link SubscribeAppPayloadV1}. */
+export function decodeSubscribeAppPayload(bytes: Uint8Array, maxBytes: number = DEFAULT_MAX_SUBSCRIBE_PAYLOAD_BYTES): SubscribeAppPayloadV1 {
+	return validateSubscribeAppPayloadV1(parseJsonBytes(bytes, maxBytes, "SubscribeAppPayloadV1"));
+}
+
+/** Parse opaque (non-framed) UTF-8 JSON payload bytes, rejecting oversized/invalid input. */
+function parseJsonBytes(bytes: Uint8Array, maxBytes: number, what: string): unknown {
+	if (bytes.length > maxBytes) {
+		fail(`${what}: payload ${bytes.length} exceeds max ${maxBytes} bytes`);
+	}
+	let text: string;
+	try {
+		text = utf8Decoder.decode(bytes);
+	} catch {
+		fail(`${what}: payload is not valid UTF-8`);
+	}
+	try {
+		return JSON.parse(text) as unknown;
+	} catch {
+		fail(`${what}: payload is not valid JSON`);
+	}
+}
+
+// --- Notification (length-framed) ---
+
+/** Narrow an already-parsed value to {@link NotificationV1}, throwing on any defect. */
+export function validateNotificationV1(value: unknown): NotificationV1 {
+	const what = "NotificationV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	const signers = reqStringArray(obj["signers"], "signers", what);
+	const out: NotificationV1 = {
+		v: 1,
+		collectionId: b64urlField(reqString(obj, "collectionId", what), "collectionId", what),
+		tailId: b64urlField(reqString(obj, "tailId", what), "tailId", what),
+		revision: reqIntInRange(obj, "revision", what, 0),
+		digest: b64urlField(reqString(obj, "digest", what), "digest", what),
+		timestamp: reqFiniteNumber(obj, "timestamp", what),
+		sig: b64urlField(reqString(obj, "sig", what), "sig", what),
+		signers: signers.map((s, i) => b64urlField(s, `signers[${i}]`, what)),
+	};
+	if (obj["delta"] !== undefined) {
+		out.delta = b64urlField(reqString(obj, "delta", what), "delta", what);
+	}
+	if (obj["rotationHint"] !== undefined) {
+		out.rotationHint = validateRotationHint(obj["rotationHint"], `${what}.rotationHint`);
+	}
+	if (obj["invalidation"] !== undefined) {
+		out.invalidation = reqBoolean(obj, "invalidation", what);
+	}
+	if (obj["invalidatedActionId"] !== undefined) {
+		out.invalidatedActionId = reqString(obj, "invalidatedActionId", what);
+	}
+	return out;
+}
+
+/** Validate an array of {@link NotificationV1} (the `entries`/`recentEntries` carried in backfill/resume replies). */
+export function validateNotificationArray(value: unknown, what: string): NotificationV1[] {
+	if (!Array.isArray(value)) {
+		fail(`${what}: field "entries" must be an array`);
+	}
+	return value.map((entry) => validateNotificationV1(entry));
+}
+
+/** Encode a {@link NotificationV1} as a length-prefixed UTF-8 JSON frame. */
+export function encodeNotificationV1(msg: NotificationV1, maxMessageBytes: number = DEFAULT_MAX_MESSAGE_BYTES): Uint8Array {
+	return encodeCohortMessage(validateNotificationV1(msg), maxMessageBytes);
+}
+
+/** Decode a length-prefixed {@link NotificationV1} frame. */
+export function decodeNotificationV1(bytes: Uint8Array, maxMessageBytes?: number): NotificationV1 {
+	return validateNotificationV1(decodeCohortMessage(bytes, maxMessageBytes));
+}

package/src/transaction/coordinator.ts

@@ -94,11 +94,15 @@ export class TransactionCoordinator {
 	}
 
 	/**
-	 * Commit a transaction (actions already applied, orchestrate PEND/COMMIT).
+	 * Commit a transaction: materialise a log entry from each collection's staged
+	 * pending actions, then orchestrate the distributed consensus (GATHER/PEND/COMMIT).
 	 *
-	 * This is called by TransactionSession.commit() after all statements have been executed.
-	 * Actions have already been applied to collections via applyActions(), so this method
-	 * just orchestrates the distributed consensus.
+	 * Called by TransactionSession.commit() after all statements have executed. The
+	 * staged mutations already live in each collection's tracker — applied either via
+	 * applyActions() (engine-driven path) or directly via Collection.act()/Tree.stage
+	 * (the vtab's deferred-DML path) — but in BOTH cases without a log entry yet, so
+	 * this method appends that entry here (see the inline note below) before pending,
+	 * and folds the committed transforms back into each collection's read cache.
 	 *
 	 * @param transaction - The transaction to commit
 	 */
@@ -107,7 +111,7 @@ export class TransactionCoordinator {
 			throw new Error(`Transaction expired at ${transaction.stamp.expiration}`);
 		}
 
-		// Collect transforms and determine critical blocks for each affected collection
+		// Collect collections with staged (un-synced) changes.
 		const collectionData = Array.from(this.collections.entries())
 			.map(([collectionId, collection]) => ({
 				collectionId,
@@ -124,30 +128,38 @@ export class TransactionCoordinator {
 			return; // Nothing to commit
 		}
 
-		// Get critical block IDs (log tail) for each affected collection
-		// The critical block is the current log tail that must participate in consensus
+		// Append each collection's staged actions to its log, then collect the
+		// resulting transforms + critical (log-tail) block for consensus.
+		//
+		// The actions were staged directly into the trackers (Collection.act, e.g.
+		// via Tree.stage) WITHOUT first appending a log entry, so — exactly as
+		// execute()/applyActionsToCollection does — we materialise the log entry
+		// here from each collection's pending actions. Reading raw tracker
+		// transforms without a fresh log entry only ever "worked" for a
+		// collection's pristine first commit (where the initial empty log block is
+		// itself an uncommitted tracker insert); it broke for any collection with
+		// prior committed state — a pre-synced index tree, or a second commit on
+		// the same collection — whose log tail lives in storage, not the tracker.
+		const allCollectionIds = collectionData.map(({ collectionId }) => collectionId);
 		const collectionTransforms = new Map<CollectionId, Transforms>();
 		const criticalBlocks = new Map<CollectionId, BlockId>();
 
-		for (const { collectionId, collection, transforms } of collectionData) {
-			collectionTransforms.set(collectionId, transforms);
-
-			// Get the current log tail block ID (critical block)
-			const log = await Log.open(collection.tracker, collectionId);
-			if (!log) {
-				throw new Error(`Log not found for collection ${collectionId}`);
-			}
-
-			const tailPath = await (log as unknown as { chain: { getTail: () => Promise<{ block: { header: { id: BlockId } } } | undefined> } }).chain.getTail();
-			if (tailPath) {
-				criticalBlocks.set(collectionId, tailPath.block.header.id);
+		for (const { collectionId, collection } of collectionData) {
+			const applyResult = await this.applyActionsToCollection(
+				{ collectionId, actions: collection.getPendingActions() },
+				transaction,
+				allCollectionIds
+			);
+			if (!applyResult.success) {
+				throw new Error(`Transaction commit failed: ${applyResult.error}`);
 			}
+			collectionTransforms.set(collectionId, applyResult.transforms!);
+			criticalBlocks.set(collectionId, applyResult.logTailBlockId!);
 		}
 
-		// Compute hash of ALL operations across ALL collections
-		// This hash is used for validation - validators re-execute the transaction
-		// and compare their computed operations hash with this one
-		const allOperations = collectionData.flatMap(({ collectionId, transforms }) => [
+		// Compute hash of ALL operations across ALL collections (post-log-append).
+		// Validators re-execute the transaction and compare their computed hash.
+		const allOperations = Array.from(collectionTransforms.entries()).flatMap(([collectionId, transforms]) => [
 			...Object.entries(transforms.inserts ?? {}).map(([blockId, block]) =>
 				({ type: 'insert' as const, collectionId, blockId, block })
 			),
@@ -173,8 +185,14 @@ export class TransactionCoordinator {
 			throw new Error(`Transaction commit failed: ${coordResult.error}`);
 		}
 
-		// Reset trackers and update actionContext after successful commit
-		for (const { collection } of collectionData) {
+		// Advance actionContext, fold the committed transforms into each
+		// collection's read cache, reset the tracker, and drop the now-committed
+		// pending actions. Order matters: cache the committed blocks BEFORE
+		// resetting the tracker (the transforms are read live), so a collection
+		// with prior committed state (a pre-synced index, or any second commit)
+		// serves the new revision instead of the stale cached one. Clearing
+		// pending keeps a subsequent commit from re-logging these actions.
+		for (const { collectionId, collection } of collectionData) {
 			const newRev = (collection['source'].actionContext?.rev ?? 0) + 1;
 			collection['source'].actionContext = {
 				committed: [
@@ -183,7 +201,9 @@ export class TransactionCoordinator {
 				],
 				rev: newRev,
 			};
+			collection.applyCommittedToCache(collectionTransforms.get(collectionId)!);
 			collection.tracker.reset();
+			collection.clearPendingActions();
 		}
 
 		// Clean up stamp tracking data
@@ -512,13 +532,19 @@ export class TransactionCoordinator {
 		const actionId = transaction.id;
 		const newRev = (collection['source'].actionContext?.rev ?? 0) + 1;
 
-		// Add actions to log (this updates the tracker with log block changes)
+		// Add actions to log (this updates the tracker with log block changes).
+		// Persist the transaction's read set on the entry so a later invalidation cascade can
+		// discover this action's read-dependents (see ActionEntry.reads). The whole transaction's
+		// reads are recorded on every collection's entry: a read may target a block in another
+		// collection, and the cascade matches read-dependents by (blockId, revision) regardless of
+		// which collection's log the dependent landed in.
 		const addResult = await log.addActions(
 			collectionActions.actions,
 			actionId,
 			newRev,
 			() => blockIdsForTransforms(transforms),
-			allCollectionIds
+			allCollectionIds,
+			transaction.reads
 		);
 
 		// Return the transforms and log tail block ID