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

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    // 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    let instance = ColumnMetadataStore.#instances.get(db);\n    if (!instance) {\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":["#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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"}

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

@@ -43,6 +43,6 @@ export declare function getAscendingEvents(db: Database): {
 }[];
 export declare function getSubscriptionState(db: StatementRunner): SubscriptionState;
 export declare function getSubscriptionStateAndContext(db: StatementRunner): SubscriptionStateAndContext;
-export declare function updateReplicationWatermark(db: StatementRunner, watermark: string): void;
+export declare function updateReplicationWatermark(db: StatementRunner, watermark: string, writeTimeMs?: number | undefined): void;
 export declare function getReplicationState(db: StatementRunner): ReplicationState;
 //# sourceMappingURL=replication-state.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"replication-state.d.ts","sourceRoot":"","sources":["../../../../../../../zero-cache/src/services/replicator/schema/replication-state.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,CAAC,MAAM,qCAAqC,CAAC;AACzD,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,iCAAiC,CAAC;AAC9D,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,2BAA2B,CAAC;AAG/D,OAAO,EAAC,wBAAwB,EAAC,MAAM,gBAAgB,CAAC;AAGxD,OAAO,EAAC,wBAAwB,EAAC,CAAC;AAElC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAMzD,eAAO,MAAM,2BAA2B,iKAKvC,CAAC;AA0CF,QAAA,MAAM,uBAAuB;;;;EASxB,CAAC;AAEN,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,QAAA,MAAM,iCAAiC;;;;;EAclC,CAAC;AAEN,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,iCAAiC,CACzC,CAAC;AAEF,QAAA,MAAM,sBAAsB;;aAE1B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,QAAQ,EACZ,YAAY,EAAE,MAAM,EAAE,EACtB,SAAS,EAAE,MAAM,EACjB,kBAAkB,GAAE,UAAe,EACnC,YAAY,UAAO,QAoBpB;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,QAAQ,QAExD;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,QAM5D;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,QAAQ;;;IAY9C;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,eAAe,GAAG,iBAAiB,CAQ3E;AAED,wBAAgB,8BAA8B,CAC5C,EAAE,EAAE,eAAe,GAClB,2BAA2B,CAS7B;AAED,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,eAAe,EACnB,SAAS,EAAE,MAAM,QAQlB;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,eAAe,GAAG,gBAAgB,CAGzE"}
+{"version":3,"file":"replication-state.d.ts","sourceRoot":"","sources":["../../../../../../../zero-cache/src/services/replicator/schema/replication-state.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,CAAC,MAAM,qCAAqC,CAAC;AACzD,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,iCAAiC,CAAC;AAC9D,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,2BAA2B,CAAC;AAI/D,OAAO,EAAC,wBAAwB,EAAC,MAAM,gBAAgB,CAAC;AAGxD,OAAO,EAAC,wBAAwB,EAAC,CAAC;AAElC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAMzD,eAAO,MAAM,2BAA2B,iKAKvC,CAAC;AA2CF,QAAA,MAAM,uBAAuB;;;;EASxB,CAAC;AAEN,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,QAAA,MAAM,iCAAiC;;;;;EAclC,CAAC;AAEN,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,iCAAiC,CACzC,CAAC;AAEF,QAAA,MAAM,sBAAsB;;aAE1B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,QAAQ,EACZ,YAAY,EAAE,MAAM,EAAE,EACtB,SAAS,EAAE,MAAM,EACjB,kBAAkB,GAAE,UAAe,EACnC,YAAY,UAAO,QAoBpB;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,QAAQ,QAExD;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,QAM5D;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,QAAQ;;;IAY9C;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,eAAe,GAAG,iBAAiB,CAQ3E;AAED,wBAAgB,8BAA8B,CAC5C,EAAE,EAAE,eAAe,GAClB,2BAA2B,CAS7B;AAED,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,eAAe,EACnB,SAAS,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,QAkBjC;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,eAAe,GAAG,gBAAgB,CAGzE"}

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

@@ -3,6 +3,7 @@ import { jsonObjectSchema, stringify } from "../../../../../shared/src/bigint-js
 import "./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";
 import { CREATE_CHANGELOG_SCHEMA } from "./change-log.js";
 //#region ../zero-cache/src/services/replicator/schema/replication-state.ts
 /**
@@ -17,7 +18,7 @@ var CREATE_RUNTIME_EVENTS_TABLE = `
     timestamp TEXT NOT NULL DEFAULT (current_timestamp)
   );
 `;
-var CREATE_REPLICATION_STATE_SCHEMA = "\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  CREATE TABLE \"_zero.replicationState\" (\n    stateVersion TEXT NOT NULL,\n    writeTimeMs INTEGER,\n    lock INTEGER PRIMARY KEY DEFAULT 1 CHECK (lock=1)\n  );\n  " + CREATE_CHANGELOG_SCHEMA + CREATE_RUNTIME_EVENTS_TABLE + CREATE_COLUMN_METADATA_TABLE + CREATE_TABLE_METADATA_TABLE;
+var CREATE_REPLICATION_STATE_SCHEMA = "\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  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  " + CREATE_CHANGELOG_SCHEMA + CREATE_RUNTIME_EVENTS_TABLE + CREATE_COLUMN_METADATA_TABLE + CREATE_TABLE_METADATA_TABLE + CREATE_BACKFILLING_TABLE;
 var stringArray = valita_exports.array(valita_exports.string());
 var subscriptionStateSchema = valita_exports.object({
 	replicaVersion: valita_exports.string(),
@@ -88,10 +89,13 @@ function getSubscriptionStateAndContext(db) {
         ON c.lock = s.lock
     `), subscriptionStateAndContextSchema);
 }
-function updateReplicationWatermark(db, watermark) {
-	db.run(`
-    UPDATE "_zero.replicationState" 
-      SET stateVersion=?, writeTimeMs=unixepoch('subsec') * 1000`, watermark);
+function updateReplicationWatermark(db, watermark, writeTimeMs) {
+	if (writeTimeMs === void 0) db.run(`
+      UPDATE "_zero.replicationState"
+        SET stateVersion=?, writeTimeMs=unixepoch('subsec') * 1000`, watermark);
+	else db.run(`
+      UPDATE "_zero.replicationState"
+        SET stateVersion=?, writeTimeMs=?`, watermark, writeTimeMs);
 }
 function getReplicationState(db) {
 	return parse(db.get(`SELECT stateVersion FROM "_zero.replicationState"`), replicationStateSchema);

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_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,\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\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) {\n  db.run(\n    /*sql*/ `\n    UPDATE \"_zero.replicationState\" \n      SET stateVersion=?, writeTimeMs=unixepoch('subsec') * 1000`,\n    watermark,\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":";;;;;;;;;;;;;AA4BA,IAAa,8BAA8B;;;;;;AAO3C,IAAM,kCAYI,4YAqBR,0BACA,8BACA,+BACA;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;CACA,GAAG,IACO;;mEAGR,SACF;AACF;AAEA,SAAgB,oBAAoB,IAAuC;CAEzE,OAAO,MADQ,GAAG,IAAI,mDACP,GAAQ,sBAAsB;AAC/C"}
+{"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"}

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

@@ -0,0 +1,131 @@
+/**
+ * Observability for the SQLite change log.
+ *
+ * Everything here now runs in the **change-streamer** process, which is where
+ * the writer lives. The module stays beside the rest of the change-log code
+ * under `services/replicator/` for the same reason `change-log-db.ts` and
+ * `change-log-stream-writer.ts` do: moving files would obscure the topology
+ * diff, and the writer's home is a property of who calls it rather than of
+ * where it sits. Metric names are unchanged from 7H — only their emitting
+ * process, and therefore their resource attributes, moved.
+ */
+import type { LogContext } from '@rocicorp/logger';
+import type { Database } from '../../../../zqlite/src/db.ts';
+import type { ChangeStreamData } from '../change-source/protocol/current/downstream.ts';
+import { type CookieOpTag, type CookieRowCounts } from './change-log-cookies.ts';
+import { type ChangeLogMeta, type ReconcileResult } from './change-log-db.ts';
+import type { ChangeLogStreamTransactionStats } from './change-log-stream-writer.ts';
+/**
+ * Reports the reconciliation of the change-log database against the watermark
+ * the stream connection resumes from. This runs once per stream connection, so
+ * a reconnect storm is visible here as well as a restart.
+ *
+ * A wipe is not an error — it is how every abnormal change-log state is
+ * collapsed into a correct one — but each wipe costs the retention window, so
+ * every reconnecting subscriber below the head gets `too-old`. The `gap` reason
+ * in particular means the log neither held the resume watermark nor could be
+ * truncated to it, so a nonzero rate in steady state is an alert, not a
+ * statistic.
+ */
+export declare function recordSQLiteChangeLogReconcile(lc: LogContext, result: ReconcileResult): void;
+/**
+ * What the log says about itself. Nothing here reads the replica: after the
+ * writer moved to the change-streamer, the replica's state version is a
+ * consequence of this log rather than a fact about it.
+ */
+export type SQLiteChangeLogStartupInfo = ChangeLogMeta & {
+    readonly headWatermark: string;
+};
+export type SQLiteChangeLogInfo = SQLiteChangeLogStartupInfo & {
+    readonly rows: number;
+    readonly estimatedBytes: number;
+    readonly cookieRows: CookieRowCounts;
+};
+/**
+ * Reads the meta row and the head. The head is an index-optimized `max()`, so
+ * unlike {@link getSQLiteChangeLogInfo} this does not scan the log.
+ *
+ * Call this after reconciliation, which is the only point at which the head is
+ * known to be the resume watermark.
+ */
+export declare function getSQLiteChangeLogStartupInfo(changeLog: Database): SQLiteChangeLogStartupInfo;
+/**
+ * Extends {@link getSQLiteChangeLogStartupInfo} with the retained row and
+ * estimated byte totals. Computing these scans the entire change-log table, so
+ * only call it when the totals are consumed, i.e. when the writer (and thus the
+ * observer) is enabled.
+ */
+export declare function getSQLiteChangeLogInfo(changeLog: Database): SQLiteChangeLogInfo;
+export declare function logSQLiteChangeLogStartup(lc: LogContext, file: string, info: SQLiteChangeLogStartupInfo): void;
+/**
+ * The on-disk footprint of a SQLite database: its main file plus its `-wal` and
+ * `-wal2` sidecars, whichever exist. `-shm` is excluded — it is a
+ * shared-memory index rather than retained bytes.
+ *
+ * A missing file counts as zero rather than warning. Which sidecars exist
+ * depends on the journal mode, and the change-log database is absent entirely
+ * until the writer creates it.
+ */
+export declare function sqliteFileBytes(lc: LogContext, file: string): Promise<number>;
+/** What the writer reports back for a committed transaction. */
+export type ChangeLogCommit = {
+    readonly watermark: string;
+    readonly stats: ChangeLogStreamTransactionStats;
+    /**
+     * Appending the commit row and committing the log's transaction. This is the
+     * cost that sits on the forward path, once per upstream transaction.
+     */
+    readonly logCommitMs: number;
+};
+export type SQLiteChangeLogObservabilityState = {
+    readonly receivedHead: string;
+    readonly sqliteHead: string;
+    readonly headLag: number | undefined;
+    readonly rows: number;
+    readonly estimatedBytes: number;
+    readonly cookieRows: CookieRowCounts;
+    readonly cookieMutations: number;
+    readonly rollbacks: number;
+    readonly invariantFailures: number;
+    readonly hashMatches: number;
+    readonly hashMismatches: number;
+    readonly hashUnpaired: number;
+};
+/**
+ * Records writer metrics in the change-streamer process. State changes only
+ * after the corresponding write succeeds, except receivedHead, which advances
+ * when a commit message arrives so that transient lag behind the log is
+ * observable.
+ */
+export declare class SQLiteChangeLogObserver {
+    #private;
+    constructor(lc: LogContext, info: SQLiteChangeLogInfo);
+    /**
+     * Called as each message arrives, before it is written. Hashes the *received*
+     * stream, which is compared against the hash the writer computes over what it
+     * *stored*.
+     */
+    messageReceived(data: ChangeStreamData, json: string): void;
+    /** Called after the message has been written to the log. */
+    messageProcessed(data: ChangeStreamData, commit: ChangeLogCommit | null, durationMs: number): void;
+    messageFailed(data: ChangeStreamData, error: unknown, durationMs: number): void;
+    /**
+     * A committed transaction folded schema changes into the cookie jar. Reported
+     * separately from {@link messageProcessed} because it costs a read of the
+     * cookie tables, which is only worth taking when they actually moved.
+     */
+    cookiesMutated(ops: readonly CookieOpTag[], rows: CookieRowCounts): void;
+    /**
+     * A missed truncate-above surfaces as a constraint violation on the writer's
+     * plain `INSERT`, which the fail-soft policy would otherwise absorb quietly.
+     * Classifying it as an invariant failure is what keeps a reconciliation bug
+     * from looking like a lost cache.
+     */
+    invariantFailure(message: string, details?: Record<string, unknown>): void;
+    /** The source interrupted the stream mid-transaction. */
+    abort(): void;
+    /** Reconciliation moved the head, so the observer's totals are restated. */
+    reconciled(info: SQLiteChangeLogInfo): void;
+    state(): SQLiteChangeLogObservabilityState;
+}
+//# sourceMappingURL=sqlite-change-log-observability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-change-log-observability.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/replicator/sqlite-change-log-observability.ts"],"names":[],"mappings":"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"}