@rocicorp/zero 1.11.0-canary.2 → 1.11.0-canary.21

package/out/zero-cache/src/services/view-syncer/pipeline-driver.js

@@ -1,5 +1,6 @@
 import { assert, unreachable } from "../../../../shared/src/asserts.js";
 import { deepEqual } from "../../../../shared/src/json.js";
+import { getOrInsertComputed } from "../../../../shared/src/map.js";
 import { must } from "../../../../shared/src/must.js";
 import { skipYields } from "../../../../zql/src/ivm/skip-yields.js";
 import { throwOutput } from "../../../../zql/src/ivm/operator.js";
@@ -14,13 +15,18 @@ import { resolveSimpleScalarSubqueries } from "../../../../zqlite/src/resolve-sc
 import { randInt } from "../../../../shared/src/rand.js";
 import { createSQLiteCostModel } from "../../../../zqlite/src/sqlite-cost-model.js";
 import { reloadPermissionsIfChanged } from "../../auth/load-permissions.js";
+import { LogThrottle } from "../../observability/log-throttle.js";
 import { getOrCreateCounter, getOrCreateLatencyHistogram } from "../../observability/metrics.js";
 import "../../types/row-key.js";
 import { getSubscriptionState } from "../replicator/schema/replication-state.js";
 import { checkClientSchema } from "./client-schema.js";
+import { planWarningMessage } from "./plan-warnings.js";
+import { queryShape } from "./query-shape.js";
 import { rowIDSignatureUnit } from "./row-set-signature.js";
 import { ResetPipelinesSignal } from "./snapshotter.js";
 //#region ../zero-cache/src/services/view-syncer/pipeline-driver.ts
+/** The most queries a log of an advancement timeout lists. */
+var ADVANCE_TIMEOUT_LOG_MAX_QUERIES = 3;
 /**
 * No matter how fast hydration is, advancement is given at least this long to
 * complete before doing a pipeline reset.
@@ -33,6 +39,8 @@ var MIN_PROJECTED_ADVANCEMENT_SAMPLE_MS = 5;
 var MIN_PROJECTED_ADVANCEMENT_CHANGES = 16;
 var PROJECTED_ADVANCEMENT_RESET_MULTIPLIER = 1.5;
 var LATE_ADVANCEMENT_FINISH_PROGRESS = .8;
+var planWarningLogThrottle = new LogThrottle({ windowMs: 60 * 6e4 });
+var slowAdvanceLogThrottle = new LogThrottle({ windowMs: 5 * 6e4 });
 function randomID() {
 	return randInt(1, Number.MAX_SAFE_INTEGER).toString(36);
 }
@@ -48,7 +56,7 @@ function minProjectedAdvancementSampleChanges(numChanges) {
 }
 function shouldResetProjectedAdvancement(elapsedMs, projectedTotalTimeMs, processedChanges, numChanges, totalHydrationTimeMs) {
 	if (projectedTotalTimeMs === void 0 || numChanges < MIN_PROJECTED_ADVANCEMENT_CHANGES || processedChanges < minProjectedAdvancementSampleChanges(numChanges) || elapsedMs < MIN_PROJECTED_ADVANCEMENT_SAMPLE_MS) return false;
-	return projectedTotalTimeMs > advancementResetTimeLimitMs(totalHydrationTimeMs) * PROJECTED_ADVANCEMENT_RESET_MULTIPLIER;
+	return projectedTotalTimeMs - elapsedMs > advancementResetTimeLimitMs(totalHydrationTimeMs) * PROJECTED_ADVANCEMENT_RESET_MULTIPLIER;
 }
 function shouldFinishLateAdvancement(processedChanges, numChanges) {
 	return numChanges > 0 && processedChanges / numChanges >= LATE_ADVANCEMENT_FINISH_PROGRESS;
@@ -77,9 +85,11 @@ var PipelineDriver = class {
 	#shardID;
 	#logConfig;
 	#config;
+	#deferredWrites;
 	#tableSpecs = /* @__PURE__ */ new Map();
 	#allTableNames = /* @__PURE__ */ new Set();
 	#costModels;
+	#planWarningThresholds;
 	#yieldThresholdMs;
 	#streamer = null;
 	#hydrateContext = null;
@@ -89,17 +99,34 @@ var PipelineDriver = class {
 	#permissions = null;
 	#advanceTime = getOrCreateLatencyHistogram("sync", "ivm.advance-time", "Time to advance all queries for a given client group in response to a single change.");
 	#conflictRowsDeleted = getOrCreateCounter("sync", "ivm.conflict-rows-deleted", "Number of rows deleted because they conflicted with added row");
+	#deferredWritesFallbacks = getOrCreateCounter("sync", "ivm.deferred-writes-fallbacks", "Number of advancements written through to the replica snapshot because their changes did not fit in the deferred IVM writes budget, from the start or partway (because of the bytes held, a change that needed more rows than were left, or more rows held than reserved)");
 	#inspectorDelegate;
-	constructor(lc, logConfig, snapshotter, shardID, storage, clientGroupID, inspectorDelegate, yieldThresholdMs, enablePlanner, config) {
+	#queryStats;
+	/**
+	* Passes the pipelines' metrics on to the inspector, and accounts the time
+	* spent pushing to each query to the advancement in progress.
+	*/
+	#metricsDelegate = { addMetric: (metric, value, ...args) => {
+		this.#inspectorDelegate.addMetric(metric, value, ...args);
+		if (metric === "query-update-server") this.#recordAdvancePush(args[0], value);
+	} };
+	constructor(lc, logConfig, snapshotter, shardID, storage, clientGroupID, inspectorDelegate, yieldThresholdMs, enablePlanner, config, deferredWrites, queryStats) {
 		this.#lc = lc.withContext("clientGroupID", clientGroupID);
 		this.#snapshotter = snapshotter;
 		this.#storage = storage;
 		this.#shardID = shardID;
 		this.#logConfig = logConfig;
 		this.#config = config;
+		this.#deferredWrites = deferredWrites;
 		this.#inspectorDelegate = inspectorDelegate;
 		this.#costModels = enablePlanner ? /* @__PURE__ */ new WeakMap() : void 0;
+		const planWarningThresholds = {
+			rows: logConfig.planWarningRowThreshold,
+			cost: logConfig.planWarningCostThreshold
+		};
+		this.#planWarningThresholds = planWarningThresholds.rows > 0 || planWarningThresholds.cost > 0 ? planWarningThresholds : void 0;
 		this.#yieldThresholdMs = yieldThresholdMs;
+		this.#queryStats = queryStats;
 	}
 	/**
 	* Initializes the PipelineDriver to the current head of the database.
@@ -173,10 +200,23 @@ var PipelineDriver = class {
 		}
 		return this.#permissions;
 	}
+	/**
+	* Advances the snapshot to the head of the database without diffing the
+	* change log, in preparation for hydrating queries at head.
+	*
+	* Throws a {@link ResetPipelinesSignal} if the change log records a
+	* schema change since the previous snapshot. The table specs (and any
+	* TableSources built from them) were computed at or before that snapshot
+	* and are stale with respect to the new head, so the caller must
+	* {@link reset()} before hydrating. ({@link advance()} detects this when
+	* the diff encounters the RESET op; this path skips the diff and so must
+	* check explicitly.)
+	*/
 	advanceWithoutDiff() {
-		const { db, version } = this.#snapshotter.advanceWithoutDiff().curr;
-		for (const table of this.#tables.values()) table.setDB(db.db);
-		return version;
+		const { prev, curr } = this.#snapshotter.advanceWithoutDiff();
+		if (curr.schemaChangedSince(prev.version)) throw new ResetPipelinesSignal(`schema changed between ${prev.version} and ${curr.version}`, "schema-change");
+		for (const table of this.#tables.values()) table.setDB(curr.db.db);
+		return curr.version;
 	}
 	#ensureCostModelExistsIfEnabled(db) {
 		let existing = this.#costModels?.get(db);
@@ -196,6 +236,7 @@ var PipelineDriver = class {
 			this.#pipelines.delete(queryID);
 			this.#destroyPipeline(queryID, pipeline, "destroy");
 		}
+		this.#tables.clear();
 		this.#rowSetSignatures.clear();
 		this.#storage.destroy();
 		this.#snapshotter.destroy();
@@ -204,18 +245,76 @@ var PipelineDriver = class {
 	queries() {
 		return this.#pipelines;
 	}
+	/**
+	* Stats from the hydration of the pipeline for `queryID`, or `undefined` if
+	* the query has no pipeline.
+	*/
+	hydrationStats(queryID) {
+		const pipeline = this.#pipelines.get(queryID);
+		return pipeline ? {
+			rowCount: pipeline.hydrationRowCount,
+			rowsRead: pipeline.hydrationRowsRead,
+			planWarnings: pipeline.planWarnings,
+			shape: pipeline.shape
+		} : void 0;
+	}
+	/**
+	* Logs what the planner warned about the plan it chose for `query`, at
+	* most once per query shape per {@link PLAN_WARNING_LOG_WINDOW_MS}.
+	*/
+	#logPlanWarnings(shape, { queryHash, transformationHash, queryName }, warnings) {
+		if (!this.#lc.warn) return;
+		const suppressed = planWarningLogThrottle.admit(`${queryName ?? ""}:${shape.hash}`);
+		if (suppressed === void 0) return;
+		const messages = warnings.map(planWarningMessage);
+		this.#lc.warn(`Query plan warning${queryName === void 0 ? "" : ` for ${queryName}`}: ` + messages.join(" "), {
+			zeroEvent: "query-plan-warning",
+			queryHash,
+			transformationHash,
+			...queryName !== void 0 && { queryName },
+			queryShape: shape.hash,
+			warnings,
+			...suppressed > 0 && { suppressedSinceLastLog: suppressed },
+			zql: shape.zql
+		});
+	}
+	#totalRowsRead() {
+		let total = 0;
+		for (const table of this.#tables.values()) total += table.rowsRead;
+		return total;
+	}
 	totalHydrationTimeMs() {
 		let total = 0;
 		for (const pipeline of this.#pipelines.values()) total += pipeline.hydrationTimeMs;
 		return total;
 	}
-	#logQueryPipelineLifecycle({ zeroEvent, pipelineRunID, queryHash, transformationHash, queryName, hydrationReason, stopReason, hydrationTimeMs, hydrationRowCount, pipelineLifetimeMs }) {
+	/**
+	* The rows the sources hold in memory for the advancement in progress.
+	* The advancement's reservation from the {@link DeferredWritesBudget}
+	* bounds this.
+	*/
+	get pendingRows() {
+		let total = 0;
+		for (const source of this.#tables.values()) total += source.pendingRows;
+		return total;
+	}
+	/**
+	* The estimated bytes of {@link pendingRows}, which are added to the
+	* {@link DeferredWritesBudget}'s held bytes as the advancement goes.
+	*/
+	get pendingBytes() {
+		let total = 0;
+		for (const source of this.#tables.values()) total += source.pendingBytes;
+		return total;
+	}
+	#logQueryPipelineLifecycle({ zeroEvent, pipelineRunID, queryHash, transformationHash, queryName, hydrationReason, stopReason, hydrationTimeMs, hydrationRowCount, hydrationRowsRead, pipelineLifetimeMs }) {
 		let lc = this.#lc.withContext("zeroEvent", zeroEvent).withContext("pipelineRunID", pipelineRunID).withContext("queryHash", queryHash).withContext("transformationHash", transformationHash);
 		if (queryName !== void 0) lc = lc.withContext("queryName", queryName);
 		if (hydrationReason !== void 0) lc = lc.withContext("hydrationReason", hydrationReason);
 		if (stopReason !== void 0) lc = lc.withContext("stopReason", stopReason);
 		if (hydrationTimeMs !== void 0) lc = lc.withContext("hydrationTimeMs", hydrationTimeMs);
 		if (hydrationRowCount !== void 0) lc = lc.withContext("hydrationRowCount", hydrationRowCount);
+		if (hydrationRowsRead !== void 0) lc = lc.withContext("hydrationRowsRead", hydrationRowsRead);
 		if (pipelineLifetimeMs !== void 0) lc = lc.withContext("pipelineLifetimeMs", pipelineLifetimeMs);
 		lc.info?.("query pipeline lifecycle");
 	}
@@ -232,11 +331,15 @@ var PipelineDriver = class {
 			this.#lc.warn?.(`Ignoring {scalar: true} on the "${table}" subquery of query ${queryID}: it does not constrain every column of any unique key ${keys.length > 0 ? `[${keys}]` : "(none on this table)"} to a literal with "=", so it is not provably limited to one row. The gate runs as a plain EXISTS.`);
 		}
 	}
+	#disableCorrelatedPredicatePushdown() {
+		return this.#config?.enableCorrelatedPredicatePushdown === false;
+	}
 	#resolveScalarSubqueries(ast) {
 		const companionRows = [];
 		const companionInputs = [];
 		const executor = (subqueryAST, childField) => {
 			const input = buildPipeline(subqueryAST, {
+				disableCorrelatedPredicatePushdown: this.#disableCorrelatedPredicatePushdown(),
 				getSource: (name) => this.#getSource(name),
 				createStorage: () => this.#createStorage(),
 				decorateSourceInput: (input) => input,
@@ -244,20 +347,25 @@ var PipelineDriver = class {
 				addEdge() {},
 				decorateFilterInput: (input) => input
 			}, "scalar-subquery");
+			companionInputs.push(input);
 			let node;
 			for (const n of skipYields(input.fetch({}))) node ??= n;
-			if (!node) {
-				companionInputs.push(input);
-				return;
-			}
+			if (!node) return;
 			companionRows.push({
 				table: subqueryAST.table,
 				row: node.row
 			});
-			companionInputs.push(input);
 			return node.row[childField] ?? null;
 		};
-		const { ast: resolved, companions, ignoredScalarHints } = resolveSimpleScalarSubqueries(ast, this.#tableSpecs, executor);
+		let resolved;
+		let companions;
+		let ignoredScalarHints;
+		try {
+			({ast: resolved, companions, ignoredScalarHints} = resolveSimpleScalarSubqueries(ast, this.#tableSpecs, executor));
+		} catch (e) {
+			for (const input of companionInputs) input.destroy();
+			throw e;
+		}
 		return {
 			ast: resolved,
 			companionRows,
@@ -288,6 +396,7 @@ var PipelineDriver = class {
 		assert(this.initialized(), "Pipeline driver must be initialized before adding queries");
 		this.removeQuery(queryID, "replace-query");
 		const pipelineRunID = randomID();
+		const shape = queryShape(query);
 		this.#logQueryPipelineLifecycle({
 			zeroEvent: "query-pipeline-hydrate-start",
 			pipelineRunID,
@@ -296,33 +405,47 @@ var PipelineDriver = class {
 			queryName,
 			hydrationReason
 		});
-		const debugDelegate = runtimeDebugFlags.trackRowsVended ? new Debug() : void 0;
+		const debugDelegate = runtimeDebugFlags.trackRowsVended ? new Debug(true) : void 0;
 		const costModel = this.#ensureCostModelExistsIfEnabled(this.#snapshotter.current().db.db);
 		assert(this.#advanceContext === null, "Cannot hydrate while advance is in progress");
 		this.#hydrateContext = { timer };
+		const rowsReadAtStart = this.#totalRowsRead();
 		let hydrationFinished = false;
 		let hydrationFailed = false;
 		let hydrationRowCount = 0;
+		let planWarnings = [];
+		const planWarningThresholds = this.#planWarningThresholds;
+		let builtInputs = [];
 		try {
 			const { ast: resolvedQuery, companionRows, companions: companionMeta, companionInputs, ignoredScalarHints } = this.#resolveScalarSubqueries(query);
+			builtInputs = [...companionInputs];
 			this.#warnIgnoredScalarHints(queryID, ignoredScalarHints);
 			const input = buildPipeline(resolvedQuery, {
 				debug: debugDelegate,
 				enableNotExists: true,
+				disableCorrelatedPredicatePushdown: this.#disableCorrelatedPredicatePushdown(),
+				enablePlannerAwarePushdown: this.#config?.enablePlannerAwarePushdown !== false,
 				getSource: (name) => this.#getSource(name),
 				createStorage: () => this.#createStorage(),
-				decorateSourceInput: (input, _queryID) => new MeasurePushOperator(new QueryFailureLoggingOperator(this.#lc, input, queryID, transformationHash, queryName), queryID, this.#inspectorDelegate, "query-update-server"),
+				decorateSourceInput: (input, _queryID) => new MeasurePushOperator(new QueryFailureLoggingOperator(this.#lc, input, queryID, transformationHash, queryName), queryID, this.#metricsDelegate, "query-update-server"),
 				decorateInput: (input) => input,
 				addEdge() {},
-				decorateFilterInput: (input) => input
+				decorateFilterInput: (input) => input,
+				planWarnings: planWarningThresholds && {
+					thresholds: planWarningThresholds,
+					report: (warnings) => {
+						planWarnings = warnings;
+					}
+				}
 			}, queryID, costModel);
+			builtInputs.push(input);
+			if (planWarnings.length > 0) this.#logPlanWarnings(shape, {
+				queryHash: queryID,
+				transformationHash,
+				queryName
+			}, planWarnings);
 			const schema = input.getSchema();
-			input.setOutput({ push: (change) => {
-				const streamer = this.#streamer;
-				assert(streamer, "must #startAccumulating() before pushing changes");
-				streamer.accumulate(queryID, schema, [change]);
-				return [];
-			} });
+			input.setOutput({ push: (change) => this.#streamPushed(queryID, schema, change) });
 			for (const change of hydrateInternal(input, queryID, must(this.#primaryKeys), this.#tableSpecs)) {
 				if (change !== "yield") hydrationRowCount++;
 				yield change;
@@ -339,6 +462,7 @@ var PipelineDriver = class {
 				};
 			}
 			const hydrationTimeMs = timer.totalElapsed();
+			const hydrationRowsRead = this.#totalRowsRead() - rowsReadAtStart;
 			if (runtimeDebugFlags.trackRowCountsVended) {
 				if (hydrationTimeMs > this.#logConfig.slowHydrateThreshold) {
 					let totalRowsConsidered = 0;
@@ -371,10 +495,7 @@ var PipelineDriver = class {
 						case 3: return [];
 					}
 					if (!scalarValuesEqual(newValue, resolvedValue)) throw new ResetPipelinesSignal(`Scalar subquery value changed for ${meta.ast.table}: ${String(resolvedValue)} -> ${String(newValue)}`, "scalar-subquery");
-					const streamer = this.#streamer;
-					assert(streamer, "must #startAccumulating() before pushing changes");
-					streamer.accumulate(queryID, companionSchema, [change]);
-					return [];
+					return this.#streamPushed(queryID, companionSchema, change);
 				} });
 				liveCompanions.push({
 					input: companionInput,
@@ -387,15 +508,29 @@ var PipelineDriver = class {
 				input,
 				hydrationTimeMs,
 				hydrationRowCount,
+				hydrationRowsRead,
+				planWarnings,
 				hydrationReason,
 				pipelineRunID,
 				pipelineReadyAtMs,
 				transformedAst: resolvedQuery,
+				originalAst: query,
+				shape,
 				transformationHash,
 				...queryName !== void 0 && { queryName },
 				companions: liveCompanions
 			});
 			hydrationFinished = true;
+			this.#queryStats?.recordHydration({
+				queryName,
+				shape
+			}, {
+				outcome: "finished",
+				timeMs: hydrationTimeMs,
+				rowCount: hydrationRowCount,
+				rowsRead: hydrationRowsRead,
+				planWarnings
+			});
 			this.#logQueryPipelineLifecycle({
 				zeroEvent: "query-pipeline-hydrate-finish",
 				pipelineRunID,
@@ -404,10 +539,18 @@ var PipelineDriver = class {
 				queryName,
 				hydrationReason,
 				hydrationTimeMs,
-				hydrationRowCount
+				hydrationRowCount,
+				hydrationRowsRead
 			});
 		} catch (e) {
 			hydrationFailed = true;
+			this.#queryStats?.recordHydration({
+				queryName,
+				shape
+			}, {
+				outcome: "failed",
+				timeMs: timer.totalElapsed()
+			});
 			this.#logQueryPipelineLifecycle({
 				zeroEvent: "query-pipeline-hydrate-failed",
 				pipelineRunID,
@@ -425,16 +568,29 @@ var PipelineDriver = class {
 			}, "query hydration failed", e);
 			throw e;
 		} finally {
-			if (!hydrationFinished && !hydrationFailed) this.#logQueryPipelineLifecycle({
-				zeroEvent: "query-pipeline-hydrate-aborted",
-				pipelineRunID,
-				queryHash: queryID,
-				transformationHash,
-				queryName,
-				hydrationReason,
-				hydrationTimeMs: timer.totalElapsed(),
-				hydrationRowCount
-			});
+			if (!hydrationFinished && !hydrationFailed) {
+				this.#queryStats?.recordHydration({
+					queryName,
+					shape
+				}, {
+					outcome: "aborted",
+					timeMs: timer.totalElapsed()
+				});
+				this.#logQueryPipelineLifecycle({
+					zeroEvent: "query-pipeline-hydrate-aborted",
+					pipelineRunID,
+					queryHash: queryID,
+					transformationHash,
+					queryName,
+					hydrationReason,
+					hydrationTimeMs: timer.totalElapsed(),
+					hydrationRowCount
+				});
+			}
+			if (!hydrationFinished) {
+				for (const input of builtInputs) input.destroy();
+				this.#rowSetSignatures.delete(queryID);
+			}
 			this.#hydrateContext = null;
 		}
 	}
@@ -516,7 +672,7 @@ var PipelineDriver = class {
 	*/
 	advance(timer) {
 		assert(this.initialized(), "Pipeline driver must be initialized before advancing");
-		const diff = this.#snapshotter.advance(this.#tableSpecs, this.#allTableNames);
+		const diff = this.#snapshotter.advance(this.#tableSpecs, this.#allTableNames, this.#tables, "divergent");
 		const { prev, curr, changes } = diff;
 		this.#lc.debug?.(`advance ${prev.version} => ${curr.version}: ${changes} changes`);
 		return {
@@ -528,26 +684,38 @@ var PipelineDriver = class {
 	*#advance(diff, timer, numChanges) {
 		assert(this.#hydrateContext === null, "Cannot advance while hydration is in progress");
 		const totalHydrationTimeMs = this.totalHydrationTimeMs();
-		this.#advanceContext = {
+		const advanceContext = {
 			timer,
 			totalHydrationTimeMs,
 			numChanges,
+			reservedRows: void 0,
+			heldBytes: 0,
 			currentChangeStartMs: void 0,
-			pos: 0
+			pos: 0,
+			currentTable: void 0,
+			queryStats: /* @__PURE__ */ new Map()
 		};
-		this.#lc.debug?.(`starting pipeline advancement of ${numChanges} changes with an advancement time limited based on total hydration time of ${totalHydrationTimeMs} ms.`);
+		this.#advanceContext = advanceContext;
+		let timedOut = false;
 		try {
-			for (const { table, prevValues, nextValue } of diff) {
+			advanceContext.reservedRows = this.#reserveDeferredWrites(numChanges);
+			const deferWrites = advanceContext.reservedRows !== void 0;
+			if (deferWrites) diff.setPrevWrites("none");
+			for (const table of this.#tables.values()) table.setDeferWrites(deferWrites);
+			this.#lc.debug?.(`starting pipeline advancement of ${numChanges} changes with an advancement time limited based on total hydration time of ${totalHydrationTimeMs} ms (${deferWrites ? "deferred" : "write-through"}).`);
+			for (const { table, prevValues: probedPrevValues, nextValue, rowKey } of diff) {
 				if (this.#shouldAdvanceYieldMaybeAbortAdvance()) yield "yield";
 				const start = timer.totalElapsed();
-				const advanceContext = must(this.#advanceContext);
 				advanceContext.currentChangeStartMs = start;
-				let type;
+				advanceContext.currentTable = table;
+				let holds = "fits";
 				try {
 					try {
 						const tableSource = this.#tables.get(table);
 						if (!tableSource) continue;
 						const primaryKey = mustGetPrimaryKey(this.#primaryKeys, table);
+						if (nextValue !== null && !this.#reserveSecondRow(advanceContext, rowKey, primaryKey)) holds = "rows";
+						const prevValues = tableSource.reconcilePendingConflicts(probedPrevValues, nextValue, rowKey, this.#tableSpecs.get(table)?.tableSpec.uniqueKeys ?? []);
 						let editOldRow = void 0;
 						for (const prevValue of prevValues) if (nextValue && deepEqual(getRowKey(primaryKey, prevValue), getRowKey(primaryKey, nextValue))) editOldRow = prevValue;
 						else {
@@ -560,34 +728,198 @@ var PipelineDriver = class {
 						advanceContext.pos++;
 					}
 					this.#shouldAdvanceYieldMaybeAbortAdvance(false);
+					if (holds === "fits") holds = this.#holdPendingRows(advanceContext);
 				} finally {
 					advanceContext.currentChangeStartMs = void 0;
 				}
 				const elapsed = timer.totalElapsed() - start;
-				this.#advanceTime.recordMs(elapsed, {
-					table,
-					type
-				});
+				this.#advanceTime.recordMs(elapsed, { table });
+				if (holds !== "fits") yield* this.#writeThrough(advanceContext, diff, holds);
 			}
 			const { curr } = diff;
 			for (const table of this.#tables.values()) table.setDB(curr.db.db);
 			this.#ensureCostModelExistsIfEnabled(curr.db.db);
 			this.#lc.debug?.(`Advanced to ${curr.version}`);
+			this.#logSlowAdvances(advanceContext);
+		} catch (e) {
+			if (e instanceof ResetPipelinesSignal && e.reason === "advancement-timeout") {
+				timedOut = true;
+				this.#logAdvanceTimeout(advanceContext, e);
+			}
+			throw e;
 		} finally {
+			if (advanceContext.reservedRows !== void 0) for (const table of this.#tables.values()) table.discardPendingChanges();
+			this.#releaseDeferredWrites(advanceContext);
 			this.#advanceContext = null;
+			this.#recordAdvanceStats(advanceContext, timedOut);
+		}
+	}
+	/** Accounts the time each query took in an advancement to its shape. */
+	#recordAdvanceStats({ queryStats }, timedOut) {
+		if (this.#queryStats === void 0) return;
+		for (const [queryID, { timeMs, changes }] of queryStats) {
+			const pipeline = this.#pipelines.get(queryID);
+			if (pipeline !== void 0) this.#queryStats.recordAdvance(pipeline, {
+				timeMs,
+				changes,
+				timedOut
+			});
+		}
+	}
+	/**
+	* Decides how the sources apply an advancement's changes: in memory if
+	* they fit in the worker's {@link DeferredWritesBudget}, and otherwise
+	* written through to the `prev` snapshot. Returns the number of rows
+	* reserved if they are held in memory.
+	*/
+	#reserveDeferredWrites(numChanges) {
+		const budget = this.#deferredWrites;
+		if (!budget) return;
+		if (budget.tryReserve(numChanges)) return numChanges;
+		this.#deferredWritesFallbacks.add(1, { stage: "start" });
+		this.#lc.debug?.(`writing through ${numChanges} changes: ${budget.reservedRows} rows of the deferred writes budget are reserved`);
+	}
+	/**
+	* If the change log identifies the rows of a table by a key other than its
+	* primary key here, an entry that sets a row can change its primary key,
+	* which is two rows to a source: the old and the new. (An entry that removes
+	* a row removes the one row its key identifies.) Reserves the second row for
+	* such an entry, if the advancement holds its changes in memory, and
+	* returns whether it fit.
+	*/
+	#reserveSecondRow(advanceContext, rowKey, primaryKey) {
+		if (advanceContext.reservedRows === void 0 || isKeyedBy(rowKey, primaryKey)) return true;
+		if (!must(this.#deferredWrites).tryReserveMore(1)) return false;
+		advanceContext.reservedRows++;
+		return true;
+	}
+	/**
+	* Writes the changes that an advancement holds in memory through to the
+	* `prev` snapshot, and the rest of its changes after them, when they no
+	* longer fit (see {@link HeldRows}). The advancement then continues as if
+	* it had written through from the start.
+	*/
+	*#writeThrough(advanceContext, diff, reason) {
+		const budget = must(this.#deferredWrites);
+		this.#deferredWritesFallbacks.add(1, {
+			stage: "partway",
+			reason
+		});
+		this.#lc.debug?.(`writing through (${reason}) at ${advanceContext.pos} of ${advanceContext.numChanges} changes, holding ${advanceContext.heldBytes} of the ${budget.heldBytes} estimated bytes held on this worker (budget: ${budget.maxBytes})`);
+		diff.setPrevWrites("divergent");
+		for (const source of this.#tables.values()) yield* source.writePendingChanges();
+		this.#releaseDeferredWrites(advanceContext);
+	}
+	#releaseDeferredWrites(advanceContext) {
+		const { reservedRows, heldBytes } = advanceContext;
+		if (reservedRows !== void 0) {
+			must(this.#deferredWrites).release(reservedRows, heldBytes);
+			advanceContext.reservedRows = void 0;
+			advanceContext.heldBytes = 0;
 		}
 	}
+	#recordAdvancePush(queryID, timeMs) {
+		const advance = this.#advanceContext;
+		if (advance === null) return;
+		const stats = getOrInsertComputed(advance.queryStats, queryID, () => ({
+			timeMs: 0,
+			changes: 0,
+			lastPos: -1,
+			timeMsByTable: /* @__PURE__ */ new Map()
+		}));
+		stats.timeMs += timeMs;
+		if (stats.lastPos !== advance.pos) {
+			stats.lastPos = advance.pos;
+			stats.changes++;
+		}
+		const table = advance.currentTable;
+		if (table !== void 0) stats.timeMsByTable.set(table, (stats.timeMsByTable.get(table) ?? 0) + timeMs);
+	}
+	/**
+	* The identity of the query of the pipeline for `queryID` and its
+	* {@link queryShape}, for logging.
+	*/
+	#queryForLog(queryID) {
+		const pipeline = this.#pipelines.get(queryID);
+		if (pipeline === void 0) return;
+		const { transformationHash, queryName, shape } = pipeline;
+		return {
+			queryName,
+			shape,
+			fields: {
+				queryHash: queryID,
+				transformationHash,
+				...queryName !== void 0 && { queryName },
+				queryShape: shape.hash
+			}
+		};
+	}
+	/**
+	* Logs each query whose pushes took longer than the slow advance
+	* threshold, at most once per query shape per
+	* {@link SLOW_ADVANCE_LOG_WINDOW_MS}.
+	*/
+	#logSlowAdvances({ queryStats, numChanges }) {
+		if (!this.#lc.warn) return;
+		for (const [queryID, stats] of queryStats) {
+			if (stats.timeMs <= this.#logConfig.slowAdvanceThreshold) continue;
+			const query = this.#queryForLog(queryID);
+			if (query === void 0) continue;
+			const suppressed = slowAdvanceLogThrottle.admit(`${query.queryName ?? ""}:${query.shape.hash}`);
+			if (suppressed === void 0) continue;
+			this.#lc.warn(`Slow query advancement${query.queryName === void 0 ? "" : ` for ${query.queryName}`}: ${Math.round(stats.timeMs)} ms for ${stats.changes} of ${numChanges} changes`, {
+				zeroEvent: "query-slow-advance",
+				...query.fields,
+				advanceTimeMs: stats.timeMs,
+				changes: stats.changes,
+				advancementChanges: numChanges,
+				timeMsByTable: Object.fromEntries(stats.timeMsByTable),
+				...suppressed > 0 && { suppressedSinceLastLog: suppressed },
+				zql: query.shape.zql
+			});
+		}
+	}
+	/**
+	* Logs the queries that took the most time in an advancement that timed
+	* out, since the reset that follows would otherwise not say what was slow.
+	* Throttled per query shape of the slowest query.
+	*/
+	#logAdvanceTimeout({ queryStats, numChanges }, reset) {
+		if (!this.#lc.warn) return;
+		const slowest = [...queryStats].toSorted(([, a], [, b]) => b.timeMs - a.timeMs).slice(0, ADVANCE_TIMEOUT_LOG_MAX_QUERIES).flatMap(([queryID, stats]) => {
+			const query = this.#queryForLog(queryID);
+			return query ? [{
+				query,
+				stats
+			}] : [];
+		});
+		if (slowest.length === 0) return;
+		const suppressed = slowAdvanceLogThrottle.admit(`timeout:${slowest[0].query.queryName ?? ""}:${slowest[0].query.shape.hash}`);
+		if (suppressed === void 0) return;
+		const summary = slowest.map(({ query, stats }) => `${query.queryName ?? query.fields.queryHash} (${Math.round(stats.timeMs)} ms)`).join(", ");
+		this.#lc.warn(`Advancement of ${numChanges} changes timed out. The queries that took the most time: ${summary}`, {
+			zeroEvent: "query-advance-timeout",
+			reason: reset.message,
+			advancementChanges: numChanges,
+			queries: slowest.map(({ query, stats }) => ({
+				...query.fields,
+				advanceTimeMs: stats.timeMs,
+				changes: stats.changes,
+				zql: query.shape.zql
+			})),
+			...suppressed > 0 && { suppressedSinceLastLog: suppressed }
+		});
+	}
 	/** Implements `BuilderDelegate.getSource()` */
 	#getSource(tableName) {
-		let source = this.#tables.get(tableName);
-		if (source) return source;
-		const tableSpec = mustGetTableSpec(this.#tableSpecs, tableName);
-		const primaryKey = mustGetPrimaryKey(this.#primaryKeys, tableName);
-		const { db } = this.#snapshotter.current();
-		source = new TableSource(this.#lc, this.#logConfig, db.db, tableName, tableSpec.zqlSpec, primaryKey, () => this.#shouldYield());
-		this.#tables.set(tableName, source);
-		this.#lc.debug?.(`created TableSource for ${tableName}`);
-		return source;
+		return getOrInsertComputed(this.#tables, tableName, (tableName) => {
+			const tableSpec = mustGetTableSpec(this.#tableSpecs, tableName);
+			const primaryKey = mustGetPrimaryKey(this.#primaryKeys, tableName);
+			const { db } = this.#snapshotter.current();
+			const source = new TableSource(this.#lc, this.#logConfig, db.db, tableName, tableSpec.zqlSpec, primaryKey, () => this.#shouldYield(), { skipUnobservableChanges: true });
+			this.#lc.debug?.(`created TableSource for ${tableName}`);
+			return source;
+		});
 	}
 	#shouldYield() {
 		if (this.#hydrateContext) return this.#hydrateContext.timer.elapsedLap() > this.#yieldThresholdMs();
@@ -608,9 +940,31 @@ var PipelineDriver = class {
 		const projectedTotalTimeMs = projectedAdvancementTimeMs(elapsed, pos, numChanges);
 		const shouldFinish = shouldFinishLateAdvancement(pos, numChanges);
 		if (!shouldFinish && shouldResetProjectedAdvancement(elapsed, projectedTotalTimeMs, pos, numChanges, totalHydrationTimeMs)) this.#throwProjectedAdvancementReset(pos, numChanges, elapsed, projectedTotalTimeMs, totalHydrationTimeMs);
-		if (!shouldFinish && elapsed > MIN_ADVANCEMENT_TIME_LIMIT_MS && (elapsed > totalHydrationTimeMs || elapsed > totalHydrationTimeMs / 2 && pos <= numChanges / 2)) throw new ResetPipelinesSignal(`Advancement exceeded timeout at ${pos} of ${numChanges} changes after ${elapsed} ms. Advancement time limited based on total hydration time of ${totalHydrationTimeMs} ms.`, "advancement-timeout");
+		if (!shouldFinish && elapsed > MIN_ADVANCEMENT_TIME_LIMIT_MS && elapsed > totalHydrationTimeMs / 2 && (projectedTotalTimeMs === void 0 || projectedTotalTimeMs - elapsed > totalHydrationTimeMs)) throw new ResetPipelinesSignal(`Advancement exceeded timeout at ${pos} of ${numChanges} changes after ${elapsed} ms. Advancement time limited based on total hydration time of ${totalHydrationTimeMs} ms.`, "advancement-timeout");
 		return checkYield && advanceTimer.elapsedLap() > this.#yieldThresholdMs();
 	}
+	/**
+	* The rows an advancement holds in memory are bounded by its reservation,
+	* but their width is not known in advance. So the bytes they are estimated
+	* to hold are added to those held by the other advancements on this worker.
+	* Says whether that takes them past the budget, or if the rows are not
+	* bounded by the reservation after all.
+	*/
+	#holdPendingRows(advanceContext) {
+		const { reservedRows, heldBytes, pos, numChanges } = advanceContext;
+		if (reservedRows === void 0) return "fits";
+		const budget = must(this.#deferredWrites);
+		const rows = this.pendingRows;
+		const bytes = this.pendingBytes;
+		advanceContext.heldBytes = bytes;
+		const bytesFit = budget.holdBytes(bytes - heldBytes);
+		if (rows > reservedRows) {
+			budget.recordRowOverrun();
+			this.#lc.error?.(`Advancement holds ${rows} rows at ${pos} of ${numChanges} changes, more than the ${reservedRows} it reserved. Writing through the rest.`);
+			return "row-overrun";
+		}
+		return bytesFit ? "fits" : "bytes";
+	}
 	#throwSlowCurrentChangeReset(pos, numChanges, elapsed, currentChangeElapsedMs, totalHydrationTimeMs) {
 		throw new ResetPipelinesSignal(`Advancement exceeded timeout processing current change at ${pos} of ${numChanges} changes after ${currentChangeElapsedMs} ms (${elapsed} ms total). Advancement time limited based on total hydration time of ${totalHydrationTimeMs} ms.`, "advancement-timeout");
 	}
@@ -634,6 +988,26 @@ var PipelineDriver = class {
 			if (this.#streamer !== null) this.#stopAccumulating();
 		}
 	}
+	/**
+	* Converts a change pushed out of a query pipeline into row changes during
+	* the push. The relationships of a pushed node are lazy, and operators such
+	* as Join compute them from the state of the push in progress: while a child
+	* change is pushed to each matching parent in turn, parents not yet pushed
+	* must not see it. Read after the push has moved on to the next parent, or
+	* after it has finished, a node's relationships show the later state, and
+	* rows that are also pushed separately are counted twice.
+	*/
+	*#streamPushed(queryID, schema, change) {
+		const streamer = this.#streamer;
+		assert(streamer, "must #startAccumulating() before pushing changes");
+		for (const rowChange of streamer.streamChange(queryID, schema, change)) {
+			if (rowChange === "yield") {
+				yield rowChange;
+				continue;
+			}
+			must(this.#streamer).add(rowChange);
+		}
+	}
 	#startAccumulating() {
 		assert(this.#streamer === null, "Streamer already started");
 		this.#streamer = new Streamer(must(this.#primaryKeys), this.#tableSpecs, (queryID, error) => this.#logQueryFailure(queryID, "query pipeline failed", error));
@@ -664,6 +1038,14 @@ var Streamer = class {
 		this.#logQueryFailure = logQueryFailure;
 	}
 	#changes = [];
+	/** Row changes that were already produced by {@link streamChange}. */
+	#rowChanges = [];
+	add(rowChange) {
+		this.#rowChanges.push(rowChange);
+	}
+	streamChange(queryID, schema, change) {
+		return this.#streamChanges(queryID, schema, [change]);
+	}
 	accumulate(queryID, schema, changes) {
 		this.#changes.push([
 			queryID,
@@ -673,6 +1055,7 @@ var Streamer = class {
 		return this;
 	}
 	*stream() {
+		yield* this.#rowChanges;
 		for (const [queryID, schema, changes] of this.#changes) try {
 			yield* this.#streamChanges(queryID, schema, changes);
 		} catch (e) {
@@ -782,6 +1165,18 @@ var QueryFailureLoggingOperator = class {
 			throw e;
 		}
 	}
+	*reconcile(_pusher) {
+		if (this.#output.reconcile) try {
+			yield* this.#output.reconcile(this);
+		} catch (e) {
+			logQueryFailure(this.#lc, {
+				queryHash: this.#queryHash,
+				transformationHash: this.#transformationHash,
+				queryName: this.#queryName
+			}, "query pipeline failed during reconcile", e);
+			throw e;
+		}
+	}
 };
 function logQueryFailure(lc, queryInfo, message, error) {
 	if (error instanceof ResetPipelinesSignal) return;
@@ -808,18 +1203,27 @@ function* toAdds(nodes) {
 function getRowKey(cols, row) {
 	return Object.fromEntries(cols.map((col) => [col, must(row[col])]));
 }
+/** Whether `rowKey` has exactly the columns of `primaryKey`. */
+function isKeyedBy(rowKey, primaryKey) {
+	let cols = 0;
+	for (const col in rowKey) {
+		if (!primaryKey.includes(col)) return false;
+		cols++;
+	}
+	return cols === primaryKey.length;
+}
 /**
 * Core hydration logic used by {@link PipelineDriver#addQuery}, extracted to a
 * function for reuse by the analyze-query RPC path so that analysis hydrates
 * queries the same way the view-syncer does in production.
 */
-function* hydrate(input, hash, clientSchema, tableSpecs) {
+function hydrate(input, hash, clientSchema, tableSpecs) {
 	const res = input.fetch({});
-	yield* new Streamer(buildPrimaryKeys(clientSchema), tableSpecs).accumulate(hash, input.getSchema(), toAdds(res)).stream();
+	return new Streamer(buildPrimaryKeys(clientSchema), tableSpecs).accumulate(hash, input.getSchema(), toAdds(res)).stream();
 }
-function* hydrateInternal(input, hash, primaryKeys, tableSpecs) {
+function hydrateInternal(input, hash, primaryKeys, tableSpecs) {
 	const res = input.fetch({});
-	yield* new Streamer(primaryKeys, tableSpecs).accumulate(hash, input.getSchema(), toAdds(res)).stream();
+	return new Streamer(primaryKeys, tableSpecs).accumulate(hash, input.getSchema(), toAdds(res)).stream();
 }
 function buildPrimaryKeys(clientSchema, primaryKeys = /* @__PURE__ */ new Map()) {
 	for (const [tableName, { primaryKey }] of Object.entries(clientSchema.tables)) primaryKeys.set(tableName, primaryKey);
@@ -828,7 +1232,7 @@ function buildPrimaryKeys(clientSchema, primaryKeys = /* @__PURE__ */ new Map())
 function mustGetPrimaryKey(primaryKeys, table) {
 	const pKeys = must(primaryKeys, "primaryKey map must be non-null");
 	const rv = pKeys.get(table);
-	assert(rv, () => `table '${table}' is not one of: ${[...pKeys.keys()].sort()}. Check the spelling and ensure that the table has a primary key.`);
+	assert(rv, () => `table '${table}' is not one of: ${JSON.stringify([...pKeys.keys()].sort())}. Check the spelling and ensure that the table has a primary key.`);
 	return rv;
 }
 /**