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

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

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-change-log-observability.js","names":["#lc","#messageProcessing","#logCommitDuration","#transactionRows","#rollbackCounter","#invariantFailureCounter","#hashComparisonCounter","#hashUnpairedCounter","#cookieMutationCounter","#receivedHead","#sqliteHead","#rows","#estimatedBytes","#cookieRows","#sourceHasher","#invariantFailure","#sourcePos","#sourceCommitHash","#resetSourceHash","#transactionWatermark","#recordRollback","#recordUnpaired","#compareHashes","#cookieMutations","#rollbacks","#invariantFailures","#hashMatches","#hashMismatches","#hashUnpaired"],"sources":["../../../../../../zero-cache/src/services/replicator/sqlite-change-log-observability.ts"],"sourcesContent":["/**\n * Observability for the SQLite change log.\n *\n * Everything here now runs in the **change-streamer** process, which is where\n * the writer lives. The module stays beside the rest of the change-log code\n * under `services/replicator/` for the same reason `change-log-db.ts` and\n * `change-log-stream-writer.ts` do: moving files would obscure the topology\n * diff, and the writer's home is a property of who calls it rather than of\n * where it sits. Metric names are unchanged from 7H — only their emitting\n * process, and therefore their resource attributes, moved.\n */\n\nimport {stat} from 'node:fs/promises';\nimport type {LogContext} from '@rocicorp/logger';\nimport {unreachable} from '../../../../shared/src/asserts.ts';\nimport type {Database} from '../../../../zqlite/src/db.ts';\nimport {\n  getOrCreateCounter,\n  getOrCreateGauge,\n  getOrCreateLatencyHistogram,\n  getOrCreateValueHistogram,\n} from '../../observability/metrics.ts';\nimport {versionFromLexi} from '../../types/lexi-version.ts';\nimport type {ChangeStreamData} from '../change-source/protocol/current/downstream.ts';\nimport {extractChangeSubstring} from '../change-streamer/change-log-codec.ts';\nimport {ChangeLogTransactionHasher} from '../change-streamer/change-log-transaction-hash.ts';\nimport {\n  readCookieRowCounts,\n  type CookieOpTag,\n  type CookieRowCounts,\n} from './change-log-cookies.ts';\nimport {\n  CHANGE_LOG_STREAM_TABLE,\n  readChangeLogHead,\n  readChangeLogMeta,\n  type ChangeLogMeta,\n  type ReconcileResult,\n} from './change-log-db.ts';\nimport type {ChangeLogStreamTransactionStats} from './change-log-stream-writer.ts';\n\n/**\n * Reports the reconciliation of the change-log database against the watermark\n * the stream connection resumes from. This runs once per stream connection, so\n * a reconnect storm is visible here as well as a restart.\n *\n * A wipe is not an error — it is how every abnormal change-log state is\n * collapsed into a correct one — but each wipe costs the retention window, so\n * every reconnecting subscriber below the head gets `too-old`. The `gap` reason\n * in particular means the log neither held the resume watermark nor could be\n * truncated to it, so a nonzero rate in steady state is an alert, not a\n * statistic.\n */\nexport function recordSQLiteChangeLogReconcile(\n  lc: LogContext,\n  result: ReconcileResult,\n): void {\n  switch (result.action) {\n    case 'truncated':\n      getOrCreateCounter(\n        'replica',\n        'sqlite_change_log.reconcile_truncated_rows',\n        'Phantom change-log rows removed at reconciliation, i.e. rows above ' +\n          'the watermark the change stream resumed from.',\n      ).add(result.rows);\n      break;\n    case 'reseeded':\n      getOrCreateCounter(\n        'replica',\n        'sqlite_change_log.reconcile_wipes',\n        'Change-log wipes at reconciliation, by reason. Each one resets the ' +\n          'retention window, so subscribers below the head get `too-old`.',\n      ).add(1, {reason: result.reason});\n      break;\n    case 'none':\n      break;\n    default:\n      unreachable(result);\n  }\n  if (result.cookiesStale) {\n    // The invariant-17 counter: after any reconcile that moved the head, the\n    // log's cookie set has to be replaced with the one that belongs to the\n    // resume watermark. A nonzero `truncated` series in steady state means\n    // phantom truncation is happening on a shard where it should not.\n    getOrCreateCounter(\n      'replica',\n      'sqlite_change_log.cookie_reseed',\n      'Change-log cookie sets invalidated at reconciliation, by the ' +\n        'reconcile action that invalidated them.',\n    ).add(1, {action: result.action});\n  }\n  lc.debug?.('SQLite change-log reconciliation', {\n    sqliteChangeLogReconcile: result,\n  });\n}\n\n/**\n * What the log says about itself. Nothing here reads the replica: after the\n * writer moved to the change-streamer, the replica's state version is a\n * consequence of this log rather than a fact about it.\n */\nexport type SQLiteChangeLogStartupInfo = ChangeLogMeta & {\n  readonly headWatermark: string;\n};\n\nexport type SQLiteChangeLogInfo = SQLiteChangeLogStartupInfo & {\n  readonly rows: number;\n  readonly estimatedBytes: number;\n  readonly cookieRows: CookieRowCounts;\n};\n\n/**\n * Reads the meta row and the head. The head is an index-optimized `max()`, so\n * unlike {@link getSQLiteChangeLogInfo} this does not scan the log.\n *\n * Call this after reconciliation, which is the only point at which the head is\n * known to be the resume watermark.\n */\nexport function getSQLiteChangeLogStartupInfo(\n  changeLog: Database,\n): SQLiteChangeLogStartupInfo {\n  const meta = readChangeLogMeta(changeLog);\n  const head = readChangeLogHead(changeLog);\n  if (head === null) {\n    throw new Error('the SQLite change log must contain its seed transaction');\n  }\n  return {...meta, headWatermark: head};\n}\n\n/**\n * Extends {@link getSQLiteChangeLogStartupInfo} with the retained row and\n * estimated byte totals. Computing these scans the entire change-log table, so\n * only call it when the totals are consumed, i.e. when the writer (and thus the\n * observer) is enabled.\n */\nexport function getSQLiteChangeLogInfo(\n  changeLog: Database,\n): SQLiteChangeLogInfo {\n  const startup = getSQLiteChangeLogStartupInfo(changeLog);\n  const aggregate = changeLog\n    .prepare(/*sql*/ `\n      SELECT count(*) AS \"rows\",\n             coalesce(sum(\"estimatedBytes\"), 0) AS \"estimatedBytes\"\n        FROM \"${CHANGE_LOG_STREAM_TABLE}\"\n    `)\n    .get<{rows: number; estimatedBytes: number}>();\n\n  return {\n    ...startup,\n    rows: aggregate.rows,\n    estimatedBytes: aggregate.estimatedBytes,\n    cookieRows: readCookieRowCounts(changeLog),\n  };\n}\n\nexport function logSQLiteChangeLogStartup(\n  lc: LogContext,\n  file: string,\n  info: SQLiteChangeLogStartupInfo,\n): void {\n  lc.info?.('SQLite change-log startup', {\n    sqliteChangeLog: {\n      file,\n      epoch: info.epoch,\n      generation: info.generation,\n      replicaID: info.replicaID,\n      schemaVersion: info.schemaVersion,\n      seedWatermark: info.seedWatermark,\n      seededAtMs: info.seededAtMs,\n      headWatermark: info.headWatermark,\n    },\n  });\n}\n\n/**\n * The on-disk footprint of a SQLite database: its main file plus its `-wal` and\n * `-wal2` sidecars, whichever exist. `-shm` is excluded — it is a\n * shared-memory index rather than retained bytes.\n *\n * A missing file counts as zero rather than warning. Which sidecars exist\n * depends on the journal mode, and the change-log database is absent entirely\n * until the writer creates it.\n */\nexport async function sqliteFileBytes(\n  lc: LogContext,\n  file: string,\n): Promise<number> {\n  const sizes = await Promise.all(\n    [file, `${file}-wal`, `${file}-wal2`].map(async path => {\n      try {\n        return (await stat(path)).size;\n      } catch (e) {\n        if ((e as NodeJS.ErrnoException).code !== 'ENOENT') {\n          lc.warn?.(`unable to stat ${path} for size metrics`, e);\n        }\n        return 0;\n      }\n    }),\n  );\n  return sizes.reduce((total, size) => total + size, 0);\n}\n\n/** What the writer reports back for a committed transaction. */\nexport type ChangeLogCommit = {\n  readonly watermark: string;\n  readonly stats: ChangeLogStreamTransactionStats;\n  /**\n   * Appending the commit row and committing the log's transaction. This is the\n   * cost that sits on the forward path, once per upstream transaction.\n   */\n  readonly logCommitMs: number;\n};\n\nexport type SQLiteChangeLogObservabilityState = {\n  readonly receivedHead: string;\n  readonly sqliteHead: string;\n  readonly headLag: number | undefined;\n  readonly rows: number;\n  readonly estimatedBytes: number;\n  readonly cookieRows: CookieRowCounts;\n  readonly cookieMutations: number;\n  readonly rollbacks: number;\n  readonly invariantFailures: number;\n  readonly hashMatches: number;\n  readonly hashMismatches: number;\n  readonly hashUnpaired: number;\n};\n\nconst TRANSACTION_ROW_BUCKETS = [2, 3, 5, 10, 25, 50, 100, 250, 1000, 5000];\n\n/**\n * Records writer metrics in the change-streamer process. State changes only\n * after the corresponding write succeeds, except receivedHead, which advances\n * when a commit message arrives so that transient lag behind the log is\n * observable.\n */\nexport class SQLiteChangeLogObserver {\n  readonly #lc: LogContext;\n  readonly #messageProcessing = getOrCreateLatencyHistogram(\n    'replica',\n    'sqlite_change_log.message_processing_duration',\n    'Time to write a replication message to the SQLite change log.',\n  );\n  // The commit that sits on the forward path. There is no second commit to\n  // order against any more: the replica's belongs to a subscriber downstream of\n  // this loop, so `sqlite_change_log.replica_commit_duration` and the phantom\n  // window it measured are gone. A failed commit is still timed, by\n  // `message_processing_duration` keyed `tag=\"commit\"`.\n  readonly #logCommitDuration = getOrCreateLatencyHistogram(\n    'replica',\n    'sqlite_change_log.log_commit_duration',\n    'Time to append the commit row to the SQLite change log and commit its ' +\n      'transaction. This is on the forward path: it precedes the forward of ' +\n      \"that transaction's commit message.\",\n  );\n  readonly #transactionRows = getOrCreateValueHistogram(\n    'replica',\n    'sqlite_change_log.transaction_rows',\n    {\n      description: 'Rows stored per committed SQLite change-log transaction.',\n      unit: '{row}',\n      bucketBoundaries: TRANSACTION_ROW_BUCKETS,\n    },\n  );\n  readonly #rollbackCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.rollbacks',\n    'SQLite change-log transactions rolled back before commit.',\n  );\n  readonly #invariantFailureCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.invariant_failures',\n    'Detected SQLite change-log writer invariant failures.',\n  );\n  readonly #hashComparisonCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.hash_comparisons',\n    'Ephemeral transaction hash comparisons between the received change stream and SQLite change-log writes.',\n  );\n  readonly #hashUnpairedCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.hash_unpaired',\n    'Committed change-log transactions without both ephemeral hashes available for comparison.',\n  );\n  // Near zero at steady state: cookie state only moves on schema changes.\n  readonly #cookieMutationCounter = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.cookie_mutations',\n    'Change-log cookie mutations folded from schema changes, by operation.',\n  );\n\n  #receivedHead: string;\n  #sqliteHead: string;\n  #rows: number;\n  #estimatedBytes: number;\n  #cookieRows: CookieRowCounts;\n  #cookieMutations = 0;\n  #transactionWatermark: string | undefined;\n  #sourceHasher: ChangeLogTransactionHasher | undefined;\n  #sourcePos = 0;\n  #sourceCommitHash: string | undefined;\n  #rollbacks = 0;\n  #invariantFailures = 0;\n  #hashMatches = 0;\n  #hashMismatches = 0;\n  #hashUnpaired = 0;\n\n  constructor(lc: LogContext, info: SQLiteChangeLogInfo) {\n    this.#lc = lc.withContext('component', 'sqlite-change-log-observer');\n    // Reconciliation has just put the head at the resume watermark, which is\n    // also the point the stream is about to be received from.\n    this.#receivedHead = info.headWatermark;\n    this.#sqliteHead = info.headWatermark;\n    this.#rows = info.rows;\n    this.#estimatedBytes = info.estimatedBytes;\n    this.#cookieRows = info.cookieRows;\n\n    getOrCreateGauge(\n      'replica',\n      'sqlite_change_log.rows',\n      'Rows retained in the SQLite change log.',\n    ).addCallback(result => result.observe(this.#rows));\n    // Nonzero with no backfill in flight is a leaked cookie, i.e. a backfill\n    // that will be re-requested forever.\n    getOrCreateGauge(\n      'replica',\n      'sqlite_change_log.cookie_rows',\n      'Cookie rows retained in the SQLite change log, by cookie table.',\n    ).addCallback(result => {\n      result.observe(this.#cookieRows.tableMetadata, {table: 'tableMetadata'});\n      result.observe(this.#cookieRows.backfilling, {table: 'backfilling'});\n    });\n    getOrCreateGauge('replica', 'sqlite_change_log.retained_bytes', {\n      description:\n        'Estimated UTF-8 payload bytes retained in the SQLite change log.',\n      unit: 'By',\n    }).addCallback(result => result.observe(this.#estimatedBytes));\n    getOrCreateGauge(\n      'replica',\n      'sqlite_change_log.head',\n      'SQLite change-log head converted from its lexicographic watermark.',\n    ).addCallback(result => {\n      const head = watermarkValue(this.#sqliteHead);\n      if (head !== undefined) {\n        result.observe(head);\n      }\n    });\n    getOrCreateGauge(\n      'replica',\n      'sqlite_change_log.head_lag',\n      'Distance from the latest received commit to the SQLite change-log ' +\n        'head. The log commits before the forward, so this is zero except ' +\n        'within a transaction.',\n    ).addCallback(result => {\n      const lag = watermarkDistance(this.#receivedHead, this.#sqliteHead);\n      if (lag !== undefined) {\n        result.observe(lag);\n      }\n    });\n  }\n\n  /**\n   * Called as each message arrives, before it is written. Hashes the *received*\n   * stream, which is compared against the hash the writer computes over what it\n   * *stored*.\n   */\n  messageReceived(data: ChangeStreamData, json: string): void {\n    const tag = data[1].tag;\n    if (data[0] === 'begin') {\n      if (this.#sourceHasher !== undefined) {\n        this.#invariantFailure(\n          'Received change-log begin while a source hash is already open',\n          {receivedWatermark: data[2].commitWatermark},\n        );\n      }\n      const watermark = data[2].commitWatermark;\n      this.#sourceHasher = new ChangeLogTransactionHasher();\n      this.#sourcePos = 0;\n      this.#sourceCommitHash = undefined;\n      this.#sourceHasher.add({\n        watermark,\n        pos: this.#sourcePos,\n        tag,\n        change: extractChangeSubstring(json, tag),\n        precommit: null,\n      });\n      return;\n    }\n\n    if (tag === 'rollback') {\n      this.#resetSourceHash();\n      return;\n    }\n\n    if (data[0] === 'commit') {\n      this.#receivedHead = data[2].watermark;\n    }\n\n    const watermark = this.#transactionWatermark;\n    if (this.#sourceHasher === undefined || watermark === undefined) {\n      this.#invariantFailure(\n        'Received change-log message without an observed transaction',\n        {tag},\n      );\n      return;\n    }\n\n    const commitWatermark =\n      data[0] === 'commit' ? data[2].watermark : watermark;\n    this.#sourceHasher.add({\n      watermark: commitWatermark,\n      pos: ++this.#sourcePos,\n      tag,\n      change: extractChangeSubstring(json, tag),\n      precommit: data[0] === 'commit' ? watermark : null,\n    });\n    if (data[0] === 'commit') {\n      this.#sourceCommitHash = this.#sourceHasher.digest();\n      this.#sourceHasher = undefined;\n    }\n  }\n\n  /** Called after the message has been written to the log. */\n  messageProcessed(\n    data: ChangeStreamData,\n    commit: ChangeLogCommit | null,\n    durationMs: number,\n  ): void {\n    const tag = data[1].tag;\n    this.#messageProcessing.recordMs(durationMs, {tag, outcome: 'success'});\n\n    if (data[0] === 'begin') {\n      if (this.#transactionWatermark !== undefined) {\n        this.#invariantFailure('SQLite change-log transaction already open', {\n          openWatermark: this.#transactionWatermark,\n          receivedWatermark: data[2].commitWatermark,\n        });\n      }\n      this.#transactionWatermark = data[2].commitWatermark;\n      return;\n    }\n\n    if (tag === 'rollback') {\n      this.#recordRollback('upstream');\n      this.#transactionWatermark = undefined;\n      this.#resetSourceHash();\n      return;\n    }\n\n    if (data[0] !== 'commit') {\n      return;\n    }\n\n    const watermark = data[2].watermark;\n    if (commit !== null) {\n      this.#logCommitDuration.recordMs(commit.logCommitMs);\n    }\n    if (this.#transactionWatermark !== watermark) {\n      this.#invariantFailure(\n        'SQLite change-log commit does not match the observed begin',\n        {openWatermark: this.#transactionWatermark, commitWatermark: watermark},\n      );\n    }\n    if (commit === null) {\n      this.#invariantFailure(\n        'SQLite change-log commit result is missing writer statistics',\n        {commitWatermark: watermark},\n      );\n      this.#recordUnpaired(watermark, 'missing-sqlite-hash');\n    } else {\n      if (commit.watermark !== watermark) {\n        this.#invariantFailure(\n          'SQLite change-log commit result has an unexpected watermark',\n          {commitWatermark: watermark, resultWatermark: commit.watermark},\n        );\n      }\n      this.#rows += commit.stats.rows;\n      this.#estimatedBytes += commit.stats.estimatedBytes;\n      this.#transactionRows.record(commit.stats.rows);\n      this.#compareHashes(watermark, this.#sourceCommitHash, commit.stats.hash);\n    }\n    if (watermark < this.#sqliteHead) {\n      this.#invariantFailure('SQLite change-log head regressed', {\n        previousHead: this.#sqliteHead,\n        commitWatermark: watermark,\n      });\n    }\n    this.#sqliteHead = watermark;\n    this.#transactionWatermark = undefined;\n    this.#resetSourceHash();\n  }\n\n  messageFailed(\n    data: ChangeStreamData,\n    error: unknown,\n    durationMs: number,\n  ): void {\n    const tag = data[1].tag;\n    this.#messageProcessing.recordMs(durationMs, {tag, outcome: 'error'});\n    if (data[0] === 'commit') {\n      // No commit duration here: a failed commit produces no statistics, so\n      // there is nothing to attribute. The attempt is timed by\n      // `message_processing_duration{tag=\"commit\",outcome=\"error\"}` above.\n      this.#recordUnpaired(data[2].watermark, 'sqlite-commit-failed');\n    }\n    if (\n      error instanceof Error &&\n      error.name === 'ChangeLogStreamInvariantError'\n    ) {\n      this.#invariantFailure(error.message);\n    }\n    if (this.#transactionWatermark !== undefined || data[0] === 'begin') {\n      this.#recordRollback('processing-error');\n    }\n    this.#transactionWatermark = undefined;\n    this.#resetSourceHash();\n  }\n\n  /**\n   * A committed transaction folded schema changes into the cookie jar. Reported\n   * separately from {@link messageProcessed} because it costs a read of the\n   * cookie tables, which is only worth taking when they actually moved.\n   */\n  cookiesMutated(ops: readonly CookieOpTag[], rows: CookieRowCounts): void {\n    for (const op of ops) {\n      this.#cookieMutations++;\n      this.#cookieMutationCounter.add(1, {op});\n    }\n    this.#cookieRows = rows;\n  }\n\n  /**\n   * A missed truncate-above surfaces as a constraint violation on the writer's\n   * plain `INSERT`, which the fail-soft policy would otherwise absorb quietly.\n   * Classifying it as an invariant failure is what keeps a reconciliation bug\n   * from looking like a lost cache.\n   */\n  invariantFailure(message: string, details?: Record<string, unknown>): void {\n    this.#invariantFailure(message, details);\n  }\n\n  /** The source interrupted the stream mid-transaction. */\n  abort(): void {\n    if (this.#transactionWatermark !== undefined) {\n      this.#recordRollback('source-interruption');\n      this.#transactionWatermark = undefined;\n    }\n    this.#resetSourceHash();\n  }\n\n  /** Reconciliation moved the head, so the observer's totals are restated. */\n  reconciled(info: SQLiteChangeLogInfo): void {\n    this.#receivedHead = info.headWatermark;\n    this.#sqliteHead = info.headWatermark;\n    this.#rows = info.rows;\n    this.#estimatedBytes = info.estimatedBytes;\n    this.#cookieRows = info.cookieRows;\n    this.#transactionWatermark = undefined;\n    this.#resetSourceHash();\n  }\n\n  state(): SQLiteChangeLogObservabilityState {\n    return {\n      receivedHead: this.#receivedHead,\n      sqliteHead: this.#sqliteHead,\n      headLag: watermarkDistance(this.#receivedHead, this.#sqliteHead),\n      rows: this.#rows,\n      estimatedBytes: this.#estimatedBytes,\n      cookieRows: this.#cookieRows,\n      cookieMutations: this.#cookieMutations,\n      rollbacks: this.#rollbacks,\n      invariantFailures: this.#invariantFailures,\n      hashMatches: this.#hashMatches,\n      hashMismatches: this.#hashMismatches,\n      hashUnpaired: this.#hashUnpaired,\n    };\n  }\n\n  #recordRollback(\n    reason: 'upstream' | 'processing-error' | 'source-interruption',\n  ) {\n    this.#rollbacks++;\n    this.#rollbackCounter.add(1, {reason});\n  }\n\n  #invariantFailure(message: string, details?: Record<string, unknown>) {\n    this.#invariantFailures++;\n    this.#invariantFailureCounter.add(1);\n    this.#lc.error?.(message, details);\n  }\n\n  #compareHashes(\n    watermark: string,\n    sourceHash: string | undefined,\n    sqliteHash: string,\n  ): void {\n    if (sourceHash === undefined) {\n      this.#recordUnpaired(watermark, 'missing-source-hash');\n      return;\n    }\n    if (sourceHash === sqliteHash) {\n      this.#hashMatches++;\n      this.#hashComparisonCounter.add(1, {outcome: 'match'});\n      return;\n    }\n    this.#hashMismatches++;\n    this.#hashComparisonCounter.add(1, {outcome: 'mismatch'});\n    this.#lc.error?.('SQLite change-log transaction hash mismatch', {\n      sqliteChangeLogHashComparison: {\n        watermark,\n        sourceHash: sourceHash.slice(0, 16),\n        sqliteHash: sqliteHash.slice(0, 16),\n      },\n    });\n  }\n\n  #recordUnpaired(\n    watermark: string,\n    reason:\n      | 'missing-source-hash'\n      | 'missing-sqlite-hash'\n      | 'sqlite-commit-failed',\n  ): void {\n    this.#hashUnpaired++;\n    this.#hashUnpairedCounter.add(1, {reason});\n    this.#lc.warn?.('SQLite change-log transaction hash was not compared', {\n      sqliteChangeLogHashComparison: {watermark, reason},\n    });\n  }\n\n  #resetSourceHash(): void {\n    this.#sourceHasher = undefined;\n    this.#sourcePos = 0;\n    this.#sourceCommitHash = undefined;\n  }\n}\n\nfunction watermarkValue(watermark: string): number | undefined {\n  try {\n    const value = Number(versionFromLexi(watermark));\n    return Number.isFinite(value) ? value : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction watermarkDistance(\n  receivedHead: string,\n  sqliteHead: string,\n): number | undefined {\n  if (receivedHead <= sqliteHead) {\n    return 0;\n  }\n  try {\n    const distance =\n      versionFromLexi(receivedHead) - versionFromLexi(sqliteHead);\n    const value = Number(distance);\n    return Number.isFinite(value) ? value : undefined;\n  } catch {\n    return undefined;\n  }\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,120 @@
+/**
+ * Deletes aged-out transactions from the change-log database, one bounded write
+ * transaction at a time.
+ *
+ * The purger is a pure function of one database: it takes the floors its caller
+ * has already gated on and narrows them, never widens them, and it reads no
+ * replication state. That is what makes it testable without a scheduler and
+ * what lets slice 9 run it from the change-streamer's stream loop, between the
+ * writer's commits, on the writer's own connection.
+ */
+import type { Database } from '../../../../zqlite/src/db.ts';
+/**
+ * The eligible set, as three ANDed bounds. Only the `externalFloor` is a safety
+ * property; the other two make the log serviceable and make purge conservative.
+ *
+ * `"watermark" < @externalFloor` is deliberately strict. A follower that lost
+ * its replica restores it from S3 at watermark `W` and then asks this log for
+ * everything after `W`, which requires the `commit` row *at* `W` to still be
+ * here (`SQLITE_CHANGE_LOG_BOUNDARY_SQL`). Deleting it returns `too-old` to the
+ * very subscriber the floor exists to protect.
+ *
+ * The head cap reads `max("watermark")` from the log's own database, which
+ * keeps the purger a pure function of one file. The cap is inert in normal
+ * operation: the floor is derived from a backup of a replica that consumes this
+ * loop's output, and the log commits before that output is forwarded, so
+ * `externalFloor <= head` holds by construction. It engages only on a *stale*
+ * log — writer stopped, mode flipped to `off`, another task took over — where
+ * deleting to a floor that has run past a frozen log would empty the file. Note
+ * that head can be a phantom — committed here but not yet re-deliverable by a
+ * resumed stream — for as long as it takes the watermark the stream would
+ * resume from to advance past it. That is harmless precisely because head is
+ * never a purge candidate, and it is why the purger asserts nothing about
+ * anything outside its own file.
+ *
+ * Ordered by `("writeTimeMs", "watermark")` so it rides the partial index,
+ * which carries one entry per transaction rather than one per change. The
+ * `LIMIT` keeps a drain from re-scanning the remaining history on every batch,
+ * which would be quadratic in the number of eligible transactions and would do
+ * it inside the `BEGIN IMMEDIATE`, holding the write lock alongside the delete.
+ *
+ * Exported so the focused query-plan test covers the production query.
+ */
+export declare const SQLITE_CHANGE_LOG_ELIGIBLE_COMMITS_SQL = "\n  SELECT \"watermark\"\n  FROM \"_zero.changeLogStream\"\n  WHERE \"writeTimeMs\" IS NOT NULL\n    AND \"writeTimeMs\" < @retentionCutoffMs\n    AND \"watermark\" < @externalFloor\n    AND \"watermark\" < (SELECT max(\"watermark\") FROM \"_zero.changeLogStream\")\n  ORDER BY \"writeTimeMs\", \"watermark\"\n  LIMIT @limit\n";
+/**
+ * Counts the rows at `@watermark`, capped at `@limit`. The cap is what keeps
+ * batch sizing O(budget): this runs per candidate inside the
+ * `BEGIN IMMEDIATE`, and the transaction being sized can be arbitrarily
+ * large — an uncapped count of a multi-million-row backfill would rescan
+ * every remaining row on every tear batch, holding the write lock (and the
+ * appending path behind it) for the duration, quadratically over the drain.
+ * The caller only needs to know whether the transaction fits its remaining
+ * budget, so it passes `remaining + 1` and reads a count above `remaining`
+ * as "does not fit".
+ *
+ * Exported so the focused tests cover the production query.
+ */
+export declare const SQLITE_CHANGE_LOG_COUNT_TRANSACTION_SQL = "\n  SELECT count(*) AS \"rows\" FROM (\n    SELECT 1\n    FROM \"_zero.changeLogStream\"\n    WHERE \"watermark\" = @watermark\n    LIMIT @limit\n  )\n";
+export type PurgeBatchResult = {
+    readonly deletedRows: number;
+    /**
+     * The watermark through which whole transactions were removed. `undefined`
+     * when the batch only tore rows off the minimum transaction without
+     * completing it — in that case `deletedRows > 0` and `moreEligible` is true.
+     */
+    readonly deletedThrough: string | undefined;
+    /** True while a tear is in progress, as well as while whole transactions remain eligible. */
+    readonly moreEligible: boolean;
+};
+export type PurgeBatchOptions = {
+    /**
+     * The floor the caller has already gated on subscriber ACKs and snapshot
+     * reservations — normally the confirmed S3 backup watermark. Transactions at
+     * or above it are NOT durable anywhere else: the change log is excluded from
+     * the litestream backup, so this is the boundary a follower restores to and
+     * then catches up from. Compared strictly (`<`), so the transaction *at* the
+     * floor survives as that follower's catchup boundary. The purger narrows this
+     * input and never widens it.
+     */
+    readonly externalFloor: string;
+    /**
+     * A *minimum* retention, ANDed on top of `externalFloor` rather than an
+     * alternative to it. Which of the two binds depends on the backup interval.
+     */
+    readonly retentionCutoffMs: number;
+    /** Starting chunk size. Not the bound — `maxDurationMs` is. */
+    readonly maxRows: number;
+    /**
+     * The statement duration target, enforced by feedback rather than by
+     * interruption: SQLite cannot yield mid-statement, so the purger measures
+     * each delete and shrinks the next batch's row budget when one overruns
+     * (see {@link SQLiteChangeLogPurger.budgetRows}) — which means the first
+     * delete after a restart, sized by `maxRows` alone, can still overrun it.
+     * The target is this consequential because purge shares the writer's
+     * connection: there is no lock to arbitrate and no `busy_timeout` to bound
+     * the wait — a long statement blocks the appending path, and the forward
+     * behind it, directly and for its full duration. That is why this is a
+     * precondition of purging from the stream loop rather than a tuning knob.
+     */
+    readonly maxDurationMs: number;
+};
+export declare class SQLiteChangeLogPurger {
+    #private;
+    /**
+     * @param db a writable connection to a change log the writer has already
+     *     created and reconciled — in slice 9, the writer's own connection.
+     *     Statements are prepared eagerly, so a caller that may run before the
+     *     log exists opens the connection lazily and treats construction failure
+     *     as a skipped cycle.
+     */
+    constructor(db: Database, now?: () => number);
+    /** The row budget the next batch would use. Exposed for tests and metrics. */
+    get budgetRows(): number | undefined;
+    /**
+     * Removes one bounded batch of aged-out history, in one `BEGIN IMMEDIATE`
+     * transaction. Callers loop while `moreEligible`, releasing whatever guards
+     * they hold between batches.
+     */
+    purgeBatch(opts: PurgeBatchOptions): PurgeBatchResult;
+}
+//# sourceMappingURL=sqlite-change-log-purger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-change-log-purger.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/replicator/sqlite-change-log-purger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAC,QAAQ,EAAY,MAAM,8BAA8B,CAAC;AAGtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,sCAAsC,2UASlD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uCAAuC,4JAOnD,CAAC;AAuCF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,6FAA6F;IAC7F,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,CAAC;AAWF,qBAAa,qBAAqB;;IAahC;;;;;;OAMG;gBAED,EAAE,EAAE,QAAQ,EACZ,GAAG,GAAE,MAAM,MAA0C;IAcvD,8EAA8E;IAC9E,IAAI,UAAU,IAAI,MAAM,GAAG,SAAS,CAEnC;IAED;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,gBAAgB;CAwMtD"}

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

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

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

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

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

@@ -4,6 +4,7 @@ import { getSubscriptionState } from "./schema/replication-state.js";
 import { StatementRunner } from "../../db/statements.js";
 import { isSQLiteCorruption, logSQLiteCorruptionDiagnostics, registerSQLiteCorruptionDiagnosticTarget } from "../../db/sqlite-corruption.js";
 import { createLogContext } from "../../server/logging.js";
+import { deleteLiteDB } from "../../db/delete-lite-db.js";
 import { ChangeProcessor } from "./change-processor.js";
 import { applyPragmas, serializeError } from "./write-worker-client.js";
 import { parentPort } from "node:worker_threads";
@@ -17,13 +18,24 @@ function createAPI() {
 	let mode;
 	let lc;
 	let replicaDbPath;
-	let unregisterCorruptionDiagnosticTarget;
-	function logCorruptionDiagnostics(err) {
-		if (lc && replicaDbPath && isSQLiteCorruption(err)) logSQLiteCorruptionDiagnostics(lc, "write-worker", replicaDbPath, err);
+	let unregisterCorruptionDiagnosticTargets = [];
+	function unregisterCorruptionDiagnostics() {
+		unregisterCorruptionDiagnosticTargets.forEach((unregister) => unregister());
+		unregisterCorruptionDiagnosticTargets = [];
+	}
+	function handleCorruptedDb(err) {
+		if (!lc || !replicaDbPath || !isSQLiteCorruption(err)) return;
+		logSQLiteCorruptionDiagnostics(lc, "write-worker", replicaDbPath, err);
+		try {
+			lc.warn?.(`deleting corrupted db at ${replicaDbPath}`);
+			deleteLiteDB(replicaDbPath);
+		} catch (e) {
+			lc.warn?.(`error deleting corrupted db at ${replicaDbPath}`, e);
+		}
 	}
 	function createProcessor() {
 		processor = new ChangeProcessor(must(runner), must(mode), (_lc, err) => {
-			logCorruptionDiagnostics(err);
+			handleCorruptedDb(err);
 			port.postMessage({ writeError: serializeError(err) });
 		});
 	}
@@ -31,11 +43,11 @@ function createAPI() {
 		init(dbPath, cpMode, pragmas, logConfig) {
 			replicaDbPath = dbPath;
 			lc = createLogContext({ log: logConfig }, "write-worker");
-			unregisterCorruptionDiagnosticTarget?.();
-			unregisterCorruptionDiagnosticTarget = registerSQLiteCorruptionDiagnosticTarget({
+			unregisterCorruptionDiagnostics();
+			unregisterCorruptionDiagnosticTargets.push(registerSQLiteCorruptionDiagnosticTarget({
 				debugName: "write-worker",
 				dbPath
-			});
+			}));
 			try {
 				db = new Database(lc, dbPath);
 				applyPragmas(db, pragmas);
@@ -43,7 +55,7 @@ function createAPI() {
 				mode = cpMode;
 				createProcessor();
 			} catch (e) {
-				logCorruptionDiagnostics(e);
+				handleCorruptedDb(e);
 				throw e;
 			}
 		},
@@ -51,7 +63,7 @@ function createAPI() {
 			try {
 				return getSubscriptionState(must(runner));
 			} catch (e) {
-				logCorruptionDiagnostics(e);
+				handleCorruptedDb(e);
 				throw e;
 			}
 		},
@@ -59,7 +71,7 @@ function createAPI() {
 			try {
 				return must(processor).processMessage(must(lc), downstream);
 			} catch (e) {
-				logCorruptionDiagnostics(e);
+				handleCorruptedDb(e);
 				throw e;
 			}
 		},
@@ -73,8 +85,7 @@ function createAPI() {
 			runner = void 0;
 			processor = void 0;
 			replicaDbPath = void 0;
-			unregisterCorruptionDiagnosticTarget?.();
-			unregisterCorruptionDiagnosticTarget = void 0;
+			unregisterCorruptionDiagnostics();
 		}
 	};
 }