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

package/out/zero-cache/src/db/migration.js

@@ -136,6 +136,6 @@ function getMinSafeVersion(log, current, proposedSafeVersion) {
 	return proposedSafeVersion;
 }
 //#endregion
-export { getVersionHistory, runSchemaMigrations };
+export { runSchemaMigrations };
 
 //# sourceMappingURL=migration.js.map

package/out/zero-cache/src/observability/metrics.d.ts

@@ -27,6 +27,11 @@ export type LatencyHistogram = {
      */
     recordMs(durationMs: number, attributes?: Parameters<Histogram['record']>[1]): void;
 };
+/**
+ * Creates a histogram for dimensionless values without applying the
+ * millisecond-to-second conversion used by the latency helpers below.
+ */
+export declare function getOrCreateValueHistogram(category: Category, name: string, opts: HistogramOptions): Histogram;
 export declare function getOrCreateHistogram(category: Category, name: string, opts: HistogramOptions): LatencyHistogram;
 export declare function getOrCreateNativeHistogram(category: Category, name: string, opts: Options): LatencyHistogram;
 /**

package/out/zero-cache/src/observability/metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/observability/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EAET,aAAa,EACb,eAAe,EACf,aAAa,EACd,MAAM,oBAAoB,CAAC;AAK5B,MAAM,MAAM,QAAQ,GAChB,aAAa,GACb,SAAS,GACT,MAAM,GACN,UAAU,GACV,QAAQ,CAAC;AAIb,KAAK,OAAO,GAAG,aAAa,GAAG;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAAC;AACrD,KAAK,gBAAgB,GAAG,OAAO,GAAG;IAAC,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAAC,CAAC;AAE/D,eAAO,MAAM,iCAAiC,wGAIpC,CAAC;AAEX,eAAO,MAAM,oCAAoC,UAEhD,CAAC;AA4BF,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,aAAa,CAAC;AACjB,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,aAAa,CAAC;AAcjB;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;;;OAMG;IACH,QAAQ,CACN,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAC9C,IAAI,CAAC;CACT,CAAC;AAoBF,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,GACrB,gBAAgB,CAelB;AAKD,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,gBAAgB,CAQlB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,gBAAgB,CAMlB;AAID,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;AACX,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC;AAgBX,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,eAAe,CAAC;AACnB,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,eAAe,CAAC"}
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/observability/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EAET,aAAa,EACb,eAAe,EACf,aAAa,EACd,MAAM,oBAAoB,CAAC;AAK5B,MAAM,MAAM,QAAQ,GAChB,aAAa,GACb,SAAS,GACT,MAAM,GACN,UAAU,GACV,QAAQ,CAAC;AAIb,KAAK,OAAO,GAAG,aAAa,GAAG;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAAC;AACrD,KAAK,gBAAgB,GAAG,OAAO,GAAG;IAAC,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAAC,CAAC;AAE/D,eAAO,MAAM,iCAAiC,wGAIpC,CAAC;AAEX,eAAO,MAAM,oCAAoC,UAEhD,CAAC;AA4BF,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,aAAa,CAAC;AACjB,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,aAAa,CAAC;AAcjB;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;;;OAMG;IACH,QAAQ,CACN,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAC9C,IAAI,CAAC;CACT,CAAC;AAoBF;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,GACrB,SAAS,CAWX;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,GACrB,gBAAgB,CAelB;AAKD,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,gBAAgB,CAQlB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,gBAAgB,CAMlB;AAID,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;AACX,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC;AAgBX,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,eAAe,CAAC;AACnB,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,eAAe,CAAC"}

package/out/zero-cache/src/observability/metrics.js

@@ -68,6 +68,20 @@ var LATENCY_HISTOGRAM_BOUNDARIES_S = [
 	30
 ];
 var histograms = cache();
+/**
+* Creates a histogram for dimensionless values without applying the
+* millisecond-to-second conversion used by the latency helpers below.
+*/
+function getOrCreateValueHistogram(category, name, opts) {
+	const { bucketBoundaries, ...metricOptions } = opts;
+	return histograms(name, (name) => getMeter().createHistogram(`zero.${category}.${name}`, {
+		...metricOptions,
+		advice: {
+			...metricOptions.advice,
+			explicitBucketBoundaries: bucketBoundaries
+		}
+	}));
+}
 function getOrCreateHistogram(category, name, opts) {
 	const { bucketBoundaries, ...metricOptions } = opts;
 	const h = histograms(name, (name) => getMeter().createHistogram(`zero.${category}.${name}`, {
@@ -117,6 +131,6 @@ function getOrCreateGauge(category, name, opts) {
 	return gauges(name, (name) => getMeter().createObservableGauge(`zero.${category}.${name}`, typeof opts === "string" ? { description: opts } : opts));
 }
 //#endregion
-export { LONG_DURATION_HISTOGRAM_BOUNDARIES_S, NATIVE_HISTOGRAM_INSTRUMENT_NAMES, getOrCreateCounter, getOrCreateGauge, getOrCreateHistogram, getOrCreateLatencyHistogram, getOrCreateNativeHistogram, getOrCreateUpDownCounter };
+export { LONG_DURATION_HISTOGRAM_BOUNDARIES_S, NATIVE_HISTOGRAM_INSTRUMENT_NAMES, getOrCreateCounter, getOrCreateGauge, getOrCreateHistogram, getOrCreateLatencyHistogram, getOrCreateNativeHistogram, getOrCreateUpDownCounter, getOrCreateValueHistogram };
 
 //# sourceMappingURL=metrics.js.map

package/out/zero-cache/src/observability/metrics.js.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.js","names":[],"sources":["../../../../../zero-cache/src/observability/metrics.ts"],"sourcesContent":["import type {\n  Counter,\n  Histogram,\n  Meter,\n  MetricOptions,\n  ObservableGauge,\n  UpDownCounter,\n} from '@opentelemetry/api';\nimport {metrics} from '@opentelemetry/api';\n\n// intentional lazy initialization so it is not started before the SDK is started.\n\nexport type Category =\n  | 'replication' // postgres to replica\n  | 'replica' // health of replica and litestream backup\n  | 'sync' // replica to client\n  | 'mutation'\n  | 'server';\n\nlet meter: Meter | undefined;\n\ntype Options = MetricOptions & {description: string};\ntype HistogramOptions = Options & {bucketBoundaries: number[]};\n\nexport const NATIVE_HISTOGRAM_INSTRUMENT_NAMES = [\n  'zero.sync.view_syncer_lag',\n  'zero.sync.view_syncer_hydration',\n  'zero.sync.e2e_serving_lag',\n] as const;\n\nexport const LONG_DURATION_HISTOGRAM_BOUNDARIES_S = [\n  1, 2, 5, 10, 30, 60, 120, 300, 600, 1200, 2400, 3600, 7200,\n];\n\nfunction getMeter() {\n  if (!meter) {\n    meter = metrics.getMeter('zero');\n  }\n  return meter;\n}\n\nfunction cache<TRet>(): (\n  name: string,\n  creator: (name: string) => TRet,\n) => TRet {\n  const instruments = new Map<string, TRet>();\n  return (name: string, creator: (name: string) => TRet) => {\n    const existing = instruments.get(name);\n    if (existing) {\n      return existing;\n    }\n\n    const ret = creator(name);\n    instruments.set(name, ret);\n    return ret;\n  };\n}\n\nconst upDownCounters = cache<UpDownCounter>();\n\nexport function getOrCreateUpDownCounter(\n  category: Category,\n  name: string,\n  description: string,\n): UpDownCounter;\nexport function getOrCreateUpDownCounter(\n  category: Category,\n  name: string,\n  opts: Options,\n): UpDownCounter;\nexport function getOrCreateUpDownCounter(\n  category: Category,\n  name: string,\n  opts: string | Options,\n): UpDownCounter {\n  return upDownCounters(name, name =>\n    getMeter().createUpDownCounter(\n      `zero.${category}.${name}`,\n      typeof opts === 'string' ? {description: opts} : opts,\n    ),\n  );\n}\n\n/**\n * A latency histogram whose {@link recordMs} method accepts raw millisecond\n * durations and converts them to seconds internally.\n *\n * Use {@link getOrCreateLatencyHistogram} to create one — the unit (`'s'`),\n * bucket boundaries, and ms→s conversion are all baked in\n */\nexport type LatencyHistogram = {\n  /**\n   * Record a duration. Pass the raw elapsed milliseconds — the conversion to\n   * seconds (required by the `unit: 's'` OTel histogram) is handled internally.\n   *\n   * @param durationMs  Elapsed time in **milliseconds** (do NOT pre-divide).\n   * @param attributes  Optional OTel attributes to attach to the observation.\n   */\n  recordMs(\n    durationMs: number,\n    attributes?: Parameters<Histogram['record']>[1],\n  ): void;\n};\n\n/**\n * Bucket boundaries (in seconds) for zero's latency histograms.\n *\n * The operational range is 1 ms – 5,000 ms (including customers actively\n * tuning queries). ~2× logarithmic steps give proportionally consistent\n * `histogram_quantile` accuracy regardless of where values cluster within\n * that range. 10,000 ms and 30,000 ms are overflow catchers for truly broken\n * states.\n *\n *   1 ms, 2 ms, 5 ms, 10 ms, 20 ms, 50 ms, 100 ms, 200 ms, 500 ms,\n *   1 s, 2 s, 5 s, 10 s, 30 s\n */\nconst LATENCY_HISTOGRAM_BOUNDARIES_S = [\n  0.001, 0.002, 0.005, 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30,\n];\n\nconst histograms = cache<Histogram>();\n\nexport function getOrCreateHistogram(\n  category: Category,\n  name: string,\n  opts: HistogramOptions,\n): LatencyHistogram {\n  const {bucketBoundaries, ...metricOptions} = opts;\n  const h = histograms(name, name =>\n    getMeter().createHistogram(`zero.${category}.${name}`, {\n      ...metricOptions,\n      advice: {\n        ...metricOptions.advice,\n        explicitBucketBoundaries: bucketBoundaries,\n      },\n    }),\n  );\n  return {\n    recordMs: (durationMs, attributes) =>\n      h.record(durationMs / 1000, attributes),\n  };\n}\n\n// Add instruments created through this helper to\n// NATIVE_HISTOGRAM_INSTRUMENT_NAMES so the SDK exports them as exponential\n// histograms.\nexport function getOrCreateNativeHistogram(\n  category: Category,\n  name: string,\n  opts: Options,\n): LatencyHistogram {\n  const h = histograms(name, name =>\n    getMeter().createHistogram(`zero.${category}.${name}`, opts),\n  );\n  return {\n    recordMs: (durationMs, attributes) =>\n      h.record(durationMs / 1000, attributes),\n  };\n}\n\n/**\n * Creates (or retrieves) a latency histogram for the given metric.\n *\n * - `unit` is always `'s'` (seconds), matching the OTel convention.\n * - Bucket boundaries are pre-set for zero's typical operation range\n *   (1 ms – 5 s); see {@link LATENCY_HISTOGRAM_BOUNDARIES_S}.\n * - The returned {@link LatencyHistogram} accepts **milliseconds** via\n *   `recordMs()`, so callers never need to divide by 1000.\n *\n * @example\n * ```ts\n * readonly #hydrationTime = getOrCreateLatencyHistogram(\n *   'sync', 'hydration-time', 'Time to hydrate a query.',\n * );\n * // ...\n * this.#hydrationTime.recordMs(performance.now() - start);\n * ```\n */\nexport function getOrCreateLatencyHistogram(\n  category: Category,\n  name: string,\n  description: string,\n): LatencyHistogram {\n  return getOrCreateHistogram(category, name, {\n    description,\n    unit: 's',\n    bucketBoundaries: LATENCY_HISTOGRAM_BOUNDARIES_S,\n  });\n}\n\nconst counters = cache<Counter>();\n\nexport function getOrCreateCounter(\n  category: Category,\n  name: string,\n  description: string,\n): Counter;\nexport function getOrCreateCounter(\n  category: Category,\n  name: string,\n  opts: Options,\n): Counter;\nexport function getOrCreateCounter(\n  category: Category,\n  name: string,\n  opts: string | Options,\n): Counter {\n  return counters(name, name =>\n    getMeter().createCounter(\n      `zero.${category}.${name}`,\n      typeof opts === 'string' ? {description: opts} : opts,\n    ),\n  );\n}\n\nconst gauges = cache<ObservableGauge>();\n\nexport function getOrCreateGauge(\n  category: Category,\n  name: string,\n  description: string,\n): ObservableGauge;\nexport function getOrCreateGauge(\n  category: Category,\n  name: string,\n  opts: Options,\n): ObservableGauge;\nexport function getOrCreateGauge(\n  category: Category,\n  name: string,\n  opts: string | Options,\n): ObservableGauge {\n  return gauges(name, name =>\n    getMeter().createObservableGauge(\n      `zero.${category}.${name}`,\n      typeof opts === 'string' ? {description: opts} : opts,\n    ),\n  );\n}\n"],"mappings":";;AAmBA,IAAI;AAKJ,IAAa,oCAAoC;CAC/C;CACA;CACA;AACF;AAEA,IAAa,uCAAuC;CAClD;CAAG;CAAG;CAAG;CAAI;CAAI;CAAI;CAAK;CAAK;CAAK;CAAM;CAAM;CAAM;AACxD;AAEA,SAAS,WAAW;CAClB,IAAI,CAAC,OACH,QAAQ,QAAQ,SAAS,MAAM;CAEjC,OAAO;AACT;AAEA,SAAS,QAGC;CACR,MAAM,8BAAc,IAAI,IAAkB;CAC1C,QAAQ,MAAc,YAAoC;EACxD,MAAM,WAAW,YAAY,IAAI,IAAI;EACrC,IAAI,UACF,OAAO;EAGT,MAAM,MAAM,QAAQ,IAAI;EACxB,YAAY,IAAI,MAAM,GAAG;EACzB,OAAO;CACT;AACF;AAEA,IAAM,iBAAiB,MAAqB;AAY5C,SAAgB,yBACd,UACA,MACA,MACe;CACf,OAAO,eAAe,OAAM,SAC1B,SAAS,EAAE,oBACT,QAAQ,SAAS,GAAG,QACpB,OAAO,SAAS,WAAW,EAAC,aAAa,KAAI,IAAI,IACnD,CACF;AACF;;;;;;;;;;;;;AAmCA,IAAM,iCAAiC;CACrC;CAAO;CAAO;CAAO;CAAM;CAAM;CAAM;CAAK;CAAK;CAAK;CAAG;CAAG;CAAG;CAAI;AACrE;AAEA,IAAM,aAAa,MAAiB;AAEpC,SAAgB,qBACd,UACA,MACA,MACkB;CAClB,MAAM,EAAC,kBAAkB,GAAG,kBAAiB;CAC7C,MAAM,IAAI,WAAW,OAAM,SACzB,SAAS,EAAE,gBAAgB,QAAQ,SAAS,GAAG,QAAQ;EACrD,GAAG;EACH,QAAQ;GACN,GAAG,cAAc;GACjB,0BAA0B;EAC5B;CACF,CAAC,CACH;CACA,OAAO,EACL,WAAW,YAAY,eACrB,EAAE,OAAO,aAAa,KAAM,UAAU,EAC1C;AACF;AAKA,SAAgB,2BACd,UACA,MACA,MACkB;CAClB,MAAM,IAAI,WAAW,OAAM,SACzB,SAAS,EAAE,gBAAgB,QAAQ,SAAS,GAAG,QAAQ,IAAI,CAC7D;CACA,OAAO,EACL,WAAW,YAAY,eACrB,EAAE,OAAO,aAAa,KAAM,UAAU,EAC1C;AACF;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,4BACd,UACA,MACA,aACkB;CAClB,OAAO,qBAAqB,UAAU,MAAM;EAC1C;EACA,MAAM;EACN,kBAAkB;CACpB,CAAC;AACH;AAEA,IAAM,WAAW,MAAe;AAYhC,SAAgB,mBACd,UACA,MACA,MACS;CACT,OAAO,SAAS,OAAM,SACpB,SAAS,EAAE,cACT,QAAQ,SAAS,GAAG,QACpB,OAAO,SAAS,WAAW,EAAC,aAAa,KAAI,IAAI,IACnD,CACF;AACF;AAEA,IAAM,SAAS,MAAuB;AAYtC,SAAgB,iBACd,UACA,MACA,MACiB;CACjB,OAAO,OAAO,OAAM,SAClB,SAAS,EAAE,sBACT,QAAQ,SAAS,GAAG,QACpB,OAAO,SAAS,WAAW,EAAC,aAAa,KAAI,IAAI,IACnD,CACF;AACF"}
+{"version":3,"file":"metrics.js","names":[],"sources":["../../../../../zero-cache/src/observability/metrics.ts"],"sourcesContent":["import type {\n  Counter,\n  Histogram,\n  Meter,\n  MetricOptions,\n  ObservableGauge,\n  UpDownCounter,\n} from '@opentelemetry/api';\nimport {metrics} from '@opentelemetry/api';\n\n// intentional lazy initialization so it is not started before the SDK is started.\n\nexport type Category =\n  | 'replication' // postgres to replica\n  | 'replica' // health of replica and litestream backup\n  | 'sync' // replica to client\n  | 'mutation'\n  | 'server';\n\nlet meter: Meter | undefined;\n\ntype Options = MetricOptions & {description: string};\ntype HistogramOptions = Options & {bucketBoundaries: number[]};\n\nexport const NATIVE_HISTOGRAM_INSTRUMENT_NAMES = [\n  'zero.sync.view_syncer_lag',\n  'zero.sync.view_syncer_hydration',\n  'zero.sync.e2e_serving_lag',\n] as const;\n\nexport const LONG_DURATION_HISTOGRAM_BOUNDARIES_S = [\n  1, 2, 5, 10, 30, 60, 120, 300, 600, 1200, 2400, 3600, 7200,\n];\n\nfunction getMeter() {\n  if (!meter) {\n    meter = metrics.getMeter('zero');\n  }\n  return meter;\n}\n\nfunction cache<TRet>(): (\n  name: string,\n  creator: (name: string) => TRet,\n) => TRet {\n  const instruments = new Map<string, TRet>();\n  return (name: string, creator: (name: string) => TRet) => {\n    const existing = instruments.get(name);\n    if (existing) {\n      return existing;\n    }\n\n    const ret = creator(name);\n    instruments.set(name, ret);\n    return ret;\n  };\n}\n\nconst upDownCounters = cache<UpDownCounter>();\n\nexport function getOrCreateUpDownCounter(\n  category: Category,\n  name: string,\n  description: string,\n): UpDownCounter;\nexport function getOrCreateUpDownCounter(\n  category: Category,\n  name: string,\n  opts: Options,\n): UpDownCounter;\nexport function getOrCreateUpDownCounter(\n  category: Category,\n  name: string,\n  opts: string | Options,\n): UpDownCounter {\n  return upDownCounters(name, name =>\n    getMeter().createUpDownCounter(\n      `zero.${category}.${name}`,\n      typeof opts === 'string' ? {description: opts} : opts,\n    ),\n  );\n}\n\n/**\n * A latency histogram whose {@link recordMs} method accepts raw millisecond\n * durations and converts them to seconds internally.\n *\n * Use {@link getOrCreateLatencyHistogram} to create one — the unit (`'s'`),\n * bucket boundaries, and ms→s conversion are all baked in\n */\nexport type LatencyHistogram = {\n  /**\n   * Record a duration. Pass the raw elapsed milliseconds — the conversion to\n   * seconds (required by the `unit: 's'` OTel histogram) is handled internally.\n   *\n   * @param durationMs  Elapsed time in **milliseconds** (do NOT pre-divide).\n   * @param attributes  Optional OTel attributes to attach to the observation.\n   */\n  recordMs(\n    durationMs: number,\n    attributes?: Parameters<Histogram['record']>[1],\n  ): void;\n};\n\n/**\n * Bucket boundaries (in seconds) for zero's latency histograms.\n *\n * The operational range is 1 ms – 5,000 ms (including customers actively\n * tuning queries). ~2× logarithmic steps give proportionally consistent\n * `histogram_quantile` accuracy regardless of where values cluster within\n * that range. 10,000 ms and 30,000 ms are overflow catchers for truly broken\n * states.\n *\n *   1 ms, 2 ms, 5 ms, 10 ms, 20 ms, 50 ms, 100 ms, 200 ms, 500 ms,\n *   1 s, 2 s, 5 s, 10 s, 30 s\n */\nconst LATENCY_HISTOGRAM_BOUNDARIES_S = [\n  0.001, 0.002, 0.005, 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30,\n];\n\nconst histograms = cache<Histogram>();\n\n/**\n * Creates a histogram for dimensionless values without applying the\n * millisecond-to-second conversion used by the latency helpers below.\n */\nexport function getOrCreateValueHistogram(\n  category: Category,\n  name: string,\n  opts: HistogramOptions,\n): Histogram {\n  const {bucketBoundaries, ...metricOptions} = opts;\n  return histograms(name, name =>\n    getMeter().createHistogram(`zero.${category}.${name}`, {\n      ...metricOptions,\n      advice: {\n        ...metricOptions.advice,\n        explicitBucketBoundaries: bucketBoundaries,\n      },\n    }),\n  );\n}\n\nexport function getOrCreateHistogram(\n  category: Category,\n  name: string,\n  opts: HistogramOptions,\n): LatencyHistogram {\n  const {bucketBoundaries, ...metricOptions} = opts;\n  const h = histograms(name, name =>\n    getMeter().createHistogram(`zero.${category}.${name}`, {\n      ...metricOptions,\n      advice: {\n        ...metricOptions.advice,\n        explicitBucketBoundaries: bucketBoundaries,\n      },\n    }),\n  );\n  return {\n    recordMs: (durationMs, attributes) =>\n      h.record(durationMs / 1000, attributes),\n  };\n}\n\n// Add instruments created through this helper to\n// NATIVE_HISTOGRAM_INSTRUMENT_NAMES so the SDK exports them as exponential\n// histograms.\nexport function getOrCreateNativeHistogram(\n  category: Category,\n  name: string,\n  opts: Options,\n): LatencyHistogram {\n  const h = histograms(name, name =>\n    getMeter().createHistogram(`zero.${category}.${name}`, opts),\n  );\n  return {\n    recordMs: (durationMs, attributes) =>\n      h.record(durationMs / 1000, attributes),\n  };\n}\n\n/**\n * Creates (or retrieves) a latency histogram for the given metric.\n *\n * - `unit` is always `'s'` (seconds), matching the OTel convention.\n * - Bucket boundaries are pre-set for zero's typical operation range\n *   (1 ms – 5 s); see {@link LATENCY_HISTOGRAM_BOUNDARIES_S}.\n * - The returned {@link LatencyHistogram} accepts **milliseconds** via\n *   `recordMs()`, so callers never need to divide by 1000.\n *\n * @example\n * ```ts\n * readonly #hydrationTime = getOrCreateLatencyHistogram(\n *   'sync', 'hydration-time', 'Time to hydrate a query.',\n * );\n * // ...\n * this.#hydrationTime.recordMs(performance.now() - start);\n * ```\n */\nexport function getOrCreateLatencyHistogram(\n  category: Category,\n  name: string,\n  description: string,\n): LatencyHistogram {\n  return getOrCreateHistogram(category, name, {\n    description,\n    unit: 's',\n    bucketBoundaries: LATENCY_HISTOGRAM_BOUNDARIES_S,\n  });\n}\n\nconst counters = cache<Counter>();\n\nexport function getOrCreateCounter(\n  category: Category,\n  name: string,\n  description: string,\n): Counter;\nexport function getOrCreateCounter(\n  category: Category,\n  name: string,\n  opts: Options,\n): Counter;\nexport function getOrCreateCounter(\n  category: Category,\n  name: string,\n  opts: string | Options,\n): Counter {\n  return counters(name, name =>\n    getMeter().createCounter(\n      `zero.${category}.${name}`,\n      typeof opts === 'string' ? {description: opts} : opts,\n    ),\n  );\n}\n\nconst gauges = cache<ObservableGauge>();\n\nexport function getOrCreateGauge(\n  category: Category,\n  name: string,\n  description: string,\n): ObservableGauge;\nexport function getOrCreateGauge(\n  category: Category,\n  name: string,\n  opts: Options,\n): ObservableGauge;\nexport function getOrCreateGauge(\n  category: Category,\n  name: string,\n  opts: string | Options,\n): ObservableGauge {\n  return gauges(name, name =>\n    getMeter().createObservableGauge(\n      `zero.${category}.${name}`,\n      typeof opts === 'string' ? {description: opts} : opts,\n    ),\n  );\n}\n"],"mappings":";;AAmBA,IAAI;AAKJ,IAAa,oCAAoC;CAC/C;CACA;CACA;AACF;AAEA,IAAa,uCAAuC;CAClD;CAAG;CAAG;CAAG;CAAI;CAAI;CAAI;CAAK;CAAK;CAAK;CAAM;CAAM;CAAM;AACxD;AAEA,SAAS,WAAW;CAClB,IAAI,CAAC,OACH,QAAQ,QAAQ,SAAS,MAAM;CAEjC,OAAO;AACT;AAEA,SAAS,QAGC;CACR,MAAM,8BAAc,IAAI,IAAkB;CAC1C,QAAQ,MAAc,YAAoC;EACxD,MAAM,WAAW,YAAY,IAAI,IAAI;EACrC,IAAI,UACF,OAAO;EAGT,MAAM,MAAM,QAAQ,IAAI;EACxB,YAAY,IAAI,MAAM,GAAG;EACzB,OAAO;CACT;AACF;AAEA,IAAM,iBAAiB,MAAqB;AAY5C,SAAgB,yBACd,UACA,MACA,MACe;CACf,OAAO,eAAe,OAAM,SAC1B,SAAS,EAAE,oBACT,QAAQ,SAAS,GAAG,QACpB,OAAO,SAAS,WAAW,EAAC,aAAa,KAAI,IAAI,IACnD,CACF;AACF;;;;;;;;;;;;;AAmCA,IAAM,iCAAiC;CACrC;CAAO;CAAO;CAAO;CAAM;CAAM;CAAM;CAAK;CAAK;CAAK;CAAG;CAAG;CAAG;CAAI;AACrE;AAEA,IAAM,aAAa,MAAiB;;;;;AAMpC,SAAgB,0BACd,UACA,MACA,MACW;CACX,MAAM,EAAC,kBAAkB,GAAG,kBAAiB;CAC7C,OAAO,WAAW,OAAM,SACtB,SAAS,EAAE,gBAAgB,QAAQ,SAAS,GAAG,QAAQ;EACrD,GAAG;EACH,QAAQ;GACN,GAAG,cAAc;GACjB,0BAA0B;EAC5B;CACF,CAAC,CACH;AACF;AAEA,SAAgB,qBACd,UACA,MACA,MACkB;CAClB,MAAM,EAAC,kBAAkB,GAAG,kBAAiB;CAC7C,MAAM,IAAI,WAAW,OAAM,SACzB,SAAS,EAAE,gBAAgB,QAAQ,SAAS,GAAG,QAAQ;EACrD,GAAG;EACH,QAAQ;GACN,GAAG,cAAc;GACjB,0BAA0B;EAC5B;CACF,CAAC,CACH;CACA,OAAO,EACL,WAAW,YAAY,eACrB,EAAE,OAAO,aAAa,KAAM,UAAU,EAC1C;AACF;AAKA,SAAgB,2BACd,UACA,MACA,MACkB;CAClB,MAAM,IAAI,WAAW,OAAM,SACzB,SAAS,EAAE,gBAAgB,QAAQ,SAAS,GAAG,QAAQ,IAAI,CAC7D;CACA,OAAO,EACL,WAAW,YAAY,eACrB,EAAE,OAAO,aAAa,KAAM,UAAU,EAC1C;AACF;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,4BACd,UACA,MACA,aACkB;CAClB,OAAO,qBAAqB,UAAU,MAAM;EAC1C;EACA,MAAM;EACN,kBAAkB;CACpB,CAAC;AACH;AAEA,IAAM,WAAW,MAAe;AAYhC,SAAgB,mBACd,UACA,MACA,MACS;CACT,OAAO,SAAS,OAAM,SACpB,SAAS,EAAE,cACT,QAAQ,SAAS,GAAG,QACpB,OAAO,SAAS,WAAW,EAAC,aAAa,KAAI,IAAI,IACnD,CACF;AACF;AAEA,IAAM,SAAS,MAAuB;AAYtC,SAAgB,iBACd,UACA,MACA,MACiB;CACjB,OAAO,OAAO,OAAM,SAClB,SAAS,EAAE,sBACT,QAAQ,SAAS,GAAG,QACpB,OAAO,SAAS,WAAW,EAAC,aAAa,KAAI,IAAI,IACnD,CACF;AACF"}

package/out/zero-cache/src/server/backup-watermark-poller.js

@@ -0,0 +1,31 @@
+import { must } from "../../../shared/src/must.js";
+import { parentWorker, singleProcessMode } from "../types/processes.js";
+import { getZeroConfig } from "../config/zero-config.js";
+import { exitAfter, runUntilKilled } from "../services/life-cycle.js";
+import { createLogContext } from "./logging.js";
+import { VfsBackupWatermarkPoller } from "../services/litestream/vfs-watermark-poller.js";
+import { LogContext, consoleLogSink } from "@rocicorp/logger";
+//#region ../zero-cache/src/server/backup-watermark-poller.ts
+var lc = new LogContext("info", {}, consoleLogSink);
+async function runWorker(parent, env, ...argv) {
+	const config = getZeroConfig({
+		env,
+		argv
+	});
+	lc = createLogContext(config, "backup-watermark-poller");
+	const { litestream, replica } = config;
+	parent.send(["ready", { ready: true }]);
+	await runUntilKilled(lc, parent, new VfsBackupWatermarkPoller(lc, parent, {
+		localDbFile: replica.file,
+		backupURL: must(litestream.backupURL, "Missing --litestream-backup-url for backup watermark reader"),
+		endpoint: litestream.endpoint,
+		region: litestream.region,
+		extensionPath: litestream.vfsExtensionPath,
+		remotePollIntervalMs: litestream.vfsProbeIntervalMs
+	}));
+}
+if (!singleProcessMode()) exitAfter(() => lc, () => runWorker(must(parentWorker), process.env, ...process.argv.slice(2)));
+//#endregion
+export { runWorker as default };
+
+//# sourceMappingURL=backup-watermark-poller.js.map

package/out/zero-cache/src/server/backup-watermark-poller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-watermark-poller.js","names":[],"sources":["../../../../../zero-cache/src/server/backup-watermark-poller.ts"],"sourcesContent":["import {consoleLogSink, LogContext} from '@rocicorp/logger';\nimport {must} from '../../../shared/src/must.ts';\nimport {getZeroConfig} from '../config/zero-config.ts';\nimport {exitAfter, runUntilKilled} from '../services/life-cycle.ts';\nimport {VfsBackupWatermarkPoller} from '../services/litestream/vfs-watermark-poller.ts';\nimport {\n  parentWorker,\n  singleProcessMode,\n  type Worker,\n} from '../types/processes.ts';\nimport {createLogContext} from './logging.ts';\n\nlet lc = new LogContext('info', {}, consoleLogSink);\n\nexport default async function runWorker(\n  parent: Worker,\n  env: NodeJS.ProcessEnv,\n  ...argv: string[]\n): Promise<void> {\n  const config = getZeroConfig({env, argv});\n  lc = createLogContext(config, 'backup-watermark-poller');\n  const {litestream, replica} = config;\n\n  parent.send(['ready', {ready: true}]);\n\n  await runUntilKilled(\n    lc,\n    parent,\n    new VfsBackupWatermarkPoller(lc, parent, {\n      localDbFile: replica.file,\n      backupURL: must(\n        litestream.backupURL,\n        'Missing --litestream-backup-url for backup watermark reader',\n      ),\n      endpoint: litestream.endpoint,\n      region: litestream.region,\n      extensionPath: litestream.vfsExtensionPath,\n      remotePollIntervalMs: litestream.vfsProbeIntervalMs,\n    }),\n  );\n}\n\n// fork()\nif (!singleProcessMode()) {\n  void exitAfter(\n    () => lc,\n    () => runWorker(must(parentWorker), process.env, ...process.argv.slice(2)),\n  );\n}\n"],"mappings":";;;;;;;;AAYA,IAAI,KAAK,IAAI,WAAW,QAAQ,CAAC,GAAG,cAAc;AAElD,eAA8B,UAC5B,QACA,KACA,GAAG,MACY;CACf,MAAM,SAAS,cAAc;EAAC;EAAK;CAAI,CAAC;CACxC,KAAK,iBAAiB,QAAQ,yBAAyB;CACvD,MAAM,EAAC,YAAY,YAAW;CAE9B,OAAO,KAAK,CAAC,SAAS,EAAC,OAAO,KAAI,CAAC,CAAC;CAEpC,MAAM,eACJ,IACA,QACA,IAAI,yBAAyB,IAAI,QAAQ;EACvC,aAAa,QAAQ;EACrB,WAAW,KACT,WAAW,WACX,6DACF;EACA,UAAU,WAAW;EACrB,QAAQ,WAAW;EACnB,eAAe,WAAW;EAC1B,sBAAsB,WAAW;CACnC,CAAC,CACH;AACF;AAGA,IAAI,CAAC,kBAAkB,GACrB,gBACQ,UACA,UAAU,KAAK,YAAY,GAAG,QAAQ,KAAK,GAAG,QAAQ,KAAK,MAAM,CAAC,CAAC,CAC3E"}

package/out/zero-cache/src/server/change-streamer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"change-streamer.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/server/change-streamer.ts"],"names":[],"mappings":"AA+BA,OAAO,EAGL,KAAK,MAAM,EACZ,MAAM,uBAAuB,CAAC;AAQ/B,wBAA8B,SAAS,CACrC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,IAAI,CAAC,CA6Mf"}
+{"version":3,"file":"change-streamer.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/server/change-streamer.ts"],"names":[],"mappings":"AAqCA,OAAO,EAIL,KAAK,MAAM,EACZ,MAAM,uBAAuB,CAAC;AAU/B,wBAA8B,SAAS,CACrC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,IAAI,CAAC,CA6Tf"}

package/out/zero-cache/src/server/change-streamer.js

@@ -1,40 +1,42 @@
 import { assert } from "../../../shared/src/asserts.js";
 import { must } from "../../../shared/src/must.js";
-import { parentWorker, singleProcessMode } from "../types/processes.js";
+import { childWorker, parentWorker, singleProcessMode } from "../types/processes.js";
 import { getShardConfig } from "../types/shards.js";
 import { getNormalizedZeroConfig } from "../config/zero-config.js";
 import { DatabaseInitError } from "../../../zqlite/src/db.js";
+import { getOrCreateGauge } from "../observability/metrics.js";
 import { connectPgClient } from "../types/pg.js";
 import { registerSQLiteCorruptionDiagnosticTarget } from "../db/sqlite-corruption.js";
-import { exitAfter, runUntilKilled } from "../services/life-cycle.js";
+import { ProcessManager, exitAfter, runUntilKilled } from "../services/life-cycle.js";
 import { createLogContext } from "./logging.js";
+import { REPLICATOR_URL } from "./worker-urls.js";
 import { getServerContext } from "../config/server-context.js";
 import { deleteLiteDB } from "../db/delete-lite-db.js";
 import { warmupConnections } from "../db/warmup.js";
 import { initEventSink, publishCriticalEvent } from "../observability/events.js";
 import { AutoResetSignal } from "../services/change-streamer/schema/tables.js";
-import { upgradeReplica } from "../services/change-source/common/replica-schema.js";
 import { ReplicationStatusPublisher, replicationStatusError } from "../services/replicator/replication-status.js";
+import { changeLogFileName, deleteChangeLogDB } from "../services/replicator/change-log-db.js";
+import { startReplicaBackupProcess } from "../services/litestream/commands.js";
 import { initializeCustomChangeSource } from "../services/change-source/custom/change-source.js";
 import { initializePostgresChangeSource } from "../services/change-source/pg/change-source.js";
-import { ChangeStreamerHttpServer } from "../services/change-streamer/change-streamer-http.js";
-import { BackupNotFoundException, restoreReplica } from "../services/litestream/commands.js";
 import { createBackupCleanupMonitor } from "../services/change-streamer/backup-cleanup-monitor-factory.js";
-import { initChangeStreamerSchema } from "../services/change-streamer/schema/init.js";
+import { ChangeStreamerHttpServer } from "../services/change-streamer/change-streamer-http.js";
+import { sqliteFileBytes } from "../services/replicator/sqlite-change-log-observability.js";
 import { PurgeLocker } from "../services/change-streamer/storer.js";
 import { initializeStreamer } from "../services/change-streamer/change-streamer-service.js";
-import { ReplicaMonitor } from "../services/change-streamer/replica-monitor.js";
+import { initChangeStreamerSchema } from "../services/change-streamer/schema/init.js";
 import { startOtelAuto } from "./otel-start.js";
+import { resolver } from "@rocicorp/resolver";
 import { LogContext, consoleLogSink } from "@rocicorp/logger";
 //#region ../zero-cache/src/server/change-streamer.ts
 var lc = new LogContext("info", {}, consoleLogSink);
 async function runWorker(parent, env, ...argv) {
-	const workerStartTime = Date.now();
 	const config = getNormalizedZeroConfig({
 		env,
 		argv
 	});
-	const { taskID, changeStreamer: { port, address, protocol, startupDelayMs, backPressureLimitHeapProportion, flowControlConsensusPaddingSeconds }, upstream, change, replica, initialSync, keepaliveTimeoutMs, sqliteCorruptionChecks } = config;
+	const { taskID, changeStreamer: { port, address, protocol, startupDelayMs, backPressureLimitHeapProportion, flowControlConsensusTimeoutProportion, flowControlSlowSubscriberGracePeriodSeconds, sqliteChangeLogMode, sqliteChangeLogRetentionMs, sqliteChangeLogReadBatchRows, sqliteChangeLogPurgeBatchRows, sqliteChangeLogBarrierTimeoutMs }, autoReset, replicationLag, litestream, upstream, change, replica, initialSync, keepaliveTimeoutMs, sqliteCorruptionChecks } = config;
 	startOtelAuto(createLogContext(config, "change-streamer", 0, false), "change-streamer", 0);
 	lc = createLogContext(config, "change-streamer");
 	registerSQLiteCorruptionDiagnosticTarget({
@@ -44,37 +46,72 @@ async function runWorker(parent, env, ...argv) {
 	initEventSink(lc, config);
 	const changeDB = await connectPgClient(lc, change.db, "change-streamer", { max: change.maxConns }, { sendStringAsJson: true });
 	warmupConnections(lc, changeDB, "change").catch(() => {});
-	const { autoReset, replicationLag } = config;
 	const shard = getShardConfig(config);
 	await initChangeStreamerSchema(lc, changeDB, shard);
-	let purgeLock = config.litestream.backupURL && config.litestream.executable ? await new PurgeLocker(lc, shard, changeDB).acquire() : null;
-	if (purgeLock) try {
-		await restoreReplica(lc, config, purgeLock);
-	} catch (e) {
-		const log = e instanceof BackupNotFoundException ? "warn" : "error";
-		lc[log]?.(`error restoring backup. resyncing the replica`, e);
-		await purgeLock.release();
-		purgeLock = null;
-	}
+	let purgeLock = litestream.backupURL && litestream.executable ? await new PurgeLocker(lc, shard, changeDB).acquire() : null;
+	const restoreOptions = {
+		litestream,
+		constraints: purgeLock ?? void 0
+	};
 	let changeStreamer;
+	let backupURL;
 	const context = getServerContext(config);
+	const sqliteChangeLogEnabled = sqliteChangeLogMode !== "off";
+	const sqliteChangeLogComparing = sqliteChangeLogMode === "compare" || sqliteChangeLogMode === "serve";
+	if (sqliteChangeLogEnabled) {
+		const changeLogFile = changeLogFileName(replica.file);
+		registerSQLiteCorruptionDiagnosticTarget({
+			debugName: "change-streamer change-log",
+			dbPath: changeLogFile
+		}, sqliteCorruptionChecks);
+		getOrCreateGauge("replica", "sqlite_change_log.file_bytes", {
+			description: "The SQLite change log's total on-disk footprint: its main db file plus its wal sidecars.",
+			unit: "By"
+		}).addCallback(async (o) => o.observe(await sqliteFileBytes(lc, changeLogFile)));
+	}
+	let waitForFirstBackupBeforeServing = false;
 	for (const first of [true, false]) try {
-		const { changeSource, subscriptionState } = upstream.type === "pg" ? await initializePostgresChangeSource(lc, upstream.db, shard, replica.file, {
+		const { changeSource, subscriptionState, destinationBackupURL, replicaID, waitForBackupBeforeServing } = upstream.type === "pg" ? await initializePostgresChangeSource(lc, upstream.db, shard, replica.file, {
 			...initialSync,
 			replicationSlotFailover: upstream.pgReplicationSlotFailover
-		}, context, replicationLag.reportIntervalMs, upstream.pgStreamInboundTimeoutMs) : await initializeCustomChangeSource(lc, upstream.db, shard, replica.file, context);
+		}, context, replicationLag.reportIntervalMs, restoreOptions, { backupV5: litestream.backupUsingV5 }, purgeLock, upstream.pgStreamInboundTimeoutMs) : await initializeCustomChangeSource(lc, upstream.db, shard, replica.file, context, restoreOptions);
 		const replicationStatusPublisher = ReplicationStatusPublisher.forReplicaFile(replica.file);
-		changeStreamer = await initializeStreamer(lc, shard, taskID, address, protocol, changeDB, changeSource, replicationStatusPublisher, subscriptionState, purgeLock, autoReset ?? false, {
+		changeStreamer = await initializeStreamer(lc, shard, taskID, address, protocol, changeDB, changeSource, replicationStatusPublisher, subscriptionState, destinationBackupURL ? {
+			backupURL: destinationBackupURL,
+			litestreamVersion: litestream.backupUsingV5 ? "v5" : "legacy"
+		} : null, purgeLock, autoReset ?? false, {
 			backPressureLimitHeapProportion,
-			flowControlConsensusPaddingSeconds,
+			flowControlConsensusTimeoutProportion,
+			flowControlSlowSubscriberGracePeriodMs: flowControlSlowSubscriberGracePeriodSeconds > 0 ? flowControlSlowSubscriberGracePeriodSeconds * 1e3 : void 0,
 			statementTimeoutMs: change.statementTimeoutMs,
-			changeLogBatchSize: change.logBatchSize
+			changeLogBatchSize: change.logBatchSize,
+			sqliteCatchup: {
+				changeLogFile: changeLogFileName(replica.file),
+				readBatchRows: sqliteChangeLogReadBatchRows,
+				barrierTimeoutMs: sqliteChangeLogBarrierTimeoutMs
+			},
+			sqliteChangeLogWriter: sqliteChangeLogEnabled ? {
+				replicaFile: replica.file,
+				identity: {
+					epoch: null,
+					generation: subscriptionState.replicaVersion,
+					replicaID
+				}
+			} : void 0,
+			sqliteChangeLogPurge: sqliteChangeLogEnabled ? {
+				retentionMs: sqliteChangeLogRetentionMs,
+				batchRows: sqliteChangeLogPurgeBatchRows
+			} : void 0,
+			sqliteChangeLogCompare: sqliteChangeLogComparing ? { replicaFile: replica.file } : void 0
 		}, setTimeout);
+		backupURL = destinationBackupURL;
+		waitForFirstBackupBeforeServing = waitForBackupBeforeServing;
 		break;
 	} catch (e) {
 		if (first && e instanceof AutoResetSignal) {
 			lc.warn?.(`resetting replica ${replica.file}`, e);
 			deleteLiteDB(replica.file);
+			deleteChangeLogDB(replica.file);
 			await purgeLock?.release();
 			purgeLock = null;
 			continue;
@@ -83,23 +120,46 @@ async function runWorker(parent, env, ...argv) {
 		throw e;
 	}
 	assert(changeStreamer, `resetting replica did not advance replicaVersion`);
-	await upgradeReplica(lc, "change-streamer-init", replica.file);
+	const processes = new ProcessManager(lc, parent);
+	if (backupURL) {
+		lc.info?.("setting up backup to", backupURL);
+		litestream.backupURL = backupURL;
+		const { promise: backupStarted, resolve } = resolver();
+		processes.addWorker(childWorker(REPLICATOR_URL, env, "backup"), "supporting", "backup-replicator").once("message", () => {
+			processes.addSubprocess(startReplicaBackupProcess(lc, litestream, replica.file), "supporting", "litestream");
+			resolve();
+		});
+		await backupStarted;
+	}
 	const backupMonitor = createBackupCleanupMonitor({
 		lc,
+		processes,
 		config,
 		replicaFile: replica.file,
 		changeStreamer,
-		initialCleanupDelayMs: Date.now() - workerStartTime,
 		env
 	});
-	const monitor = backupMonitor ?? new ReplicaMonitor(lc, replica.file, changeStreamer);
 	const changeStreamerWebServer = new ChangeStreamerHttpServer(lc, {
 		port,
 		keepaliveTimeoutMs,
 		startupDelayMs
-	}, parent, changeStreamer, backupMonitor);
-	parent.send(["ready", { ready: true }]);
-	return runUntilKilled(lc, parent, changeStreamerWebServer, monitor);
+	}, parent, changeStreamer);
+	if (waitForFirstBackupBeforeServing) {
+		const start = performance.now();
+		lc.info?.(`awaiting initial backup ...`);
+		backupMonitor.firstBackupReceived().then(() => {
+			const elapsed = performance.now() - start;
+			lc.info?.(`initial backup confirmed after ${elapsed.toFixed(2)}ms`);
+			parent.send(["ready", { ready: true }]);
+		});
+	} else parent.send(["ready", { ready: true }]);
+	try {
+		await runUntilKilled(lc, parent, changeStreamerWebServer, backupMonitor);
+	} catch (err) {
+		processes.logErrorAndExit(err, "change-streamer");
+	} finally {
+		await processes.shutdown();
+	}
 }
 if (!singleProcessMode()) exitAfter(() => lc, () => runWorker(must(parentWorker), process.env, ...process.argv.slice(2)).catch(async (e) => {
 	await publishCriticalEvent(lc, replicationStatusError(lc, "Initializing", e));

package/out/zero-cache/src/server/change-streamer.js.map

@@ -1 +1 @@
-{"version":3,"file":"change-streamer.js","names":[],"sources":["../../../../../zero-cache/src/server/change-streamer.ts"],"sourcesContent":["import {consoleLogSink, LogContext} from '@rocicorp/logger';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport {DatabaseInitError} from '../../../zqlite/src/db.ts';\nimport {getServerContext} from '../config/server-context.ts';\nimport {getNormalizedZeroConfig} from '../config/zero-config.ts';\nimport {deleteLiteDB} from '../db/delete-lite-db.ts';\nimport {registerSQLiteCorruptionDiagnosticTarget} from '../db/sqlite-corruption.ts';\nimport {warmupConnections} from '../db/warmup.ts';\nimport {initEventSink, publishCriticalEvent} from '../observability/events.ts';\nimport {upgradeReplica} from '../services/change-source/common/replica-schema.ts';\nimport {initializeCustomChangeSource} from '../services/change-source/custom/change-source.ts';\nimport {initializePostgresChangeSource} from '../services/change-source/pg/change-source.ts';\nimport {createBackupCleanupMonitor} from '../services/change-streamer/backup-cleanup-monitor-factory.ts';\nimport {ChangeStreamerHttpServer} from '../services/change-streamer/change-streamer-http.ts';\nimport {initializeStreamer} from '../services/change-streamer/change-streamer-service.ts';\nimport type {ChangeStreamerService} from '../services/change-streamer/change-streamer.ts';\nimport {ReplicaMonitor} from '../services/change-streamer/replica-monitor.ts';\nimport {initChangeStreamerSchema} from '../services/change-streamer/schema/init.ts';\nimport {AutoResetSignal} from '../services/change-streamer/schema/tables.ts';\nimport {PurgeLocker} from '../services/change-streamer/storer.ts';\nimport {exitAfter, runUntilKilled} from '../services/life-cycle.ts';\nimport {\n  BackupNotFoundException,\n  restoreReplica,\n} from '../services/litestream/commands.ts';\nimport {\n  replicationStatusError,\n  ReplicationStatusPublisher,\n} from '../services/replicator/replication-status.ts';\nimport {connectPgClient} from '../types/pg.ts';\nimport {\n  parentWorker,\n  singleProcessMode,\n  type Worker,\n} from '../types/processes.ts';\nimport {getShardConfig} from '../types/shards.ts';\nimport {createLogContext} from './logging.ts';\nimport {startOtelAuto} from './otel-start.ts';\n\n// Default LogContext, overridden in runWorker\nlet lc = new LogContext('info', {}, consoleLogSink);\n\nexport default async function runWorker(\n  parent: Worker,\n  env: NodeJS.ProcessEnv,\n  ...argv: string[]\n): Promise<void> {\n  const workerStartTime = Date.now();\n  const config = getNormalizedZeroConfig({env, argv});\n  const {\n    taskID,\n    changeStreamer: {\n      port,\n      address,\n      protocol,\n      startupDelayMs,\n      backPressureLimitHeapProportion,\n      flowControlConsensusPaddingSeconds,\n    },\n    upstream,\n    change,\n    replica,\n    initialSync,\n    keepaliveTimeoutMs,\n    sqliteCorruptionChecks,\n  } = config;\n\n  startOtelAuto(\n    createLogContext(config, 'change-streamer', 0, false),\n    'change-streamer',\n    0,\n  );\n  lc = createLogContext(config, 'change-streamer');\n  registerSQLiteCorruptionDiagnosticTarget(\n    {\n      debugName: 'change-streamer replica',\n      dbPath: replica.file,\n    },\n    sqliteCorruptionChecks,\n  );\n  initEventSink(lc, config);\n\n  // Kick off DB connection warmup in the background.\n  const changeDB = await connectPgClient(\n    lc,\n    change.db,\n    'change-streamer',\n    {\n      max: change.maxConns,\n    },\n    {sendStringAsJson: true},\n  );\n  void warmupConnections(lc, changeDB, 'change').catch(() => {});\n\n  const {autoReset, replicationLag} = config;\n  const shard = getShardConfig(config);\n\n  // Ensure the change DB schema is initialized/up-to-date.\n  await initChangeStreamerSchema(lc, changeDB, shard);\n\n  // When restoring from litestream, acquire a lock to prevent change-log\n  // purges. This ensures that (this) change-streamer will be able to resume\n  // from the backup.\n  let purgeLock =\n    config.litestream.backupURL && config.litestream.executable\n      ? await new PurgeLocker(lc, shard, changeDB).acquire()\n      : null;\n\n  // Restore from litestream if the change-log has entries.\n  if (purgeLock) {\n    try {\n      await restoreReplica(lc, config, purgeLock);\n    } catch (e) {\n      // If the restore failed, e.g. due to a corrupt or missing backup, the\n      // replication-manager recovers by re-syncing.\n      const log = e instanceof BackupNotFoundException ? 'warn' : 'error';\n      lc[log]?.(`error restoring backup. resyncing the replica`, e);\n\n      // The purgeLock must be released if the backup could not be restored,\n      // or it will otherwise prevent the change-db update after the resync\n      // completes.\n      await purgeLock.release();\n      purgeLock = null;\n    }\n  }\n\n  let changeStreamer: ChangeStreamerService | undefined;\n\n  const context = getServerContext(config);\n\n  for (const first of [true, false]) {\n    try {\n      // Note: This performs initial sync of the replica if necessary.\n      const {changeSource, subscriptionState} =\n        upstream.type === 'pg'\n          ? await initializePostgresChangeSource(\n              lc,\n              upstream.db,\n              shard,\n              replica.file,\n              {\n                ...initialSync,\n                replicationSlotFailover: upstream.pgReplicationSlotFailover,\n              },\n              context,\n              replicationLag.reportIntervalMs,\n              upstream.pgStreamInboundTimeoutMs,\n            )\n          : await initializeCustomChangeSource(\n              lc,\n              upstream.db,\n              shard,\n              replica.file,\n              context,\n            );\n\n      const replicationStatusPublisher =\n        ReplicationStatusPublisher.forReplicaFile(replica.file);\n\n      changeStreamer = await initializeStreamer(\n        lc,\n        shard,\n        taskID,\n        address,\n        protocol,\n        changeDB,\n        changeSource,\n        replicationStatusPublisher,\n        subscriptionState,\n        purgeLock,\n        autoReset ?? false,\n        {\n          backPressureLimitHeapProportion,\n          flowControlConsensusPaddingSeconds,\n          statementTimeoutMs: change.statementTimeoutMs,\n          changeLogBatchSize: change.logBatchSize,\n        },\n        setTimeout,\n      );\n      break;\n    } catch (e) {\n      if (first && e instanceof AutoResetSignal) {\n        lc.warn?.(`resetting replica ${replica.file}`, e);\n        // TODO: Make deleteLiteDB work with litestream. It will probably have to be\n        //       a semantic wipe instead of a file delete.\n        deleteLiteDB(replica.file);\n        // Release the purge lock before retrying. This is safe because the\n        // purge lock exists to preserve change-log entries so the new\n        // change-streamer can resume from the backup replica's watermark.\n        // An AutoResetSignal means we cant resume from the backup replica\n        // (e.g. its replication slot is gone), so the change-log entries the lock\n        // was protecting are no longer needed. The retry performs a fresh\n        // initial sync with a new replication slot, independent of the old\n        // change-log. Releasing is also necessary to avoid a\n        // self-deadlock when CHANGE_DB == UPSTREAM_DB:\n        // CREATE_REPLICATION_SLOT waits for all older transactions to\n        // finish, including this lock's open transaction.\n        await purgeLock?.release();\n        purgeLock = null;\n        continue; // execute again with a fresh initial-sync\n      }\n      if (e instanceof DatabaseInitError) {\n        throw new Error(\n          `Cannot open ZERO_REPLICA_FILE at \"${replica.file}\". Please check that the path is valid.`,\n          {cause: e},\n        );\n      }\n      throw e;\n    }\n  }\n  // impossible: upstream must have advanced in order for replication to be stuck.\n  assert(changeStreamer, `resetting replica did not advance replicaVersion`);\n\n  // Perform any upgrades to the replica in case it was restored from an\n  // earlier version. Note that this upgrade is done by the replicator worker\n  // as well (in both the replication-manager and the view-syncer), but the\n  // change-streamer independently reads the replica, and it is fine run the\n  // upgrade logic redundantly since it is idempotent.\n  await upgradeReplica(lc, 'change-streamer-init', replica.file);\n\n  const backupMonitor = createBackupCleanupMonitor({\n    lc,\n    config,\n    replicaFile: replica.file,\n    changeStreamer,\n    // The time between when the zero-cache was started to when the\n    // change-streamer is ready to start serves as the initial delay for\n    // watermark cleanup (as it either includes a similar replica\n    // restoration/preparation step, or an initial-sync, which\n    // generally takes longer).\n    //\n    // Consider: Also account for permanent volumes?\n    initialCleanupDelayMs: Date.now() - workerStartTime,\n    env,\n  });\n  const monitor =\n    backupMonitor ?? new ReplicaMonitor(lc, replica.file, changeStreamer);\n\n  const changeStreamerWebServer = new ChangeStreamerHttpServer(\n    lc,\n    {port, keepaliveTimeoutMs, startupDelayMs},\n    parent,\n    changeStreamer,\n    backupMonitor,\n  );\n\n  parent.send(['ready', {ready: true}]);\n\n  // Note: The changeStreamer itself is not started here; it is started by the\n  //       changeStreamerWebServer.\n  return runUntilKilled(lc, parent, changeStreamerWebServer, monitor);\n}\n\n// fork()\nif (!singleProcessMode()) {\n  void exitAfter(\n    () => lc,\n    () =>\n      runWorker(\n        must(parentWorker),\n        process.env,\n        ...process.argv.slice(2),\n      ).catch(async e => {\n        await publishCriticalEvent(\n          lc,\n          replicationStatusError(lc, 'Initializing', e),\n        );\n        throw e;\n      }),\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,IAAI,KAAK,IAAI,WAAW,QAAQ,CAAC,GAAG,cAAc;AAElD,eAA8B,UAC5B,QACA,KACA,GAAG,MACY;CACf,MAAM,kBAAkB,KAAK,IAAI;CACjC,MAAM,SAAS,wBAAwB;EAAC;EAAK;CAAI,CAAC;CAClD,MAAM,EACJ,QACA,gBAAgB,EACd,MACA,SACA,UACA,gBACA,iCACA,sCAEF,UACA,QACA,SACA,aACA,oBACA,2BACE;CAEJ,cACE,iBAAiB,QAAQ,mBAAmB,GAAG,KAAK,GACpD,mBACA,CACF;CACA,KAAK,iBAAiB,QAAQ,iBAAiB;CAC/C,yCACE;EACE,WAAW;EACX,QAAQ,QAAQ;CAClB,GACA,sBACF;CACA,cAAc,IAAI,MAAM;CAGxB,MAAM,WAAW,MAAM,gBACrB,IACA,OAAO,IACP,mBACA,EACE,KAAK,OAAO,SACd,GACA,EAAC,kBAAkB,KAAI,CACzB;CACA,kBAAuB,IAAI,UAAU,QAAQ,EAAE,YAAY,CAAC,CAAC;CAE7D,MAAM,EAAC,WAAW,mBAAkB;CACpC,MAAM,QAAQ,eAAe,MAAM;CAGnC,MAAM,yBAAyB,IAAI,UAAU,KAAK;CAKlD,IAAI,YACF,OAAO,WAAW,aAAa,OAAO,WAAW,aAC7C,MAAM,IAAI,YAAY,IAAI,OAAO,QAAQ,EAAE,QAAQ,IACnD;CAGN,IAAI,WACF,IAAI;EACF,MAAM,eAAe,IAAI,QAAQ,SAAS;CAC5C,SAAS,GAAG;EAGV,MAAM,MAAM,aAAa,0BAA0B,SAAS;EAC5D,GAAG,OAAO,iDAAiD,CAAC;EAK5D,MAAM,UAAU,QAAQ;EACxB,YAAY;CACd;CAGF,IAAI;CAEJ,MAAM,UAAU,iBAAiB,MAAM;CAEvC,KAAK,MAAM,SAAS,CAAC,MAAM,KAAK,GAC9B,IAAI;EAEF,MAAM,EAAC,cAAc,sBACnB,SAAS,SAAS,OACd,MAAM,+BACJ,IACA,SAAS,IACT,OACA,QAAQ,MACR;GACE,GAAG;GACH,yBAAyB,SAAS;EACpC,GACA,SACA,eAAe,kBACf,SAAS,wBACX,IACA,MAAM,6BACJ,IACA,SAAS,IACT,OACA,QAAQ,MACR,OACF;EAEN,MAAM,6BACJ,2BAA2B,eAAe,QAAQ,IAAI;EAExD,iBAAiB,MAAM,mBACrB,IACA,OACA,QACA,SACA,UACA,UACA,cACA,4BACA,mBACA,WACA,aAAa,OACb;GACE;GACA;GACA,oBAAoB,OAAO;GAC3B,oBAAoB,OAAO;EAC7B,GACA,UACF;EACA;CACF,SAAS,GAAG;EACV,IAAI,SAAS,aAAa,iBAAiB;GACzC,GAAG,OAAO,qBAAqB,QAAQ,QAAQ,CAAC;GAGhD,aAAa,QAAQ,IAAI;GAYzB,MAAM,WAAW,QAAQ;GACzB,YAAY;GACZ;EACF;EACA,IAAI,aAAa,mBACf,MAAM,IAAI,MACR,qCAAqC,QAAQ,KAAK,0CAClD,EAAC,OAAO,EAAC,CACX;EAEF,MAAM;CACR;CAGF,OAAO,gBAAgB,kDAAkD;CAOzE,MAAM,eAAe,IAAI,wBAAwB,QAAQ,IAAI;CAE7D,MAAM,gBAAgB,2BAA2B;EAC/C;EACA;EACA,aAAa,QAAQ;EACrB;EAQA,uBAAuB,KAAK,IAAI,IAAI;EACpC;CACF,CAAC;CACD,MAAM,UACJ,iBAAiB,IAAI,eAAe,IAAI,QAAQ,MAAM,cAAc;CAEtE,MAAM,0BAA0B,IAAI,yBAClC,IACA;EAAC;EAAM;EAAoB;CAAc,GACzC,QACA,gBACA,aACF;CAEA,OAAO,KAAK,CAAC,SAAS,EAAC,OAAO,KAAI,CAAC,CAAC;CAIpC,OAAO,eAAe,IAAI,QAAQ,yBAAyB,OAAO;AACpE;AAGA,IAAI,CAAC,kBAAkB,GACrB,gBACQ,UAEJ,UACE,KAAK,YAAY,GACjB,QAAQ,KACR,GAAG,QAAQ,KAAK,MAAM,CAAC,CACzB,EAAE,MAAM,OAAM,MAAK;CACjB,MAAM,qBACJ,IACA,uBAAuB,IAAI,gBAAgB,CAAC,CAC9C;CACA,MAAM;AACR,CAAC,CACL"}
+{"version":3,"file":"change-streamer.js","names":[],"sources":["../../../../../zero-cache/src/server/change-streamer.ts"],"sourcesContent":["import {consoleLogSink, LogContext} from '@rocicorp/logger';\nimport {resolver} from '@rocicorp/resolver';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport {DatabaseInitError} from '../../../zqlite/src/db.ts';\nimport {getServerContext} from '../config/server-context.ts';\nimport {getNormalizedZeroConfig} from '../config/zero-config.ts';\nimport {deleteLiteDB} from '../db/delete-lite-db.ts';\nimport {registerSQLiteCorruptionDiagnosticTarget} from '../db/sqlite-corruption.ts';\nimport {warmupConnections} from '../db/warmup.ts';\nimport {initEventSink, publishCriticalEvent} from '../observability/events.ts';\nimport {getOrCreateGauge} from '../observability/metrics.ts';\nimport {initializeCustomChangeSource} from '../services/change-source/custom/change-source.ts';\nimport {initializePostgresChangeSource} from '../services/change-source/pg/change-source.ts';\nimport {createBackupCleanupMonitor} from '../services/change-streamer/backup-cleanup-monitor-factory.ts';\nimport {ChangeStreamerHttpServer} from '../services/change-streamer/change-streamer-http.ts';\nimport {initializeStreamer} from '../services/change-streamer/change-streamer-service.ts';\nimport type {ChangeStreamerService} from '../services/change-streamer/change-streamer.ts';\nimport {initChangeStreamerSchema} from '../services/change-streamer/schema/init.ts';\nimport {AutoResetSignal} from '../services/change-streamer/schema/tables.ts';\nimport {PurgeLocker} from '../services/change-streamer/storer.ts';\nimport {\n  exitAfter,\n  ProcessManager,\n  runUntilKilled,\n} from '../services/life-cycle.ts';\nimport {startReplicaBackupProcess} from '../services/litestream/commands.ts';\nimport {\n  changeLogFileName,\n  deleteChangeLogDB,\n} from '../services/replicator/change-log-db.ts';\nimport {\n  replicationStatusError,\n  ReplicationStatusPublisher,\n} from '../services/replicator/replication-status.ts';\nimport {sqliteFileBytes} from '../services/replicator/sqlite-change-log-observability.ts';\nimport {connectPgClient} from '../types/pg.ts';\nimport {\n  childWorker,\n  parentWorker,\n  singleProcessMode,\n  type Worker,\n} from '../types/processes.ts';\nimport {getShardConfig} from '../types/shards.ts';\nimport type {ReplicaFileMode} from '../workers/replicator.ts';\nimport {createLogContext} from './logging.ts';\nimport {startOtelAuto} from './otel-start.ts';\nimport {REPLICATOR_URL} from './worker-urls.ts';\n\n// Default LogContext, overridden in runWorker\nlet lc = new LogContext('info', {}, consoleLogSink);\n\nexport default async function runWorker(\n  parent: Worker,\n  env: NodeJS.ProcessEnv,\n  ...argv: string[]\n): Promise<void> {\n  const config = getNormalizedZeroConfig({env, argv});\n  const {\n    taskID,\n    changeStreamer: {\n      port,\n      address,\n      protocol,\n      startupDelayMs,\n      backPressureLimitHeapProportion,\n      flowControlConsensusTimeoutProportion,\n      flowControlSlowSubscriberGracePeriodSeconds,\n      sqliteChangeLogMode,\n      sqliteChangeLogRetentionMs,\n      sqliteChangeLogReadBatchRows,\n      sqliteChangeLogPurgeBatchRows,\n      sqliteChangeLogBarrierTimeoutMs,\n    },\n    autoReset,\n    replicationLag,\n    litestream,\n    upstream,\n    change,\n    replica,\n    initialSync,\n    keepaliveTimeoutMs,\n    sqliteCorruptionChecks,\n  } = config;\n\n  startOtelAuto(\n    createLogContext(config, 'change-streamer', 0, false),\n    'change-streamer',\n    0,\n  );\n  lc = createLogContext(config, 'change-streamer');\n  registerSQLiteCorruptionDiagnosticTarget(\n    {\n      debugName: 'change-streamer replica',\n      dbPath: replica.file,\n    },\n    sqliteCorruptionChecks,\n  );\n  initEventSink(lc, config);\n\n  // Kick off DB connection warmup in the background.\n  const changeDB = await connectPgClient(\n    lc,\n    change.db,\n    'change-streamer',\n    {max: change.maxConns},\n    {sendStringAsJson: true},\n  );\n  void warmupConnections(lc, changeDB, 'change').catch(() => {});\n\n  const shard = getShardConfig(config);\n\n  // Ensure the change DB schema is initialized/up-to-date.\n  await initChangeStreamerSchema(lc, changeDB, shard);\n\n  // When restoring from litestream, acquire a lock to prevent change-log\n  // purges. This ensures that (this) change-streamer will be able to resume\n  // from the backup.\n  let purgeLock =\n    litestream.backupURL && litestream.executable\n      ? await new PurgeLocker(lc, shard, changeDB).acquire()\n      : null;\n  const restoreOptions = {litestream, constraints: purgeLock ?? undefined};\n\n  let changeStreamer: ChangeStreamerService | undefined;\n  let backupURL: string | undefined;\n\n  const context = getServerContext(config);\n  const sqliteChangeLogEnabled = sqliteChangeLogMode !== 'off';\n  // The modes are cumulative, so `serve` implies `compare`.\n  const sqliteChangeLogComparing =\n    sqliteChangeLogMode === 'compare' || sqliteChangeLogMode === 'serve';\n  if (sqliteChangeLogEnabled) {\n    const changeLogFile = changeLogFileName(replica.file);\n    registerSQLiteCorruptionDiagnosticTarget(\n      {\n        debugName: 'change-streamer change-log',\n        dbPath: changeLogFile,\n      },\n      sqliteCorruptionChecks,\n    );\n    // The log's bytes are accounted for in the process that writes them. This\n    // is local disk only — the log is excluded from the litestream backup — and\n    // it is a whole-database total, because a table that left the replica left\n    // through its wal: the replica's footprint is what shrank and this is where\n    // it went.\n    getOrCreateGauge('replica', 'sqlite_change_log.file_bytes', {\n      description:\n        `The SQLite change log's total on-disk footprint: its main db file ` +\n        `plus its wal sidecars.`,\n      unit: 'By',\n    }).addCallback(async o =>\n      o.observe(await sqliteFileBytes(lc, changeLogFile)),\n    );\n  }\n\n  let waitForFirstBackupBeforeServing = false;\n  for (const first of [true, false]) {\n    try {\n      // Note: This performs initial sync of the replica if necessary.\n      const {\n        changeSource,\n        subscriptionState,\n        destinationBackupURL,\n        replicaID,\n        waitForBackupBeforeServing,\n      } =\n        upstream.type === 'pg'\n          ? await initializePostgresChangeSource(\n              lc,\n              upstream.db,\n              shard,\n              replica.file,\n              {\n                ...initialSync,\n                replicationSlotFailover: upstream.pgReplicationSlotFailover,\n              },\n              context,\n              replicationLag.reportIntervalMs,\n              restoreOptions,\n              {backupV5: litestream.backupUsingV5},\n              purgeLock,\n              upstream.pgStreamInboundTimeoutMs,\n            )\n          : await initializeCustomChangeSource(\n              lc,\n              upstream.db,\n              shard,\n              replica.file,\n              context,\n              restoreOptions,\n            );\n\n      const replicationStatusPublisher =\n        ReplicationStatusPublisher.forReplicaFile(replica.file);\n\n      changeStreamer = await initializeStreamer(\n        lc,\n        shard,\n        taskID,\n        address,\n        protocol,\n        changeDB,\n        changeSource,\n        replicationStatusPublisher,\n        subscriptionState,\n        destinationBackupURL\n          ? {\n              backupURL: destinationBackupURL,\n              litestreamVersion: litestream.backupUsingV5 ? 'v5' : 'legacy',\n            }\n          : null,\n        purgeLock,\n        autoReset ?? false,\n        {\n          backPressureLimitHeapProportion,\n          flowControlConsensusTimeoutProportion,\n          flowControlSlowSubscriberGracePeriodMs:\n            flowControlSlowSubscriberGracePeriodSeconds > 0\n              ? flowControlSlowSubscriberGracePeriodSeconds * 1000\n              : undefined,\n          statementTimeoutMs: change.statementTimeoutMs,\n          changeLogBatchSize: change.logBatchSize,\n          sqliteCatchup: {\n            changeLogFile: changeLogFileName(replica.file),\n            readBatchRows: sqliteChangeLogReadBatchRows,\n            barrierTimeoutMs: sqliteChangeLogBarrierTimeoutMs,\n          },\n          // The presence of these options is the writer's gate. This process\n          // performs the restore and the initial sync, so the replica's\n          // identity is in hand at the moment the log is opened.\n          sqliteChangeLogWriter: sqliteChangeLogEnabled\n            ? {\n                replicaFile: replica.file,\n                identity: {\n                  // RMv2 supplies the epoch; until then the generation and the\n                  // replica ID are the whole of the identity.\n                  epoch: null,\n                  generation: subscriptionState.replicaVersion,\n                  replicaID,\n                },\n              }\n            : undefined,\n          // The purge scheduler shares the writer's gate -- mode, not the\n          // read path -- because `write` mode, with no read selector at all,\n          // is the configuration it ships in.\n          sqliteChangeLogPurge: sqliteChangeLogEnabled\n            ? {\n                retentionMs: sqliteChangeLogRetentionMs,\n                batchRows: sqliteChangeLogPurgeBatchRows,\n              }\n            : undefined,\n          // `compare` and above. The replica-derived initialization path runs\n          // at full rate and is checked against Postgres, which stays\n          // authoritative. Flipping authority to the replica comes later.\n          sqliteChangeLogCompare: sqliteChangeLogComparing\n            ? {replicaFile: replica.file}\n            : undefined,\n        },\n        setTimeout,\n      );\n      backupURL = destinationBackupURL;\n      waitForFirstBackupBeforeServing = waitForBackupBeforeServing;\n      break;\n    } catch (e) {\n      if (first && e instanceof AutoResetSignal) {\n        lc.warn?.(`resetting replica ${replica.file}`, e);\n        // TODO: Make deleteLiteDB work with litestream. It will probably have to be\n        //       a semantic wipe instead of a file delete.\n        deleteLiteDB(replica.file);\n        // The change log carries the identity of the replica it was written\n        // beside, and the retry performs a fresh initial sync with a new\n        // replicaVersion. Reconciliation would catch that on its own (as\n        // 'identity-mismatch') but only after the writer opened a file that is\n        // known here to be garbage.\n        deleteChangeLogDB(replica.file);\n        // Release the purge lock before retrying. This is safe because the\n        // purge lock exists to preserve change-log entries so the new\n        // change-streamer can resume from the backup replica's watermark.\n        // An AutoResetSignal means we cant resume from the backup replica\n        // (e.g. its replication slot is gone), so the change-log entries the lock\n        // was protecting are no longer needed. The retry performs a fresh\n        // initial sync with a new replication slot, independent of the old\n        // change-log. Releasing is also necessary to avoid a\n        // self-deadlock when CHANGE_DB == UPSTREAM_DB:\n        // CREATE_REPLICATION_SLOT waits for all older transactions to\n        // finish, including this lock's open transaction.\n        await purgeLock?.release();\n        purgeLock = null;\n        continue; // execute again with a fresh initial-sync\n      }\n      if (e instanceof DatabaseInitError) {\n        throw new Error(\n          `Cannot open ZERO_REPLICA_FILE at \"${replica.file}\". Please check that the path is valid.`,\n          {cause: e},\n        );\n      }\n      throw e;\n    }\n  }\n  // impossible: upstream must have advanced in order for replication to be stuck.\n  assert(changeStreamer, `resetting replica did not advance replicaVersion`);\n\n  const processes = new ProcessManager(lc, parent);\n  if (backupURL) {\n    lc.info?.('setting up backup to', backupURL);\n    litestream.backupURL = backupURL;\n    const {promise: backupStarted, resolve} = resolver();\n\n    // Start a backup replicator and corresponding litestream backup process.\n    processes\n      .addWorker(\n        childWorker(REPLICATOR_URL, env, 'backup' satisfies ReplicaFileMode),\n        'supporting',\n        'backup-replicator',\n      )\n      // Wait for the replicator's first message (i.e. \"ready\") before starting\n      // litestream backup in order to avoid contending on the sqlite lock\n      // when the replicator first prepares the db file.\n      .once('message', () => {\n        processes.addSubprocess(\n          startReplicaBackupProcess(lc, litestream, replica.file),\n          'supporting',\n          'litestream',\n        );\n        resolve();\n      });\n    await backupStarted;\n  }\n\n  const backupMonitor = createBackupCleanupMonitor({\n    lc,\n    processes,\n    config,\n    replicaFile: replica.file,\n    changeStreamer,\n    env,\n  });\n\n  const changeStreamerWebServer = new ChangeStreamerHttpServer(\n    lc,\n    {port, keepaliveTimeoutMs, startupDelayMs},\n    parent,\n    changeStreamer,\n  );\n\n  if (waitForFirstBackupBeforeServing) {\n    const start = performance.now();\n    lc.info?.(`awaiting initial backup ...`);\n\n    void backupMonitor.firstBackupReceived().then(() => {\n      const elapsed = performance.now() - start;\n      lc.info?.(`initial backup confirmed after ${elapsed.toFixed(2)}ms`);\n      parent.send(['ready', {ready: true}]);\n    });\n  } else {\n    parent.send(['ready', {ready: true}]);\n  }\n\n  // Note: The changeStreamer itself is not started here; it is started by the\n  //       changeStreamerWebServer after a delay to ensure that routing\n  //       routing elements have registered the server before the\n  //       change-streamer takes over the replication slot.\n  // TODO: Remove this delay and start the changeStreamer normally here once\n  //       transitioned to RMv2, since changeStreamer startup will no longer\n  //       disrupt an existing task.\n  try {\n    await runUntilKilled(lc, parent, changeStreamerWebServer, backupMonitor);\n  } catch (err) {\n    processes.logErrorAndExit(err, 'change-streamer');\n  } finally {\n    await processes.shutdown();\n  }\n}\n\n// fork()\nif (!singleProcessMode()) {\n  void exitAfter(\n    () => lc,\n    () =>\n      runWorker(\n        must(parentWorker),\n        process.env,\n        ...process.argv.slice(2),\n      ).catch(async e => {\n        await publishCriticalEvent(\n          lc,\n          replicationStatusError(lc, 'Initializing', e),\n        );\n        throw e;\n      }),\n  );\n}\n"],"mappings":"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"}

package/out/zero-cache/src/server/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/server/main.ts"],"names":[],"mappings":"AAkBA,OAAO,EAIL,KAAK,MAAM,EACZ,MAAM,uBAAuB,CAAC;AAwB/B,wBAA8B,SAAS,CACrC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,OAAO,CAAC,IAAI,CAAC,CAsLf"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/server/main.ts"],"names":[],"mappings":"AAeA,OAAO,EAIL,KAAK,MAAM,EACZ,MAAM,uBAAuB,CAAC;AAwB/B,wBAA8B,SAAS,CACrC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,OAAO,CAAC,IAAI,CAAC,CA+Jf"}

package/out/zero-cache/src/server/main.js

@@ -1,3 +1,4 @@
+import { assert } from "../../../shared/src/asserts.js";
 import { must } from "../../../shared/src/must.js";
 import { childWorker, parentWorker, singleProcessMode } from "../types/processes.js";
 import { getNormalizedZeroConfig } from "../config/zero-config.js";
@@ -6,7 +7,6 @@ import { ProcessManager, exitAfter, recordStartupDurationMs, runUntilKilled } fr
 import { createLogContext } from "./logging.js";
 import { CHANGE_STREAMER_URL, REAPER_URL, REPLICATOR_URL, SHADOW_SYNCER_URL, SYNCER_URL } from "./worker-urls.js";
 import { initEventSink } from "../observability/events.js";
-import { restoreReplica, startReplicaBackupProcess } from "../services/litestream/commands.js";
 import { startOtelAuto } from "./otel-start.js";
 import { createNotifierFrom, handleSubscriptionsFrom, subscribeTo } from "../workers/replicator.js";
 import { WorkerDispatcher } from "./worker-dispatcher.js";
@@ -42,23 +42,12 @@ async function runWorker(parent, env) {
 	}
 	const { taskID, changeStreamer: { mode: changeStreamerMode, uri: changeStreamerURI }, litestream } = config;
 	const runChangeStreamer = changeStreamerMode === "dedicated" && changeStreamerURI === void 0;
+	assert(!(config.changeStreamer.sqliteChangeLogMode !== "off") || runChangeStreamer, "SQLite change-log writing requires this process tree to run the change-streamer, which is where the writer lives");
 	let changeStreamer;
-	if (!runChangeStreamer) {
-		changeStreamer = void 0;
-		if (litestream.executable) await restoreReplica(lc, config, null);
-	} else {
+	if (runChangeStreamer) {
 		const { promise: changeStreamerReady, resolve: changeStreamerStarted } = resolver();
 		changeStreamer = loadWorker(CHANGE_STREAMER_URL, "supporting").once("message", changeStreamerStarted);
 		await changeStreamerReady;
-		if (litestream.backupURL) {
-			const { promise: backupReady, resolve } = resolver();
-			const mode = "backup";
-			loadWorker(REPLICATOR_URL, "supporting", mode, mode).once("message", () => {
-				processes.addSubprocess(startReplicaBackupProcess(lc, config), "supporting", "litestream");
-				resolve();
-			});
-			await backupReady;
-		}
 	}
 	if (numSyncers > 0) {
 		const { promise: reaperReady, resolve: reaperStarted } = resolver();
@@ -96,8 +85,9 @@ async function runWorker(parent, env) {
 		await runUntilKilled(lc, parent, new WorkerDispatcher(lc, taskID, parent, syncers, mutator, changeStreamer));
 	} catch (err) {
 		processes.logErrorAndExit(err, "dispatcher");
+	} finally {
+		await processes.shutdown();
 	}
-	await processes.done();
 }
 if (!singleProcessMode()) exitAfter(() => lc, () => runWorker(must(parentWorker), process.env));
 //#endregion

package/out/zero-cache/src/server/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","names":[],"sources":["../../../../../zero-cache/src/server/main.ts"],"sourcesContent":["import path from 'node:path';\nimport {consoleLogSink, LogContext} from '@rocicorp/logger';\nimport {resolver} from '@rocicorp/resolver';\nimport {must} from '../../../shared/src/must.ts';\nimport {getNormalizedZeroConfig} from '../config/zero-config.ts';\nimport {registerSQLiteCorruptionDiagnosticTarget} from '../db/sqlite-corruption.ts';\nimport {initEventSink} from '../observability/events.ts';\nimport {\n  exitAfter,\n  ProcessManager,\n  recordStartupDurationMs,\n  runUntilKilled,\n  type WorkerType,\n} from '../services/life-cycle.ts';\nimport {\n  restoreReplica,\n  startReplicaBackupProcess,\n} from '../services/litestream/commands.ts';\nimport {\n  childWorker,\n  parentWorker,\n  singleProcessMode,\n  type Worker,\n} from '../types/processes.ts';\nimport {\n  createNotifierFrom,\n  handleSubscriptionsFrom,\n  type ReplicaFileMode,\n  subscribeTo,\n} from '../workers/replicator.ts';\nimport {createLogContext} from './logging.ts';\nimport {startOtelAuto} from './otel-start.ts';\nimport {WorkerDispatcher} from './worker-dispatcher.ts';\nimport {\n  CHANGE_STREAMER_URL,\n  MUTATOR_URL,\n  REAPER_URL,\n  REPLICATOR_URL,\n  SHADOW_SYNCER_URL,\n  SYNCER_URL,\n} from './worker-urls.ts';\n\nconst clientConnectionBifurcated = false;\n\n// Default LogContext, overridden in runWorker\nlet lc = new LogContext('info', {}, consoleLogSink);\n\nexport default async function runWorker(\n  parent: Worker,\n  env: NodeJS.ProcessEnv,\n): Promise<void> {\n  const startMs = Date.now();\n  const config = getNormalizedZeroConfig({env});\n\n  startOtelAuto(\n    createLogContext(config, 'dispatcher', 0, false),\n    'dispatcher',\n    0,\n  );\n  lc = createLogContext(config, 'dispatcher');\n  registerSQLiteCorruptionDiagnosticTarget(\n    {\n      debugName: 'dispatcher replica',\n      dbPath: config.replica.file,\n    },\n    config.sqliteCorruptionChecks,\n  );\n  initEventSink(lc, config);\n\n  const processes = new ProcessManager(lc, parent);\n\n  const {numSyncWorkers: numSyncers} = config;\n  if (config.enableCrudMutations && config.upstream.maxConns < numSyncers) {\n    throw new Error(\n      `Insufficient upstream connections (${config.upstream.maxConns}) for ${numSyncers} syncers.` +\n        `Increase ZERO_UPSTREAM_MAX_CONNS or decrease ZERO_NUM_SYNC_WORKERS (which defaults to available cores).`,\n    );\n  }\n  if (config.cvr.maxConns < numSyncers) {\n    throw new Error(\n      `Insufficient cvr connections (${config.cvr.maxConns}) for ${numSyncers} syncers.` +\n        `Increase ZERO_CVR_MAX_CONNS or decrease ZERO_NUM_SYNC_WORKERS (which defaults to available cores).`,\n    );\n  }\n\n  const internalFlags: string[] =\n    numSyncers === 0\n      ? []\n      : [\n          '--upstream-max-conns-per-worker',\n          String(Math.floor(config.upstream.maxConns / numSyncers)),\n          '--cvr-max-conns-per-worker',\n          String(Math.floor(config.cvr.maxConns / numSyncers)),\n        ];\n\n  function loadWorker(\n    moduleUrl: URL,\n    type: WorkerType,\n    id?: string | number,\n    ...args: string[]\n  ): Worker {\n    const worker = childWorker(moduleUrl, env, ...args, ...internalFlags);\n    const name = path.basename(moduleUrl.pathname) + (id ? ` (${id})` : '');\n    return processes.addWorker(worker, type, name);\n  }\n\n  const {\n    taskID,\n    changeStreamer: {mode: changeStreamerMode, uri: changeStreamerURI},\n    litestream,\n  } = config;\n  const runChangeStreamer =\n    changeStreamerMode === 'dedicated' && changeStreamerURI === undefined;\n\n  let changeStreamer: Worker | undefined;\n\n  if (!runChangeStreamer) {\n    changeStreamer = undefined;\n    if (litestream.executable) {\n      // For view-syncers, the backup is restored here. For the replication-manager,\n      // the backup is restored in the change-streamer worker.\n      await restoreReplica(lc, config, null);\n    }\n  } else {\n    const {promise: changeStreamerReady, resolve: changeStreamerStarted} =\n      resolver();\n    changeStreamer = loadWorker(CHANGE_STREAMER_URL, 'supporting').once(\n      'message',\n      changeStreamerStarted,\n    );\n\n    // Wait for the change-streamer to be ready to guarantee that a replica\n    // file is present.\n    await changeStreamerReady;\n\n    if (litestream.backupURL) {\n      // Start a backup replicator and corresponding litestream backup process.\n      const {promise: backupReady, resolve} = resolver();\n      const mode: ReplicaFileMode = 'backup';\n      loadWorker(REPLICATOR_URL, 'supporting', mode, mode).once(\n        // Wait for the Replicator's first message (i.e. \"ready\") before starting\n        // litestream backup in order to avoid contending on the lock when the\n        // replicator first prepares the db file.\n        'message',\n        () => {\n          processes.addSubprocess(\n            startReplicaBackupProcess(lc, config),\n            'supporting',\n            'litestream',\n          );\n          resolve();\n        },\n      );\n      await backupReady;\n    }\n  }\n\n  if (numSyncers > 0) {\n    const {promise: reaperReady, resolve: reaperStarted} = resolver();\n    loadWorker(REAPER_URL, 'supporting').once('message', reaperStarted);\n    // Before starting the view-syncers, ensure that the reaper has started\n    // up, indicating that any CVR db migrations have been performed.\n    await reaperReady;\n  }\n\n  // Only run the shadow-sync canary on the replication-manager (or in\n  // single-node mode, where it also owns upstream). Running on every\n  // view-syncer would hammer the upstream with N redundant canaries.\n  if (config.shadowSync.enabled && runChangeStreamer) {\n    const {promise: shadowReady, resolve: shadowStarted} = resolver();\n    loadWorker(SHADOW_SYNCER_URL, 'supporting').once('message', shadowStarted);\n    await shadowReady;\n  }\n\n  const syncers: Worker[] = [];\n  if (numSyncers) {\n    const mode: ReplicaFileMode =\n      runChangeStreamer && litestream.backupURL ? 'serving-copy' : 'serving';\n    const {promise: replicaReady, resolve} = resolver();\n    const replicator = loadWorker(\n      REPLICATOR_URL,\n      'supporting',\n      mode,\n      mode,\n    ).once('message', () => {\n      subscribeTo(lc, replicator);\n      resolve();\n    });\n    await replicaReady;\n\n    const notifier = createNotifierFrom(lc, replicator);\n    for (let i = 0; i < numSyncers; i++) {\n      syncers.push(loadWorker(SYNCER_URL, 'user-facing', i, mode, String(i)));\n    }\n    syncers.forEach(syncer => handleSubscriptionsFrom(lc, syncer, notifier));\n  }\n  let mutator: Worker | undefined;\n  if (clientConnectionBifurcated) {\n    mutator = loadWorker(MUTATOR_URL, 'supporting', 'mutator');\n  }\n\n  lc.info?.('waiting for workers to be ready ...');\n  const logWaiting = setInterval(\n    () => lc.info?.(`still waiting for ${processes.initializing().join(', ')}`),\n    10_000,\n  );\n  await processes.allWorkersReady();\n  clearInterval(logWaiting);\n  const startupDurationMs = Date.now() - startMs;\n  lc.info?.(`all workers ready (${startupDurationMs} ms)`);\n  recordStartupDurationMs(startupDurationMs);\n\n  parent.send(['ready', {ready: true}]);\n\n  try {\n    await runUntilKilled(\n      lc,\n      parent,\n      new WorkerDispatcher(\n        lc,\n        taskID,\n        parent,\n        syncers,\n        mutator,\n        changeStreamer,\n      ),\n    );\n  } catch (err) {\n    processes.logErrorAndExit(err, 'dispatcher');\n  }\n\n  await processes.done();\n}\n\nif (!singleProcessMode()) {\n  void exitAfter(\n    () => lc,\n    () => runWorker(must(parentWorker), process.env),\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"main.js","names":[],"sources":["../../../../../zero-cache/src/server/main.ts"],"sourcesContent":["import path from 'node:path';\nimport {consoleLogSink, LogContext} from '@rocicorp/logger';\nimport {resolver} from '@rocicorp/resolver';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport {getNormalizedZeroConfig} from '../config/zero-config.ts';\nimport {registerSQLiteCorruptionDiagnosticTarget} from '../db/sqlite-corruption.ts';\nimport {initEventSink} from '../observability/events.ts';\nimport {\n  exitAfter,\n  ProcessManager,\n  recordStartupDurationMs,\n  runUntilKilled,\n  type WorkerType,\n} from '../services/life-cycle.ts';\nimport {\n  childWorker,\n  parentWorker,\n  singleProcessMode,\n  type Worker,\n} from '../types/processes.ts';\nimport {\n  createNotifierFrom,\n  handleSubscriptionsFrom,\n  type ReplicaFileMode,\n  subscribeTo,\n} from '../workers/replicator.ts';\nimport {createLogContext} from './logging.ts';\nimport {startOtelAuto} from './otel-start.ts';\nimport {WorkerDispatcher} from './worker-dispatcher.ts';\nimport {\n  CHANGE_STREAMER_URL,\n  MUTATOR_URL,\n  REAPER_URL,\n  REPLICATOR_URL,\n  SHADOW_SYNCER_URL,\n  SYNCER_URL,\n} from './worker-urls.ts';\n\nconst clientConnectionBifurcated = false;\n\n// Default LogContext, overridden in runWorker\nlet lc = new LogContext('info', {}, consoleLogSink);\n\nexport default async function runWorker(\n  parent: Worker,\n  env: NodeJS.ProcessEnv,\n): Promise<void> {\n  const startMs = Date.now();\n  const config = getNormalizedZeroConfig({env});\n\n  startOtelAuto(\n    createLogContext(config, 'dispatcher', 0, false),\n    'dispatcher',\n    0,\n  );\n  lc = createLogContext(config, 'dispatcher');\n  registerSQLiteCorruptionDiagnosticTarget(\n    {\n      debugName: 'dispatcher replica',\n      dbPath: config.replica.file,\n    },\n    config.sqliteCorruptionChecks,\n  );\n  initEventSink(lc, config);\n\n  const processes = new ProcessManager(lc, parent);\n\n  const {numSyncWorkers: numSyncers} = config;\n  if (config.enableCrudMutations && config.upstream.maxConns < numSyncers) {\n    throw new Error(\n      `Insufficient upstream connections (${config.upstream.maxConns}) for ${numSyncers} syncers.` +\n        `Increase ZERO_UPSTREAM_MAX_CONNS or decrease ZERO_NUM_SYNC_WORKERS (which defaults to available cores).`,\n    );\n  }\n  if (config.cvr.maxConns < numSyncers) {\n    throw new Error(\n      `Insufficient cvr connections (${config.cvr.maxConns}) for ${numSyncers} syncers.` +\n        `Increase ZERO_CVR_MAX_CONNS or decrease ZERO_NUM_SYNC_WORKERS (which defaults to available cores).`,\n    );\n  }\n\n  const internalFlags: string[] =\n    numSyncers === 0\n      ? []\n      : [\n          '--upstream-max-conns-per-worker',\n          String(Math.floor(config.upstream.maxConns / numSyncers)),\n          '--cvr-max-conns-per-worker',\n          String(Math.floor(config.cvr.maxConns / numSyncers)),\n        ];\n\n  function loadWorker(\n    moduleUrl: URL,\n    type: WorkerType,\n    id?: string | number,\n    ...args: string[]\n  ): Worker {\n    const worker = childWorker(moduleUrl, env, ...args, ...internalFlags);\n    const name = path.basename(moduleUrl.pathname) + (id ? ` (${id})` : '');\n    return processes.addWorker(worker, type, name);\n  }\n\n  const {\n    taskID,\n    changeStreamer: {mode: changeStreamerMode, uri: changeStreamerURI},\n    litestream,\n  } = config;\n  const runChangeStreamer =\n    changeStreamerMode === 'dedicated' && changeStreamerURI === undefined;\n  const sqliteChangeLogEnabled =\n    config.changeStreamer.sqliteChangeLogMode !== 'off';\n  assert(\n    !sqliteChangeLogEnabled || runChangeStreamer,\n    'SQLite change-log writing requires this process tree to run the change-streamer, which is where the writer lives',\n  );\n\n  let changeStreamer: Worker | undefined;\n\n  if (runChangeStreamer) {\n    const {promise: changeStreamerReady, resolve: changeStreamerStarted} =\n      resolver();\n    changeStreamer = loadWorker(CHANGE_STREAMER_URL, 'supporting').once(\n      'message',\n      changeStreamerStarted,\n    );\n    // Wait for the change-streamer to be ready to guarantee that a replica\n    // file is present.\n    await changeStreamerReady;\n  }\n\n  if (numSyncers > 0) {\n    const {promise: reaperReady, resolve: reaperStarted} = resolver();\n    loadWorker(REAPER_URL, 'supporting').once('message', reaperStarted);\n    // Before starting the view-syncers, ensure that the reaper has started\n    // up, indicating that any CVR db migrations have been performed.\n    await reaperReady;\n  }\n\n  // Only run the shadow-sync canary on the replication-manager (or in\n  // single-node mode, where it also owns upstream). Running on every\n  // view-syncer would hammer the upstream with N redundant canaries.\n  if (config.shadowSync.enabled && runChangeStreamer) {\n    const {promise: shadowReady, resolve: shadowStarted} = resolver();\n    loadWorker(SHADOW_SYNCER_URL, 'supporting').once('message', shadowStarted);\n    await shadowReady;\n  }\n\n  const syncers: Worker[] = [];\n  if (numSyncers) {\n    const mode: ReplicaFileMode =\n      runChangeStreamer && litestream.backupURL ? 'serving-copy' : 'serving';\n    const {promise: replicaReady, resolve} = resolver();\n    const replicator = loadWorker(\n      REPLICATOR_URL,\n      'supporting',\n      mode,\n      mode,\n    ).once('message', () => {\n      subscribeTo(lc, replicator);\n      resolve();\n    });\n    await replicaReady;\n\n    const notifier = createNotifierFrom(lc, replicator);\n    for (let i = 0; i < numSyncers; i++) {\n      syncers.push(loadWorker(SYNCER_URL, 'user-facing', i, mode, String(i)));\n    }\n    syncers.forEach(syncer => handleSubscriptionsFrom(lc, syncer, notifier));\n  }\n  let mutator: Worker | undefined;\n  if (clientConnectionBifurcated) {\n    mutator = loadWorker(MUTATOR_URL, 'supporting', 'mutator');\n  }\n\n  lc.info?.('waiting for workers to be ready ...');\n  const logWaiting = setInterval(\n    () => lc.info?.(`still waiting for ${processes.initializing().join(', ')}`),\n    10_000,\n  );\n  await processes.allWorkersReady();\n  clearInterval(logWaiting);\n  const startupDurationMs = Date.now() - startMs;\n  lc.info?.(`all workers ready (${startupDurationMs} ms)`);\n  recordStartupDurationMs(startupDurationMs);\n\n  parent.send(['ready', {ready: true}]);\n\n  try {\n    await runUntilKilled(\n      lc,\n      parent,\n      new WorkerDispatcher(\n        lc,\n        taskID,\n        parent,\n        syncers,\n        mutator,\n        changeStreamer,\n      ),\n    );\n  } catch (err) {\n    processes.logErrorAndExit(err, 'dispatcher');\n  } finally {\n    await processes.shutdown();\n  }\n}\n\nif (!singleProcessMode()) {\n  void exitAfter(\n    () => lc,\n    () => runWorker(must(parentWorker), process.env),\n  );\n}\n"],"mappings":"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"}

package/out/zero-cache/src/server/replicator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replicator.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/server/replicator.ts"],"names":[],"mappings":"AAmBA,OAAO,EAGL,KAAK,MAAM,EACZ,MAAM,uBAAuB,CAAC;AAe/B,wBAA8B,SAAS,CACrC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,IAAI,CAAC,CAoFf"}
+{"version":3,"file":"replicator.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/server/replicator.ts"],"names":[],"mappings":"AAmCA,OAAO,EAGL,KAAK,MAAM,EACZ,MAAM,uBAAuB,CAAC;AAgB/B,wBAA8B,SAAS,CACrC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,IAAI,CAAC,CAiGf"}