@rocicorp/zero 1.10.0-canary.0 → 1.10.0-canary.10

package/out/zero-cache/src/services/change-streamer/change-streamer-service.js

@@ -1,31 +1,41 @@
-import { unreachable } from "../../../../shared/src/asserts.js";
+import { assert, unreachable } from "../../../../shared/src/asserts.js";
 import { promiseVoid } from "../../../../shared/src/resolved-promises.js";
+import { must } from "../../../../shared/src/must.js";
+import { promiseOrAbort } from "../../../../shared/src/promise-race.js";
 import "../change-source/protocol/current/downstream.js";
-import { getOrCreateCounter } from "../../observability/metrics.js";
+import { getOrCreateCounter, getOrCreateLatencyHistogram } from "../../observability/metrics.js";
 import { DEFAULT_MAX_RETRY_DELAY_MS, RunningState, UnrecoverableError } from "../running-state.js";
 import { min } from "../../types/lexi-version.js";
 import { publishCriticalEvent } from "../../observability/events.js";
-import { AutoResetSignal, ensureReplicationConfig, markResetRequired } from "./schema/tables.js";
 import { Subscription } from "../../types/subscription.js";
+import { AutoResetSignal, ensureReplicationConfig, markResetRequired } from "./schema/tables.js";
 import { publishReplicationError, replicationStatusError } from "../replicator/replication-status.js";
 import "./change-streamer.js";
+import { SQLiteChangeLogReader } from "./sqlite-change-log-reader.js";
+import { ChangeLogInitializer, replicaInitializationSource } from "./change-log-initializer.js";
 import { Forwarder } from "./forwarder.js";
-import { initChangeStreamerSchema } from "./schema/init.js";
+import { SnapshotReservations } from "./snapshot-reservations.js";
+import { SQLiteChangeLogCatchup } from "./sqlite-change-log-catchup.js";
+import { SQLiteChangeLogComparator } from "./sqlite-change-log-comparator.js";
+import { SQLiteChangeLogPurgeScheduler } from "./sqlite-change-log-purge-scheduler.js";
+import { SQLiteChangeLogReadRouter, inspectSQLiteChangeLog } from "./sqlite-change-log-read-router.js";
+import { SQLiteChangeLogWriter } from "./sqlite-change-log-writer.js";
 import { Storer } from "./storer.js";
 import { Subscriber } from "./subscriber.js";
+import { UpstreamAcker } from "./upstream-acker.js";
 import { resolver } from "@rocicorp/resolver";
 import { getDefaultHighWaterMark } from "node:stream";
 //#region ../zero-cache/src/services/change-streamer/change-streamer-service.ts
 /**
 * Performs initialization and schema migrations to initialize a ChangeStreamerImpl.
 */
-async function initializeStreamer(lc, shard, taskID, discoveryAddress, discoveryProtocol, changeDB, changeSource, replicationStatusPublisher, subscriptionState, purgeLock, autoReset, opts, setTimeoutFn = setTimeout) {
-	await initChangeStreamerSchema(lc, changeDB, shard);
-	await ensureReplicationConfig(lc, changeDB, subscriptionState, shard, autoReset, setTimeoutFn);
+async function initializeStreamer(lc, shard, taskID, discoveryAddress, discoveryProtocol, changeDB, changeSource, replicationStatusPublisher, subscriptionState, backupConfig, purgeLock, autoReset, opts, setTimeoutFn = setTimeout) {
+	await ensureReplicationConfig(lc, changeDB, subscriptionState, shard, autoReset, purgeLock ?? void 0, setTimeoutFn);
 	const { replicaVersion } = subscriptionState;
-	return new ChangeStreamerImpl(lc, shard, taskID, discoveryAddress, discoveryProtocol, changeDB, replicaVersion, changeSource, replicationStatusPublisher, purgeLock, autoReset, opts, setTimeoutFn);
+	return new ChangeStreamerImpl(lc, shard, taskID, discoveryAddress, discoveryProtocol, changeDB, replicaVersion, changeSource, replicationStatusPublisher, backupConfig, purgeLock, autoReset, opts, setTimeoutFn);
 }
 var REPLICATION_STATUS_ERROR_DELAY_THRESHOLD_MS = 5e3;
+var DEFAULT_CHANGE_LOG_UNAVAILABLE_WARN_THRESHOLD_MS = 6e4;
 /**
 * Upstream-agnostic dispatch of messages in a {@link ChangeStreamMessage} to a
 * {@link Forwarder} and {@link Storer} to execute the forward-store-ack
@@ -173,30 +183,115 @@ var ChangeStreamerImpl = class {
 	#source;
 	#storer;
 	#forwarder;
+	#reservations;
 	#replicationStatusPublisher;
+	#sqliteCatchupOptions;
+	#changeLogWriter;
+	#purgeScheduler;
+	#comparator;
+	#acker;
+	#initializer;
+	#readRouter;
 	#autoReset;
 	#state;
-	#initialWatermarks = /* @__PURE__ */ new Set();
 	#serving = resolver();
 	#txCounter = getOrCreateCounter("replication", "transactions", "Count of replicated transactions");
 	#changeCounter = getOrCreateCounter("replication", "changes", "Count of replicated changes (DML or DDL statements)");
+	#transactionForwardDuration = getOrCreateLatencyHistogram("replication", "transaction_forward_duration", "Time from receiving a transaction's `begin` to forwarding its `commit`, i.e. the change-streamer half of forward-to-subscriber latency.");
+	#catchupRoutes = getOrCreateCounter("replication", "sqlite_change_log.catchup_routes", "Catchup subscriptions by selected source and low-cardinality reason.");
+	#reservationDemotions = getOrCreateCounter("replication", "sqlite_change_log.reservation_demotions", "Snapshot reservations demoted from SQLite to PG because the change log could not cover the backup being restored. With PG retired these followers have no fallback, so this is the rate at which one would instead have to wait for a later backup.");
+	#reservationConfirmDelays = getOrCreateCounter("replication", "sqlite_change_log.reservation_confirm_delays", "Snapshot reservations whose confirmation was deferred because the selected source's change-log minimum was later than the backup watermark. Counted once per reservation, by that source.");
 	#latestStatus;
+	#latestLagReportCommitTimeMs = 0;
+	#backupWatermark;
+	#pgPurgedWatermark = "";
+	/**
+	* The floor last logged as held back by a laggard. The level-triggered
+	* retry re-evaluates every {@link CLEANUP_DELAY_MS}; logging only when the
+	* blocking floor moves keeps a stuck subscriber from emitting the same
+	* line indefinitely.
+	*/
+	#loggedBehindWatermark;
+	#sqlitePurgeContinuation;
 	#purgeLock;
+	#pgPurgeScheduled = false;
+	#pgPurgeRunning = false;
+	#sqlitePurgeScheduled = false;
+	#sqlitePurgeRunning = false;
 	#stream;
-	constructor(lc, shard, taskID, discoveryAddress, discoveryProtocol, changeDB, replicaVersion, source, replicationStatusPublisher, initialPurgeLock, autoReset, opts, setTimeoutFn = setTimeout) {
+	#sqliteCatchup;
+	#changeLogUnavailableSince;
+	#lastForwardedCommitWatermark;
+	#transactionForwardStartedAt;
+	#currentTransactionCompletion;
+	constructor(lc, shard, taskID, discoveryAddress, discoveryProtocol, changeDB, replicaVersion, source, replicationStatusPublisher, backupConfig, initialPurgeLock, autoReset, opts, setTimeoutFn = setTimeout) {
 		this.id = `change-streamer`;
 		this.#lc = lc.withContext("component", "change-streamer");
 		this.#shard = shard;
 		this.#changeDB = changeDB;
 		this.#replicaVersion = replicaVersion;
 		this.#source = source;
-		this.#storer = new Storer(lc, shard, taskID, discoveryAddress, discoveryProtocol, changeDB, replicaVersion, (consumed) => this.#stream?.acks.push([
-			"status",
-			consumed[1],
-			consumed[2]
-		]), (err) => this.stop(err), opts);
-		this.#forwarder = new Forwarder(lc, { flowControlConsensusPaddingSeconds: opts.flowControlConsensusPaddingSeconds });
+		this.#storer = new Storer(lc, shard, taskID, discoveryAddress, discoveryProtocol, changeDB, replicaVersion, (consumed) => this.#acker.trackPgChangeLog(consumed[2].watermark), (err) => this.stop(err), opts);
+		this.#forwarder = new Forwarder(lc, {
+			flowControlConsensusTimeoutProportion: opts.flowControlConsensusTimeoutProportion,
+			flowControlSlowSubscriberGracePeriodMs: opts.flowControlSlowSubscriberGracePeriodMs
+		});
+		const serveOptions = opts.sqliteChangeLogServe;
+		const writerOptions = opts.sqliteChangeLogWriter;
+		const catchupOptions = opts.sqliteCatchup;
+		this.#readRouter = serveOptions && writerOptions && catchupOptions ? new SQLiteChangeLogReadRouter({
+			shard,
+			readPercent: serveOptions.readPercent,
+			coldReadPercent: serveOptions.coldReadPercent,
+			retentionMs: serveOptions.retentionMs,
+			failureCooldownMs: serveOptions.failureCooldownMs,
+			now: serveOptions.now,
+			inspect: serveOptions.inspect ?? (() => inspectSQLiteChangeLog(lc, catchupOptions.changeLogFile, writerOptions.identity))
+		}) : void 0;
+		this.#reservations = backupConfig ? new SnapshotReservations(lc, backupConfig, (taskID) => {
+			this.#readRouter?.release(taskID);
+			this.#purgeScheduler?.resume(taskID);
+		}) : void 0;
 		this.#replicationStatusPublisher = replicationStatusPublisher;
+		this.#changeLogWriter = opts.sqliteChangeLogWriter ? new SQLiteChangeLogWriter(lc, {
+			...opts.sqliteChangeLogWriter,
+			onCommit: (watermark) => {
+				this.#sqliteCatchup?.onChangeLogCommit(watermark);
+				this.#purgeScheduler?.onWriterIdle();
+			},
+			onDisabled: () => {
+				this.#readRouter?.trip(true);
+				this.#closeSQLiteCatchup();
+				this.#comparator?.stop();
+			},
+			onRebuilt: () => {
+				this.#closeSQLiteCatchup();
+				this.#comparator?.invalidate();
+			}
+		}) : void 0;
+		this.#purgeScheduler = opts.sqliteChangeLogPurge && this.#changeLogWriter ? new SQLiteChangeLogPurgeScheduler(lc, () => this.#changeLogWriter?.connection, () => this.#forwarder.getAcks(), opts.sqliteChangeLogPurge) : void 0;
+		this.#acker = new UpstreamAcker({
+			trackPgChangeLog: true,
+			trackBackup: backupConfig?.litestreamVersion === "v5"
+		});
+		const replicaSource = opts.sqliteChangeLogCompare ? replicaInitializationSource(lc, opts.sqliteChangeLogCompare.replicaFile) : void 0;
+		this.#initializer = new ChangeLogInitializer(lc, {
+			initFromPgChangeLog: true,
+			initFromReplica: replicaSource !== void 0
+		}, {
+			pgChangeLog: () => this.#storer.getStartStreamInitializationParameters(),
+			replica: () => must(replicaSource)(),
+			reconcileChangeLog: (resumeFrom, seed) => resumeFrom ? this.#changeLogWriter?.reconcile(resumeFrom) : this.#changeLogWriter?.reconcileFromLog(seed),
+			changeLog: () => this.#changeLogWriter?.connection
+		});
+		this.#sqliteCatchupOptions = opts.sqliteCatchup ? {
+			...opts.sqliteCatchup,
+			cleanupGuard: opts.sqliteCatchup.cleanupGuard ?? this.#purgeScheduler?.cleanupGuard
+		} : void 0;
+		this.#comparator = opts.sqliteChangeLogCompare && opts.sqliteChangeLogWriter && opts.sqliteCatchup ? new SQLiteChangeLogComparator(lc, shard, opts.sqliteCatchup.changeLogFile, opts.sqliteChangeLogWriter.identity, this.#storer, {
+			setTimeoutFn,
+			...opts.sqliteChangeLogCompare
+		}) : void 0;
 		this.#purgeLock = initialPurgeLock;
 		this.#autoReset = autoReset;
 		this.#state = new RunningState(this.id, void 0, setTimeoutFn);
@@ -205,8 +300,11 @@ var ChangeStreamerImpl = class {
 	async run() {
 		this.#lc.info?.("starting change stream");
 		this.#forwarder.startProgressMonitor();
-		const lagReport = await this.#source.startLagReporter();
-		if (lagReport) this.#latestStatus.lagReport = lagReport;
+		const lagReportInit = await this.#source.startLagReporter();
+		if (lagReportInit) {
+			this.#latestStatus.lagReport = { nextSendTimeMs: lagReportInit.nextSendTimeMs };
+			this.#latestLagReportCommitTimeMs = lagReportInit.firstCommitTimeMs;
+		}
 		await this.#storer.assumeOwnership(this.#purgeLock);
 		this.#purgeLock = null;
 		const flushBytesThreshold = getDefaultHighWaterMark(false);
@@ -215,19 +313,22 @@ var ChangeStreamerImpl = class {
 			let watermark = null;
 			let unflushedBytes = 0;
 			try {
-				const { lastWatermark, backfillRequests } = await this.#storer.getStartStreamInitializationParameters();
+				const { lastWatermark, backfillRequests } = await this.#initializer.initialize();
+				this.#lastForwardedCommitWatermark = lastWatermark;
 				const stream = await this.#source.startStream(lastWatermark, backfillRequests);
 				this.#storer.run().catch((e) => stream.changes.cancel(e));
 				this.#stream = stream;
 				if (this.#state.resetBackoff() > REPLICATION_STATUS_ERROR_DELAY_THRESHOLD_MS) this.#replicationStatusPublisher.publish(this.#lc, "Replicating", `Replicating from ${lastWatermark}`);
 				watermark = null;
+				this.#acker.reset(stream.acks);
 				for await (const change of stream.changes) {
+					this.#acker.trackDownstream(change);
 					const [type, msg] = change;
 					switch (type) {
 						case "status":
-							if (msg.ack) this.#storer.status(change);
-							if (msg.lagReport) {
+							if (msg.lagReport && msg.lagReport.lastTimings.commitTimeMs >= this.#latestLagReportCommitTimeMs) {
 								this.#latestStatus.lagReport = msg.lagReport;
+								this.#latestLagReportCommitTimeMs = msg.lagReport.lastTimings.commitTimeMs;
 								this.#forwarder.sendStatus(this.#latestStatus);
 							}
 							continue;
@@ -247,20 +348,25 @@ var ChangeStreamerImpl = class {
 							break;
 					}
 					const json = this.#storer.store(watermark, change);
+					this.#changeLogWriter?.write(change, json);
 					const entry = [
 						watermark,
 						change[1].tag,
 						json
 					];
 					unflushedBytes += json.length;
-					if (unflushedBytes < flushBytesThreshold) this.#forwarder.forward(entry);
-					else {
-						await this.#forwarder.forwardWithFlowControl(entry);
+					if (unflushedBytes < flushBytesThreshold) {
+						this.#forwarder.forward(entry);
+						this.#recordForwardedTransactionBoundary(type, entry[0]);
+					} else {
+						const forwarded = this.#forwarder.forwardWithFlowControl(entry);
+						this.#recordForwardedTransactionBoundary(type, entry[0]);
+						await promiseOrAbort(forwarded, stream.changes.signal, this.#state.signal);
 						unflushedBytes = 0;
 					}
 					if (type === "commit" || type === "rollback") watermark = null;
 					const readyForMore = this.#storer.readyForMore();
-					if (readyForMore) await readyForMore;
+					if (readyForMore) await promiseOrAbort(readyForMore, stream.changes.signal, this.#state.signal);
 				}
 			} catch (e) {
 				err = e;
@@ -271,11 +377,14 @@ var ChangeStreamerImpl = class {
 			if (watermark) {
 				this.#lc.warn?.(`aborting interrupted transaction ${watermark}`);
 				this.#storer.abort();
+				this.#changeLogWriter?.abort();
+				this.#purgeScheduler?.onWriterIdle();
 				this.#forwarder.forward([
 					watermark,
 					"rollback",
 					ROLLBACK_JSON
 				]);
+				this.#recordForwardedTransactionBoundary("rollback", watermark);
 			}
 			await Promise.all([
 				this.#storer.stop(),
@@ -301,27 +410,135 @@ var ChangeStreamerImpl = class {
 			default: unreachable(tag);
 		}
 	}
-	subscribe(ctx) {
+	async subscribe(ctx) {
 		const { protocolVersion, id, mode, replicaVersion, watermark } = ctx;
 		if (mode === "serving") this.#serving.resolve();
-		const downstream = Subscription.create({ cleanup: () => this.#forwarder.remove(subscriber) });
-		const subscriber = new Subscriber(protocolVersion, id, watermark, downstream, () => this.#latestStatus);
+		let cleanupSubscriber = () => {};
+		const downstream = Subscription.create({ cleanup: () => cleanupSubscriber() });
+		const subscriber = new Subscriber(protocolVersion, id, watermark, downstream, () => this.#latestStatus, {});
+		const lc = this.#lc.withContext("subscriber", subscriber.id);
+		const removeFromForwarder = () => {
+			lc.info?.(`removing subscriber ${subscriber.id}`);
+			this.#forwarder.remove(subscriber);
+		};
+		cleanupSubscriber = removeFromForwarder;
 		if (replicaVersion !== this.#replicaVersion) {
-			this.#lc.warn?.(`rejecting subscriber at replica version ${replicaVersion}`);
+			lc.warn?.(`rejecting subscriber at replica version ${replicaVersion}`);
 			subscriber.close(1, `current replica version is ${this.#replicaVersion} (requested ${replicaVersion})`);
 		} else {
-			this.#lc.debug?.(`adding subscriber ${subscriber.id}`);
-			this.#forwarder.add(subscriber);
-			this.#storer.catchup(subscriber, mode);
+			lc.info?.(`adding subscriber ${subscriber.id}`);
+			const catchupFromPG = () => {
+				cleanupSubscriber = removeFromForwarder;
+				this.#forwarder.add(subscriber);
+				this.#storer.catchup(subscriber, mode);
+			};
+			const sqliteSelection = this.#selectSQLiteCatchup(lc, ctx);
+			if (!sqliteSelection) catchupFromPG();
+			else {
+				const { catchup, reason, coverage, logWarm } = sqliteSelection;
+				cleanupSubscriber = () => catchup.remove(subscriber);
+				const registration = await catchup.catchup(subscriber, () => this.#captureRequiredHead(), { logWarm });
+				switch (registration.kind) {
+					case "registered":
+						lc.debug?.(`serving ${ctx.id} from SQLite catchup`, ...coverage ? [{ sqliteChangeLogCoverage: coverage }] : []);
+						this.#recordCatchupRoute("sqlite", reason);
+						break;
+					case "uncovered":
+						lc.info?.(`serving ${ctx.id} from PG catchup: subscriber watermark ${ctx.watermark} is below the SQLite change-log minimum ` + registration.minWatermark);
+						this.#recordCatchupRoute("pg", "watermark-uncovered");
+						catchupFromPG();
+						break;
+					case "declined":
+						lc.error?.(`serving ${ctx.id} from PG catchup: SQLite catchup registration failed`, registration.error);
+						this.#recordCatchupRoute("pg", "registration-failed");
+						catchupFromPG();
+						break;
+					case "handled":
+						this.#recordCatchupRoute("sqlite", "registration-handled");
+						break;
+					default: unreachable(registration);
+				}
+			}
+		}
+		this.#reservations?.close(ctx.taskID);
+		return downstream;
+	}
+	async startSnapshotReservation(taskID) {
+		if (!this.#reservations) throw new Error("backups are not configured");
+		const downstream = this.#reservations.open(taskID);
+		try {
+			await (this.#purgeScheduler?.pause(taskID) ?? promiseVoid);
+			if (!this.#reservations.isCurrent(taskID, downstream)) return downstream;
+			this.#readRouter?.pin(taskID);
+			await this.#confirmReservations();
+			return downstream;
+		} catch (e) {
+			downstream.cancel();
+			throw e;
 		}
-		return Promise.resolve(downstream);
 	}
-	scheduleCleanup(watermark) {
-		const origSize = this.#initialWatermarks.size;
-		this.#initialWatermarks.add(watermark);
-		if (origSize === 0) this.#state.setTimeout(() => this.#purgeOldChanges(), CLEANUP_DELAY_MS);
+	trackBackupWatermark(watermark) {
+		this.#backupWatermark = watermark;
+		this.#acker.trackBackup(watermark);
+		this.#requestSQLitePurge("deferred");
+		this.#maybeSchedulePGPurge();
+		this.#maybeScheduleSQLitePurge();
+		this.#confirmReservations().catch((e) => this.#lc.warn?.(`error confirming snapshot reservation`, e));
 	}
-	async getChangeLogState() {
+	async #confirmReservations() {
+		const backupWatermark = this.#backupWatermark;
+		const reservations = this.#reservations;
+		if (backupWatermark === void 0 || !reservations?.confirmationsRequired()) return;
+		const pgState = await this.#getChangeLogState();
+		for (const taskID of reservations.unconfirmedTaskIDs()) {
+			let route = this.#readRouter?.peek(taskID);
+			if (this.#readRouter && route === void 0) continue;
+			if (route?.source === "sqlite") {
+				const coverage = must(route.coverage, "a pinned SQLite route must carry its covered range");
+				if (coverage.minWatermark > backupWatermark) {
+					this.#lc.info?.(`demoting ${taskID} to PG catchup: SQLite change-log minimum ${coverage.minWatermark} is later than backupWatermark ` + backupWatermark);
+					this.#reservationDemotions.add(1);
+					route = must(this.#readRouter).demote(taskID);
+				}
+			}
+			const source = route?.source ?? "pg";
+			let minWatermark;
+			if (route?.source === "sqlite") minWatermark = must(route.coverage, "a pinned SQLite route must carry its covered range").minWatermark;
+			else ({minWatermark} = pgState);
+			if (minWatermark <= backupWatermark) reservations.confirmFor(taskID, pgState.replicaVersion, backupWatermark, source);
+			else {
+				if (reservations.noteConfirmationDelayed(taskID)) this.#reservationConfirmDelays.add(1);
+				this.#lc.error?.(`pg change-log minWatermark ${minWatermark} is later than backupWatermark ${backupWatermark}. Delaying confirmation of snapshot reservation until next backup.`);
+			}
+		}
+	}
+	#maybeSchedulePGPurge() {
+		const backupWatermark = this.#backupWatermark;
+		if (this.#pgPurgeScheduled || this.#pgPurgeRunning || backupWatermark === void 0 || this.#pgPurgedWatermark >= backupWatermark) return;
+		this.#pgPurgeScheduled = true;
+		this.#state.setTimeout(() => {
+			this.#pgPurgeScheduled = false;
+			this.#pgPurgeRunning = true;
+			return this.#purgePGChangeLog().finally(() => {
+				this.#pgPurgeRunning = false;
+				this.#maybeSchedulePGPurge();
+			});
+		}, CLEANUP_DELAY_MS);
+	}
+	#maybeScheduleSQLitePurge() {
+		if (this.#sqlitePurgeScheduled || this.#sqlitePurgeRunning || this.#backupWatermark === void 0 || this.#sqlitePurgeContinuation === void 0) return;
+		const delay = this.#sqlitePurgeContinuation === "immediate" ? 0 : CLEANUP_DELAY_MS;
+		this.#sqlitePurgeScheduled = true;
+		this.#state.setTimeout(() => {
+			this.#sqlitePurgeScheduled = false;
+			this.#sqlitePurgeRunning = true;
+			return this.#purgeSQLiteChangeLog().finally(() => {
+				this.#sqlitePurgeRunning = false;
+				this.#maybeScheduleSQLitePurge();
+			});
+		}, delay);
+	}
+	async #getChangeLogState() {
 		const minWatermark = await this.#storer.getMinWatermarkForCatchup();
 		if (!minWatermark) this.#lc.warn?.(`Unexpected empty changeLog. Resync if "Local replica watermark" errors arise`);
 		return {
@@ -329,45 +546,218 @@ var ChangeStreamerImpl = class {
 			minWatermark: minWatermark ?? this.#replicaVersion
 		};
 	}
+	#getCleanupFloor() {
+		const backupWatermark = this.#backupWatermark;
+		assert(backupWatermark !== void 0, "cleanup cannot run without a backup watermark");
+		const current = [...this.#forwarder.getAcks(), ...this.#reservations?.getReservedWatermarks() ?? []];
+		return {
+			backupWatermark,
+			purgeWatermark: min(backupWatermark, ...current),
+			current
+		};
+	}
+	async #purgePGChangeLog() {
+		try {
+			const { backupWatermark, purgeWatermark, current } = this.#getCleanupFloor();
+			if (purgeWatermark < backupWatermark) {
+				if (this.#loggedBehindWatermark !== purgeWatermark) {
+					this.#loggedBehindWatermark = purgeWatermark;
+					this.#lc.info?.(`At least one client is behind backup ${backupWatermark}`, { watermarks: current });
+				}
+			} else this.#loggedBehindWatermark = void 0;
+			if (purgeWatermark <= this.#pgPurgedWatermark) return;
+			this.#lc.info?.(`Purging PG changes before ${purgeWatermark} ...`);
+			const start = performance.now();
+			const deleted = await this.#storer.purgeRecordsBefore(purgeWatermark);
+			const elapsed = (performance.now() - start).toFixed(2);
+			this.#lc.info?.(`Purged ${deleted} PG changes before ${purgeWatermark} (${elapsed} ms)`);
+			this.#pgPurgedWatermark = purgeWatermark;
+		} catch (e) {
+			this.#lc.warn?.(`error purging the PG change log`, e);
+		}
+	}
+	async #purgeSQLiteChangeLog() {
+		const scheduler = this.#purgeScheduler;
+		if (!scheduler) return;
+		try {
+			const { backupWatermark, purgeWatermark } = this.#getCleanupFloor();
+			this.#sqlitePurgeContinuation = void 0;
+			if (purgeWatermark < backupWatermark) this.#requestSQLitePurge("deferred");
+			const result = await scheduler.purge(purgeWatermark);
+			this.#requestSQLitePurge(result.continuation);
+		} catch (e) {
+			this.#requestSQLitePurge("deferred");
+			this.#lc.warn?.(`error purging the SQLite change log`, e);
+		}
+	}
+	#requestSQLitePurge(continuation) {
+		if (!this.#purgeScheduler || continuation === void 0) return;
+		if (continuation === "immediate" || this.#sqlitePurgeContinuation === void 0) this.#sqlitePurgeContinuation = continuation;
+	}
+	async stop(err) {
+		this.#state.stop(this.#lc, err);
+		this.#stream?.changes.cancel();
+		this.#purgeScheduler?.stop();
+		this.#comparator?.stop();
+		this.#sqliteCatchup?.close();
+		this.#changeLogWriter?.close();
+		await Promise.allSettled([this.#storer.stop(), this.#source.stop()]);
+	}
+	#recordForwardedTransactionBoundary(type, watermark) {
+		switch (type) {
+			case "begin":
+				assert(this.#currentTransactionCompletion === void 0, "forwarded begin while a transaction is already in progress");
+				this.#currentTransactionCompletion = resolver();
+				this.#transactionForwardStartedAt = performance.now();
+				break;
+			case "commit": {
+				const completion = this.#currentTransactionCompletion;
+				assert(completion, "forwarded commit without a pending transaction");
+				this.#recordTransactionForwardDuration();
+				this.#lastForwardedCommitWatermark = watermark;
+				this.#currentTransactionCompletion = void 0;
+				completion.resolve({
+					kind: "committed",
+					watermark
+				});
+				break;
+			}
+			case "rollback": {
+				const completion = this.#currentTransactionCompletion;
+				assert(completion, "forwarded rollback without a pending transaction");
+				const committed = this.#lastForwardedCommitWatermark;
+				assert(committed, "last forwarded commit watermark is not initialized");
+				this.#transactionForwardStartedAt = void 0;
+				this.#currentTransactionCompletion = void 0;
+				completion.resolve({
+					kind: "rolled-back",
+					watermark: committed
+				});
+				break;
+			}
+		}
+	}
+	#recordTransactionForwardDuration() {
+		const startedAt = this.#transactionForwardStartedAt;
+		this.#transactionForwardStartedAt = void 0;
+		if (startedAt !== void 0) this.#transactionForwardDuration.recordMs(performance.now() - startedAt, { sqlite_change_log: this.#changeLogWriter?.enabled ? "on" : "off" });
+	}
 	/**
-	* Makes a best effort to purge the change log. In the event of a database
-	* error, exceptions will be logged and swallowed, so this method is safe
-	* to run in a timeout.
+	* Closes and forgets the cached catchup coordinator, so that a later
+	* subscription re-opens the log from scratch rather than reading a handle
+	* whose file is gone.
 	*/
-	async #purgeOldChanges() {
-		const initial = [...this.#initialWatermarks];
-		if (initial.length === 0) {
-			this.#lc.warn?.("No initial watermarks to check for cleanup");
+	#closeSQLiteCatchup() {
+		this.#sqliteCatchup?.close();
+		this.#sqliteCatchup = void 0;
+	}
+	#captureRequiredHead() {
+		const committed = this.#lastForwardedCommitWatermark;
+		assert(committed, "last forwarded commit watermark is not initialized");
+		return this.#currentTransactionCompletion?.promise.then((completion) => completion.watermark) ?? committed;
+	}
+	#selectSQLiteCatchup(lc, ctx) {
+		const opts = this.#sqliteCatchupOptions;
+		if (this.#lastForwardedCommitWatermark === void 0 || !opts) {
+			this.#recordCatchupRoute("pg", "not-ready");
+			return;
+		}
+		if (ctx.mode !== "serving") {
+			lc.info?.(`not serving backup subscriber ${ctx.id} from SQLite catchup`);
+			this.#recordCatchupRoute("pg", "ineligible-mode");
+			return;
+		}
+		let route;
+		if (this.#readRouter) {
+			route = this.#readRouter.consume(ctx.taskID);
+			if (route.source === "pg") {
+				if (route.reason === "cold-log") lc.info?.(`serving ${ctx.id} from PG catchup: SQLite change log is still warming`, { sqliteChangeLogCoverage: route.coverage });
+				else if (route.reason === "log-unavailable") this.#declineSQLiteCatchup(lc, ctx, opts, `${opts.changeLogFile} is unavailable or incompatible`);
+				else lc.debug?.(`serving ${ctx.id} from PG catchup: SQLite route ${route.reason}`, ...route.coverage ? [{ sqliteChangeLogCoverage: route.coverage }] : []);
+				this.#recordCatchupRoute("pg", route.reason);
+				return;
+			}
+			const coverage = route.coverage;
+			assert(coverage, "a SQLite route must carry its covered range");
+			if (ctx.watermark < coverage.minWatermark) {
+				lc.info?.(`serving ${ctx.id} from PG catchup: subscriber watermark ${ctx.watermark} is below the SQLite change-log minimum ` + coverage.minWatermark, { sqliteChangeLogCoverage: coverage });
+				this.#recordCatchupRoute("pg", "watermark-uncovered");
+				return;
+			}
+		}
+		if (!this.#readRouter && !opts.shouldUse?.(ctx)) {
+			this.#recordCatchupRoute("pg", "selector");
 			return;
 		}
-		const current = [...this.#forwarder.getAcks()];
-		if (current.length === 0) {
-			this.#lc.warn?.("No subscribers to confirm cleanup");
+		if (this.#readRouter && opts.shouldUse && !opts.shouldUse(ctx)) {
+			this.#recordCatchupRoute("pg", "selector");
 			return;
 		}
+		const catchup = this.#sqliteCatchup ?? this.#openSQLiteCatchup(lc, opts, ctx);
+		if (catchup) return {
+			catchup,
+			reason: route?.reason ?? "selector",
+			coverage: route?.coverage,
+			logWarm: route === void 0 ? void 0 : route.reason !== "selected-cold"
+		};
+		else this.#recordCatchupRoute("pg", "log-unavailable");
+	}
+	#recordCatchupRoute(source, reason) {
+		this.#catchupRoutes.add(1, {
+			source,
+			reason
+		});
+	}
+	/**
+	* Opens the change log and, if it can serve, wraps it in the coordinator that
+	* subsequent subscriptions reuse.
+	*
+	* The log may not exist yet -- the writer creates it at the stream loop's
+	* first reconcile, and deletes it when it fails soft -- or may exist without
+	* content, or may be unreadable. None of those can be allowed to fail a
+	* subscription:
+	* this is the last point at which PG catchup is still available -- past
+	* `Forwarder.add()` the subscriber is committed to SQLite -- so each declines
+	* here instead. Neither the failure nor the reader is retained, so a later
+	* subscription retries from scratch.
+	*/
+	#openSQLiteCatchup(lc, opts, ctx) {
+		let reader;
 		try {
-			const earliestInitial = min(...initial);
-			const earliestCurrent = min(...current);
-			if (earliestCurrent < earliestInitial) this.#lc.info?.(`At least one client is behind backup (${earliestCurrent} < ${earliestInitial})`);
-			else {
-				this.#lc.info?.(`Purging changes before ${earliestInitial} ...`);
-				const start = performance.now();
-				const deleted = await this.#storer.purgeRecordsBefore(earliestInitial);
-				const elapsed = (performance.now() - start).toFixed(2);
-				this.#lc.info?.(`Purged ${deleted} changes before ${earliestInitial} (${elapsed} ms)`);
-				this.#initialWatermarks.delete(earliestInitial);
+			reader = new SQLiteChangeLogReader(this.#lc, opts.changeLogFile);
+			if (reader.plan(ctx.watermark).kind === "not-ready") {
+				reader.close();
+				this.#declineSQLiteCatchup(lc, ctx, opts, `${opts.changeLogFile} has no changes to serve yet`);
+				return;
 			}
 		} catch (e) {
-			this.#lc.warn?.(`error purging change log`, e);
-		} finally {
-			if (this.#initialWatermarks.size) this.#state.setTimeout(() => this.#purgeOldChanges(), CLEANUP_DELAY_MS);
+			reader?.close();
+			this.#declineSQLiteCatchup(lc, ctx, opts, `cannot read ${opts.changeLogFile}`, e);
+			return;
 		}
+		this.#changeLogUnavailableSince = void 0;
+		this.#sqliteCatchup = new SQLiteChangeLogCatchup(this.#lc, this.#forwarder, reader, {
+			batchSize: opts.readBatchRows,
+			barrierTimeoutMs: opts.barrierTimeoutMs,
+			barrierPollIntervalMs: opts.barrierPollIntervalMs,
+			cleanupGuard: opts.cleanupGuard,
+			onFailure: (failure) => {
+				this.#lc.warn?.(`temporarily disabling SQLite catchup after ${failure}`);
+				this.#readRouter?.trip();
+			}
+		});
+		return this.#sqliteCatchup;
 	}
-	async stop(err) {
-		this.#state.stop(this.#lc, err);
-		this.#stream?.changes.cancel();
-		await this.#storer.stop();
-		await this.#source.stop();
+	/**
+	* Reports falling back to PG catchup, tracking how long the log has been
+	* unavailable so that a subscription that merely arrived before the writer's
+	* first reconcile does not look like an incident.
+	*/
+	#declineSQLiteCatchup(lc, ctx, opts, reason, error) {
+		const now = Date.now();
+		this.#changeLogUnavailableSince ??= now;
+		const unavailableMs = now - this.#changeLogUnavailableSince;
+		lc[unavailableMs >= (opts.notReadyWarnThresholdMs ?? DEFAULT_CHANGE_LOG_UNAVAILABLE_WARN_THRESHOLD_MS) ? "warn" : "debug"]?.(`serving ${ctx.id} from PG catchup: ${reason} (unavailable for ${unavailableMs} ms)`, ...error === void 0 ? [] : [error]);
 	}
 };
 var CLEANUP_DELAY_MS = DEFAULT_MAX_RETRY_DELAY_MS * 3;