@rocicorp/zero 1.11.0-head-86ca5eff-20261014 → 1.11.1

package/out/zero-cache/src/services/replicator/schema/backfilling.js.map

@@ -1 +1 @@
-{"version":3,"file":"backfilling.js","names":["#db","#run","#upsert","#renameTable","#dropTable","#renameColumn","#deleteColumn","#getProgress","#setProgress","#dropColumn"],"sources":["../../../../../../../zero-cache/src/services/replicator/schema/backfilling.ts"],"sourcesContent":["/**\n * The replica's backfill cookie, keyed by upstream identity.\n *\n * `_zero.column_metadata.backfill` already records which columns are being\n * backfilled, and it stays authoritative for `isBackfilling`, which is what the\n * replica's own read paths use. What it cannot do is name the table an upstream\n * would recognize: it is keyed by *lite* table name, and `liteTableName()`\n * collapses the `public` schema and has no inverse anywhere in the tree. A lite\n * name containing a dot is ambiguous — `{public, \"a.b\"}` and `{a, b}` produce\n * the same string — and a table with backfilling columns and no\n * `_zero.tableMetadata` row (legal, since its metadata is optional) cannot be\n * resolved at all.\n *\n * That is the whole of what blocks a change log from being initialized out of a\n * restored replica, so this table carries the identity the reconstruction needs:\n * a straight row copy into the change log's own cookie tables, with nothing to\n * reconstruct and nothing to guess. The replica's copy is the *seed* source; the\n * change log's copy (`replicator/change-log-cookies.ts`) is the *working* set,\n * folded forward from the seed as the log's head advances.\n *\n * The cost is a second copy of `backfill` inside the replica, taken\n * deliberately — though not to save writes: `_zero.column_metadata` is written\n * only by initial sync, the DDL handlers, and backfill completion, so two more\n * columns on it would be free. It is a matter of shape. That table is keyed by\n * lite table name, so `schema`/`table` would be non-key duplicates of its own\n * key, to be held in sync with it across every rename with no answer to which\n * encoding is authoritative. This one is keyed exactly as `cdc.backfilling` and\n * `_zero.changeLogBackfilling` are, which is what makes the change log's\n * initialization comparison a row-set diff rather than a translation, and what\n * lets all three stores interpret the same fold. It also holds in-flight backfills and nothing else,\n * where the same query against `column_metadata` is an unindexed scan over a row\n * per column of every table.\n *\n * This table is write-only from the replica's perspective. Nothing in the\n * replicator reads it; it exists to be read by the change-streamer.\n */\n\nimport type {LogContext} from '@rocicorp/logger';\nimport {unreachable} from '../../../../../shared/src/asserts.ts';\nimport {BigIntJSON} from '../../../../../shared/src/bigint-json.ts';\nimport type {Database, Statement} from '../../../../../zqlite/src/db.ts';\nimport {getOrCreateCounter} from '../../../observability/metrics.ts';\nimport {liteTableName} from '../../../types/names.ts';\nimport type {\n  BackfillID,\n  BackfillProgressMark,\n  Identifier,\n  SchemaChange,\n  TableMetadata,\n} from '../../change-source/protocol/current/data.ts';\nimport type {BackfillRequest} from '../../change-source/protocol/current/upstream.ts';\nimport {\n  backfillRequestsFrom,\n  cookieOps,\n  type CookieOp,\n  type CookieSet,\n} from '../change-log-cookies.ts';\n\nexport const BACKFILLING_TABLE = '_zero.backfilling';\n\n// `backfill` holds the JSON that `cdc.backfilling` holds as JSONB. SQLite has\n// no JSONB, and nothing here queries into the document: it is stored to be\n// handed back to the change source verbatim.\n//\n// `progress` holds the JSON of the BackfillProgressMark up to which the\n// column's backfill data has been received contiguously (see\n// `acceptBackfill()`), or NULL if no data has been received (i.e. the backfill\n// must start from scratch). It is deliberately a separate column from\n// `backfill` so that the cookie set (and its comparison with the change log's\n// cookie jars) is unaffected by it.\nexport const CREATE_BACKFILLING_TABLE = /*sql*/ `\n  CREATE TABLE \"${BACKFILLING_TABLE}\" (\n    \"schema\"   TEXT NOT NULL,\n    \"table\"    TEXT NOT NULL,\n    \"column\"   TEXT NOT NULL,\n    \"backfill\" TEXT NOT NULL,\n    \"progress\" TEXT,\n    PRIMARY KEY (\"schema\", \"table\", \"column\")\n  );\n`;\n\n/**\n * The replica's interpreter of the cookie fold in\n * `replicator/change-log-cookies.ts`.\n *\n * The fold is shared rather than re-implemented for the same reason the\n * Postgres and SQLite change logs share it: the three stores must agree on every\n * transition forever, and the failure mode when they drift is a backfill that is\n * silently never re-requested, on a column that is then silently never\n * populated. Sharing it makes the replica-versus-Postgres comparison a\n * regression test on the interpreters rather than on three implementations of\n * the same switch.\n *\n * Only the backfill half of the fold is interpreted here. The replica's metadata\n * cookie is `_zero.tableMetadata.upstreamMetadata`, which `TableMetadataTracker`\n * already maintains at the same sites, so an `upsert-metadata` op is inert.\n *\n * Statements are lazily prepared, matching `TableMetadataTracker`: a replica\n * that never sees a schema change never prepares any of them.\n */\nexport class BackfillingTracker {\n  readonly #db: Database;\n\n  #upsert: Statement | undefined;\n  #renameTable: Statement | undefined;\n  #dropTable: Statement | undefined;\n  #renameColumn: Statement | undefined;\n  #dropColumn: Statement | undefined;\n  #getProgress: Statement | undefined;\n  #setProgress: Statement | undefined;\n\n  constructor(db: Database) {\n    this.#db = db;\n  }\n\n  /**\n   * Applies the change's backfill-cookie ops, returning the ops that were\n   * applied. Changes that carry no backfill state — index changes, metadata-only\n   * updates, and the `create-table` / `add-column` variants from a change source\n   * that does not support backfill — apply nothing.\n   */\n  apply(change: SchemaChange): CookieOp[] {\n    const ops = cookieOps(change);\n    for (const op of ops) {\n      this.#run(op);\n    }\n    return ops;\n  }\n\n  #run(op: CookieOp): void {\n    switch (op.op) {\n      case 'upsert-metadata':\n        // Maintained by TableMetadataTracker in \"_zero.tableMetadata\".\n        break;\n\n      case 'upsert-backfill':\n        (this.#upsert ??= this.#db.prepare(/*sql*/ `\n          INSERT INTO \"${BACKFILLING_TABLE}\"\n            (\"schema\", \"table\", \"column\", \"backfill\") VALUES (?, ?, ?, ?)\n            ON CONFLICT (\"schema\", \"table\", \"column\")\n            DO UPDATE SET \"backfill\" = excluded.\"backfill\", \"progress\" = NULL\n        `)).run(\n          op.table.schema,\n          op.table.name,\n          op.column,\n          BigIntJSON.stringify(op.backfill),\n        );\n        break;\n\n      case 'rename-table':\n        (this.#renameTable ??= this.#db.prepare(/*sql*/ `\n          UPDATE \"${BACKFILLING_TABLE}\"\n            SET \"schema\" = ?, \"table\" = ? WHERE \"schema\" = ? AND \"table\" = ?\n        `)).run(op.new.schema, op.new.name, op.old.schema, op.old.name);\n        break;\n\n      case 'drop-table':\n        (this.#dropTable ??= this.#db.prepare(/*sql*/ `\n          DELETE FROM \"${BACKFILLING_TABLE}\"\n            WHERE \"schema\" = ? AND \"table\" = ?\n        `)).run(op.table.schema, op.table.name);\n        break;\n\n      case 'rename-column':\n        (this.#renameColumn ??= this.#db.prepare(/*sql*/ `\n          UPDATE \"${BACKFILLING_TABLE}\" SET \"column\" = ?\n            WHERE \"schema\" = ? AND \"table\" = ? AND \"column\" = ?\n        `)).run(op.new, op.table.schema, op.table.name, op.old);\n        break;\n\n      case 'drop-column':\n        this.#deleteColumn(op.table, op.column);\n        break;\n\n      case 'complete-backfill':\n        // A per-column delete rather than an `IN` list, which cannot be a\n        // single prepared statement across arities. The columns of one\n        // completed backfill are few, and this runs only on schema changes.\n        for (const column of op.columns) {\n          this.#deleteColumn(op.table, column);\n        }\n        break;\n\n      default:\n        unreachable(op);\n    }\n  }\n\n  /**\n   * Returns the tracked progress of the backfilling columns of the `table`,\n   * keyed by column name. Columns that are not backfilling are absent.\n   */\n  getProgress(\n    table: Identifier,\n  ): Map<string, BackfillProgressMark | undefined> {\n    const rows = (this.#getProgress ??= this.#db.prepare(/*sql*/ `\n      SELECT \"column\", \"progress\" FROM \"${BACKFILLING_TABLE}\"\n        WHERE \"schema\" = ? AND \"table\" = ?\n    `)).all<{column: string; progress: string | null}>(\n      table.schema,\n      table.name,\n    );\n    return new Map(\n      rows.map(({column, progress}) => [\n        column,\n        progress === null\n          ? undefined\n          : (BigIntJSON.parse(progress) as BackfillProgressMark),\n      ]),\n    );\n  }\n\n  /** Sets (or clears) the tracked progress of a backfilling column. */\n  setProgress(\n    table: Identifier,\n    column: string,\n    progress: BackfillProgressMark | undefined,\n  ): void {\n    (this.#setProgress ??= this.#db.prepare(/*sql*/ `\n      UPDATE \"${BACKFILLING_TABLE}\" SET \"progress\" = ?\n        WHERE \"schema\" = ? AND \"table\" = ? AND \"column\" = ?\n    `)).run(\n      progress === undefined ? null : BigIntJSON.stringify(progress),\n      table.schema,\n      table.name,\n      column,\n    );\n  }\n\n  /**\n   * Marks the backfill of the `columns` as complete. This is the subset of\n   * a `backfill-completed` message's columns (including row key columns)\n   * whose progress is contiguous with the message.\n   */\n  complete(table: Identifier, columns: readonly string[]): void {\n    this.#run({op: 'complete-backfill', table, columns});\n  }\n\n  #deleteColumn(table: Identifier, column: string): void {\n    (this.#dropColumn ??= this.#db.prepare(/*sql*/ `\n      DELETE FROM \"${BACKFILLING_TABLE}\"\n        WHERE \"schema\" = ? AND \"table\" = ? AND \"column\" = ?\n    `)).run(table.schema, table.name, column);\n  }\n}\n\n/**\n * Returns the {@link BackfillRequest}s from the current replica cookies. The\n * result has the same shape as the Postgres initialization result.\n *\n * The caller must pair this snapshot with the replica state version. When the\n * replica trails the change log, the comparison applies the missing schema\n * changes before it compares the results.\n */\nexport function readBackfillRequests(db: Database): BackfillRequest[] {\n  return backfillRequestsFrom(readReplicaCookies(db));\n}\n\n/**\n * Returns the {@link BackfillRequest}s of the replica's pending backfills,\n * including the tracked progress of each column. These are the backfills that\n * a subscriber reports to the change-streamer when starting a subscription.\n *\n * The caller must pair this snapshot with the replica state version.\n */\nexport function readReplicaBackfills(db: Database): BackfillRequest[] {\n  const requests = readBackfillRequests(db);\n  const progress = db\n    .prepare(/*sql*/ `\n      SELECT \"schema\", \"table\", \"column\", \"progress\"\n        FROM \"${BACKFILLING_TABLE}\" WHERE \"progress\" IS NOT NULL\n    `)\n    .all<{schema: string; table: string; column: string; progress: string}>();\n  for (const {schema, table, column, progress: mark} of progress) {\n    const req = requests.find(\n      r => r.table.schema === schema && r.table.name === table,\n    );\n    const col = req?.columns[column];\n    if (col) {\n      col.progress = BigIntJSON.parse(mark) as BackfillProgressMark;\n    }\n  }\n  return requests;\n}\n\n/**\n * The replica's whole cookie set, in the shape the change log holds it — the\n * seed a change log would be initialized from, and the replica-derived half of\n * the initialization comparison.\n *\n * The metadata half is filtered on `upstreamMetadata IS NOT NULL` because\n * `_zero.tableMetadata` carries `minRowVersion` as well, so a row exists for\n * every table whose rows were ever force-re-downloaded, whether or not upstream\n * ever sent metadata for it. Neither cookie store can represent that row:\n * `cdc.tableMetadata.\"metadata\"` and `_zero.changeLogTableMetadata.\"metadata\"`\n * are both `NOT NULL`.\n *\n * Only meaningful paired with `_zero.replicationState.stateVersion`, read in\n * the same snapshot (invariant 15).\n */\nexport function readReplicaCookies(db: Database): CookieSet {\n  const tableMetadata = db\n    .prepare(/*sql*/ `\n      SELECT \"schema\", \"table\", \"upstreamMetadata\" AS \"metadata\"\n        FROM \"_zero.tableMetadata\"\n        WHERE \"upstreamMetadata\" IS NOT NULL\n        ORDER BY \"schema\", \"table\"\n    `)\n    .all<{schema: string; table: string; metadata: string}>()\n    .map(({schema, table, metadata}) => ({\n      schema,\n      table,\n      metadata: BigIntJSON.parse(metadata) as TableMetadata,\n    }));\n\n  const backfilling = db\n    .prepare(/*sql*/ `\n      SELECT \"schema\", \"table\", \"column\", \"backfill\"\n        FROM \"${BACKFILLING_TABLE}\"\n        ORDER BY \"schema\", \"table\", \"column\"\n    `)\n    .all<{schema: string; table: string; column: string; backfill: string}>()\n    .map(({schema, table, column, backfill}) => ({\n      schema,\n      table,\n      column,\n      backfill: BigIntJSON.parse(backfill) as BackfillID,\n    }));\n\n  return {tableMetadata, backfilling};\n}\n\n/**\n * Seeds {@link BACKFILLING_TABLE} from `_zero.column_metadata`, resolving each\n * lite table name back to its upstream identity. Used by the v17 migration.\n *\n * The resolution is exact for a table that has a `_zero.tableMetadata` row, and\n * exact for a lite name with no dot in it — `liteTableName()` only omits the\n * schema for `public`. What is left over is an in-flight backfill, on a\n * non-`public` schema, on a table with no metadata row, at the instant of\n * upgrade. Those get the best-effort first-dot split and are counted, because a\n * wrong identity produces a `BackfillRequest` the change source will reject\n * rather than a silently wrong one, and because the initialization comparison\n * surfaces it before anything depends on it. The expected count is zero.\n *\n * A full replace rather than an insert-if-absent: `migrateData` re-runs after a\n * rollback and roll-forward, during which a v16 zero-cache advanced the replica\n * without knowing this table existed. Rebuilding it from `column_metadata` —\n * which that zero-cache *did* maintain — is what makes the re-run both\n * idempotent and correct.\n */\nexport function populateBackfillingFromColumnMetadata(\n  lc: LogContext,\n  db: Database,\n): void {\n  db.prepare(/*sql*/ `DELETE FROM \"${BACKFILLING_TABLE}\"`).run();\n\n  const backfilling = db\n    .prepare(/*sql*/ `\n      SELECT table_name, column_name, backfill FROM \"_zero.column_metadata\"\n        WHERE backfill IS NOT NULL\n        ORDER BY table_name, column_name\n    `)\n    .all<{table_name: string; column_name: string; backfill: string}>();\n\n  const unresolvable = getOrCreateCounter(\n    'replica',\n    'backfilling_unresolvable_rows',\n    'In-flight backfills whose upstream table identity could not be recovered ' +\n      'from the replica when \"' +\n      BACKFILLING_TABLE +\n      '\" was created. A best-effort identity is stored; the expected count is 0.',\n  );\n  if (backfilling.length === 0) {\n    unresolvable.add(0); // the common case: publish the series anyway\n    return;\n  }\n\n  const byLiteName = new Map<string, Identifier>(\n    db\n      .prepare(/*sql*/ `SELECT \"schema\", \"table\" FROM \"_zero.tableMetadata\"`)\n      .all<{schema: string; table: string}>()\n      .map(({schema, table}) => [\n        liteTableName({schema, name: table}),\n        {schema, name: table},\n      ]),\n  );\n\n  const insert = db.prepare(/*sql*/ `\n    INSERT INTO \"${BACKFILLING_TABLE}\"\n      (\"schema\", \"table\", \"column\", \"backfill\") VALUES (?, ?, ?, ?)\n  `);\n  let unresolved = 0;\n  for (const {table_name: liteName, column_name, backfill} of backfilling) {\n    const known = byLiteName.get(liteName);\n    const dot = known ? -1 : liteName.indexOf('.');\n    const table = known ?? {\n      schema: dot < 0 ? 'public' : liteName.slice(0, dot),\n      name: dot < 0 ? liteName : liteName.slice(dot + 1),\n    };\n    if (!known && dot >= 0) {\n      unresolved++;\n      lc.warn?.(\n        `no metadata for backfilling table \"${liteName}\"; ` +\n          `assuming {schema: \"${table.schema}\", name: \"${table.name}\"}`,\n      );\n    }\n    insert.run(table.schema, table.name, column_name, backfill);\n  }\n  unresolvable.add(unresolved);\n  lc.info?.(\n    `seeded \"${BACKFILLING_TABLE}\" with ${backfilling.length} in-flight ` +\n      `backfill(s), ${unresolved} of which could not be resolved`,\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"backfilling.js","names":[],"sources":["../../../../../../../zero-cache/src/services/replicator/schema/backfilling.ts"],"sourcesContent":["/**\n * The replica's backfill cookie, keyed by upstream identity.\n *\n * `_zero.column_metadata.backfill` already records which columns are being\n * backfilled, and it stays authoritative for `isBackfilling`, which is what the\n * replica's own read paths use. What it cannot do is name the table an upstream\n * would recognize: it is keyed by *lite* table name, and `liteTableName()`\n * collapses the `public` schema and has no inverse anywhere in the tree. A lite\n * name containing a dot is ambiguous — `{public, \"a.b\"}` and `{a, b}` produce\n * the same string — and a table with backfilling columns and no\n * `_zero.tableMetadata` row (legal, since its metadata is optional) cannot be\n * resolved at all.\n *\n * That is the whole of what blocks a change log from being initialized out of a\n * restored replica, so this table carries the identity the reconstruction needs:\n * a straight row copy into the change log's own cookie tables, with nothing to\n * reconstruct and nothing to guess. The replica's copy is the *seed* source; the\n * change log's copy (`replicator/change-log-cookies.ts`) is the *working* set,\n * folded forward from the seed as the log's head advances.\n *\n * The cost is a second copy of `backfill` inside the replica, taken\n * deliberately — though not to save writes: `_zero.column_metadata` is written\n * only by initial sync, the DDL handlers, and backfill completion, so two more\n * columns on it would be free. It is a matter of shape. That table is keyed by\n * lite table name, so `schema`/`table` would be non-key duplicates of its own\n * key, to be held in sync with it across every rename with no answer to which\n * encoding is authoritative. This one is keyed exactly as `cdc.backfilling` and\n * `_zero.changeLogBackfilling` are, which is what makes the change log's\n * initialization comparison a row-set diff rather than a translation, and what\n * lets all three stores interpret the same fold. It also holds in-flight backfills and nothing else,\n * where the same query against `column_metadata` is an unindexed scan over a row\n * per column of every table.\n *\n * This table is write-only from the replica's perspective. Nothing in the\n * replicator reads it; it exists to be read by the change-streamer.\n */\n\nimport type {LogContext} from '@rocicorp/logger';\nimport {unreachable} from '../../../../../shared/src/asserts.ts';\nimport {BigIntJSON} from '../../../../../shared/src/bigint-json.ts';\nimport type {Database, Statement} from '../../../../../zqlite/src/db.ts';\nimport {getOrCreateCounter} from '../../../observability/metrics.ts';\nimport {liteTableName} from '../../../types/names.ts';\nimport type {\n  BackfillID,\n  BackfillProgressMark,\n  Identifier,\n  SchemaChange,\n  TableMetadata,\n} from '../../change-source/protocol/current/data.ts';\nimport type {BackfillRequest} from '../../change-source/protocol/current/upstream.ts';\nimport {\n  backfillRequestsFrom,\n  cookieOps,\n  type CookieOp,\n  type CookieSet,\n} from '../change-log-cookies.ts';\n\nexport const BACKFILLING_TABLE = '_zero.backfilling';\n\n// `backfill` holds the JSON that `cdc.backfilling` holds as JSONB. SQLite has\n// no JSONB, and nothing here queries into the document: it is stored to be\n// handed back to the change source verbatim.\n//\n// `progress` holds the JSON of the BackfillProgressMark up to which the\n// column's backfill data has been received contiguously (see\n// `acceptBackfill()`), or NULL if no data has been received (i.e. the backfill\n// must start from scratch). It is deliberately a separate column from\n// `backfill` so that the cookie set (and its comparison with the change log's\n// cookie jars) is unaffected by it.\nexport const CREATE_BACKFILLING_TABLE = /*sql*/ `\n  CREATE TABLE \"${BACKFILLING_TABLE}\" (\n    \"schema\"   TEXT NOT NULL,\n    \"table\"    TEXT NOT NULL,\n    \"column\"   TEXT NOT NULL,\n    \"backfill\" TEXT NOT NULL,\n    \"progress\" TEXT,\n    PRIMARY KEY (\"schema\", \"table\", \"column\")\n  );\n`;\n\n/**\n * The replica's interpreter of the cookie fold in\n * `replicator/change-log-cookies.ts`.\n *\n * The fold is shared rather than re-implemented for the same reason the\n * Postgres and SQLite change logs share it: the three stores must agree on every\n * transition forever, and the failure mode when they drift is a backfill that is\n * silently never re-requested, on a column that is then silently never\n * populated. Sharing it makes the replica-versus-Postgres comparison a\n * regression test on the interpreters rather than on three implementations of\n * the same switch.\n *\n * Only the backfill half of the fold is interpreted here. The replica's metadata\n * cookie is `_zero.tableMetadata.upstreamMetadata`, which `TableMetadataTracker`\n * already maintains at the same sites, so an `upsert-metadata` op is inert.\n *\n * Statements are lazily prepared, matching `TableMetadataTracker`: a replica\n * that never sees a schema change never prepares any of them.\n */\nexport class BackfillingTracker {\n  readonly #db: Database;\n\n  #upsert: Statement | undefined;\n  #renameTable: Statement | undefined;\n  #dropTable: Statement | undefined;\n  #renameColumn: Statement | undefined;\n  #dropColumn: Statement | undefined;\n  #getProgress: Statement | undefined;\n  #setProgress: Statement | undefined;\n\n  constructor(db: Database) {\n    this.#db = db;\n  }\n\n  /**\n   * Applies the change's backfill-cookie ops, returning the ops that were\n   * applied. Changes that carry no backfill state — index changes, metadata-only\n   * updates, and the `create-table` / `add-column` variants from a change source\n   * that does not support backfill — apply nothing.\n   */\n  apply(change: SchemaChange): CookieOp[] {\n    const ops = cookieOps(change);\n    for (const op of ops) {\n      this.#run(op);\n    }\n    return ops;\n  }\n\n  #run(op: CookieOp): void {\n    switch (op.op) {\n      case 'upsert-metadata':\n        // Maintained by TableMetadataTracker in \"_zero.tableMetadata\".\n        break;\n\n      case 'upsert-backfill':\n        (this.#upsert ??= this.#db.prepare(/*sql*/ `\n          INSERT INTO \"${BACKFILLING_TABLE}\"\n            (\"schema\", \"table\", \"column\", \"backfill\") VALUES (?, ?, ?, ?)\n            ON CONFLICT (\"schema\", \"table\", \"column\")\n            DO UPDATE SET \"backfill\" = excluded.\"backfill\", \"progress\" = NULL\n        `)).run(\n          op.table.schema,\n          op.table.name,\n          op.column,\n          BigIntJSON.stringify(op.backfill),\n        );\n        break;\n\n      case 'rename-table':\n        (this.#renameTable ??= this.#db.prepare(/*sql*/ `\n          UPDATE \"${BACKFILLING_TABLE}\"\n            SET \"schema\" = ?, \"table\" = ? WHERE \"schema\" = ? AND \"table\" = ?\n        `)).run(op.new.schema, op.new.name, op.old.schema, op.old.name);\n        break;\n\n      case 'drop-table':\n        (this.#dropTable ??= this.#db.prepare(/*sql*/ `\n          DELETE FROM \"${BACKFILLING_TABLE}\"\n            WHERE \"schema\" = ? AND \"table\" = ?\n        `)).run(op.table.schema, op.table.name);\n        break;\n\n      case 'rename-column':\n        (this.#renameColumn ??= this.#db.prepare(/*sql*/ `\n          UPDATE \"${BACKFILLING_TABLE}\" SET \"column\" = ?\n            WHERE \"schema\" = ? AND \"table\" = ? AND \"column\" = ?\n        `)).run(op.new, op.table.schema, op.table.name, op.old);\n        break;\n\n      case 'drop-column':\n        this.#deleteColumn(op.table, op.column);\n        break;\n\n      case 'complete-backfill':\n        // A per-column delete rather than an `IN` list, which cannot be a\n        // single prepared statement across arities. The columns of one\n        // completed backfill are few, and this runs only on schema changes.\n        for (const column of op.columns) {\n          this.#deleteColumn(op.table, column);\n        }\n        break;\n\n      default:\n        unreachable(op);\n    }\n  }\n\n  /**\n   * Returns the tracked progress of the backfilling columns of the `table`,\n   * keyed by column name. Columns that are not backfilling are absent.\n   */\n  getProgress(\n    table: Identifier,\n  ): Map<string, BackfillProgressMark | undefined> {\n    const rows = (this.#getProgress ??= this.#db.prepare(/*sql*/ `\n      SELECT \"column\", \"progress\" FROM \"${BACKFILLING_TABLE}\"\n        WHERE \"schema\" = ? AND \"table\" = ?\n    `)).all<{column: string; progress: string | null}>(\n      table.schema,\n      table.name,\n    );\n    return new Map(\n      rows.map(({column, progress}) => [\n        column,\n        progress === null\n          ? undefined\n          : (BigIntJSON.parse(progress) as BackfillProgressMark),\n      ]),\n    );\n  }\n\n  /** Sets (or clears) the tracked progress of a backfilling column. */\n  setProgress(\n    table: Identifier,\n    column: string,\n    progress: BackfillProgressMark | undefined,\n  ): void {\n    (this.#setProgress ??= this.#db.prepare(/*sql*/ `\n      UPDATE \"${BACKFILLING_TABLE}\" SET \"progress\" = ?\n        WHERE \"schema\" = ? AND \"table\" = ? AND \"column\" = ?\n    `)).run(\n      progress === undefined ? null : BigIntJSON.stringify(progress),\n      table.schema,\n      table.name,\n      column,\n    );\n  }\n\n  /**\n   * Marks the backfill of the `columns` as complete. This is the subset of\n   * a `backfill-completed` message's columns (including row key columns)\n   * whose progress is contiguous with the message.\n   */\n  complete(table: Identifier, columns: readonly string[]): void {\n    this.#run({op: 'complete-backfill', table, columns});\n  }\n\n  #deleteColumn(table: Identifier, column: string): void {\n    (this.#dropColumn ??= this.#db.prepare(/*sql*/ `\n      DELETE FROM \"${BACKFILLING_TABLE}\"\n        WHERE \"schema\" = ? AND \"table\" = ? AND \"column\" = ?\n    `)).run(table.schema, table.name, column);\n  }\n}\n\n/**\n * Returns the {@link BackfillRequest}s from the current replica cookies. The\n * result has the same shape as the Postgres initialization result.\n *\n * The caller must pair this snapshot with the replica state version. When the\n * replica trails the change log, the comparison applies the missing schema\n * changes before it compares the results.\n */\nexport function readBackfillRequests(db: Database): BackfillRequest[] {\n  return backfillRequestsFrom(readReplicaCookies(db));\n}\n\n/**\n * Returns the {@link BackfillRequest}s of the replica's pending backfills,\n * including the tracked progress of each column. These are the backfills that\n * a subscriber reports to the change-streamer when starting a subscription.\n *\n * The caller must pair this snapshot with the replica state version.\n */\nexport function readReplicaBackfills(db: Database): BackfillRequest[] {\n  const requests = readBackfillRequests(db);\n  const progress = db\n    .prepare(/*sql*/ `\n      SELECT \"schema\", \"table\", \"column\", \"progress\"\n        FROM \"${BACKFILLING_TABLE}\" WHERE \"progress\" IS NOT NULL\n    `)\n    .all<{schema: string; table: string; column: string; progress: string}>();\n  for (const {schema, table, column, progress: mark} of progress) {\n    const req = requests.find(\n      r => r.table.schema === schema && r.table.name === table,\n    );\n    const col = req?.columns[column];\n    if (col) {\n      col.progress = BigIntJSON.parse(mark) as BackfillProgressMark;\n    }\n  }\n  return requests;\n}\n\n/**\n * The replica's whole cookie set, in the shape the change log holds it — the\n * seed a change log would be initialized from, and the replica-derived half of\n * the initialization comparison.\n *\n * The metadata half is filtered on `upstreamMetadata IS NOT NULL` because\n * `_zero.tableMetadata` carries `minRowVersion` as well, so a row exists for\n * every table whose rows were ever force-re-downloaded, whether or not upstream\n * ever sent metadata for it. Neither cookie store can represent that row:\n * `cdc.tableMetadata.\"metadata\"` and `_zero.changeLogTableMetadata.\"metadata\"`\n * are both `NOT NULL`.\n *\n * Only meaningful paired with `_zero.replicationState.stateVersion`, read in\n * the same snapshot (invariant 15).\n */\nexport function readReplicaCookies(db: Database): CookieSet {\n  const tableMetadata = db\n    .prepare(/*sql*/ `\n      SELECT \"schema\", \"table\", \"upstreamMetadata\" AS \"metadata\"\n        FROM \"_zero.tableMetadata\"\n        WHERE \"upstreamMetadata\" IS NOT NULL\n        ORDER BY \"schema\", \"table\"\n    `)\n    .all<{schema: string; table: string; metadata: string}>()\n    .map(({schema, table, metadata}) => ({\n      schema,\n      table,\n      metadata: BigIntJSON.parse(metadata) as TableMetadata,\n    }));\n\n  const backfilling = db\n    .prepare(/*sql*/ `\n      SELECT \"schema\", \"table\", \"column\", \"backfill\"\n        FROM \"${BACKFILLING_TABLE}\"\n        ORDER BY \"schema\", \"table\", \"column\"\n    `)\n    .all<{schema: string; table: string; column: string; backfill: string}>()\n    .map(({schema, table, column, backfill}) => ({\n      schema,\n      table,\n      column,\n      backfill: BigIntJSON.parse(backfill) as BackfillID,\n    }));\n\n  return {tableMetadata, backfilling};\n}\n\n/**\n * Seeds {@link BACKFILLING_TABLE} from `_zero.column_metadata`, resolving each\n * lite table name back to its upstream identity. Used by the v17 migration.\n *\n * The resolution is exact for a table that has a `_zero.tableMetadata` row, and\n * exact for a lite name with no dot in it — `liteTableName()` only omits the\n * schema for `public`. What is left over is an in-flight backfill, on a\n * non-`public` schema, on a table with no metadata row, at the instant of\n * upgrade. Those get the best-effort first-dot split and are counted, because a\n * wrong identity produces a `BackfillRequest` the change source will reject\n * rather than a silently wrong one, and because the initialization comparison\n * surfaces it before anything depends on it. The expected count is zero.\n *\n * A full replace rather than an insert-if-absent: `migrateData` re-runs after a\n * rollback and roll-forward, during which a v16 zero-cache advanced the replica\n * without knowing this table existed. Rebuilding it from `column_metadata` —\n * which that zero-cache *did* maintain — is what makes the re-run both\n * idempotent and correct.\n */\nexport function populateBackfillingFromColumnMetadata(\n  lc: LogContext,\n  db: Database,\n): void {\n  db.prepare(/*sql*/ `DELETE FROM \"${BACKFILLING_TABLE}\"`).run();\n\n  const backfilling = db\n    .prepare(/*sql*/ `\n      SELECT table_name, column_name, backfill FROM \"_zero.column_metadata\"\n        WHERE backfill IS NOT NULL\n        ORDER BY table_name, column_name\n    `)\n    .all<{table_name: string; column_name: string; backfill: string}>();\n\n  const unresolvable = getOrCreateCounter(\n    'replica',\n    'backfilling_unresolvable_rows',\n    'In-flight backfills whose upstream table identity could not be recovered ' +\n      'from the replica when \"' +\n      BACKFILLING_TABLE +\n      '\" was created. A best-effort identity is stored; the expected count is 0.',\n  );\n  if (backfilling.length === 0) {\n    unresolvable.add(0); // the common case: publish the series anyway\n    return;\n  }\n\n  const byLiteName = new Map<string, Identifier>(\n    db\n      .prepare(/*sql*/ `SELECT \"schema\", \"table\" FROM \"_zero.tableMetadata\"`)\n      .all<{schema: string; table: string}>()\n      .map(({schema, table}) => [\n        liteTableName({schema, name: table}),\n        {schema, name: table},\n      ]),\n  );\n\n  const insert = db.prepare(/*sql*/ `\n    INSERT INTO \"${BACKFILLING_TABLE}\"\n      (\"schema\", \"table\", \"column\", \"backfill\") VALUES (?, ?, ?, ?)\n  `);\n  let unresolved = 0;\n  for (const {table_name: liteName, column_name, backfill} of backfilling) {\n    const known = byLiteName.get(liteName);\n    const dot = known ? -1 : liteName.indexOf('.');\n    const table = known ?? {\n      schema: dot < 0 ? 'public' : liteName.slice(0, dot),\n      name: dot < 0 ? liteName : liteName.slice(dot + 1),\n    };\n    if (!known && dot >= 0) {\n      unresolved++;\n      lc.warn?.(\n        `no metadata for backfilling table \"${liteName}\"; ` +\n          `assuming {schema: \"${table.schema}\", name: \"${table.name}\"}`,\n      );\n    }\n    insert.run(table.schema, table.name, column_name, backfill);\n  }\n  unresolvable.add(unresolved);\n  lc.info?.(\n    `seeded \"${BACKFILLING_TABLE}\" with ${backfilling.length} in-flight ` +\n      `backfill(s), ${unresolved} of which could not be resolved`,\n  );\n}\n"],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"change-log.js","names":["#logRowOpStmt","#logRowOpWithBackfillStmt","#logTableWideOpStmt","#getRowOpStmt","#logRowOp"],"sources":["../../../../../../../zero-cache/src/services/replicator/schema/change-log.ts"],"sourcesContent":["import {\n  jsonObjectSchema,\n  parse,\n  stringify,\n} from '../../../../../shared/src/bigint-json.ts';\nimport * as v from '../../../../../shared/src/valita.ts';\nimport type {Database, Statement} from '../../../../../zqlite/src/db.ts';\nimport type {LexiVersion} from '../../../types/lexi-version.ts';\nimport type {LiteRowKey} from '../../../types/lite.ts';\nimport {normalizedKeyOrder} from '../../../types/row-key.ts';\n\n/**\n * The Change Log tracks the last operation (set or delete) for each row in the\n * data base, ordered by state version; in other words, a cross-table\n * index of row changes ordered by version. This facilitates a minimal \"diff\"\n * of row changes needed to advance a pipeline from one state version to another.\n *\n * The Change Log stores identifiers only, i.e. it does not store contents.\n * A database snapshot at the previous version can be used to query a row's\n * old contents, if any, and the current snapshot can be used to query a row's\n * new contents. (In the common case, the new contents will have just been applied\n * and thus has a high likelihood of being in the SQLite cache.)\n *\n * There are two table-wide operations:\n * - `t` corresponds to the postgres `TRUNCATE` operation\n * - `r` represents any schema (i.e. column) change\n *\n * For both operations, the corresponding row changes are not explicitly included\n * in the change log. The consumer has the option of simulating them be reading\n * from pre- and post- snapshots, or resetting their state entirely with the current\n * snapshot.\n *\n * To achieve the desired ordering semantics when processing tables that have been\n * truncated, reset, and modified, the \"rowKey\" is set to `null` for resets and\n * the empty string `\"\"` for truncates. This means that resets will be encountered\n * before truncates, which will be processed before any subsequent row changes.\n *\n * This ordering is chosen because resets are currently the more \"destructive\" op\n * and result in aborting the processing (and starting from scratch); doing this\n * earlier reduces wasted work.\n */\n\nexport const SET_OP = 's';\nexport const DEL_OP = 'd';\nexport const TRUNCATE_OP = 't';\nexport const RESET_OP = 'r';\n\n// Exported for testing (and migrations)\nexport const CREATE_CHANGELOG_SCHEMA =\n  // stateVersion : a.k.a. row version\n  // pos          : order in which to process the change (within the version)\n  // table        : The table associated with the change\n  // rowKey       : JSON row key for a row change. For table-wide changes RESET\n  //                and TRUNCATE, there is no associated row; instead, `pos` is\n  //                set to -1 and the rowKey is set to the stateVersion,\n  //                guaranteeing when attempting to process the transaction,\n  //                the pipeline is reset (and the change log traversal\n  //                aborted).\n  // op           : 's' for set (insert/update)\n  //              : 'd' for delete\n  //              : 'r' for table reset (schema change)\n  //              : 't' for table truncation (which also resets the pipeline)\n  // backfillingColumnVersions\n  //              : A JSON mapping from column name to stateVersion tracked\n  //                for replicated writes of columns that are being backfilled.\n  //                This is used to prevent backfill data, which is at a\n  //                fixed snapshot/version outside of the replication stream,\n  //                from overwriting newer column values.\n  //\n  // Naming note: To maintain compatibility between a new replication-manager\n  // and old view-syncers, the previous _zero.changeLog table is preserved\n  // and its replacement given a new name \"changeLog2\".\n  `\n  CREATE TABLE \"_zero.changeLog2\" (\n    \"stateVersion\"              TEXT NOT NULL,\n    \"pos\"                       INT  NOT NULL,\n    \"table\"                     TEXT NOT NULL,\n    \"rowKey\"                    TEXT NOT NULL,\n    \"op\"                        TEXT NOT NULL,\n    \"backfillingColumnVersions\" TEXT DEFAULT '{}',\n    PRIMARY KEY(\"stateVersion\", \"pos\"),\n    UNIQUE(\"table\", \"rowKey\")\n  );\n  `;\n\n/**\n * Contains the changeLog fields relevant for computing the diff between\n * two snapshots of a replica. The `pos` and `backfillingColumnVersions`\n * fields are excluded, though the query should be ordered by\n * `<stateVersion, pos>`.\n */\nexport const changeLogEntrySchema = v\n  .object({\n    stateVersion: v.string(),\n    table: v.string(),\n    rowKey: v.string(),\n    op: v.literalUnion(SET_OP, DEL_OP, TRUNCATE_OP, RESET_OP),\n  })\n  .map(val => ({\n    ...val,\n    // Note: sets the rowKey to `null` for table-wide ops / resets\n    rowKey:\n      val.op === 't' || val.op === 'r'\n        ? null\n        : v.parse(parse(val.rowKey), jsonObjectSchema),\n  }));\n\nexport type ChangeLogEntry = v.Infer<typeof changeLogEntrySchema>;\n\nconst rawChangeLogEntrySchema = v.object({\n  stateVersion: v.string(),\n  table: v.string(),\n  rowKey: v.string(),\n  op: v.literalUnion(SET_OP, DEL_OP, TRUNCATE_OP, RESET_OP),\n  backfillingColumnVersions: v\n    .string()\n    .map(val => v.record(v.string()).parse(JSON.parse(val))),\n});\n\nexport type RawChangeLogEntry = v.Infer<typeof rawChangeLogEntrySchema>;\n\nexport class ChangeLog {\n  readonly #logRowOpStmt: Statement;\n  readonly #logRowOpWithBackfillStmt: Statement;\n  readonly #logTableWideOpStmt;\n  readonly #getRowOpStmt: Statement;\n\n  constructor(db: Database) {\n    this.#logRowOpStmt = db.prepare(/*sql*/ `\n      INSERT OR REPLACE INTO \"_zero.changeLog2\" \n        (stateVersion, pos, \"table\", rowKey, op)\n        VALUES (@version, @pos, @table, JSON(@rowKey), @op)\n    `);\n\n    this.#logRowOpWithBackfillStmt = db.prepare(/*sql*/ `\n      INSERT INTO \"_zero.changeLog2\" \n        (stateVersion, pos, \"table\", rowKey, op, backfillingColumnVersions)\n        VALUES (@version, @pos, @table, JSON(@rowKey), @op, \n                JSON(@backfillingColumnVersions))\n        ON CONFLICT (\"table\", rowKey) DO UPDATE \n                   SET stateVersion = excluded.stateVersion,\n                                pos = excluded.pos,\n                                 op = excluded.op,\n          backfillingColumnVersions = json_patch(\n          backfillingColumnVersions, excluded.backfillingColumnVersions)\n    `);\n\n    // Because table-wide ops result in aborting an incremental update\n    // and rehydrating all queries at \"head\", they are assigned pos = -1\n    // as an optimization to abort as early as possible to skip unnecessary\n    // updates.\n    //\n    // However, changeLog entries that are destined to be \"skipped\" are\n    // nonetheless kept for the purpose of tracking backfillingColumnVersions.\n    this.#logTableWideOpStmt = db.prepare(/*sql*/ `\n      INSERT OR REPLACE INTO \"_zero.changeLog2\" \n        (stateVersion, pos, \"table\", rowKey, op) \n        VALUES (@version, -1, @table, @version, @op)\n    `);\n\n    // oxlint-disable-next-line zero/no-select-star -- Local SQLite replica query; not run through pg prepared statements.\n    this.#getRowOpStmt = db.prepare(/*sql*/ `\n      SELECT * FROM \"_zero.changeLog2\" WHERE \"table\" = ? AND \"rowKey\" = JSON(?)\n    `);\n  }\n\n  /**\n   *\n   * @param backfilled The backfilling columns for which values were set. Note\n   *   that an empty list and the `undefined` value mean different things;\n   *   * An empty list indicates that a backfill is in progress but no\n   *     backfilling values were set. In this case, existing\n   *     backfillingColumnVersions are preserved.\n   *   * `undefined` indicates that there are no columns being backfilled.\n   *     In this case, any vestigial `backfillingColumnVersions` value\n   *     is cleared.\n   */\n  logSetOp(\n    version: LexiVersion,\n    pos: number,\n    table: string,\n    row: LiteRowKey,\n    backfilled: string[] | undefined,\n  ): string {\n    return this.#logRowOp(version, pos, table, row, SET_OP, backfilled);\n  }\n\n  logDeleteOp(\n    version: LexiVersion,\n    pos: number,\n    table: string,\n    row: LiteRowKey,\n  ): string {\n    // Note: For delete ops, it is always safe to clear the\n    //       backfillingColumnVersions because the backfill algorithm\n    //       understands that deletes apply to the whole row.\n    return this.#logRowOp(version, pos, table, row, DEL_OP, undefined);\n  }\n\n  getLatestRowOp(table: string, row: LiteRowKey) {\n    const rowKey = stringify(normalizedKeyOrder(row));\n    const result = this.#getRowOpStmt.get(table, rowKey);\n    return result === undefined\n      ? undefined\n      : v.parse(result, rawChangeLogEntrySchema, 'passthrough');\n  }\n\n  #logRowOp(\n    version: LexiVersion,\n    pos: number,\n    table: string,\n    row: LiteRowKey,\n    op: string,\n    backfilled: string[] | undefined,\n  ): string {\n    const rowKey = stringify(normalizedKeyOrder(row));\n    if (backfilled === undefined) {\n      this.#logRowOpStmt.run({version, pos, table, rowKey, op});\n    } else {\n      const versions: Record<string, string> = {};\n      for (const col of backfilled) {\n        versions[col] = version;\n      }\n      this.#logRowOpWithBackfillStmt.run({\n        version,\n        pos,\n        table,\n        rowKey,\n        op,\n        backfillingColumnVersions: JSON.stringify(versions),\n      });\n    }\n    return rowKey;\n  }\n\n  logTruncateOp(version: LexiVersion, table: string) {\n    this.#logTableWideOpStmt.run({version, table, op: TRUNCATE_OP});\n  }\n\n  logResetOp(version: LexiVersion, table: string) {\n    this.#logTableWideOpStmt.run({version, table, op: RESET_OP});\n  }\n}\n"],"mappings":";;;AAgDA,IAAa,0BAwBX;;;;;;;;;;;;;;;;;;AAmBF,IAAa,uBAAuB,eACjC,OAAO;CACN,cAAc,eAAE,OAAO;CACvB,OAAO,eAAE,OAAO;CAChB,QAAQ,eAAE,OAAO;CACjB,IAAI,aAAA,KAAA,KAAA,KAAA,GAAoD;AAC1D,CAAC,EACA,KAAI,SAAQ;CACX,GAAG;CAEH,QACE,IAAI,OAAO,OAAO,IAAI,OAAO,MACzB,OACA,MAAQ,QAAM,IAAI,MAAM,GAAG,gBAAgB;AACnD,EAAE;AAIJ,IAAM,0BAA0B,eAAE,OAAO;CACvC,cAAc,eAAE,OAAO;CACvB,OAAO,eAAE,OAAO;CAChB,QAAQ,eAAE,OAAO;CACjB,IAAI,aAAA,KAAA,KAAA,KAAA,GAAoD;CACxD,2BAA2B,eACxB,OAAO,EACP,KAAI,QAAO,eAAE,OAAO,eAAE,OAAO,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,CAAC,CAAC;AAC3D,CAAC;AAID,IAAa,YAAb,MAAuB;CACrB;CACA;CACA;CACA;CAEA,YAAY,IAAc;EACxB,KAAKA,gBAAgB,GAAG,QAAgB;;;;KAIvC;EAED,KAAKC,4BAA4B,GAAG,QAAgB;;;;;;;;;;;KAWnD;EASD,KAAKC,sBAAsB,GAAG,QAAgB;;;;KAI7C;EAGD,KAAKC,gBAAgB,GAAG,QAAgB;;KAEvC;CACH;;;;;;;;;;;;CAaA,SACE,SACA,KACA,OACA,KACA,YACQ;EACR,OAAO,KAAKC,UAAU,SAAS,KAAK,OAAO,KAAA,KAAa,UAAU;CACpE;CAEA,YACE,SACA,KACA,OACA,KACQ;EAIR,OAAO,KAAKA,UAAU,SAAS,KAAK,OAAO,KAAA,KAAa,KAAA,CAAS;CACnE;CAEA,eAAe,OAAe,KAAiB;EAC7C,MAAM,SAAS,UAAU,mBAAmB,GAAG,CAAC;EAChD,MAAM,SAAS,KAAKD,cAAc,IAAI,OAAO,MAAM;EACnD,OAAO,WAAW,KAAA,IACd,KAAA,IACA,MAAQ,QAAQ,yBAAyB,aAAa;CAC5D;CAEA,UACE,SACA,KACA,OACA,KACA,IACA,YACQ;EACR,MAAM,SAAS,UAAU,mBAAmB,GAAG,CAAC;EAChD,IAAI,eAAe,KAAA,GACjB,KAAKH,cAAc,IAAI;GAAC;GAAS;GAAK;GAAO;GAAQ;EAAE,CAAC;OACnD;GACL,MAAM,WAAmC,CAAC;GAC1C,KAAK,MAAM,OAAO,YAChB,SAAS,OAAO;GAElB,KAAKC,0BAA0B,IAAI;IACjC;IACA;IACA;IACA;IACA;IACA,2BAA2B,KAAK,UAAU,QAAQ;GACpD,CAAC;EACH;EACA,OAAO;CACT;CAEA,cAAc,SAAsB,OAAe;EACjD,KAAKC,oBAAoB,IAAI;GAAC;GAAS;GAAO,IAAA;EAAe,CAAC;CAChE;CAEA,WAAW,SAAsB,OAAe;EAC9C,KAAKA,oBAAoB,IAAI;GAAC;GAAS;GAAO,IAAA;EAAY,CAAC;CAC7D;AACF"}
+{"version":3,"file":"change-log.js","names":["v","v.literalUnion","v.parse","parse"],"sources":["../../../../../../../zero-cache/src/services/replicator/schema/change-log.ts"],"sourcesContent":["import {\n  jsonObjectSchema,\n  parse,\n  stringify,\n} from '../../../../../shared/src/bigint-json.ts';\nimport * as v from '../../../../../shared/src/valita.ts';\nimport type {Database, Statement} from '../../../../../zqlite/src/db.ts';\nimport type {LexiVersion} from '../../../types/lexi-version.ts';\nimport type {LiteRowKey} from '../../../types/lite.ts';\nimport {normalizedKeyOrder} from '../../../types/row-key.ts';\n\n/**\n * The Change Log tracks the last operation (set or delete) for each row in the\n * data base, ordered by state version; in other words, a cross-table\n * index of row changes ordered by version. This facilitates a minimal \"diff\"\n * of row changes needed to advance a pipeline from one state version to another.\n *\n * The Change Log stores identifiers only, i.e. it does not store contents.\n * A database snapshot at the previous version can be used to query a row's\n * old contents, if any, and the current snapshot can be used to query a row's\n * new contents. (In the common case, the new contents will have just been applied\n * and thus has a high likelihood of being in the SQLite cache.)\n *\n * There are two table-wide operations:\n * - `t` corresponds to the postgres `TRUNCATE` operation\n * - `r` represents any schema (i.e. column) change\n *\n * For both operations, the corresponding row changes are not explicitly included\n * in the change log. The consumer has the option of simulating them be reading\n * from pre- and post- snapshots, or resetting their state entirely with the current\n * snapshot.\n *\n * To achieve the desired ordering semantics when processing tables that have been\n * truncated, reset, and modified, the \"rowKey\" is set to `null` for resets and\n * the empty string `\"\"` for truncates. This means that resets will be encountered\n * before truncates, which will be processed before any subsequent row changes.\n *\n * This ordering is chosen because resets are currently the more \"destructive\" op\n * and result in aborting the processing (and starting from scratch); doing this\n * earlier reduces wasted work.\n */\n\nexport const SET_OP = 's';\nexport const DEL_OP = 'd';\nexport const TRUNCATE_OP = 't';\nexport const RESET_OP = 'r';\n\n// Exported for testing (and migrations)\nexport const CREATE_CHANGELOG_SCHEMA =\n  // stateVersion : a.k.a. row version\n  // pos          : order in which to process the change (within the version)\n  // table        : The table associated with the change\n  // rowKey       : JSON row key for a row change. For table-wide changes RESET\n  //                and TRUNCATE, there is no associated row; instead, `pos` is\n  //                set to -1 and the rowKey is set to the stateVersion,\n  //                guaranteeing when attempting to process the transaction,\n  //                the pipeline is reset (and the change log traversal\n  //                aborted).\n  // op           : 's' for set (insert/update)\n  //              : 'd' for delete\n  //              : 'r' for table reset (schema change)\n  //              : 't' for table truncation (which also resets the pipeline)\n  // backfillingColumnVersions\n  //              : A JSON mapping from column name to stateVersion tracked\n  //                for replicated writes of columns that are being backfilled.\n  //                This is used to prevent backfill data, which is at a\n  //                fixed snapshot/version outside of the replication stream,\n  //                from overwriting newer column values.\n  //\n  // Naming note: To maintain compatibility between a new replication-manager\n  // and old view-syncers, the previous _zero.changeLog table is preserved\n  // and its replacement given a new name \"changeLog2\".\n  `\n  CREATE TABLE \"_zero.changeLog2\" (\n    \"stateVersion\"              TEXT NOT NULL,\n    \"pos\"                       INT  NOT NULL,\n    \"table\"                     TEXT NOT NULL,\n    \"rowKey\"                    TEXT NOT NULL,\n    \"op\"                        TEXT NOT NULL,\n    \"backfillingColumnVersions\" TEXT DEFAULT '{}',\n    PRIMARY KEY(\"stateVersion\", \"pos\"),\n    UNIQUE(\"table\", \"rowKey\")\n  );\n  `;\n\n/**\n * Contains the changeLog fields relevant for computing the diff between\n * two snapshots of a replica. The `pos` and `backfillingColumnVersions`\n * fields are excluded, though the query should be ordered by\n * `<stateVersion, pos>`.\n */\nexport const changeLogEntrySchema = v\n  .object({\n    stateVersion: v.string(),\n    table: v.string(),\n    rowKey: v.string(),\n    op: v.literalUnion(SET_OP, DEL_OP, TRUNCATE_OP, RESET_OP),\n  })\n  .map(val => ({\n    ...val,\n    // Note: sets the rowKey to `null` for table-wide ops / resets\n    rowKey:\n      val.op === 't' || val.op === 'r'\n        ? null\n        : v.parse(parse(val.rowKey), jsonObjectSchema),\n  }));\n\nexport type ChangeLogEntry = v.Infer<typeof changeLogEntrySchema>;\n\nconst rawChangeLogEntrySchema = v.object({\n  stateVersion: v.string(),\n  table: v.string(),\n  rowKey: v.string(),\n  op: v.literalUnion(SET_OP, DEL_OP, TRUNCATE_OP, RESET_OP),\n  backfillingColumnVersions: v\n    .string()\n    .map(val => v.record(v.string()).parse(JSON.parse(val))),\n});\n\nexport type RawChangeLogEntry = v.Infer<typeof rawChangeLogEntrySchema>;\n\nexport class ChangeLog {\n  readonly #logRowOpStmt: Statement;\n  readonly #logRowOpWithBackfillStmt: Statement;\n  readonly #logTableWideOpStmt;\n  readonly #getRowOpStmt: Statement;\n\n  constructor(db: Database) {\n    this.#logRowOpStmt = db.prepare(/*sql*/ `\n      INSERT OR REPLACE INTO \"_zero.changeLog2\" \n        (stateVersion, pos, \"table\", rowKey, op)\n        VALUES (@version, @pos, @table, JSON(@rowKey), @op)\n    `);\n\n    this.#logRowOpWithBackfillStmt = db.prepare(/*sql*/ `\n      INSERT INTO \"_zero.changeLog2\" \n        (stateVersion, pos, \"table\", rowKey, op, backfillingColumnVersions)\n        VALUES (@version, @pos, @table, JSON(@rowKey), @op, \n                JSON(@backfillingColumnVersions))\n        ON CONFLICT (\"table\", rowKey) DO UPDATE \n                   SET stateVersion = excluded.stateVersion,\n                                pos = excluded.pos,\n                                 op = excluded.op,\n          backfillingColumnVersions = json_patch(\n          backfillingColumnVersions, excluded.backfillingColumnVersions)\n    `);\n\n    // Because table-wide ops result in aborting an incremental update\n    // and rehydrating all queries at \"head\", they are assigned pos = -1\n    // as an optimization to abort as early as possible to skip unnecessary\n    // updates.\n    //\n    // However, changeLog entries that are destined to be \"skipped\" are\n    // nonetheless kept for the purpose of tracking backfillingColumnVersions.\n    this.#logTableWideOpStmt = db.prepare(/*sql*/ `\n      INSERT OR REPLACE INTO \"_zero.changeLog2\" \n        (stateVersion, pos, \"table\", rowKey, op) \n        VALUES (@version, -1, @table, @version, @op)\n    `);\n\n    // oxlint-disable-next-line zero/no-select-star -- Local SQLite replica query; not run through pg prepared statements.\n    this.#getRowOpStmt = db.prepare(/*sql*/ `\n      SELECT * FROM \"_zero.changeLog2\" WHERE \"table\" = ? AND \"rowKey\" = JSON(?)\n    `);\n  }\n\n  /**\n   *\n   * @param backfilled The backfilling columns for which values were set. Note\n   *   that an empty list and the `undefined` value mean different things;\n   *   * An empty list indicates that a backfill is in progress but no\n   *     backfilling values were set. In this case, existing\n   *     backfillingColumnVersions are preserved.\n   *   * `undefined` indicates that there are no columns being backfilled.\n   *     In this case, any vestigial `backfillingColumnVersions` value\n   *     is cleared.\n   */\n  logSetOp(\n    version: LexiVersion,\n    pos: number,\n    table: string,\n    row: LiteRowKey,\n    backfilled: string[] | undefined,\n  ): string {\n    return this.#logRowOp(version, pos, table, row, SET_OP, backfilled);\n  }\n\n  logDeleteOp(\n    version: LexiVersion,\n    pos: number,\n    table: string,\n    row: LiteRowKey,\n  ): string {\n    // Note: For delete ops, it is always safe to clear the\n    //       backfillingColumnVersions because the backfill algorithm\n    //       understands that deletes apply to the whole row.\n    return this.#logRowOp(version, pos, table, row, DEL_OP, undefined);\n  }\n\n  getLatestRowOp(table: string, row: LiteRowKey) {\n    const rowKey = stringify(normalizedKeyOrder(row));\n    const result = this.#getRowOpStmt.get(table, rowKey);\n    return result === undefined\n      ? undefined\n      : v.parse(result, rawChangeLogEntrySchema, 'passthrough');\n  }\n\n  #logRowOp(\n    version: LexiVersion,\n    pos: number,\n    table: string,\n    row: LiteRowKey,\n    op: string,\n    backfilled: string[] | undefined,\n  ): string {\n    const rowKey = stringify(normalizedKeyOrder(row));\n    if (backfilled === undefined) {\n      this.#logRowOpStmt.run({version, pos, table, rowKey, op});\n    } else {\n      const versions: Record<string, string> = {};\n      for (const col of backfilled) {\n        versions[col] = version;\n      }\n      this.#logRowOpWithBackfillStmt.run({\n        version,\n        pos,\n        table,\n        rowKey,\n        op,\n        backfillingColumnVersions: JSON.stringify(versions),\n      });\n    }\n    return rowKey;\n  }\n\n  logTruncateOp(version: LexiVersion, table: string) {\n    this.#logTableWideOpStmt.run({version, table, op: TRUNCATE_OP});\n  }\n\n  logResetOp(version: LexiVersion, table: string) {\n    this.#logTableWideOpStmt.run({version, table, op: RESET_OP});\n  }\n}\n"],"mappings":";;;AAgDA,IAAa,0BAwBX;;;;;;;;;;;;;;;;;;AAmBF,IAAa,uBAAuBA,eACjC,OAAO;CACN,cAAcA,eAAE,OAAO;CACvB,OAAOA,eAAE,OAAO;CAChB,QAAQA,eAAE,OAAO;CACjB,IAAIC,aAAAA,KAAAA,KAAAA,KAAAA,GAAoD;AAC1D,CAAC,CAAC,CACD,KAAI,SAAQ;CACX,GAAG;CAEH,QACE,IAAI,OAAO,OAAO,IAAI,OAAO,MACzB,OACAC,MAAQC,QAAM,IAAI,MAAM,GAAG,gBAAgB;AACnD,EAAE;AAIJ,IAAM,0BAA0BH,eAAE,OAAO;CACvC,cAAcA,eAAE,OAAO;CACvB,OAAOA,eAAE,OAAO;CAChB,QAAQA,eAAE,OAAO;CACjB,IAAIC,aAAAA,KAAAA,KAAAA,KAAAA,GAAoD;CACxD,2BAA2BD,eACxB,OAAO,CAAC,CACR,KAAI,QAAOA,eAAE,OAAOA,eAAE,OAAO,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,GAAG,CAAC,CAAC;AAC3D,CAAC;AAID,IAAa,YAAb,MAAuB;CACrB;CACA;CACA;CACA;CAEA,YAAY,IAAc;EACxB,KAAK,gBAAgB,GAAG,QAAgB;;;;KAIvC;EAED,KAAK,4BAA4B,GAAG,QAAgB;;;;;;;;;;;KAWnD;EASD,KAAK,sBAAsB,GAAG,QAAgB;;;;KAI7C;EAGD,KAAK,gBAAgB,GAAG,QAAgB;;KAEvC;CACH;;;;;;;;;;;;CAaA,SACE,SACA,KACA,OACA,KACA,YACQ;EACR,OAAO,KAAK,UAAU,SAAS,KAAK,OAAO,KAAA,KAAa,UAAU;CACpE;CAEA,YACE,SACA,KACA,OACA,KACQ;EAIR,OAAO,KAAK,UAAU,SAAS,KAAK,OAAO,KAAA,KAAa,KAAA,CAAS;CACnE;CAEA,eAAe,OAAe,KAAiB;EAC7C,MAAM,SAAS,UAAU,mBAAmB,GAAG,CAAC;EAChD,MAAM,SAAS,KAAK,cAAc,IAAI,OAAO,MAAM;EACnD,OAAO,WAAW,KAAA,IACd,KAAA,IACAE,MAAQ,QAAQ,yBAAyB,aAAa;CAC5D;CAEA,UACE,SACA,KACA,OACA,KACA,IACA,YACQ;EACR,MAAM,SAAS,UAAU,mBAAmB,GAAG,CAAC;EAChD,IAAI,eAAe,KAAA,GACjB,KAAK,cAAc,IAAI;GAAC;GAAS;GAAK;GAAO;GAAQ;EAAE,CAAC;OACnD;GACL,MAAM,WAAmC,CAAC;GAC1C,KAAK,MAAM,OAAO,YAChB,SAAS,OAAO;GAElB,KAAK,0BAA0B,IAAI;IACjC;IACA;IACA;IACA;IACA;IACA,2BAA2B,KAAK,UAAU,QAAQ;GACpD,CAAC;EACH;EACA,OAAO;CACT;CAEA,cAAc,SAAsB,OAAe;EACjD,KAAK,oBAAoB,IAAI;GAAC;GAAS;GAAO,IAAA;EAAe,CAAC;CAChE;CAEA,WAAW,SAAsB,OAAe;EAC9C,KAAK,oBAAoB,IAAI;GAAC;GAAS;GAAO,IAAA;EAAY,CAAC;CAC7D;AACF"}

package/out/zero-cache/src/services/replicator/schema/column-metadata.js

@@ -202,6 +202,6 @@ function pgColumnSpecToMetadata(spec) {
 	};
 }
 //#endregion
-export { CREATE_COLUMN_METADATA_TABLE, ColumnMetadataStore, metadataToLiteTypeString, populateFromExistingTables };
+export { CREATE_COLUMN_METADATA_TABLE, ColumnMetadataStore, liteTypeStringToMetadata, metadataToLiteTypeString, pgColumnSpecToMetadata, populateFromExistingTables };
 
 //# sourceMappingURL=column-metadata.js.map

package/out/zero-cache/src/services/replicator/schema/column-metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"column-metadata.js","names":["#instances","#insertStmt","#updateStmt","#clearBackfillStmt","#deleteColumnStmt","#deleteTableStmt","#renameTableStmt","#getColumnStmt","#getTableStmt","#hasTableStmt","#insertMetadata"],"sources":["../../../../../../../zero-cache/src/services/replicator/schema/column-metadata.ts"],"sourcesContent":["/**\n * Column metadata table for storing upstream PostgreSQL schema information.\n *\n * Previously, upstream type metadata was embedded in SQLite column type strings\n * using pipe-delimited notation (e.g., \"int8|NOT_NULL|TEXT_ENUM\"). This caused\n * issues with SQLite type affinity and made schema inspection difficult.\n *\n * This table stores that metadata separately, allowing SQLite columns to use\n * plain type names while preserving all necessary upstream type information.\n */\n\nimport type {Database, Statement} from '../../../../../zqlite/src/db.ts';\nimport {isArrayColumn, isEnumColumn} from '../../../db/pg-to-lite.ts';\nimport type {ColumnSpec, LiteTableSpec} from '../../../db/specs.ts';\nimport {\n  isArray as checkIsArray,\n  isEnum as checkIsEnum,\n  liteTypeString,\n  nullableUpstream,\n  upstreamDataType,\n} from '../../../types/lite.ts';\nimport type {BackfillID} from '../../change-source/protocol/current.ts';\n\n/**\n * Structured column metadata, replacing the old pipe-delimited string format.\n */\nexport interface ColumnMetadata {\n  /** PostgreSQL type name, e.g., 'int8', 'varchar', 'text[]', 'user_role' */\n  upstreamType: string;\n  isNotNull: boolean;\n  isEnum: boolean;\n  isArray: boolean;\n  /** Maximum character length for varchar/char types */\n  characterMaxLength?: number | null;\n  isBackfilling: boolean;\n}\n\ntype ColumnMetadataRow = {\n  upstream_type: string;\n  is_not_null: number;\n  is_enum: number;\n  is_array: number;\n  character_max_length: number | null;\n  backfill: string | null;\n};\n\nexport const CREATE_COLUMN_METADATA_TABLE = `\n  CREATE TABLE \"_zero.column_metadata\" (\n    table_name TEXT NOT NULL,\n    column_name TEXT NOT NULL,\n    upstream_type TEXT NOT NULL,\n    is_not_null INTEGER NOT NULL,\n    is_enum INTEGER NOT NULL,\n    is_array INTEGER NOT NULL,\n    character_max_length INTEGER,\n    backfill TEXT,\n    PRIMARY KEY (table_name, column_name)\n  );\n`;\n\n/**\n * Efficient column metadata store that prepares all statements upfront.\n * Use this class to avoid re-preparing statements on every operation.\n *\n * Access via `ColumnMetadataStore.getInstance(db)`, which returns `undefined`\n * if the metadata table doesn't exist yet.\n */\nexport class ColumnMetadataStore {\n  static #instances = new WeakMap<Database, ColumnMetadataStore>();\n\n  readonly #insertStmt: Statement;\n  readonly #updateStmt: Statement;\n  readonly #clearBackfillStmt: Statement;\n  readonly #deleteColumnStmt: Statement;\n  readonly #deleteTableStmt: Statement;\n  readonly #renameTableStmt: Statement;\n  readonly #getColumnStmt: Statement;\n  readonly #getTableStmt: Statement;\n  readonly #hasTableStmt: Statement;\n\n  private constructor(db: Database) {\n    this.#insertStmt = db.prepare(`\n      INSERT INTO \"_zero.column_metadata\"\n        (table_name, column_name, upstream_type, is_not_null, is_enum, is_array, character_max_length, backfill)\n      VALUES (?, ?, ?, ?, ?, ?, ?, ?)\n    `);\n\n    this.#updateStmt = db.prepare(`\n      UPDATE \"_zero.column_metadata\"\n      SET column_name = ?,\n          upstream_type = ?,\n          is_not_null = ?,\n          is_enum = ?,\n          is_array = ?,\n          character_max_length = ?\n      WHERE table_name = ? AND column_name = ?\n    `);\n\n    this.#clearBackfillStmt = db.prepare(/*sql*/ `\n      UPDATE \"_zero.column_metadata\"\n      SET backfill = NULL\n      WHERE table_name = ? AND column_name = ?\n    `);\n\n    this.#deleteColumnStmt = db.prepare(`\n      DELETE FROM \"_zero.column_metadata\"\n      WHERE table_name = ? AND column_name = ?\n    `);\n\n    this.#deleteTableStmt = db.prepare(`\n      DELETE FROM \"_zero.column_metadata\"\n      WHERE table_name = ?\n    `);\n\n    this.#renameTableStmt = db.prepare(`\n      UPDATE \"_zero.column_metadata\"\n      SET table_name = ?\n      WHERE table_name = ?\n    `);\n\n    this.#getColumnStmt = db.prepare(`\n      SELECT upstream_type, is_not_null, is_enum, is_array, character_max_length, backfill\n      FROM \"_zero.column_metadata\"\n      WHERE table_name = ? AND column_name = ?\n    `);\n\n    this.#getTableStmt = db.prepare(`\n      SELECT column_name, upstream_type, is_not_null, is_enum, is_array, character_max_length, backfill\n      FROM \"_zero.column_metadata\"\n      WHERE table_name = ?\n      ORDER BY column_name\n    `);\n\n    this.#hasTableStmt = db.prepare(`\n      SELECT 1 FROM sqlite_master\n      WHERE type = 'table' AND name = '_zero.column_metadata'\n    `);\n  }\n\n  /**\n   * Gets the singleton instance of ColumnMetadataStore for the given database.\n   * Returns `undefined` if the metadata table doesn't exist yet.\n   */\n  static getInstance(db: Database): ColumnMetadataStore | undefined {\n    let instance = ColumnMetadataStore.#instances.get(db);\n    if (!instance) {\n      // Check if table exists\n      const tableExists = db\n        .prepare(\n          `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = '_zero.column_metadata'`,\n        )\n        .get();\n\n      if (!tableExists) {\n        return undefined;\n      }\n\n      instance = new ColumnMetadataStore(db);\n      ColumnMetadataStore.#instances.set(db, instance);\n    }\n    return instance;\n  }\n\n  insert(\n    tableName: string,\n    columnName: string,\n    spec: ColumnSpec,\n    backfill?: BackfillID,\n  ): void {\n    const metadata = pgColumnSpecToMetadata(spec);\n    this.#insertMetadata(tableName, columnName, metadata, backfill);\n  }\n\n  #insertMetadata(\n    tableName: string,\n    columnName: string,\n    metadata: Omit<ColumnMetadata, 'isBackfilling'>,\n    backfill?: BackfillID,\n  ): void {\n    this.#insertStmt.run(\n      tableName,\n      columnName,\n      metadata.upstreamType,\n      metadata.isNotNull ? 1 : 0,\n      metadata.isEnum ? 1 : 0,\n      metadata.isArray ? 1 : 0,\n      metadata.characterMaxLength ?? null,\n      backfill ? JSON.stringify(backfill) : null,\n    );\n  }\n\n  update(\n    tableName: string,\n    oldColumnName: string,\n    newColumnName: string,\n    spec: ColumnSpec,\n  ): void {\n    const metadata = pgColumnSpecToMetadata(spec);\n    this.#updateStmt.run(\n      newColumnName,\n      metadata.upstreamType,\n      metadata.isNotNull ? 1 : 0,\n      metadata.isEnum ? 1 : 0,\n      metadata.isArray ? 1 : 0,\n      metadata.characterMaxLength ?? null,\n      tableName,\n      oldColumnName,\n    );\n  }\n\n  clearBackfilling(tableName: string, columnName: string): void {\n    this.#clearBackfillStmt.run(tableName, columnName);\n  }\n\n  deleteColumn(tableName: string, columnName: string): void {\n    this.#deleteColumnStmt.run(tableName, columnName);\n  }\n\n  deleteTable(tableName: string): void {\n    this.#deleteTableStmt.run(tableName);\n  }\n\n  renameTable(oldTableName: string, newTableName: string): void {\n    this.#renameTableStmt.run(newTableName, oldTableName);\n  }\n\n  getColumn(tableName: string, columnName: string): ColumnMetadata | undefined {\n    const row = this.#getColumnStmt.get(tableName, columnName) as\n      | ColumnMetadataRow\n      | undefined;\n\n    if (!row) {\n      return undefined;\n    }\n\n    return {\n      upstreamType: row.upstream_type,\n      isNotNull: row.is_not_null !== 0,\n      isEnum: row.is_enum !== 0,\n      isArray: row.is_array !== 0,\n      characterMaxLength: row.character_max_length,\n      isBackfilling: row.backfill !== null,\n    };\n  }\n\n  getTable(tableName: string): Map<string, ColumnMetadata> {\n    const rows = this.#getTableStmt.all(tableName) as Array<\n      ColumnMetadataRow & {column_name: string}\n    >;\n\n    const metadata = new Map<string, ColumnMetadata>();\n    for (const row of rows) {\n      metadata.set(row.column_name, {\n        upstreamType: row.upstream_type,\n        isNotNull: row.is_not_null !== 0,\n        isEnum: row.is_enum !== 0,\n        isArray: row.is_array !== 0,\n        characterMaxLength: row.character_max_length,\n        isBackfilling: row.backfill !== null,\n      });\n    }\n\n    return metadata;\n  }\n\n  hasTable(): boolean {\n    const result = this.#hasTableStmt.get();\n    return result !== undefined;\n  }\n}\n\n/**\n * Populates metadata table from existing tables that use pipe notation.\n * This is used during migration v8 to backfill the metadata table.\n */\nexport function populateFromExistingTables(\n  db: Database,\n  tables: LiteTableSpec[],\n): void {\n  // The backfill column is not relevant here, and does not exist on\n  // older versions of the replica.\n  const legacyInsertStmt = db.prepare(`\n      INSERT INTO \"_zero.column_metadata\"\n        (table_name, column_name, upstream_type, is_not_null, is_enum, is_array, character_max_length)\n      VALUES (?, ?, ?, ?, ?, ?, ?)\n    `);\n\n  for (const table of tables) {\n    for (const [columnName, columnSpec] of Object.entries(table.columns)) {\n      const metadata = liteTypeStringToMetadata(\n        columnSpec.dataType,\n        columnSpec.characterMaximumLength,\n      );\n      legacyInsertStmt.run(\n        table.name,\n        columnName,\n        metadata.upstreamType,\n        metadata.isNotNull ? 1 : 0,\n        metadata.isEnum ? 1 : 0,\n        metadata.isArray ? 1 : 0,\n        metadata.characterMaxLength ?? null,\n      );\n    }\n  }\n}\n\n/**\n * Converts pipe-delimited LiteTypeString to structured ColumnMetadata.\n * This is a compatibility helper for the migration period.\n */\nexport function liteTypeStringToMetadata(\n  liteTypeString: string,\n  characterMaxLength?: number | null,\n): ColumnMetadata {\n  const baseType = upstreamDataType(liteTypeString);\n  const isArrayType = checkIsArray(liteTypeString);\n\n  // Reconstruct the full upstream type including array notation\n  // For new-style arrays like 'text[]', upstreamDataType returns 'text[]'\n  // For old-style arrays like 'int4|NOT_NULL[]', upstreamDataType returns 'int4', so we append '[]'\n  const fullUpstreamType =\n    isArrayType && !baseType.includes('[]') ? `${baseType}[]` : baseType;\n\n  return {\n    upstreamType: fullUpstreamType,\n    isNotNull: !nullableUpstream(liteTypeString),\n    isEnum: checkIsEnum(liteTypeString),\n    isArray: isArrayType,\n    characterMaxLength: characterMaxLength ?? null,\n    isBackfilling: false,\n  };\n}\n\n/**\n * Converts structured ColumnMetadata back to pipe-delimited LiteTypeString.\n * This is a compatibility helper for the migration period.\n */\nexport function metadataToLiteTypeString(metadata: ColumnMetadata): string {\n  return liteTypeString(\n    metadata.upstreamType,\n    metadata.isNotNull,\n    metadata.isEnum,\n    metadata.isArray,\n  );\n}\n\n/**\n * Converts PostgreSQL ColumnSpec to structured ColumnMetadata.\n * Used during replication to populate the metadata table from upstream schema.\n *\n * Uses the same logic as liteTypeString() and mapPostgresToLiteColumn() via shared helpers.\n */\nexport function pgColumnSpecToMetadata(spec: ColumnSpec): ColumnMetadata {\n  return {\n    upstreamType: spec.dataType,\n    isNotNull: spec.notNull ?? false,\n    isEnum: isEnumColumn(spec),\n    isArray: isArrayColumn(spec),\n    characterMaxLength: spec.characterMaximumLength ?? null,\n    isBackfilling: false,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"column-metadata.js","names":["checkIsArray","checkIsEnum"],"sources":["../../../../../../../zero-cache/src/services/replicator/schema/column-metadata.ts"],"sourcesContent":["/**\n * Column metadata table for storing upstream PostgreSQL schema information.\n *\n * Previously, upstream type metadata was embedded in SQLite column type strings\n * using pipe-delimited notation (e.g., \"int8|NOT_NULL|TEXT_ENUM\"). This caused\n * issues with SQLite type affinity and made schema inspection difficult.\n *\n * This table stores that metadata separately, allowing SQLite columns to use\n * plain type names while preserving all necessary upstream type information.\n */\n\nimport type {Database, Statement} from '../../../../../zqlite/src/db.ts';\nimport {isArrayColumn, isEnumColumn} from '../../../db/pg-to-lite.ts';\nimport type {ColumnSpec, LiteTableSpec} from '../../../db/specs.ts';\nimport {\n  isArray as checkIsArray,\n  isEnum as checkIsEnum,\n  liteTypeString,\n  nullableUpstream,\n  upstreamDataType,\n} from '../../../types/lite.ts';\nimport type {BackfillID} from '../../change-source/protocol/current.ts';\n\n/**\n * Structured column metadata, replacing the old pipe-delimited string format.\n */\nexport interface ColumnMetadata {\n  /** PostgreSQL type name, e.g., 'int8', 'varchar', 'text[]', 'user_role' */\n  upstreamType: string;\n  isNotNull: boolean;\n  isEnum: boolean;\n  isArray: boolean;\n  /** Maximum character length for varchar/char types */\n  characterMaxLength?: number | null;\n  isBackfilling: boolean;\n}\n\ntype ColumnMetadataRow = {\n  upstream_type: string;\n  is_not_null: number;\n  is_enum: number;\n  is_array: number;\n  character_max_length: number | null;\n  backfill: string | null;\n};\n\nexport const CREATE_COLUMN_METADATA_TABLE = `\n  CREATE TABLE \"_zero.column_metadata\" (\n    table_name TEXT NOT NULL,\n    column_name TEXT NOT NULL,\n    upstream_type TEXT NOT NULL,\n    is_not_null INTEGER NOT NULL,\n    is_enum INTEGER NOT NULL,\n    is_array INTEGER NOT NULL,\n    character_max_length INTEGER,\n    backfill TEXT,\n    PRIMARY KEY (table_name, column_name)\n  );\n`;\n\n/**\n * Efficient column metadata store that prepares all statements upfront.\n * Use this class to avoid re-preparing statements on every operation.\n *\n * Access via `ColumnMetadataStore.getInstance(db)`, which returns `undefined`\n * if the metadata table doesn't exist yet.\n */\nexport class ColumnMetadataStore {\n  static #instances = new WeakMap<Database, ColumnMetadataStore>();\n\n  readonly #insertStmt: Statement;\n  readonly #updateStmt: Statement;\n  readonly #clearBackfillStmt: Statement;\n  readonly #deleteColumnStmt: Statement;\n  readonly #deleteTableStmt: Statement;\n  readonly #renameTableStmt: Statement;\n  readonly #getColumnStmt: Statement;\n  readonly #getTableStmt: Statement;\n  readonly #hasTableStmt: Statement;\n\n  private constructor(db: Database) {\n    this.#insertStmt = db.prepare(`\n      INSERT INTO \"_zero.column_metadata\"\n        (table_name, column_name, upstream_type, is_not_null, is_enum, is_array, character_max_length, backfill)\n      VALUES (?, ?, ?, ?, ?, ?, ?, ?)\n    `);\n\n    this.#updateStmt = db.prepare(`\n      UPDATE \"_zero.column_metadata\"\n      SET column_name = ?,\n          upstream_type = ?,\n          is_not_null = ?,\n          is_enum = ?,\n          is_array = ?,\n          character_max_length = ?\n      WHERE table_name = ? AND column_name = ?\n    `);\n\n    this.#clearBackfillStmt = db.prepare(/*sql*/ `\n      UPDATE \"_zero.column_metadata\"\n      SET backfill = NULL\n      WHERE table_name = ? AND column_name = ?\n    `);\n\n    this.#deleteColumnStmt = db.prepare(`\n      DELETE FROM \"_zero.column_metadata\"\n      WHERE table_name = ? AND column_name = ?\n    `);\n\n    this.#deleteTableStmt = db.prepare(`\n      DELETE FROM \"_zero.column_metadata\"\n      WHERE table_name = ?\n    `);\n\n    this.#renameTableStmt = db.prepare(`\n      UPDATE \"_zero.column_metadata\"\n      SET table_name = ?\n      WHERE table_name = ?\n    `);\n\n    this.#getColumnStmt = db.prepare(`\n      SELECT upstream_type, is_not_null, is_enum, is_array, character_max_length, backfill\n      FROM \"_zero.column_metadata\"\n      WHERE table_name = ? AND column_name = ?\n    `);\n\n    this.#getTableStmt = db.prepare(`\n      SELECT column_name, upstream_type, is_not_null, is_enum, is_array, character_max_length, backfill\n      FROM \"_zero.column_metadata\"\n      WHERE table_name = ?\n      ORDER BY column_name\n    `);\n\n    this.#hasTableStmt = db.prepare(`\n      SELECT 1 FROM sqlite_master\n      WHERE type = 'table' AND name = '_zero.column_metadata'\n    `);\n  }\n\n  /**\n   * Gets the singleton instance of ColumnMetadataStore for the given database.\n   * Returns `undefined` if the metadata table doesn't exist yet.\n   */\n  static getInstance(db: Database): ColumnMetadataStore | undefined {\n    let instance = ColumnMetadataStore.#instances.get(db);\n    if (!instance) {\n      // Check if table exists\n      const tableExists = db\n        .prepare(\n          `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = '_zero.column_metadata'`,\n        )\n        .get();\n\n      if (!tableExists) {\n        return undefined;\n      }\n\n      instance = new ColumnMetadataStore(db);\n      ColumnMetadataStore.#instances.set(db, instance);\n    }\n    return instance;\n  }\n\n  insert(\n    tableName: string,\n    columnName: string,\n    spec: ColumnSpec,\n    backfill?: BackfillID,\n  ): void {\n    const metadata = pgColumnSpecToMetadata(spec);\n    this.#insertMetadata(tableName, columnName, metadata, backfill);\n  }\n\n  #insertMetadata(\n    tableName: string,\n    columnName: string,\n    metadata: Omit<ColumnMetadata, 'isBackfilling'>,\n    backfill?: BackfillID,\n  ): void {\n    this.#insertStmt.run(\n      tableName,\n      columnName,\n      metadata.upstreamType,\n      metadata.isNotNull ? 1 : 0,\n      metadata.isEnum ? 1 : 0,\n      metadata.isArray ? 1 : 0,\n      metadata.characterMaxLength ?? null,\n      backfill ? JSON.stringify(backfill) : null,\n    );\n  }\n\n  update(\n    tableName: string,\n    oldColumnName: string,\n    newColumnName: string,\n    spec: ColumnSpec,\n  ): void {\n    const metadata = pgColumnSpecToMetadata(spec);\n    this.#updateStmt.run(\n      newColumnName,\n      metadata.upstreamType,\n      metadata.isNotNull ? 1 : 0,\n      metadata.isEnum ? 1 : 0,\n      metadata.isArray ? 1 : 0,\n      metadata.characterMaxLength ?? null,\n      tableName,\n      oldColumnName,\n    );\n  }\n\n  clearBackfilling(tableName: string, columnName: string): void {\n    this.#clearBackfillStmt.run(tableName, columnName);\n  }\n\n  deleteColumn(tableName: string, columnName: string): void {\n    this.#deleteColumnStmt.run(tableName, columnName);\n  }\n\n  deleteTable(tableName: string): void {\n    this.#deleteTableStmt.run(tableName);\n  }\n\n  renameTable(oldTableName: string, newTableName: string): void {\n    this.#renameTableStmt.run(newTableName, oldTableName);\n  }\n\n  getColumn(tableName: string, columnName: string): ColumnMetadata | undefined {\n    const row = this.#getColumnStmt.get(tableName, columnName) as\n      | ColumnMetadataRow\n      | undefined;\n\n    if (!row) {\n      return undefined;\n    }\n\n    return {\n      upstreamType: row.upstream_type,\n      isNotNull: row.is_not_null !== 0,\n      isEnum: row.is_enum !== 0,\n      isArray: row.is_array !== 0,\n      characterMaxLength: row.character_max_length,\n      isBackfilling: row.backfill !== null,\n    };\n  }\n\n  getTable(tableName: string): Map<string, ColumnMetadata> {\n    const rows = this.#getTableStmt.all(tableName) as Array<\n      ColumnMetadataRow & {column_name: string}\n    >;\n\n    const metadata = new Map<string, ColumnMetadata>();\n    for (const row of rows) {\n      metadata.set(row.column_name, {\n        upstreamType: row.upstream_type,\n        isNotNull: row.is_not_null !== 0,\n        isEnum: row.is_enum !== 0,\n        isArray: row.is_array !== 0,\n        characterMaxLength: row.character_max_length,\n        isBackfilling: row.backfill !== null,\n      });\n    }\n\n    return metadata;\n  }\n\n  hasTable(): boolean {\n    const result = this.#hasTableStmt.get();\n    return result !== undefined;\n  }\n}\n\n/**\n * Populates metadata table from existing tables that use pipe notation.\n * This is used during migration v8 to backfill the metadata table.\n */\nexport function populateFromExistingTables(\n  db: Database,\n  tables: LiteTableSpec[],\n): void {\n  // The backfill column is not relevant here, and does not exist on\n  // older versions of the replica.\n  const legacyInsertStmt = db.prepare(`\n      INSERT INTO \"_zero.column_metadata\"\n        (table_name, column_name, upstream_type, is_not_null, is_enum, is_array, character_max_length)\n      VALUES (?, ?, ?, ?, ?, ?, ?)\n    `);\n\n  for (const table of tables) {\n    for (const [columnName, columnSpec] of Object.entries(table.columns)) {\n      const metadata = liteTypeStringToMetadata(\n        columnSpec.dataType,\n        columnSpec.characterMaximumLength,\n      );\n      legacyInsertStmt.run(\n        table.name,\n        columnName,\n        metadata.upstreamType,\n        metadata.isNotNull ? 1 : 0,\n        metadata.isEnum ? 1 : 0,\n        metadata.isArray ? 1 : 0,\n        metadata.characterMaxLength ?? null,\n      );\n    }\n  }\n}\n\n/**\n * Converts pipe-delimited LiteTypeString to structured ColumnMetadata.\n * This is a compatibility helper for the migration period.\n */\nexport function liteTypeStringToMetadata(\n  liteTypeString: string,\n  characterMaxLength?: number | null,\n): ColumnMetadata {\n  const baseType = upstreamDataType(liteTypeString);\n  const isArrayType = checkIsArray(liteTypeString);\n\n  // Reconstruct the full upstream type including array notation\n  // For new-style arrays like 'text[]', upstreamDataType returns 'text[]'\n  // For old-style arrays like 'int4|NOT_NULL[]', upstreamDataType returns 'int4', so we append '[]'\n  const fullUpstreamType =\n    isArrayType && !baseType.includes('[]') ? `${baseType}[]` : baseType;\n\n  return {\n    upstreamType: fullUpstreamType,\n    isNotNull: !nullableUpstream(liteTypeString),\n    isEnum: checkIsEnum(liteTypeString),\n    isArray: isArrayType,\n    characterMaxLength: characterMaxLength ?? null,\n    isBackfilling: false,\n  };\n}\n\n/**\n * Converts structured ColumnMetadata back to pipe-delimited LiteTypeString.\n * This is a compatibility helper for the migration period.\n */\nexport function metadataToLiteTypeString(metadata: ColumnMetadata): string {\n  return liteTypeString(\n    metadata.upstreamType,\n    metadata.isNotNull,\n    metadata.isEnum,\n    metadata.isArray,\n  );\n}\n\n/**\n * Converts PostgreSQL ColumnSpec to structured ColumnMetadata.\n * Used during replication to populate the metadata table from upstream schema.\n *\n * Uses the same logic as liteTypeString() and mapPostgresToLiteColumn() via shared helpers.\n */\nexport function pgColumnSpecToMetadata(spec: ColumnSpec): ColumnMetadata {\n  return {\n    upstreamType: spec.dataType,\n    isNotNull: spec.notNull ?? false,\n    isEnum: isEnumColumn(spec),\n    isArray: isArrayColumn(spec),\n    characterMaxLength: spec.characterMaximumLength ?? null,\n    isBackfilling: false,\n  };\n}\n"],"mappings":"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"}

package/out/zero-cache/src/services/replicator/schema/replication-state.js

@@ -1,6 +1,6 @@
 import { parse, valita_exports } from "../../../../../shared/src/valita.js";
 import { jsonObjectSchema, stringify } from "../../../../../shared/src/bigint-json.js";
-import "./constants.js";
+import { ZERO_VERSION_COLUMN_NAME } from "./constants.js";
 import { CREATE_COLUMN_METADATA_TABLE } from "./column-metadata.js";
 import { CREATE_TABLE_METADATA_TABLE } from "./table-metadata.js";
 import { CREATE_BACKFILLING_TABLE } from "./backfilling.js";
@@ -73,21 +73,23 @@ function getAscendingEvents(db) {
 	}));
 }
 function getSubscriptionState(db) {
-	return parse(db.get(`
+	const result = db.get(`
       SELECT c.replicaVersion, c.publications, s.stateVersion as watermark
         FROM "_zero.replicationConfig" as c
         JOIN "_zero.replicationState" as s
         ON c.lock = s.lock
-    `), subscriptionStateSchema);
+    `);
+	return parse(result, subscriptionStateSchema);
 }
 function getSubscriptionStateAndContext(db) {
-	return parse(db.get(`
+	const result = db.get(`
       SELECT c.replicaVersion, c.publications, c.initialSyncContext,
         s.stateVersion as watermark
         FROM "_zero.replicationConfig" as c
         JOIN "_zero.replicationState" as s
         ON c.lock = s.lock
-    `), subscriptionStateAndContextSchema);
+    `);
+	return parse(result, subscriptionStateAndContextSchema);
 }
 function updateReplicationWatermark(db, watermark, writeTimeMs) {
 	if (writeTimeMs === void 0) db.run(`
@@ -98,9 +100,10 @@ function updateReplicationWatermark(db, watermark, writeTimeMs) {
         SET stateVersion=?, writeTimeMs=?`, watermark, writeTimeMs);
 }
 function getReplicationState(db) {
-	return parse(db.get(`SELECT stateVersion FROM "_zero.replicationState"`), replicationStateSchema);
+	const result = db.get(`SELECT stateVersion FROM "_zero.replicationState"`);
+	return parse(result, replicationStateSchema);
 }
 //#endregion
-export { CREATE_RUNTIME_EVENTS_TABLE, createReplicationStateTables, getAscendingEvents, getReplicationState, getSubscriptionState, getSubscriptionStateAndContext, initReplicationState, recordEvent, updateReplicationWatermark };
+export { CREATE_RUNTIME_EVENTS_TABLE, ZERO_VERSION_COLUMN_NAME, createReplicationStateTables, getAscendingEvents, getReplicationState, getSubscriptionState, getSubscriptionStateAndContext, initReplicationState, recordEvent, updateReplicationWatermark };
 
 //# sourceMappingURL=replication-state.js.map

package/out/zero-cache/src/services/replicator/schema/replication-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"replication-state.js","names":[],"sources":["../../../../../../../zero-cache/src/services/replicator/schema/replication-state.ts"],"sourcesContent":["/**\n * Replication metadata, used for incremental view maintenance and catchup.\n *\n * These tables are created atomically in {@link setupReplicationTables}\n * after the logical replication handoff when initial data synchronization has completed.\n */\n\nimport {\n  jsonObjectSchema,\n  stringify,\n  type JSONObject,\n} from '../../../../../shared/src/bigint-json.ts';\nimport * as v from '../../../../../shared/src/valita.ts';\nimport type {Database} from '../../../../../zqlite/src/db.ts';\nimport type {StatementRunner} from '../../../db/statements.ts';\nimport {CREATE_BACKFILLING_TABLE} from './backfilling.ts';\nimport {CREATE_CHANGELOG_SCHEMA} from './change-log.ts';\nimport {CREATE_COLUMN_METADATA_TABLE} from './column-metadata.ts';\nimport {ZERO_VERSION_COLUMN_NAME} from './constants.ts';\nimport {CREATE_TABLE_METADATA_TABLE} from './table-metadata.ts';\n\nexport {ZERO_VERSION_COLUMN_NAME};\n\nexport type RuntimeEvent = 'sync' | 'upgrade' | 'vacuum';\n\n// event     : The RuntimeEvent. Only one row per event is tracked.\n//             Inserting an event will REPLACE any row for the same event.\n// timestamp : SQLite timestamp string, e.g. \"2024-04-12 11:37:46\".\n//             Append a `Z` when parsing with `new Date(...)`;\nexport const CREATE_RUNTIME_EVENTS_TABLE = `\n  CREATE TABLE \"_zero.runtimeEvents\" (\n    event TEXT PRIMARY KEY ON CONFLICT REPLACE,\n    timestamp TEXT NOT NULL DEFAULT (current_timestamp)\n  );\n`;\n\nconst CREATE_REPLICATION_STATE_SCHEMA =\n  // replicaVersion     : A value identifying the version at which the initial sync happened, i.e.\n  //                      the version at which all rows were copied, and to `_0_version` was set.\n  //                      This value is used to distinguish data from other replicas (e.g. if a\n  //                      replica is reset or if there are ever multiple replicas).\n  // publications       : JSON stringified array of publication names\n  // initialSyncContext : Metadata related to the context of when and how the replica was initially\n  //                      synced. This corresponds with the same column stored in upstream and is\n  //                      used for debugging replica version mismatches, which can arise from a number\n  //                      of misconfigurations, such as dueling replication-managers, or restores of\n  //                      stale litestream backups.\n  // lock               : Auto-magic column for enforcing single-row semantics.\n  /*sql*/ `\n  CREATE TABLE \"_zero.replicationConfig\" (\n    replicaVersion TEXT NOT NULL,\n    publications TEXT NOT NULL,\n    initialSyncContext TEXT DEFAULT '{}',\n    lock INTEGER PRIMARY KEY DEFAULT 1 CHECK (lock=1)\n  );\n  ` +\n  // stateVersion     : The latest version replicated from upstream, starting with the initial\n  //                    `replicaVersion` and moving forward to each subsequent commit watermark\n  //                    (e.g. corresponding to a Postgres LSN). Versions are represented as\n  //                    lexicographically sortable watermarks (e.g. LexiVersions).\n  // writeTimeMs      : The millisecond epoch at which this version was written to the replica.\n  //\n  /*sql*/ `\n  CREATE TABLE \"_zero.replicationState\" (\n    stateVersion TEXT NOT NULL,\n    writeTimeMs INTEGER NOT NULL,\n    lock INTEGER PRIMARY KEY DEFAULT 1 CHECK (lock=1)\n  );\n  ` +\n  CREATE_CHANGELOG_SCHEMA +\n  CREATE_RUNTIME_EVENTS_TABLE +\n  CREATE_COLUMN_METADATA_TABLE +\n  CREATE_TABLE_METADATA_TABLE +\n  CREATE_BACKFILLING_TABLE;\n\nconst stringArray = v.array(v.string());\n\nconst subscriptionStateSchema = v\n  .object({\n    replicaVersion: v.string(),\n    publications: v.string(),\n    watermark: v.string(),\n  })\n  .map(s => ({\n    ...s,\n    publications: v.parse(JSON.parse(s.publications), stringArray),\n  }));\n\nexport type SubscriptionState = v.Infer<typeof subscriptionStateSchema>;\n\nconst subscriptionStateAndContextSchema = v\n  .object({\n    replicaVersion: v.string(),\n    publications: v.string(),\n    initialSyncContext: v.string(),\n    watermark: v.string(),\n  })\n  .map(s => ({\n    ...s,\n    publications: v.parse(JSON.parse(s.publications), stringArray),\n    initialSyncContext: v.parse(\n      JSON.parse(s.initialSyncContext),\n      jsonObjectSchema,\n    ),\n  }));\n\nexport type SubscriptionStateAndContext = v.Infer<\n  typeof subscriptionStateAndContextSchema\n>;\n\nconst replicationStateSchema = v.object({\n  stateVersion: v.string(),\n});\n\nexport type ReplicationState = v.Infer<typeof replicationStateSchema>;\n\nexport function initReplicationState(\n  db: Database,\n  publications: string[],\n  watermark: string,\n  initialSyncContext: JSONObject = {},\n  createTables = true,\n) {\n  if (createTables) {\n    createReplicationStateTables(db);\n  }\n  db.prepare(\n    `\n    INSERT INTO \"_zero.replicationConfig\" \n       (replicaVersion, publications, initialSyncContext) VALUES (?, ?, ?)\n    `,\n  ).run(\n    watermark,\n    JSON.stringify(publications.sort()),\n    stringify(initialSyncContext),\n  );\n  db.prepare(/*sql*/ `\n    INSERT INTO \"_zero.replicationState\" (stateVersion, writeTimeMs) \n      VALUES (?, unixepoch('subsec') * 1000)\n    `).run(watermark);\n  recordEvent(db, 'sync');\n}\n\n/**\n * Exposed as a separate function for the custom change source,\n * which needs the tables to be created in order to construct\n * ChangeProcessor before it knows the initial watermark.\n */\nexport function createReplicationStateTables(db: Database) {\n  db.exec(CREATE_REPLICATION_STATE_SCHEMA);\n}\n\nexport function recordEvent(db: Database, event: RuntimeEvent) {\n  db.prepare(\n    `\n    INSERT INTO \"_zero.runtimeEvents\" (event) VALUES (?) \n    `,\n  ).run(event);\n}\n\nexport function getAscendingEvents(db: Database) {\n  const result = db\n    .prepare(\n      `SELECT event, timestamp FROM \"_zero.runtimeEvents\" \n         ORDER BY timestamp ASC\n    `,\n    )\n    .all<{event: string; timestamp: string}>();\n  return result.map(({event, timestamp}) => ({\n    event,\n    timestamp: new Date(timestamp + 'Z'),\n  }));\n}\n\nexport function getSubscriptionState(db: StatementRunner): SubscriptionState {\n  const result = db.get(/*sql*/ `\n      SELECT c.replicaVersion, c.publications, s.stateVersion as watermark\n        FROM \"_zero.replicationConfig\" as c\n        JOIN \"_zero.replicationState\" as s\n        ON c.lock = s.lock\n    `);\n  return v.parse(result, subscriptionStateSchema);\n}\n\nexport function getSubscriptionStateAndContext(\n  db: StatementRunner,\n): SubscriptionStateAndContext {\n  const result = db.get(/*sql*/ `\n      SELECT c.replicaVersion, c.publications, c.initialSyncContext,\n        s.stateVersion as watermark\n        FROM \"_zero.replicationConfig\" as c\n        JOIN \"_zero.replicationState\" as s\n        ON c.lock = s.lock\n    `);\n  return v.parse(result, subscriptionStateAndContextSchema);\n}\n\nexport function updateReplicationWatermark(\n  db: StatementRunner,\n  watermark: string,\n  writeTimeMs?: number | undefined,\n) {\n  if (writeTimeMs === undefined) {\n    db.run(\n      /*sql*/ `\n      UPDATE \"_zero.replicationState\"\n        SET stateVersion=?, writeTimeMs=unixepoch('subsec') * 1000`,\n      watermark,\n    );\n  } else {\n    db.run(\n      /*sql*/ `\n      UPDATE \"_zero.replicationState\"\n        SET stateVersion=?, writeTimeMs=?`,\n      watermark,\n      writeTimeMs,\n    );\n  }\n}\n\nexport function getReplicationState(db: StatementRunner): ReplicationState {\n  const result = db.get(`SELECT stateVersion FROM \"_zero.replicationState\"`);\n  return v.parse(result, replicationStateSchema);\n}\n"],"mappings":";;;;;;;;;;;;;;AA6BA,IAAa,8BAA8B;;;;;;AAO3C,IAAM,kCAYI,qZAqBR,0BACA,8BACA,+BACA,8BACA;AAEF,IAAM,cAAc,eAAE,MAAM,eAAE,OAAO,CAAC;AAEtC,IAAM,0BAA0B,eAC7B,OAAO;CACN,gBAAgB,eAAE,OAAO;CACzB,cAAc,eAAE,OAAO;CACvB,WAAW,eAAE,OAAO;AACtB,CAAC,EACA,KAAI,OAAM;CACT,GAAG;CACH,cAAc,MAAQ,KAAK,MAAM,EAAE,YAAY,GAAG,WAAW;AAC/D,EAAE;AAIJ,IAAM,oCAAoC,eACvC,OAAO;CACN,gBAAgB,eAAE,OAAO;CACzB,cAAc,eAAE,OAAO;CACvB,oBAAoB,eAAE,OAAO;CAC7B,WAAW,eAAE,OAAO;AACtB,CAAC,EACA,KAAI,OAAM;CACT,GAAG;CACH,cAAc,MAAQ,KAAK,MAAM,EAAE,YAAY,GAAG,WAAW;CAC7D,oBAAoB,MAClB,KAAK,MAAM,EAAE,kBAAkB,GAC/B,gBACF;AACF,EAAE;AAMJ,IAAM,yBAAyB,eAAE,OAAO,EACtC,cAAc,eAAE,OAAO,EACzB,CAAC;AAID,SAAgB,qBACd,IACA,cACA,WACA,qBAAiC,CAAC,GAClC,eAAe,MACf;CACA,IAAI,cACF,6BAA6B,EAAE;CAEjC,GAAG,QACD;;;KAIF,EAAE,IACA,WACA,KAAK,UAAU,aAAa,KAAK,CAAC,GAClC,UAAU,kBAAkB,CAC9B;CACA,GAAG,QAAgB;;;KAGhB,EAAE,IAAI,SAAS;CAClB,YAAY,IAAI,MAAM;AACxB;;;;;;AAOA,SAAgB,6BAA6B,IAAc;CACzD,GAAG,KAAK,+BAA+B;AACzC;AAEA,SAAgB,YAAY,IAAc,OAAqB;CAC7D,GAAG,QACD;;KAGF,EAAE,IAAI,KAAK;AACb;AAEA,SAAgB,mBAAmB,IAAc;CAQ/C,OAPe,GACZ,QACC;;KAGF,EACC,IACI,EAAO,KAAK,EAAC,OAAO,iBAAgB;EACzC;EACA,2BAAW,IAAI,KAAK,YAAY,GAAG;CACrC,EAAE;AACJ;AAEA,SAAgB,qBAAqB,IAAwC;CAO3E,OAAO,MANQ,GAAG,IAAY;;;;;KAMf,GAAQ,uBAAuB;AAChD;AAEA,SAAgB,+BACd,IAC6B;CAQ7B,OAAO,MAPQ,GAAG,IAAY;;;;;;KAOf,GAAQ,iCAAiC;AAC1D;AAEA,SAAgB,2BACd,IACA,WACA,aACA;CACA,IAAI,gBAAgB,KAAA,GAClB,GAAG,IACO;;qEAGR,SACF;MAEA,GAAG,IACO;;4CAGR,WACA,WACF;AAEJ;AAEA,SAAgB,oBAAoB,IAAuC;CAEzE,OAAO,MADQ,GAAG,IAAI,mDACP,GAAQ,sBAAsB;AAC/C"}
+{"version":3,"file":"replication-state.js","names":["v","v.parse"],"sources":["../../../../../../../zero-cache/src/services/replicator/schema/replication-state.ts"],"sourcesContent":["/**\n * Replication metadata, used for incremental view maintenance and catchup.\n *\n * These tables are created atomically in {@link setupReplicationTables}\n * after the logical replication handoff when initial data synchronization has completed.\n */\n\nimport {\n  jsonObjectSchema,\n  stringify,\n  type JSONObject,\n} from '../../../../../shared/src/bigint-json.ts';\nimport * as v from '../../../../../shared/src/valita.ts';\nimport type {Database} from '../../../../../zqlite/src/db.ts';\nimport type {StatementRunner} from '../../../db/statements.ts';\nimport {CREATE_BACKFILLING_TABLE} from './backfilling.ts';\nimport {CREATE_CHANGELOG_SCHEMA} from './change-log.ts';\nimport {CREATE_COLUMN_METADATA_TABLE} from './column-metadata.ts';\nimport {ZERO_VERSION_COLUMN_NAME} from './constants.ts';\nimport {CREATE_TABLE_METADATA_TABLE} from './table-metadata.ts';\n\nexport {ZERO_VERSION_COLUMN_NAME};\n\nexport type RuntimeEvent = 'sync' | 'upgrade' | 'vacuum';\n\n// event     : The RuntimeEvent. Only one row per event is tracked.\n//             Inserting an event will REPLACE any row for the same event.\n// timestamp : SQLite timestamp string, e.g. \"2024-04-12 11:37:46\".\n//             Append a `Z` when parsing with `new Date(...)`;\nexport const CREATE_RUNTIME_EVENTS_TABLE = `\n  CREATE TABLE \"_zero.runtimeEvents\" (\n    event TEXT PRIMARY KEY ON CONFLICT REPLACE,\n    timestamp TEXT NOT NULL DEFAULT (current_timestamp)\n  );\n`;\n\nconst CREATE_REPLICATION_STATE_SCHEMA =\n  // replicaVersion     : A value identifying the version at which the initial sync happened, i.e.\n  //                      the version at which all rows were copied, and to `_0_version` was set.\n  //                      This value is used to distinguish data from other replicas (e.g. if a\n  //                      replica is reset or if there are ever multiple replicas).\n  // publications       : JSON stringified array of publication names\n  // initialSyncContext : Metadata related to the context of when and how the replica was initially\n  //                      synced. This corresponds with the same column stored in upstream and is\n  //                      used for debugging replica version mismatches, which can arise from a number\n  //                      of misconfigurations, such as dueling replication-managers, or restores of\n  //                      stale litestream backups.\n  // lock               : Auto-magic column for enforcing single-row semantics.\n  /*sql*/ `\n  CREATE TABLE \"_zero.replicationConfig\" (\n    replicaVersion TEXT NOT NULL,\n    publications TEXT NOT NULL,\n    initialSyncContext TEXT DEFAULT '{}',\n    lock INTEGER PRIMARY KEY DEFAULT 1 CHECK (lock=1)\n  );\n  ` +\n  // stateVersion     : The latest version replicated from upstream, starting with the initial\n  //                    `replicaVersion` and moving forward to each subsequent commit watermark\n  //                    (e.g. corresponding to a Postgres LSN). Versions are represented as\n  //                    lexicographically sortable watermarks (e.g. LexiVersions).\n  // writeTimeMs      : The millisecond epoch at which this version was written to the replica.\n  //\n  /*sql*/ `\n  CREATE TABLE \"_zero.replicationState\" (\n    stateVersion TEXT NOT NULL,\n    writeTimeMs INTEGER NOT NULL,\n    lock INTEGER PRIMARY KEY DEFAULT 1 CHECK (lock=1)\n  );\n  ` +\n  CREATE_CHANGELOG_SCHEMA +\n  CREATE_RUNTIME_EVENTS_TABLE +\n  CREATE_COLUMN_METADATA_TABLE +\n  CREATE_TABLE_METADATA_TABLE +\n  CREATE_BACKFILLING_TABLE;\n\nconst stringArray = v.array(v.string());\n\nconst subscriptionStateSchema = v\n  .object({\n    replicaVersion: v.string(),\n    publications: v.string(),\n    watermark: v.string(),\n  })\n  .map(s => ({\n    ...s,\n    publications: v.parse(JSON.parse(s.publications), stringArray),\n  }));\n\nexport type SubscriptionState = v.Infer<typeof subscriptionStateSchema>;\n\nconst subscriptionStateAndContextSchema = v\n  .object({\n    replicaVersion: v.string(),\n    publications: v.string(),\n    initialSyncContext: v.string(),\n    watermark: v.string(),\n  })\n  .map(s => ({\n    ...s,\n    publications: v.parse(JSON.parse(s.publications), stringArray),\n    initialSyncContext: v.parse(\n      JSON.parse(s.initialSyncContext),\n      jsonObjectSchema,\n    ),\n  }));\n\nexport type SubscriptionStateAndContext = v.Infer<\n  typeof subscriptionStateAndContextSchema\n>;\n\nconst replicationStateSchema = v.object({\n  stateVersion: v.string(),\n});\n\nexport type ReplicationState = v.Infer<typeof replicationStateSchema>;\n\nexport function initReplicationState(\n  db: Database,\n  publications: string[],\n  watermark: string,\n  initialSyncContext: JSONObject = {},\n  createTables = true,\n) {\n  if (createTables) {\n    createReplicationStateTables(db);\n  }\n  db.prepare(\n    `\n    INSERT INTO \"_zero.replicationConfig\" \n       (replicaVersion, publications, initialSyncContext) VALUES (?, ?, ?)\n    `,\n  ).run(\n    watermark,\n    JSON.stringify(publications.sort()),\n    stringify(initialSyncContext),\n  );\n  db.prepare(/*sql*/ `\n    INSERT INTO \"_zero.replicationState\" (stateVersion, writeTimeMs) \n      VALUES (?, unixepoch('subsec') * 1000)\n    `).run(watermark);\n  recordEvent(db, 'sync');\n}\n\n/**\n * Exposed as a separate function for the custom change source,\n * which needs the tables to be created in order to construct\n * ChangeProcessor before it knows the initial watermark.\n */\nexport function createReplicationStateTables(db: Database) {\n  db.exec(CREATE_REPLICATION_STATE_SCHEMA);\n}\n\nexport function recordEvent(db: Database, event: RuntimeEvent) {\n  db.prepare(\n    `\n    INSERT INTO \"_zero.runtimeEvents\" (event) VALUES (?) \n    `,\n  ).run(event);\n}\n\nexport function getAscendingEvents(db: Database) {\n  const result = db\n    .prepare(\n      `SELECT event, timestamp FROM \"_zero.runtimeEvents\" \n         ORDER BY timestamp ASC\n    `,\n    )\n    .all<{event: string; timestamp: string}>();\n  return result.map(({event, timestamp}) => ({\n    event,\n    timestamp: new Date(timestamp + 'Z'),\n  }));\n}\n\nexport function getSubscriptionState(db: StatementRunner): SubscriptionState {\n  const result = db.get(/*sql*/ `\n      SELECT c.replicaVersion, c.publications, s.stateVersion as watermark\n        FROM \"_zero.replicationConfig\" as c\n        JOIN \"_zero.replicationState\" as s\n        ON c.lock = s.lock\n    `);\n  return v.parse(result, subscriptionStateSchema);\n}\n\nexport function getSubscriptionStateAndContext(\n  db: StatementRunner,\n): SubscriptionStateAndContext {\n  const result = db.get(/*sql*/ `\n      SELECT c.replicaVersion, c.publications, c.initialSyncContext,\n        s.stateVersion as watermark\n        FROM \"_zero.replicationConfig\" as c\n        JOIN \"_zero.replicationState\" as s\n        ON c.lock = s.lock\n    `);\n  return v.parse(result, subscriptionStateAndContextSchema);\n}\n\nexport function updateReplicationWatermark(\n  db: StatementRunner,\n  watermark: string,\n  writeTimeMs?: number | undefined,\n) {\n  if (writeTimeMs === undefined) {\n    db.run(\n      /*sql*/ `\n      UPDATE \"_zero.replicationState\"\n        SET stateVersion=?, writeTimeMs=unixepoch('subsec') * 1000`,\n      watermark,\n    );\n  } else {\n    db.run(\n      /*sql*/ `\n      UPDATE \"_zero.replicationState\"\n        SET stateVersion=?, writeTimeMs=?`,\n      watermark,\n      writeTimeMs,\n    );\n  }\n}\n\nexport function getReplicationState(db: StatementRunner): ReplicationState {\n  const result = db.get(`SELECT stateVersion FROM \"_zero.replicationState\"`);\n  return v.parse(result, replicationStateSchema);\n}\n"],"mappings":";;;;;;;;;;;;;;AA6BA,IAAa,8BAA8B;;;;;;AAO3C,IAAM,kCAYI,qZAqBR,0BACA,8BACA,+BACA,8BACA;AAEF,IAAM,cAAcA,eAAE,MAAMA,eAAE,OAAO,CAAC;AAEtC,IAAM,0BAA0BA,eAC7B,OAAO;CACN,gBAAgBA,eAAE,OAAO;CACzB,cAAcA,eAAE,OAAO;CACvB,WAAWA,eAAE,OAAO;AACtB,CAAC,CAAC,CACD,KAAI,OAAM;CACT,GAAG;CACH,cAAcC,MAAQ,KAAK,MAAM,EAAE,YAAY,GAAG,WAAW;AAC/D,EAAE;AAIJ,IAAM,oCAAoCD,eACvC,OAAO;CACN,gBAAgBA,eAAE,OAAO;CACzB,cAAcA,eAAE,OAAO;CACvB,oBAAoBA,eAAE,OAAO;CAC7B,WAAWA,eAAE,OAAO;AACtB,CAAC,CAAC,CACD,KAAI,OAAM;CACT,GAAG;CACH,cAAcC,MAAQ,KAAK,MAAM,EAAE,YAAY,GAAG,WAAW;CAC7D,oBAAoBA,MAClB,KAAK,MAAM,EAAE,kBAAkB,GAC/B,gBACF;AACF,EAAE;AAMJ,IAAM,yBAAyBD,eAAE,OAAO,EACtC,cAAcA,eAAE,OAAO,EACzB,CAAC;AAID,SAAgB,qBACd,IACA,cACA,WACA,qBAAiC,CAAC,GAClC,eAAe,MACf;CACA,IAAI,cACF,6BAA6B,EAAE;CAEjC,GAAG,QACD;;;KAIF,CAAC,CAAC,IACA,WACA,KAAK,UAAU,aAAa,KAAK,CAAC,GAClC,UAAU,kBAAkB,CAC9B;CACA,GAAG,QAAgB;;;KAGhB,CAAC,CAAC,IAAI,SAAS;CAClB,YAAY,IAAI,MAAM;AACxB;;;;;;AAOA,SAAgB,6BAA6B,IAAc;CACzD,GAAG,KAAK,+BAA+B;AACzC;AAEA,SAAgB,YAAY,IAAc,OAAqB;CAC7D,GAAG,QACD;;KAGF,CAAC,CAAC,IAAI,KAAK;AACb;AAEA,SAAgB,mBAAmB,IAAc;CAQ/C,OAPe,GACZ,QACC;;KAGF,CAAC,CACA,IACI,CAAA,CAAO,KAAK,EAAC,OAAO,iBAAgB;EACzC;EACA,2BAAW,IAAI,KAAK,YAAY,GAAG;CACrC,EAAE;AACJ;AAEA,SAAgB,qBAAqB,IAAwC;CAC3E,MAAM,SAAS,GAAG,IAAY;;;;;KAK3B;CACH,OAAOC,MAAQ,QAAQ,uBAAuB;AAChD;AAEA,SAAgB,+BACd,IAC6B;CAC7B,MAAM,SAAS,GAAG,IAAY;;;;;;KAM3B;CACH,OAAOA,MAAQ,QAAQ,iCAAiC;AAC1D;AAEA,SAAgB,2BACd,IACA,WACA,aACA;CACA,IAAI,gBAAgB,KAAA,GAClB,GAAG,IACO;;qEAGR,SACF;MAEA,GAAG,IACO;;4CAGR,WACA,WACF;AAEJ;AAEA,SAAgB,oBAAoB,IAAuC;CACzE,MAAM,SAAS,GAAG,IAAI,mDAAmD;CACzE,OAAOA,MAAQ,QAAQ,sBAAsB;AAC/C"}

package/out/zero-cache/src/services/replicator/schema/table-metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"table-metadata.js","names":["#db","#setUpstreamMetadata","#setMinRowVersion","#getMinRowVersions","#rename","#drop"],"sources":["../../../../../../../zero-cache/src/services/replicator/schema/table-metadata.ts"],"sourcesContent":["import type {Database, Statement} from '../../../../../zqlite/src/db.ts';\nimport {liteTableName} from '../../../types/names.ts';\nimport type {\n  Identifier,\n  TableMetadata,\n} from '../../change-source/protocol/current.ts';\n\n/**\n * Table-level controls for handling replicated data.\n *\n * ### Columns\n *\n * `minRowVersion`: the minimum `_0_version` value to apply to\n *   all rows in the table. This overrides any per-row\n *   `_0_version` value that is smaller (i.e. earlier).\n *   The `minRowVersion` column is used to force a re-download\n *   of all rows after a table-wide schema change (by giving\n *   each row a version that's newer than what's in any CVR).\n *   The naive, brute-force method of updating all of the rows\n *   requires re-writing the entire table into the WAL as one\n *   SQLite operation, which is too costly from both latency\n *   and storage space.\n *\n * `upstreamMetadata`: the replica-level analog of tableMetadata in\n *   change-streamer/schema. Per the requirement of the backfill\n *   protocol, backfill metadata must be tracked outside of the\n *   change source (otherwise the change source would have to be\n *   able to compute the state of the metadata at arbitrary points\n *   in the past).\n *\n * `metadata`: the previous name of the `upstreamMetadata` column,\n *   kept for backwards compatibility.\n *\n * This tracking is done:\n * 1. at the Change DB level, by the change-streamer\n * 2. at the replica level, in order to support the eventual configuration\n *    of ephemeral Change DBs (on SQLite) that are initialized from data\n *    in the replica.\n */\nexport const CREATE_TABLE_METADATA_TABLE = /*sql*/ `\n  CREATE TABLE \"_zero.tableMetadata\" (\n    \"schema\"           TEXT NOT NULL,\n    \"table\"            TEXT NOT NULL,\n    \"minRowVersion\"    TEXT NOT NULL DEFAULT \"00\",\n    \"upstreamMetadata\" TEXT,\n    \"metadata\"         TEXT,  -- deprecated\n    PRIMARY KEY (\"schema\", \"table\")\n  );\n`;\n\nexport class TableMetadataTracker {\n  readonly #db: Database;\n\n  // All statements are lazily created.\n  #setUpstreamMetadata: Statement | undefined;\n  #setMinRowVersion: Statement | undefined;\n  #getMinRowVersions: Statement | undefined;\n  #rename: Statement | undefined;\n  #drop: Statement | undefined;\n\n  constructor(db: Database) {\n    this.#db = db;\n  }\n\n  setUpstreamMetadata({schema, name}: Identifier, metadata: TableMetadata) {\n    (this.#setUpstreamMetadata ??= this.#db.prepare(/*sql*/ `\n      INSERT INTO \"_zero.tableMetadata\" (\"schema\", \"table\", \"upstreamMetadata\") \n        VALUES (@schema, @name, @metadata)\n        ON CONFLICT (\"schema\", \"table\")\n        DO UPDATE SET \"upstreamMetadata\" = @metadata\n    `)).run({\n      schema,\n      name,\n      metadata: JSON.stringify(metadata),\n    });\n  }\n\n  setMinRowVersion({schema, name}: Identifier, version: string) {\n    (this.#setMinRowVersion ??= this.#db.prepare(/*sql*/ `\n      INSERT INTO \"_zero.tableMetadata\" (\"schema\", \"table\", \"minRowVersion\") \n        VALUES (@schema, @name, @version)\n        ON CONFLICT (\"schema\", \"table\")\n        DO UPDATE SET \"minRowVersion\" = @version;\n    `)).run({schema, name, version});\n  }\n\n  getMinRowVersions(): Map<string, string> {\n    const results = (this.#getMinRowVersions ??= this.#db.prepare(/*sql*/ `\n      SELECT \"schema\", \"table\" as \"name\", \"minRowVersion\" FROM \"_zero.tableMetadata\"\n    `)).all<{schema: string; name: string; minRowVersion: string}>();\n    return new Map(\n      results.map(({schema, name, minRowVersion}) => [\n        liteTableName({schema, name}),\n        minRowVersion,\n      ]),\n    );\n  }\n\n  rename(oldTable: Identifier, newTable: Identifier) {\n    (this.#rename ??= this.#db.prepare(/*sql*/ `\n      UPDATE \"_zero.tableMetadata\" SET \"schema\" = ?, \"table\" = ?\n        WHERE \"schema\" = ? AND \"table\" = ?\n    `)).run(newTable.schema, newTable.name, oldTable.schema, oldTable.name);\n  }\n\n  drop({schema, name}: Identifier) {\n    (this.#drop ??= this.#db.prepare(/*sql*/ `\n      DELETE FROM \"_zero.tableMetadata\" WHERE \"schema\" = ? AND \"table\" = ?\n    `)).run(schema, name);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,IAAa,8BAAsC;;;;;;;;;;AAWnD,IAAa,uBAAb,MAAkC;CAChC;CAGA;CACA;CACA;CACA;CACA;CAEA,YAAY,IAAc;EACxB,KAAKA,MAAM;CACb;CAEA,oBAAoB,EAAC,QAAQ,QAAmB,UAAyB;EACvE,CAAC,KAAKC,yBAAyB,KAAKD,IAAI,QAAgB;;;;;KAKvD,GAAG,IAAI;GACN;GACA;GACA,UAAU,KAAK,UAAU,QAAQ;EACnC,CAAC;CACH;CAEA,iBAAiB,EAAC,QAAQ,QAAmB,SAAiB;EAC5D,CAAC,KAAKE,sBAAsB,KAAKF,IAAI,QAAgB;;;;;KAKpD,GAAG,IAAI;GAAC;GAAQ;GAAM;EAAO,CAAC;CACjC;CAEA,oBAAyC;EACvC,MAAM,WAAW,KAAKG,uBAAuB,KAAKH,IAAI,QAAgB;;KAErE,GAAG,IAA2D;EAC/D,OAAO,IAAI,IACT,QAAQ,KAAK,EAAC,QAAQ,MAAM,oBAAmB,CAC7C,cAAc;GAAC;GAAQ;EAAI,CAAC,GAC5B,aACF,CAAC,CACH;CACF;CAEA,OAAO,UAAsB,UAAsB;EACjD,CAAC,KAAKI,YAAY,KAAKJ,IAAI,QAAgB;;;KAG1C,GAAG,IAAI,SAAS,QAAQ,SAAS,MAAM,SAAS,QAAQ,SAAS,IAAI;CACxE;CAEA,KAAK,EAAC,QAAQ,QAAmB;EAC/B,CAAC,KAAKK,UAAU,KAAKL,IAAI,QAAgB;;KAExC,GAAG,IAAI,QAAQ,IAAI;CACtB;AACF"}
+{"version":3,"file":"table-metadata.js","names":[],"sources":["../../../../../../../zero-cache/src/services/replicator/schema/table-metadata.ts"],"sourcesContent":["import type {Database, Statement} from '../../../../../zqlite/src/db.ts';\nimport {liteTableName} from '../../../types/names.ts';\nimport type {\n  Identifier,\n  TableMetadata,\n} from '../../change-source/protocol/current.ts';\n\n/**\n * Table-level controls for handling replicated data.\n *\n * ### Columns\n *\n * `minRowVersion`: the minimum `_0_version` value to apply to\n *   all rows in the table. This overrides any per-row\n *   `_0_version` value that is smaller (i.e. earlier).\n *   The `minRowVersion` column is used to force a re-download\n *   of all rows after a table-wide schema change (by giving\n *   each row a version that's newer than what's in any CVR).\n *   The naive, brute-force method of updating all of the rows\n *   requires re-writing the entire table into the WAL as one\n *   SQLite operation, which is too costly from both latency\n *   and storage space.\n *\n * `upstreamMetadata`: the replica-level analog of tableMetadata in\n *   change-streamer/schema. Per the requirement of the backfill\n *   protocol, backfill metadata must be tracked outside of the\n *   change source (otherwise the change source would have to be\n *   able to compute the state of the metadata at arbitrary points\n *   in the past).\n *\n * `metadata`: the previous name of the `upstreamMetadata` column,\n *   kept for backwards compatibility.\n *\n * This tracking is done:\n * 1. at the Change DB level, by the change-streamer\n * 2. at the replica level, in order to support the eventual configuration\n *    of ephemeral Change DBs (on SQLite) that are initialized from data\n *    in the replica.\n */\nexport const CREATE_TABLE_METADATA_TABLE = /*sql*/ `\n  CREATE TABLE \"_zero.tableMetadata\" (\n    \"schema\"           TEXT NOT NULL,\n    \"table\"            TEXT NOT NULL,\n    \"minRowVersion\"    TEXT NOT NULL DEFAULT \"00\",\n    \"upstreamMetadata\" TEXT,\n    \"metadata\"         TEXT,  -- deprecated\n    PRIMARY KEY (\"schema\", \"table\")\n  );\n`;\n\nexport class TableMetadataTracker {\n  readonly #db: Database;\n\n  // All statements are lazily created.\n  #setUpstreamMetadata: Statement | undefined;\n  #setMinRowVersion: Statement | undefined;\n  #getMinRowVersions: Statement | undefined;\n  #rename: Statement | undefined;\n  #drop: Statement | undefined;\n\n  constructor(db: Database) {\n    this.#db = db;\n  }\n\n  setUpstreamMetadata({schema, name}: Identifier, metadata: TableMetadata) {\n    (this.#setUpstreamMetadata ??= this.#db.prepare(/*sql*/ `\n      INSERT INTO \"_zero.tableMetadata\" (\"schema\", \"table\", \"upstreamMetadata\") \n        VALUES (@schema, @name, @metadata)\n        ON CONFLICT (\"schema\", \"table\")\n        DO UPDATE SET \"upstreamMetadata\" = @metadata\n    `)).run({\n      schema,\n      name,\n      metadata: JSON.stringify(metadata),\n    });\n  }\n\n  setMinRowVersion({schema, name}: Identifier, version: string) {\n    (this.#setMinRowVersion ??= this.#db.prepare(/*sql*/ `\n      INSERT INTO \"_zero.tableMetadata\" (\"schema\", \"table\", \"minRowVersion\") \n        VALUES (@schema, @name, @version)\n        ON CONFLICT (\"schema\", \"table\")\n        DO UPDATE SET \"minRowVersion\" = @version;\n    `)).run({schema, name, version});\n  }\n\n  getMinRowVersions(): Map<string, string> {\n    const results = (this.#getMinRowVersions ??= this.#db.prepare(/*sql*/ `\n      SELECT \"schema\", \"table\" as \"name\", \"minRowVersion\" FROM \"_zero.tableMetadata\"\n    `)).all<{schema: string; name: string; minRowVersion: string}>();\n    return new Map(\n      results.map(({schema, name, minRowVersion}) => [\n        liteTableName({schema, name}),\n        minRowVersion,\n      ]),\n    );\n  }\n\n  rename(oldTable: Identifier, newTable: Identifier) {\n    (this.#rename ??= this.#db.prepare(/*sql*/ `\n      UPDATE \"_zero.tableMetadata\" SET \"schema\" = ?, \"table\" = ?\n        WHERE \"schema\" = ? AND \"table\" = ?\n    `)).run(newTable.schema, newTable.name, oldTable.schema, oldTable.name);\n  }\n\n  drop({schema, name}: Identifier) {\n    (this.#drop ??= this.#db.prepare(/*sql*/ `\n      DELETE FROM \"_zero.tableMetadata\" WHERE \"schema\" = ? AND \"table\" = ?\n    `)).run(schema, name);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,IAAa,8BAAsC;;;;;;;;;;AAWnD,IAAa,uBAAb,MAAkC;CAChC;CAGA;CACA;CACA;CACA;CACA;CAEA,YAAY,IAAc;EACxB,KAAK,MAAM;CACb;CAEA,oBAAoB,EAAC,QAAQ,QAAmB,UAAyB;EACvE,CAAC,KAAK,yBAAyB,KAAK,IAAI,QAAgB;;;;;KAKvD,EAAA,CAAG,IAAI;GACN;GACA;GACA,UAAU,KAAK,UAAU,QAAQ;EACnC,CAAC;CACH;CAEA,iBAAiB,EAAC,QAAQ,QAAmB,SAAiB;EAC5D,CAAC,KAAK,sBAAsB,KAAK,IAAI,QAAgB;;;;;KAKpD,EAAA,CAAG,IAAI;GAAC;GAAQ;GAAM;EAAO,CAAC;CACjC;CAEA,oBAAyC;EACvC,MAAM,WAAW,KAAK,uBAAuB,KAAK,IAAI,QAAgB;;KAErE,EAAA,CAAG,IAA2D;EAC/D,OAAO,IAAI,IACT,QAAQ,KAAK,EAAC,QAAQ,MAAM,oBAAmB,CAC7C,cAAc;GAAC;GAAQ;EAAI,CAAC,GAC5B,aACF,CAAC,CACH;CACF;CAEA,OAAO,UAAsB,UAAsB;EACjD,CAAC,KAAK,YAAY,KAAK,IAAI,QAAgB;;;KAG1C,EAAA,CAAG,IAAI,SAAS,QAAQ,SAAS,MAAM,SAAS,QAAQ,SAAS,IAAI;CACxE;CAEA,KAAK,EAAC,QAAQ,QAAmB;EAC/B,CAAC,KAAK,UAAU,KAAK,IAAI,QAAgB;;KAExC,EAAA,CAAG,IAAI,QAAQ,IAAI;CACtB;AACF"}

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

@@ -415,6 +415,6 @@ function watermarkDistance(receivedHead, sqliteHead) {
 	}
 }
 //#endregion
-export { SQLiteChangeLogObserver, getSQLiteChangeLogInfo, logSQLiteChangeLogStartup, recordSQLiteChangeLogReconcile, sqliteFileBytes };
+export { SQLiteChangeLogObserver, getSQLiteChangeLogInfo, getSQLiteChangeLogStartupInfo, logSQLiteChangeLogStartup, recordSQLiteChangeLogReconcile, sqliteFileBytes };
 
 //# sourceMappingURL=sqlite-change-log-observability.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"sqlite-change-log-observability.js","names":["#lc","#messageProcessing","#logCommitDuration","#transactionRows","#rollbackCounter","#invariantFailureCounter","#hashComparisonCounter","#hashUnpairedCounter","#cookieMutationCounter","#receivedHead","#sqliteHead","#rows","#estimatedBytes","#cookieRows","#sourceHasher","#invariantFailure","#sourcePos","#sourceCommitHash","#resetSourceHash","#transactionWatermark","#recordRollback","#recordUnpaired","#compareHashes","#cookieMutations","#rollbacks","#invariantFailures","#hashMatches","#hashMismatches","#hashUnpaired"],"sources":["../../../../../../zero-cache/src/services/replicator/sqlite-change-log-observability.ts"],"sourcesContent":["/**\n * Observability for the SQLite change log.\n *\n * Everything here now runs in the **change-streamer** process, which is where\n * the writer lives. The module stays beside the rest of the change-log code\n * under `services/replicator/` for the same reason `change-log-db.ts` and\n * `change-log-stream-writer.ts` do: moving files would obscure the topology\n * diff, and the writer's home is a property of who calls it rather than of\n * where it sits. Metric names are unchanged from 7H — only their emitting\n * process, and therefore their resource attributes, moved.\n */\n\nimport {stat} from 'node:fs/promises';\nimport type {LogContext} from '@rocicorp/logger';\nimport {unreachable} from '../../../../shared/src/asserts.ts';\nimport type {Database} from '../../../../zqlite/src/db.ts';\nimport {\n  getOrCreateCounter,\n  getOrCreateGauge,\n  getOrCreateLatencyHistogram,\n  getOrCreateValueHistogram,\n} from '../../observability/metrics.ts';\nimport {versionFromLexi} from '../../types/lexi-version.ts';\nimport type {ChangeStreamData} from '../change-source/protocol/current/downstream.ts';\nimport {extractChangeSubstring} from '../change-streamer/change-log-codec.ts';\nimport {ChangeLogTransactionHasher} from '../change-streamer/change-log-transaction-hash.ts';\nimport {\n  readCookieRowCounts,\n  type CookieOpTag,\n  type CookieRowCounts,\n} from './change-log-cookies.ts';\nimport {\n  CHANGE_LOG_STREAM_TABLE,\n  readChangeLogBounds,\n  readChangeLogMeta,\n  type ChangeLogMeta,\n  type ReconcileResult,\n} from './change-log-db.ts';\nimport type {ChangeLogStreamTransactionStats} from './change-log-stream-writer.ts';\n\n/**\n * Reports the reconciliation of the change-log database against the watermark\n * the stream connection resumes from. This runs once per stream connection, so\n * a reconnect storm is visible here as well as a restart.\n *\n * A wipe is not an error — it is how every abnormal change-log state is\n * collapsed into a correct one — but each wipe costs the retention window, so\n * every reconnecting subscriber below the head gets `too-old`. The `gap` reason\n * in particular means the log neither held the resume watermark nor could be\n * truncated to it, so a nonzero rate in steady state is an alert, not a\n * statistic.\n */\nexport function recordSQLiteChangeLogReconcile(\n  lc: LogContext,\n  result: ReconcileResult,\n): void {\n  switch (result.action) {\n    case 'truncated':\n      getOrCreateCounter(\n        'replica',\n        'sqlite_change_log.reconcile_truncated_rows',\n        'Phantom change-log rows removed at reconciliation, i.e. rows above ' +\n          'the watermark the change stream resumed from.',\n      ).add(result.rows);\n      break;\n    case 'reseeded':\n      getOrCreateCounter(\n        'replica',\n        'sqlite_change_log.reconcile_wipes',\n        'Change-log wipes at reconciliation, by reason. Each one resets the ' +\n          'retention window, so subscribers below the head get `too-old`.',\n      ).add(1, {reason: result.reason});\n      break;\n    case 'none':\n      break;\n    default:\n      unreachable(result);\n  }\n  if (result.cookiesStale) {\n    // The invariant-17 counter: after any reconcile that moved the head, the\n    // log's cookie set has to be replaced with the one that belongs to the\n    // resume watermark. A nonzero `truncated` series in steady state means\n    // phantom truncation is happening on a shard where it should not.\n    getOrCreateCounter(\n      'replica',\n      'sqlite_change_log.cookie_reseed',\n      'Change-log cookie sets invalidated at reconciliation, by the ' +\n        'reconcile action that invalidated them.',\n    ).add(1, {action: result.action});\n  }\n  lc.debug?.('SQLite change-log reconciliation', {\n    sqliteChangeLogReconcile: result,\n  });\n}\n\n/**\n * What the log says about itself. Nothing here reads the replica: after the\n * writer moved to the change-streamer, the replica's state version is a\n * consequence of this log rather than a fact about it.\n */\nexport type SQLiteChangeLogStartupInfo = ChangeLogMeta & {\n  readonly minWatermark: string;\n  readonly headWatermark: string;\n};\n\nexport type SQLiteChangeLogInfo = SQLiteChangeLogStartupInfo & {\n  readonly rows: number;\n  readonly estimatedBytes: number;\n  readonly cookieRows: CookieRowCounts;\n};\n\n/**\n * Reads the meta row and covered range. Unlike {@link getSQLiteChangeLogInfo}\n * this does not scan the log; see {@link readChangeLogBounds}.\n *\n * Call this after reconciliation, which is the only point at which the head is\n * known to be the resume watermark.\n */\nexport function getSQLiteChangeLogStartupInfo(\n  changeLog: Database,\n): SQLiteChangeLogStartupInfo {\n  const meta = readChangeLogMeta(changeLog);\n  const {minWatermark, headWatermark} = readChangeLogBounds(changeLog);\n  if (minWatermark === null || headWatermark === null) {\n    throw new Error('the SQLite change log must contain its seed transaction');\n  }\n  return {...meta, minWatermark, headWatermark};\n}\n\n/**\n * Extends {@link getSQLiteChangeLogStartupInfo} with the retained row and\n * estimated byte totals. Computing these scans the entire change-log table, so\n * only call it when the totals are consumed, i.e. when the writer (and thus the\n * observer) is enabled.\n */\nexport function getSQLiteChangeLogInfo(\n  changeLog: Database,\n): SQLiteChangeLogInfo {\n  const startup = getSQLiteChangeLogStartupInfo(changeLog);\n  const aggregate = changeLog\n    .prepare(/*sql*/ `\n      SELECT count(*) AS \"rows\",\n             coalesce(sum(\"estimatedBytes\"), 0) AS \"estimatedBytes\"\n        FROM \"${CHANGE_LOG_STREAM_TABLE}\"\n    `)\n    .get<{rows: number; estimatedBytes: number}>();\n\n  return {\n    ...startup,\n    rows: aggregate.rows,\n    estimatedBytes: aggregate.estimatedBytes,\n    cookieRows: readCookieRowCounts(changeLog),\n  };\n}\n\nexport function logSQLiteChangeLogStartup(\n  lc: LogContext,\n  file: string,\n  info: SQLiteChangeLogStartupInfo,\n): void {\n  lc.info?.('SQLite change-log startup', {\n    sqliteChangeLog: {\n      file,\n      epoch: info.epoch,\n      generation: info.generation,\n      replicaID: info.replicaID,\n      schemaVersion: info.schemaVersion,\n      seedWatermark: info.seedWatermark,\n      seededAtMs: info.seededAtMs,\n      minWatermark: info.minWatermark,\n      headWatermark: info.headWatermark,\n    },\n  });\n}\n\n/**\n * The on-disk footprint of a SQLite database: its main file plus its `-wal` and\n * `-wal2` sidecars, whichever exist. `-shm` is excluded — it is a\n * shared-memory index rather than retained bytes.\n *\n * A missing file counts as zero rather than warning. Which sidecars exist\n * depends on the journal mode, and the change-log database is absent entirely\n * until the writer creates it.\n */\nexport async function sqliteFileBytes(\n  lc: LogContext,\n  file: string,\n): Promise<number> {\n  const sizes = await Promise.all(\n    [file, `${file}-wal`, `${file}-wal2`].map(async path => {\n      try {\n        return (await stat(path)).size;\n      } catch (e) {\n        if ((e as NodeJS.ErrnoException).code !== 'ENOENT') {\n          lc.warn?.(`unable to stat ${path} for size metrics`, e);\n        }\n        return 0;\n      }\n    }),\n  );\n  return sizes.reduce((total, size) => total + size, 0);\n}\n\n/** What the writer reports back for a committed transaction. */\nexport type ChangeLogCommit = {\n  readonly watermark: string;\n  readonly stats: ChangeLogStreamTransactionStats;\n  /**\n   * Appending the commit row and committing the log's transaction. This is the\n   * cost that sits on the forward path, once per upstream transaction.\n   */\n  readonly logCommitMs: number;\n};\n\nexport type SQLiteChangeLogObservabilityState = {\n  readonly receivedHead: string;\n  readonly sqliteHead: string;\n  readonly headLag: number | undefined;\n  readonly rows: number;\n  readonly estimatedBytes: number;\n  readonly cookieRows: CookieRowCounts;\n  readonly cookieMutations: number;\n  readonly rollbacks: number;\n  readonly invariantFailures: number;\n  readonly hashMatches: number;\n  readonly hashMismatches: number;\n  readonly hashUnpaired: number;\n};\n\nconst TRANSACTION_ROW_BUCKETS = [2, 3, 5, 10, 25, 50, 100, 250, 1000, 5000];\n\n/**\n * Records writer metrics in the change-streamer process. State changes only\n * after the corresponding write succeeds, except receivedHead, which advances\n * when a commit message arrives so that transient lag behind the log is\n * observable.\n */\nexport class SQLiteChangeLogObserver {\n  readonly #lc: LogContext;\n  readonly #messageProcessing = getOrCreateLatencyHistogram(\n    'replica',\n    'sqlite_change_log.message_processing_duration',\n    'Sampled time to write a replication message to the SQLite change log.',\n  );\n  // The commit that sits on the forward path. There is no second commit to\n  // order against any more: the replica's belongs to a subscriber downstream of\n  // this loop, so `sqlite_change_log.replica_commit_duration` and the phantom\n  // window it measured are gone. Sampled failed commits are still timed by\n  // `message_processing_duration` keyed `tag=\"commit\"`.\n  readonly #logCommitDuration = getOrCreateLatencyHistogram(\n    'replica',\n    'sqlite_change_log.log_commit_duration',\n    'Time to append the commit row to the SQLite change log and commit its ' +\n      'transaction. This is on the forward path: it precedes the forward of ' +\n      \"that transaction's commit message.\",\n  );\n  readonly #transactionRows = getOrCreateValueHistogram(\n    'replica',\n    'sqlite_change_log.transaction_rows',\n    {\n      description: 'Rows stored per committed SQLite change-log transaction.',\n      unit: '{row}',\n      bucketBoundaries: TRANSACTION_ROW_BUCKETS,\n    },\n  );\n  readonly #rollbackCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.rollbacks',\n    'SQLite change-log transactions rolled back before commit.',\n  );\n  readonly #invariantFailureCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.invariant_failures',\n    'Detected SQLite change-log writer invariant failures.',\n  );\n  readonly #hashComparisonCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.hash_comparisons',\n    'Sampled ephemeral transaction hash comparisons between the received change stream and SQLite change-log writes.',\n  );\n  readonly #hashUnpairedCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.hash_unpaired',\n    'Committed change-log transactions without both ephemeral hashes available for comparison.',\n  );\n  // Near zero at steady state: cookie state only moves on schema changes.\n  readonly #cookieMutationCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.cookie_mutations',\n    'Change-log cookie mutations folded from schema changes, by operation.',\n  );\n\n  #receivedHead: string;\n  #sqliteHead: string;\n  #rows: number;\n  #estimatedBytes: number;\n  #cookieRows: CookieRowCounts;\n  #cookieMutations = 0;\n  #transactionWatermark: string | undefined;\n  #sourceHasher: ChangeLogTransactionHasher | undefined;\n  #sourcePos = 0;\n  #sourceCommitHash: string | undefined;\n  #rollbacks = 0;\n  #invariantFailures = 0;\n  #hashMatches = 0;\n  #hashMismatches = 0;\n  #hashUnpaired = 0;\n\n  constructor(lc: LogContext, info: SQLiteChangeLogInfo) {\n    this.#lc = lc.withContext('component', 'sqlite-change-log-observer');\n    // Reconciliation has just put the head at the resume watermark, which is\n    // also the point the stream is about to be received from.\n    this.#receivedHead = info.headWatermark;\n    this.#sqliteHead = info.headWatermark;\n    this.#rows = info.rows;\n    this.#estimatedBytes = info.estimatedBytes;\n    this.#cookieRows = info.cookieRows;\n\n    getOrCreateGauge(\n      'replica',\n      'sqlite_change_log.rows',\n      'Rows retained in the SQLite change log.',\n    ).addCallback(result => result.observe(this.#rows));\n    // Nonzero with no backfill in flight is a leaked cookie, i.e. a backfill\n    // that will be re-requested forever.\n    getOrCreateGauge(\n      'replica',\n      'sqlite_change_log.cookie_rows',\n      'Cookie rows retained in the SQLite change log, by cookie table.',\n    ).addCallback(result => {\n      result.observe(this.#cookieRows.tableMetadata, {table: 'tableMetadata'});\n      result.observe(this.#cookieRows.backfilling, {table: 'backfilling'});\n    });\n    getOrCreateGauge('replica', 'sqlite_change_log.retained_bytes', {\n      description:\n        'Estimated UTF-8 payload bytes retained in the SQLite change log.',\n      unit: 'By',\n    }).addCallback(result => result.observe(this.#estimatedBytes));\n    getOrCreateGauge(\n      'replica',\n      'sqlite_change_log.head',\n      'SQLite change-log head converted from its lexicographic watermark.',\n    ).addCallback(result => {\n      const head = watermarkValue(this.#sqliteHead);\n      if (head !== undefined) {\n        result.observe(head);\n      }\n    });\n    getOrCreateGauge(\n      'replica',\n      'sqlite_change_log.head_lag',\n      'Distance from the latest received commit to the SQLite change-log ' +\n        'head. The log commits before the forward, so this is zero except ' +\n        'within a transaction.',\n    ).addCallback(result => {\n      const lag = watermarkDistance(this.#receivedHead, this.#sqliteHead);\n      if (lag !== undefined) {\n        result.observe(lag);\n      }\n    });\n  }\n\n  /**\n   * Called as each message arrives, before it is written. For a sampled\n   * transaction, hashes the *received* stream and compares it with the hash the\n   * writer computes over what it *stored*.\n   */\n  messageReceived(\n    data: ChangeStreamData,\n    json: string,\n    validateHash = true,\n    storedChange = extractChangeSubstring(json, data[1].tag),\n  ): void {\n    const tag = data[1].tag;\n    if (data[0] === 'begin') {\n      if (this.#sourceHasher !== undefined) {\n        this.#invariantFailure(\n          'Received change-log begin while a source hash is already open',\n          {receivedWatermark: data[2].commitWatermark},\n        );\n      }\n      const watermark = data[2].commitWatermark;\n      this.#sourceHasher = validateHash\n        ? new ChangeLogTransactionHasher()\n        : undefined;\n      this.#sourcePos = 0;\n      this.#sourceCommitHash = undefined;\n      this.#sourceHasher?.add({\n        watermark,\n        pos: this.#sourcePos,\n        tag,\n        change: storedChange,\n        precommit: null,\n      });\n      return;\n    }\n\n    if (tag === 'rollback') {\n      this.#resetSourceHash();\n      return;\n    }\n\n    if (data[0] === 'commit') {\n      this.#receivedHead = data[2].watermark;\n    }\n\n    if (!validateHash) {\n      return;\n    }\n\n    const watermark = this.#transactionWatermark;\n    if (this.#sourceHasher === undefined || watermark === undefined) {\n      this.#invariantFailure(\n        'Received change-log message without an observed transaction',\n        {tag},\n      );\n      return;\n    }\n\n    const commitWatermark =\n      data[0] === 'commit' ? data[2].watermark : watermark;\n    this.#sourceHasher.add({\n      watermark: commitWatermark,\n      pos: ++this.#sourcePos,\n      tag,\n      change: storedChange,\n      precommit: data[0] === 'commit' ? watermark : null,\n    });\n    if (data[0] === 'commit') {\n      this.#sourceCommitHash = this.#sourceHasher.digest();\n      this.#sourceHasher = undefined;\n    }\n  }\n\n  /** Called after the message has been written to the log. */\n  messageProcessed(\n    data: ChangeStreamData,\n    commit: ChangeLogCommit | null,\n    durationMs: number | undefined,\n  ): void {\n    const tag = data[1].tag;\n    if (durationMs !== undefined) {\n      this.#messageProcessing.recordMs(durationMs, {tag, outcome: 'success'});\n    }\n\n    if (data[0] === 'begin') {\n      if (this.#transactionWatermark !== undefined) {\n        this.#invariantFailure('SQLite change-log transaction already open', {\n          openWatermark: this.#transactionWatermark,\n          receivedWatermark: data[2].commitWatermark,\n        });\n      }\n      this.#transactionWatermark = data[2].commitWatermark;\n      return;\n    }\n\n    if (tag === 'rollback') {\n      this.#recordRollback('upstream');\n      this.#transactionWatermark = undefined;\n      this.#resetSourceHash();\n      return;\n    }\n\n    if (data[0] !== 'commit') {\n      return;\n    }\n\n    const watermark = data[2].watermark;\n    if (commit !== null) {\n      this.#logCommitDuration.recordMs(commit.logCommitMs);\n    }\n    if (this.#transactionWatermark !== watermark) {\n      this.#invariantFailure(\n        'SQLite change-log commit does not match the observed begin',\n        {openWatermark: this.#transactionWatermark, commitWatermark: watermark},\n      );\n    }\n    if (commit === null) {\n      this.#invariantFailure(\n        'SQLite change-log commit result is missing writer statistics',\n        {commitWatermark: watermark},\n      );\n      this.#recordUnpaired(watermark, 'missing-sqlite-hash');\n    } else {\n      if (commit.watermark !== watermark) {\n        this.#invariantFailure(\n          'SQLite change-log commit result has an unexpected watermark',\n          {commitWatermark: watermark, resultWatermark: commit.watermark},\n        );\n      }\n      this.#rows += commit.stats.rows;\n      this.#estimatedBytes += commit.stats.estimatedBytes;\n      this.#transactionRows.record(commit.stats.rows);\n      if (\n        this.#sourceCommitHash !== undefined ||\n        commit.stats.hash !== undefined\n      ) {\n        this.#compareHashes(\n          watermark,\n          this.#sourceCommitHash,\n          commit.stats.hash,\n        );\n      }\n    }\n    if (watermark < this.#sqliteHead) {\n      this.#invariantFailure('SQLite change-log head regressed', {\n        previousHead: this.#sqliteHead,\n        commitWatermark: watermark,\n      });\n    }\n    this.#sqliteHead = watermark;\n    this.#transactionWatermark = undefined;\n    this.#resetSourceHash();\n  }\n\n  messageFailed(\n    data: ChangeStreamData,\n    error: unknown,\n    durationMs: number | undefined,\n  ): void {\n    const tag = data[1].tag;\n    if (durationMs !== undefined) {\n      this.#messageProcessing.recordMs(durationMs, {tag, outcome: 'error'});\n    }\n    if (data[0] === 'commit' && this.#sourceCommitHash !== undefined) {\n      // No commit duration here: a failed commit produces no statistics, so\n      // there is nothing to attribute. The attempt is timed by\n      // `message_processing_duration{tag=\"commit\",outcome=\"error\"}` above.\n      this.#recordUnpaired(data[2].watermark, 'sqlite-commit-failed');\n    }\n    if (\n      error instanceof Error &&\n      error.name === 'ChangeLogStreamInvariantError'\n    ) {\n      this.#invariantFailure(error.message);\n    }\n    if (this.#transactionWatermark !== undefined || data[0] === 'begin') {\n      this.#recordRollback('processing-error');\n    }\n    this.#transactionWatermark = undefined;\n    this.#resetSourceHash();\n  }\n\n  /**\n   * A committed transaction folded schema changes into the cookie jar. Reported\n   * separately from {@link messageProcessed} because it costs a read of the\n   * cookie tables, which is only worth taking when they actually moved.\n   */\n  cookiesMutated(ops: readonly CookieOpTag[], rows: CookieRowCounts): void {\n    for (const op of ops) {\n      this.#cookieMutations++;\n      this.#cookieMutationCounter.add(1, {op});\n    }\n    this.#cookieRows = rows;\n  }\n\n  /**\n   * A missed truncate-above surfaces as a constraint violation on the writer's\n   * plain `INSERT`, which the fail-soft policy would otherwise absorb quietly.\n   * Classifying it as an invariant failure is what keeps a reconciliation bug\n   * from looking like a lost cache.\n   */\n  invariantFailure(message: string, details?: Record<string, unknown>): void {\n    this.#invariantFailure(message, details);\n  }\n\n  /** The source interrupted the stream mid-transaction. */\n  abort(): void {\n    if (this.#transactionWatermark !== undefined) {\n      this.#recordRollback('source-interruption');\n      this.#transactionWatermark = undefined;\n    }\n    this.#resetSourceHash();\n  }\n\n  /** Reconciliation moved the head, so the observer's totals are restated. */\n  reconciled(info: SQLiteChangeLogInfo): void {\n    this.#receivedHead = info.headWatermark;\n    this.#sqliteHead = info.headWatermark;\n    this.#rows = info.rows;\n    this.#estimatedBytes = info.estimatedBytes;\n    this.#cookieRows = info.cookieRows;\n    this.#transactionWatermark = undefined;\n    this.#resetSourceHash();\n  }\n\n  state(): SQLiteChangeLogObservabilityState {\n    return {\n      receivedHead: this.#receivedHead,\n      sqliteHead: this.#sqliteHead,\n      headLag: watermarkDistance(this.#receivedHead, this.#sqliteHead),\n      rows: this.#rows,\n      estimatedBytes: this.#estimatedBytes,\n      cookieRows: this.#cookieRows,\n      cookieMutations: this.#cookieMutations,\n      rollbacks: this.#rollbacks,\n      invariantFailures: this.#invariantFailures,\n      hashMatches: this.#hashMatches,\n      hashMismatches: this.#hashMismatches,\n      hashUnpaired: this.#hashUnpaired,\n    };\n  }\n\n  #recordRollback(\n    reason: 'upstream' | 'processing-error' | 'source-interruption',\n  ) {\n    this.#rollbacks++;\n    this.#rollbackCounter.add(1, {reason});\n  }\n\n  #invariantFailure(message: string, details?: Record<string, unknown>) {\n    this.#invariantFailures++;\n    this.#invariantFailureCounter.add(1);\n    this.#lc.error?.(message, details);\n  }\n\n  #compareHashes(\n    watermark: string,\n    sourceHash: string | undefined,\n    sqliteHash: string | undefined,\n  ): void {\n    if (sourceHash === undefined) {\n      this.#recordUnpaired(watermark, 'missing-source-hash');\n      return;\n    }\n    if (sqliteHash === undefined) {\n      this.#recordUnpaired(watermark, 'missing-sqlite-hash');\n      return;\n    }\n    if (sourceHash === sqliteHash) {\n      this.#hashMatches++;\n      this.#hashComparisonCounter.add(1, {outcome: 'match'});\n      return;\n    }\n    this.#hashMismatches++;\n    this.#hashComparisonCounter.add(1, {outcome: 'mismatch'});\n    this.#lc.error?.('SQLite change-log transaction hash mismatch', {\n      sqliteChangeLogHashComparison: {\n        watermark,\n        sourceHash: sourceHash.slice(0, 16),\n        sqliteHash: sqliteHash.slice(0, 16),\n      },\n    });\n  }\n\n  #recordUnpaired(\n    watermark: string,\n    reason:\n      | 'missing-source-hash'\n      | 'missing-sqlite-hash'\n      | 'sqlite-commit-failed',\n  ): void {\n    this.#hashUnpaired++;\n    this.#hashUnpairedCounter.add(1, {reason});\n    this.#lc.warn?.('SQLite change-log transaction hash was not compared', {\n      sqliteChangeLogHashComparison: {watermark, reason},\n    });\n  }\n\n  #resetSourceHash(): void {\n    this.#sourceHasher = undefined;\n    this.#sourcePos = 0;\n    this.#sourceCommitHash = undefined;\n  }\n}\n\nfunction watermarkValue(watermark: string): number | undefined {\n  try {\n    const value = Number(versionFromLexi(watermark));\n    return Number.isFinite(value) ? value : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction watermarkDistance(\n  receivedHead: string,\n  sqliteHead: string,\n): number | undefined {\n  if (receivedHead <= sqliteHead) {\n    return 0;\n  }\n  try {\n    const distance =\n      versionFromLexi(receivedHead) - versionFromLexi(sqliteHead);\n    const value = Number(distance);\n    return Number.isFinite(value) ? value : undefined;\n  } catch {\n    return undefined;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"sqlite-change-log-observability.js","names":[],"sources":["../../../../../../zero-cache/src/services/replicator/sqlite-change-log-observability.ts"],"sourcesContent":["/**\n * Observability for the SQLite change log.\n *\n * Everything here now runs in the **change-streamer** process, which is where\n * the writer lives. The module stays beside the rest of the change-log code\n * under `services/replicator/` for the same reason `change-log-db.ts` and\n * `change-log-stream-writer.ts` do: moving files would obscure the topology\n * diff, and the writer's home is a property of who calls it rather than of\n * where it sits. Metric names are unchanged from 7H — only their emitting\n * process, and therefore their resource attributes, moved.\n */\n\nimport {stat} from 'node:fs/promises';\nimport type {LogContext} from '@rocicorp/logger';\nimport {unreachable} from '../../../../shared/src/asserts.ts';\nimport type {Database} from '../../../../zqlite/src/db.ts';\nimport {\n  getOrCreateCounter,\n  getOrCreateGauge,\n  getOrCreateLatencyHistogram,\n  getOrCreateValueHistogram,\n} from '../../observability/metrics.ts';\nimport {versionFromLexi} from '../../types/lexi-version.ts';\nimport type {ChangeStreamData} from '../change-source/protocol/current/downstream.ts';\nimport {extractChangeSubstring} from '../change-streamer/change-log-codec.ts';\nimport {ChangeLogTransactionHasher} from '../change-streamer/change-log-transaction-hash.ts';\nimport {\n  readCookieRowCounts,\n  type CookieOpTag,\n  type CookieRowCounts,\n} from './change-log-cookies.ts';\nimport {\n  CHANGE_LOG_STREAM_TABLE,\n  readChangeLogBounds,\n  readChangeLogMeta,\n  type ChangeLogMeta,\n  type ReconcileResult,\n} from './change-log-db.ts';\nimport type {ChangeLogStreamTransactionStats} from './change-log-stream-writer.ts';\n\n/**\n * Reports the reconciliation of the change-log database against the watermark\n * the stream connection resumes from. This runs once per stream connection, so\n * a reconnect storm is visible here as well as a restart.\n *\n * A wipe is not an error — it is how every abnormal change-log state is\n * collapsed into a correct one — but each wipe costs the retention window, so\n * every reconnecting subscriber below the head gets `too-old`. The `gap` reason\n * in particular means the log neither held the resume watermark nor could be\n * truncated to it, so a nonzero rate in steady state is an alert, not a\n * statistic.\n */\nexport function recordSQLiteChangeLogReconcile(\n  lc: LogContext,\n  result: ReconcileResult,\n): void {\n  switch (result.action) {\n    case 'truncated':\n      getOrCreateCounter(\n        'replica',\n        'sqlite_change_log.reconcile_truncated_rows',\n        'Phantom change-log rows removed at reconciliation, i.e. rows above ' +\n          'the watermark the change stream resumed from.',\n      ).add(result.rows);\n      break;\n    case 'reseeded':\n      getOrCreateCounter(\n        'replica',\n        'sqlite_change_log.reconcile_wipes',\n        'Change-log wipes at reconciliation, by reason. Each one resets the ' +\n          'retention window, so subscribers below the head get `too-old`.',\n      ).add(1, {reason: result.reason});\n      break;\n    case 'none':\n      break;\n    default:\n      unreachable(result);\n  }\n  if (result.cookiesStale) {\n    // The invariant-17 counter: after any reconcile that moved the head, the\n    // log's cookie set has to be replaced with the one that belongs to the\n    // resume watermark. A nonzero `truncated` series in steady state means\n    // phantom truncation is happening on a shard where it should not.\n    getOrCreateCounter(\n      'replica',\n      'sqlite_change_log.cookie_reseed',\n      'Change-log cookie sets invalidated at reconciliation, by the ' +\n        'reconcile action that invalidated them.',\n    ).add(1, {action: result.action});\n  }\n  lc.debug?.('SQLite change-log reconciliation', {\n    sqliteChangeLogReconcile: result,\n  });\n}\n\n/**\n * What the log says about itself. Nothing here reads the replica: after the\n * writer moved to the change-streamer, the replica's state version is a\n * consequence of this log rather than a fact about it.\n */\nexport type SQLiteChangeLogStartupInfo = ChangeLogMeta & {\n  readonly minWatermark: string;\n  readonly headWatermark: string;\n};\n\nexport type SQLiteChangeLogInfo = SQLiteChangeLogStartupInfo & {\n  readonly rows: number;\n  readonly estimatedBytes: number;\n  readonly cookieRows: CookieRowCounts;\n};\n\n/**\n * Reads the meta row and covered range. Unlike {@link getSQLiteChangeLogInfo}\n * this does not scan the log; see {@link readChangeLogBounds}.\n *\n * Call this after reconciliation, which is the only point at which the head is\n * known to be the resume watermark.\n */\nexport function getSQLiteChangeLogStartupInfo(\n  changeLog: Database,\n): SQLiteChangeLogStartupInfo {\n  const meta = readChangeLogMeta(changeLog);\n  const {minWatermark, headWatermark} = readChangeLogBounds(changeLog);\n  if (minWatermark === null || headWatermark === null) {\n    throw new Error('the SQLite change log must contain its seed transaction');\n  }\n  return {...meta, minWatermark, headWatermark};\n}\n\n/**\n * Extends {@link getSQLiteChangeLogStartupInfo} with the retained row and\n * estimated byte totals. Computing these scans the entire change-log table, so\n * only call it when the totals are consumed, i.e. when the writer (and thus the\n * observer) is enabled.\n */\nexport function getSQLiteChangeLogInfo(\n  changeLog: Database,\n): SQLiteChangeLogInfo {\n  const startup = getSQLiteChangeLogStartupInfo(changeLog);\n  const aggregate = changeLog\n    .prepare(/*sql*/ `\n      SELECT count(*) AS \"rows\",\n             coalesce(sum(\"estimatedBytes\"), 0) AS \"estimatedBytes\"\n        FROM \"${CHANGE_LOG_STREAM_TABLE}\"\n    `)\n    .get<{rows: number; estimatedBytes: number}>();\n\n  return {\n    ...startup,\n    rows: aggregate.rows,\n    estimatedBytes: aggregate.estimatedBytes,\n    cookieRows: readCookieRowCounts(changeLog),\n  };\n}\n\nexport function logSQLiteChangeLogStartup(\n  lc: LogContext,\n  file: string,\n  info: SQLiteChangeLogStartupInfo,\n): void {\n  lc.info?.('SQLite change-log startup', {\n    sqliteChangeLog: {\n      file,\n      epoch: info.epoch,\n      generation: info.generation,\n      replicaID: info.replicaID,\n      schemaVersion: info.schemaVersion,\n      seedWatermark: info.seedWatermark,\n      seededAtMs: info.seededAtMs,\n      minWatermark: info.minWatermark,\n      headWatermark: info.headWatermark,\n    },\n  });\n}\n\n/**\n * The on-disk footprint of a SQLite database: its main file plus its `-wal` and\n * `-wal2` sidecars, whichever exist. `-shm` is excluded — it is a\n * shared-memory index rather than retained bytes.\n *\n * A missing file counts as zero rather than warning. Which sidecars exist\n * depends on the journal mode, and the change-log database is absent entirely\n * until the writer creates it.\n */\nexport async function sqliteFileBytes(\n  lc: LogContext,\n  file: string,\n): Promise<number> {\n  const sizes = await Promise.all(\n    [file, `${file}-wal`, `${file}-wal2`].map(async path => {\n      try {\n        return (await stat(path)).size;\n      } catch (e) {\n        if ((e as NodeJS.ErrnoException).code !== 'ENOENT') {\n          lc.warn?.(`unable to stat ${path} for size metrics`, e);\n        }\n        return 0;\n      }\n    }),\n  );\n  return sizes.reduce((total, size) => total + size, 0);\n}\n\n/** What the writer reports back for a committed transaction. */\nexport type ChangeLogCommit = {\n  readonly watermark: string;\n  readonly stats: ChangeLogStreamTransactionStats;\n  /**\n   * Appending the commit row and committing the log's transaction. This is the\n   * cost that sits on the forward path, once per upstream transaction.\n   */\n  readonly logCommitMs: number;\n};\n\nexport type SQLiteChangeLogObservabilityState = {\n  readonly receivedHead: string;\n  readonly sqliteHead: string;\n  readonly headLag: number | undefined;\n  readonly rows: number;\n  readonly estimatedBytes: number;\n  readonly cookieRows: CookieRowCounts;\n  readonly cookieMutations: number;\n  readonly rollbacks: number;\n  readonly invariantFailures: number;\n  readonly hashMatches: number;\n  readonly hashMismatches: number;\n  readonly hashUnpaired: number;\n};\n\nconst TRANSACTION_ROW_BUCKETS = [2, 3, 5, 10, 25, 50, 100, 250, 1000, 5000];\n\n/**\n * Records writer metrics in the change-streamer process. State changes only\n * after the corresponding write succeeds, except receivedHead, which advances\n * when a commit message arrives so that transient lag behind the log is\n * observable.\n */\nexport class SQLiteChangeLogObserver {\n  readonly #lc: LogContext;\n  readonly #messageProcessing = getOrCreateLatencyHistogram(\n    'replica',\n    'sqlite_change_log.message_processing_duration',\n    'Sampled time to write a replication message to the SQLite change log.',\n  );\n  // The commit that sits on the forward path. There is no second commit to\n  // order against any more: the replica's belongs to a subscriber downstream of\n  // this loop, so `sqlite_change_log.replica_commit_duration` and the phantom\n  // window it measured are gone. Sampled failed commits are still timed by\n  // `message_processing_duration` keyed `tag=\"commit\"`.\n  readonly #logCommitDuration = getOrCreateLatencyHistogram(\n    'replica',\n    'sqlite_change_log.log_commit_duration',\n    'Time to append the commit row to the SQLite change log and commit its ' +\n      'transaction. This is on the forward path: it precedes the forward of ' +\n      \"that transaction's commit message.\",\n  );\n  readonly #transactionRows = getOrCreateValueHistogram(\n    'replica',\n    'sqlite_change_log.transaction_rows',\n    {\n      description: 'Rows stored per committed SQLite change-log transaction.',\n      unit: '{row}',\n      bucketBoundaries: TRANSACTION_ROW_BUCKETS,\n    },\n  );\n  readonly #rollbackCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.rollbacks',\n    'SQLite change-log transactions rolled back before commit.',\n  );\n  readonly #invariantFailureCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.invariant_failures',\n    'Detected SQLite change-log writer invariant failures.',\n  );\n  readonly #hashComparisonCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.hash_comparisons',\n    'Sampled ephemeral transaction hash comparisons between the received change stream and SQLite change-log writes.',\n  );\n  readonly #hashUnpairedCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.hash_unpaired',\n    'Committed change-log transactions without both ephemeral hashes available for comparison.',\n  );\n  // Near zero at steady state: cookie state only moves on schema changes.\n  readonly #cookieMutationCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.cookie_mutations',\n    'Change-log cookie mutations folded from schema changes, by operation.',\n  );\n\n  #receivedHead: string;\n  #sqliteHead: string;\n  #rows: number;\n  #estimatedBytes: number;\n  #cookieRows: CookieRowCounts;\n  #cookieMutations = 0;\n  #transactionWatermark: string | undefined;\n  #sourceHasher: ChangeLogTransactionHasher | undefined;\n  #sourcePos = 0;\n  #sourceCommitHash: string | undefined;\n  #rollbacks = 0;\n  #invariantFailures = 0;\n  #hashMatches = 0;\n  #hashMismatches = 0;\n  #hashUnpaired = 0;\n\n  constructor(lc: LogContext, info: SQLiteChangeLogInfo) {\n    this.#lc = lc.withContext('component', 'sqlite-change-log-observer');\n    // Reconciliation has just put the head at the resume watermark, which is\n    // also the point the stream is about to be received from.\n    this.#receivedHead = info.headWatermark;\n    this.#sqliteHead = info.headWatermark;\n    this.#rows = info.rows;\n    this.#estimatedBytes = info.estimatedBytes;\n    this.#cookieRows = info.cookieRows;\n\n    getOrCreateGauge(\n      'replica',\n      'sqlite_change_log.rows',\n      'Rows retained in the SQLite change log.',\n    ).addCallback(result => result.observe(this.#rows));\n    // Nonzero with no backfill in flight is a leaked cookie, i.e. a backfill\n    // that will be re-requested forever.\n    getOrCreateGauge(\n      'replica',\n      'sqlite_change_log.cookie_rows',\n      'Cookie rows retained in the SQLite change log, by cookie table.',\n    ).addCallback(result => {\n      result.observe(this.#cookieRows.tableMetadata, {table: 'tableMetadata'});\n      result.observe(this.#cookieRows.backfilling, {table: 'backfilling'});\n    });\n    getOrCreateGauge('replica', 'sqlite_change_log.retained_bytes', {\n      description:\n        'Estimated UTF-8 payload bytes retained in the SQLite change log.',\n      unit: 'By',\n    }).addCallback(result => result.observe(this.#estimatedBytes));\n    getOrCreateGauge(\n      'replica',\n      'sqlite_change_log.head',\n      'SQLite change-log head converted from its lexicographic watermark.',\n    ).addCallback(result => {\n      const head = watermarkValue(this.#sqliteHead);\n      if (head !== undefined) {\n        result.observe(head);\n      }\n    });\n    getOrCreateGauge(\n      'replica',\n      'sqlite_change_log.head_lag',\n      'Distance from the latest received commit to the SQLite change-log ' +\n        'head. The log commits before the forward, so this is zero except ' +\n        'within a transaction.',\n    ).addCallback(result => {\n      const lag = watermarkDistance(this.#receivedHead, this.#sqliteHead);\n      if (lag !== undefined) {\n        result.observe(lag);\n      }\n    });\n  }\n\n  /**\n   * Called as each message arrives, before it is written. For a sampled\n   * transaction, hashes the *received* stream and compares it with the hash the\n   * writer computes over what it *stored*.\n   */\n  messageReceived(\n    data: ChangeStreamData,\n    json: string,\n    validateHash = true,\n    storedChange = extractChangeSubstring(json, data[1].tag),\n  ): void {\n    const tag = data[1].tag;\n    if (data[0] === 'begin') {\n      if (this.#sourceHasher !== undefined) {\n        this.#invariantFailure(\n          'Received change-log begin while a source hash is already open',\n          {receivedWatermark: data[2].commitWatermark},\n        );\n      }\n      const watermark = data[2].commitWatermark;\n      this.#sourceHasher = validateHash\n        ? new ChangeLogTransactionHasher()\n        : undefined;\n      this.#sourcePos = 0;\n      this.#sourceCommitHash = undefined;\n      this.#sourceHasher?.add({\n        watermark,\n        pos: this.#sourcePos,\n        tag,\n        change: storedChange,\n        precommit: null,\n      });\n      return;\n    }\n\n    if (tag === 'rollback') {\n      this.#resetSourceHash();\n      return;\n    }\n\n    if (data[0] === 'commit') {\n      this.#receivedHead = data[2].watermark;\n    }\n\n    if (!validateHash) {\n      return;\n    }\n\n    const watermark = this.#transactionWatermark;\n    if (this.#sourceHasher === undefined || watermark === undefined) {\n      this.#invariantFailure(\n        'Received change-log message without an observed transaction',\n        {tag},\n      );\n      return;\n    }\n\n    const commitWatermark =\n      data[0] === 'commit' ? data[2].watermark : watermark;\n    this.#sourceHasher.add({\n      watermark: commitWatermark,\n      pos: ++this.#sourcePos,\n      tag,\n      change: storedChange,\n      precommit: data[0] === 'commit' ? watermark : null,\n    });\n    if (data[0] === 'commit') {\n      this.#sourceCommitHash = this.#sourceHasher.digest();\n      this.#sourceHasher = undefined;\n    }\n  }\n\n  /** Called after the message has been written to the log. */\n  messageProcessed(\n    data: ChangeStreamData,\n    commit: ChangeLogCommit | null,\n    durationMs: number | undefined,\n  ): void {\n    const tag = data[1].tag;\n    if (durationMs !== undefined) {\n      this.#messageProcessing.recordMs(durationMs, {tag, outcome: 'success'});\n    }\n\n    if (data[0] === 'begin') {\n      if (this.#transactionWatermark !== undefined) {\n        this.#invariantFailure('SQLite change-log transaction already open', {\n          openWatermark: this.#transactionWatermark,\n          receivedWatermark: data[2].commitWatermark,\n        });\n      }\n      this.#transactionWatermark = data[2].commitWatermark;\n      return;\n    }\n\n    if (tag === 'rollback') {\n      this.#recordRollback('upstream');\n      this.#transactionWatermark = undefined;\n      this.#resetSourceHash();\n      return;\n    }\n\n    if (data[0] !== 'commit') {\n      return;\n    }\n\n    const watermark = data[2].watermark;\n    if (commit !== null) {\n      this.#logCommitDuration.recordMs(commit.logCommitMs);\n    }\n    if (this.#transactionWatermark !== watermark) {\n      this.#invariantFailure(\n        'SQLite change-log commit does not match the observed begin',\n        {openWatermark: this.#transactionWatermark, commitWatermark: watermark},\n      );\n    }\n    if (commit === null) {\n      this.#invariantFailure(\n        'SQLite change-log commit result is missing writer statistics',\n        {commitWatermark: watermark},\n      );\n      this.#recordUnpaired(watermark, 'missing-sqlite-hash');\n    } else {\n      if (commit.watermark !== watermark) {\n        this.#invariantFailure(\n          'SQLite change-log commit result has an unexpected watermark',\n          {commitWatermark: watermark, resultWatermark: commit.watermark},\n        );\n      }\n      this.#rows += commit.stats.rows;\n      this.#estimatedBytes += commit.stats.estimatedBytes;\n      this.#transactionRows.record(commit.stats.rows);\n      if (\n        this.#sourceCommitHash !== undefined ||\n        commit.stats.hash !== undefined\n      ) {\n        this.#compareHashes(\n          watermark,\n          this.#sourceCommitHash,\n          commit.stats.hash,\n        );\n      }\n    }\n    if (watermark < this.#sqliteHead) {\n      this.#invariantFailure('SQLite change-log head regressed', {\n        previousHead: this.#sqliteHead,\n        commitWatermark: watermark,\n      });\n    }\n    this.#sqliteHead = watermark;\n    this.#transactionWatermark = undefined;\n    this.#resetSourceHash();\n  }\n\n  messageFailed(\n    data: ChangeStreamData,\n    error: unknown,\n    durationMs: number | undefined,\n  ): void {\n    const tag = data[1].tag;\n    if (durationMs !== undefined) {\n      this.#messageProcessing.recordMs(durationMs, {tag, outcome: 'error'});\n    }\n    if (data[0] === 'commit' && this.#sourceCommitHash !== undefined) {\n      // No commit duration here: a failed commit produces no statistics, so\n      // there is nothing to attribute. The attempt is timed by\n      // `message_processing_duration{tag=\"commit\",outcome=\"error\"}` above.\n      this.#recordUnpaired(data[2].watermark, 'sqlite-commit-failed');\n    }\n    if (\n      error instanceof Error &&\n      error.name === 'ChangeLogStreamInvariantError'\n    ) {\n      this.#invariantFailure(error.message);\n    }\n    if (this.#transactionWatermark !== undefined || data[0] === 'begin') {\n      this.#recordRollback('processing-error');\n    }\n    this.#transactionWatermark = undefined;\n    this.#resetSourceHash();\n  }\n\n  /**\n   * A committed transaction folded schema changes into the cookie jar. Reported\n   * separately from {@link messageProcessed} because it costs a read of the\n   * cookie tables, which is only worth taking when they actually moved.\n   */\n  cookiesMutated(ops: readonly CookieOpTag[], rows: CookieRowCounts): void {\n    for (const op of ops) {\n      this.#cookieMutations++;\n      this.#cookieMutationCounter.add(1, {op});\n    }\n    this.#cookieRows = rows;\n  }\n\n  /**\n   * A missed truncate-above surfaces as a constraint violation on the writer's\n   * plain `INSERT`, which the fail-soft policy would otherwise absorb quietly.\n   * Classifying it as an invariant failure is what keeps a reconciliation bug\n   * from looking like a lost cache.\n   */\n  invariantFailure(message: string, details?: Record<string, unknown>): void {\n    this.#invariantFailure(message, details);\n  }\n\n  /** The source interrupted the stream mid-transaction. */\n  abort(): void {\n    if (this.#transactionWatermark !== undefined) {\n      this.#recordRollback('source-interruption');\n      this.#transactionWatermark = undefined;\n    }\n    this.#resetSourceHash();\n  }\n\n  /** Reconciliation moved the head, so the observer's totals are restated. */\n  reconciled(info: SQLiteChangeLogInfo): void {\n    this.#receivedHead = info.headWatermark;\n    this.#sqliteHead = info.headWatermark;\n    this.#rows = info.rows;\n    this.#estimatedBytes = info.estimatedBytes;\n    this.#cookieRows = info.cookieRows;\n    this.#transactionWatermark = undefined;\n    this.#resetSourceHash();\n  }\n\n  state(): SQLiteChangeLogObservabilityState {\n    return {\n      receivedHead: this.#receivedHead,\n      sqliteHead: this.#sqliteHead,\n      headLag: watermarkDistance(this.#receivedHead, this.#sqliteHead),\n      rows: this.#rows,\n      estimatedBytes: this.#estimatedBytes,\n      cookieRows: this.#cookieRows,\n      cookieMutations: this.#cookieMutations,\n      rollbacks: this.#rollbacks,\n      invariantFailures: this.#invariantFailures,\n      hashMatches: this.#hashMatches,\n      hashMismatches: this.#hashMismatches,\n      hashUnpaired: this.#hashUnpaired,\n    };\n  }\n\n  #recordRollback(\n    reason: 'upstream' | 'processing-error' | 'source-interruption',\n  ) {\n    this.#rollbacks++;\n    this.#rollbackCounter.add(1, {reason});\n  }\n\n  #invariantFailure(message: string, details?: Record<string, unknown>) {\n    this.#invariantFailures++;\n    this.#invariantFailureCounter.add(1);\n    this.#lc.error?.(message, details);\n  }\n\n  #compareHashes(\n    watermark: string,\n    sourceHash: string | undefined,\n    sqliteHash: string | undefined,\n  ): void {\n    if (sourceHash === undefined) {\n      this.#recordUnpaired(watermark, 'missing-source-hash');\n      return;\n    }\n    if (sqliteHash === undefined) {\n      this.#recordUnpaired(watermark, 'missing-sqlite-hash');\n      return;\n    }\n    if (sourceHash === sqliteHash) {\n      this.#hashMatches++;\n      this.#hashComparisonCounter.add(1, {outcome: 'match'});\n      return;\n    }\n    this.#hashMismatches++;\n    this.#hashComparisonCounter.add(1, {outcome: 'mismatch'});\n    this.#lc.error?.('SQLite change-log transaction hash mismatch', {\n      sqliteChangeLogHashComparison: {\n        watermark,\n        sourceHash: sourceHash.slice(0, 16),\n        sqliteHash: sqliteHash.slice(0, 16),\n      },\n    });\n  }\n\n  #recordUnpaired(\n    watermark: string,\n    reason:\n      | 'missing-source-hash'\n      | 'missing-sqlite-hash'\n      | 'sqlite-commit-failed',\n  ): void {\n    this.#hashUnpaired++;\n    this.#hashUnpairedCounter.add(1, {reason});\n    this.#lc.warn?.('SQLite change-log transaction hash was not compared', {\n      sqliteChangeLogHashComparison: {watermark, reason},\n    });\n  }\n\n  #resetSourceHash(): void {\n    this.#sourceHasher = undefined;\n    this.#sourcePos = 0;\n    this.#sourceCommitHash = undefined;\n  }\n}\n\nfunction watermarkValue(watermark: string): number | undefined {\n  try {\n    const value = Number(versionFromLexi(watermark));\n    return Number.isFinite(value) ? value : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction watermarkDistance(\n  receivedHead: string,\n  sqliteHead: string,\n): number | undefined {\n  if (receivedHead <= sqliteHead) {\n    return 0;\n  }\n  try {\n    const distance =\n      versionFromLexi(receivedHead) - versionFromLexi(sqliteHead);\n    const value = Number(distance);\n    return Number.isFinite(value) ? value : undefined;\n  } catch {\n    return undefined;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,SAAgB,+BACd,IACA,QACM;CACN,QAAQ,OAAO,QAAf;EACE,KAAK;GACH,mBACE,WACA,8CACA,kHAEF,CAAC,CAAC,IAAI,OAAO,IAAI;GACjB;EACF,KAAK;GACH,mBACE,WACA,qCACA,mIAEF,CAAC,CAAC,IAAI,GAAG,EAAC,QAAQ,OAAO,OAAM,CAAC;GAChC;EACF,KAAK,QACH;EACF,SACE,YAAY,MAAM;CACtB;CACA,IAAI,OAAO,cAKT,mBACE,WACA,mCACA,sGAEF,CAAC,CAAC,IAAI,GAAG,EAAC,QAAQ,OAAO,OAAM,CAAC;CAElC,GAAG,QAAQ,oCAAoC,EAC7C,0BAA0B,OAC5B,CAAC;AACH;;;;;;;;AAyBA,SAAgB,8BACd,WAC4B;CAC5B,MAAM,OAAO,kBAAkB,SAAS;CACxC,MAAM,EAAC,cAAc,kBAAiB,oBAAoB,SAAS;CACnE,IAAI,iBAAiB,QAAQ,kBAAkB,MAC7C,MAAM,IAAI,MAAM,yDAAyD;CAE3E,OAAO;EAAC,GAAG;EAAM;EAAc;CAAa;AAC9C;;;;;;;AAQA,SAAgB,uBACd,WACqB;CACrB,MAAM,UAAU,8BAA8B,SAAS;CACvD,MAAM,YAAY,UACf,QAAgB;;;gBAGL,wBAAwB;KACnC,CAAC,CACD,IAA4C;CAE/C,OAAO;EACL,GAAG;EACH,MAAM,UAAU;EAChB,gBAAgB,UAAU;EAC1B,YAAY,oBAAoB,SAAS;CAC3C;AACF;AAEA,SAAgB,0BACd,IACA,MACA,MACM;CACN,GAAG,OAAO,6BAA6B,EACrC,iBAAiB;EACf;EACA,OAAO,KAAK;EACZ,YAAY,KAAK;EACjB,WAAW,KAAK;EAChB,eAAe,KAAK;EACpB,eAAe,KAAK;EACpB,YAAY,KAAK;EACjB,cAAc,KAAK;EACnB,eAAe,KAAK;CACtB,EACF,CAAC;AACH;;;;;;;;;;AAWA,eAAsB,gBACpB,IACA,MACiB;CAajB,QAAO,MAZa,QAAQ,IAC1B;EAAC;EAAM,GAAG,KAAK;EAAO,GAAG,KAAK;CAAM,CAAC,CAAC,IAAI,OAAM,SAAQ;EACtD,IAAI;GACF,QAAQ,MAAM,KAAK,IAAI,EAAA,CAAG;EAC5B,SAAS,GAAG;GACV,IAAK,EAA4B,SAAS,UACxC,GAAG,OAAO,kBAAkB,KAAK,oBAAoB,CAAC;GAExD,OAAO;EACT;CACF,CAAC,CACH,EAAA,CACa,QAAQ,OAAO,SAAS,QAAQ,MAAM,CAAC;AACtD;AA4BA,IAAM,0BAA0B;CAAC;CAAG;CAAG;CAAG;CAAI;CAAI;CAAI;CAAK;CAAK;CAAM;AAAI;;;;;;;AAQ1E,IAAa,0BAAb,MAAqC;CACnC;CACA,qBAA8B,4BAC5B,WACA,iDACA,uEACF;CAMA,qBAA8B,4BAC5B,WACA,yCACA,+KAGF;CACA,mBAA4B,0BAC1B,WACA,sCACA;EACE,aAAa;EACb,MAAM;EACN,kBAAkB;CACpB,CACF;CACA,mBAA4B,mBAC1B,WACA,+BACA,2DACF;CACA,2BAAoC,mBAClC,WACA,wCACA,uDACF;CACA,yBAAkC,mBAChC,WACA,sCACA,iHACF;CACA,uBAAgC,mBAC9B,WACA,mCACA,2FACF;CAEA,yBAAkC,mBAChC,WACA,sCACA,uEACF;CAEA;CACA;CACA;CACA;CACA;CACA,mBAAmB;CACnB;CACA;CACA,aAAa;CACb;CACA,aAAa;CACb,qBAAqB;CACrB,eAAe;CACf,kBAAkB;CAClB,gBAAgB;CAEhB,YAAY,IAAgB,MAA2B;EACrD,KAAK,MAAM,GAAG,YAAY,aAAa,4BAA4B;EAGnE,KAAK,gBAAgB,KAAK;EAC1B,KAAK,cAAc,KAAK;EACxB,KAAK,QAAQ,KAAK;EAClB,KAAK,kBAAkB,KAAK;EAC5B,KAAK,cAAc,KAAK;EAExB,iBACE,WACA,0BACA,yCACF,CAAC,CAAC,aAAY,WAAU,OAAO,QAAQ,KAAK,KAAK,CAAC;EAGlD,iBACE,WACA,iCACA,iEACF,CAAC,CAAC,aAAY,WAAU;GACtB,OAAO,QAAQ,KAAK,YAAY,eAAe,EAAC,OAAO,gBAAe,CAAC;GACvE,OAAO,QAAQ,KAAK,YAAY,aAAa,EAAC,OAAO,cAAa,CAAC;EACrE,CAAC;EACD,iBAAiB,WAAW,oCAAoC;GAC9D,aACE;GACF,MAAM;EACR,CAAC,CAAC,CAAC,aAAY,WAAU,OAAO,QAAQ,KAAK,eAAe,CAAC;EAC7D,iBACE,WACA,0BACA,oEACF,CAAC,CAAC,aAAY,WAAU;GACtB,MAAM,OAAO,eAAe,KAAK,WAAW;GAC5C,IAAI,SAAS,KAAA,GACX,OAAO,QAAQ,IAAI;EAEvB,CAAC;EACD,iBACE,WACA,8BACA,0JAGF,CAAC,CAAC,aAAY,WAAU;GACtB,MAAM,MAAM,kBAAkB,KAAK,eAAe,KAAK,WAAW;GAClE,IAAI,QAAQ,KAAA,GACV,OAAO,QAAQ,GAAG;EAEtB,CAAC;CACH;;;;;;CAOA,gBACE,MACA,MACA,eAAe,MACf,eAAe,uBAAuB,MAAM,KAAK,EAAE,CAAC,GAAG,GACjD;EACN,MAAM,MAAM,KAAK,EAAE,CAAC;EACpB,IAAI,KAAK,OAAO,SAAS;GACvB,IAAI,KAAK,kBAAkB,KAAA,GACzB,KAAK,kBACH,iEACA,EAAC,mBAAmB,KAAK,EAAE,CAAC,gBAAe,CAC7C;GAEF,MAAM,YAAY,KAAK,EAAE,CAAC;GAC1B,KAAK,gBAAgB,eACjB,IAAI,2BAA2B,IAC/B,KAAA;GACJ,KAAK,aAAa;GAClB,KAAK,oBAAoB,KAAA;GACzB,KAAK,eAAe,IAAI;IACtB;IACA,KAAK,KAAK;IACV;IACA,QAAQ;IACR,WAAW;GACb,CAAC;GACD;EACF;EAEA,IAAI,QAAQ,YAAY;GACtB,KAAK,iBAAiB;GACtB;EACF;EAEA,IAAI,KAAK,OAAO,UACd,KAAK,gBAAgB,KAAK,EAAE,CAAC;EAG/B,IAAI,CAAC,cACH;EAGF,MAAM,YAAY,KAAK;EACvB,IAAI,KAAK,kBAAkB,KAAA,KAAa,cAAc,KAAA,GAAW;GAC/D,KAAK,kBACH,+DACA,EAAC,IAAG,CACN;GACA;EACF;EAEA,MAAM,kBACJ,KAAK,OAAO,WAAW,KAAK,EAAE,CAAC,YAAY;EAC7C,KAAK,cAAc,IAAI;GACrB,WAAW;GACX,KAAK,EAAE,KAAK;GACZ;GACA,QAAQ;GACR,WAAW,KAAK,OAAO,WAAW,YAAY;EAChD,CAAC;EACD,IAAI,KAAK,OAAO,UAAU;GACxB,KAAK,oBAAoB,KAAK,cAAc,OAAO;GACnD,KAAK,gBAAgB,KAAA;EACvB;CACF;;CAGA,iBACE,MACA,QACA,YACM;EACN,MAAM,MAAM,KAAK,EAAE,CAAC;EACpB,IAAI,eAAe,KAAA,GACjB,KAAK,mBAAmB,SAAS,YAAY;GAAC;GAAK,SAAS;EAAS,CAAC;EAGxE,IAAI,KAAK,OAAO,SAAS;GACvB,IAAI,KAAK,0BAA0B,KAAA,GACjC,KAAK,kBAAkB,8CAA8C;IACnE,eAAe,KAAK;IACpB,mBAAmB,KAAK,EAAE,CAAC;GAC7B,CAAC;GAEH,KAAK,wBAAwB,KAAK,EAAE,CAAC;GACrC;EACF;EAEA,IAAI,QAAQ,YAAY;GACtB,KAAK,gBAAgB,UAAU;GAC/B,KAAK,wBAAwB,KAAA;GAC7B,KAAK,iBAAiB;GACtB;EACF;EAEA,IAAI,KAAK,OAAO,UACd;EAGF,MAAM,YAAY,KAAK,EAAE,CAAC;EAC1B,IAAI,WAAW,MACb,KAAK,mBAAmB,SAAS,OAAO,WAAW;EAErD,IAAI,KAAK,0BAA0B,WACjC,KAAK,kBACH,8DACA;GAAC,eAAe,KAAK;GAAuB,iBAAiB;EAAS,CACxE;EAEF,IAAI,WAAW,MAAM;GACnB,KAAK,kBACH,gEACA,EAAC,iBAAiB,UAAS,CAC7B;GACA,KAAK,gBAAgB,WAAW,qBAAqB;EACvD,OAAO;GACL,IAAI,OAAO,cAAc,WACvB,KAAK,kBACH,+DACA;IAAC,iBAAiB;IAAW,iBAAiB,OAAO;GAAS,CAChE;GAEF,KAAK,SAAS,OAAO,MAAM;GAC3B,KAAK,mBAAmB,OAAO,MAAM;GACrC,KAAK,iBAAiB,OAAO,OAAO,MAAM,IAAI;GAC9C,IACE,KAAK,sBAAsB,KAAA,KAC3B,OAAO,MAAM,SAAS,KAAA,GAEtB,KAAK,eACH,WACA,KAAK,mBACL,OAAO,MAAM,IACf;EAEJ;EACA,IAAI,YAAY,KAAK,aACnB,KAAK,kBAAkB,oCAAoC;GACzD,cAAc,KAAK;GACnB,iBAAiB;EACnB,CAAC;EAEH,KAAK,cAAc;EACnB,KAAK,wBAAwB,KAAA;EAC7B,KAAK,iBAAiB;CACxB;CAEA,cACE,MACA,OACA,YACM;EACN,MAAM,MAAM,KAAK,EAAE,CAAC;EACpB,IAAI,eAAe,KAAA,GACjB,KAAK,mBAAmB,SAAS,YAAY;GAAC;GAAK,SAAS;EAAO,CAAC;EAEtE,IAAI,KAAK,OAAO,YAAY,KAAK,sBAAsB,KAAA,GAIrD,KAAK,gBAAgB,KAAK,EAAE,CAAC,WAAW,sBAAsB;EAEhE,IACE,iBAAiB,SACjB,MAAM,SAAS,iCAEf,KAAK,kBAAkB,MAAM,OAAO;EAEtC,IAAI,KAAK,0BAA0B,KAAA,KAAa,KAAK,OAAO,SAC1D,KAAK,gBAAgB,kBAAkB;EAEzC,KAAK,wBAAwB,KAAA;EAC7B,KAAK,iBAAiB;CACxB;;;;;;CAOA,eAAe,KAA6B,MAA6B;EACvE,KAAK,MAAM,MAAM,KAAK;GACpB,KAAK;GACL,KAAK,uBAAuB,IAAI,GAAG,EAAC,GAAE,CAAC;EACzC;EACA,KAAK,cAAc;CACrB;;;;;;;CAQA,iBAAiB,SAAiB,SAAyC;EACzE,KAAK,kBAAkB,SAAS,OAAO;CACzC;;CAGA,QAAc;EACZ,IAAI,KAAK,0BAA0B,KAAA,GAAW;GAC5C,KAAK,gBAAgB,qBAAqB;GAC1C,KAAK,wBAAwB,KAAA;EAC/B;EACA,KAAK,iBAAiB;CACxB;;CAGA,WAAW,MAAiC;EAC1C,KAAK,gBAAgB,KAAK;EAC1B,KAAK,cAAc,KAAK;EACxB,KAAK,QAAQ,KAAK;EAClB,KAAK,kBAAkB,KAAK;EAC5B,KAAK,cAAc,KAAK;EACxB,KAAK,wBAAwB,KAAA;EAC7B,KAAK,iBAAiB;CACxB;CAEA,QAA2C;EACzC,OAAO;GACL,cAAc,KAAK;GACnB,YAAY,KAAK;GACjB,SAAS,kBAAkB,KAAK,eAAe,KAAK,WAAW;GAC/D,MAAM,KAAK;GACX,gBAAgB,KAAK;GACrB,YAAY,KAAK;GACjB,iBAAiB,KAAK;GACtB,WAAW,KAAK;GAChB,mBAAmB,KAAK;GACxB,aAAa,KAAK;GAClB,gBAAgB,KAAK;GACrB,cAAc,KAAK;EACrB;CACF;CAEA,gBACE,QACA;EACA,KAAK;EACL,KAAK,iBAAiB,IAAI,GAAG,EAAC,OAAM,CAAC;CACvC;CAEA,kBAAkB,SAAiB,SAAmC;EACpE,KAAK;EACL,KAAK,yBAAyB,IAAI,CAAC;EACnC,KAAK,IAAI,QAAQ,SAAS,OAAO;CACnC;CAEA,eACE,WACA,YACA,YACM;EACN,IAAI,eAAe,KAAA,GAAW;GAC5B,KAAK,gBAAgB,WAAW,qBAAqB;GACrD;EACF;EACA,IAAI,eAAe,KAAA,GAAW;GAC5B,KAAK,gBAAgB,WAAW,qBAAqB;GACrD;EACF;EACA,IAAI,eAAe,YAAY;GAC7B,KAAK;GACL,KAAK,uBAAuB,IAAI,GAAG,EAAC,SAAS,QAAO,CAAC;GACrD;EACF;EACA,KAAK;EACL,KAAK,uBAAuB,IAAI,GAAG,EAAC,SAAS,WAAU,CAAC;EACxD,KAAK,IAAI,QAAQ,+CAA+C,EAC9D,+BAA+B;GAC7B;GACA,YAAY,WAAW,MAAM,GAAG,EAAE;GAClC,YAAY,WAAW,MAAM,GAAG,EAAE;EACpC,EACF,CAAC;CACH;CAEA,gBACE,WACA,QAIM;EACN,KAAK;EACL,KAAK,qBAAqB,IAAI,GAAG,EAAC,OAAM,CAAC;EACzC,KAAK,IAAI,OAAO,uDAAuD,EACrE,+BAA+B;GAAC;GAAW;EAAM,EACnD,CAAC;CACH;CAEA,mBAAyB;EACvB,KAAK,gBAAgB,KAAA;EACrB,KAAK,aAAa;EAClB,KAAK,oBAAoB,KAAA;CAC3B;AACF;AAEA,SAAS,eAAe,WAAuC;CAC7D,IAAI;EACF,MAAM,QAAQ,OAAO,gBAAgB,SAAS,CAAC;EAC/C,OAAO,OAAO,SAAS,KAAK,IAAI,QAAQ,KAAA;CAC1C,QAAQ;EACN;CACF;AACF;AAEA,SAAS,kBACP,cACA,YACoB;CACpB,IAAI,gBAAgB,YAClB,OAAO;CAET,IAAI;EACF,MAAM,WACJ,gBAAgB,YAAY,IAAI,gBAAgB,UAAU;EAC5D,MAAM,QAAQ,OAAO,QAAQ;EAC7B,OAAO,OAAO,SAAS,KAAK,IAAI,QAAQ,KAAA;CAC1C,QAAQ;EACN;CACF;AACF"}

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

@@ -278,6 +278,6 @@ var SQLiteChangeLogPurger = class {
 	}
 };
 //#endregion
-export { SQLiteChangeLogPurger };
+export { SQLITE_CHANGE_LOG_COUNT_TRANSACTION_SQL, SQLITE_CHANGE_LOG_ELIGIBLE_COMMITS_SQL, SQLiteChangeLogPurger };
 
 //# sourceMappingURL=sqlite-change-log-purger.js.map