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

package/out/zero-cache/src/services/change-streamer/sqlite-change-log-read-router.js

@@ -0,0 +1,157 @@
+import { Database } from "../../../../zqlite/src/db.js";
+import { readChangeLogBounds, readChangeLogMeta } from "../replicator/change-log-db.js";
+import { isSampledForShard } from "./shard-sampling.js";
+//#region ../zero-cache/src/services/change-streamer/sqlite-change-log-read-router.ts
+var DEFAULT_FAILURE_COOLDOWN_MS = 3e4;
+/**
+* Selects and pins the catchup source shared by `/snapshot` and `/changes`.
+*
+* A post-registration SQLite failure opens a process-local breaker. Requests
+* use PG during the cooldown; the first request after it expires is the
+* bounded probe. A successful readiness inspection closes the breaker, while
+* another unavailable result rearms it. A writer failure opens it permanently
+* because the writer remains disabled and its file stays absent for the life
+* of the process.
+*/
+var SQLiteChangeLogReadRouter = class {
+	#shard;
+	#readPercent;
+	#coldReadPercent;
+	#retentionMs;
+	#inspect;
+	#failureCooldownMs;
+	#now;
+	#pins = /* @__PURE__ */ new Map();
+	#breakerUntilMs;
+	#permanentlyDisabled = false;
+	constructor(opts) {
+		this.#shard = opts.shard;
+		this.#readPercent = opts.readPercent;
+		this.#coldReadPercent = opts.coldReadPercent ?? 0;
+		this.#retentionMs = opts.retentionMs;
+		this.#inspect = opts.inspect;
+		this.#failureCooldownMs = opts.failureCooldownMs ?? DEFAULT_FAILURE_COOLDOWN_MS;
+		this.#now = opts.now ?? Date.now;
+	}
+	/** Chooses and pins a source for a snapshot reservation. */
+	pin(taskID) {
+		const route = this.#choose(taskID);
+		this.#pins.set(taskID, route);
+		return route;
+	}
+	/** Returns the source pinned by an active snapshot reservation. */
+	peek(taskID) {
+		const route = this.#pins.get(taskID);
+		return route && this.#asPinned(route);
+	}
+	/** Consumes a snapshot pin, or makes the stable choice for a direct retry. */
+	consume(taskID) {
+		const route = this.#pins.get(taskID);
+		if (route === void 0) return this.#choose(taskID);
+		this.#pins.delete(taskID);
+		return this.#asPinned(route);
+	}
+	/** Releases a pin whose snapshot reservation ended before subscribing. */
+	release(taskID) {
+		this.#pins.delete(taskID);
+	}
+	/**
+	* Replaces a pinned SQLite route with PG, for a reservation whose backup
+	* the log cannot cover -- most often a log seeded after that backup.
+	*
+	* The pin moves, not just the reservation's advertised bounds. Confirming
+	* with PG bounds while the task's `/changes` request still resolves to
+	* SQLite is exactly the mismatch the reservation path exists to prevent,
+	* so the two have to change together.
+	*
+	* A task with no pin is left alone: `consume` makes it a fresh choice.
+	*/
+	demote(taskID) {
+		const route = {
+			source: "pg",
+			reason: "backup-uncovered"
+		};
+		if (this.#pins.has(taskID)) this.#pins.set(taskID, route);
+		return route;
+	}
+	/** Opens the post-registration failure breaker. */
+	trip(permanent = false) {
+		if (permanent) {
+			this.#permanentlyDisabled = true;
+			this.#breakerUntilMs = void 0;
+			return;
+		}
+		if (!this.#permanentlyDisabled) this.#breakerUntilMs = this.#now() + this.#failureCooldownMs;
+	}
+	#choose(taskID) {
+		const now = this.#now();
+		if (this.#permanentlyDisabled || this.#breakerUntilMs !== void 0 && now < this.#breakerUntilMs) return {
+			source: "pg",
+			reason: "breaker-open"
+		};
+		let coverage;
+		try {
+			coverage = this.#inspect();
+		} catch {
+			coverage = void 0;
+		}
+		if (coverage === void 0) {
+			if (this.#breakerUntilMs !== void 0) this.#breakerUntilMs = now + this.#failureCooldownMs;
+			return {
+				source: "pg",
+				reason: "log-unavailable"
+			};
+		}
+		this.#breakerUntilMs = void 0;
+		const cold = now - coverage.seededAtMs < this.#retentionMs;
+		if (cold && !isSampledForShard(this.#shard, taskID, this.#coldReadPercent)) return {
+			source: "pg",
+			reason: "cold-log",
+			coverage
+		};
+		if (!isSampledForShard(this.#shard, taskID, this.#readPercent)) return {
+			source: "pg",
+			reason: "percentage",
+			coverage
+		};
+		return {
+			source: "sqlite",
+			reason: cold ? "selected-cold" : "selected",
+			coverage
+		};
+	}
+	#asPinned(route) {
+		return {
+			...route,
+			pinned: true
+		};
+	}
+};
+/**
+* Reads the coverage and validates the v2 schema and RMv2 identity in one
+* short-lived readonly connection. It never creates the log.
+*/
+function inspectSQLiteChangeLog(lc, changeLogFile, identity) {
+	let db;
+	try {
+		db = new Database(lc.withContext("component", "sqlite-change-log-read-router"), changeLogFile, { readonly: true });
+		const meta = readChangeLogMeta(db);
+		if (meta.schemaVersion !== 4 || meta.epoch !== identity.epoch || meta.generation !== identity.generation || meta.replicaID !== identity.replicaID) return;
+		const bounds = readChangeLogBounds(db);
+		if (bounds.minWatermark === null || bounds.headWatermark === null) return;
+		return {
+			seededAtMs: meta.seededAtMs,
+			seedWatermark: meta.seedWatermark,
+			minWatermark: bounds.minWatermark,
+			headWatermark: bounds.headWatermark
+		};
+	} catch {
+		return;
+	} finally {
+		db?.close();
+	}
+}
+//#endregion
+export { SQLiteChangeLogReadRouter, inspectSQLiteChangeLog };
+
+//# sourceMappingURL=sqlite-change-log-read-router.js.map

package/out/zero-cache/src/services/change-streamer/sqlite-change-log-read-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-change-log-read-router.js","names":["#shard","#readPercent","#coldReadPercent","#retentionMs","#inspect","#failureCooldownMs","#now","#pins","#choose","#asPinned","#permanentlyDisabled","#breakerUntilMs"],"sources":["../../../../../../zero-cache/src/services/change-streamer/sqlite-change-log-read-router.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {Database} from '../../../../zqlite/src/db.ts';\nimport type {ShardID} from '../../types/shards.ts';\nimport {\n  CHANGE_LOG_DB_SCHEMA_VERSION,\n  readChangeLogBounds,\n  readChangeLogMeta,\n  type ChangeLogIdentity,\n} from '../replicator/change-log-db.ts';\nimport {isSampledForShard} from './shard-sampling.ts';\n\nexport type ChangeLogReadSource = 'pg' | 'sqlite';\n\nexport type SQLiteChangeLogCoverage = {\n  readonly seededAtMs: number;\n  readonly seedWatermark: string;\n  readonly minWatermark: string;\n  readonly headWatermark: string;\n};\n\nexport type ChangeLogReadRouteReason =\n  | 'selected'\n  // Selected while the log was still inside its warm-up window. Kept\n  // distinct from 'selected' so bootstrap serving is separable in metrics\n  // from steady-state serving.\n  | 'selected-cold'\n  | 'percentage'\n  | 'cold-log'\n  | 'log-unavailable'\n  | 'breaker-open'\n  // Pinned to SQLite, then demoted because the log could not cover the\n  // backup the reservation is restoring from. See {@link\n  // SQLiteChangeLogReadRouter.demote}.\n  | 'backup-uncovered';\n\nexport type ChangeLogReadRoute = {\n  readonly source: ChangeLogReadSource;\n  readonly reason: ChangeLogReadRouteReason;\n  readonly pinned?: boolean | undefined;\n  readonly coverage?: SQLiteChangeLogCoverage | undefined;\n};\n\nexport type SQLiteChangeLogReadRouterOptions = {\n  readonly shard: ShardID;\n  readonly readPercent: number;\n  /**\n   * Percentage of eligible tasks served from a log that has not yet aged\n   * through {@link retentionMs}. Defaults to zero, which keeps every such\n   * task on PG.\n   */\n  readonly coldReadPercent?: number | undefined;\n  readonly retentionMs: number;\n  readonly inspect: () => SQLiteChangeLogCoverage | undefined;\n  readonly failureCooldownMs?: number | undefined;\n  readonly now?: (() => number) | undefined;\n};\n\nconst DEFAULT_FAILURE_COOLDOWN_MS = 30_000;\n\n/**\n * Selects and pins the catchup source shared by `/snapshot` and `/changes`.\n *\n * A post-registration SQLite failure opens a process-local breaker. Requests\n * use PG during the cooldown; the first request after it expires is the\n * bounded probe. A successful readiness inspection closes the breaker, while\n * another unavailable result rearms it. A writer failure opens it permanently\n * because the writer remains disabled and its file stays absent for the life\n * of the process.\n */\nexport class SQLiteChangeLogReadRouter {\n  readonly #shard: ShardID;\n  readonly #readPercent: number;\n  readonly #coldReadPercent: number;\n  readonly #retentionMs: number;\n  readonly #inspect: () => SQLiteChangeLogCoverage | undefined;\n  readonly #failureCooldownMs: number;\n  readonly #now: () => number;\n  readonly #pins = new Map<string, ChangeLogReadRoute>();\n\n  #breakerUntilMs: number | undefined;\n  #permanentlyDisabled = false;\n\n  constructor(opts: SQLiteChangeLogReadRouterOptions) {\n    this.#shard = opts.shard;\n    this.#readPercent = opts.readPercent;\n    this.#coldReadPercent = opts.coldReadPercent ?? 0;\n    this.#retentionMs = opts.retentionMs;\n    this.#inspect = opts.inspect;\n    this.#failureCooldownMs =\n      opts.failureCooldownMs ?? DEFAULT_FAILURE_COOLDOWN_MS;\n    this.#now = opts.now ?? Date.now;\n  }\n\n  /** Chooses and pins a source for a snapshot reservation. */\n  pin(taskID: string): ChangeLogReadRoute {\n    const route = this.#choose(taskID);\n    this.#pins.set(taskID, route);\n    return route;\n  }\n\n  /** Returns the source pinned by an active snapshot reservation. */\n  peek(taskID: string): ChangeLogReadRoute | undefined {\n    const route = this.#pins.get(taskID);\n    return route && this.#asPinned(route);\n  }\n\n  /** Consumes a snapshot pin, or makes the stable choice for a direct retry. */\n  consume(taskID: string): ChangeLogReadRoute {\n    const route = this.#pins.get(taskID);\n    if (route === undefined) {\n      return this.#choose(taskID);\n    }\n    this.#pins.delete(taskID);\n    return this.#asPinned(route);\n  }\n\n  /** Releases a pin whose snapshot reservation ended before subscribing. */\n  release(taskID: string): void {\n    this.#pins.delete(taskID);\n  }\n\n  /**\n   * Replaces a pinned SQLite route with PG, for a reservation whose backup\n   * the log cannot cover -- most often a log seeded after that backup.\n   *\n   * The pin moves, not just the reservation's advertised bounds. Confirming\n   * with PG bounds while the task's `/changes` request still resolves to\n   * SQLite is exactly the mismatch the reservation path exists to prevent,\n   * so the two have to change together.\n   *\n   * A task with no pin is left alone: `consume` makes it a fresh choice.\n   */\n  demote(taskID: string): ChangeLogReadRoute {\n    const route: ChangeLogReadRoute = {\n      source: 'pg',\n      reason: 'backup-uncovered',\n    };\n    if (this.#pins.has(taskID)) {\n      this.#pins.set(taskID, route);\n    }\n    return route;\n  }\n\n  /** Opens the post-registration failure breaker. */\n  trip(permanent = false): void {\n    if (permanent) {\n      this.#permanentlyDisabled = true;\n      this.#breakerUntilMs = undefined;\n      return;\n    }\n    if (!this.#permanentlyDisabled) {\n      this.#breakerUntilMs = this.#now() + this.#failureCooldownMs;\n    }\n  }\n\n  #choose(taskID: string): ChangeLogReadRoute {\n    const now = this.#now();\n    if (\n      this.#permanentlyDisabled ||\n      (this.#breakerUntilMs !== undefined && now < this.#breakerUntilMs)\n    ) {\n      return {source: 'pg', reason: 'breaker-open'};\n    }\n\n    // Inspect eligibility even at readPercent=0. Slice 11 starts its rollout\n    // at zero specifically so warm/cold/unavailable rates are visible before\n    // any subscriber is routed to SQLite.\n    let coverage: SQLiteChangeLogCoverage | undefined;\n    try {\n      coverage = this.#inspect();\n    } catch {\n      coverage = undefined;\n    }\n    if (coverage === undefined) {\n      // This was a breaker probe rather than ordinary startup unavailability.\n      // Rearm it so a busy retry loop does not turn into an open/read loop.\n      if (this.#breakerUntilMs !== undefined) {\n        this.#breakerUntilMs = now + this.#failureCooldownMs;\n      }\n      return {source: 'pg', reason: 'log-unavailable'};\n    }\n    // A successful probe restores eligibility. This happens before the gates\n    // below so that declining a task -- for a cold log or for the percentage\n    // -- does not leave the cooldown armed against the next ordinary\n    // unavailability.\n    this.#breakerUntilMs = undefined;\n    // A log seeded less than a retention window ago holds less history than\n    // the purger promises to keep, so it is the case that most often cannot\n    // cover a follower. It is also the only path that has no PG to fall back\n    // to once PG is retired, which is the argument for exercising it now\n    // rather than meeting it at the cutover: `coldReadPercent` is that dial.\n    const cold = now - coverage.seededAtMs < this.#retentionMs;\n    if (\n      cold &&\n      !isSampledForShard(this.#shard, taskID, this.#coldReadPercent)\n    ) {\n      return {source: 'pg', reason: 'cold-log', coverage};\n    }\n\n    // Keeping the percentage decision after readiness makes zero-percent\n    // rollouts emit eligibility metrics without serving reads.\n    if (!isSampledForShard(this.#shard, taskID, this.#readPercent)) {\n      return {source: 'pg', reason: 'percentage', coverage};\n    }\n    return {\n      source: 'sqlite',\n      reason: cold ? 'selected-cold' : 'selected',\n      coverage,\n    };\n  }\n\n  #asPinned(route: ChangeLogReadRoute): ChangeLogReadRoute {\n    return {...route, pinned: true};\n  }\n}\n\n/**\n * Reads the coverage and validates the v2 schema and RMv2 identity in one\n * short-lived readonly connection. It never creates the log.\n */\nexport function inspectSQLiteChangeLog(\n  lc: LogContext,\n  changeLogFile: string,\n  identity: ChangeLogIdentity,\n): SQLiteChangeLogCoverage | undefined {\n  let db: Database | undefined;\n  try {\n    db = new Database(\n      lc.withContext('component', 'sqlite-change-log-read-router'),\n      changeLogFile,\n      {readonly: true},\n    );\n    const meta = readChangeLogMeta(db);\n    if (\n      meta.schemaVersion !== CHANGE_LOG_DB_SCHEMA_VERSION ||\n      meta.epoch !== identity.epoch ||\n      meta.generation !== identity.generation ||\n      meta.replicaID !== identity.replicaID\n    ) {\n      return undefined;\n    }\n    const bounds = readChangeLogBounds(db);\n    if (bounds.minWatermark === null || bounds.headWatermark === null) {\n      return undefined;\n    }\n    return {\n      seededAtMs: meta.seededAtMs,\n      seedWatermark: meta.seedWatermark,\n      minWatermark: bounds.minWatermark,\n      headWatermark: bounds.headWatermark,\n    };\n  } catch {\n    return undefined;\n  } finally {\n    db?.close();\n  }\n}\n"],"mappings":";;;;AAyDA,IAAM,8BAA8B;;;;;;;;;;;AAYpC,IAAa,4BAAb,MAAuC;CACrC;CACA;CACA;CACA;CACA;CACA;CACA;CACA,wBAAiB,IAAI,IAAgC;CAErD;CACA,uBAAuB;CAEvB,YAAY,MAAwC;EAClD,KAAKA,SAAS,KAAK;EACnB,KAAKC,eAAe,KAAK;EACzB,KAAKC,mBAAmB,KAAK,mBAAmB;EAChD,KAAKC,eAAe,KAAK;EACzB,KAAKC,WAAW,KAAK;EACrB,KAAKC,qBACH,KAAK,qBAAqB;EAC5B,KAAKC,OAAO,KAAK,OAAO,KAAK;CAC/B;;CAGA,IAAI,QAAoC;EACtC,MAAM,QAAQ,KAAKE,QAAQ,MAAM;EACjC,KAAKD,MAAM,IAAI,QAAQ,KAAK;EAC5B,OAAO;CACT;;CAGA,KAAK,QAAgD;EACnD,MAAM,QAAQ,KAAKA,MAAM,IAAI,MAAM;EACnC,OAAO,SAAS,KAAKE,UAAU,KAAK;CACtC;;CAGA,QAAQ,QAAoC;EAC1C,MAAM,QAAQ,KAAKF,MAAM,IAAI,MAAM;EACnC,IAAI,UAAU,KAAA,GACZ,OAAO,KAAKC,QAAQ,MAAM;EAE5B,KAAKD,MAAM,OAAO,MAAM;EACxB,OAAO,KAAKE,UAAU,KAAK;CAC7B;;CAGA,QAAQ,QAAsB;EAC5B,KAAKF,MAAM,OAAO,MAAM;CAC1B;;;;;;;;;;;;CAaA,OAAO,QAAoC;EACzC,MAAM,QAA4B;GAChC,QAAQ;GACR,QAAQ;EACV;EACA,IAAI,KAAKA,MAAM,IAAI,MAAM,GACvB,KAAKA,MAAM,IAAI,QAAQ,KAAK;EAE9B,OAAO;CACT;;CAGA,KAAK,YAAY,OAAa;EAC5B,IAAI,WAAW;GACb,KAAKG,uBAAuB;GAC5B,KAAKC,kBAAkB,KAAA;GACvB;EACF;EACA,IAAI,CAAC,KAAKD,sBACR,KAAKC,kBAAkB,KAAKL,KAAK,IAAI,KAAKD;CAE9C;CAEA,QAAQ,QAAoC;EAC1C,MAAM,MAAM,KAAKC,KAAK;EACtB,IACE,KAAKI,wBACJ,KAAKC,oBAAoB,KAAA,KAAa,MAAM,KAAKA,iBAElD,OAAO;GAAC,QAAQ;GAAM,QAAQ;EAAc;EAM9C,IAAI;EACJ,IAAI;GACF,WAAW,KAAKP,SAAS;EAC3B,QAAQ;GACN,WAAW,KAAA;EACb;EACA,IAAI,aAAa,KAAA,GAAW;GAG1B,IAAI,KAAKO,oBAAoB,KAAA,GAC3B,KAAKA,kBAAkB,MAAM,KAAKN;GAEpC,OAAO;IAAC,QAAQ;IAAM,QAAQ;GAAiB;EACjD;EAKA,KAAKM,kBAAkB,KAAA;EAMvB,MAAM,OAAO,MAAM,SAAS,aAAa,KAAKR;EAC9C,IACE,QACA,CAAC,kBAAkB,KAAKH,QAAQ,QAAQ,KAAKE,gBAAgB,GAE7D,OAAO;GAAC,QAAQ;GAAM,QAAQ;GAAY;EAAQ;EAKpD,IAAI,CAAC,kBAAkB,KAAKF,QAAQ,QAAQ,KAAKC,YAAY,GAC3D,OAAO;GAAC,QAAQ;GAAM,QAAQ;GAAc;EAAQ;EAEtD,OAAO;GACL,QAAQ;GACR,QAAQ,OAAO,kBAAkB;GACjC;EACF;CACF;CAEA,UAAU,OAA+C;EACvD,OAAO;GAAC,GAAG;GAAO,QAAQ;EAAI;CAChC;AACF;;;;;AAMA,SAAgB,uBACd,IACA,eACA,UACqC;CACrC,IAAI;CACJ,IAAI;EACF,KAAK,IAAI,SACP,GAAG,YAAY,aAAa,+BAA+B,GAC3D,eACA,EAAC,UAAU,KAAI,CACjB;EACA,MAAM,OAAO,kBAAkB,EAAE;EACjC,IACE,KAAK,kBAAA,KACL,KAAK,UAAU,SAAS,SACxB,KAAK,eAAe,SAAS,cAC7B,KAAK,cAAc,SAAS,WAE5B;EAEF,MAAM,SAAS,oBAAoB,EAAE;EACrC,IAAI,OAAO,iBAAiB,QAAQ,OAAO,kBAAkB,MAC3D;EAEF,OAAO;GACL,YAAY,KAAK;GACjB,eAAe,KAAK;GACpB,cAAc,OAAO;GACrB,eAAe,OAAO;EACxB;CACF,QAAQ;EACN;CACF,UAAU;EACR,IAAI,MAAM;CACZ;AACF"}

package/out/zero-cache/src/services/change-streamer/sqlite-change-log-reader.d.ts

@@ -0,0 +1,62 @@
+import type { LogContext } from '@rocicorp/logger';
+import type { WatermarkedChange } from './change-streamer.ts';
+export type CatchupPlan = {
+    readonly kind: 'range';
+    readonly minWatermark: string;
+    readonly headWatermark: string;
+} | {
+    readonly kind: 'ahead';
+    readonly headWatermark: string;
+} | {
+    readonly kind: 'too-old';
+    readonly minWatermark: string;
+    readonly headWatermark: string;
+} | {
+    readonly kind: 'not-ready';
+};
+/**
+ * Seeks to the final position so validating a boundary does not scan every row
+ * of a large transaction. Exported so the focused query-plan test covers the
+ * production subquery.
+ */
+export declare const SQLITE_CHANGE_LOG_BOUNDARY_SQL = "\n  SELECT\n    \"precommit\" = @fromWatermark AND\n      \"tag\" = 'commit' AS \"boundaryExists\"\n  FROM \"_zero.changeLogStream\"\n  WHERE \"watermark\" = @fromWatermark\n  ORDER BY \"pos\" DESC\n  LIMIT 1\n";
+/**
+ * The log describes its own bounds; nothing here reads the replica.
+ * `max("watermark")` is the head because a transaction's rows commit atomically,
+ * so the log never ends mid-transaction.
+ *
+ * `min` and `max` are deliberately kept as *separate* scalar subqueries: SQLite
+ * applies its single-aggregate index optimization only when the aggregate is
+ * alone in its query, so `SELECT min(x), max(x) FROM t` degrades to a full scan
+ * while two scalar subqueries are two index seeks. The query-plan test pins
+ * this.
+ *
+ * Exported so that test can cover the production query.
+ */
+export declare const SQLITE_CHANGE_LOG_PLAN_SQL = "\n  SELECT\n    (SELECT max(\"watermark\") FROM \"_zero.changeLogStream\")\n      AS \"headWatermark\",\n    (SELECT min(\"watermark\") FROM \"_zero.changeLogStream\")\n      AS \"minWatermark\",\n    coalesce((\n  SELECT\n    \"precommit\" = @fromWatermark AND\n      \"tag\" = 'commit' AS \"boundaryExists\"\n  FROM \"_zero.changeLogStream\"\n  WHERE \"watermark\" = @fromWatermark\n  ORDER BY \"pos\" DESC\n  LIMIT 1\n), 0) AS \"boundaryExists\"\n";
+/** Exported so the focused query-plan test covers the production query. */
+export declare const SQLITE_CHANGE_LOG_READ_BATCH_SQL = "\n  SELECT\n    \"watermark\",\n    \"pos\",\n    \"tag\",\n    \"change\"\n  FROM \"_zero.changeLogStream\"\n  WHERE (\"watermark\", \"pos\") > (?, ?)\n    AND \"watermark\" <= ?\n  ORDER BY \"watermark\", \"pos\"\n  LIMIT ?\n";
+/**
+ * Reads the change log without retaining a SQLite snapshot while a consumer
+ * processes a batch.
+ *
+ * The log lives in its own database beside the replica
+ * (`changeLogFileName(replicaFile)`), which this reader opens read-only; it
+ * never opens the replica. The connection therefore keeps the journal mode
+ * configured by the change-log writer. Callers pin a head with {@link plan}
+ * before passing it to {@link read}.
+ *
+ * A change-streamer can start before the replicator has created the log, so the
+ * stream table may not exist yet. Statements are prepared on first use rather
+ * than in the constructor, and {@link plan} reports `not-ready` until they can
+ * be; a reader constructed too early becomes usable once the writer catches up.
+ */
+export declare class SQLiteChangeLogReader implements Disposable {
+    #private;
+    constructor(lc: LogContext, changeLogFile: string);
+    plan(fromWatermark: string): CatchupPlan;
+    read(fromWatermark: string, throughWatermark: string, batchSize: number, signal?: AbortSignal | undefined, maxRows?: number | undefined): AsyncIterable<readonly WatermarkedChange[]>;
+    close(): void;
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=sqlite-change-log-reader.d.ts.map

package/out/zero-cache/src/services/change-streamer/sqlite-change-log-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-change-log-reader.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/sqlite-change-log-reader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AASjD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,sBAAsB,CAAC;AAE5D,MAAM,MAAM,WAAW,GACnB;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,GACD;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAC,GACxD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,GAKD;IAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAC,CAAC;AAiBjC;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,uNAQ1C,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B,ucAOtC,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,gCAAgC,wOAW5C,CAAC;AAMF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,qBAAsB,YAAW,UAAU;;gBAK1C,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM;IAQjD,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,WAAW;IAqBjC,IAAI,CACT,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,MAAM,EACxB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,EAChC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,GAC3B,aAAa,CAAC,SAAS,iBAAiB,EAAE,CAAC;IA6E9C,KAAK,IAAI,IAAI;IAQb,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAuCzB"}

package/out/zero-cache/src/services/change-streamer/sqlite-change-log-reader.js

@@ -0,0 +1,164 @@
+import { assert } from "../../../../shared/src/asserts.js";
+import { AbortError } from "../../../../shared/src/abort-error.js";
+import { Database } from "../../../../zqlite/src/db.js";
+import { CHANGE_LOG_STREAM_TABLE } from "../replicator/change-log-db.js";
+import { reconstructWatermarkedChange } from "./change-log-codec.js";
+//#region ../zero-cache/src/services/change-streamer/sqlite-change-log-reader.ts
+/**
+* Seeks to the final position so validating a boundary does not scan every row
+* of a large transaction. Exported so the focused query-plan test covers the
+* production subquery.
+*/
+var SQLITE_CHANGE_LOG_BOUNDARY_SQL = `
+  SELECT
+    "precommit" = @fromWatermark AND
+      "tag" = 'commit' AS "boundaryExists"
+  FROM "${CHANGE_LOG_STREAM_TABLE}"
+  WHERE "watermark" = @fromWatermark
+  ORDER BY "pos" DESC
+  LIMIT 1
+`;
+/**
+* The log describes its own bounds; nothing here reads the replica.
+* `max("watermark")` is the head because a transaction's rows commit atomically,
+* so the log never ends mid-transaction.
+*
+* `min` and `max` are deliberately kept as *separate* scalar subqueries: SQLite
+* applies its single-aggregate index optimization only when the aggregate is
+* alone in its query, so `SELECT min(x), max(x) FROM t` degrades to a full scan
+* while two scalar subqueries are two index seeks. The query-plan test pins
+* this.
+*
+* Exported so that test can cover the production query.
+*/
+var SQLITE_CHANGE_LOG_PLAN_SQL = `
+  SELECT
+    (SELECT max("watermark") FROM "${CHANGE_LOG_STREAM_TABLE}")
+      AS "headWatermark",
+    (SELECT min("watermark") FROM "${CHANGE_LOG_STREAM_TABLE}")
+      AS "minWatermark",
+    coalesce((${SQLITE_CHANGE_LOG_BOUNDARY_SQL}), 0) AS "boundaryExists"
+`;
+/** Exported so the focused query-plan test covers the production query. */
+var SQLITE_CHANGE_LOG_READ_BATCH_SQL = `
+  SELECT
+    "watermark",
+    "pos",
+    "tag",
+    "change"
+  FROM "${CHANGE_LOG_STREAM_TABLE}"
+  WHERE ("watermark", "pos") > (?, ?)
+    AND "watermark" <= ?
+  ORDER BY "watermark", "pos"
+  LIMIT ?
+`;
+var TABLE_EXISTS_SQL = `
+  SELECT 1 FROM "sqlite_master" WHERE "type" = 'table' AND "name" = ?
+`;
+/**
+* Reads the change log without retaining a SQLite snapshot while a consumer
+* processes a batch.
+*
+* The log lives in its own database beside the replica
+* (`changeLogFileName(replicaFile)`), which this reader opens read-only; it
+* never opens the replica. The connection therefore keeps the journal mode
+* configured by the change-log writer. Callers pin a head with {@link plan}
+* before passing it to {@link read}.
+*
+* A change-streamer can start before the replicator has created the log, so the
+* stream table may not exist yet. Statements are prepared on first use rather
+* than in the constructor, and {@link plan} reports `not-ready` until they can
+* be; a reader constructed too early becomes usable once the writer catches up.
+*/
+var SQLiteChangeLogReader = class {
+	#db;
+	#statements;
+	#closed = false;
+	constructor(lc, changeLogFile) {
+		this.#db = new Database(lc.withContext("component", "sqlite-change-log-reader"), changeLogFile, { readonly: true });
+	}
+	plan(fromWatermark) {
+		this.#assertOpen();
+		const statements = this.#prepare();
+		if (statements === void 0) return { kind: "not-ready" };
+		const row = statements.plan.get({ fromWatermark });
+		if (row.headWatermark === null || row.minWatermark === null) return { kind: "not-ready" };
+		const { headWatermark, minWatermark } = row;
+		if (fromWatermark > headWatermark) return {
+			kind: "ahead",
+			headWatermark
+		};
+		if (fromWatermark < minWatermark || row.boundaryExists === 0) return {
+			kind: "too-old",
+			minWatermark,
+			headWatermark
+		};
+		return {
+			kind: "range",
+			minWatermark,
+			headWatermark
+		};
+	}
+	async *read(fromWatermark, throughWatermark, batchSize, signal, maxRows) {
+		assert(Number.isSafeInteger(batchSize) && batchSize > 0, "SQLite change log batch size must be a positive safe integer");
+		assert(maxRows === void 0 || Number.isSafeInteger(maxRows) && maxRows > 0, "SQLite change log row limit must be a positive safe integer");
+		this.#assertOpen();
+		const statements = this.#prepare();
+		assert(statements !== void 0, "SQLite change log must be ready before it is read");
+		let lastWatermark = fromWatermark;
+		let lastPos = Number.MAX_SAFE_INTEGER;
+		let lastTag;
+		let rowsRead = 0;
+		while (true) {
+			this.#throwIfAborted(signal);
+			const remainingRows = maxRows === void 0 ? batchSize : maxRows - rowsRead;
+			if (remainingRows === 0) break;
+			const rows = statements.readBatch.all(lastWatermark, lastPos, throughWatermark, Math.min(batchSize, remainingRows));
+			this.#throwIfAborted(signal);
+			if (rows.length === 0) break;
+			const changes = rows.map(reconstructWatermarkedChange);
+			const last = rows.at(-1);
+			assert(last !== void 0, "non-empty batch must have a final row");
+			lastWatermark = last.watermark;
+			lastPos = last.pos;
+			lastTag = last.tag;
+			rowsRead += rows.length;
+			yield changes;
+		}
+		if (fromWatermark !== throughWatermark && (maxRows === void 0 || rowsRead < maxRows)) assert(lastWatermark === throughWatermark && lastTag === "commit", () => `SQLite change log did not end at pinned head ${throughWatermark}`);
+	}
+	close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#db.close();
+	}
+	[Symbol.dispose]() {
+		this.close();
+	}
+	/**
+	* Prepares the statements once the stream table exists, memoizing them.
+	* Returns `undefined` while the log has not been created, which is a normal
+	* startup state rather than an error.
+	*/
+	#prepare() {
+		if (this.#statements === void 0 && this.#streamTableExists()) this.#statements = {
+			plan: this.#db.prepare(SQLITE_CHANGE_LOG_PLAN_SQL),
+			readBatch: this.#db.prepare(SQLITE_CHANGE_LOG_READ_BATCH_SQL)
+		};
+		return this.#statements;
+	}
+	#streamTableExists() {
+		return this.#db.prepare(TABLE_EXISTS_SQL).get(CHANGE_LOG_STREAM_TABLE) !== void 0;
+	}
+	#assertOpen() {
+		if (this.#closed) throw new AbortError("SQLite change log reader is closed");
+	}
+	#throwIfAborted(signal) {
+		this.#assertOpen();
+		if (signal?.aborted) throw new AbortError("SQLite change log read aborted");
+	}
+};
+//#endregion
+export { SQLITE_CHANGE_LOG_BOUNDARY_SQL, SQLITE_CHANGE_LOG_PLAN_SQL, SQLiteChangeLogReader };
+
+//# sourceMappingURL=sqlite-change-log-reader.js.map

package/out/zero-cache/src/services/change-streamer/sqlite-change-log-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-change-log-reader.js","names":["#db","#assertOpen","#prepare","#throwIfAborted","#closed","#statements","#streamTableExists"],"sources":["../../../../../../zero-cache/src/services/change-streamer/sqlite-change-log-reader.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {AbortError} from '../../../../shared/src/abort-error.ts';\nimport {assert} from '../../../../shared/src/asserts.ts';\nimport {Database, type Statement} from '../../../../zqlite/src/db.ts';\nimport {CHANGE_LOG_STREAM_TABLE} from '../replicator/change-log-db.ts';\nimport {\n  reconstructWatermarkedChange,\n  type ChangeLogEntry,\n} from './change-log-codec.ts';\nimport type {WatermarkedChange} from './change-streamer.ts';\n\nexport type CatchupPlan =\n  | {\n      readonly kind: 'range';\n      readonly minWatermark: string;\n      readonly headWatermark: string;\n    }\n  | {readonly kind: 'ahead'; readonly headWatermark: string}\n  | {\n      readonly kind: 'too-old';\n      readonly minWatermark: string;\n      readonly headWatermark: string;\n    }\n  // The log exists as a file but has no content to serve: the replicator has\n  // not created or reconciled it yet. Subscriber selection treats this as\n  // \"decline and fall back to PG catchup\", which is why it is a plan rather\n  // than an error.\n  | {readonly kind: 'not-ready'};\n\ntype PlanRow = {\n  readonly headWatermark: string | null;\n  readonly minWatermark: string | null;\n  readonly boundaryExists: number;\n};\n\ntype ChangeLogRow = ChangeLogEntry & {\n  readonly pos: number;\n};\n\ntype PreparedStatements = {\n  readonly plan: Statement;\n  readonly readBatch: Statement;\n};\n\n/**\n * Seeks to the final position so validating a boundary does not scan every row\n * of a large transaction. Exported so the focused query-plan test covers the\n * production subquery.\n */\nexport const SQLITE_CHANGE_LOG_BOUNDARY_SQL = /*sql*/ `\n  SELECT\n    \"precommit\" = @fromWatermark AND\n      \"tag\" = 'commit' AS \"boundaryExists\"\n  FROM \"${CHANGE_LOG_STREAM_TABLE}\"\n  WHERE \"watermark\" = @fromWatermark\n  ORDER BY \"pos\" DESC\n  LIMIT 1\n`;\n\n/**\n * The log describes its own bounds; nothing here reads the replica.\n * `max(\"watermark\")` is the head because a transaction's rows commit atomically,\n * so the log never ends mid-transaction.\n *\n * `min` and `max` are deliberately kept as *separate* scalar subqueries: SQLite\n * applies its single-aggregate index optimization only when the aggregate is\n * alone in its query, so `SELECT min(x), max(x) FROM t` degrades to a full scan\n * while two scalar subqueries are two index seeks. The query-plan test pins\n * this.\n *\n * Exported so that test can cover the production query.\n */\nexport const SQLITE_CHANGE_LOG_PLAN_SQL = /*sql*/ `\n  SELECT\n    (SELECT max(\"watermark\") FROM \"${CHANGE_LOG_STREAM_TABLE}\")\n      AS \"headWatermark\",\n    (SELECT min(\"watermark\") FROM \"${CHANGE_LOG_STREAM_TABLE}\")\n      AS \"minWatermark\",\n    coalesce((${SQLITE_CHANGE_LOG_BOUNDARY_SQL}), 0) AS \"boundaryExists\"\n`;\n\n/** Exported so the focused query-plan test covers the production query. */\nexport const SQLITE_CHANGE_LOG_READ_BATCH_SQL = /*sql*/ `\n  SELECT\n    \"watermark\",\n    \"pos\",\n    \"tag\",\n    \"change\"\n  FROM \"${CHANGE_LOG_STREAM_TABLE}\"\n  WHERE (\"watermark\", \"pos\") > (?, ?)\n    AND \"watermark\" <= ?\n  ORDER BY \"watermark\", \"pos\"\n  LIMIT ?\n`;\n\nconst TABLE_EXISTS_SQL = /*sql*/ `\n  SELECT 1 FROM \"sqlite_master\" WHERE \"type\" = 'table' AND \"name\" = ?\n`;\n\n/**\n * Reads the change log without retaining a SQLite snapshot while a consumer\n * processes a batch.\n *\n * The log lives in its own database beside the replica\n * (`changeLogFileName(replicaFile)`), which this reader opens read-only; it\n * never opens the replica. The connection therefore keeps the journal mode\n * configured by the change-log writer. Callers pin a head with {@link plan}\n * before passing it to {@link read}.\n *\n * A change-streamer can start before the replicator has created the log, so the\n * stream table may not exist yet. Statements are prepared on first use rather\n * than in the constructor, and {@link plan} reports `not-ready` until they can\n * be; a reader constructed too early becomes usable once the writer catches up.\n */\nexport class SQLiteChangeLogReader implements Disposable {\n  readonly #db: Database;\n  #statements: PreparedStatements | undefined;\n  #closed = false;\n\n  constructor(lc: LogContext, changeLogFile: string) {\n    this.#db = new Database(\n      lc.withContext('component', 'sqlite-change-log-reader'),\n      changeLogFile,\n      {readonly: true},\n    );\n  }\n\n  plan(fromWatermark: string): CatchupPlan {\n    this.#assertOpen();\n    const statements = this.#prepare();\n    if (statements === undefined) {\n      return {kind: 'not-ready'};\n    }\n    const row = statements.plan.get<PlanRow>({fromWatermark});\n    if (row.headWatermark === null || row.minWatermark === null) {\n      return {kind: 'not-ready'};\n    }\n    const {headWatermark, minWatermark} = row;\n\n    if (fromWatermark > headWatermark) {\n      return {kind: 'ahead', headWatermark};\n    }\n    if (fromWatermark < minWatermark || row.boundaryExists === 0) {\n      return {kind: 'too-old', minWatermark, headWatermark};\n    }\n    return {kind: 'range', minWatermark, headWatermark};\n  }\n\n  async *read(\n    fromWatermark: string,\n    throughWatermark: string,\n    batchSize: number,\n    signal?: AbortSignal | undefined,\n    maxRows?: number | undefined,\n  ): AsyncIterable<readonly WatermarkedChange[]> {\n    assert(\n      Number.isSafeInteger(batchSize) && batchSize > 0,\n      'SQLite change log batch size must be a positive safe integer',\n    );\n    assert(\n      maxRows === undefined || (Number.isSafeInteger(maxRows) && maxRows > 0),\n      'SQLite change log row limit must be a positive safe integer',\n    );\n    this.#assertOpen();\n    const statements = this.#prepare();\n    assert(\n      statements !== undefined,\n      'SQLite change log must be ready before it is read',\n    );\n\n    let lastWatermark = fromWatermark;\n    // The first query must be strictly after the requested transaction. Every\n    // real stream position is far below this sentinel.\n    let lastPos = Number.MAX_SAFE_INTEGER;\n    let lastTag: string | undefined;\n    let rowsRead = 0;\n\n    while (true) {\n      this.#throwIfAborted(signal);\n      const remainingRows =\n        maxRows === undefined ? batchSize : maxRows - rowsRead;\n      if (remainingRows === 0) {\n        break;\n      }\n      const rows = statements.readBatch.all<ChangeLogRow>(\n        lastWatermark,\n        lastPos,\n        throughWatermark,\n        Math.min(batchSize, remainingRows),\n      );\n      this.#throwIfAborted(signal);\n\n      if (rows.length === 0) {\n        break;\n      }\n\n      const changes = rows.map(reconstructWatermarkedChange);\n      const last = rows.at(-1);\n      assert(last !== undefined, 'non-empty batch must have a final row');\n      lastWatermark = last.watermark;\n      lastPos = last.pos;\n      lastTag = last.tag;\n      rowsRead += rows.length;\n\n      // all() has exhausted the SELECT and closed its implicit read\n      // transaction. This yield therefore cannot pin the WAL while subscriber\n      // flow control is pending.\n      yield changes;\n    }\n\n    // `throughWatermark` was pinned from `max(\"watermark\")` of this same table,\n    // so reaching it no longer depends on the log agreeing with the replica's\n    // `_zero.replicationState`, which is what this assertion used to guard.\n    // What remains is a concurrent purge of the head transaction, which the\n    // purge policy (never past the latest durable transaction) does not do.\n    // A read that stopped at `maxRows` cannot know whether more rows follow,\n    // so completeness is only asserted for a read that ran out on its own.\n    // Detecting a short bounded read is left to the caller, which set the\n    // limit and is the only side that knows what a full range should hold.\n    if (\n      fromWatermark !== throughWatermark &&\n      (maxRows === undefined || rowsRead < maxRows)\n    ) {\n      assert(\n        lastWatermark === throughWatermark && lastTag === 'commit',\n        () =>\n          `SQLite change log did not end at pinned head ${throughWatermark}`,\n      );\n    }\n  }\n\n  close(): void {\n    if (this.#closed) {\n      return;\n    }\n    this.#closed = true;\n    this.#db.close();\n  }\n\n  [Symbol.dispose](): void {\n    this.close();\n  }\n\n  /**\n   * Prepares the statements once the stream table exists, memoizing them.\n   * Returns `undefined` while the log has not been created, which is a normal\n   * startup state rather than an error.\n   */\n  #prepare(): PreparedStatements | undefined {\n    if (this.#statements === undefined && this.#streamTableExists()) {\n      this.#statements = {\n        plan: this.#db.prepare(SQLITE_CHANGE_LOG_PLAN_SQL),\n        readBatch: this.#db.prepare(SQLITE_CHANGE_LOG_READ_BATCH_SQL),\n      };\n    }\n    return this.#statements;\n  }\n\n  #streamTableExists(): boolean {\n    return (\n      this.#db\n        .prepare(TABLE_EXISTS_SQL)\n        .get<{1: number} | undefined>(CHANGE_LOG_STREAM_TABLE) !== undefined\n    );\n  }\n\n  #assertOpen(): void {\n    if (this.#closed) {\n      throw new AbortError('SQLite change log reader is closed');\n    }\n  }\n\n  #throwIfAborted(signal: AbortSignal | undefined): void {\n    this.#assertOpen();\n    if (signal?.aborted) {\n      throw new AbortError('SQLite change log read aborted');\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;AAiDA,IAAa,iCAAyC;;;;UAI5C,wBAAwB;;;;;;;;;;;;;;;;;;AAmBlC,IAAa,6BAAqC;;qCAEb,wBAAwB;;qCAExB,wBAAwB;;gBAE7C,+BAA+B;;;AAI/C,IAAa,mCAA2C;;;;;;UAM9C,wBAAwB;;;;;;AAOlC,IAAM,mBAA2B;;;;;;;;;;;;;;;;;;AAmBjC,IAAa,wBAAb,MAAyD;CACvD;CACA;CACA,UAAU;CAEV,YAAY,IAAgB,eAAuB;EACjD,KAAKA,MAAM,IAAI,SACb,GAAG,YAAY,aAAa,0BAA0B,GACtD,eACA,EAAC,UAAU,KAAI,CACjB;CACF;CAEA,KAAK,eAAoC;EACvC,KAAKC,YAAY;EACjB,MAAM,aAAa,KAAKC,SAAS;EACjC,IAAI,eAAe,KAAA,GACjB,OAAO,EAAC,MAAM,YAAW;EAE3B,MAAM,MAAM,WAAW,KAAK,IAAa,EAAC,cAAa,CAAC;EACxD,IAAI,IAAI,kBAAkB,QAAQ,IAAI,iBAAiB,MACrD,OAAO,EAAC,MAAM,YAAW;EAE3B,MAAM,EAAC,eAAe,iBAAgB;EAEtC,IAAI,gBAAgB,eAClB,OAAO;GAAC,MAAM;GAAS;EAAa;EAEtC,IAAI,gBAAgB,gBAAgB,IAAI,mBAAmB,GACzD,OAAO;GAAC,MAAM;GAAW;GAAc;EAAa;EAEtD,OAAO;GAAC,MAAM;GAAS;GAAc;EAAa;CACpD;CAEA,OAAO,KACL,eACA,kBACA,WACA,QACA,SAC6C;EAC7C,OACE,OAAO,cAAc,SAAS,KAAK,YAAY,GAC/C,8DACF;EACA,OACE,YAAY,KAAA,KAAc,OAAO,cAAc,OAAO,KAAK,UAAU,GACrE,6DACF;EACA,KAAKD,YAAY;EACjB,MAAM,aAAa,KAAKC,SAAS;EACjC,OACE,eAAe,KAAA,GACf,mDACF;EAEA,IAAI,gBAAgB;EAGpB,IAAI,UAAU,OAAO;EACrB,IAAI;EACJ,IAAI,WAAW;EAEf,OAAO,MAAM;GACX,KAAKC,gBAAgB,MAAM;GAC3B,MAAM,gBACJ,YAAY,KAAA,IAAY,YAAY,UAAU;GAChD,IAAI,kBAAkB,GACpB;GAEF,MAAM,OAAO,WAAW,UAAU,IAChC,eACA,SACA,kBACA,KAAK,IAAI,WAAW,aAAa,CACnC;GACA,KAAKA,gBAAgB,MAAM;GAE3B,IAAI,KAAK,WAAW,GAClB;GAGF,MAAM,UAAU,KAAK,IAAI,4BAA4B;GACrD,MAAM,OAAO,KAAK,GAAG,EAAE;GACvB,OAAO,SAAS,KAAA,GAAW,uCAAuC;GAClE,gBAAgB,KAAK;GACrB,UAAU,KAAK;GACf,UAAU,KAAK;GACf,YAAY,KAAK;GAKjB,MAAM;EACR;EAWA,IACE,kBAAkB,qBACjB,YAAY,KAAA,KAAa,WAAW,UAErC,OACE,kBAAkB,oBAAoB,YAAY,gBAEhD,gDAAgD,kBACpD;CAEJ;CAEA,QAAc;EACZ,IAAI,KAAKC,SACP;EAEF,KAAKA,UAAU;EACf,KAAKJ,IAAI,MAAM;CACjB;CAEA,CAAC,OAAO,WAAiB;EACvB,KAAK,MAAM;CACb;;;;;;CAOA,WAA2C;EACzC,IAAI,KAAKK,gBAAgB,KAAA,KAAa,KAAKC,mBAAmB,GAC5D,KAAKD,cAAc;GACjB,MAAM,KAAKL,IAAI,QAAQ,0BAA0B;GACjD,WAAW,KAAKA,IAAI,QAAQ,gCAAgC;EAC9D;EAEF,OAAO,KAAKK;CACd;CAEA,qBAA8B;EAC5B,OACE,KAAKL,IACF,QAAQ,gBAAgB,EACxB,IAA6B,uBAAuB,MAAM,KAAA;CAEjE;CAEA,cAAoB;EAClB,IAAI,KAAKI,SACP,MAAM,IAAI,WAAW,oCAAoC;CAE7D;CAEA,gBAAgB,QAAuC;EACrD,KAAKH,YAAY;EACjB,IAAI,QAAQ,SACV,MAAM,IAAI,WAAW,gCAAgC;CAEzD;AACF"}

package/out/zero-cache/src/services/change-streamer/sqlite-change-log-writer.d.ts

@@ -0,0 +1,109 @@
+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 ChangeLogIdentity, type ChangeLogResumePoint } from '../replicator/change-log-db.ts';
+import { type SQLiteChangeLogObservabilityState } from '../replicator/sqlite-change-log-observability.ts';
+export type SQLiteChangeLogWriterOptions = {
+    /** The replica file the log is named after, i.e. `${replicaFile}-change-log`. */
+    replicaFile: string;
+    /** The replica whose contents this log belongs to. */
+    identity: ChangeLogIdentity;
+    /**
+     * Called after each transaction's log commit, with the log's new head. This
+     * is what releases the catchup barrier: after the writer moved in-process,
+     * the head advances here rather than at a subscriber's ACK.
+     */
+    onCommit?: ((watermark: string) => void) | undefined;
+    /**
+     * Called when the writer disables itself and deletes the file. The reader is
+     * cached on the service, so a delete that leaves it open would leave an
+     * in-process reader serving an unlinked inode while every new open sees
+     * nothing.
+     */
+    onDisabled?: (() => void) | undefined;
+    /** Called when reconciliation replaces the file, to close cached readers. */
+    onRebuilt?: (() => void) | undefined;
+    /** Overridable for tests. */
+    now?: (() => number) | undefined;
+};
+/**
+ * Appends the canonical change stream to the SQLite change log, from the
+ * change-streamer's own stream loop.
+ *
+ * ### Ordering
+ *
+ * The log's commit for a transaction precedes the forward of that transaction's
+ * `commit` message, and nothing `await`s in between. Everything that can
+ * advance the watermark the stream would resume from — the storer's Postgres
+ * commit, `lastWatermark`, the upstream ACK — runs strictly after it, so the
+ * log's head is always at or above the resume point. A *hole* is therefore
+ * unreachable at any crash timing, and a *phantom* is the normal state, which is
+ * what makes truncate-above the whole of reconciliation.
+ *
+ * ### Fail-soft
+ *
+ * The log is a catchup cache: nothing in it is not either already durable in the
+ * replica's litestream backup or re-derivable from the replication slot. A write
+ * failure must therefore not stop replication for the shard. Corruption is
+ * rebuilt once at open; any other write error — a full disk, an I/O error, a
+ * permissions problem — logs, disables the writer, deletes the file, closes the
+ * reader, and lets the stream continue. The cost is catchup reach, and reach is
+ * recoverable: `too-old` sends a subscriber to a restore.
+ *
+ * One carve-out keeps that from hiding the bug class this topology introduces. A
+ * missed truncate-above surfaces as `SQLITE_CONSTRAINT` on the writer's plain
+ * `INSERT`, which is "any write error other than corruption" and would be
+ * absorbed quietly. It is counted as an invariant failure and alerted on before
+ * failing soft.
+ */
+export declare class SQLiteChangeLogWriter {
+    #private;
+    constructor(lc: LogContext, opts: SQLiteChangeLogWriterOptions);
+    /** False once the writer has failed soft, or after {@link close}. */
+    get enabled(): boolean;
+    /**
+     * The writer's own connection, which is the one purge runs on (§3.3): one
+     * process appends *and* deletes, on one handle, with no second writable
+     * connection and no cross-process barrier. `undefined` until the stream
+     * loop's first reconcile creates the log, and again once the writer has
+     * failed soft and deleted the file — both of which a purge cycle treats as
+     * "skip", not as an error.
+     */
+    get connection(): Database | undefined;
+    /** Exposed for tests and for the integration assertions on the metrics. */
+    state(): SQLiteChangeLogObservabilityState | undefined;
+    /**
+     * Opens the log if necessary and reconciles it with the Postgres resume
+     * point. Returns the resume point stored in the log.
+     *
+     * Returns `undefined` when the writer is disabled. The caller must then use
+     * another source.
+     *
+     * This runs for every connection because Postgres supplies a new resume point
+     * after each reconnect. The log can contain transactions above that point.
+     * Reconciliation removes them before Postgres sends them again.
+     *
+     * `resumeFrom` includes cookies because the cookies must match the resume
+     * watermark.
+     */
+    reconcile(resumeFrom: ChangeLogResumePoint): ChangeLogResumePoint | undefined;
+    /**
+     * Reconciles the log without a Postgres resume point.
+     *
+     * A valid log uses its own head and cookies. A new or invalid log uses the
+     * replica values returned by `seed`.
+     */
+    reconcileFromLog(seed: () => ChangeLogResumePoint): ChangeLogResumePoint | undefined;
+    /**
+     * Writes one stream message, committing at transaction boundaries. Never
+     * throws: a write failure disables the writer instead of failing the stream.
+     */
+    write(change: ChangeStreamData, json: string): void;
+    /**
+     * Discards the open transaction, if any. Called when the change stream is
+     * interrupted mid-transaction.
+     */
+    abort(): void;
+    close(): void;
+}
+//# sourceMappingURL=sqlite-change-log-writer.d.ts.map

package/out/zero-cache/src/services/change-streamer/sqlite-change-log-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-change-log-writer.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/sqlite-change-log-writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAGjD,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,8BAA8B,CAAC;AAM3D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,iDAAiD,CAAC;AAKtF,OAAO,EAUL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAE1B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAML,KAAK,iCAAiC,EACvC,MAAM,kDAAkD,CAAC;AAE1D,MAAM,MAAM,4BAA4B,GAAG;IACzC,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACrD;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IACtC,6EAA6E;IAC7E,SAAS,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IACrC,6BAA6B;IAC7B,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,qBAAqB;;gBAUpB,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,4BAA4B;IAM9D,qEAAqE;IACrE,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;;;OAOG;IACH,IAAI,UAAU,IAAI,QAAQ,GAAG,SAAS,CAErC;IAED,2EAA2E;IAC3E,KAAK,IAAI,iCAAiC,GAAG,SAAS;IAItD;;;;;;;;;;;;;OAaG;IACH,SAAS,CACP,UAAU,EAAE,oBAAoB,GAC/B,oBAAoB,GAAG,SAAS;IAInC;;;;;OAKG;IACH,gBAAgB,CACd,IAAI,EAAE,MAAM,oBAAoB,GAC/B,oBAAoB,GAAG,SAAS;IA6GnC;;;OAGG;IACH,KAAK,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAkEnD;;;OAGG;IACH,KAAK,IAAI,IAAI;IAab,KAAK,IAAI,IAAI;CAwCd"}