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

package/out/zero-cache/src/db/migration.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../shared/src/asserts.js";
+import { AbortError } from "../../../shared/src/abort-error.js";
 import { parse, valita_exports } from "../../../shared/src/valita.js";
 import { must } from "../../../shared/src/must.js";
 import "../types/pg.js";
@@ -35,7 +36,8 @@ async function runSchemaMigrations(log, debugName, schemaName, db, setupMigratio
 		});
 		log.info?.(`Running ${debugName} at schema v${codeVersion}`);
 	} catch (e) {
-		log.error?.("Error in ensureSchemaMigrated", e);
+		if (e instanceof AbortError) log.warn?.("Schema requires reset; resync will follow", e);
+		else log.error?.("Error in ensureSchemaMigrated", e);
 		throw e;
 	} finally {
 		log.flush();
@@ -134,6 +136,6 @@ function getMinSafeVersion(log, current, proposedSafeVersion) {
 	return proposedSafeVersion;
 }
 //#endregion
-export { getVersionHistory, runSchemaMigrations };
+export { runSchemaMigrations };
 
 //# sourceMappingURL=migration.js.map

package/out/zero-cache/src/db/migration.js.map

@@ -1 +1 @@
-{"version":3,"file":"migration.js","names":[],"sources":["../../../../../zero-cache/src/db/migration.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport type postgres from 'postgres';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport * as v from '../../../shared/src/valita.ts';\nimport {type PostgresDB, type PostgresTransaction} from '../types/pg.ts';\nimport {runTx} from './run-transaction.ts';\n\ntype Operations = (log: LogContext, tx: PostgresTransaction) => Promise<void>;\n\n/**\n * Encapsulates the logic for setting up or upgrading to a new schema. After the\n * Migration code successfully completes, {@link runSchemaMigrations}\n * will update the schema version and commit the transaction.\n */\nexport type Migration = {\n  /**\n   * Perform database operations that create or alter table structure. This is\n   * called at most once during lifetime of the application. If a `migrateData()`\n   * operation is defined, that will be performed after `migrateSchema()` succeeds.\n   */\n  migrateSchema?: Operations;\n\n  /**\n   * Perform database operations to migrate data to the new schema. This is\n   * called after `migrateSchema()` (if defined), and may be called again\n   * to re-migrate data after the server was rolled back to an earlier version,\n   * and rolled forward again.\n   *\n   * Consequently, the logic in `migrateData()` must be idempotent.\n   */\n  migrateData?: Operations;\n\n  /**\n   * Sets the `minSafeVersion` to the specified value, prohibiting running\n   * any earlier code versions.\n   */\n  minSafeVersion?: number;\n};\n\n/**\n * Mapping of incremental migrations to move from the previous old code\n * version to next one. Versions must be non-zero.\n *\n * The schema resulting from performing incremental migrations should be\n * equivalent to that of the `setupMigration` on a blank database.\n *\n * The highest destinationVersion of this map denotes the current\n * \"code version\", and is also used as the destination version when\n * running the initial setup migration on a blank database.\n */\nexport type IncrementalMigrationMap = {\n  [destinationVersion: number]: Migration;\n};\n\n/**\n * Ensures that the schema is compatible with the current code, updating and\n * migrating the schema if necessary.\n */\nexport async function runSchemaMigrations(\n  log: LogContext,\n  debugName: string,\n  schemaName: string,\n  db: PostgresDB,\n  setupMigration: Migration,\n  incrementalMigrationMap: IncrementalMigrationMap,\n): Promise<void> {\n  log = log.withContext('initSchema', schemaName);\n\n  const versionMigrations = sorted(incrementalMigrationMap);\n  assert(\n    versionMigrations.length,\n    `Must specify at least one version migration`,\n  );\n  assert(\n    versionMigrations[0][0] > 0,\n    `Versions must be non-zero positive numbers`,\n  );\n  // oxlint-disable-next-line typescript/no-non-null-assertion\n  const codeVersion = versionMigrations.at(-1)![0];\n\n  log.info?.(\n    `Checking schema for compatibility with ${debugName} at schema v${codeVersion}`,\n  );\n\n  try {\n    await runTx(db, async tx => {\n      // Acquire advisory lock to prevent concurrent migrations from racing.\n      // This can happen during rolling deployments when multiple pods start\n      // up simultaneously. The lock auto-releases when the transaction ends.\n      const lockName = `migrate-schema:${schemaName}`;\n      await tx`SELECT pg_advisory_xact_lock(hashtext(${lockName}))`;\n\n      let versions = await ensureVersionHistory(tx, schemaName);\n\n      if (codeVersion < versions.minSafeVersion) {\n        throw new Error(\n          `Cannot run ${debugName} at schema v${codeVersion} because rollback limit is v${versions.minSafeVersion}`,\n        );\n      }\n\n      if (versions.dataVersion > codeVersion) {\n        log.info?.(\n          `Data is at v${versions.dataVersion}. Resetting to v${codeVersion}`,\n        );\n        await updateVersionHistory(log, tx, schemaName, versions, codeVersion);\n        return;\n      }\n\n      if (versions.dataVersion === codeVersion) {\n        return;\n      }\n\n      const migrations =\n        versions.dataVersion === 0\n          ? // For an empty database (v0), only run the setup migration.\n            ([[codeVersion, setupMigration]] as const)\n          : versionMigrations;\n\n      for (const [dest, migration] of migrations) {\n        if (versions.dataVersion < dest) {\n          log.info?.(\n            `Migrating schema from v${versions.dataVersion} to v${dest}`,\n          );\n          void log.flush();\n          versions = await runMigration(\n            log,\n            schemaName,\n            tx,\n            versions,\n            dest,\n            migration,\n          );\n        }\n      }\n    });\n\n    log.info?.(`Running ${debugName} at schema v${codeVersion}`);\n  } catch (e) {\n    log.error?.('Error in ensureSchemaMigrated', e);\n    throw e;\n  } finally {\n    void log.flush();\n  }\n}\n\nfunction sorted(\n  incrementalMigrationMap: IncrementalMigrationMap,\n): [number, Migration][] {\n  const versionMigrations: [number, Migration][] = [];\n  for (const [v, m] of Object.entries(incrementalMigrationMap)) {\n    versionMigrations.push([Number(v), m]);\n  }\n  return versionMigrations.sort(([a], [b]) => a - b);\n}\n\n// Exposed for tests.\nexport const versionHistory = v.object({\n  /**\n   * The `schemaVersion` is highest code version that has ever been run\n   * on the database, and is used to delineate the structure of the tables\n   * in the database. A schemaVersion only moves forward; rolling back to\n   * an earlier (safe) code version does not revert schema changes that\n   * have already been applied.\n   */\n  schemaVersion: v.number(),\n\n  /**\n   * The data version is the code version of the latest server that ran.\n   * Note that this may be less than the schemaVersion in the case that\n   * a server is rolled back to an earlier version after a schema change.\n   * In such a case, data (but not schema), may need to be re-migrated\n   * when rolling forward again.\n   */\n  dataVersion: v.number(),\n\n  /**\n   * The minimum code version that is safe to run. This is used when\n   * a schema migration is not backwards compatible with an older version\n   * of the code.\n   */\n  minSafeVersion: v.number(),\n});\n\n// Exposed for tests.\nexport type VersionHistory = v.Infer<typeof versionHistory>;\n\n// Exposed for tests.\nexport async function createVersionHistoryTable(\n  sql: postgres.Sql,\n  schemaName: string,\n) {\n  // Note: The `lock` column transparently ensures that at most one row exists.\n  await sql`\n    CREATE SCHEMA IF NOT EXISTS ${sql(schemaName)};\n    CREATE TABLE IF NOT EXISTS ${sql(schemaName)}.\"versionHistory\" (\n      \"dataVersion\" int NOT NULL,\n      \"schemaVersion\" int NOT NULL,\n      \"minSafeVersion\" int NOT NULL,\n\n      lock char(1) NOT NULL CONSTRAINT DF_schema_meta_lock DEFAULT 'v',\n      CONSTRAINT PK_schema_meta_lock PRIMARY KEY (lock),\n      CONSTRAINT CK_schema_meta_lock CHECK (lock='v')\n    );`.simple();\n}\n\nasync function ensureVersionHistory(\n  sql: postgres.Sql,\n  schemaName: string,\n): Promise<VersionHistory> {\n  return must(await getVersionHistory(sql, schemaName, true));\n}\n\nexport async function getVersionHistory(\n  sql: postgres.Sql,\n  schemaName: string,\n  create = false,\n): Promise<VersionHistory | null> {\n  const exists = await sql`\n  SELECT nspname, relname FROM pg_class\n    JOIN pg_namespace ON relnamespace = pg_namespace.oid\n    WHERE nspname = ${schemaName} AND relname = ${'versionHistory'}`;\n\n  if (exists.length === 0) {\n    if (create) {\n      await createVersionHistoryTable(sql, schemaName);\n    } else {\n      return null;\n    }\n  }\n  const rows = await sql`\n    SELECT \"dataVersion\", \"schemaVersion\", \"minSafeVersion\"\n       FROM ${sql(schemaName)}.\"versionHistory\"`;\n\n  if (rows.length === 0) {\n    return create\n      ? {schemaVersion: 0, dataVersion: 0, minSafeVersion: 0}\n      : null;\n  }\n  return v.parse(rows[0], versionHistory);\n}\n\nasync function updateVersionHistory(\n  log: LogContext,\n  sql: postgres.Sql,\n  schemaName: string,\n  prev: VersionHistory,\n  newVersion: number,\n  minSafeVersion?: number,\n): Promise<VersionHistory> {\n  assert(newVersion > 0, 'newVersion must be positive');\n  const versions = {\n    dataVersion: newVersion,\n    // The schemaVersion never moves backwards.\n    schemaVersion: Math.max(newVersion, prev.schemaVersion),\n    minSafeVersion: getMinSafeVersion(log, prev, minSafeVersion),\n  } satisfies VersionHistory;\n\n  await sql`\n    INSERT INTO ${sql(schemaName)}.\"versionHistory\" ${sql(versions)}\n      ON CONFLICT (lock) DO UPDATE SET ${sql(versions)}\n  `;\n  return versions;\n}\n\nasync function runMigration(\n  log: LogContext,\n  schemaName: string,\n  tx: PostgresTransaction,\n  versions: VersionHistory,\n  destinationVersion: number,\n  migration: Migration,\n): Promise<VersionHistory> {\n  if (versions.schemaVersion < destinationVersion) {\n    await migration.migrateSchema?.(log, tx);\n  }\n  if (versions.dataVersion < destinationVersion) {\n    await migration.migrateData?.(log, tx);\n  }\n  return updateVersionHistory(\n    log,\n    tx,\n    schemaName,\n    versions,\n    destinationVersion,\n    migration.minSafeVersion,\n  );\n}\n\n/**\n * Bumps the rollback limit [[toAtLeast]] the specified version.\n * Leaves the rollback limit unchanged if it is equal or greater.\n */\nfunction getMinSafeVersion(\n  log: LogContext,\n  current: VersionHistory,\n  proposedSafeVersion?: number,\n): number {\n  if (proposedSafeVersion === undefined) {\n    return current.minSafeVersion;\n  }\n  if (current.minSafeVersion >= proposedSafeVersion) {\n    // The rollback limit must never move backwards.\n    log.debug?.(\n      `rollback limit is already at ${current.minSafeVersion}, ` +\n        `don't need to bump to ${proposedSafeVersion}`,\n    );\n    return current.minSafeVersion;\n  }\n  log.info?.(\n    `bumping rollback limit from ${current.minSafeVersion} to ${proposedSafeVersion}`,\n  );\n  return proposedSafeVersion;\n}\n"],"mappings":"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"}
+{"version":3,"file":"migration.js","names":[],"sources":["../../../../../zero-cache/src/db/migration.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport type postgres from 'postgres';\nimport {AbortError} from '../../../shared/src/abort-error.ts';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport * as v from '../../../shared/src/valita.ts';\nimport {type PostgresDB, type PostgresTransaction} from '../types/pg.ts';\nimport {runTx} from './run-transaction.ts';\n\ntype Operations = (log: LogContext, tx: PostgresTransaction) => Promise<void>;\n\n/**\n * Encapsulates the logic for setting up or upgrading to a new schema. After the\n * Migration code successfully completes, {@link runSchemaMigrations}\n * will update the schema version and commit the transaction.\n */\nexport type Migration = {\n  /**\n   * Perform database operations that create or alter table structure. This is\n   * called at most once during lifetime of the application. If a `migrateData()`\n   * operation is defined, that will be performed after `migrateSchema()` succeeds.\n   */\n  migrateSchema?: Operations;\n\n  /**\n   * Perform database operations to migrate data to the new schema. This is\n   * called after `migrateSchema()` (if defined), and may be called again\n   * to re-migrate data after the server was rolled back to an earlier version,\n   * and rolled forward again.\n   *\n   * Consequently, the logic in `migrateData()` must be idempotent.\n   */\n  migrateData?: Operations;\n\n  /**\n   * Sets the `minSafeVersion` to the specified value, prohibiting running\n   * any earlier code versions.\n   */\n  minSafeVersion?: number;\n};\n\n/**\n * Mapping of incremental migrations to move from the previous old code\n * version to next one. Versions must be non-zero.\n *\n * The schema resulting from performing incremental migrations should be\n * equivalent to that of the `setupMigration` on a blank database.\n *\n * The highest destinationVersion of this map denotes the current\n * \"code version\", and is also used as the destination version when\n * running the initial setup migration on a blank database.\n */\nexport type IncrementalMigrationMap = {\n  [destinationVersion: number]: Migration;\n};\n\n/**\n * Ensures that the schema is compatible with the current code, updating and\n * migrating the schema if necessary.\n */\nexport async function runSchemaMigrations(\n  log: LogContext,\n  debugName: string,\n  schemaName: string,\n  db: PostgresDB,\n  setupMigration: Migration,\n  incrementalMigrationMap: IncrementalMigrationMap,\n): Promise<void> {\n  log = log.withContext('initSchema', schemaName);\n\n  const versionMigrations = sorted(incrementalMigrationMap);\n  assert(\n    versionMigrations.length,\n    `Must specify at least one version migration`,\n  );\n  assert(\n    versionMigrations[0][0] > 0,\n    `Versions must be non-zero positive numbers`,\n  );\n  // oxlint-disable-next-line typescript/no-non-null-assertion\n  const codeVersion = versionMigrations.at(-1)![0];\n\n  log.info?.(\n    `Checking schema for compatibility with ${debugName} at schema v${codeVersion}`,\n  );\n\n  try {\n    await runTx(db, async tx => {\n      // Acquire advisory lock to prevent concurrent migrations from racing.\n      // This can happen during rolling deployments when multiple pods start\n      // up simultaneously. The lock auto-releases when the transaction ends.\n      const lockName = `migrate-schema:${schemaName}`;\n      await tx`SELECT pg_advisory_xact_lock(hashtext(${lockName}))`;\n\n      let versions = await ensureVersionHistory(tx, schemaName);\n\n      if (codeVersion < versions.minSafeVersion) {\n        throw new Error(\n          `Cannot run ${debugName} at schema v${codeVersion} because rollback limit is v${versions.minSafeVersion}`,\n        );\n      }\n\n      if (versions.dataVersion > codeVersion) {\n        log.info?.(\n          `Data is at v${versions.dataVersion}. Resetting to v${codeVersion}`,\n        );\n        await updateVersionHistory(log, tx, schemaName, versions, codeVersion);\n        return;\n      }\n\n      if (versions.dataVersion === codeVersion) {\n        return;\n      }\n\n      const migrations =\n        versions.dataVersion === 0\n          ? // For an empty database (v0), only run the setup migration.\n            ([[codeVersion, setupMigration]] as const)\n          : versionMigrations;\n\n      for (const [dest, migration] of migrations) {\n        if (versions.dataVersion < dest) {\n          log.info?.(\n            `Migrating schema from v${versions.dataVersion} to v${dest}`,\n          );\n          void log.flush();\n          versions = await runMigration(\n            log,\n            schemaName,\n            tx,\n            versions,\n            dest,\n            migration,\n          );\n        }\n      }\n    });\n\n    log.info?.(`Running ${debugName} at schema v${codeVersion}`);\n  } catch (e) {\n    if (e instanceof AbortError) {\n      // AbortErrors (e.g. AutoResetSignal) are not failures. They are the\n      // expected mechanism for signaling that the schema is not initialized\n      // (or otherwise needs a reset) so that the caller can backtrack and\n      // resync. Logging them at `error` would trip error-based alerting for a\n      // normal, self-healing path.\n      log.warn?.('Schema requires reset; resync will follow', e);\n    } else {\n      log.error?.('Error in ensureSchemaMigrated', e);\n    }\n    throw e;\n  } finally {\n    void log.flush();\n  }\n}\n\nfunction sorted(\n  incrementalMigrationMap: IncrementalMigrationMap,\n): [number, Migration][] {\n  const versionMigrations: [number, Migration][] = [];\n  for (const [v, m] of Object.entries(incrementalMigrationMap)) {\n    versionMigrations.push([Number(v), m]);\n  }\n  return versionMigrations.sort(([a], [b]) => a - b);\n}\n\n// Exposed for tests.\nexport const versionHistory = v.object({\n  /**\n   * The `schemaVersion` is highest code version that has ever been run\n   * on the database, and is used to delineate the structure of the tables\n   * in the database. A schemaVersion only moves forward; rolling back to\n   * an earlier (safe) code version does not revert schema changes that\n   * have already been applied.\n   */\n  schemaVersion: v.number(),\n\n  /**\n   * The data version is the code version of the latest server that ran.\n   * Note that this may be less than the schemaVersion in the case that\n   * a server is rolled back to an earlier version after a schema change.\n   * In such a case, data (but not schema), may need to be re-migrated\n   * when rolling forward again.\n   */\n  dataVersion: v.number(),\n\n  /**\n   * The minimum code version that is safe to run. This is used when\n   * a schema migration is not backwards compatible with an older version\n   * of the code.\n   */\n  minSafeVersion: v.number(),\n});\n\n// Exposed for tests.\nexport type VersionHistory = v.Infer<typeof versionHistory>;\n\n// Exposed for tests.\nexport async function createVersionHistoryTable(\n  sql: postgres.Sql,\n  schemaName: string,\n) {\n  // Note: The `lock` column transparently ensures that at most one row exists.\n  await sql`\n    CREATE SCHEMA IF NOT EXISTS ${sql(schemaName)};\n    CREATE TABLE IF NOT EXISTS ${sql(schemaName)}.\"versionHistory\" (\n      \"dataVersion\" int NOT NULL,\n      \"schemaVersion\" int NOT NULL,\n      \"minSafeVersion\" int NOT NULL,\n\n      lock char(1) NOT NULL CONSTRAINT DF_schema_meta_lock DEFAULT 'v',\n      CONSTRAINT PK_schema_meta_lock PRIMARY KEY (lock),\n      CONSTRAINT CK_schema_meta_lock CHECK (lock='v')\n    );`.simple();\n}\n\nasync function ensureVersionHistory(\n  sql: postgres.Sql,\n  schemaName: string,\n): Promise<VersionHistory> {\n  return must(await getVersionHistory(sql, schemaName, true));\n}\n\nexport async function getVersionHistory(\n  sql: postgres.Sql,\n  schemaName: string,\n  create = false,\n): Promise<VersionHistory | null> {\n  const exists = await sql`\n  SELECT nspname, relname FROM pg_class\n    JOIN pg_namespace ON relnamespace = pg_namespace.oid\n    WHERE nspname = ${schemaName} AND relname = ${'versionHistory'}`;\n\n  if (exists.length === 0) {\n    if (create) {\n      await createVersionHistoryTable(sql, schemaName);\n    } else {\n      return null;\n    }\n  }\n  const rows = await sql`\n    SELECT \"dataVersion\", \"schemaVersion\", \"minSafeVersion\"\n       FROM ${sql(schemaName)}.\"versionHistory\"`;\n\n  if (rows.length === 0) {\n    return create\n      ? {schemaVersion: 0, dataVersion: 0, minSafeVersion: 0}\n      : null;\n  }\n  return v.parse(rows[0], versionHistory);\n}\n\nasync function updateVersionHistory(\n  log: LogContext,\n  sql: postgres.Sql,\n  schemaName: string,\n  prev: VersionHistory,\n  newVersion: number,\n  minSafeVersion?: number,\n): Promise<VersionHistory> {\n  assert(newVersion > 0, 'newVersion must be positive');\n  const versions = {\n    dataVersion: newVersion,\n    // The schemaVersion never moves backwards.\n    schemaVersion: Math.max(newVersion, prev.schemaVersion),\n    minSafeVersion: getMinSafeVersion(log, prev, minSafeVersion),\n  } satisfies VersionHistory;\n\n  await sql`\n    INSERT INTO ${sql(schemaName)}.\"versionHistory\" ${sql(versions)}\n      ON CONFLICT (lock) DO UPDATE SET ${sql(versions)}\n  `;\n  return versions;\n}\n\nasync function runMigration(\n  log: LogContext,\n  schemaName: string,\n  tx: PostgresTransaction,\n  versions: VersionHistory,\n  destinationVersion: number,\n  migration: Migration,\n): Promise<VersionHistory> {\n  if (versions.schemaVersion < destinationVersion) {\n    await migration.migrateSchema?.(log, tx);\n  }\n  if (versions.dataVersion < destinationVersion) {\n    await migration.migrateData?.(log, tx);\n  }\n  return updateVersionHistory(\n    log,\n    tx,\n    schemaName,\n    versions,\n    destinationVersion,\n    migration.minSafeVersion,\n  );\n}\n\n/**\n * Bumps the rollback limit [[toAtLeast]] the specified version.\n * Leaves the rollback limit unchanged if it is equal or greater.\n */\nfunction getMinSafeVersion(\n  log: LogContext,\n  current: VersionHistory,\n  proposedSafeVersion?: number,\n): number {\n  if (proposedSafeVersion === undefined) {\n    return current.minSafeVersion;\n  }\n  if (current.minSafeVersion >= proposedSafeVersion) {\n    // The rollback limit must never move backwards.\n    log.debug?.(\n      `rollback limit is already at ${current.minSafeVersion}, ` +\n        `don't need to bump to ${proposedSafeVersion}`,\n    );\n    return current.minSafeVersion;\n  }\n  log.info?.(\n    `bumping rollback limit from ${current.minSafeVersion} to ${proposedSafeVersion}`,\n  );\n  return proposedSafeVersion;\n}\n"],"mappings":"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"}

package/out/zero-cache/src/db/sqlite-corruption.d.ts

@@ -3,9 +3,10 @@ type DiagnosticTarget = {
     readonly debugName: string;
     readonly dbPath: string;
 };
+export type SQLiteCorruptionChecks = boolean;
 export declare function isSQLiteCorruption(e: unknown): boolean;
-export declare function registerSQLiteCorruptionDiagnosticTarget(target: DiagnosticTarget): () => void;
+export declare function registerSQLiteCorruptionDiagnosticTarget(target: DiagnosticTarget, corruptionChecks?: SQLiteCorruptionChecks): () => void;
 export declare function logLastChanceSQLiteCorruptionDiagnostics(lc: LogContext, cause: unknown): boolean;
-export declare function logSQLiteCorruptionDiagnostics(lc: LogContext, debugName: string, dbPath: string, cause: unknown): void;
+export declare function logSQLiteCorruptionDiagnostics(lc: LogContext, debugName: string, dbPath: string, cause: unknown, corruptionChecks?: SQLiteCorruptionChecks): void;
 export {};
 //# sourceMappingURL=sqlite-corruption.d.ts.map

package/out/zero-cache/src/db/sqlite-corruption.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-corruption.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/db/sqlite-corruption.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAiCjD,KAAK,gBAAgB,GAAG;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAKF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED,wBAAgB,wCAAwC,CACtD,MAAM,EAAE,gBAAgB,GACvB,MAAM,IAAI,CAIZ;AAED,wBAAgB,wCAAwC,CACtD,EAAE,EAAE,UAAU,EACd,KAAK,EAAE,OAAO,GACb,OAAO,CAQT;AAED,wBAAgB,8BAA8B,CAC5C,EAAE,EAAE,UAAU,EACd,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,IAAI,CA+CN"}
+{"version":3,"file":"sqlite-corruption.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/db/sqlite-corruption.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAoCjD,KAAK,gBAAgB,GAAG;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AASF,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAAC;AAE7C,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED,wBAAgB,wCAAwC,CACtD,MAAM,EAAE,gBAAgB,EACxB,gBAAgB,GAAE,sBAA8B,GAC/C,MAAM,IAAI,CAIZ;AAED,wBAAgB,wCAAwC,CACtD,EAAE,EAAE,UAAU,EACd,KAAK,EAAE,OAAO,GACb,OAAO,CAkBT;AAED,wBAAgB,8BAA8B,CAC5C,EAAE,EAAE,UAAU,EACd,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,gBAAgB,GAAE,sBAA8B,GAC/C,IAAI,CAiDN"}

package/out/zero-cache/src/db/sqlite-corruption.js

@@ -2,7 +2,7 @@ import { Database } from "../../../zqlite/src/db.js";
 import { SqliteError } from "@rocicorp/zero-sqlite3";
 import { existsSync, statSync } from "node:fs";
 //#region ../zero-cache/src/db/sqlite-corruption.ts
-var SQLITE_CORRUPTION_CODES = new Set(["SQLITE_CORRUPT", "SQLITE_NOTADB"]);
+var SQLITE_CORRUPTION_CODE = /^SQLITE_(CORRUPT(_|$)|NOTADB$)/;
 var SQLITE_CORRUPTION_MESSAGE = /database disk image is malformed|file is not a database|database is malformed|malformed database/i;
 var SQLITE_FILE_SUFFIXES = [
 	"",
@@ -17,17 +17,20 @@ var nextDiagnosticTargetID = 0;
 function isSQLiteCorruption(e) {
 	return getSQLiteCorruptionCode(e) !== void 0;
 }
-function registerSQLiteCorruptionDiagnosticTarget(target) {
+function registerSQLiteCorruptionDiagnosticTarget(target, corruptionChecks = false) {
 	const id = nextDiagnosticTargetID++;
-	diagnosticTargets.set(id, target);
+	diagnosticTargets.set(id, {
+		...target,
+		corruptionChecks
+	});
 	return () => diagnosticTargets.delete(id);
 }
 function logLastChanceSQLiteCorruptionDiagnostics(lc, cause) {
 	if (!isSQLiteCorruption(cause) || diagnosticTargets.size === 0) return false;
-	for (const { debugName, dbPath } of diagnosticTargets.values()) logSQLiteCorruptionDiagnostics(lc, debugName, dbPath, cause);
+	for (const { debugName, dbPath, corruptionChecks } of diagnosticTargets.values()) logSQLiteCorruptionDiagnostics(lc, debugName, dbPath, cause, corruptionChecks);
 	return true;
 }
-function logSQLiteCorruptionDiagnostics(lc, debugName, dbPath, cause) {
+function logSQLiteCorruptionDiagnostics(lc, debugName, dbPath, cause, corruptionChecks = false) {
 	const start = Date.now();
 	lc.error?.("SQLite replica corruption detected", {
 		debugName,
@@ -51,8 +54,10 @@ function logSQLiteCorruptionDiagnostics(lc, debugName, dbPath, cause) {
 	try {
 		logDiagnostic(lc, debugName, "basic-pragmas", () => ({ pragmas: getBasicPragmas(db) }));
 		logDiagnostic(lc, debugName, "replica-metadata", () => ({ metadata: getReplicaMetadata(db) }));
-		logDiagnostic(lc, debugName, "quick-check", () => ({ check: runCheck(db, "quick_check") }));
-		logDiagnostic(lc, debugName, "integrity-check", () => ({ check: runCheck(db, "integrity_check") }));
+		if (corruptionChecks) {
+			logDiagnostic(lc, debugName, "quick-check", () => ({ check: runCheck(db, "quick_check") }));
+			logDiagnostic(lc, debugName, "integrity-check", () => ({ check: runCheck(db, "integrity_check") }));
+		}
 		lc.error?.("SQLite corruption diagnostics completed", {
 			debugName,
 			dbPath,
@@ -68,7 +73,7 @@ function getSQLiteCorruptionCode(e) {
 	while (current !== void 0 && current !== null && !seen.has(current)) {
 		seen.add(current);
 		const code = getErrorCode(current);
-		if (code !== void 0 && SQLITE_CORRUPTION_CODES.has(code)) return code;
+		if (code !== void 0 && SQLITE_CORRUPTION_CODE.test(code)) return code;
 		if (current instanceof SqliteError || current instanceof Error) {
 			if (SQLITE_CORRUPTION_MESSAGE.test(current.message)) return code ?? "SQLITE_CORRUPT";
 			current = getErrorCause(current);

package/out/zero-cache/src/db/sqlite-corruption.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-corruption.js","names":[],"sources":["../../../../../zero-cache/src/db/sqlite-corruption.ts"],"sourcesContent":["import {existsSync, statSync} from 'node:fs';\nimport type {LogContext} from '@rocicorp/logger';\nimport {SqliteError} from '@rocicorp/zero-sqlite3';\nimport {Database} from '../../../zqlite/src/db.ts';\n\nconst SQLITE_CORRUPTION_CODES = new Set(['SQLITE_CORRUPT', 'SQLITE_NOTADB']);\nconst SQLITE_CORRUPTION_MESSAGE =\n  /database disk image is malformed|file is not a database|database is malformed|malformed database/i;\nconst SQLITE_FILE_SUFFIXES = ['', '-wal', '-wal2', '-shm', '-journal'] as const;\nconst MAX_LOGGED_CHECK_ISSUES = 20;\n\ntype ErrorSummary = {\n  readonly name: string;\n  readonly message: string;\n  readonly code?: string | undefined;\n  readonly cause?: ErrorSummary | string | undefined;\n};\n\ntype SQLiteFileStats = {\n  readonly suffix: string;\n  readonly path: string;\n  readonly sizeBytes: number;\n  readonly mtimeMs: number;\n};\n\ntype CheckSummary = {\n  readonly status: 'ok' | 'failed';\n  readonly rowCount: number;\n  readonly issueCount: number;\n  readonly loggedIssueCount: number;\n  readonly truncated: boolean;\n  readonly issues: string[];\n};\n\ntype DiagnosticTarget = {\n  readonly debugName: string;\n  readonly dbPath: string;\n};\n\nconst diagnosticTargets = new Map<number, DiagnosticTarget>();\nlet nextDiagnosticTargetID = 0;\n\nexport function isSQLiteCorruption(e: unknown): boolean {\n  return getSQLiteCorruptionCode(e) !== undefined;\n}\n\nexport function registerSQLiteCorruptionDiagnosticTarget(\n  target: DiagnosticTarget,\n): () => void {\n  const id = nextDiagnosticTargetID++;\n  diagnosticTargets.set(id, target);\n  return () => diagnosticTargets.delete(id);\n}\n\nexport function logLastChanceSQLiteCorruptionDiagnostics(\n  lc: LogContext,\n  cause: unknown,\n): boolean {\n  if (!isSQLiteCorruption(cause) || diagnosticTargets.size === 0) {\n    return false;\n  }\n  for (const {debugName, dbPath} of diagnosticTargets.values()) {\n    logSQLiteCorruptionDiagnostics(lc, debugName, dbPath, cause);\n  }\n  return true;\n}\n\nexport function logSQLiteCorruptionDiagnostics(\n  lc: LogContext,\n  debugName: string,\n  dbPath: string,\n  cause: unknown,\n): void {\n  const start = Date.now();\n  lc.error?.('SQLite replica corruption detected', {\n    debugName,\n    dbPath,\n    cause: summarizeError(cause),\n  });\n\n  logDiagnostic(lc, debugName, 'file-stats', () => ({\n    files: getSQLiteFileStats(dbPath),\n  }));\n\n  let db: Database | undefined;\n  try {\n    db = new Database(lc, dbPath, {readonly: true});\n    db.pragma('busy_timeout = 1000');\n  } catch (e) {\n    lc.error?.('SQLite corruption diagnostic failed', {\n      debugName,\n      step: 'open-readonly',\n      durationMs: Date.now() - start,\n      error: summarizeError(e),\n    });\n    return;\n  }\n\n  try {\n    logDiagnostic(lc, debugName, 'basic-pragmas', () => ({\n      pragmas: getBasicPragmas(db),\n    }));\n    logDiagnostic(lc, debugName, 'replica-metadata', () => ({\n      metadata: getReplicaMetadata(db),\n    }));\n    logDiagnostic(lc, debugName, 'quick-check', () => ({\n      check: runCheck(db, 'quick_check'),\n    }));\n    logDiagnostic(lc, debugName, 'integrity-check', () => ({\n      check: runCheck(db, 'integrity_check'),\n    }));\n    lc.error?.('SQLite corruption diagnostics completed', {\n      debugName,\n      dbPath,\n      durationMs: Date.now() - start,\n    });\n  } finally {\n    db.close();\n  }\n}\n\nfunction getSQLiteCorruptionCode(e: unknown): string | undefined {\n  let current = e;\n  const seen = new Set<unknown>();\n\n  while (current !== undefined && current !== null && !seen.has(current)) {\n    seen.add(current);\n\n    const code = getErrorCode(current);\n    if (code !== undefined && SQLITE_CORRUPTION_CODES.has(code)) {\n      return code;\n    }\n\n    if (current instanceof SqliteError || current instanceof Error) {\n      if (SQLITE_CORRUPTION_MESSAGE.test(current.message)) {\n        return code ?? 'SQLITE_CORRUPT';\n      }\n      current = getErrorCause(current);\n      continue;\n    }\n\n    break;\n  }\n\n  return undefined;\n}\n\nfunction getErrorCode(e: unknown): string | undefined {\n  if (e && typeof e === 'object' && 'code' in e) {\n    const code = (e as {readonly code?: unknown}).code;\n    return typeof code === 'string' ? code : undefined;\n  }\n  return undefined;\n}\n\nfunction getErrorCause(e: Error): unknown {\n  return (e as {readonly cause?: unknown}).cause;\n}\n\nfunction summarizeError(e: unknown, depth = 0): ErrorSummary | string {\n  if (!(e instanceof Error)) {\n    return String(e);\n  }\n  const cause = getErrorCause(e);\n  return {\n    name: e.name,\n    message: e.message,\n    code: getErrorCode(e),\n    cause:\n      cause === undefined || depth >= 4\n        ? undefined\n        : summarizeError(cause, depth + 1),\n  };\n}\n\nfunction getSQLiteFileStats(dbPath: string): SQLiteFileStats[] {\n  const stats: SQLiteFileStats[] = [];\n  for (const suffix of SQLITE_FILE_SUFFIXES) {\n    const path = `${dbPath}${suffix}`;\n    if (!existsSync(path)) {\n      continue;\n    }\n    const stat = statSync(path);\n    stats.push({\n      suffix,\n      path,\n      sizeBytes: stat.size,\n      mtimeMs: stat.mtimeMs,\n    });\n  }\n  return stats;\n}\n\nfunction getBasicPragmas(db: Database) {\n  return {\n    pageSize: firstPragmaValue<number>(db, 'page_size', 'page_size'),\n    pageCount: firstPragmaValue<number>(db, 'page_count', 'page_count'),\n    freelistCount: firstPragmaValue<number>(\n      db,\n      'freelist_count',\n      'freelist_count',\n    ),\n    journalMode: firstPragmaValue<string>(db, 'journal_mode', 'journal_mode'),\n    schemaVersion: firstPragmaValue<number>(\n      db,\n      'schema_version',\n      'schema_version',\n    ),\n    userVersion: firstPragmaValue<number>(db, 'user_version', 'user_version'),\n    applicationID: firstPragmaValue<number>(\n      db,\n      'application_id',\n      'application_id',\n    ),\n  };\n}\n\nfunction getReplicaMetadata(db: Database) {\n  return {\n    versionHistory: queryDiagnostic(() =>\n      db\n        .prepare(\n          `SELECT dataVersion, schemaVersion, minSafeVersion\n           FROM \"_zero.versionHistory\"`,\n        )\n        .get(),\n    ),\n    subscriptionState: queryDiagnostic(() =>\n      db\n        .prepare(\n          `SELECT c.replicaVersion, s.stateVersion as watermark\n           FROM \"_zero.replicationConfig\" as c\n           JOIN \"_zero.replicationState\" as s\n           ON c.lock = s.lock`,\n        )\n        .get(),\n    ),\n    sqliteCatalogCounts: queryDiagnostic(() =>\n      db\n        .prepare(\n          `SELECT type, count(*) as count\n           FROM sqlite_master\n           GROUP BY type\n           ORDER BY type`,\n        )\n        .all(),\n    ),\n  };\n}\n\nfunction queryDiagnostic<T>(query: () => T):\n  | {readonly ok: true; readonly value: T}\n  | {\n      readonly ok: false;\n      readonly error: ErrorSummary | string;\n    } {\n  try {\n    return {ok: true, value: query()};\n  } catch (e) {\n    return {ok: false, error: summarizeError(e)};\n  }\n}\n\nfunction firstPragmaValue<T>(\n  db: Database,\n  pragma: string,\n  column: string,\n): T | undefined {\n  const [row] = db.pragma<Record<string, T>>(pragma);\n  return row?.[column];\n}\n\nfunction runCheck(db: Database, pragma: 'quick_check' | 'integrity_check') {\n  const rows = db.pragma<Record<string, string>>(pragma);\n  const issues = rows\n    .map(row => row[pragma] ?? Object.values(row)[0] ?? '')\n    .filter(issue => issue !== '' && issue !== 'ok');\n  const loggedIssues = issues.slice(0, MAX_LOGGED_CHECK_ISSUES);\n  return {\n    status: issues.length === 0 ? 'ok' : 'failed',\n    rowCount: rows.length,\n    issueCount: issues.length,\n    loggedIssueCount: loggedIssues.length,\n    truncated: issues.length > loggedIssues.length,\n    issues: loggedIssues,\n  } satisfies CheckSummary;\n}\n\nfunction logDiagnostic<T>(\n  lc: LogContext,\n  debugName: string,\n  step: string,\n  fn: () => T,\n): void {\n  const start = Date.now();\n  try {\n    const result = fn();\n    lc.error?.('SQLite corruption diagnostic', {\n      debugName,\n      step,\n      durationMs: Date.now() - start,\n      result,\n    });\n  } catch (e) {\n    lc.error?.('SQLite corruption diagnostic failed', {\n      debugName,\n      step,\n      durationMs: Date.now() - start,\n      error: summarizeError(e),\n    });\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"sqlite-corruption.js","names":[],"sources":["../../../../../zero-cache/src/db/sqlite-corruption.ts"],"sourcesContent":["import {existsSync, statSync} from 'node:fs';\nimport type {LogContext} from '@rocicorp/logger';\nimport {SqliteError} from '@rocicorp/zero-sqlite3';\nimport {Database} from '../../../zqlite/src/db.ts';\n\n// Matches primary corruption codes and extended variants (e.g.\n// SQLITE_CORRUPT_INDEX, SQLITE_CORRUPT_VTAB, SQLITE_CORRUPT_SEQUENCE), which\n// the driver reports because it enables sqlite3_extended_result_codes().\nconst SQLITE_CORRUPTION_CODE = /^SQLITE_(CORRUPT(_|$)|NOTADB$)/;\nconst SQLITE_CORRUPTION_MESSAGE =\n  /database disk image is malformed|file is not a database|database is malformed|malformed database/i;\nconst SQLITE_FILE_SUFFIXES = ['', '-wal', '-wal2', '-shm', '-journal'] as const;\nconst MAX_LOGGED_CHECK_ISSUES = 20;\n\ntype ErrorSummary = {\n  readonly name: string;\n  readonly message: string;\n  readonly code?: string | undefined;\n  readonly cause?: ErrorSummary | string | undefined;\n};\n\ntype SQLiteFileStats = {\n  readonly suffix: string;\n  readonly path: string;\n  readonly sizeBytes: number;\n  readonly mtimeMs: number;\n};\n\ntype CheckSummary = {\n  readonly status: 'ok' | 'failed';\n  readonly rowCount: number;\n  readonly issueCount: number;\n  readonly loggedIssueCount: number;\n  readonly truncated: boolean;\n  readonly issues: string[];\n};\n\ntype DiagnosticTarget = {\n  readonly debugName: string;\n  readonly dbPath: string;\n};\n\ntype RegisteredDiagnosticTarget = DiagnosticTarget & {\n  readonly corruptionChecks: SQLiteCorruptionChecks;\n};\n\nconst diagnosticTargets = new Map<number, RegisteredDiagnosticTarget>();\nlet nextDiagnosticTargetID = 0;\n\nexport type SQLiteCorruptionChecks = boolean;\n\nexport function isSQLiteCorruption(e: unknown): boolean {\n  return getSQLiteCorruptionCode(e) !== undefined;\n}\n\nexport function registerSQLiteCorruptionDiagnosticTarget(\n  target: DiagnosticTarget,\n  corruptionChecks: SQLiteCorruptionChecks = false,\n): () => void {\n  const id = nextDiagnosticTargetID++;\n  diagnosticTargets.set(id, {...target, corruptionChecks});\n  return () => diagnosticTargets.delete(id);\n}\n\nexport function logLastChanceSQLiteCorruptionDiagnostics(\n  lc: LogContext,\n  cause: unknown,\n): boolean {\n  if (!isSQLiteCorruption(cause) || diagnosticTargets.size === 0) {\n    return false;\n  }\n  for (const {\n    debugName,\n    dbPath,\n    corruptionChecks,\n  } of diagnosticTargets.values()) {\n    logSQLiteCorruptionDiagnostics(\n      lc,\n      debugName,\n      dbPath,\n      cause,\n      corruptionChecks,\n    );\n  }\n  return true;\n}\n\nexport function logSQLiteCorruptionDiagnostics(\n  lc: LogContext,\n  debugName: string,\n  dbPath: string,\n  cause: unknown,\n  corruptionChecks: SQLiteCorruptionChecks = false,\n): void {\n  const start = Date.now();\n  lc.error?.('SQLite replica corruption detected', {\n    debugName,\n    dbPath,\n    cause: summarizeError(cause),\n  });\n\n  logDiagnostic(lc, debugName, 'file-stats', () => ({\n    files: getSQLiteFileStats(dbPath),\n  }));\n\n  let db: Database | undefined;\n  try {\n    db = new Database(lc, dbPath, {readonly: true});\n    db.pragma('busy_timeout = 1000');\n  } catch (e) {\n    lc.error?.('SQLite corruption diagnostic failed', {\n      debugName,\n      step: 'open-readonly',\n      durationMs: Date.now() - start,\n      error: summarizeError(e),\n    });\n    return;\n  }\n\n  try {\n    logDiagnostic(lc, debugName, 'basic-pragmas', () => ({\n      pragmas: getBasicPragmas(db),\n    }));\n    logDiagnostic(lc, debugName, 'replica-metadata', () => ({\n      metadata: getReplicaMetadata(db),\n    }));\n    if (corruptionChecks) {\n      logDiagnostic(lc, debugName, 'quick-check', () => ({\n        check: runCheck(db, 'quick_check'),\n      }));\n      logDiagnostic(lc, debugName, 'integrity-check', () => ({\n        check: runCheck(db, 'integrity_check'),\n      }));\n    }\n    lc.error?.('SQLite corruption diagnostics completed', {\n      debugName,\n      dbPath,\n      durationMs: Date.now() - start,\n    });\n  } finally {\n    db.close();\n  }\n}\n\nfunction getSQLiteCorruptionCode(e: unknown): string | undefined {\n  let current = e;\n  const seen = new Set<unknown>();\n\n  while (current !== undefined && current !== null && !seen.has(current)) {\n    seen.add(current);\n\n    const code = getErrorCode(current);\n    if (code !== undefined && SQLITE_CORRUPTION_CODE.test(code)) {\n      return code;\n    }\n\n    if (current instanceof SqliteError || current instanceof Error) {\n      if (SQLITE_CORRUPTION_MESSAGE.test(current.message)) {\n        return code ?? 'SQLITE_CORRUPT';\n      }\n      current = getErrorCause(current);\n      continue;\n    }\n\n    break;\n  }\n\n  return undefined;\n}\n\nfunction getErrorCode(e: unknown): string | undefined {\n  if (e && typeof e === 'object' && 'code' in e) {\n    const code = (e as {readonly code?: unknown}).code;\n    return typeof code === 'string' ? code : undefined;\n  }\n  return undefined;\n}\n\nfunction getErrorCause(e: Error): unknown {\n  return (e as {readonly cause?: unknown}).cause;\n}\n\nfunction summarizeError(e: unknown, depth = 0): ErrorSummary | string {\n  if (!(e instanceof Error)) {\n    return String(e);\n  }\n  const cause = getErrorCause(e);\n  return {\n    name: e.name,\n    message: e.message,\n    code: getErrorCode(e),\n    cause:\n      cause === undefined || depth >= 4\n        ? undefined\n        : summarizeError(cause, depth + 1),\n  };\n}\n\nfunction getSQLiteFileStats(dbPath: string): SQLiteFileStats[] {\n  const stats: SQLiteFileStats[] = [];\n  for (const suffix of SQLITE_FILE_SUFFIXES) {\n    const path = `${dbPath}${suffix}`;\n    if (!existsSync(path)) {\n      continue;\n    }\n    const stat = statSync(path);\n    stats.push({\n      suffix,\n      path,\n      sizeBytes: stat.size,\n      mtimeMs: stat.mtimeMs,\n    });\n  }\n  return stats;\n}\n\nfunction getBasicPragmas(db: Database) {\n  return {\n    pageSize: firstPragmaValue<number>(db, 'page_size', 'page_size'),\n    pageCount: firstPragmaValue<number>(db, 'page_count', 'page_count'),\n    freelistCount: firstPragmaValue<number>(\n      db,\n      'freelist_count',\n      'freelist_count',\n    ),\n    journalMode: firstPragmaValue<string>(db, 'journal_mode', 'journal_mode'),\n    schemaVersion: firstPragmaValue<number>(\n      db,\n      'schema_version',\n      'schema_version',\n    ),\n    userVersion: firstPragmaValue<number>(db, 'user_version', 'user_version'),\n    applicationID: firstPragmaValue<number>(\n      db,\n      'application_id',\n      'application_id',\n    ),\n  };\n}\n\nfunction getReplicaMetadata(db: Database) {\n  return {\n    versionHistory: queryDiagnostic(() =>\n      db\n        .prepare(\n          `SELECT dataVersion, schemaVersion, minSafeVersion\n           FROM \"_zero.versionHistory\"`,\n        )\n        .get(),\n    ),\n    subscriptionState: queryDiagnostic(() =>\n      db\n        .prepare(\n          `SELECT c.replicaVersion, s.stateVersion as watermark\n           FROM \"_zero.replicationConfig\" as c\n           JOIN \"_zero.replicationState\" as s\n           ON c.lock = s.lock`,\n        )\n        .get(),\n    ),\n    sqliteCatalogCounts: queryDiagnostic(() =>\n      db\n        .prepare(\n          `SELECT type, count(*) as count\n           FROM sqlite_master\n           GROUP BY type\n           ORDER BY type`,\n        )\n        .all(),\n    ),\n  };\n}\n\nfunction queryDiagnostic<T>(query: () => T):\n  | {readonly ok: true; readonly value: T}\n  | {\n      readonly ok: false;\n      readonly error: ErrorSummary | string;\n    } {\n  try {\n    return {ok: true, value: query()};\n  } catch (e) {\n    return {ok: false, error: summarizeError(e)};\n  }\n}\n\nfunction firstPragmaValue<T>(\n  db: Database,\n  pragma: string,\n  column: string,\n): T | undefined {\n  const [row] = db.pragma<Record<string, T>>(pragma);\n  return row?.[column];\n}\n\nfunction runCheck(db: Database, pragma: 'quick_check' | 'integrity_check') {\n  const rows = db.pragma<Record<string, string>>(pragma);\n  const issues = rows\n    .map(row => row[pragma] ?? Object.values(row)[0] ?? '')\n    .filter(issue => issue !== '' && issue !== 'ok');\n  const loggedIssues = issues.slice(0, MAX_LOGGED_CHECK_ISSUES);\n  return {\n    status: issues.length === 0 ? 'ok' : 'failed',\n    rowCount: rows.length,\n    issueCount: issues.length,\n    loggedIssueCount: loggedIssues.length,\n    truncated: issues.length > loggedIssues.length,\n    issues: loggedIssues,\n  } satisfies CheckSummary;\n}\n\nfunction logDiagnostic<T>(\n  lc: LogContext,\n  debugName: string,\n  step: string,\n  fn: () => T,\n): void {\n  const start = Date.now();\n  try {\n    const result = fn();\n    lc.error?.('SQLite corruption diagnostic', {\n      debugName,\n      step,\n      durationMs: Date.now() - start,\n      result,\n    });\n  } catch (e) {\n    lc.error?.('SQLite corruption diagnostic failed', {\n      debugName,\n      step,\n      durationMs: Date.now() - start,\n      error: summarizeError(e),\n    });\n  }\n}\n"],"mappings":"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"}

package/out/zero-cache/src/observability/metrics.d.ts

@@ -6,7 +6,7 @@ type Options = MetricOptions & {
 type HistogramOptions = Options & {
     bucketBoundaries: number[];
 };
-export declare const NATIVE_HISTOGRAM_INSTRUMENT_NAMES: readonly ["zero.sync.view_syncer_lag", "zero.sync.view_syncer_hydration"];
+export declare const NATIVE_HISTOGRAM_INSTRUMENT_NAMES: readonly ["zero.sync.view_syncer_lag", "zero.sync.view_syncer_hydration", "zero.sync.e2e_serving_lag"];
 export declare const LONG_DURATION_HISTOGRAM_BOUNDARIES_S: number[];
 export declare function getOrCreateUpDownCounter(category: Category, name: string, description: string): UpDownCounter;
 export declare function getOrCreateUpDownCounter(category: Category, name: string, opts: Options): UpDownCounter;
@@ -27,6 +27,11 @@ export type LatencyHistogram = {
      */
     recordMs(durationMs: number, attributes?: Parameters<Histogram['record']>[1]): void;
 };
+/**
+ * Creates a histogram for dimensionless values without applying the
+ * millisecond-to-second conversion used by the latency helpers below.
+ */
+export declare function getOrCreateValueHistogram(category: Category, name: string, opts: HistogramOptions): Histogram;
 export declare function getOrCreateHistogram(category: Category, name: string, opts: HistogramOptions): LatencyHistogram;
 export declare function getOrCreateNativeHistogram(category: Category, name: string, opts: Options): LatencyHistogram;
 /**

package/out/zero-cache/src/observability/metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/observability/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EAET,aAAa,EACb,eAAe,EACf,aAAa,EACd,MAAM,oBAAoB,CAAC;AAK5B,MAAM,MAAM,QAAQ,GAChB,aAAa,GACb,SAAS,GACT,MAAM,GACN,UAAU,GACV,QAAQ,CAAC;AAIb,KAAK,OAAO,GAAG,aAAa,GAAG;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAAC;AACrD,KAAK,gBAAgB,GAAG,OAAO,GAAG;IAAC,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAAC,CAAC;AAE/D,eAAO,MAAM,iCAAiC,2EAGpC,CAAC;AAEX,eAAO,MAAM,oCAAoC,UAEhD,CAAC;AA4BF,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,aAAa,CAAC;AACjB,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,aAAa,CAAC;AAcjB;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;;;OAMG;IACH,QAAQ,CACN,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAC9C,IAAI,CAAC;CACT,CAAC;AAoBF,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,GACrB,gBAAgB,CAelB;AAKD,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,gBAAgB,CAQlB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,gBAAgB,CAMlB;AAID,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;AACX,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC;AAgBX,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,eAAe,CAAC;AACnB,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,eAAe,CAAC"}
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/observability/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EAET,aAAa,EACb,eAAe,EACf,aAAa,EACd,MAAM,oBAAoB,CAAC;AAK5B,MAAM,MAAM,QAAQ,GAChB,aAAa,GACb,SAAS,GACT,MAAM,GACN,UAAU,GACV,QAAQ,CAAC;AAIb,KAAK,OAAO,GAAG,aAAa,GAAG;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAAC;AACrD,KAAK,gBAAgB,GAAG,OAAO,GAAG;IAAC,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAAC,CAAC;AAE/D,eAAO,MAAM,iCAAiC,wGAIpC,CAAC;AAEX,eAAO,MAAM,oCAAoC,UAEhD,CAAC;AA4BF,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,aAAa,CAAC;AACjB,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,aAAa,CAAC;AAcjB;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;;;OAMG;IACH,QAAQ,CACN,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAC9C,IAAI,CAAC;CACT,CAAC;AAoBF;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,GACrB,SAAS,CAWX;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,GACrB,gBAAgB,CAelB;AAKD,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,gBAAgB,CAQlB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,gBAAgB,CAMlB;AAID,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;AACX,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC;AAgBX,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,eAAe,CAAC;AACnB,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,eAAe,CAAC"}

package/out/zero-cache/src/observability/metrics.js

@@ -1,7 +1,11 @@
 import { metrics } from "@opentelemetry/api";
 //#region ../zero-cache/src/observability/metrics.ts
 var meter;
-var NATIVE_HISTOGRAM_INSTRUMENT_NAMES = ["zero.sync.view_syncer_lag", "zero.sync.view_syncer_hydration"];
+var NATIVE_HISTOGRAM_INSTRUMENT_NAMES = [
+	"zero.sync.view_syncer_lag",
+	"zero.sync.view_syncer_hydration",
+	"zero.sync.e2e_serving_lag"
+];
 var LONG_DURATION_HISTOGRAM_BOUNDARIES_S = [
 	1,
 	2,
@@ -64,6 +68,20 @@ var LATENCY_HISTOGRAM_BOUNDARIES_S = [
 	30
 ];
 var histograms = cache();
+/**
+* Creates a histogram for dimensionless values without applying the
+* millisecond-to-second conversion used by the latency helpers below.
+*/
+function getOrCreateValueHistogram(category, name, opts) {
+	const { bucketBoundaries, ...metricOptions } = opts;
+	return histograms(name, (name) => getMeter().createHistogram(`zero.${category}.${name}`, {
+		...metricOptions,
+		advice: {
+			...metricOptions.advice,
+			explicitBucketBoundaries: bucketBoundaries
+		}
+	}));
+}
 function getOrCreateHistogram(category, name, opts) {
 	const { bucketBoundaries, ...metricOptions } = opts;
 	const h = histograms(name, (name) => getMeter().createHistogram(`zero.${category}.${name}`, {
@@ -113,6 +131,6 @@ function getOrCreateGauge(category, name, opts) {
 	return gauges(name, (name) => getMeter().createObservableGauge(`zero.${category}.${name}`, typeof opts === "string" ? { description: opts } : opts));
 }
 //#endregion
-export { LONG_DURATION_HISTOGRAM_BOUNDARIES_S, NATIVE_HISTOGRAM_INSTRUMENT_NAMES, getOrCreateCounter, getOrCreateGauge, getOrCreateHistogram, getOrCreateLatencyHistogram, getOrCreateNativeHistogram, getOrCreateUpDownCounter };
+export { LONG_DURATION_HISTOGRAM_BOUNDARIES_S, NATIVE_HISTOGRAM_INSTRUMENT_NAMES, getOrCreateCounter, getOrCreateGauge, getOrCreateHistogram, getOrCreateLatencyHistogram, getOrCreateNativeHistogram, getOrCreateUpDownCounter, getOrCreateValueHistogram };
 
 //# sourceMappingURL=metrics.js.map

package/out/zero-cache/src/observability/metrics.js.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.js","names":[],"sources":["../../../../../zero-cache/src/observability/metrics.ts"],"sourcesContent":["import type {\n  Counter,\n  Histogram,\n  Meter,\n  MetricOptions,\n  ObservableGauge,\n  UpDownCounter,\n} from '@opentelemetry/api';\nimport {metrics} from '@opentelemetry/api';\n\n// intentional lazy initialization so it is not started before the SDK is started.\n\nexport type Category =\n  | 'replication' // postgres to replica\n  | 'replica' // health of replica and litestream backup\n  | 'sync' // replica to client\n  | 'mutation'\n  | 'server';\n\nlet meter: Meter | undefined;\n\ntype Options = MetricOptions & {description: string};\ntype HistogramOptions = Options & {bucketBoundaries: number[]};\n\nexport const NATIVE_HISTOGRAM_INSTRUMENT_NAMES = [\n  'zero.sync.view_syncer_lag',\n  'zero.sync.view_syncer_hydration',\n] as const;\n\nexport const LONG_DURATION_HISTOGRAM_BOUNDARIES_S = [\n  1, 2, 5, 10, 30, 60, 120, 300, 600, 1200, 2400, 3600, 7200,\n];\n\nfunction getMeter() {\n  if (!meter) {\n    meter = metrics.getMeter('zero');\n  }\n  return meter;\n}\n\nfunction cache<TRet>(): (\n  name: string,\n  creator: (name: string) => TRet,\n) => TRet {\n  const instruments = new Map<string, TRet>();\n  return (name: string, creator: (name: string) => TRet) => {\n    const existing = instruments.get(name);\n    if (existing) {\n      return existing;\n    }\n\n    const ret = creator(name);\n    instruments.set(name, ret);\n    return ret;\n  };\n}\n\nconst upDownCounters = cache<UpDownCounter>();\n\nexport function getOrCreateUpDownCounter(\n  category: Category,\n  name: string,\n  description: string,\n): UpDownCounter;\nexport function getOrCreateUpDownCounter(\n  category: Category,\n  name: string,\n  opts: Options,\n): UpDownCounter;\nexport function getOrCreateUpDownCounter(\n  category: Category,\n  name: string,\n  opts: string | Options,\n): UpDownCounter {\n  return upDownCounters(name, name =>\n    getMeter().createUpDownCounter(\n      `zero.${category}.${name}`,\n      typeof opts === 'string' ? {description: opts} : opts,\n    ),\n  );\n}\n\n/**\n * A latency histogram whose {@link recordMs} method accepts raw millisecond\n * durations and converts them to seconds internally.\n *\n * Use {@link getOrCreateLatencyHistogram} to create one — the unit (`'s'`),\n * bucket boundaries, and ms→s conversion are all baked in\n */\nexport type LatencyHistogram = {\n  /**\n   * Record a duration. Pass the raw elapsed milliseconds — the conversion to\n   * seconds (required by the `unit: 's'` OTel histogram) is handled internally.\n   *\n   * @param durationMs  Elapsed time in **milliseconds** (do NOT pre-divide).\n   * @param attributes  Optional OTel attributes to attach to the observation.\n   */\n  recordMs(\n    durationMs: number,\n    attributes?: Parameters<Histogram['record']>[1],\n  ): void;\n};\n\n/**\n * Bucket boundaries (in seconds) for zero's latency histograms.\n *\n * The operational range is 1 ms – 5,000 ms (including customers actively\n * tuning queries). ~2× logarithmic steps give proportionally consistent\n * `histogram_quantile` accuracy regardless of where values cluster within\n * that range. 10,000 ms and 30,000 ms are overflow catchers for truly broken\n * states.\n *\n *   1 ms, 2 ms, 5 ms, 10 ms, 20 ms, 50 ms, 100 ms, 200 ms, 500 ms,\n *   1 s, 2 s, 5 s, 10 s, 30 s\n */\nconst LATENCY_HISTOGRAM_BOUNDARIES_S = [\n  0.001, 0.002, 0.005, 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30,\n];\n\nconst histograms = cache<Histogram>();\n\nexport function getOrCreateHistogram(\n  category: Category,\n  name: string,\n  opts: HistogramOptions,\n): LatencyHistogram {\n  const {bucketBoundaries, ...metricOptions} = opts;\n  const h = histograms(name, name =>\n    getMeter().createHistogram(`zero.${category}.${name}`, {\n      ...metricOptions,\n      advice: {\n        ...metricOptions.advice,\n        explicitBucketBoundaries: bucketBoundaries,\n      },\n    }),\n  );\n  return {\n    recordMs: (durationMs, attributes) =>\n      h.record(durationMs / 1000, attributes),\n  };\n}\n\n// Add instruments created through this helper to\n// NATIVE_HISTOGRAM_INSTRUMENT_NAMES so the SDK exports them as exponential\n// histograms.\nexport function getOrCreateNativeHistogram(\n  category: Category,\n  name: string,\n  opts: Options,\n): LatencyHistogram {\n  const h = histograms(name, name =>\n    getMeter().createHistogram(`zero.${category}.${name}`, opts),\n  );\n  return {\n    recordMs: (durationMs, attributes) =>\n      h.record(durationMs / 1000, attributes),\n  };\n}\n\n/**\n * Creates (or retrieves) a latency histogram for the given metric.\n *\n * - `unit` is always `'s'` (seconds), matching the OTel convention.\n * - Bucket boundaries are pre-set for zero's typical operation range\n *   (1 ms – 5 s); see {@link LATENCY_HISTOGRAM_BOUNDARIES_S}.\n * - The returned {@link LatencyHistogram} accepts **milliseconds** via\n *   `recordMs()`, so callers never need to divide by 1000.\n *\n * @example\n * ```ts\n * readonly #hydrationTime = getOrCreateLatencyHistogram(\n *   'sync', 'hydration-time', 'Time to hydrate a query.',\n * );\n * // ...\n * this.#hydrationTime.recordMs(performance.now() - start);\n * ```\n */\nexport function getOrCreateLatencyHistogram(\n  category: Category,\n  name: string,\n  description: string,\n): LatencyHistogram {\n  return getOrCreateHistogram(category, name, {\n    description,\n    unit: 's',\n    bucketBoundaries: LATENCY_HISTOGRAM_BOUNDARIES_S,\n  });\n}\n\nconst counters = cache<Counter>();\n\nexport function getOrCreateCounter(\n  category: Category,\n  name: string,\n  description: string,\n): Counter;\nexport function getOrCreateCounter(\n  category: Category,\n  name: string,\n  opts: Options,\n): Counter;\nexport function getOrCreateCounter(\n  category: Category,\n  name: string,\n  opts: string | Options,\n): Counter {\n  return counters(name, name =>\n    getMeter().createCounter(\n      `zero.${category}.${name}`,\n      typeof opts === 'string' ? {description: opts} : opts,\n    ),\n  );\n}\n\nconst gauges = cache<ObservableGauge>();\n\nexport function getOrCreateGauge(\n  category: Category,\n  name: string,\n  description: string,\n): ObservableGauge;\nexport function getOrCreateGauge(\n  category: Category,\n  name: string,\n  opts: Options,\n): ObservableGauge;\nexport function getOrCreateGauge(\n  category: Category,\n  name: string,\n  opts: string | Options,\n): ObservableGauge {\n  return gauges(name, name =>\n    getMeter().createObservableGauge(\n      `zero.${category}.${name}`,\n      typeof opts === 'string' ? {description: opts} : opts,\n    ),\n  );\n}\n"],"mappings":";;AAmBA,IAAI;AAKJ,IAAa,oCAAoC,CAC/C,6BACA,iCACF;AAEA,IAAa,uCAAuC;CAClD;CAAG;CAAG;CAAG;CAAI;CAAI;CAAI;CAAK;CAAK;CAAK;CAAM;CAAM;CAAM;AACxD;AAEA,SAAS,WAAW;CAClB,IAAI,CAAC,OACH,QAAQ,QAAQ,SAAS,MAAM;CAEjC,OAAO;AACT;AAEA,SAAS,QAGC;CACR,MAAM,8BAAc,IAAI,IAAkB;CAC1C,QAAQ,MAAc,YAAoC;EACxD,MAAM,WAAW,YAAY,IAAI,IAAI;EACrC,IAAI,UACF,OAAO;EAGT,MAAM,MAAM,QAAQ,IAAI;EACxB,YAAY,IAAI,MAAM,GAAG;EACzB,OAAO;CACT;AACF;AAEA,IAAM,iBAAiB,MAAqB;AAY5C,SAAgB,yBACd,UACA,MACA,MACe;CACf,OAAO,eAAe,OAAM,SAC1B,SAAS,EAAE,oBACT,QAAQ,SAAS,GAAG,QACpB,OAAO,SAAS,WAAW,EAAC,aAAa,KAAI,IAAI,IACnD,CACF;AACF;;;;;;;;;;;;;AAmCA,IAAM,iCAAiC;CACrC;CAAO;CAAO;CAAO;CAAM;CAAM;CAAM;CAAK;CAAK;CAAK;CAAG;CAAG;CAAG;CAAI;AACrE;AAEA,IAAM,aAAa,MAAiB;AAEpC,SAAgB,qBACd,UACA,MACA,MACkB;CAClB,MAAM,EAAC,kBAAkB,GAAG,kBAAiB;CAC7C,MAAM,IAAI,WAAW,OAAM,SACzB,SAAS,EAAE,gBAAgB,QAAQ,SAAS,GAAG,QAAQ;EACrD,GAAG;EACH,QAAQ;GACN,GAAG,cAAc;GACjB,0BAA0B;EAC5B;CACF,CAAC,CACH;CACA,OAAO,EACL,WAAW,YAAY,eACrB,EAAE,OAAO,aAAa,KAAM,UAAU,EAC1C;AACF;AAKA,SAAgB,2BACd,UACA,MACA,MACkB;CAClB,MAAM,IAAI,WAAW,OAAM,SACzB,SAAS,EAAE,gBAAgB,QAAQ,SAAS,GAAG,QAAQ,IAAI,CAC7D;CACA,OAAO,EACL,WAAW,YAAY,eACrB,EAAE,OAAO,aAAa,KAAM,UAAU,EAC1C;AACF;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,4BACd,UACA,MACA,aACkB;CAClB,OAAO,qBAAqB,UAAU,MAAM;EAC1C;EACA,MAAM;EACN,kBAAkB;CACpB,CAAC;AACH;AAEA,IAAM,WAAW,MAAe;AAYhC,SAAgB,mBACd,UACA,MACA,MACS;CACT,OAAO,SAAS,OAAM,SACpB,SAAS,EAAE,cACT,QAAQ,SAAS,GAAG,QACpB,OAAO,SAAS,WAAW,EAAC,aAAa,KAAI,IAAI,IACnD,CACF;AACF;AAEA,IAAM,SAAS,MAAuB;AAYtC,SAAgB,iBACd,UACA,MACA,MACiB;CACjB,OAAO,OAAO,OAAM,SAClB,SAAS,EAAE,sBACT,QAAQ,SAAS,GAAG,QACpB,OAAO,SAAS,WAAW,EAAC,aAAa,KAAI,IAAI,IACnD,CACF;AACF"}
+{"version":3,"file":"metrics.js","names":[],"sources":["../../../../../zero-cache/src/observability/metrics.ts"],"sourcesContent":["import type {\n  Counter,\n  Histogram,\n  Meter,\n  MetricOptions,\n  ObservableGauge,\n  UpDownCounter,\n} from '@opentelemetry/api';\nimport {metrics} from '@opentelemetry/api';\n\n// intentional lazy initialization so it is not started before the SDK is started.\n\nexport type Category =\n  | 'replication' // postgres to replica\n  | 'replica' // health of replica and litestream backup\n  | 'sync' // replica to client\n  | 'mutation'\n  | 'server';\n\nlet meter: Meter | undefined;\n\ntype Options = MetricOptions & {description: string};\ntype HistogramOptions = Options & {bucketBoundaries: number[]};\n\nexport const NATIVE_HISTOGRAM_INSTRUMENT_NAMES = [\n  'zero.sync.view_syncer_lag',\n  'zero.sync.view_syncer_hydration',\n  'zero.sync.e2e_serving_lag',\n] as const;\n\nexport const LONG_DURATION_HISTOGRAM_BOUNDARIES_S = [\n  1, 2, 5, 10, 30, 60, 120, 300, 600, 1200, 2400, 3600, 7200,\n];\n\nfunction getMeter() {\n  if (!meter) {\n    meter = metrics.getMeter('zero');\n  }\n  return meter;\n}\n\nfunction cache<TRet>(): (\n  name: string,\n  creator: (name: string) => TRet,\n) => TRet {\n  const instruments = new Map<string, TRet>();\n  return (name: string, creator: (name: string) => TRet) => {\n    const existing = instruments.get(name);\n    if (existing) {\n      return existing;\n    }\n\n    const ret = creator(name);\n    instruments.set(name, ret);\n    return ret;\n  };\n}\n\nconst upDownCounters = cache<UpDownCounter>();\n\nexport function getOrCreateUpDownCounter(\n  category: Category,\n  name: string,\n  description: string,\n): UpDownCounter;\nexport function getOrCreateUpDownCounter(\n  category: Category,\n  name: string,\n  opts: Options,\n): UpDownCounter;\nexport function getOrCreateUpDownCounter(\n  category: Category,\n  name: string,\n  opts: string | Options,\n): UpDownCounter {\n  return upDownCounters(name, name =>\n    getMeter().createUpDownCounter(\n      `zero.${category}.${name}`,\n      typeof opts === 'string' ? {description: opts} : opts,\n    ),\n  );\n}\n\n/**\n * A latency histogram whose {@link recordMs} method accepts raw millisecond\n * durations and converts them to seconds internally.\n *\n * Use {@link getOrCreateLatencyHistogram} to create one — the unit (`'s'`),\n * bucket boundaries, and ms→s conversion are all baked in\n */\nexport type LatencyHistogram = {\n  /**\n   * Record a duration. Pass the raw elapsed milliseconds — the conversion to\n   * seconds (required by the `unit: 's'` OTel histogram) is handled internally.\n   *\n   * @param durationMs  Elapsed time in **milliseconds** (do NOT pre-divide).\n   * @param attributes  Optional OTel attributes to attach to the observation.\n   */\n  recordMs(\n    durationMs: number,\n    attributes?: Parameters<Histogram['record']>[1],\n  ): void;\n};\n\n/**\n * Bucket boundaries (in seconds) for zero's latency histograms.\n *\n * The operational range is 1 ms – 5,000 ms (including customers actively\n * tuning queries). ~2× logarithmic steps give proportionally consistent\n * `histogram_quantile` accuracy regardless of where values cluster within\n * that range. 10,000 ms and 30,000 ms are overflow catchers for truly broken\n * states.\n *\n *   1 ms, 2 ms, 5 ms, 10 ms, 20 ms, 50 ms, 100 ms, 200 ms, 500 ms,\n *   1 s, 2 s, 5 s, 10 s, 30 s\n */\nconst LATENCY_HISTOGRAM_BOUNDARIES_S = [\n  0.001, 0.002, 0.005, 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30,\n];\n\nconst histograms = cache<Histogram>();\n\n/**\n * Creates a histogram for dimensionless values without applying the\n * millisecond-to-second conversion used by the latency helpers below.\n */\nexport function getOrCreateValueHistogram(\n  category: Category,\n  name: string,\n  opts: HistogramOptions,\n): Histogram {\n  const {bucketBoundaries, ...metricOptions} = opts;\n  return histograms(name, name =>\n    getMeter().createHistogram(`zero.${category}.${name}`, {\n      ...metricOptions,\n      advice: {\n        ...metricOptions.advice,\n        explicitBucketBoundaries: bucketBoundaries,\n      },\n    }),\n  );\n}\n\nexport function getOrCreateHistogram(\n  category: Category,\n  name: string,\n  opts: HistogramOptions,\n): LatencyHistogram {\n  const {bucketBoundaries, ...metricOptions} = opts;\n  const h = histograms(name, name =>\n    getMeter().createHistogram(`zero.${category}.${name}`, {\n      ...metricOptions,\n      advice: {\n        ...metricOptions.advice,\n        explicitBucketBoundaries: bucketBoundaries,\n      },\n    }),\n  );\n  return {\n    recordMs: (durationMs, attributes) =>\n      h.record(durationMs / 1000, attributes),\n  };\n}\n\n// Add instruments created through this helper to\n// NATIVE_HISTOGRAM_INSTRUMENT_NAMES so the SDK exports them as exponential\n// histograms.\nexport function getOrCreateNativeHistogram(\n  category: Category,\n  name: string,\n  opts: Options,\n): LatencyHistogram {\n  const h = histograms(name, name =>\n    getMeter().createHistogram(`zero.${category}.${name}`, opts),\n  );\n  return {\n    recordMs: (durationMs, attributes) =>\n      h.record(durationMs / 1000, attributes),\n  };\n}\n\n/**\n * Creates (or retrieves) a latency histogram for the given metric.\n *\n * - `unit` is always `'s'` (seconds), matching the OTel convention.\n * - Bucket boundaries are pre-set for zero's typical operation range\n *   (1 ms – 5 s); see {@link LATENCY_HISTOGRAM_BOUNDARIES_S}.\n * - The returned {@link LatencyHistogram} accepts **milliseconds** via\n *   `recordMs()`, so callers never need to divide by 1000.\n *\n * @example\n * ```ts\n * readonly #hydrationTime = getOrCreateLatencyHistogram(\n *   'sync', 'hydration-time', 'Time to hydrate a query.',\n * );\n * // ...\n * this.#hydrationTime.recordMs(performance.now() - start);\n * ```\n */\nexport function getOrCreateLatencyHistogram(\n  category: Category,\n  name: string,\n  description: string,\n): LatencyHistogram {\n  return getOrCreateHistogram(category, name, {\n    description,\n    unit: 's',\n    bucketBoundaries: LATENCY_HISTOGRAM_BOUNDARIES_S,\n  });\n}\n\nconst counters = cache<Counter>();\n\nexport function getOrCreateCounter(\n  category: Category,\n  name: string,\n  description: string,\n): Counter;\nexport function getOrCreateCounter(\n  category: Category,\n  name: string,\n  opts: Options,\n): Counter;\nexport function getOrCreateCounter(\n  category: Category,\n  name: string,\n  opts: string | Options,\n): Counter {\n  return counters(name, name =>\n    getMeter().createCounter(\n      `zero.${category}.${name}`,\n      typeof opts === 'string' ? {description: opts} : opts,\n    ),\n  );\n}\n\nconst gauges = cache<ObservableGauge>();\n\nexport function getOrCreateGauge(\n  category: Category,\n  name: string,\n  description: string,\n): ObservableGauge;\nexport function getOrCreateGauge(\n  category: Category,\n  name: string,\n  opts: Options,\n): ObservableGauge;\nexport function getOrCreateGauge(\n  category: Category,\n  name: string,\n  opts: string | Options,\n): ObservableGauge {\n  return gauges(name, name =>\n    getMeter().createObservableGauge(\n      `zero.${category}.${name}`,\n      typeof opts === 'string' ? {description: opts} : opts,\n    ),\n  );\n}\n"],"mappings":";;AAmBA,IAAI;AAKJ,IAAa,oCAAoC;CAC/C;CACA;CACA;AACF;AAEA,IAAa,uCAAuC;CAClD;CAAG;CAAG;CAAG;CAAI;CAAI;CAAI;CAAK;CAAK;CAAK;CAAM;CAAM;CAAM;AACxD;AAEA,SAAS,WAAW;CAClB,IAAI,CAAC,OACH,QAAQ,QAAQ,SAAS,MAAM;CAEjC,OAAO;AACT;AAEA,SAAS,QAGC;CACR,MAAM,8BAAc,IAAI,IAAkB;CAC1C,QAAQ,MAAc,YAAoC;EACxD,MAAM,WAAW,YAAY,IAAI,IAAI;EACrC,IAAI,UACF,OAAO;EAGT,MAAM,MAAM,QAAQ,IAAI;EACxB,YAAY,IAAI,MAAM,GAAG;EACzB,OAAO;CACT;AACF;AAEA,IAAM,iBAAiB,MAAqB;AAY5C,SAAgB,yBACd,UACA,MACA,MACe;CACf,OAAO,eAAe,OAAM,SAC1B,SAAS,EAAE,oBACT,QAAQ,SAAS,GAAG,QACpB,OAAO,SAAS,WAAW,EAAC,aAAa,KAAI,IAAI,IACnD,CACF;AACF;;;;;;;;;;;;;AAmCA,IAAM,iCAAiC;CACrC;CAAO;CAAO;CAAO;CAAM;CAAM;CAAM;CAAK;CAAK;CAAK;CAAG;CAAG;CAAG;CAAI;AACrE;AAEA,IAAM,aAAa,MAAiB;;;;;AAMpC,SAAgB,0BACd,UACA,MACA,MACW;CACX,MAAM,EAAC,kBAAkB,GAAG,kBAAiB;CAC7C,OAAO,WAAW,OAAM,SACtB,SAAS,EAAE,gBAAgB,QAAQ,SAAS,GAAG,QAAQ;EACrD,GAAG;EACH,QAAQ;GACN,GAAG,cAAc;GACjB,0BAA0B;EAC5B;CACF,CAAC,CACH;AACF;AAEA,SAAgB,qBACd,UACA,MACA,MACkB;CAClB,MAAM,EAAC,kBAAkB,GAAG,kBAAiB;CAC7C,MAAM,IAAI,WAAW,OAAM,SACzB,SAAS,EAAE,gBAAgB,QAAQ,SAAS,GAAG,QAAQ;EACrD,GAAG;EACH,QAAQ;GACN,GAAG,cAAc;GACjB,0BAA0B;EAC5B;CACF,CAAC,CACH;CACA,OAAO,EACL,WAAW,YAAY,eACrB,EAAE,OAAO,aAAa,KAAM,UAAU,EAC1C;AACF;AAKA,SAAgB,2BACd,UACA,MACA,MACkB;CAClB,MAAM,IAAI,WAAW,OAAM,SACzB,SAAS,EAAE,gBAAgB,QAAQ,SAAS,GAAG,QAAQ,IAAI,CAC7D;CACA,OAAO,EACL,WAAW,YAAY,eACrB,EAAE,OAAO,aAAa,KAAM,UAAU,EAC1C;AACF;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,4BACd,UACA,MACA,aACkB;CAClB,OAAO,qBAAqB,UAAU,MAAM;EAC1C;EACA,MAAM;EACN,kBAAkB;CACpB,CAAC;AACH;AAEA,IAAM,WAAW,MAAe;AAYhC,SAAgB,mBACd,UACA,MACA,MACS;CACT,OAAO,SAAS,OAAM,SACpB,SAAS,EAAE,cACT,QAAQ,SAAS,GAAG,QACpB,OAAO,SAAS,WAAW,EAAC,aAAa,KAAI,IAAI,IACnD,CACF;AACF;AAEA,IAAM,SAAS,MAAuB;AAYtC,SAAgB,iBACd,UACA,MACA,MACiB;CACjB,OAAO,OAAO,OAAM,SAClB,SAAS,EAAE,sBACT,QAAQ,SAAS,GAAG,QACpB,OAAO,SAAS,WAAW,EAAC,aAAa,KAAI,IAAI,IACnD,CACF;AACF"}

package/out/zero-cache/src/server/backup-watermark-poller.js

@@ -0,0 +1,31 @@
+import { must } from "../../../shared/src/must.js";
+import { parentWorker, singleProcessMode } from "../types/processes.js";
+import { getZeroConfig } from "../config/zero-config.js";
+import { exitAfter, runUntilKilled } from "../services/life-cycle.js";
+import { createLogContext } from "./logging.js";
+import { VfsBackupWatermarkPoller } from "../services/litestream/vfs-watermark-poller.js";
+import { LogContext, consoleLogSink } from "@rocicorp/logger";
+//#region ../zero-cache/src/server/backup-watermark-poller.ts
+var lc = new LogContext("info", {}, consoleLogSink);
+async function runWorker(parent, env, ...argv) {
+	const config = getZeroConfig({
+		env,
+		argv
+	});
+	lc = createLogContext(config, "backup-watermark-poller");
+	const { litestream, replica } = config;
+	parent.send(["ready", { ready: true }]);
+	await runUntilKilled(lc, parent, new VfsBackupWatermarkPoller(lc, parent, {
+		localDbFile: replica.file,
+		backupURL: must(litestream.backupURL, "Missing --litestream-backup-url for backup watermark reader"),
+		endpoint: litestream.endpoint,
+		region: litestream.region,
+		extensionPath: litestream.vfsExtensionPath,
+		remotePollIntervalMs: litestream.vfsProbeIntervalMs
+	}));
+}
+if (!singleProcessMode()) exitAfter(() => lc, () => runWorker(must(parentWorker), process.env, ...process.argv.slice(2)));
+//#endregion
+export { runWorker as default };
+
+//# sourceMappingURL=backup-watermark-poller.js.map

package/out/zero-cache/src/server/backup-watermark-poller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-watermark-poller.js","names":[],"sources":["../../../../../zero-cache/src/server/backup-watermark-poller.ts"],"sourcesContent":["import {consoleLogSink, LogContext} from '@rocicorp/logger';\nimport {must} from '../../../shared/src/must.ts';\nimport {getZeroConfig} from '../config/zero-config.ts';\nimport {exitAfter, runUntilKilled} from '../services/life-cycle.ts';\nimport {VfsBackupWatermarkPoller} from '../services/litestream/vfs-watermark-poller.ts';\nimport {\n  parentWorker,\n  singleProcessMode,\n  type Worker,\n} from '../types/processes.ts';\nimport {createLogContext} from './logging.ts';\n\nlet lc = new LogContext('info', {}, consoleLogSink);\n\nexport default async function runWorker(\n  parent: Worker,\n  env: NodeJS.ProcessEnv,\n  ...argv: string[]\n): Promise<void> {\n  const config = getZeroConfig({env, argv});\n  lc = createLogContext(config, 'backup-watermark-poller');\n  const {litestream, replica} = config;\n\n  parent.send(['ready', {ready: true}]);\n\n  await runUntilKilled(\n    lc,\n    parent,\n    new VfsBackupWatermarkPoller(lc, parent, {\n      localDbFile: replica.file,\n      backupURL: must(\n        litestream.backupURL,\n        'Missing --litestream-backup-url for backup watermark reader',\n      ),\n      endpoint: litestream.endpoint,\n      region: litestream.region,\n      extensionPath: litestream.vfsExtensionPath,\n      remotePollIntervalMs: litestream.vfsProbeIntervalMs,\n    }),\n  );\n}\n\n// fork()\nif (!singleProcessMode()) {\n  void exitAfter(\n    () => lc,\n    () => runWorker(must(parentWorker), process.env, ...process.argv.slice(2)),\n  );\n}\n"],"mappings":";;;;;;;;AAYA,IAAI,KAAK,IAAI,WAAW,QAAQ,CAAC,GAAG,cAAc;AAElD,eAA8B,UAC5B,QACA,KACA,GAAG,MACY;CACf,MAAM,SAAS,cAAc;EAAC;EAAK;CAAI,CAAC;CACxC,KAAK,iBAAiB,QAAQ,yBAAyB;CACvD,MAAM,EAAC,YAAY,YAAW;CAE9B,OAAO,KAAK,CAAC,SAAS,EAAC,OAAO,KAAI,CAAC,CAAC;CAEpC,MAAM,eACJ,IACA,QACA,IAAI,yBAAyB,IAAI,QAAQ;EACvC,aAAa,QAAQ;EACrB,WAAW,KACT,WAAW,WACX,6DACF;EACA,UAAU,WAAW;EACrB,QAAQ,WAAW;EACnB,eAAe,WAAW;EAC1B,sBAAsB,WAAW;CACnC,CAAC,CACH;AACF;AAGA,IAAI,CAAC,kBAAkB,GACrB,gBACQ,UACA,UAAU,KAAK,YAAY,GAAG,QAAQ,KAAK,GAAG,QAAQ,KAAK,MAAM,CAAC,CAAC,CAC3E"}

package/out/zero-cache/src/server/change-streamer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"change-streamer.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/server/change-streamer.ts"],"names":[],"mappings":"AA+BA,OAAO,EAGL,KAAK,MAAM,EACZ,MAAM,uBAAuB,CAAC;AAQ/B,wBAA8B,SAAS,CACrC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,IAAI,CAAC,CAsMf"}
+{"version":3,"file":"change-streamer.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/server/change-streamer.ts"],"names":[],"mappings":"AAqCA,OAAO,EAIL,KAAK,MAAM,EACZ,MAAM,uBAAuB,CAAC;AAU/B,wBAA8B,SAAS,CACrC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,IAAI,CAAC,CA6Tf"}

package/out/zero-cache/src/server/change-streamer.js

@@ -1,80 +1,117 @@
 import { assert } from "../../../shared/src/asserts.js";
 import { must } from "../../../shared/src/must.js";
-import { parentWorker, singleProcessMode } from "../types/processes.js";
+import { childWorker, parentWorker, singleProcessMode } from "../types/processes.js";
 import { getShardConfig } from "../types/shards.js";
 import { getNormalizedZeroConfig } from "../config/zero-config.js";
 import { DatabaseInitError } from "../../../zqlite/src/db.js";
+import { getOrCreateGauge } from "../observability/metrics.js";
 import { connectPgClient } from "../types/pg.js";
 import { registerSQLiteCorruptionDiagnosticTarget } from "../db/sqlite-corruption.js";
-import { exitAfter, runUntilKilled } from "../services/life-cycle.js";
+import { ProcessManager, exitAfter, runUntilKilled } from "../services/life-cycle.js";
 import { createLogContext } from "./logging.js";
+import { REPLICATOR_URL } from "./worker-urls.js";
 import { getServerContext } from "../config/server-context.js";
 import { deleteLiteDB } from "../db/delete-lite-db.js";
 import { warmupConnections } from "../db/warmup.js";
 import { initEventSink, publishCriticalEvent } from "../observability/events.js";
 import { AutoResetSignal } from "../services/change-streamer/schema/tables.js";
-import { upgradeReplica } from "../services/change-source/common/replica-schema.js";
 import { ReplicationStatusPublisher, replicationStatusError } from "../services/replicator/replication-status.js";
+import { changeLogFileName, deleteChangeLogDB } from "../services/replicator/change-log-db.js";
+import { startReplicaBackupProcess } from "../services/litestream/commands.js";
 import { initializeCustomChangeSource } from "../services/change-source/custom/change-source.js";
 import { initializePostgresChangeSource } from "../services/change-source/pg/change-source.js";
-import { ChangeStreamerHttpServer } from "../services/change-streamer/change-streamer-http.js";
-import { BackupNotFoundException, restoreReplica } from "../services/litestream/commands.js";
 import { createBackupCleanupMonitor } from "../services/change-streamer/backup-cleanup-monitor-factory.js";
-import { initChangeStreamerSchema } from "../services/change-streamer/schema/init.js";
+import { ChangeStreamerHttpServer } from "../services/change-streamer/change-streamer-http.js";
+import { sqliteFileBytes } from "../services/replicator/sqlite-change-log-observability.js";
 import { PurgeLocker } from "../services/change-streamer/storer.js";
 import { initializeStreamer } from "../services/change-streamer/change-streamer-service.js";
-import { ReplicaMonitor } from "../services/change-streamer/replica-monitor.js";
+import { initChangeStreamerSchema } from "../services/change-streamer/schema/init.js";
 import { startOtelAuto } from "./otel-start.js";
+import { resolver } from "@rocicorp/resolver";
 import { LogContext, consoleLogSink } from "@rocicorp/logger";
 //#region ../zero-cache/src/server/change-streamer.ts
 var lc = new LogContext("info", {}, consoleLogSink);
 async function runWorker(parent, env, ...argv) {
-	const workerStartTime = Date.now();
 	const config = getNormalizedZeroConfig({
 		env,
 		argv
 	});
-	const { taskID, changeStreamer: { port, address, protocol, startupDelayMs, backPressureLimitHeapProportion, flowControlConsensusPaddingSeconds }, upstream, change, replica, initialSync, keepaliveTimeoutMs } = config;
+	const { taskID, changeStreamer: { port, address, protocol, startupDelayMs, backPressureLimitHeapProportion, flowControlConsensusTimeoutProportion, flowControlSlowSubscriberGracePeriodSeconds, sqliteChangeLogMode, sqliteChangeLogRetentionMs, sqliteChangeLogReadBatchRows, sqliteChangeLogPurgeBatchRows, sqliteChangeLogBarrierTimeoutMs }, autoReset, replicationLag, litestream, upstream, change, replica, initialSync, keepaliveTimeoutMs, sqliteCorruptionChecks } = config;
 	startOtelAuto(createLogContext(config, "change-streamer", 0, false), "change-streamer", 0);
 	lc = createLogContext(config, "change-streamer");
 	registerSQLiteCorruptionDiagnosticTarget({
 		debugName: "change-streamer replica",
 		dbPath: replica.file
-	});
+	}, sqliteCorruptionChecks);
 	initEventSink(lc, config);
 	const changeDB = await connectPgClient(lc, change.db, "change-streamer", { max: change.maxConns }, { sendStringAsJson: true });
 	warmupConnections(lc, changeDB, "change").catch(() => {});
-	const { autoReset, replicationLag } = config;
 	const shard = getShardConfig(config);
 	await initChangeStreamerSchema(lc, changeDB, shard);
-	let purgeLock = await new PurgeLocker(lc, shard, changeDB).acquire();
-	if (purgeLock) try {
-		await restoreReplica(lc, config, purgeLock);
-	} catch (e) {
-		const log = e instanceof BackupNotFoundException ? "warn" : "error";
-		lc[log]?.(`error restoring backup. resyncing the replica: ${String(e)}`, e);
-		await purgeLock.release();
-		purgeLock = null;
-	}
+	let purgeLock = litestream.backupURL && litestream.executable ? await new PurgeLocker(lc, shard, changeDB).acquire() : null;
+	const restoreOptions = {
+		litestream,
+		constraints: purgeLock ?? void 0
+	};
 	let changeStreamer;
+	let backupURL;
 	const context = getServerContext(config);
+	const sqliteChangeLogEnabled = sqliteChangeLogMode !== "off";
+	const sqliteChangeLogComparing = sqliteChangeLogMode === "compare" || sqliteChangeLogMode === "serve";
+	if (sqliteChangeLogEnabled) {
+		const changeLogFile = changeLogFileName(replica.file);
+		registerSQLiteCorruptionDiagnosticTarget({
+			debugName: "change-streamer change-log",
+			dbPath: changeLogFile
+		}, sqliteCorruptionChecks);
+		getOrCreateGauge("replica", "sqlite_change_log.file_bytes", {
+			description: "The SQLite change log's total on-disk footprint: its main db file plus its wal sidecars.",
+			unit: "By"
+		}).addCallback(async (o) => o.observe(await sqliteFileBytes(lc, changeLogFile)));
+	}
+	let waitForFirstBackupBeforeServing = false;
 	for (const first of [true, false]) try {
-		const { changeSource, subscriptionState } = upstream.type === "pg" ? await initializePostgresChangeSource(lc, upstream.db, shard, replica.file, {
+		const { changeSource, subscriptionState, destinationBackupURL, replicaID, waitForBackupBeforeServing } = upstream.type === "pg" ? await initializePostgresChangeSource(lc, upstream.db, shard, replica.file, {
 			...initialSync,
 			replicationSlotFailover: upstream.pgReplicationSlotFailover
-		}, context, replicationLag.reportIntervalMs) : await initializeCustomChangeSource(lc, upstream.db, shard, replica.file, context);
+		}, context, replicationLag.reportIntervalMs, restoreOptions, { backupV5: litestream.backupUsingV5 }, purgeLock, upstream.pgStreamInboundTimeoutMs) : await initializeCustomChangeSource(lc, upstream.db, shard, replica.file, context, restoreOptions);
 		const replicationStatusPublisher = ReplicationStatusPublisher.forReplicaFile(replica.file);
-		changeStreamer = await initializeStreamer(lc, shard, taskID, address, protocol, changeDB, changeSource, replicationStatusPublisher, subscriptionState, purgeLock, autoReset ?? false, {
+		changeStreamer = await initializeStreamer(lc, shard, taskID, address, protocol, changeDB, changeSource, replicationStatusPublisher, subscriptionState, destinationBackupURL ? {
+			backupURL: destinationBackupURL,
+			litestreamVersion: litestream.backupUsingV5 ? "v5" : "legacy"
+		} : null, purgeLock, autoReset ?? false, {
 			backPressureLimitHeapProportion,
-			flowControlConsensusPaddingSeconds,
+			flowControlConsensusTimeoutProportion,
+			flowControlSlowSubscriberGracePeriodMs: flowControlSlowSubscriberGracePeriodSeconds > 0 ? flowControlSlowSubscriberGracePeriodSeconds * 1e3 : void 0,
 			statementTimeoutMs: change.statementTimeoutMs,
-			changeLogBatchSize: change.logBatchSize
+			changeLogBatchSize: change.logBatchSize,
+			sqliteCatchup: {
+				changeLogFile: changeLogFileName(replica.file),
+				readBatchRows: sqliteChangeLogReadBatchRows,
+				barrierTimeoutMs: sqliteChangeLogBarrierTimeoutMs
+			},
+			sqliteChangeLogWriter: sqliteChangeLogEnabled ? {
+				replicaFile: replica.file,
+				identity: {
+					epoch: null,
+					generation: subscriptionState.replicaVersion,
+					replicaID
+				}
+			} : void 0,
+			sqliteChangeLogPurge: sqliteChangeLogEnabled ? {
+				retentionMs: sqliteChangeLogRetentionMs,
+				batchRows: sqliteChangeLogPurgeBatchRows
+			} : void 0,
+			sqliteChangeLogCompare: sqliteChangeLogComparing ? { replicaFile: replica.file } : void 0
 		}, setTimeout);
+		backupURL = destinationBackupURL;
+		waitForFirstBackupBeforeServing = waitForBackupBeforeServing;
 		break;
 	} catch (e) {
 		if (first && e instanceof AutoResetSignal) {
 			lc.warn?.(`resetting replica ${replica.file}`, e);
 			deleteLiteDB(replica.file);
+			deleteChangeLogDB(replica.file);
 			await purgeLock?.release();
 			purgeLock = null;
 			continue;
@@ -83,23 +120,46 @@ async function runWorker(parent, env, ...argv) {
 		throw e;
 	}
 	assert(changeStreamer, `resetting replica did not advance replicaVersion`);
-	await upgradeReplica(lc, "change-streamer-init", replica.file);
+	const processes = new ProcessManager(lc, parent);
+	if (backupURL) {
+		lc.info?.("setting up backup to", backupURL);
+		litestream.backupURL = backupURL;
+		const { promise: backupStarted, resolve } = resolver();
+		processes.addWorker(childWorker(REPLICATOR_URL, env, "backup"), "supporting", "backup-replicator").once("message", () => {
+			processes.addSubprocess(startReplicaBackupProcess(lc, litestream, replica.file), "supporting", "litestream");
+			resolve();
+		});
+		await backupStarted;
+	}
 	const backupMonitor = createBackupCleanupMonitor({
 		lc,
+		processes,
 		config,
 		replicaFile: replica.file,
 		changeStreamer,
-		initialCleanupDelayMs: Date.now() - workerStartTime,
 		env
 	});
-	const monitor = backupMonitor ?? new ReplicaMonitor(lc, replica.file, changeStreamer);
 	const changeStreamerWebServer = new ChangeStreamerHttpServer(lc, {
 		port,
 		keepaliveTimeoutMs,
 		startupDelayMs
-	}, parent, changeStreamer, backupMonitor);
-	parent.send(["ready", { ready: true }]);
-	return runUntilKilled(lc, parent, changeStreamerWebServer, monitor);
+	}, parent, changeStreamer);
+	if (waitForFirstBackupBeforeServing) {
+		const start = performance.now();
+		lc.info?.(`awaiting initial backup ...`);
+		backupMonitor.firstBackupReceived().then(() => {
+			const elapsed = performance.now() - start;
+			lc.info?.(`initial backup confirmed after ${elapsed.toFixed(2)}ms`);
+			parent.send(["ready", { ready: true }]);
+		});
+	} else parent.send(["ready", { ready: true }]);
+	try {
+		await runUntilKilled(lc, parent, changeStreamerWebServer, backupMonitor);
+	} catch (err) {
+		processes.logErrorAndExit(err, "change-streamer");
+	} finally {
+		await processes.shutdown();
+	}
 }
 if (!singleProcessMode()) exitAfter(() => lc, () => runWorker(must(parentWorker), process.env, ...process.argv.slice(2)).catch(async (e) => {
 	await publishCriticalEvent(lc, replicationStatusError(lc, "Initializing", e));