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

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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"}

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

@@ -0,0 +1,413 @@
+import { unreachable } from "../../../../shared/src/asserts.js";
+import { getOrCreateCounter, getOrCreateGauge, getOrCreateLatencyHistogram, getOrCreateValueHistogram } from "../../observability/metrics.js";
+import { readCookieRowCounts } from "./change-log-cookies.js";
+import { versionFromLexi } from "../../types/lexi-version.js";
+import { CHANGE_LOG_STREAM_TABLE, readChangeLogHead, readChangeLogMeta } from "./change-log-db.js";
+import { extractChangeSubstring } from "../change-streamer/change-log-codec.js";
+import { ChangeLogTransactionHasher } from "../change-streamer/change-log-transaction-hash.js";
+import { stat } from "node:fs/promises";
+//#region ../zero-cache/src/services/replicator/sqlite-change-log-observability.ts
+/**
+* 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.
+*/
+/**
+* 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.
+*/
+function recordSQLiteChangeLogReconcile(lc, result) {
+	switch (result.action) {
+		case "truncated":
+			getOrCreateCounter("replica", "sqlite_change_log.reconcile_truncated_rows", "Phantom change-log rows removed at reconciliation, i.e. rows above the watermark the change stream resumed from.").add(result.rows);
+			break;
+		case "reseeded":
+			getOrCreateCounter("replica", "sqlite_change_log.reconcile_wipes", "Change-log wipes at reconciliation, by reason. Each one resets the retention window, so subscribers below the head get `too-old`.").add(1, { reason: result.reason });
+			break;
+		case "none": break;
+		default: unreachable(result);
+	}
+	if (result.cookiesStale) getOrCreateCounter("replica", "sqlite_change_log.cookie_reseed", "Change-log cookie sets invalidated at reconciliation, by the reconcile action that invalidated them.").add(1, { action: result.action });
+	lc.debug?.("SQLite change-log reconciliation", { sqliteChangeLogReconcile: result });
+}
+/**
+* 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.
+*/
+function getSQLiteChangeLogStartupInfo(changeLog) {
+	const meta = readChangeLogMeta(changeLog);
+	const head = readChangeLogHead(changeLog);
+	if (head === null) throw new Error("the SQLite change log must contain its seed transaction");
+	return {
+		...meta,
+		headWatermark: head
+	};
+}
+/**
+* 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.
+*/
+function getSQLiteChangeLogInfo(changeLog) {
+	const startup = getSQLiteChangeLogStartupInfo(changeLog);
+	const aggregate = changeLog.prepare(`
+      SELECT count(*) AS "rows",
+             coalesce(sum("estimatedBytes"), 0) AS "estimatedBytes"
+        FROM "${CHANGE_LOG_STREAM_TABLE}"
+    `).get();
+	return {
+		...startup,
+		rows: aggregate.rows,
+		estimatedBytes: aggregate.estimatedBytes,
+		cookieRows: readCookieRowCounts(changeLog)
+	};
+}
+function logSQLiteChangeLogStartup(lc, file, info) {
+	lc.info?.("SQLite change-log startup", { sqliteChangeLog: {
+		file,
+		epoch: info.epoch,
+		generation: info.generation,
+		replicaID: info.replicaID,
+		schemaVersion: info.schemaVersion,
+		seedWatermark: info.seedWatermark,
+		seededAtMs: info.seededAtMs,
+		headWatermark: info.headWatermark
+	} });
+}
+/**
+* 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.
+*/
+async function sqliteFileBytes(lc, file) {
+	return (await Promise.all([
+		file,
+		`${file}-wal`,
+		`${file}-wal2`
+	].map(async (path) => {
+		try {
+			return (await stat(path)).size;
+		} catch (e) {
+			if (e.code !== "ENOENT") lc.warn?.(`unable to stat ${path} for size metrics`, e);
+			return 0;
+		}
+	}))).reduce((total, size) => total + size, 0);
+}
+var TRANSACTION_ROW_BUCKETS = [
+	2,
+	3,
+	5,
+	10,
+	25,
+	50,
+	100,
+	250,
+	1e3,
+	5e3
+];
+/**
+* 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.
+*/
+var SQLiteChangeLogObserver = class {
+	#lc;
+	#messageProcessing = getOrCreateLatencyHistogram("replica", "sqlite_change_log.message_processing_duration", "Time to write a replication message to the SQLite change log.");
+	#logCommitDuration = getOrCreateLatencyHistogram("replica", "sqlite_change_log.log_commit_duration", "Time to append the commit row to the SQLite change log and commit its transaction. This is on the forward path: it precedes the forward of that transaction's commit message.");
+	#transactionRows = getOrCreateValueHistogram("replica", "sqlite_change_log.transaction_rows", {
+		description: "Rows stored per committed SQLite change-log transaction.",
+		unit: "{row}",
+		bucketBoundaries: TRANSACTION_ROW_BUCKETS
+	});
+	#rollbackCounter = getOrCreateCounter("replica", "sqlite_change_log.rollbacks", "SQLite change-log transactions rolled back before commit.");
+	#invariantFailureCounter = getOrCreateCounter("replica", "sqlite_change_log.invariant_failures", "Detected SQLite change-log writer invariant failures.");
+	#hashComparisonCounter = getOrCreateCounter("replica", "sqlite_change_log.hash_comparisons", "Ephemeral transaction hash comparisons between the received change stream and SQLite change-log writes.");
+	#hashUnpairedCounter = getOrCreateCounter("replica", "sqlite_change_log.hash_unpaired", "Committed change-log transactions without both ephemeral hashes available for comparison.");
+	#cookieMutationCounter = getOrCreateCounter("replica", "sqlite_change_log.cookie_mutations", "Change-log cookie mutations folded from schema changes, by operation.");
+	#receivedHead;
+	#sqliteHead;
+	#rows;
+	#estimatedBytes;
+	#cookieRows;
+	#cookieMutations = 0;
+	#transactionWatermark;
+	#sourceHasher;
+	#sourcePos = 0;
+	#sourceCommitHash;
+	#rollbacks = 0;
+	#invariantFailures = 0;
+	#hashMatches = 0;
+	#hashMismatches = 0;
+	#hashUnpaired = 0;
+	constructor(lc, info) {
+		this.#lc = lc.withContext("component", "sqlite-change-log-observer");
+		this.#receivedHead = info.headWatermark;
+		this.#sqliteHead = info.headWatermark;
+		this.#rows = info.rows;
+		this.#estimatedBytes = info.estimatedBytes;
+		this.#cookieRows = info.cookieRows;
+		getOrCreateGauge("replica", "sqlite_change_log.rows", "Rows retained in the SQLite change log.").addCallback((result) => result.observe(this.#rows));
+		getOrCreateGauge("replica", "sqlite_change_log.cookie_rows", "Cookie rows retained in the SQLite change log, by cookie table.").addCallback((result) => {
+			result.observe(this.#cookieRows.tableMetadata, { table: "tableMetadata" });
+			result.observe(this.#cookieRows.backfilling, { table: "backfilling" });
+		});
+		getOrCreateGauge("replica", "sqlite_change_log.retained_bytes", {
+			description: "Estimated UTF-8 payload bytes retained in the SQLite change log.",
+			unit: "By"
+		}).addCallback((result) => result.observe(this.#estimatedBytes));
+		getOrCreateGauge("replica", "sqlite_change_log.head", "SQLite change-log head converted from its lexicographic watermark.").addCallback((result) => {
+			const head = watermarkValue(this.#sqliteHead);
+			if (head !== void 0) result.observe(head);
+		});
+		getOrCreateGauge("replica", "sqlite_change_log.head_lag", "Distance from the latest received commit to the SQLite change-log head. The log commits before the forward, so this is zero except within a transaction.").addCallback((result) => {
+			const lag = watermarkDistance(this.#receivedHead, this.#sqliteHead);
+			if (lag !== void 0) result.observe(lag);
+		});
+	}
+	/**
+	* 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, json) {
+		const tag = data[1].tag;
+		if (data[0] === "begin") {
+			if (this.#sourceHasher !== void 0) this.#invariantFailure("Received change-log begin while a source hash is already open", { receivedWatermark: data[2].commitWatermark });
+			const watermark = data[2].commitWatermark;
+			this.#sourceHasher = new ChangeLogTransactionHasher();
+			this.#sourcePos = 0;
+			this.#sourceCommitHash = void 0;
+			this.#sourceHasher.add({
+				watermark,
+				pos: this.#sourcePos,
+				tag,
+				change: extractChangeSubstring(json, tag),
+				precommit: null
+			});
+			return;
+		}
+		if (tag === "rollback") {
+			this.#resetSourceHash();
+			return;
+		}
+		if (data[0] === "commit") this.#receivedHead = data[2].watermark;
+		const watermark = this.#transactionWatermark;
+		if (this.#sourceHasher === void 0 || watermark === void 0) {
+			this.#invariantFailure("Received change-log message without an observed transaction", { tag });
+			return;
+		}
+		const commitWatermark = data[0] === "commit" ? data[2].watermark : watermark;
+		this.#sourceHasher.add({
+			watermark: commitWatermark,
+			pos: ++this.#sourcePos,
+			tag,
+			change: extractChangeSubstring(json, tag),
+			precommit: data[0] === "commit" ? watermark : null
+		});
+		if (data[0] === "commit") {
+			this.#sourceCommitHash = this.#sourceHasher.digest();
+			this.#sourceHasher = void 0;
+		}
+	}
+	/** Called after the message has been written to the log. */
+	messageProcessed(data, commit, durationMs) {
+		const tag = data[1].tag;
+		this.#messageProcessing.recordMs(durationMs, {
+			tag,
+			outcome: "success"
+		});
+		if (data[0] === "begin") {
+			if (this.#transactionWatermark !== void 0) this.#invariantFailure("SQLite change-log transaction already open", {
+				openWatermark: this.#transactionWatermark,
+				receivedWatermark: data[2].commitWatermark
+			});
+			this.#transactionWatermark = data[2].commitWatermark;
+			return;
+		}
+		if (tag === "rollback") {
+			this.#recordRollback("upstream");
+			this.#transactionWatermark = void 0;
+			this.#resetSourceHash();
+			return;
+		}
+		if (data[0] !== "commit") return;
+		const watermark = data[2].watermark;
+		if (commit !== null) this.#logCommitDuration.recordMs(commit.logCommitMs);
+		if (this.#transactionWatermark !== watermark) this.#invariantFailure("SQLite change-log commit does not match the observed begin", {
+			openWatermark: this.#transactionWatermark,
+			commitWatermark: watermark
+		});
+		if (commit === null) {
+			this.#invariantFailure("SQLite change-log commit result is missing writer statistics", { commitWatermark: watermark });
+			this.#recordUnpaired(watermark, "missing-sqlite-hash");
+		} else {
+			if (commit.watermark !== watermark) this.#invariantFailure("SQLite change-log commit result has an unexpected watermark", {
+				commitWatermark: watermark,
+				resultWatermark: commit.watermark
+			});
+			this.#rows += commit.stats.rows;
+			this.#estimatedBytes += commit.stats.estimatedBytes;
+			this.#transactionRows.record(commit.stats.rows);
+			this.#compareHashes(watermark, this.#sourceCommitHash, commit.stats.hash);
+		}
+		if (watermark < this.#sqliteHead) this.#invariantFailure("SQLite change-log head regressed", {
+			previousHead: this.#sqliteHead,
+			commitWatermark: watermark
+		});
+		this.#sqliteHead = watermark;
+		this.#transactionWatermark = void 0;
+		this.#resetSourceHash();
+	}
+	messageFailed(data, error, durationMs) {
+		const tag = data[1].tag;
+		this.#messageProcessing.recordMs(durationMs, {
+			tag,
+			outcome: "error"
+		});
+		if (data[0] === "commit") this.#recordUnpaired(data[2].watermark, "sqlite-commit-failed");
+		if (error instanceof Error && error.name === "ChangeLogStreamInvariantError") this.#invariantFailure(error.message);
+		if (this.#transactionWatermark !== void 0 || data[0] === "begin") this.#recordRollback("processing-error");
+		this.#transactionWatermark = void 0;
+		this.#resetSourceHash();
+	}
+	/**
+	* 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, rows) {
+		for (const op of ops) {
+			this.#cookieMutations++;
+			this.#cookieMutationCounter.add(1, { op });
+		}
+		this.#cookieRows = rows;
+	}
+	/**
+	* 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, details) {
+		this.#invariantFailure(message, details);
+	}
+	/** The source interrupted the stream mid-transaction. */
+	abort() {
+		if (this.#transactionWatermark !== void 0) {
+			this.#recordRollback("source-interruption");
+			this.#transactionWatermark = void 0;
+		}
+		this.#resetSourceHash();
+	}
+	/** Reconciliation moved the head, so the observer's totals are restated. */
+	reconciled(info) {
+		this.#receivedHead = info.headWatermark;
+		this.#sqliteHead = info.headWatermark;
+		this.#rows = info.rows;
+		this.#estimatedBytes = info.estimatedBytes;
+		this.#cookieRows = info.cookieRows;
+		this.#transactionWatermark = void 0;
+		this.#resetSourceHash();
+	}
+	state() {
+		return {
+			receivedHead: this.#receivedHead,
+			sqliteHead: this.#sqliteHead,
+			headLag: watermarkDistance(this.#receivedHead, this.#sqliteHead),
+			rows: this.#rows,
+			estimatedBytes: this.#estimatedBytes,
+			cookieRows: this.#cookieRows,
+			cookieMutations: this.#cookieMutations,
+			rollbacks: this.#rollbacks,
+			invariantFailures: this.#invariantFailures,
+			hashMatches: this.#hashMatches,
+			hashMismatches: this.#hashMismatches,
+			hashUnpaired: this.#hashUnpaired
+		};
+	}
+	#recordRollback(reason) {
+		this.#rollbacks++;
+		this.#rollbackCounter.add(1, { reason });
+	}
+	#invariantFailure(message, details) {
+		this.#invariantFailures++;
+		this.#invariantFailureCounter.add(1);
+		this.#lc.error?.(message, details);
+	}
+	#compareHashes(watermark, sourceHash, sqliteHash) {
+		if (sourceHash === void 0) {
+			this.#recordUnpaired(watermark, "missing-source-hash");
+			return;
+		}
+		if (sourceHash === sqliteHash) {
+			this.#hashMatches++;
+			this.#hashComparisonCounter.add(1, { outcome: "match" });
+			return;
+		}
+		this.#hashMismatches++;
+		this.#hashComparisonCounter.add(1, { outcome: "mismatch" });
+		this.#lc.error?.("SQLite change-log transaction hash mismatch", { sqliteChangeLogHashComparison: {
+			watermark,
+			sourceHash: sourceHash.slice(0, 16),
+			sqliteHash: sqliteHash.slice(0, 16)
+		} });
+	}
+	#recordUnpaired(watermark, reason) {
+		this.#hashUnpaired++;
+		this.#hashUnpairedCounter.add(1, { reason });
+		this.#lc.warn?.("SQLite change-log transaction hash was not compared", { sqliteChangeLogHashComparison: {
+			watermark,
+			reason
+		} });
+	}
+	#resetSourceHash() {
+		this.#sourceHasher = void 0;
+		this.#sourcePos = 0;
+		this.#sourceCommitHash = void 0;
+	}
+};
+function watermarkValue(watermark) {
+	try {
+		const value = Number(versionFromLexi(watermark));
+		return Number.isFinite(value) ? value : void 0;
+	} catch {
+		return;
+	}
+}
+function watermarkDistance(receivedHead, sqliteHead) {
+	if (receivedHead <= sqliteHead) return 0;
+	try {
+		const distance = versionFromLexi(receivedHead) - versionFromLexi(sqliteHead);
+		const value = Number(distance);
+		return Number.isFinite(value) ? value : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { SQLiteChangeLogObserver, getSQLiteChangeLogInfo, logSQLiteChangeLogStartup, recordSQLiteChangeLogReconcile, sqliteFileBytes };
+
+//# sourceMappingURL=sqlite-change-log-observability.js.map