@rocicorp/zero 1.9.1-canary.1 → 1.10.0-canary.1

package/out/zero-cache/src/services/replicator/sqlite-change-log-purger.js

@@ -0,0 +1,283 @@
+import { assert } from "../../../../shared/src/asserts.js";
+import { CHANGE_LOG_STREAM_TABLE } from "./change-log-db.js";
+//#region ../zero-cache/src/services/replicator/sqlite-change-log-purger.ts
+/**
+* Deletes aged-out transactions from the change-log database, one bounded write
+* transaction at a time.
+*
+* The purger is a pure function of one database: it takes the floors its caller
+* has already gated on and narrows them, never widens them, and it reads no
+* replication state. That is what makes it testable without a scheduler and
+* what lets slice 9 run it from the change-streamer's stream loop, between the
+* writer's commits, on the writer's own connection.
+*/
+/**
+* The eligible set, as three ANDed bounds. Only the `externalFloor` is a safety
+* property; the other two make the log serviceable and make purge conservative.
+*
+* `"watermark" < @externalFloor` is deliberately strict. A follower that lost
+* its replica restores it from S3 at watermark `W` and then asks this log for
+* everything after `W`, which requires the `commit` row *at* `W` to still be
+* here (`SQLITE_CHANGE_LOG_BOUNDARY_SQL`). Deleting it returns `too-old` to the
+* very subscriber the floor exists to protect.
+*
+* The head cap reads `max("watermark")` from the log's own database, which
+* keeps the purger a pure function of one file. The cap is inert in normal
+* operation: the floor is derived from a backup of a replica that consumes this
+* loop's output, and the log commits before that output is forwarded, so
+* `externalFloor <= head` holds by construction. It engages only on a *stale*
+* log — writer stopped, mode flipped to `off`, another task took over — where
+* deleting to a floor that has run past a frozen log would empty the file. Note
+* that head can be a phantom — committed here but not yet re-deliverable by a
+* resumed stream — for as long as it takes the watermark the stream would
+* resume from to advance past it. That is harmless precisely because head is
+* never a purge candidate, and it is why the purger asserts nothing about
+* anything outside its own file.
+*
+* Ordered by `("writeTimeMs", "watermark")` so it rides the partial index,
+* which carries one entry per transaction rather than one per change. The
+* `LIMIT` keeps a drain from re-scanning the remaining history on every batch,
+* which would be quadratic in the number of eligible transactions and would do
+* it inside the `BEGIN IMMEDIATE`, holding the write lock alongside the delete.
+*
+* Exported so the focused query-plan test covers the production query.
+*/
+var SQLITE_CHANGE_LOG_ELIGIBLE_COMMITS_SQL = `
+  SELECT "watermark"
+  FROM "${CHANGE_LOG_STREAM_TABLE}"
+  WHERE "writeTimeMs" IS NOT NULL
+    AND "writeTimeMs" < @retentionCutoffMs
+    AND "watermark" < @externalFloor
+    AND "watermark" < (SELECT max("watermark") FROM "${CHANGE_LOG_STREAM_TABLE}")
+  ORDER BY "writeTimeMs", "watermark"
+  LIMIT @limit
+`;
+/**
+* Counts the rows at `@watermark`, capped at `@limit`. The cap is what keeps
+* batch sizing O(budget): this runs per candidate inside the
+* `BEGIN IMMEDIATE`, and the transaction being sized can be arbitrarily
+* large — an uncapped count of a multi-million-row backfill would rescan
+* every remaining row on every tear batch, holding the write lock (and the
+* appending path behind it) for the duration, quadratically over the drain.
+* The caller only needs to know whether the transaction fits its remaining
+* budget, so it passes `remaining + 1` and reads a count above `remaining`
+* as "does not fit".
+*
+* Exported so the focused tests cover the production query.
+*/
+var SQLITE_CHANGE_LOG_COUNT_TRANSACTION_SQL = `
+  SELECT count(*) AS "rows" FROM (
+    SELECT 1
+    FROM "${CHANGE_LOG_STREAM_TABLE}"
+    WHERE "watermark" = @watermark
+    LIMIT @limit
+  )
+`;
+/**
+* A prefix delete, so no transaction between the minimum and the head is ever
+* split. The `<=` is correct and is not the floor comparison: `deletedThrough`
+* is a watermark this batch already established as wholly eligible.
+*/
+var DELETE_THROUGH_SQL = `
+  DELETE FROM "${CHANGE_LOG_STREAM_TABLE}" WHERE "watermark" <= ?
+`;
+var MIN_WATERMARK_SQL = `
+  SELECT min("watermark") AS "minWatermark" FROM "${CHANGE_LOG_STREAM_TABLE}"
+`;
+/**
+* The `pos` at `@offset` rows into the torn transaction, ascending. `undefined`
+* when fewer than `@offset` rows remain, which is how the tear knows it is on
+* its final chunk.
+*/
+var TEAR_BOUNDARY_SQL = `
+  SELECT "pos"
+  FROM "${CHANGE_LOG_STREAM_TABLE}"
+  WHERE "watermark" = @watermark
+  ORDER BY "pos"
+  LIMIT 1 OFFSET @offset
+`;
+/**
+* A range scan on the primary key. Expressed as `"pos" < @pos` rather than
+* `DELETE ... LIMIT n`, which is both non-portable and the wrong bound: it
+* carries no guarantee about *which* rows it removes, and the commit row must
+* survive until the chunk that finishes the tear.
+*/
+var DELETE_BELOW_POS_SQL = `
+  DELETE FROM "${CHANGE_LOG_STREAM_TABLE}"
+  WHERE "watermark" = @watermark AND "pos" < @pos
+`;
+var SQLiteChangeLogPurger = class {
+	#db;
+	#now;
+	#stmts;
+	/**
+	* The measured row budget, carried across batches. Row cost varies with
+	* payload size, so `maxRows` alone cannot bound a statement's duration; this
+	* shrinks when a delete overruns `maxDurationMs` and grows back when the
+	* budget — rather than the eligible set — was what limited the batch.
+	*/
+	#budgetRows;
+	/**
+	* @param db a writable connection to a change log the writer has already
+	*     created and reconciled — in slice 9, the writer's own connection.
+	*     Statements are prepared eagerly, so a caller that may run before the
+	*     log exists opens the connection lazily and treats construction failure
+	*     as a skipped cycle.
+	*/
+	constructor(db, now = performance.now.bind(performance)) {
+		this.#db = db;
+		this.#now = now;
+		this.#stmts = {
+			eligibleCommits: db.prepare(SQLITE_CHANGE_LOG_ELIGIBLE_COMMITS_SQL),
+			countTransaction: db.prepare(SQLITE_CHANGE_LOG_COUNT_TRANSACTION_SQL),
+			deleteThrough: db.prepare(DELETE_THROUGH_SQL),
+			minWatermark: db.prepare(MIN_WATERMARK_SQL),
+			tearBoundary: db.prepare(TEAR_BOUNDARY_SQL),
+			deleteBelowPos: db.prepare(DELETE_BELOW_POS_SQL)
+		};
+	}
+	/** The row budget the next batch would use. Exposed for tests and metrics. */
+	get budgetRows() {
+		return this.#budgetRows;
+	}
+	/**
+	* Removes one bounded batch of aged-out history, in one `BEGIN IMMEDIATE`
+	* transaction. Callers loop while `moreEligible`, releasing whatever guards
+	* they hold between batches.
+	*/
+	purgeBatch(opts) {
+		const { maxRows, maxDurationMs } = opts;
+		assert(Number.isSafeInteger(maxRows) && maxRows > 0, "change-log purge maxRows must be a positive safe integer");
+		assert(maxDurationMs > 0, "change-log purge maxDurationMs must be positive");
+		this.#db.exec("BEGIN IMMEDIATE");
+		try {
+			const result = this.#purge(opts);
+			this.#db.exec("COMMIT");
+			return result;
+		} catch (e) {
+			if (this.#db.inTransaction) this.#db.exec("ROLLBACK");
+			throw e;
+		}
+	}
+	#purge(opts) {
+		const { externalFloor, retentionCutoffMs } = opts;
+		const budget = this.#budget(opts.maxRows);
+		const limit = Math.max(1, Math.ceil(budget / 2));
+		const candidates = this.#stmts.eligibleCommits.all({
+			retentionCutoffMs,
+			externalFloor,
+			limit
+		});
+		if (candidates.length === 0) return {
+			deletedRows: 0,
+			deletedThrough: void 0,
+			moreEligible: false
+		};
+		let rows = 0;
+		let deletedThrough;
+		for (const { watermark } of candidates) {
+			const remaining = budget - rows;
+			const { rows: n } = this.#stmts.countTransaction.get({
+				watermark,
+				limit: remaining + 1
+			});
+			if (n > remaining) break;
+			rows += n;
+			deletedThrough = watermark;
+		}
+		if (deletedThrough === void 0) return this.#tear(opts, budget);
+		return {
+			deletedRows: this.#timed(opts, budget, () => this.#stmts.deleteThrough.run(deletedThrough).changes),
+			deletedThrough,
+			moreEligible: this.#anyEligible(opts)
+		};
+	}
+	/**
+	* Removes one bounded chunk of the minimum transaction, which is the only
+	* transaction that is ever torn.
+	*
+	* A single upstream transaction can be arbitrarily large — a backfill, a
+	* schema migration — and SQLite cannot yield mid-statement, so the only way
+	* to bound the lock hold is to delete it across several statements. That is
+	* unobservable given three constraints, all of which live here:
+	*
+	* 1. Only `min("watermark")` is torn, so at most one transaction is ever
+	*    partial. A reader never reads *into* a transaction — `read()` starts
+	*    strictly after `(fromWatermark, MAX_SAFE_INTEGER)` — so the only
+	*    transaction a tear can touch is one a subscriber reads *from*, and
+	*    reading from it does not read its rows.
+	* 2. Rows go ascending by `pos`, commit row last. `plan()`'s boundary check
+	*    reads the *highest* `pos` at the watermark and requires it to be the
+	*    `commit`; removing that row first would give a subscriber sitting
+	*    exactly there a spurious `too-old`.
+	* 3. The commit row is removed by a prefix delete, which advances
+	*    `min("watermark")` in the same SQLite transaction, so no state exposes
+	*    the boundary as gone while the minimum still points at it. Normally that
+	*    is {@link SQLiteChangeLogPurger.purgeBatch}'s ordinary whole-transaction
+	*    delete, taken on the batch where what is left of the torn transaction
+	*    finally fits the budget; the branch below is the same delete for the
+	*    case where the minimum is not itself in the eligible set.
+	*
+	* A crash mid-tear needs no recovery state: the torn transaction is still the
+	* minimum and still eligible, so the next batch continues it. Reconciliation
+	* is unaffected — it tests the head, and a tear is at the tail.
+	*
+	* Tearing the minimum is safe even in the unusual case where it is not itself
+	* in the eligible set (a writer whose clock went backwards can put a later
+	* watermark at an earlier `writeTimeMs`). Both watermark bounds are
+	* prefix-closed — a non-empty eligible set implies `min < externalFloor` and
+	* `min < head` — and the prefix delete this batch would otherwise run removes
+	* the minimum anyway. Only the time floor, which is a minimum-retention
+	* courtesy rather than a safety property, can be crossed that way.
+	*/
+	#tear(opts, budget) {
+		const { minWatermark } = this.#stmts.minWatermark.get();
+		assert(minWatermark !== null, "change-log purge found eligible transactions in an empty log");
+		const boundary = this.#stmts.tearBoundary.get({
+			watermark: minWatermark,
+			offset: budget
+		});
+		if (boundary === void 0) return {
+			deletedRows: this.#timed(opts, budget, () => this.#stmts.deleteThrough.run(minWatermark).changes),
+			deletedThrough: minWatermark,
+			moreEligible: this.#anyEligible(opts)
+		};
+		return {
+			deletedRows: this.#timed(opts, budget, () => this.#stmts.deleteBelowPos.run({
+				watermark: minWatermark,
+				pos: boundary.pos
+			}).changes),
+			deletedThrough: void 0,
+			moreEligible: true
+		};
+	}
+	#anyEligible({ externalFloor, retentionCutoffMs }) {
+		return this.#stmts.eligibleCommits.get({
+			retentionCutoffMs,
+			externalFloor,
+			limit: 1
+		}) !== void 0;
+	}
+	#budget(maxRows) {
+		return Math.max(1, Math.min(maxRows, this.#budgetRows ?? maxRows));
+	}
+	/**
+	* Runs a delete and feeds its measured duration back into the row budget.
+	* Growth is gated on the budget having been the binding constraint: a batch
+	* that finished quickly because only four rows were eligible is no evidence
+	* that a larger statement would stay under the target.
+	*/
+	#timed({ maxRows, maxDurationMs }, budget, run) {
+		const start = this.#now();
+		const deletedRows = run();
+		const elapsedMs = this.#now() - start;
+		if (elapsedMs > maxDurationMs) this.#budgetRows = Math.max(1, Math.floor(budget / 2));
+		else if (deletedRows >= budget && elapsedMs * 2 <= maxDurationMs) this.#budgetRows = Math.min(maxRows, budget * 2);
+		else this.#budgetRows = budget;
+		return deletedRows;
+	}
+};
+//#endregion
+export { SQLiteChangeLogPurger };
+
+//# sourceMappingURL=sqlite-change-log-purger.js.map

package/out/zero-cache/src/services/replicator/sqlite-change-log-purger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-change-log-purger.js","names":["#db","#now","#stmts","#budgetRows","#purge","#budget","#tear","#timed","#anyEligible"],"sources":["../../../../../../zero-cache/src/services/replicator/sqlite-change-log-purger.ts"],"sourcesContent":["/**\n * Deletes aged-out transactions from the change-log database, one bounded write\n * transaction at a time.\n *\n * The purger is a pure function of one database: it takes the floors its caller\n * has already gated on and narrows them, never widens them, and it reads no\n * replication state. That is what makes it testable without a scheduler and\n * what lets slice 9 run it from the change-streamer's stream loop, between the\n * writer's commits, on the writer's own connection.\n */\n\nimport {assert} from '../../../../shared/src/asserts.ts';\nimport type {Database, Statement} from '../../../../zqlite/src/db.ts';\nimport {CHANGE_LOG_STREAM_TABLE} from './change-log-db.ts';\n\n/**\n * The eligible set, as three ANDed bounds. Only the `externalFloor` is a safety\n * property; the other two make the log serviceable and make purge conservative.\n *\n * `\"watermark\" < @externalFloor` is deliberately strict. A follower that lost\n * its replica restores it from S3 at watermark `W` and then asks this log for\n * everything after `W`, which requires the `commit` row *at* `W` to still be\n * here (`SQLITE_CHANGE_LOG_BOUNDARY_SQL`). Deleting it returns `too-old` to the\n * very subscriber the floor exists to protect.\n *\n * The head cap reads `max(\"watermark\")` from the log's own database, which\n * keeps the purger a pure function of one file. The cap is inert in normal\n * operation: the floor is derived from a backup of a replica that consumes this\n * loop's output, and the log commits before that output is forwarded, so\n * `externalFloor <= head` holds by construction. It engages only on a *stale*\n * log — writer stopped, mode flipped to `off`, another task took over — where\n * deleting to a floor that has run past a frozen log would empty the file. Note\n * that head can be a phantom — committed here but not yet re-deliverable by a\n * resumed stream — for as long as it takes the watermark the stream would\n * resume from to advance past it. That is harmless precisely because head is\n * never a purge candidate, and it is why the purger asserts nothing about\n * anything outside its own file.\n *\n * Ordered by `(\"writeTimeMs\", \"watermark\")` so it rides the partial index,\n * which carries one entry per transaction rather than one per change. The\n * `LIMIT` keeps a drain from re-scanning the remaining history on every batch,\n * which would be quadratic in the number of eligible transactions and would do\n * it inside the `BEGIN IMMEDIATE`, holding the write lock alongside the delete.\n *\n * Exported so the focused query-plan test covers the production query.\n */\nexport const SQLITE_CHANGE_LOG_ELIGIBLE_COMMITS_SQL = /*sql*/ `\n  SELECT \"watermark\"\n  FROM \"${CHANGE_LOG_STREAM_TABLE}\"\n  WHERE \"writeTimeMs\" IS NOT NULL\n    AND \"writeTimeMs\" < @retentionCutoffMs\n    AND \"watermark\" < @externalFloor\n    AND \"watermark\" < (SELECT max(\"watermark\") FROM \"${CHANGE_LOG_STREAM_TABLE}\")\n  ORDER BY \"writeTimeMs\", \"watermark\"\n  LIMIT @limit\n`;\n\n/**\n * Counts the rows at `@watermark`, capped at `@limit`. The cap is what keeps\n * batch sizing O(budget): this runs per candidate inside the\n * `BEGIN IMMEDIATE`, and the transaction being sized can be arbitrarily\n * large — an uncapped count of a multi-million-row backfill would rescan\n * every remaining row on every tear batch, holding the write lock (and the\n * appending path behind it) for the duration, quadratically over the drain.\n * The caller only needs to know whether the transaction fits its remaining\n * budget, so it passes `remaining + 1` and reads a count above `remaining`\n * as \"does not fit\".\n *\n * Exported so the focused tests cover the production query.\n */\nexport const SQLITE_CHANGE_LOG_COUNT_TRANSACTION_SQL = /*sql*/ `\n  SELECT count(*) AS \"rows\" FROM (\n    SELECT 1\n    FROM \"${CHANGE_LOG_STREAM_TABLE}\"\n    WHERE \"watermark\" = @watermark\n    LIMIT @limit\n  )\n`;\n\n/**\n * A prefix delete, so no transaction between the minimum and the head is ever\n * split. The `<=` is correct and is not the floor comparison: `deletedThrough`\n * is a watermark this batch already established as wholly eligible.\n */\nconst DELETE_THROUGH_SQL = /*sql*/ `\n  DELETE FROM \"${CHANGE_LOG_STREAM_TABLE}\" WHERE \"watermark\" <= ?\n`;\n\nconst MIN_WATERMARK_SQL = /*sql*/ `\n  SELECT min(\"watermark\") AS \"minWatermark\" FROM \"${CHANGE_LOG_STREAM_TABLE}\"\n`;\n\n/**\n * The `pos` at `@offset` rows into the torn transaction, ascending. `undefined`\n * when fewer than `@offset` rows remain, which is how the tear knows it is on\n * its final chunk.\n */\nconst TEAR_BOUNDARY_SQL = /*sql*/ `\n  SELECT \"pos\"\n  FROM \"${CHANGE_LOG_STREAM_TABLE}\"\n  WHERE \"watermark\" = @watermark\n  ORDER BY \"pos\"\n  LIMIT 1 OFFSET @offset\n`;\n\n/**\n * A range scan on the primary key. Expressed as `\"pos\" < @pos` rather than\n * `DELETE ... LIMIT n`, which is both non-portable and the wrong bound: it\n * carries no guarantee about *which* rows it removes, and the commit row must\n * survive until the chunk that finishes the tear.\n */\nconst DELETE_BELOW_POS_SQL = /*sql*/ `\n  DELETE FROM \"${CHANGE_LOG_STREAM_TABLE}\"\n  WHERE \"watermark\" = @watermark AND \"pos\" < @pos\n`;\n\nexport type PurgeBatchResult = {\n  readonly deletedRows: number;\n  /**\n   * The watermark through which whole transactions were removed. `undefined`\n   * when the batch only tore rows off the minimum transaction without\n   * completing it — in that case `deletedRows > 0` and `moreEligible` is true.\n   */\n  readonly deletedThrough: string | undefined;\n  /** True while a tear is in progress, as well as while whole transactions remain eligible. */\n  readonly moreEligible: boolean;\n};\n\nexport type PurgeBatchOptions = {\n  /**\n   * The floor the caller has already gated on subscriber ACKs and snapshot\n   * reservations — normally the confirmed S3 backup watermark. Transactions at\n   * or above it are NOT durable anywhere else: the change log is excluded from\n   * the litestream backup, so this is the boundary a follower restores to and\n   * then catches up from. Compared strictly (`<`), so the transaction *at* the\n   * floor survives as that follower's catchup boundary. The purger narrows this\n   * input and never widens it.\n   */\n  readonly externalFloor: string;\n  /**\n   * A *minimum* retention, ANDed on top of `externalFloor` rather than an\n   * alternative to it. Which of the two binds depends on the backup interval.\n   */\n  readonly retentionCutoffMs: number;\n  /** Starting chunk size. Not the bound — `maxDurationMs` is. */\n  readonly maxRows: number;\n  /**\n   * The statement duration target, enforced by feedback rather than by\n   * interruption: SQLite cannot yield mid-statement, so the purger measures\n   * each delete and shrinks the next batch's row budget when one overruns\n   * (see {@link SQLiteChangeLogPurger.budgetRows}) — which means the first\n   * delete after a restart, sized by `maxRows` alone, can still overrun it.\n   * The target is this consequential because purge shares the writer's\n   * connection: there is no lock to arbitrate and no `busy_timeout` to bound\n   * the wait — a long statement blocks the appending path, and the forward\n   * behind it, directly and for its full duration. That is why this is a\n   * precondition of purging from the stream loop rather than a tuning knob.\n   */\n  readonly maxDurationMs: number;\n};\n\ntype Statements = {\n  readonly eligibleCommits: Statement;\n  readonly countTransaction: Statement;\n  readonly deleteThrough: Statement;\n  readonly minWatermark: Statement;\n  readonly tearBoundary: Statement;\n  readonly deleteBelowPos: Statement;\n};\n\nexport class SQLiteChangeLogPurger {\n  readonly #db: Database;\n  readonly #now: () => number;\n  readonly #stmts: Statements;\n\n  /**\n   * The measured row budget, carried across batches. Row cost varies with\n   * payload size, so `maxRows` alone cannot bound a statement's duration; this\n   * shrinks when a delete overruns `maxDurationMs` and grows back when the\n   * budget — rather than the eligible set — was what limited the batch.\n   */\n  #budgetRows: number | undefined;\n\n  /**\n   * @param db a writable connection to a change log the writer has already\n   *     created and reconciled — in slice 9, the writer's own connection.\n   *     Statements are prepared eagerly, so a caller that may run before the\n   *     log exists opens the connection lazily and treats construction failure\n   *     as a skipped cycle.\n   */\n  constructor(\n    db: Database,\n    now: () => number = performance.now.bind(performance),\n  ) {\n    this.#db = db;\n    this.#now = now;\n    this.#stmts = {\n      eligibleCommits: db.prepare(SQLITE_CHANGE_LOG_ELIGIBLE_COMMITS_SQL),\n      countTransaction: db.prepare(SQLITE_CHANGE_LOG_COUNT_TRANSACTION_SQL),\n      deleteThrough: db.prepare(DELETE_THROUGH_SQL),\n      minWatermark: db.prepare(MIN_WATERMARK_SQL),\n      tearBoundary: db.prepare(TEAR_BOUNDARY_SQL),\n      deleteBelowPos: db.prepare(DELETE_BELOW_POS_SQL),\n    };\n  }\n\n  /** The row budget the next batch would use. Exposed for tests and metrics. */\n  get budgetRows(): number | undefined {\n    return this.#budgetRows;\n  }\n\n  /**\n   * Removes one bounded batch of aged-out history, in one `BEGIN IMMEDIATE`\n   * transaction. Callers loop while `moreEligible`, releasing whatever guards\n   * they hold between batches.\n   */\n  purgeBatch(opts: PurgeBatchOptions): PurgeBatchResult {\n    const {maxRows, maxDurationMs} = opts;\n    assert(\n      Number.isSafeInteger(maxRows) && maxRows > 0,\n      'change-log purge maxRows must be a positive safe integer',\n    );\n    assert(\n      maxDurationMs > 0,\n      'change-log purge maxDurationMs must be positive',\n    );\n\n    this.#db.exec('BEGIN IMMEDIATE');\n    try {\n      const result = this.#purge(opts);\n      this.#db.exec('COMMIT');\n      return result;\n    } catch (e) {\n      if (this.#db.inTransaction) {\n        this.#db.exec('ROLLBACK');\n      }\n      throw e;\n    }\n  }\n\n  #purge(opts: PurgeBatchOptions): PurgeBatchResult {\n    const {externalFloor, retentionCutoffMs} = opts;\n    const budget = this.#budget(opts.maxRows);\n    // Each transaction is at least a `begin` and a `commit`, so this is the\n    // most candidates that can fit in the budget.\n    const limit = Math.max(1, Math.ceil(budget / 2));\n    const candidates = this.#stmts.eligibleCommits.all<{watermark: string}>({\n      retentionCutoffMs,\n      externalFloor,\n      limit,\n    });\n    if (candidates.length === 0) {\n      return {deletedRows: 0, deletedThrough: undefined, moreEligible: false};\n    }\n\n    // Accounted per candidate rather than per prefix, which is exact as long as\n    // the candidates arrive in watermark order — they do, because the single\n    // writer stamps `writeTimeMs` at commit time. A clock that went backwards\n    // can put a non-candidate below `deletedThrough`, and the prefix delete\n    // then removes more rows than were counted. Not a safety problem: both\n    // watermark bounds are prefix-closed, only the minimum-retention courtesy\n    // is crossed, and `maxRows` is the starting chunk size rather than the\n    // bound — `maxDurationMs` is, and the governor measures what actually ran.\n    let rows = 0;\n    let deletedThrough: string | undefined;\n    for (const {watermark} of candidates) {\n      // The count is capped at one past the remaining budget: `n > remaining`\n      // is exactly `rows + n > budget` for a fitting transaction, and a\n      // too-large one stops scanning as soon as it is known not to fit.\n      const remaining = budget - rows;\n      const {rows: n} = this.#stmts.countTransaction.get<{rows: number}>({\n        watermark,\n        limit: remaining + 1,\n      });\n      if (n > remaining) {\n        break;\n      }\n      rows += n;\n      deletedThrough = watermark;\n    }\n\n    if (deletedThrough === undefined) {\n      return this.#tear(opts, budget);\n    }\n    const deletedRows = this.#timed(\n      opts,\n      budget,\n      () => this.#stmts.deleteThrough.run(deletedThrough).changes,\n    );\n    return {\n      deletedRows,\n      deletedThrough,\n      moreEligible: this.#anyEligible(opts),\n    };\n  }\n\n  /**\n   * Removes one bounded chunk of the minimum transaction, which is the only\n   * transaction that is ever torn.\n   *\n   * A single upstream transaction can be arbitrarily large — a backfill, a\n   * schema migration — and SQLite cannot yield mid-statement, so the only way\n   * to bound the lock hold is to delete it across several statements. That is\n   * unobservable given three constraints, all of which live here:\n   *\n   * 1. Only `min(\"watermark\")` is torn, so at most one transaction is ever\n   *    partial. A reader never reads *into* a transaction — `read()` starts\n   *    strictly after `(fromWatermark, MAX_SAFE_INTEGER)` — so the only\n   *    transaction a tear can touch is one a subscriber reads *from*, and\n   *    reading from it does not read its rows.\n   * 2. Rows go ascending by `pos`, commit row last. `plan()`'s boundary check\n   *    reads the *highest* `pos` at the watermark and requires it to be the\n   *    `commit`; removing that row first would give a subscriber sitting\n   *    exactly there a spurious `too-old`.\n   * 3. The commit row is removed by a prefix delete, which advances\n   *    `min(\"watermark\")` in the same SQLite transaction, so no state exposes\n   *    the boundary as gone while the minimum still points at it. Normally that\n   *    is {@link SQLiteChangeLogPurger.purgeBatch}'s ordinary whole-transaction\n   *    delete, taken on the batch where what is left of the torn transaction\n   *    finally fits the budget; the branch below is the same delete for the\n   *    case where the minimum is not itself in the eligible set.\n   *\n   * A crash mid-tear needs no recovery state: the torn transaction is still the\n   * minimum and still eligible, so the next batch continues it. Reconciliation\n   * is unaffected — it tests the head, and a tear is at the tail.\n   *\n   * Tearing the minimum is safe even in the unusual case where it is not itself\n   * in the eligible set (a writer whose clock went backwards can put a later\n   * watermark at an earlier `writeTimeMs`). Both watermark bounds are\n   * prefix-closed — a non-empty eligible set implies `min < externalFloor` and\n   * `min < head` — and the prefix delete this batch would otherwise run removes\n   * the minimum anyway. Only the time floor, which is a minimum-retention\n   * courtesy rather than a safety property, can be crossed that way.\n   */\n  #tear(opts: PurgeBatchOptions, budget: number): PurgeBatchResult {\n    const {minWatermark} = this.#stmts.minWatermark.get<{\n      minWatermark: string | null;\n    }>();\n    assert(\n      minWatermark !== null,\n      'change-log purge found eligible transactions in an empty log',\n    );\n\n    const boundary = this.#stmts.tearBoundary.get<{pos: number} | undefined>({\n      watermark: minWatermark,\n      offset: budget,\n    });\n    if (boundary === undefined) {\n      // At most `budget` rows are left at the minimum, which is reachable only\n      // when the minimum is not the transaction that failed to fit — i.e. when\n      // it is not itself eligible. The prefix delete removes it whole and\n      // advances `min(\"watermark\")`.\n      const deletedRows = this.#timed(\n        opts,\n        budget,\n        () => this.#stmts.deleteThrough.run(minWatermark).changes,\n      );\n      return {\n        deletedRows,\n        deletedThrough: minWatermark,\n        moreEligible: this.#anyEligible(opts),\n      };\n    }\n    // `boundary.pos` is the `budget`-th row by `pos`, so this removes exactly\n    // `budget` rows and always makes progress. The commit row is the highest\n    // `pos`, so it can only be reached by the branch above.\n    const deletedRows = this.#timed(\n      opts,\n      budget,\n      () =>\n        this.#stmts.deleteBelowPos.run({\n          watermark: minWatermark,\n          pos: boundary.pos,\n        }).changes,\n    );\n    return {deletedRows, deletedThrough: undefined, moreEligible: true};\n  }\n\n  #anyEligible({externalFloor, retentionCutoffMs}: PurgeBatchOptions): boolean {\n    return (\n      this.#stmts.eligibleCommits.get<{watermark: string} | undefined>({\n        retentionCutoffMs,\n        externalFloor,\n        limit: 1,\n      }) !== undefined\n    );\n  }\n\n  #budget(maxRows: number): number {\n    return Math.max(1, Math.min(maxRows, this.#budgetRows ?? maxRows));\n  }\n\n  /**\n   * Runs a delete and feeds its measured duration back into the row budget.\n   * Growth is gated on the budget having been the binding constraint: a batch\n   * that finished quickly because only four rows were eligible is no evidence\n   * that a larger statement would stay under the target.\n   */\n  #timed(\n    {maxRows, maxDurationMs}: PurgeBatchOptions,\n    budget: number,\n    run: () => number,\n  ): number {\n    const start = this.#now();\n    const deletedRows = run();\n    const elapsedMs = this.#now() - start;\n\n    if (elapsedMs > maxDurationMs) {\n      this.#budgetRows = Math.max(1, Math.floor(budget / 2));\n    } else if (deletedRows >= budget && elapsedMs * 2 <= maxDurationMs) {\n      this.#budgetRows = Math.min(maxRows, budget * 2);\n    } else {\n      this.#budgetRows = budget;\n    }\n    return deletedRows;\n  }\n}\n"],"mappings":"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"}

package/out/zero-cache/src/services/replicator/write-worker.js

@@ -18,7 +18,11 @@ function createAPI() {
 	let mode;
 	let lc;
 	let replicaDbPath;
-	let unregisterCorruptionDiagnosticTarget;
+	let unregisterCorruptionDiagnosticTargets = [];
+	function unregisterCorruptionDiagnostics() {
+		unregisterCorruptionDiagnosticTargets.forEach((unregister) => unregister());
+		unregisterCorruptionDiagnosticTargets = [];
+	}
 	function handleCorruptedDb(err) {
 		if (!lc || !replicaDbPath || !isSQLiteCorruption(err)) return;
 		logSQLiteCorruptionDiagnostics(lc, "write-worker", replicaDbPath, err);
@@ -39,11 +43,11 @@ function createAPI() {
 		init(dbPath, cpMode, pragmas, logConfig) {
 			replicaDbPath = dbPath;
 			lc = createLogContext({ log: logConfig }, "write-worker");
-			unregisterCorruptionDiagnosticTarget?.();
-			unregisterCorruptionDiagnosticTarget = registerSQLiteCorruptionDiagnosticTarget({
+			unregisterCorruptionDiagnostics();
+			unregisterCorruptionDiagnosticTargets.push(registerSQLiteCorruptionDiagnosticTarget({
 				debugName: "write-worker",
 				dbPath
-			});
+			}));
 			try {
 				db = new Database(lc, dbPath);
 				applyPragmas(db, pragmas);
@@ -81,8 +85,7 @@ function createAPI() {
 			runner = void 0;
 			processor = void 0;
 			replicaDbPath = void 0;
-			unregisterCorruptionDiagnosticTarget?.();
-			unregisterCorruptionDiagnosticTarget = void 0;
+			unregisterCorruptionDiagnostics();
 		}
 	};
 }

package/out/zero-cache/src/services/replicator/write-worker.js.map

@@ -1 +1 @@
-{"version":3,"file":"write-worker.js","names":[],"sources":["../../../../../../zero-cache/src/services/replicator/write-worker.ts"],"sourcesContent":["import {parentPort} from 'node:worker_threads';\nimport type {LogContext} from '@rocicorp/logger';\nimport type {LogConfig} from '../../../../shared/src/logging.ts';\nimport {must} from '../../../../shared/src/must.ts';\nimport {Database} from '../../../../zqlite/src/db.ts';\nimport {deleteLiteDB} from '../../db/delete-lite-db.ts';\nimport {\n  isSQLiteCorruption,\n  logSQLiteCorruptionDiagnostics,\n  registerSQLiteCorruptionDiagnosticTarget,\n} from '../../db/sqlite-corruption.ts';\nimport {StatementRunner} from '../../db/statements.ts';\nimport {createLogContext} from '../../server/logging.ts';\nimport type {ChangeStreamData} from '../change-source/protocol/current/downstream.ts';\nimport {ChangeProcessor, type ChangeProcessorMode} from './change-processor.ts';\nimport {getSubscriptionState} from './schema/replication-state.ts';\nimport {\n  applyPragmas,\n  serializeError,\n  type ArgsMap,\n  type Method,\n  type PragmaConfig,\n  type Request,\n  type Response,\n  type ResultMap,\n  type WriteError,\n} from './write-worker-client.ts';\n\nif (!parentPort) {\n  throw new Error('write-worker must be run as a worker thread');\n}\n\nconst port = parentPort;\n\ntype API = {[M in Method]: (...args: ArgsMap[M]) => ResultMap[M]};\n\nfunction createAPI(): API {\n  let db: Database | undefined;\n  let runner: StatementRunner | undefined;\n  let processor: ChangeProcessor | undefined;\n  let mode: ChangeProcessorMode | undefined;\n  let lc: LogContext | undefined;\n  let replicaDbPath: string | undefined;\n  let unregisterCorruptionDiagnosticTarget: (() => void) | undefined;\n\n  function handleCorruptedDb(err: unknown) {\n    if (!lc || !replicaDbPath || !isSQLiteCorruption(err)) {\n      return;\n    }\n    logSQLiteCorruptionDiagnostics(lc, 'write-worker', replicaDbPath, err);\n    try {\n      lc.warn?.(`deleting corrupted db at ${replicaDbPath}`);\n      deleteLiteDB(replicaDbPath);\n    } catch (e) {\n      lc.warn?.(`error deleting corrupted db at ${replicaDbPath}`, e);\n    }\n  }\n\n  function createProcessor() {\n    processor = new ChangeProcessor(must(runner), must(mode), (_lc, err) => {\n      handleCorruptedDb(err);\n      port.postMessage({\n        writeError: serializeError(err),\n      } satisfies WriteError);\n    });\n  }\n\n  return {\n    init(\n      dbPath: string,\n      cpMode: ChangeProcessorMode,\n      pragmas: PragmaConfig,\n      logConfig: LogConfig,\n    ) {\n      replicaDbPath = dbPath;\n      lc = createLogContext({log: logConfig}, 'write-worker');\n      unregisterCorruptionDiagnosticTarget?.();\n      unregisterCorruptionDiagnosticTarget =\n        registerSQLiteCorruptionDiagnosticTarget({\n          debugName: 'write-worker',\n          dbPath,\n        });\n      try {\n        db = new Database(lc, dbPath);\n        applyPragmas(db, pragmas);\n        runner = new StatementRunner(db);\n        mode = cpMode;\n        createProcessor();\n      } catch (e) {\n        handleCorruptedDb(e);\n        throw e;\n      }\n    },\n\n    getSubscriptionState() {\n      try {\n        return getSubscriptionState(must(runner));\n      } catch (e) {\n        handleCorruptedDb(e);\n        throw e;\n      }\n    },\n\n    processMessage(downstream: ChangeStreamData) {\n      try {\n        return must(processor).processMessage(must(lc), downstream);\n      } catch (e) {\n        handleCorruptedDb(e);\n        throw e;\n      }\n    },\n\n    abort() {\n      must(processor).abort(must(lc));\n      createProcessor();\n    },\n\n    stop() {\n      db?.close();\n      db = undefined;\n      runner = undefined;\n      processor = undefined;\n      replicaDbPath = undefined;\n      unregisterCorruptionDiagnosticTarget?.();\n      unregisterCorruptionDiagnosticTarget = undefined;\n    },\n  };\n}\n\nconst api = createAPI();\n\nport.on('message', (msg: Request) => {\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- TS can't narrow msg.method + msg.args together\n    const result = (api[msg.method] as (...args: any[]) => unknown)(\n      ...msg.args,\n    );\n    // abort is fire-and-forget — no pending slot on the client side.\n    if (msg.method !== 'abort') {\n      port.postMessage({method: msg.method, result} as Response);\n    }\n  } catch (e) {\n    if (msg.method !== 'abort') {\n      port.postMessage({\n        method: msg.method,\n        error: serializeError(e),\n      } as Response);\n    }\n  }\n});\n"],"mappings":";;;;;;;;;;;AA4BA,IAAI,CAAC,YACH,MAAM,IAAI,MAAM,6CAA6C;AAG/D,IAAM,OAAO;AAIb,SAAS,YAAiB;CACxB,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ,IAAI;CAEJ,SAAS,kBAAkB,KAAc;EACvC,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,mBAAmB,GAAG,GAClD;EAEF,+BAA+B,IAAI,gBAAgB,eAAe,GAAG;EACrE,IAAI;GACF,GAAG,OAAO,4BAA4B,eAAe;GACrD,aAAa,aAAa;EAC5B,SAAS,GAAG;GACV,GAAG,OAAO,kCAAkC,iBAAiB,CAAC;EAChE;CACF;CAEA,SAAS,kBAAkB;EACzB,YAAY,IAAI,gBAAgB,KAAK,MAAM,GAAG,KAAK,IAAI,IAAI,KAAK,QAAQ;GACtE,kBAAkB,GAAG;GACrB,KAAK,YAAY,EACf,YAAY,eAAe,GAAG,EAChC,CAAsB;EACxB,CAAC;CACH;CAEA,OAAO;EACL,KACE,QACA,QACA,SACA,WACA;GACA,gBAAgB;GAChB,KAAK,iBAAiB,EAAC,KAAK,UAAS,GAAG,cAAc;GACtD,uCAAuC;GACvC,uCACE,yCAAyC;IACvC,WAAW;IACX;GACF,CAAC;GACH,IAAI;IACF,KAAK,IAAI,SAAS,IAAI,MAAM;IAC5B,aAAa,IAAI,OAAO;IACxB,SAAS,IAAI,gBAAgB,EAAE;IAC/B,OAAO;IACP,gBAAgB;GAClB,SAAS,GAAG;IACV,kBAAkB,CAAC;IACnB,MAAM;GACR;EACF;EAEA,uBAAuB;GACrB,IAAI;IACF,OAAO,qBAAqB,KAAK,MAAM,CAAC;GAC1C,SAAS,GAAG;IACV,kBAAkB,CAAC;IACnB,MAAM;GACR;EACF;EAEA,eAAe,YAA8B;GAC3C,IAAI;IACF,OAAO,KAAK,SAAS,EAAE,eAAe,KAAK,EAAE,GAAG,UAAU;GAC5D,SAAS,GAAG;IACV,kBAAkB,CAAC;IACnB,MAAM;GACR;EACF;EAEA,QAAQ;GACN,KAAK,SAAS,EAAE,MAAM,KAAK,EAAE,CAAC;GAC9B,gBAAgB;EAClB;EAEA,OAAO;GACL,IAAI,MAAM;GACV,KAAK,KAAA;GACL,SAAS,KAAA;GACT,YAAY,KAAA;GACZ,gBAAgB,KAAA;GAChB,uCAAuC;GACvC,uCAAuC,KAAA;EACzC;CACF;AACF;AAEA,IAAM,MAAM,UAAU;AAEtB,KAAK,GAAG,YAAY,QAAiB;CACnC,IAAI;EAEF,MAAM,SAAU,IAAI,IAAI,QACtB,GAAG,IAAI,IACT;EAEA,IAAI,IAAI,WAAW,SACjB,KAAK,YAAY;GAAC,QAAQ,IAAI;GAAQ;EAAM,CAAa;CAE7D,SAAS,GAAG;EACV,IAAI,IAAI,WAAW,SACjB,KAAK,YAAY;GACf,QAAQ,IAAI;GACZ,OAAO,eAAe,CAAC;EACzB,CAAa;CAEjB;AACF,CAAC"}
+{"version":3,"file":"write-worker.js","names":[],"sources":["../../../../../../zero-cache/src/services/replicator/write-worker.ts"],"sourcesContent":["import {parentPort} from 'node:worker_threads';\nimport type {LogContext} from '@rocicorp/logger';\nimport type {LogConfig} from '../../../../shared/src/logging.ts';\nimport {must} from '../../../../shared/src/must.ts';\nimport {Database} from '../../../../zqlite/src/db.ts';\nimport {deleteLiteDB} from '../../db/delete-lite-db.ts';\nimport {\n  isSQLiteCorruption,\n  logSQLiteCorruptionDiagnostics,\n  registerSQLiteCorruptionDiagnosticTarget,\n} from '../../db/sqlite-corruption.ts';\nimport {StatementRunner} from '../../db/statements.ts';\nimport {createLogContext} from '../../server/logging.ts';\nimport type {ChangeStreamData} from '../change-source/protocol/current/downstream.ts';\nimport {ChangeProcessor, type ChangeProcessorMode} from './change-processor.ts';\nimport {getSubscriptionState} from './schema/replication-state.ts';\nimport {\n  applyPragmas,\n  serializeError,\n  type ArgsMap,\n  type Method,\n  type PragmaConfig,\n  type Request,\n  type Response,\n  type ResultMap,\n  type WriteError,\n} from './write-worker-client.ts';\n\nif (!parentPort) {\n  throw new Error('write-worker must be run as a worker thread');\n}\n\nconst port = parentPort;\n\ntype API = {[M in Method]: (...args: ArgsMap[M]) => ResultMap[M]};\n\nfunction createAPI(): API {\n  let db: Database | undefined;\n  let runner: StatementRunner | undefined;\n  let processor: ChangeProcessor | undefined;\n  let mode: ChangeProcessorMode | undefined;\n  let lc: LogContext | undefined;\n  let replicaDbPath: string | undefined;\n  let unregisterCorruptionDiagnosticTargets: (() => void)[] = [];\n\n  function unregisterCorruptionDiagnostics() {\n    unregisterCorruptionDiagnosticTargets.forEach(unregister => unregister());\n    unregisterCorruptionDiagnosticTargets = [];\n  }\n\n  function handleCorruptedDb(err: unknown) {\n    if (!lc || !replicaDbPath || !isSQLiteCorruption(err)) {\n      return;\n    }\n    logSQLiteCorruptionDiagnostics(lc, 'write-worker', replicaDbPath, err);\n    try {\n      lc.warn?.(`deleting corrupted db at ${replicaDbPath}`);\n      deleteLiteDB(replicaDbPath);\n    } catch (e) {\n      lc.warn?.(`error deleting corrupted db at ${replicaDbPath}`, e);\n    }\n  }\n\n  function createProcessor() {\n    processor = new ChangeProcessor(must(runner), must(mode), (_lc, err) => {\n      handleCorruptedDb(err);\n      port.postMessage({\n        writeError: serializeError(err),\n      } satisfies WriteError);\n    });\n  }\n\n  return {\n    init(\n      dbPath: string,\n      cpMode: ChangeProcessorMode,\n      pragmas: PragmaConfig,\n      logConfig: LogConfig,\n    ): void {\n      replicaDbPath = dbPath;\n      lc = createLogContext({log: logConfig}, 'write-worker');\n      unregisterCorruptionDiagnostics();\n      unregisterCorruptionDiagnosticTargets.push(\n        registerSQLiteCorruptionDiagnosticTarget({\n          debugName: 'write-worker',\n          dbPath,\n        }),\n      );\n      try {\n        db = new Database(lc, dbPath);\n        applyPragmas(db, pragmas);\n        runner = new StatementRunner(db);\n        mode = cpMode;\n        createProcessor();\n      } catch (e) {\n        handleCorruptedDb(e);\n        throw e;\n      }\n    },\n\n    getSubscriptionState() {\n      try {\n        return getSubscriptionState(must(runner));\n      } catch (e) {\n        handleCorruptedDb(e);\n        throw e;\n      }\n    },\n\n    processMessage(downstream: ChangeStreamData) {\n      try {\n        return must(processor).processMessage(must(lc), downstream);\n      } catch (e) {\n        handleCorruptedDb(e);\n        throw e;\n      }\n    },\n\n    abort() {\n      must(processor).abort(must(lc));\n      createProcessor();\n    },\n\n    stop() {\n      db?.close();\n      db = undefined;\n      runner = undefined;\n      processor = undefined;\n      replicaDbPath = undefined;\n      unregisterCorruptionDiagnostics();\n    },\n  };\n}\n\nconst api = createAPI();\n\nport.on('message', (msg: Request) => {\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- TS can't narrow msg.method + msg.args together\n    const result = (api[msg.method] as (...args: any[]) => unknown)(\n      ...msg.args,\n    );\n    // abort is fire-and-forget — no pending slot on the client side.\n    if (msg.method !== 'abort') {\n      port.postMessage({method: msg.method, result} as Response);\n    }\n  } catch (e) {\n    if (msg.method !== 'abort') {\n      port.postMessage({\n        method: msg.method,\n        error: serializeError(e),\n      } as Response);\n    }\n  }\n});\n"],"mappings":";;;;;;;;;;;AA4BA,IAAI,CAAC,YACH,MAAM,IAAI,MAAM,6CAA6C;AAG/D,IAAM,OAAO;AAIb,SAAS,YAAiB;CACxB,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ,IAAI,wCAAwD,CAAC;CAE7D,SAAS,kCAAkC;EACzC,sCAAsC,SAAQ,eAAc,WAAW,CAAC;EACxE,wCAAwC,CAAC;CAC3C;CAEA,SAAS,kBAAkB,KAAc;EACvC,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,mBAAmB,GAAG,GAClD;EAEF,+BAA+B,IAAI,gBAAgB,eAAe,GAAG;EACrE,IAAI;GACF,GAAG,OAAO,4BAA4B,eAAe;GACrD,aAAa,aAAa;EAC5B,SAAS,GAAG;GACV,GAAG,OAAO,kCAAkC,iBAAiB,CAAC;EAChE;CACF;CAEA,SAAS,kBAAkB;EACzB,YAAY,IAAI,gBAAgB,KAAK,MAAM,GAAG,KAAK,IAAI,IAAI,KAAK,QAAQ;GACtE,kBAAkB,GAAG;GACrB,KAAK,YAAY,EACf,YAAY,eAAe,GAAG,EAChC,CAAsB;EACxB,CAAC;CACH;CAEA,OAAO;EACL,KACE,QACA,QACA,SACA,WACM;GACN,gBAAgB;GAChB,KAAK,iBAAiB,EAAC,KAAK,UAAS,GAAG,cAAc;GACtD,gCAAgC;GAChC,sCAAsC,KACpC,yCAAyC;IACvC,WAAW;IACX;GACF,CAAC,CACH;GACA,IAAI;IACF,KAAK,IAAI,SAAS,IAAI,MAAM;IAC5B,aAAa,IAAI,OAAO;IACxB,SAAS,IAAI,gBAAgB,EAAE;IAC/B,OAAO;IACP,gBAAgB;GAClB,SAAS,GAAG;IACV,kBAAkB,CAAC;IACnB,MAAM;GACR;EACF;EAEA,uBAAuB;GACrB,IAAI;IACF,OAAO,qBAAqB,KAAK,MAAM,CAAC;GAC1C,SAAS,GAAG;IACV,kBAAkB,CAAC;IACnB,MAAM;GACR;EACF;EAEA,eAAe,YAA8B;GAC3C,IAAI;IACF,OAAO,KAAK,SAAS,EAAE,eAAe,KAAK,EAAE,GAAG,UAAU;GAC5D,SAAS,GAAG;IACV,kBAAkB,CAAC;IACnB,MAAM;GACR;EACF;EAEA,QAAQ;GACN,KAAK,SAAS,EAAE,MAAM,KAAK,EAAE,CAAC;GAC9B,gBAAgB;EAClB;EAEA,OAAO;GACL,IAAI,MAAM;GACV,KAAK,KAAA;GACL,SAAS,KAAA;GACT,YAAY,KAAA;GACZ,gBAAgB,KAAA;GAChB,gCAAgC;EAClC;CACF;AACF;AAEA,IAAM,MAAM,UAAU;AAEtB,KAAK,GAAG,YAAY,QAAiB;CACnC,IAAI;EAEF,MAAM,SAAU,IAAI,IAAI,QACtB,GAAG,IAAI,IACT;EAEA,IAAI,IAAI,WAAW,SACjB,KAAK,YAAY;GAAC,QAAQ,IAAI;GAAQ;EAAM,CAAa;CAE7D,SAAS,GAAG;EACV,IAAI,IAAI,WAAW,SACjB,KAAK,YAAY;GACf,QAAQ,IAAI;GACZ,OAAO,eAAe,CAAC;EACzB,CAAa;CAEjB;AACF,CAAC"}

package/out/zero-cache/src/services/run-ast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-ast.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/services/run-ast.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAQjD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,oDAAoD,CAAC;AAC3F,OAAO,KAAK,EAAC,GAAG,EAAe,MAAM,mCAAmC,CAAC;AAEzE,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,6CAA6C,CAAC;AAG9E,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,kDAAkD,CAAC;AACxF,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,yCAAyC,CAAC;AACxE,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,qCAAqC,CAAC;AAI7C,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,gDAAgD,CAAC;AACxF,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,2CAA2C,CAAC;AAC5E,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,2BAA2B,CAAC;AAExD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAG7C,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,gBAAgB,CAAC;AAGnD,MAAM,MAAM,aAAa,GAAG;IAC1B,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,oBAAoB,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC9C,SAAS,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC5C,EAAE,EAAE,QAAQ,CAAC;IACb,IAAI,EAAE,eAAe,CAAC;IACtB,WAAW,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC5C,YAAY,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IACxC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,wBAAsB,MAAM,CAC1B,EAAE,EAAE,UAAU,EACd,YAAY,EAAE,YAAY,EAC1B,GAAG,EAAE,GAAG,EACR,aAAa,EAAE,OAAO,EACtB,OAAO,EAAE,aAAa,EACtB,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAChC,OAAO,CAAC,kBAAkB,CAAC,CA6I7B"}
+{"version":3,"file":"run-ast.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/services/run-ast.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAQjD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,oDAAoD,CAAC;AAC3F,OAAO,KAAK,EAAC,GAAG,EAAe,MAAM,mCAAmC,CAAC;AAEzE,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,6CAA6C,CAAC;AAG9E,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,kDAAkD,CAAC;AACxF,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,yCAAyC,CAAC;AACxE,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,qCAAqC,CAAC;AAI7C,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,gDAAgD,CAAC;AACxF,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,2CAA2C,CAAC;AAC5E,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,2BAA2B,CAAC;AAExD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAG7C,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,gBAAgB,CAAC;AAGnD,MAAM,MAAM,aAAa,GAAG;IAC1B,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,oBAAoB,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC9C,SAAS,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC5C,EAAE,EAAE,QAAQ,CAAC;IACb,IAAI,EAAE,eAAe,CAAC;IACtB,WAAW,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC5C,YAAY,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IACxC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,wBAAsB,MAAM,CAC1B,EAAE,EAAE,UAAU,EACd,YAAY,EAAE,YAAY,EAC1B,GAAG,EAAE,GAAG,EACR,aAAa,EAAE,OAAO,EACtB,OAAO,EAAE,aAAa,EACtB,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAsJ7B"}

package/out/zero-cache/src/services/run-ast.js

@@ -40,7 +40,8 @@ async function runAst(lc, clientSchema, ast, isTransformed, options, yieldProces
 		input.destroy();
 		return node ? node.row[childField] ?? null : void 0;
 	};
-	const { ast: resolvedAst } = resolveSimpleScalarSubqueries(ast, options.tableSpecs, executor);
+	const { ast: resolvedAst, ignoredScalarHints } = resolveSimpleScalarSubqueries(ast, options.tableSpecs, executor);
+	for (const { table, uniqueKeys } of ignoredScalarHints) lc.warn?.(`Ignoring {scalar: true} on the "${table}" subquery: it does not constrain every column of any unique key [${uniqueKeys.map((k) => `(${k.join(", ")})`).join(", ")}] to a literal with "=", so it is not provably limited to one row. The gate runs as a plain EXISTS.`);
 	const pipeline = buildPipeline(resolvedAst, host, "query-id", options.costModel, lc, options.planDebugger);
 	const start = performance.now();
 	let syncedRowCount = 0;

package/out/zero-cache/src/services/run-ast.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-ast.js","names":[],"sources":["../../../../../zero-cache/src/services/run-ast.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\n// @circular-dep-ignore\nimport {astToZQL} from '../../../ast-to-zql/src/ast-to-zql.ts';\n// @circular-dep-ignore\nimport {formatOutput} from '../../../ast-to-zql/src/format.ts';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport {sleep} from '../../../shared/src/sleep.ts';\nimport type {AnalyzeQueryResult} from '../../../zero-protocol/src/analyze-query-result.ts';\nimport type {AST, LiteralValue} from '../../../zero-protocol/src/ast.ts';\nimport {mapAST} from '../../../zero-protocol/src/ast.ts';\nimport type {ClientSchema} from '../../../zero-protocol/src/client-schema.ts';\nimport type {Row} from '../../../zero-protocol/src/data.ts';\nimport {hashOfAST} from '../../../zero-protocol/src/query-hash.ts';\nimport type {PermissionsConfig} from '../../../zero-schema/src/compiled-permissions.ts';\nimport type {NameMapper} from '../../../zero-schema/src/name-mapper.ts';\nimport {\n  buildPipeline,\n  type BuilderDelegate,\n} from '../../../zql/src/builder/builder.ts';\nimport {ChangeType} from '../../../zql/src/ivm/change-type.ts';\nimport type {Node} from '../../../zql/src/ivm/data.ts';\nimport {skipYields} from '../../../zql/src/ivm/operator.ts';\nimport type {ConnectionCostModel} from '../../../zql/src/planner/planner-connection.ts';\nimport type {PlanDebugger} from '../../../zql/src/planner/planner-debug.ts';\nimport type {Database} from '../../../zqlite/src/db.ts';\nimport {resolveSimpleScalarSubqueries} from '../../../zqlite/src/resolve-scalar-subqueries.ts';\nimport type {JWTAuth} from '../auth/auth.ts';\nimport {transformAndHashQuery} from '../auth/read-authorizer.ts';\nimport {computeZqlSpecs} from '../db/lite-tables.ts';\nimport type {LiteAndZqlSpec} from '../db/specs.ts';\nimport {hydrate} from './view-syncer/pipeline-driver.ts';\n\nexport type RunAstOptions = {\n  applyPermissions?: boolean | undefined;\n  auth?: JWTAuth | undefined;\n  clientToServerMapper?: NameMapper | undefined;\n  costModel?: ConnectionCostModel | undefined;\n  db: Database;\n  host: BuilderDelegate;\n  permissions?: PermissionsConfig | undefined;\n  planDebugger?: PlanDebugger | undefined;\n  syncedRows?: boolean | undefined;\n  tableSpecs: Map<string, LiteAndZqlSpec>;\n  vendedRows?: boolean | undefined;\n};\n\nexport async function runAst(\n  lc: LogContext,\n  clientSchema: ClientSchema,\n  ast: AST,\n  isTransformed: boolean,\n  options: RunAstOptions,\n  yieldProcess: () => Promise<void>,\n): Promise<AnalyzeQueryResult> {\n  const {clientToServerMapper, permissions, host, db} = options;\n  const result: AnalyzeQueryResult = {\n    warnings: [],\n    syncedRows: undefined,\n    syncedRowCount: 0,\n    start: 0,\n    end: 0,\n    elapsed: 0,\n    afterPermissions: undefined,\n    readRows: undefined,\n    readRowCountsByQuery: {},\n    readRowCount: undefined,\n  };\n\n  if (!isTransformed) {\n    // map the AST to server names if not already transformed\n    ast = mapAST(ast, must(clientToServerMapper));\n  }\n  if (options.applyPermissions) {\n    const auth = options.auth;\n    if (!auth) {\n      result.warnings.push(\n        'No auth data provided. Permission rules will compare to `NULL` wherever an auth data field is referenced.',\n      );\n    }\n    ast = transformAndHashQuery(\n      lc,\n      'clientGroupIDForAnalyze',\n      ast,\n      must(permissions),\n      auth,\n      false,\n    ).transformedAst;\n    result.afterPermissions = await formatOutput(ast.table + astToZQL(ast));\n  }\n\n  // Resolve scalar subqueries (e.g. whereExists with {scalar: true}) to\n  // literal equality conditions so that SQLite can use indexes effectively.\n  // Without this, correlated subqueries get stripped from SQL filters and\n  // queries on large tables fall back to full table scans.\n  const executor = (\n    subqueryAST: AST,\n    childField: string,\n  ): LiteralValue | null | undefined => {\n    const input = buildPipeline(subqueryAST, host, 'scalar-subquery');\n    // Consume the full stream rather than using first() to avoid\n    // triggering early return on Take's #initialFetch assertion.\n    // The subquery AST already has limit: 1, so at most one row is produced.\n    let node: Node | undefined;\n    for (const n of skipYields(input.fetch({}))) {\n      node ??= n;\n    }\n    input.destroy();\n    return node ? ((node.row[childField] as LiteralValue) ?? null) : undefined;\n  };\n\n  const {ast: resolvedAst} = resolveSimpleScalarSubqueries(\n    ast,\n    options.tableSpecs,\n    executor,\n  );\n\n  const pipeline = buildPipeline(\n    resolvedAst,\n    host,\n    'query-id',\n    options.costModel,\n    lc,\n    options.planDebugger,\n  );\n\n  const start = performance.now();\n\n  let syncedRowCount = 0;\n  const rowsByTable: Record<string, Row[]> = {};\n  const seenByTable: Set<string> = new Set();\n  for (const rowChange of hydrate(\n    pipeline,\n    hashOfAST(resolvedAst),\n    clientSchema,\n    computeZqlSpecs(lc, db, {includeBackfillingColumns: false}),\n  )) {\n    if (rowChange === 'yield') {\n      await yieldProcess();\n      continue;\n    }\n    assert(\n      rowChange.type === ChangeType.ADD,\n      'Hydration only handles add row changes',\n    );\n\n    // yield to other tasks to avoid blocking for too long\n    if (syncedRowCount % 10 === 0) {\n      await Promise.resolve();\n    }\n    if (syncedRowCount % 100 === 0) {\n      await sleep(1);\n    }\n\n    let rows: Row[] = rowsByTable[rowChange.table];\n    const s = rowChange.table + '.' + JSON.stringify(rowChange.row);\n    if (seenByTable.has(s)) {\n      continue; // skip duplicates\n    }\n    syncedRowCount++;\n    seenByTable.add(s);\n    if (options.syncedRows) {\n      if (!rows) {\n        rows = [];\n        rowsByTable[rowChange.table] = rows;\n      }\n      rows.push(rowChange.row);\n    }\n  }\n\n  const end = performance.now();\n  if (options.syncedRows) {\n    result.syncedRows = rowsByTable;\n  }\n  result.start = start;\n  result.end = end;\n  result.elapsed = end - start;\n\n  // Always include the count of synced and vended rows.\n  result.syncedRowCount = syncedRowCount;\n  result.readRowCountsByQuery = host.debug?.getVendedRowCounts() ?? {};\n  let readRowCount = 0;\n  for (const c of Object.values(result.readRowCountsByQuery)) {\n    for (const v of Object.values(c)) {\n      readRowCount += v;\n    }\n  }\n  result.readRowCount = readRowCount;\n  result.dbScansByQuery = host.debug?.getNVisitCounts() ?? {};\n  result.sqlitePlans = host.debug?.getSQLitePlans() ?? {};\n\n  if (options.vendedRows) {\n    result.readRows = host.debug?.getVendedRows();\n  }\n  return result;\n}\n"],"mappings":";;;;;;;;;;;;;;AA+CA,eAAsB,OACpB,IACA,cACA,KACA,eACA,SACA,cAC6B;CAC7B,MAAM,EAAC,sBAAsB,aAAa,MAAM,OAAM;CACtD,MAAM,SAA6B;EACjC,UAAU,CAAC;EACX,YAAY,KAAA;EACZ,gBAAgB;EAChB,OAAO;EACP,KAAK;EACL,SAAS;EACT,kBAAkB,KAAA;EAClB,UAAU,KAAA;EACV,sBAAsB,CAAC;EACvB,cAAc,KAAA;CAChB;CAEA,IAAI,CAAC,eAEH,MAAM,OAAO,KAAK,KAAK,oBAAoB,CAAC;CAE9C,IAAI,QAAQ,kBAAkB;EAC5B,MAAM,OAAO,QAAQ;EACrB,IAAI,CAAC,MACH,OAAO,SAAS,KACd,2GACF;EAEF,MAAM,sBACJ,IACA,2BACA,KACA,KAAK,WAAW,GAChB,MACA,KACF,EAAE;EACF,OAAO,mBAAmB,MAAM,aAAa,IAAI,QAAQ,SAAS,GAAG,CAAC;CACxE;CAMA,MAAM,YACJ,aACA,eACoC;EACpC,MAAM,QAAQ,cAAc,aAAa,MAAM,iBAAiB;EAIhE,IAAI;EACJ,KAAK,MAAM,KAAK,WAAW,MAAM,MAAM,CAAC,CAAC,CAAC,GACxC,SAAS;EAEX,MAAM,QAAQ;EACd,OAAO,OAAS,KAAK,IAAI,eAAgC,OAAQ,KAAA;CACnE;CAEA,MAAM,EAAC,KAAK,gBAAe,8BACzB,KACA,QAAQ,YACR,QACF;CAEA,MAAM,WAAW,cACf,aACA,MACA,YACA,QAAQ,WACR,IACA,QAAQ,YACV;CAEA,MAAM,QAAQ,YAAY,IAAI;CAE9B,IAAI,iBAAiB;CACrB,MAAM,cAAqC,CAAC;CAC5C,MAAM,8BAA2B,IAAI,IAAI;CACzC,KAAK,MAAM,aAAa,QACtB,UACA,UAAU,WAAW,GACrB,cACA,gBAAgB,IAAI,IAAI,EAAC,2BAA2B,MAAK,CAAC,CAC5D,GAAG;EACD,IAAI,cAAc,SAAS;GACzB,MAAM,aAAa;GACnB;EACF;EACA,OACE,UAAU,SAAS,GACnB,wCACF;EAGA,IAAI,iBAAiB,OAAO,GAC1B,MAAM,QAAQ,QAAQ;EAExB,IAAI,iBAAiB,QAAQ,GAC3B,MAAM,MAAM,CAAC;EAGf,IAAI,OAAc,YAAY,UAAU;EACxC,MAAM,IAAI,UAAU,QAAQ,MAAM,KAAK,UAAU,UAAU,GAAG;EAC9D,IAAI,YAAY,IAAI,CAAC,GACnB;EAEF;EACA,YAAY,IAAI,CAAC;EACjB,IAAI,QAAQ,YAAY;GACtB,IAAI,CAAC,MAAM;IACT,OAAO,CAAC;IACR,YAAY,UAAU,SAAS;GACjC;GACA,KAAK,KAAK,UAAU,GAAG;EACzB;CACF;CAEA,MAAM,MAAM,YAAY,IAAI;CAC5B,IAAI,QAAQ,YACV,OAAO,aAAa;CAEtB,OAAO,QAAQ;CACf,OAAO,MAAM;CACb,OAAO,UAAU,MAAM;CAGvB,OAAO,iBAAiB;CACxB,OAAO,uBAAuB,KAAK,OAAO,mBAAmB,KAAK,CAAC;CACnE,IAAI,eAAe;CACnB,KAAK,MAAM,KAAK,OAAO,OAAO,OAAO,oBAAoB,GACvD,KAAK,MAAM,KAAK,OAAO,OAAO,CAAC,GAC7B,gBAAgB;CAGpB,OAAO,eAAe;CACtB,OAAO,iBAAiB,KAAK,OAAO,gBAAgB,KAAK,CAAC;CAC1D,OAAO,cAAc,KAAK,OAAO,eAAe,KAAK,CAAC;CAEtD,IAAI,QAAQ,YACV,OAAO,WAAW,KAAK,OAAO,cAAc;CAE9C,OAAO;AACT"}
+{"version":3,"file":"run-ast.js","names":[],"sources":["../../../../../zero-cache/src/services/run-ast.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\n// @circular-dep-ignore\nimport {astToZQL} from '../../../ast-to-zql/src/ast-to-zql.ts';\n// @circular-dep-ignore\nimport {formatOutput} from '../../../ast-to-zql/src/format.ts';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport {sleep} from '../../../shared/src/sleep.ts';\nimport type {AnalyzeQueryResult} from '../../../zero-protocol/src/analyze-query-result.ts';\nimport type {AST, LiteralValue} from '../../../zero-protocol/src/ast.ts';\nimport {mapAST} from '../../../zero-protocol/src/ast.ts';\nimport type {ClientSchema} from '../../../zero-protocol/src/client-schema.ts';\nimport type {Row} from '../../../zero-protocol/src/data.ts';\nimport {hashOfAST} from '../../../zero-protocol/src/query-hash.ts';\nimport type {PermissionsConfig} from '../../../zero-schema/src/compiled-permissions.ts';\nimport type {NameMapper} from '../../../zero-schema/src/name-mapper.ts';\nimport {\n  buildPipeline,\n  type BuilderDelegate,\n} from '../../../zql/src/builder/builder.ts';\nimport {ChangeType} from '../../../zql/src/ivm/change-type.ts';\nimport type {Node} from '../../../zql/src/ivm/data.ts';\nimport {skipYields} from '../../../zql/src/ivm/operator.ts';\nimport type {ConnectionCostModel} from '../../../zql/src/planner/planner-connection.ts';\nimport type {PlanDebugger} from '../../../zql/src/planner/planner-debug.ts';\nimport type {Database} from '../../../zqlite/src/db.ts';\nimport {resolveSimpleScalarSubqueries} from '../../../zqlite/src/resolve-scalar-subqueries.ts';\nimport type {JWTAuth} from '../auth/auth.ts';\nimport {transformAndHashQuery} from '../auth/read-authorizer.ts';\nimport {computeZqlSpecs} from '../db/lite-tables.ts';\nimport type {LiteAndZqlSpec} from '../db/specs.ts';\nimport {hydrate} from './view-syncer/pipeline-driver.ts';\n\nexport type RunAstOptions = {\n  applyPermissions?: boolean | undefined;\n  auth?: JWTAuth | undefined;\n  clientToServerMapper?: NameMapper | undefined;\n  costModel?: ConnectionCostModel | undefined;\n  db: Database;\n  host: BuilderDelegate;\n  permissions?: PermissionsConfig | undefined;\n  planDebugger?: PlanDebugger | undefined;\n  syncedRows?: boolean | undefined;\n  tableSpecs: Map<string, LiteAndZqlSpec>;\n  vendedRows?: boolean | undefined;\n};\n\nexport async function runAst(\n  lc: LogContext,\n  clientSchema: ClientSchema,\n  ast: AST,\n  isTransformed: boolean,\n  options: RunAstOptions,\n  yieldProcess: () => Promise<void>,\n): Promise<AnalyzeQueryResult> {\n  const {clientToServerMapper, permissions, host, db} = options;\n  const result: AnalyzeQueryResult = {\n    warnings: [],\n    syncedRows: undefined,\n    syncedRowCount: 0,\n    start: 0,\n    end: 0,\n    elapsed: 0,\n    afterPermissions: undefined,\n    readRows: undefined,\n    readRowCountsByQuery: {},\n    readRowCount: undefined,\n  };\n\n  if (!isTransformed) {\n    // map the AST to server names if not already transformed\n    ast = mapAST(ast, must(clientToServerMapper));\n  }\n  if (options.applyPermissions) {\n    const auth = options.auth;\n    if (!auth) {\n      result.warnings.push(\n        'No auth data provided. Permission rules will compare to `NULL` wherever an auth data field is referenced.',\n      );\n    }\n    ast = transformAndHashQuery(\n      lc,\n      'clientGroupIDForAnalyze',\n      ast,\n      must(permissions),\n      auth,\n      false,\n    ).transformedAst;\n    result.afterPermissions = await formatOutput(ast.table + astToZQL(ast));\n  }\n\n  // Resolve scalar subqueries (e.g. whereExists with {scalar: true}) to\n  // literal equality conditions so that SQLite can use indexes effectively.\n  // Without this, correlated subqueries get stripped from SQL filters and\n  // queries on large tables fall back to full table scans.\n  const executor = (\n    subqueryAST: AST,\n    childField: string,\n  ): LiteralValue | null | undefined => {\n    const input = buildPipeline(subqueryAST, host, 'scalar-subquery');\n    // Consume the full stream rather than using first() to avoid\n    // triggering early return on Take's #initialFetch assertion.\n    // The subquery AST already has limit: 1, so at most one row is produced.\n    let node: Node | undefined;\n    for (const n of skipYields(input.fetch({}))) {\n      node ??= n;\n    }\n    input.destroy();\n    return node ? ((node.row[childField] as LiteralValue) ?? null) : undefined;\n  };\n\n  const {ast: resolvedAst, ignoredScalarHints} = resolveSimpleScalarSubqueries(\n    ast,\n    options.tableSpecs,\n    executor,\n  );\n  for (const {table, uniqueKeys} of ignoredScalarHints) {\n    lc.warn?.(\n      `Ignoring {scalar: true} on the \"${table}\" subquery: it does not ` +\n        `constrain every column of any unique key ` +\n        `[${uniqueKeys.map(k => `(${k.join(', ')})`).join(', ')}] to a ` +\n        `literal with \"=\", so it is not provably limited to one row. ` +\n        `The gate runs as a plain EXISTS.`,\n    );\n  }\n\n  const pipeline = buildPipeline(\n    resolvedAst,\n    host,\n    'query-id',\n    options.costModel,\n    lc,\n    options.planDebugger,\n  );\n\n  const start = performance.now();\n\n  let syncedRowCount = 0;\n  const rowsByTable: Record<string, Row[]> = {};\n  const seenByTable: Set<string> = new Set();\n  for (const rowChange of hydrate(\n    pipeline,\n    hashOfAST(resolvedAst),\n    clientSchema,\n    computeZqlSpecs(lc, db, {includeBackfillingColumns: false}),\n  )) {\n    if (rowChange === 'yield') {\n      await yieldProcess();\n      continue;\n    }\n    assert(\n      rowChange.type === ChangeType.ADD,\n      'Hydration only handles add row changes',\n    );\n\n    // yield to other tasks to avoid blocking for too long\n    if (syncedRowCount % 10 === 0) {\n      await Promise.resolve();\n    }\n    if (syncedRowCount % 100 === 0) {\n      await sleep(1);\n    }\n\n    let rows: Row[] = rowsByTable[rowChange.table];\n    const s = rowChange.table + '.' + JSON.stringify(rowChange.row);\n    if (seenByTable.has(s)) {\n      continue; // skip duplicates\n    }\n    syncedRowCount++;\n    seenByTable.add(s);\n    if (options.syncedRows) {\n      if (!rows) {\n        rows = [];\n        rowsByTable[rowChange.table] = rows;\n      }\n      rows.push(rowChange.row);\n    }\n  }\n\n  const end = performance.now();\n  if (options.syncedRows) {\n    result.syncedRows = rowsByTable;\n  }\n  result.start = start;\n  result.end = end;\n  result.elapsed = end - start;\n\n  // Always include the count of synced and vended rows.\n  result.syncedRowCount = syncedRowCount;\n  result.readRowCountsByQuery = host.debug?.getVendedRowCounts() ?? {};\n  let readRowCount = 0;\n  for (const c of Object.values(result.readRowCountsByQuery)) {\n    for (const v of Object.values(c)) {\n      readRowCount += v;\n    }\n  }\n  result.readRowCount = readRowCount;\n  result.dbScansByQuery = host.debug?.getNVisitCounts() ?? {};\n  result.sqlitePlans = host.debug?.getSQLitePlans() ?? {};\n\n  if (options.vendedRows) {\n    result.readRows = host.debug?.getVendedRows();\n  }\n  return result;\n}\n"],"mappings":";;;;;;;;;;;;;;AA+CA,eAAsB,OACpB,IACA,cACA,KACA,eACA,SACA,cAC6B;CAC7B,MAAM,EAAC,sBAAsB,aAAa,MAAM,OAAM;CACtD,MAAM,SAA6B;EACjC,UAAU,CAAC;EACX,YAAY,KAAA;EACZ,gBAAgB;EAChB,OAAO;EACP,KAAK;EACL,SAAS;EACT,kBAAkB,KAAA;EAClB,UAAU,KAAA;EACV,sBAAsB,CAAC;EACvB,cAAc,KAAA;CAChB;CAEA,IAAI,CAAC,eAEH,MAAM,OAAO,KAAK,KAAK,oBAAoB,CAAC;CAE9C,IAAI,QAAQ,kBAAkB;EAC5B,MAAM,OAAO,QAAQ;EACrB,IAAI,CAAC,MACH,OAAO,SAAS,KACd,2GACF;EAEF,MAAM,sBACJ,IACA,2BACA,KACA,KAAK,WAAW,GAChB,MACA,KACF,EAAE;EACF,OAAO,mBAAmB,MAAM,aAAa,IAAI,QAAQ,SAAS,GAAG,CAAC;CACxE;CAMA,MAAM,YACJ,aACA,eACoC;EACpC,MAAM,QAAQ,cAAc,aAAa,MAAM,iBAAiB;EAIhE,IAAI;EACJ,KAAK,MAAM,KAAK,WAAW,MAAM,MAAM,CAAC,CAAC,CAAC,GACxC,SAAS;EAEX,MAAM,QAAQ;EACd,OAAO,OAAS,KAAK,IAAI,eAAgC,OAAQ,KAAA;CACnE;CAEA,MAAM,EAAC,KAAK,aAAa,uBAAsB,8BAC7C,KACA,QAAQ,YACR,QACF;CACA,KAAK,MAAM,EAAC,OAAO,gBAAe,oBAChC,GAAG,OACD,mCAAmC,MAAM,oEAEnC,WAAW,KAAI,MAAK,IAAI,EAAE,KAAK,IAAI,EAAE,EAAE,EAAE,KAAK,IAAI,EAAE,oGAG5D;CAGF,MAAM,WAAW,cACf,aACA,MACA,YACA,QAAQ,WACR,IACA,QAAQ,YACV;CAEA,MAAM,QAAQ,YAAY,IAAI;CAE9B,IAAI,iBAAiB;CACrB,MAAM,cAAqC,CAAC;CAC5C,MAAM,8BAA2B,IAAI,IAAI;CACzC,KAAK,MAAM,aAAa,QACtB,UACA,UAAU,WAAW,GACrB,cACA,gBAAgB,IAAI,IAAI,EAAC,2BAA2B,MAAK,CAAC,CAC5D,GAAG;EACD,IAAI,cAAc,SAAS;GACzB,MAAM,aAAa;GACnB;EACF;EACA,OACE,UAAU,SAAS,GACnB,wCACF;EAGA,IAAI,iBAAiB,OAAO,GAC1B,MAAM,QAAQ,QAAQ;EAExB,IAAI,iBAAiB,QAAQ,GAC3B,MAAM,MAAM,CAAC;EAGf,IAAI,OAAc,YAAY,UAAU;EACxC,MAAM,IAAI,UAAU,QAAQ,MAAM,KAAK,UAAU,UAAU,GAAG;EAC9D,IAAI,YAAY,IAAI,CAAC,GACnB;EAEF;EACA,YAAY,IAAI,CAAC;EACjB,IAAI,QAAQ,YAAY;GACtB,IAAI,CAAC,MAAM;IACT,OAAO,CAAC;IACR,YAAY,UAAU,SAAS;GACjC;GACA,KAAK,KAAK,UAAU,GAAG;EACzB;CACF;CAEA,MAAM,MAAM,YAAY,IAAI;CAC5B,IAAI,QAAQ,YACV,OAAO,aAAa;CAEtB,OAAO,QAAQ;CACf,OAAO,MAAM;CACb,OAAO,UAAU,MAAM;CAGvB,OAAO,iBAAiB;CACxB,OAAO,uBAAuB,KAAK,OAAO,mBAAmB,KAAK,CAAC;CACnE,IAAI,eAAe;CACnB,KAAK,MAAM,KAAK,OAAO,OAAO,OAAO,oBAAoB,GACvD,KAAK,MAAM,KAAK,OAAO,OAAO,CAAC,GAC7B,gBAAgB;CAGpB,OAAO,eAAe;CACtB,OAAO,iBAAiB,KAAK,OAAO,gBAAgB,KAAK,CAAC;CAC1D,OAAO,cAAc,KAAK,OAAO,eAAe,KAAK,CAAC;CAEtD,IAAI,QAAQ,YACV,OAAO,WAAW,KAAK,OAAO,cAAc;CAE9C,OAAO;AACT"}

package/out/zero-cache/src/services/running-state.d.ts

@@ -32,7 +32,7 @@ export declare class RunningState {
     /**
      * Sets a Timeout that is automatically cancelled if the service is cancelled.
      */
-    setTimeout<TArgs extends unknown[]>(fn: (...args: TArgs) => void, timeoutMs: number, ...args: TArgs): void;
+    setTimeout<TArgs extends unknown[]>(fn: (...args: TArgs) => void, timeoutMs: number, ...args: TArgs): NodeJS.Timeout;
     /**
      * Returns a promise that resolves after `ms` milliseconds or when
      * the service is stopped.

package/out/zero-cache/src/services/running-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"running-state.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/services/running-state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAGjD,OAAO,EAAC,cAAc,EAAC,MAAM,8BAA8B,CAAC;AAI5D,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAEhD,MAAM,MAAM,WAAW,GAAG;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC;AAEtC;;GAEG;AACH,qBAAa,YAAY;;gBAarB,WAAW,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,WAAW,EACzB,YAAY,oBAAa,EACzB,OAAO,wBAAiB;IA+B1B,IAAI,MAAM,IAAI,WAAW,CAExB;IAED,IAAI,UAAU,WAEb;IAED;;;;;OAKG;IACH,SAAS,IAAI,OAAO;IAIpB;;;OAGG;IACH,YAAY,CAAC,CAAC,EAAE,UAAU,GAAG,YAAY;IAMzC;;OAEG;IACH,UAAU,CAAC,KAAK,SAAS,OAAO,EAAE,EAChC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI,EAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,IAAI,EAAE,KAAK;IAWhB;;;OAGG;IACG,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItC;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI;IAQzC;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB;;;;;;OAMG;IACG,OAAO,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB1D;;;;;;OAMG;IACH,YAAY;CAKb;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,wBAAwB;CACtC"}
+{"version":3,"file":"running-state.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/services/running-state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAGjD,OAAO,EAAC,cAAc,EAAC,MAAM,8BAA8B,CAAC;AAI5D,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAEhD,MAAM,MAAM,WAAW,GAAG;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC;AAEtC;;GAEG;AACH,qBAAa,YAAY;;gBAarB,WAAW,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,WAAW,EACzB,YAAY,oBAAa,EACzB,OAAO,wBAAiB;IA+B1B,IAAI,MAAM,IAAI,WAAW,CAExB;IAED,IAAI,UAAU,WAEb;IAED;;;;;OAKG;IACH,SAAS,IAAI,OAAO;IAIpB;;;OAGG;IACH,YAAY,CAAC,CAAC,EAAE,UAAU,GAAG,YAAY;IAMzC;;OAEG;IACH,UAAU,CAAC,KAAK,SAAS,OAAO,EAAE,EAChC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI,EAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,IAAI,EAAE,KAAK;IAYhB;;;OAGG;IACG,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItC;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI;IAQzC;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB;;;;;;OAMG;IACG,OAAO,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB1D;;;;;;OAMG;IACH,YAAY;CAKb;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,wBAAwB;CACtC"}

package/out/zero-cache/src/services/running-state.js

@@ -70,6 +70,7 @@ var RunningState = class {
 			return fn(...args);
 		}, timeoutMs);
 		this.#pendingTimeouts.add(timeout);
+		return timeout;
 	}
 	/**
 	* Returns a promise that resolves after `ms` milliseconds or when

package/out/zero-cache/src/services/running-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"running-state.js","names":["#serviceName","#controller","#sleep","#setTimeout","#stopped","#initialRetryDelay","#maxRetryDelay","#pendingTimeouts","#retryDelay"],"sources":["../../../../../zero-cache/src/services/running-state.ts"],"sourcesContent":["import {PG_UNDEFINED_TABLE} from '@drdgvhbh/postgres-error-codes';\nimport type {LogContext} from '@rocicorp/logger';\nimport {resolver} from '@rocicorp/resolver';\nimport {AbortError} from '../../../shared/src/abort-error.ts';\nimport {sleepWithAbort} from '../../../shared/src/sleep.ts';\nimport {isPostgresError} from '../types/pg.ts';\n\nconst DEFAULT_INITIAL_RETRY_DELAY_MS = 25;\nexport const DEFAULT_MAX_RETRY_DELAY_MS = 10000;\n\nexport type RetryConfig = {\n  initialRetryDelay?: number;\n  maxRetryDelay?: number;\n};\n\nexport interface Cancelable {\n  cancel(): void;\n}\n\nexport type UnregisterFn = () => void;\n\n/**\n * Facilitates lifecycle control with exponential backoff.\n */\nexport class RunningState {\n  readonly #serviceName: string;\n  readonly #controller: AbortController;\n  readonly #sleep: typeof sleepWithAbort;\n  readonly #setTimeout: typeof setTimeout;\n  readonly #stopped: Promise<void>;\n\n  readonly #initialRetryDelay: number;\n  readonly #maxRetryDelay: number;\n  readonly #pendingTimeouts = new Set<NodeJS.Timeout>();\n  #retryDelay: number;\n\n  constructor(\n    serviceName: string,\n    retryConfig?: RetryConfig,\n    setTimeoutFn = setTimeout,\n    sleeper = sleepWithAbort,\n  ) {\n    const {\n      initialRetryDelay = DEFAULT_INITIAL_RETRY_DELAY_MS,\n      maxRetryDelay = DEFAULT_MAX_RETRY_DELAY_MS,\n    } = retryConfig ?? {};\n\n    this.#serviceName = serviceName;\n    this.#initialRetryDelay = initialRetryDelay;\n    this.#maxRetryDelay = maxRetryDelay;\n    this.#retryDelay = initialRetryDelay;\n\n    this.#controller = new AbortController();\n    this.#sleep = sleeper;\n    this.#setTimeout = setTimeoutFn;\n\n    const {promise, resolve} = resolver();\n    this.#stopped = promise;\n    this.#controller.signal.addEventListener(\n      'abort',\n      () => {\n        resolve();\n        for (const timeout of this.#pendingTimeouts) {\n          clearTimeout(timeout);\n        }\n        this.#pendingTimeouts.clear();\n      },\n      {once: true},\n    );\n  }\n\n  get signal(): AbortSignal {\n    return this.#controller.signal;\n  }\n\n  get retryDelay() {\n    return this.#retryDelay;\n  }\n\n  /**\n   * Returns `true` until {@link stop()} has been called.\n   *\n   * This is usually called as part of the service's main loop\n   * conditional to determine if the next iteration should execute.\n   */\n  shouldRun(): boolean {\n    return !this.#controller.signal.aborted;\n  }\n\n  /**\n   * Registers a Cancelable object to be invoked when {@link stop()} is called.\n   * Returns a method to unregister the object.\n   */\n  cancelOnStop(c: Cancelable): UnregisterFn {\n    const onStop = () => c.cancel();\n    this.#controller.signal.addEventListener('abort', onStop, {once: true});\n    return () => this.#controller.signal.removeEventListener('abort', onStop);\n  }\n\n  /**\n   * Sets a Timeout that is automatically cancelled if the service is cancelled.\n   */\n  setTimeout<TArgs extends unknown[]>(\n    fn: (...args: TArgs) => void,\n    timeoutMs: number,\n    ...args: TArgs\n  ) {\n    const timeout = this.#setTimeout(() => {\n      clearTimeout(timeout);\n      this.#pendingTimeouts.delete(timeout);\n      return fn(...args);\n    }, timeoutMs);\n\n    this.#pendingTimeouts.add(timeout);\n  }\n\n  /**\n   * Returns a promise that resolves after `ms` milliseconds or when\n   * the service is stopped.\n   */\n  async sleep(ms: number): Promise<void> {\n    await Promise.race(this.#sleep(ms, this.#controller.signal));\n  }\n\n  /**\n   * Called to stop the service. After this is called, {@link shouldRun()}\n   * will return `false` and the {@link stopped()} Promise will be resolved.\n   */\n  stop(lc: LogContext, err?: unknown): void {\n    if (this.shouldRun()) {\n      const log = !err || err instanceof AbortError ? 'info' : 'error';\n      lc[log]?.(`stopping ${this.#serviceName}`, err ?? '');\n      this.#controller.abort();\n    }\n  }\n\n  /**\n   * Returns a Promise that resolves when {@link stop()} is called.\n   */\n  stopped(): Promise<void> {\n    return this.#stopped;\n  }\n\n  /**\n   * Call in response to an error or unexpected termination in the main\n   * loop of the service. The returned Promise will resolve after an\n   * exponential delay, or once {@link stop()} is called.\n   *\n   * If the supplied `err` is an `AbortError`, the service will shut down.\n   */\n  async backoff(lc: LogContext, err: unknown): Promise<void> {\n    const delay = this.#retryDelay;\n    this.#retryDelay = Math.min(delay * 2, this.#maxRetryDelay);\n\n    // Common failure mode when the user deletes a pg schema out from under\n    // us after init. Turn into an AbortError to force restart, which will\n    // restart and re-init the schema.\n    if (isPostgresError(err, PG_UNDEFINED_TABLE)) {\n      err = new AbortError('undefined table', {cause: err});\n    }\n\n    if (err instanceof AbortError || err instanceof UnrecoverableError) {\n      this.resetBackoff();\n      this.stop(lc, err);\n    } else if (this.shouldRun()) {\n      // Use delay-based log level: higher delay means more retries\n      const log: 'info' | 'warn' | 'error' =\n        delay < 1000 ? 'info' : delay < 6500 ? 'warn' : 'error';\n\n      lc[log]?.(`retrying ${this.#serviceName} in ${delay} ms`, err);\n      await this.sleep(delay);\n    }\n  }\n\n  /**\n   * When using {@link backoff()}, this method should be called when the\n   * implementation receives a healthy signal (e.g. a successful\n   * response). This resets the delay used in {@link backoff()}.\n   *\n   * @returns The previous backoff delay\n   */\n  resetBackoff() {\n    const prevDelay = this.#retryDelay;\n    this.#retryDelay = this.#initialRetryDelay;\n    return prevDelay;\n  }\n}\n\n/**\n * Superclass for Errors that should bypass exponential backoff\n * and immediately shut down the server.\n */\nexport class UnrecoverableError extends Error {\n  readonly name = 'UnrecoverableError';\n}\n"],"mappings":";;;;;;AAOA,IAAM,iCAAiC;AACvC,IAAa,6BAA6B;;;;AAgB1C,IAAa,eAAb,MAA0B;CACxB;CACA;CACA;CACA;CACA;CAEA;CACA;CACA,mCAA4B,IAAI,IAAoB;CACpD;CAEA,YACE,aACA,aACA,eAAe,YACf,UAAU,gBACV;EACA,MAAM,EACJ,oBAAoB,gCACpB,gBAAgB,+BACd,eAAe,CAAC;EAEpB,KAAKA,eAAe;EACpB,KAAKK,qBAAqB;EAC1B,KAAKC,iBAAiB;EACtB,KAAKE,cAAc;EAEnB,KAAKP,cAAc,IAAI,gBAAgB;EACvC,KAAKC,SAAS;EACd,KAAKC,cAAc;EAEnB,MAAM,EAAC,SAAS,YAAW,SAAS;EACpC,KAAKC,WAAW;EAChB,KAAKH,YAAY,OAAO,iBACtB,eACM;GACJ,QAAQ;GACR,KAAK,MAAM,WAAW,KAAKM,kBACzB,aAAa,OAAO;GAEtB,KAAKA,iBAAiB,MAAM;EAC9B,GACA,EAAC,MAAM,KAAI,CACb;CACF;CAEA,IAAI,SAAsB;EACxB,OAAO,KAAKN,YAAY;CAC1B;CAEA,IAAI,aAAa;EACf,OAAO,KAAKO;CACd;;;;;;;CAQA,YAAqB;EACnB,OAAO,CAAC,KAAKP,YAAY,OAAO;CAClC;;;;;CAMA,aAAa,GAA6B;EACxC,MAAM,eAAe,EAAE,OAAO;EAC9B,KAAKA,YAAY,OAAO,iBAAiB,SAAS,QAAQ,EAAC,MAAM,KAAI,CAAC;EACtE,aAAa,KAAKA,YAAY,OAAO,oBAAoB,SAAS,MAAM;CAC1E;;;;CAKA,WACE,IACA,WACA,GAAG,MACH;EACA,MAAM,UAAU,KAAKE,kBAAkB;GACrC,aAAa,OAAO;GACpB,KAAKI,iBAAiB,OAAO,OAAO;GACpC,OAAO,GAAG,GAAG,IAAI;EACnB,GAAG,SAAS;EAEZ,KAAKA,iBAAiB,IAAI,OAAO;CACnC;;;;;CAMA,MAAM,MAAM,IAA2B;EACrC,MAAM,QAAQ,KAAK,KAAKL,OAAO,IAAI,KAAKD,YAAY,MAAM,CAAC;CAC7D;;;;;CAMA,KAAK,IAAgB,KAAqB;EACxC,IAAI,KAAK,UAAU,GAAG;GAEpB,GADY,CAAC,OAAO,eAAe,aAAa,SAAS,WAC/C,YAAY,KAAKD,gBAAgB,OAAO,EAAE;GACpD,KAAKC,YAAY,MAAM;EACzB;CACF;;;;CAKA,UAAyB;EACvB,OAAO,KAAKG;CACd;;;;;;;;CASA,MAAM,QAAQ,IAAgB,KAA6B;EACzD,MAAM,QAAQ,KAAKI;EACnB,KAAKA,cAAc,KAAK,IAAI,QAAQ,GAAG,KAAKF,cAAc;EAK1D,IAAI,gBAAgB,KAAK,kBAAkB,GACzC,MAAM,IAAI,WAAW,mBAAmB,EAAC,OAAO,IAAG,CAAC;EAGtD,IAAI,eAAe,cAAc,eAAe,oBAAoB;GAClE,KAAK,aAAa;GAClB,KAAK,KAAK,IAAI,GAAG;EACnB,OAAO,IAAI,KAAK,UAAU,GAAG;GAK3B,GAFE,QAAQ,MAAO,SAAS,QAAQ,OAAO,SAAS,WAExC,YAAY,KAAKN,aAAa,MAAM,MAAM,MAAM,GAAG;GAC7D,MAAM,KAAK,MAAM,KAAK;EACxB;CACF;;;;;;;;CASA,eAAe;EACb,MAAM,YAAY,KAAKQ;EACvB,KAAKA,cAAc,KAAKH;EACxB,OAAO;CACT;AACF;;;;;AAMA,IAAa,qBAAb,cAAwC,MAAM;CAC5C,OAAgB;AAClB"}
+{"version":3,"file":"running-state.js","names":["#serviceName","#controller","#sleep","#setTimeout","#stopped","#initialRetryDelay","#maxRetryDelay","#pendingTimeouts","#retryDelay"],"sources":["../../../../../zero-cache/src/services/running-state.ts"],"sourcesContent":["import {PG_UNDEFINED_TABLE} from '@drdgvhbh/postgres-error-codes';\nimport type {LogContext} from '@rocicorp/logger';\nimport {resolver} from '@rocicorp/resolver';\nimport {AbortError} from '../../../shared/src/abort-error.ts';\nimport {sleepWithAbort} from '../../../shared/src/sleep.ts';\nimport {isPostgresError} from '../types/pg.ts';\n\nconst DEFAULT_INITIAL_RETRY_DELAY_MS = 25;\nexport const DEFAULT_MAX_RETRY_DELAY_MS = 10000;\n\nexport type RetryConfig = {\n  initialRetryDelay?: number;\n  maxRetryDelay?: number;\n};\n\nexport interface Cancelable {\n  cancel(): void;\n}\n\nexport type UnregisterFn = () => void;\n\n/**\n * Facilitates lifecycle control with exponential backoff.\n */\nexport class RunningState {\n  readonly #serviceName: string;\n  readonly #controller: AbortController;\n  readonly #sleep: typeof sleepWithAbort;\n  readonly #setTimeout: typeof setTimeout;\n  readonly #stopped: Promise<void>;\n\n  readonly #initialRetryDelay: number;\n  readonly #maxRetryDelay: number;\n  readonly #pendingTimeouts = new Set<NodeJS.Timeout>();\n  #retryDelay: number;\n\n  constructor(\n    serviceName: string,\n    retryConfig?: RetryConfig,\n    setTimeoutFn = setTimeout,\n    sleeper = sleepWithAbort,\n  ) {\n    const {\n      initialRetryDelay = DEFAULT_INITIAL_RETRY_DELAY_MS,\n      maxRetryDelay = DEFAULT_MAX_RETRY_DELAY_MS,\n    } = retryConfig ?? {};\n\n    this.#serviceName = serviceName;\n    this.#initialRetryDelay = initialRetryDelay;\n    this.#maxRetryDelay = maxRetryDelay;\n    this.#retryDelay = initialRetryDelay;\n\n    this.#controller = new AbortController();\n    this.#sleep = sleeper;\n    this.#setTimeout = setTimeoutFn;\n\n    const {promise, resolve} = resolver();\n    this.#stopped = promise;\n    this.#controller.signal.addEventListener(\n      'abort',\n      () => {\n        resolve();\n        for (const timeout of this.#pendingTimeouts) {\n          clearTimeout(timeout);\n        }\n        this.#pendingTimeouts.clear();\n      },\n      {once: true},\n    );\n  }\n\n  get signal(): AbortSignal {\n    return this.#controller.signal;\n  }\n\n  get retryDelay() {\n    return this.#retryDelay;\n  }\n\n  /**\n   * Returns `true` until {@link stop()} has been called.\n   *\n   * This is usually called as part of the service's main loop\n   * conditional to determine if the next iteration should execute.\n   */\n  shouldRun(): boolean {\n    return !this.#controller.signal.aborted;\n  }\n\n  /**\n   * Registers a Cancelable object to be invoked when {@link stop()} is called.\n   * Returns a method to unregister the object.\n   */\n  cancelOnStop(c: Cancelable): UnregisterFn {\n    const onStop = () => c.cancel();\n    this.#controller.signal.addEventListener('abort', onStop, {once: true});\n    return () => this.#controller.signal.removeEventListener('abort', onStop);\n  }\n\n  /**\n   * Sets a Timeout that is automatically cancelled if the service is cancelled.\n   */\n  setTimeout<TArgs extends unknown[]>(\n    fn: (...args: TArgs) => void,\n    timeoutMs: number,\n    ...args: TArgs\n  ) {\n    const timeout = this.#setTimeout(() => {\n      clearTimeout(timeout);\n      this.#pendingTimeouts.delete(timeout);\n      return fn(...args);\n    }, timeoutMs);\n\n    this.#pendingTimeouts.add(timeout);\n    return timeout;\n  }\n\n  /**\n   * Returns a promise that resolves after `ms` milliseconds or when\n   * the service is stopped.\n   */\n  async sleep(ms: number): Promise<void> {\n    await Promise.race(this.#sleep(ms, this.#controller.signal));\n  }\n\n  /**\n   * Called to stop the service. After this is called, {@link shouldRun()}\n   * will return `false` and the {@link stopped()} Promise will be resolved.\n   */\n  stop(lc: LogContext, err?: unknown): void {\n    if (this.shouldRun()) {\n      const log = !err || err instanceof AbortError ? 'info' : 'error';\n      lc[log]?.(`stopping ${this.#serviceName}`, err ?? '');\n      this.#controller.abort();\n    }\n  }\n\n  /**\n   * Returns a Promise that resolves when {@link stop()} is called.\n   */\n  stopped(): Promise<void> {\n    return this.#stopped;\n  }\n\n  /**\n   * Call in response to an error or unexpected termination in the main\n   * loop of the service. The returned Promise will resolve after an\n   * exponential delay, or once {@link stop()} is called.\n   *\n   * If the supplied `err` is an `AbortError`, the service will shut down.\n   */\n  async backoff(lc: LogContext, err: unknown): Promise<void> {\n    const delay = this.#retryDelay;\n    this.#retryDelay = Math.min(delay * 2, this.#maxRetryDelay);\n\n    // Common failure mode when the user deletes a pg schema out from under\n    // us after init. Turn into an AbortError to force restart, which will\n    // restart and re-init the schema.\n    if (isPostgresError(err, PG_UNDEFINED_TABLE)) {\n      err = new AbortError('undefined table', {cause: err});\n    }\n\n    if (err instanceof AbortError || err instanceof UnrecoverableError) {\n      this.resetBackoff();\n      this.stop(lc, err);\n    } else if (this.shouldRun()) {\n      // Use delay-based log level: higher delay means more retries\n      const log: 'info' | 'warn' | 'error' =\n        delay < 1000 ? 'info' : delay < 6500 ? 'warn' : 'error';\n\n      lc[log]?.(`retrying ${this.#serviceName} in ${delay} ms`, err);\n      await this.sleep(delay);\n    }\n  }\n\n  /**\n   * When using {@link backoff()}, this method should be called when the\n   * implementation receives a healthy signal (e.g. a successful\n   * response). This resets the delay used in {@link backoff()}.\n   *\n   * @returns The previous backoff delay\n   */\n  resetBackoff() {\n    const prevDelay = this.#retryDelay;\n    this.#retryDelay = this.#initialRetryDelay;\n    return prevDelay;\n  }\n}\n\n/**\n * Superclass for Errors that should bypass exponential backoff\n * and immediately shut down the server.\n */\nexport class UnrecoverableError extends Error {\n  readonly name = 'UnrecoverableError';\n}\n"],"mappings":";;;;;;AAOA,IAAM,iCAAiC;AACvC,IAAa,6BAA6B;;;;AAgB1C,IAAa,eAAb,MAA0B;CACxB;CACA;CACA;CACA;CACA;CAEA;CACA;CACA,mCAA4B,IAAI,IAAoB;CACpD;CAEA,YACE,aACA,aACA,eAAe,YACf,UAAU,gBACV;EACA,MAAM,EACJ,oBAAoB,gCACpB,gBAAgB,+BACd,eAAe,CAAC;EAEpB,KAAKA,eAAe;EACpB,KAAKK,qBAAqB;EAC1B,KAAKC,iBAAiB;EACtB,KAAKE,cAAc;EAEnB,KAAKP,cAAc,IAAI,gBAAgB;EACvC,KAAKC,SAAS;EACd,KAAKC,cAAc;EAEnB,MAAM,EAAC,SAAS,YAAW,SAAS;EACpC,KAAKC,WAAW;EAChB,KAAKH,YAAY,OAAO,iBACtB,eACM;GACJ,QAAQ;GACR,KAAK,MAAM,WAAW,KAAKM,kBACzB,aAAa,OAAO;GAEtB,KAAKA,iBAAiB,MAAM;EAC9B,GACA,EAAC,MAAM,KAAI,CACb;CACF;CAEA,IAAI,SAAsB;EACxB,OAAO,KAAKN,YAAY;CAC1B;CAEA,IAAI,aAAa;EACf,OAAO,KAAKO;CACd;;;;;;;CAQA,YAAqB;EACnB,OAAO,CAAC,KAAKP,YAAY,OAAO;CAClC;;;;;CAMA,aAAa,GAA6B;EACxC,MAAM,eAAe,EAAE,OAAO;EAC9B,KAAKA,YAAY,OAAO,iBAAiB,SAAS,QAAQ,EAAC,MAAM,KAAI,CAAC;EACtE,aAAa,KAAKA,YAAY,OAAO,oBAAoB,SAAS,MAAM;CAC1E;;;;CAKA,WACE,IACA,WACA,GAAG,MACH;EACA,MAAM,UAAU,KAAKE,kBAAkB;GACrC,aAAa,OAAO;GACpB,KAAKI,iBAAiB,OAAO,OAAO;GACpC,OAAO,GAAG,GAAG,IAAI;EACnB,GAAG,SAAS;EAEZ,KAAKA,iBAAiB,IAAI,OAAO;EACjC,OAAO;CACT;;;;;CAMA,MAAM,MAAM,IAA2B;EACrC,MAAM,QAAQ,KAAK,KAAKL,OAAO,IAAI,KAAKD,YAAY,MAAM,CAAC;CAC7D;;;;;CAMA,KAAK,IAAgB,KAAqB;EACxC,IAAI,KAAK,UAAU,GAAG;GAEpB,GADY,CAAC,OAAO,eAAe,aAAa,SAAS,WAC/C,YAAY,KAAKD,gBAAgB,OAAO,EAAE;GACpD,KAAKC,YAAY,MAAM;EACzB;CACF;;;;CAKA,UAAyB;EACvB,OAAO,KAAKG;CACd;;;;;;;;CASA,MAAM,QAAQ,IAAgB,KAA6B;EACzD,MAAM,QAAQ,KAAKI;EACnB,KAAKA,cAAc,KAAK,IAAI,QAAQ,GAAG,KAAKF,cAAc;EAK1D,IAAI,gBAAgB,KAAK,kBAAkB,GACzC,MAAM,IAAI,WAAW,mBAAmB,EAAC,OAAO,IAAG,CAAC;EAGtD,IAAI,eAAe,cAAc,eAAe,oBAAoB;GAClE,KAAK,aAAa;GAClB,KAAK,KAAK,IAAI,GAAG;EACnB,OAAO,IAAI,KAAK,UAAU,GAAG;GAK3B,GAFE,QAAQ,MAAO,SAAS,QAAQ,OAAO,SAAS,WAExC,YAAY,KAAKN,aAAa,MAAM,MAAM,MAAM,GAAG;GAC7D,MAAM,KAAK,MAAM,KAAK;EACxB;CACF;;;;;;;;CASA,eAAe;EACb,MAAM,YAAY,KAAKQ;EACvB,KAAKA,cAAc,KAAKH;EACxB,OAAO;CACT;AACF;;;;;AAMA,IAAa,qBAAb,cAAwC,MAAM;CAC5C,OAAgB;AAClB"}

package/out/zero-cache/src/services/view-syncer/e2e-serving-lag.d.ts

@@ -13,6 +13,15 @@ export type PendingUpstreamCommit = {
  * distribution rather than a periodic snapshot of how far behind things are.
  * A ViewSyncer that is stuck contributes nothing until it recovers, instead of
  * re-reporting its age on every sample tick.
+ *
+ * "Reaches clients" includes an advancement that had nothing to send this
+ * client group. Such an advancement still establishes that the group is
+ * current as of that commit, so it must clear the pending commit; a tracker
+ * that waited for a *data* poke would instead accumulate the oldest commit
+ * across every quiet interval and report the whole interval as lag the next
+ * time the group happened to match a transaction. The caller is responsible
+ * for passing the replica version it advanced to rather than the CVR version,
+ * which only moves when there is something to write.
  */
 export declare class E2EServingLagTracker {
     #private;

package/out/zero-cache/src/services/view-syncer/e2e-serving-lag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"e2e-serving-lag.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/view-syncer/e2e-serving-lag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,6BAA6B,CAAC;AAE9D,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,qBAAa,oBAAoB;;IAG/B,IAAI,OAAO,IAAI,qBAAqB,GAAG,IAAI,CAE1C;IAED;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAC,SAAS,EAAE,oBAAoB,EAAC,EAAE,YAAY,GAAG,IAAI;IAcrE;;;;;OAKG;IACH,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;CAoB1E;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B,CAAC"}
+{"version":3,"file":"e2e-serving-lag.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/view-syncer/e2e-serving-lag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,6BAA6B,CAAC;AAE9D,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,oBAAoB;;IAG/B,IAAI,OAAO,IAAI,qBAAqB,GAAG,IAAI,CAE1C;IAED;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAC,SAAS,EAAE,oBAAoB,EAAC,EAAE,YAAY,GAAG,IAAI;IAcrE;;;;;OAKG;IACH,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;CAoB1E;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B,CAAC"}

package/out/zero-cache/src/services/view-syncer/e2e-serving-lag.js

@@ -9,6 +9,15 @@
 * distribution rather than a periodic snapshot of how far behind things are.
 * A ViewSyncer that is stuck contributes nothing until it recovers, instead of
 * re-reporting its age on every sample tick.
+*
+* "Reaches clients" includes an advancement that had nothing to send this
+* client group. Such an advancement still establishes that the group is
+* current as of that commit, so it must clear the pending commit; a tracker
+* that waited for a *data* poke would instead accumulate the oldest commit
+* across every quiet interval and report the whole interval as lag the next
+* time the group happened to match a transaction. The caller is responsible
+* for passing the replica version it advanced to rather than the CVR version,
+* which only moves when there is something to write.
 */
 var E2EServingLagTracker = class {
 	#pending = null;

package/out/zero-cache/src/services/view-syncer/e2e-serving-lag.js.map

@@ -1 +1 @@
-{"version":3,"file":"e2e-serving-lag.js","names":["#pending"],"sources":["../../../../../../zero-cache/src/services/view-syncer/e2e-serving-lag.ts"],"sourcesContent":["import type {ReplicaState} from '../replicator/replicator.ts';\n\nexport type PendingUpstreamCommit = {\n  readonly watermark: string;\n  readonly commitTimeMs: number;\n};\n\n/**\n * Pairs the upstream commit timestamps carried by `version-ready`\n * notifications with the moment the corresponding change is poked to clients,\n * yielding the end-to-end serving lag.\n *\n * This measures completion, not backlog: an observation is produced only when\n * work actually reaches clients, so the resulting histogram is a latency\n * distribution rather than a periodic snapshot of how far behind things are.\n * A ViewSyncer that is stuck contributes nothing until it recovers, instead of\n * re-reporting its age on every sample tick.\n */\nexport class E2EServingLagTracker {\n  #pending: PendingUpstreamCommit | null = null;\n\n  get pending(): PendingUpstreamCommit | null {\n    return this.#pending;\n  }\n\n  /**\n   * Records the upstream commit behind a `version-ready` notification.\n   *\n   * Notifications coalesce when the ViewSyncer is busy, so one state may stand\n   * in for several commits. The *oldest* commit time is kept, since it bounds\n   * the lag of everything the notification subsumed, while the watermark\n   * advances to the newest — that is the one that must be served for all of\n   * the subsumed commits to have been delivered.\n   */\n  onVersionReady({watermark, upstreamCommitTimeMs}: ReplicaState): void {\n    if (watermark === undefined || upstreamCommitTimeMs === undefined) {\n      return;\n    }\n    const pending = this.#pending;\n    this.#pending = {\n      watermark,\n      commitTimeMs:\n        pending === null\n          ? upstreamCommitTimeMs\n          : Math.min(pending.commitTimeMs, upstreamCommitTimeMs),\n    };\n  }\n\n  /**\n   * Called once a version has been poked to clients.\n   *\n   * @return the observation to record, or `null` if the served version does\n   *     not yet cover an outstanding upstream commit.\n   */\n  onVersionServed(servedVersion: string, nowMs: number): Observation | null {\n    const pending = this.#pending;\n    if (pending === null || servedVersion < pending.watermark) {\n      return null;\n    }\n    this.#pending = null;\n\n    const lagMs = nowMs - pending.commitTimeMs;\n    if (lagMs >= 0) {\n      return {lagMs, clamped: false};\n    }\n    // The commit time is on the upstream database's clock while `nowMs` is\n    // local, so a negative duration means upstream's clock is running ahead of\n    // ours by more than the entire pipeline latency. Clamp, because a negative\n    // value would corrupt the histogram's sum -- but report the clamp, since\n    // it is proof of gross clock skew, and skew in this direction biases the\n    // metric *low*, which reads as healthy serving rather than as a broken\n    // measurement. See replication.upstream_clock_skew for the magnitude.\n    return {lagMs: 0, clamped: true};\n  }\n}\n\nexport type Observation = {\n  /** End-to-end lag in milliseconds, clamped to be non-negative. */\n  readonly lagMs: number;\n  /** Whether the clamp was applied, i.e. the raw measurement was negative. */\n  readonly clamped: boolean;\n};\n"],"mappings":";;;;;;;;;;;;AAkBA,IAAa,uBAAb,MAAkC;CAChC,WAAyC;CAEzC,IAAI,UAAwC;EAC1C,OAAO,KAAKA;CACd;;;;;;;;;;CAWA,eAAe,EAAC,WAAW,wBAA2C;EACpE,IAAI,cAAc,KAAA,KAAa,yBAAyB,KAAA,GACtD;EAEF,MAAM,UAAU,KAAKA;EACrB,KAAKA,WAAW;GACd;GACA,cACE,YAAY,OACR,uBACA,KAAK,IAAI,QAAQ,cAAc,oBAAoB;EAC3D;CACF;;;;;;;CAQA,gBAAgB,eAAuB,OAAmC;EACxE,MAAM,UAAU,KAAKA;EACrB,IAAI,YAAY,QAAQ,gBAAgB,QAAQ,WAC9C,OAAO;EAET,KAAKA,WAAW;EAEhB,MAAM,QAAQ,QAAQ,QAAQ;EAC9B,IAAI,SAAS,GACX,OAAO;GAAC;GAAO,SAAS;EAAK;EAS/B,OAAO;GAAC,OAAO;GAAG,SAAS;EAAI;CACjC;AACF"}
+{"version":3,"file":"e2e-serving-lag.js","names":["#pending"],"sources":["../../../../../../zero-cache/src/services/view-syncer/e2e-serving-lag.ts"],"sourcesContent":["import type {ReplicaState} from '../replicator/replicator.ts';\n\nexport type PendingUpstreamCommit = {\n  readonly watermark: string;\n  readonly commitTimeMs: number;\n};\n\n/**\n * Pairs the upstream commit timestamps carried by `version-ready`\n * notifications with the moment the corresponding change is poked to clients,\n * yielding the end-to-end serving lag.\n *\n * This measures completion, not backlog: an observation is produced only when\n * work actually reaches clients, so the resulting histogram is a latency\n * distribution rather than a periodic snapshot of how far behind things are.\n * A ViewSyncer that is stuck contributes nothing until it recovers, instead of\n * re-reporting its age on every sample tick.\n *\n * \"Reaches clients\" includes an advancement that had nothing to send this\n * client group. Such an advancement still establishes that the group is\n * current as of that commit, so it must clear the pending commit; a tracker\n * that waited for a *data* poke would instead accumulate the oldest commit\n * across every quiet interval and report the whole interval as lag the next\n * time the group happened to match a transaction. The caller is responsible\n * for passing the replica version it advanced to rather than the CVR version,\n * which only moves when there is something to write.\n */\nexport class E2EServingLagTracker {\n  #pending: PendingUpstreamCommit | null = null;\n\n  get pending(): PendingUpstreamCommit | null {\n    return this.#pending;\n  }\n\n  /**\n   * Records the upstream commit behind a `version-ready` notification.\n   *\n   * Notifications coalesce when the ViewSyncer is busy, so one state may stand\n   * in for several commits. The *oldest* commit time is kept, since it bounds\n   * the lag of everything the notification subsumed, while the watermark\n   * advances to the newest — that is the one that must be served for all of\n   * the subsumed commits to have been delivered.\n   */\n  onVersionReady({watermark, upstreamCommitTimeMs}: ReplicaState): void {\n    if (watermark === undefined || upstreamCommitTimeMs === undefined) {\n      return;\n    }\n    const pending = this.#pending;\n    this.#pending = {\n      watermark,\n      commitTimeMs:\n        pending === null\n          ? upstreamCommitTimeMs\n          : Math.min(pending.commitTimeMs, upstreamCommitTimeMs),\n    };\n  }\n\n  /**\n   * Called once a version has been poked to clients.\n   *\n   * @return the observation to record, or `null` if the served version does\n   *     not yet cover an outstanding upstream commit.\n   */\n  onVersionServed(servedVersion: string, nowMs: number): Observation | null {\n    const pending = this.#pending;\n    if (pending === null || servedVersion < pending.watermark) {\n      return null;\n    }\n    this.#pending = null;\n\n    const lagMs = nowMs - pending.commitTimeMs;\n    if (lagMs >= 0) {\n      return {lagMs, clamped: false};\n    }\n    // The commit time is on the upstream database's clock while `nowMs` is\n    // local, so a negative duration means upstream's clock is running ahead of\n    // ours by more than the entire pipeline latency. Clamp, because a negative\n    // value would corrupt the histogram's sum -- but report the clamp, since\n    // it is proof of gross clock skew, and skew in this direction biases the\n    // metric *low*, which reads as healthy serving rather than as a broken\n    // measurement. See replication.upstream_clock_skew for the magnitude.\n    return {lagMs: 0, clamped: true};\n  }\n}\n\nexport type Observation = {\n  /** End-to-end lag in milliseconds, clamped to be non-negative. */\n  readonly lagMs: number;\n  /** Whether the clamp was applied, i.e. the raw measurement was negative. */\n  readonly clamped: boolean;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA2BA,IAAa,uBAAb,MAAkC;CAChC,WAAyC;CAEzC,IAAI,UAAwC;EAC1C,OAAO,KAAKA;CACd;;;;;;;;;;CAWA,eAAe,EAAC,WAAW,wBAA2C;EACpE,IAAI,cAAc,KAAA,KAAa,yBAAyB,KAAA,GACtD;EAEF,MAAM,UAAU,KAAKA;EACrB,KAAKA,WAAW;GACd;GACA,cACE,YAAY,OACR,uBACA,KAAK,IAAI,QAAQ,cAAc,oBAAoB;EAC3D;CACF;;;;;;;CAQA,gBAAgB,eAAuB,OAAmC;EACxE,MAAM,UAAU,KAAKA;EACrB,IAAI,YAAY,QAAQ,gBAAgB,QAAQ,WAC9C,OAAO;EAET,KAAKA,WAAW;EAEhB,MAAM,QAAQ,QAAQ,QAAQ;EAC9B,IAAI,SAAS,GACX,OAAO;GAAC;GAAO,SAAS;EAAK;EAS/B,OAAO;GAAC,OAAO;GAAG,SAAS;EAAI;CACjC;AACF"}