@rocicorp/zero 1.11.0-canary.3 → 1.11.0-canary.30

package/out/zero-cache/src/services/view-syncer/drain-coordinator.js.map

@@ -1 +1 @@
-{"version":3,"file":"drain-coordinator.js","names":["#draining","#nextDrainTime","#timeoutID","#timeout"],"sources":["../../../../../../zero-cache/src/services/view-syncer/drain-coordinator.ts"],"sourcesContent":["import {resolver} from '@rocicorp/resolver';\nimport {assert} from '../../../../shared/src/asserts.ts';\n\n// The target (additional) utilization to impose on the server\n// that receives the drained connections.\nconst TARGET_UTILIZATION = 0.6;\n\n/**\n * There are two types of drains:\n * 1. Elective drains happen when a view-syncer is about to process\n *    a replication event and drains instead because {@link shouldDrain()}\n *    returned true. In this case, it exits its processing loop and\n *    calls {@link drainNextIn()} immediately.\n * 2. Force drains are performed by the Syncer, which picks a random\n *    view-syncer and calls {@link stop()}.\n *\n * In the case of a forced drain, the view-syncer may be queued up\n * behind a large amount of CPU-consuming events, and thus it may take\n * a long time before it actually stops. Elective drains are preferred because\n * they are less subject to that variance. However, elective drains only happen\n * if there is a task to be processed, so forced drains are still necessary\n * for draining servers with no work / tasks.\n *\n * The Syncer kicks off the drain process by calling {@link drainNextIn drainNextIn(0)},\n * which sets off a short {@link forceDrainTimeout} but starts returning `true` for\n * {@link shouldDrain()} for elective drains. In the latter case, the drained\n * view-syncer immediately exiting its processing loop and calls\n * {@link drainNextIn drainNextIn(myHydrationTime)} to reset the timeout\n * for the next elective or forced drain.\n */\nexport class DrainCoordinator {\n  readonly #draining = resolver<'draining'>();\n  #nextDrainTime = 0;\n  #timeout = resolver();\n  #timeoutID: NodeJS.Timeout | undefined;\n\n  get draining(): Promise<'draining'> {\n    return this.#draining.promise;\n  }\n\n  shouldDrain() {\n    return this.#nextDrainTime && this.#nextDrainTime <= Date.now();\n  }\n\n  drainNextIn(interval: number) {\n    this.#draining.resolve('draining');\n    // Increase the timeout between drains to give the receiving\n    // server space to perform normal processing.\n    interval /= TARGET_UTILIZATION;\n\n    const now = Date.now();\n    assert(\n      this.#nextDrainTime <= now,\n      `drainNextIn() should only be called if shouldDrain()`,\n    );\n    this.#nextDrainTime = now + interval;\n\n    // Push the forceDrainTimeout forward.\n    clearTimeout(this.#timeoutID);\n    this.#timeoutID = setTimeout(() => {\n      this.#timeout.resolve();\n      this.#timeout = resolver();\n    }, interval + FORCE_DRAIN_PADDING);\n  }\n\n  get forceDrainTimeout() {\n    return this.#timeout.promise;\n  }\n\n  // Exposed for testing.\n  get nextDrainTime() {\n    return this.#nextDrainTime;\n  }\n}\n\nconst FORCE_DRAIN_PADDING = 2;\n"],"mappings":";;;AAKA,IAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;AAyB3B,IAAa,mBAAb,MAA8B;CAC5B,YAAqB,SAAqB;CAC1C,iBAAiB;CACjB,WAAW,SAAS;CACpB;CAEA,IAAI,WAAgC;EAClC,OAAO,KAAKA,UAAU;CACxB;CAEA,cAAc;EACZ,OAAO,KAAKC,kBAAkB,KAAKA,kBAAkB,KAAK,IAAI;CAChE;CAEA,YAAY,UAAkB;EAC5B,KAAKD,UAAU,QAAQ,UAAU;EAGjC,YAAY;EAEZ,MAAM,MAAM,KAAK,IAAI;EACrB,OACE,KAAKC,kBAAkB,KACvB,sDACF;EACA,KAAKA,iBAAiB,MAAM;EAG5B,aAAa,KAAKC,UAAU;EAC5B,KAAKA,aAAa,iBAAiB;GACjC,KAAKC,SAAS,QAAQ;GACtB,KAAKA,WAAW,SAAS;EAC3B,GAAG,WAAW,mBAAmB;CACnC;CAEA,IAAI,oBAAoB;EACtB,OAAO,KAAKA,SAAS;CACvB;CAGA,IAAI,gBAAgB;EAClB,OAAO,KAAKF;CACd;AACF;AAEA,IAAM,sBAAsB"}
+{"version":3,"file":"drain-coordinator.js","names":["#drainListeners","#draining","#nextDrainTime","#timeoutID","#timeout"],"sources":["../../../../../../zero-cache/src/services/view-syncer/drain-coordinator.ts"],"sourcesContent":["import {resolver} from '@rocicorp/resolver';\nimport {assert} from '../../../../shared/src/asserts.ts';\n\ntype DrainListener = () => void;\n\n// The target (additional) utilization to impose on the server\n// that receives the drained connections.\nconst TARGET_UTILIZATION = 0.6;\n\n/**\n * There are two types of drains:\n * 1. Elective drains happen when a view-syncer is about to process\n *    a replication event and drains instead because {@link shouldDrain()}\n *    returned true. In this case, it exits its processing loop and\n *    calls {@link drainNextIn()} immediately.\n * 2. Force drains are performed by the Syncer, which picks a random\n *    view-syncer and calls {@link stop()}.\n *\n * In the case of a forced drain, the view-syncer may be queued up\n * behind a large amount of CPU-consuming events, and thus it may take\n * a long time before it actually stops. Elective drains are preferred because\n * they are less subject to that variance. However, elective drains only happen\n * if there is a task to be processed, so forced drains are still necessary\n * for draining servers with no work / tasks.\n *\n * The Syncer kicks off the drain process by calling {@link drainNextIn drainNextIn(0)},\n * which sets off a short {@link forceDrainTimeout} but starts returning `true` for\n * {@link shouldDrain()} for elective drains. In the latter case, the drained\n * view-syncer immediately exiting its processing loop and calls\n * {@link drainNextIn drainNextIn(myHydrationTime)} to reset the timeout\n * for the next elective or forced drain.\n */\nexport class DrainCoordinator {\n  #draining = false;\n  readonly #drainListeners = new Set<DrainListener>();\n  #nextDrainTime = 0;\n  #timeout = resolver();\n  #timeoutID: NodeJS.Timeout | undefined;\n\n  /**\n   * Calls `listener` once draining has started (immediately if it already\n   * has) and returns a function that unsubscribes it.\n   *\n   * This is a subscription rather than a Promise so that a caller that stops\n   * caring (e.g. a view-syncer that finished initializing) can let go of it.\n   * A reaction attached to a Promise that may never settle would otherwise\n   * be retained by the coordinator for the lifetime of the server, once per\n   * view-syncer ever created.\n   */\n  onDraining(listener: DrainListener): () => void {\n    if (this.#draining) {\n      listener();\n      return () => {};\n    }\n    this.#drainListeners.add(listener);\n    return () => {\n      this.#drainListeners.delete(listener);\n    };\n  }\n\n  // Exposed for testing.\n  get drainListenerCount() {\n    return this.#drainListeners.size;\n  }\n\n  shouldDrain() {\n    return this.#nextDrainTime && this.#nextDrainTime <= Date.now();\n  }\n\n  drainNextIn(interval: number) {\n    if (!this.#draining) {\n      this.#draining = true;\n      const listeners = [...this.#drainListeners];\n      this.#drainListeners.clear();\n      for (const listener of listeners) {\n        listener();\n      }\n    }\n    // Increase the timeout between drains to give the receiving\n    // server space to perform normal processing.\n    interval /= TARGET_UTILIZATION;\n\n    const now = Date.now();\n    assert(\n      this.#nextDrainTime <= now,\n      `drainNextIn() should only be called if shouldDrain()`,\n    );\n    this.#nextDrainTime = now + interval;\n\n    // Push the forceDrainTimeout forward.\n    clearTimeout(this.#timeoutID);\n    this.#timeoutID = setTimeout(() => {\n      this.#timeout.resolve();\n      this.#timeout = resolver();\n    }, interval + FORCE_DRAIN_PADDING);\n  }\n\n  get forceDrainTimeout() {\n    return this.#timeout.promise;\n  }\n\n  // Exposed for testing.\n  get nextDrainTime() {\n    return this.#nextDrainTime;\n  }\n}\n\nconst FORCE_DRAIN_PADDING = 2;\n"],"mappings":";;;AAOA,IAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;AAyB3B,IAAa,mBAAb,MAA8B;CAC5B,YAAY;CACZ,kCAA2B,IAAI,IAAmB;CAClD,iBAAiB;CACjB,WAAW,SAAS;CACpB;;;;;;;;;;;CAYA,WAAW,UAAqC;EAC9C,IAAI,KAAKC,WAAW;GAClB,SAAS;GACT,aAAa,CAAC;EAChB;EACA,KAAKD,gBAAgB,IAAI,QAAQ;EACjC,aAAa;GACX,KAAKA,gBAAgB,OAAO,QAAQ;EACtC;CACF;CAGA,IAAI,qBAAqB;EACvB,OAAO,KAAKA,gBAAgB;CAC9B;CAEA,cAAc;EACZ,OAAO,KAAKE,kBAAkB,KAAKA,kBAAkB,KAAK,IAAI;CAChE;CAEA,YAAY,UAAkB;EAC5B,IAAI,CAAC,KAAKD,WAAW;GACnB,KAAKA,YAAY;GACjB,MAAM,YAAY,CAAC,GAAG,KAAKD,eAAe;GAC1C,KAAKA,gBAAgB,MAAM;GAC3B,KAAK,MAAM,YAAY,WACrB,SAAS;EAEb;EAGA,YAAY;EAEZ,MAAM,MAAM,KAAK,IAAI;EACrB,OACE,KAAKE,kBAAkB,KACvB,sDACF;EACA,KAAKA,iBAAiB,MAAM;EAG5B,aAAa,KAAKC,UAAU;EAC5B,KAAKA,aAAa,iBAAiB;GACjC,KAAKC,SAAS,QAAQ;GACtB,KAAKA,WAAW,SAAS;EAC3B,GAAG,WAAW,mBAAmB;CACnC;CAEA,IAAI,oBAAoB;EACtB,OAAO,KAAKA,SAAS;CACvB;CAGA,IAAI,gBAAgB;EAClB,OAAO,KAAKF;CACd;AACF;AAEA,IAAM,sBAAsB"}

package/out/zero-cache/src/services/view-syncer/hydration-budget.d.ts

@@ -0,0 +1,33 @@
+export type MonotonicClock = () => number;
+/**
+ * A soft wall-clock budget for one view-syncer hydration pass.
+ *
+ * Callers check the budget only at query boundaries. Consequently, a query
+ * that starts before the limit is reached is always allowed to finish.
+ *
+ * The budget measures hydration work. Intervals that are not hydration --
+ * notably the remote custom-query transform round trips -- are discounted via
+ * {@link excluding}, so that endpoint latency cannot spend a budget that only
+ * evicting queries could recover.
+ */
+export declare class HydrationBudget {
+    #private;
+    readonly limitMs: number;
+    constructor(limitMs: number, now?: MonotonicClock);
+    /**
+     * Runs `fn`, discounting the time it takes as non-hydration work. The
+     * interval is measured with this budget's own clock, so an injected clock
+     * governs both the elapsed time and what is excluded from it.
+     */
+    excluding<T>(fn: () => Promise<T>): Promise<T>;
+    elapsedMs(): number;
+    /**
+     * Whether the budget is spent. A disabled budget (`limitMs === 0`) is never
+     * exhausted. The elapsed time at the first exhausted check is retained in
+     * {@link exhaustedAtMs} so that reporting does not re-read the clock.
+     */
+    exhausted(): boolean;
+    /** The elapsed time at which {@link exhausted} first returned true. */
+    get exhaustedAtMs(): number | undefined;
+}
+//# sourceMappingURL=hydration-budget.d.ts.map

package/out/zero-cache/src/services/view-syncer/hydration-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydration-budget.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/view-syncer/hydration-budget.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAMzB,YACE,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,cAAkD,EASxD;IAED;;;;OAIG;IACG,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAOnD;IAED,SAAS,IAAI,MAAM,CAElB;IAED;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAUnB;IAED,uEAAuE;IACvE,IAAI,aAAa,IAAI,MAAM,GAAG,SAAS,CAEtC;CACF"}

package/out/zero-cache/src/services/view-syncer/hydration-budget.js

@@ -0,0 +1,62 @@
+import { assert } from "../../../../shared/src/asserts.js";
+//#region ../zero-cache/src/services/view-syncer/hydration-budget.ts
+/**
+* A soft wall-clock budget for one view-syncer hydration pass.
+*
+* Callers check the budget only at query boundaries. Consequently, a query
+* that starts before the limit is reached is always allowed to finish.
+*
+* The budget measures hydration work. Intervals that are not hydration --
+* notably the remote custom-query transform round trips -- are discounted via
+* {@link excluding}, so that endpoint latency cannot spend a budget that only
+* evicting queries could recover.
+*/
+var HydrationBudget = class {
+	limitMs;
+	#now;
+	#startedAt;
+	#excludedMs = 0;
+	#exhaustedAtMs;
+	constructor(limitMs, now = performance.now.bind(performance)) {
+		assert(Number.isSafeInteger(limitMs) && limitMs >= 0, "Hydration budget must be a nonnegative integer");
+		this.limitMs = limitMs;
+		this.#now = now;
+		this.#startedAt = now();
+	}
+	/**
+	* Runs `fn`, discounting the time it takes as non-hydration work. The
+	* interval is measured with this budget's own clock, so an injected clock
+	* governs both the elapsed time and what is excluded from it.
+	*/
+	async excluding(fn) {
+		const start = this.#now();
+		try {
+			return await fn();
+		} finally {
+			this.#excludedMs += this.#now() - start;
+		}
+	}
+	elapsedMs() {
+		return this.#now() - this.#startedAt - this.#excludedMs;
+	}
+	/**
+	* Whether the budget is spent. A disabled budget (`limitMs === 0`) is never
+	* exhausted. The elapsed time at the first exhausted check is retained in
+	* {@link exhaustedAtMs} so that reporting does not re-read the clock.
+	*/
+	exhausted() {
+		if (this.limitMs === 0) return false;
+		const elapsed = this.elapsedMs();
+		if (elapsed < this.limitMs) return false;
+		this.#exhaustedAtMs ??= elapsed;
+		return true;
+	}
+	/** The elapsed time at which {@link exhausted} first returned true. */
+	get exhaustedAtMs() {
+		return this.#exhaustedAtMs;
+	}
+};
+//#endregion
+export { HydrationBudget };
+
+//# sourceMappingURL=hydration-budget.js.map

package/out/zero-cache/src/services/view-syncer/hydration-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydration-budget.js","names":["#now","#startedAt","#excludedMs","#exhaustedAtMs"],"sources":["../../../../../../zero-cache/src/services/view-syncer/hydration-budget.ts"],"sourcesContent":["import {assert} from '../../../../shared/src/asserts.ts';\n\nexport type MonotonicClock = () => number;\n\n/**\n * A soft wall-clock budget for one view-syncer hydration pass.\n *\n * Callers check the budget only at query boundaries. Consequently, a query\n * that starts before the limit is reached is always allowed to finish.\n *\n * The budget measures hydration work. Intervals that are not hydration --\n * notably the remote custom-query transform round trips -- are discounted via\n * {@link excluding}, so that endpoint latency cannot spend a budget that only\n * evicting queries could recover.\n */\nexport class HydrationBudget {\n  readonly limitMs: number;\n  readonly #now: MonotonicClock;\n  readonly #startedAt: number;\n  #excludedMs = 0;\n  #exhaustedAtMs: number | undefined;\n\n  constructor(\n    limitMs: number,\n    now: MonotonicClock = performance.now.bind(performance),\n  ) {\n    assert(\n      Number.isSafeInteger(limitMs) && limitMs >= 0,\n      'Hydration budget must be a nonnegative integer',\n    );\n    this.limitMs = limitMs;\n    this.#now = now;\n    this.#startedAt = now();\n  }\n\n  /**\n   * Runs `fn`, discounting the time it takes as non-hydration work. The\n   * interval is measured with this budget's own clock, so an injected clock\n   * governs both the elapsed time and what is excluded from it.\n   */\n  async excluding<T>(fn: () => Promise<T>): Promise<T> {\n    const start = this.#now();\n    try {\n      return await fn();\n    } finally {\n      this.#excludedMs += this.#now() - start;\n    }\n  }\n\n  elapsedMs(): number {\n    return this.#now() - this.#startedAt - this.#excludedMs;\n  }\n\n  /**\n   * Whether the budget is spent. A disabled budget (`limitMs === 0`) is never\n   * exhausted. The elapsed time at the first exhausted check is retained in\n   * {@link exhaustedAtMs} so that reporting does not re-read the clock.\n   */\n  exhausted(): boolean {\n    if (this.limitMs === 0) {\n      return false;\n    }\n    const elapsed = this.elapsedMs();\n    if (elapsed < this.limitMs) {\n      return false;\n    }\n    this.#exhaustedAtMs ??= elapsed;\n    return true;\n  }\n\n  /** The elapsed time at which {@link exhausted} first returned true. */\n  get exhaustedAtMs(): number | undefined {\n    return this.#exhaustedAtMs;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAeA,IAAa,kBAAb,MAA6B;CAC3B;CACA;CACA;CACA,cAAc;CACd;CAEA,YACE,SACA,MAAsB,YAAY,IAAI,KAAK,WAAW,GACtD;EACA,OACE,OAAO,cAAc,OAAO,KAAK,WAAW,GAC5C,gDACF;EACA,KAAK,UAAU;EACf,KAAKA,OAAO;EACZ,KAAKC,aAAa,IAAI;CACxB;;;;;;CAOA,MAAM,UAAa,IAAkC;EACnD,MAAM,QAAQ,KAAKD,KAAK;EACxB,IAAI;GACF,OAAO,MAAM,GAAG;EAClB,UAAU;GACR,KAAKE,eAAe,KAAKF,KAAK,IAAI;EACpC;CACF;CAEA,YAAoB;EAClB,OAAO,KAAKA,KAAK,IAAI,KAAKC,aAAa,KAAKC;CAC9C;;;;;;CAOA,YAAqB;EACnB,IAAI,KAAK,YAAY,GACnB,OAAO;EAET,MAAM,UAAU,KAAK,UAAU;EAC/B,IAAI,UAAU,KAAK,SACjB,OAAO;EAET,KAAKC,mBAAmB;EACxB,OAAO;CACT;;CAGA,IAAI,gBAAoC;EACtC,OAAO,KAAKA;CACd;AACF"}

package/out/zero-cache/src/services/view-syncer/hydration-circuit-breaker.d.ts

@@ -0,0 +1,51 @@
+import type { MonotonicClock } from './hydration-budget.ts';
+/**
+ * How long a tripped query stays rejected before a retry is allowed.
+ *
+ * A query that blows the timeout is almost always slow because of the shape
+ * of its data rather than because of transient load, so retrying it on every
+ * reconnect would burn a full timeout each time. The cooldown keeps that cost
+ * to at most one timeout per cooldown period per query.
+ */
+export declare const DEFAULT_CIRCUIT_BREAKER_OPEN_MS: number;
+/**
+ * A per-query circuit breaker for view-syncer hydration.
+ *
+ * Hydration of a single query is aborted once its processing time exceeds
+ * {@link timeoutMs}. Callers check {@link exceeded} at the yield points of a
+ * hydration, so a query is only ever aborted between time slices.
+ *
+ * Once a query has been aborted the breaker is "open" for its transformation
+ * hash: {@link isOpen} reports true for {@link openMs}, and callers reject the
+ * query up front instead of hydrating it again. After that the breaker is
+ * implicitly half-open: the next hydration attempt runs, and either succeeds
+ * or trips the breaker again.
+ *
+ * The breaker is keyed by transformation hash rather than query hash because
+ * the transformation (permissions, auth context) determines the pipeline that
+ * runs, and a different transformation of the same query may well be fast.
+ */
+export declare class HydrationCircuitBreaker {
+    #private;
+    readonly timeoutMs: number;
+    readonly openMs: number;
+    constructor(timeoutMs: number, openMs?: number, now?: MonotonicClock);
+    /** Whether the breaker does anything at all. */
+    get enabled(): boolean;
+    /**
+     * Whether a hydration that has consumed `elapsedMs` of processing time must
+     * be aborted. Always false when the breaker is disabled.
+     */
+    exceeded(elapsedMs: number): boolean;
+    /**
+     * Records that hydrating `transformationHash` was aborted.
+     *
+     * Trips are rare, so this is also when expired entries are swept, which
+     * keeps the map bounded by the number of hashes tripped within one cooldown
+     * rather than by every hash ever tripped.
+     */
+    trip(transformationHash: string): void;
+    /** Whether `transformationHash` is currently rejected. */
+    isOpen(transformationHash: string): boolean;
+}
+//# sourceMappingURL=hydration-circuit-breaker.d.ts.map

package/out/zero-cache/src/services/view-syncer/hydration-circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydration-circuit-breaker.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/view-syncer/hydration-circuit-breaker.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,uBAAuB,CAAC;AAE1D;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,QAAa,CAAC;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,uBAAuB;;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAIxB,YACE,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,MAAwC,EAChD,GAAG,GAAE,cAAkD,EAUxD;IAED,gDAAgD;IAChD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEnC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAQrC;IAED,0DAA0D;IAC1D,MAAM,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAU1C;CACF"}

package/out/zero-cache/src/services/view-syncer/hydration-circuit-breaker.js

@@ -0,0 +1,78 @@
+import { assert } from "../../../../shared/src/asserts.js";
+//#region ../zero-cache/src/services/view-syncer/hydration-circuit-breaker.ts
+/**
+* How long a tripped query stays rejected before a retry is allowed.
+*
+* A query that blows the timeout is almost always slow because of the shape
+* of its data rather than because of transient load, so retrying it on every
+* reconnect would burn a full timeout each time. The cooldown keeps that cost
+* to at most one timeout per cooldown period per query.
+*/
+var DEFAULT_CIRCUIT_BREAKER_OPEN_MS = 5 * 6e4;
+/**
+* A per-query circuit breaker for view-syncer hydration.
+*
+* Hydration of a single query is aborted once its processing time exceeds
+* {@link timeoutMs}. Callers check {@link exceeded} at the yield points of a
+* hydration, so a query is only ever aborted between time slices.
+*
+* Once a query has been aborted the breaker is "open" for its transformation
+* hash: {@link isOpen} reports true for {@link openMs}, and callers reject the
+* query up front instead of hydrating it again. After that the breaker is
+* implicitly half-open: the next hydration attempt runs, and either succeeds
+* or trips the breaker again.
+*
+* The breaker is keyed by transformation hash rather than query hash because
+* the transformation (permissions, auth context) determines the pipeline that
+* runs, and a different transformation of the same query may well be fast.
+*/
+var HydrationCircuitBreaker = class {
+	timeoutMs;
+	openMs;
+	#now;
+	#openedAt = /* @__PURE__ */ new Map();
+	constructor(timeoutMs, openMs = DEFAULT_CIRCUIT_BREAKER_OPEN_MS, now = performance.now.bind(performance)) {
+		assert(Number.isSafeInteger(timeoutMs) && timeoutMs >= 0, "Hydration timeout must be a nonnegative integer");
+		assert(openMs >= 0, "Circuit breaker open duration must be nonnegative");
+		this.timeoutMs = timeoutMs;
+		this.openMs = openMs;
+		this.#now = now;
+	}
+	/** Whether the breaker does anything at all. */
+	get enabled() {
+		return this.timeoutMs > 0;
+	}
+	/**
+	* Whether a hydration that has consumed `elapsedMs` of processing time must
+	* be aborted. Always false when the breaker is disabled.
+	*/
+	exceeded(elapsedMs) {
+		return this.enabled && elapsedMs >= this.timeoutMs;
+	}
+	/**
+	* Records that hydrating `transformationHash` was aborted.
+	*
+	* Trips are rare, so this is also when expired entries are swept, which
+	* keeps the map bounded by the number of hashes tripped within one cooldown
+	* rather than by every hash ever tripped.
+	*/
+	trip(transformationHash) {
+		const now = this.#now();
+		for (const [hash, openedAt] of this.#openedAt) if (now - openedAt >= this.openMs) this.#openedAt.delete(hash);
+		this.#openedAt.set(transformationHash, now);
+	}
+	/** Whether `transformationHash` is currently rejected. */
+	isOpen(transformationHash) {
+		const openedAt = this.#openedAt.get(transformationHash);
+		if (openedAt === void 0) return false;
+		if (this.#now() - openedAt >= this.openMs) {
+			this.#openedAt.delete(transformationHash);
+			return false;
+		}
+		return true;
+	}
+};
+//#endregion
+export { HydrationCircuitBreaker };
+
+//# sourceMappingURL=hydration-circuit-breaker.js.map

package/out/zero-cache/src/services/view-syncer/hydration-circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydration-circuit-breaker.js","names":["#now","#openedAt"],"sources":["../../../../../../zero-cache/src/services/view-syncer/hydration-circuit-breaker.ts"],"sourcesContent":["import {assert} from '../../../../shared/src/asserts.ts';\nimport type {MonotonicClock} from './hydration-budget.ts';\n\n/**\n * How long a tripped query stays rejected before a retry is allowed.\n *\n * A query that blows the timeout is almost always slow because of the shape\n * of its data rather than because of transient load, so retrying it on every\n * reconnect would burn a full timeout each time. The cooldown keeps that cost\n * to at most one timeout per cooldown period per query.\n */\nexport const DEFAULT_CIRCUIT_BREAKER_OPEN_MS = 5 * 60_000;\n\n/**\n * A per-query circuit breaker for view-syncer hydration.\n *\n * Hydration of a single query is aborted once its processing time exceeds\n * {@link timeoutMs}. Callers check {@link exceeded} at the yield points of a\n * hydration, so a query is only ever aborted between time slices.\n *\n * Once a query has been aborted the breaker is \"open\" for its transformation\n * hash: {@link isOpen} reports true for {@link openMs}, and callers reject the\n * query up front instead of hydrating it again. After that the breaker is\n * implicitly half-open: the next hydration attempt runs, and either succeeds\n * or trips the breaker again.\n *\n * The breaker is keyed by transformation hash rather than query hash because\n * the transformation (permissions, auth context) determines the pipeline that\n * runs, and a different transformation of the same query may well be fast.\n */\nexport class HydrationCircuitBreaker {\n  readonly timeoutMs: number;\n  readonly openMs: number;\n  readonly #now: MonotonicClock;\n  readonly #openedAt = new Map<string, number>();\n\n  constructor(\n    timeoutMs: number,\n    openMs: number = DEFAULT_CIRCUIT_BREAKER_OPEN_MS,\n    now: MonotonicClock = performance.now.bind(performance),\n  ) {\n    assert(\n      Number.isSafeInteger(timeoutMs) && timeoutMs >= 0,\n      'Hydration timeout must be a nonnegative integer',\n    );\n    assert(openMs >= 0, 'Circuit breaker open duration must be nonnegative');\n    this.timeoutMs = timeoutMs;\n    this.openMs = openMs;\n    this.#now = now;\n  }\n\n  /** Whether the breaker does anything at all. */\n  get enabled(): boolean {\n    return this.timeoutMs > 0;\n  }\n\n  /**\n   * Whether a hydration that has consumed `elapsedMs` of processing time must\n   * be aborted. Always false when the breaker is disabled.\n   */\n  exceeded(elapsedMs: number): boolean {\n    return this.enabled && elapsedMs >= this.timeoutMs;\n  }\n\n  /**\n   * Records that hydrating `transformationHash` was aborted.\n   *\n   * Trips are rare, so this is also when expired entries are swept, which\n   * keeps the map bounded by the number of hashes tripped within one cooldown\n   * rather than by every hash ever tripped.\n   */\n  trip(transformationHash: string): void {\n    const now = this.#now();\n    for (const [hash, openedAt] of this.#openedAt) {\n      if (now - openedAt >= this.openMs) {\n        this.#openedAt.delete(hash);\n      }\n    }\n    this.#openedAt.set(transformationHash, now);\n  }\n\n  /** Whether `transformationHash` is currently rejected. */\n  isOpen(transformationHash: string): boolean {\n    const openedAt = this.#openedAt.get(transformationHash);\n    if (openedAt === undefined) {\n      return false;\n    }\n    if (this.#now() - openedAt >= this.openMs) {\n      this.#openedAt.delete(transformationHash);\n      return false;\n    }\n    return true;\n  }\n}\n"],"mappings":";;;;;;;;;;AAWA,IAAa,kCAAkC,IAAI;;;;;;;;;;;;;;;;;;AAmBnD,IAAa,0BAAb,MAAqC;CACnC;CACA;CACA;CACA,4BAAqB,IAAI,IAAoB;CAE7C,YACE,WACA,SAAiB,iCACjB,MAAsB,YAAY,IAAI,KAAK,WAAW,GACtD;EACA,OACE,OAAO,cAAc,SAAS,KAAK,aAAa,GAChD,iDACF;EACA,OAAO,UAAU,GAAG,mDAAmD;EACvE,KAAK,YAAY;EACjB,KAAK,SAAS;EACd,KAAKA,OAAO;CACd;;CAGA,IAAI,UAAmB;EACrB,OAAO,KAAK,YAAY;CAC1B;;;;;CAMA,SAAS,WAA4B;EACnC,OAAO,KAAK,WAAW,aAAa,KAAK;CAC3C;;;;;;;;CASA,KAAK,oBAAkC;EACrC,MAAM,MAAM,KAAKA,KAAK;EACtB,KAAK,MAAM,CAAC,MAAM,aAAa,KAAKC,WAClC,IAAI,MAAM,YAAY,KAAK,QACzB,KAAKA,UAAU,OAAO,IAAI;EAG9B,KAAKA,UAAU,IAAI,oBAAoB,GAAG;CAC5C;;CAGA,OAAO,oBAAqC;EAC1C,MAAM,WAAW,KAAKA,UAAU,IAAI,kBAAkB;EACtD,IAAI,aAAa,KAAA,GACf,OAAO;EAET,IAAI,KAAKD,KAAK,IAAI,YAAY,KAAK,QAAQ;GACzC,KAAKC,UAAU,OAAO,kBAAkB;GACxC,OAAO;EACT;EACA,OAAO;CACT;AACF"}

package/out/zero-cache/src/services/view-syncer/inspect-handler.d.ts

@@ -1,4 +1,5 @@
 import type { LogContext } from '@rocicorp/logger';
+import type { AnalyzeQueryResult } from '../../../../zero-protocol/src/analyze-query-result.ts';
 import type { QueryServerMetrics } from '../../../../zero-protocol/src/inspect-down.ts';
 import { type UnparsedInspectUpBody } from '../../../../zero-protocol/src/inspect-up.ts';
 import type { NormalizedZeroConfig } from '../../config/normalize.ts';
@@ -7,7 +8,15 @@ import type { ClientHandler } from './client-handler.ts';
 import type { ConnectionContext } from './connection-context-manager.ts';
 import type { CVRStore } from './cvr-store.ts';
 import type { CVRSnapshot } from './cvr.ts';
-export declare function handleInspect(lc: LogContext, body: UnparsedInspectUpBody, cvr: CVRSnapshot, client: ClientHandler, inspectorDelegate: InspectorDelegate, clientGroupID: string, cvrStore: CVRStore, config: NormalizedZeroConfig, ctx: ConnectionContext): Promise<void>;
+export declare function handleInspect(lc: LogContext, body: UnparsedInspectUpBody, cvr: CVRSnapshot, client: ClientHandler, inspectorDelegate: InspectorDelegate, clientGroupID: string, authOwner: object, cvrStore: CVRStore, config: NormalizedZeroConfig, ctx: ConnectionContext): Promise<void>;
+/**
+ * Removes the planner's `filter` nodes from `joinPlans` for clients that
+ * can't parse them: a `filter` node fails an older client's parse of the
+ * whole message, which disconnects it.
+ *
+ * @visibleForTesting
+ */
+export declare function withoutFilterNodes(result: AnalyzeQueryResult): AnalyzeQueryResult;
 /**
  * Converts per-query server metrics to the appropriate wire format based on the
  * client's protocol version.

package/out/zero-cache/src/services/view-syncer/inspect-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inspect-handler.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/view-syncer/inspect-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAKjD,OAAO,KAAK,EACV,kBAAkB,EAEnB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,6CAA6C,CAAC;AAGrD,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,2BAA2B,CAAC;AAMpE,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,oCAAoC,CAAC;AAE1E,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,iCAAiC,CAAC;AACvE,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,UAAU,CAAC;AAE1C,wBAAsB,aAAa,CACjC,EAAE,EAAE,UAAU,EACd,IAAI,EAAE,qBAAqB,EAC3B,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,aAAa,EACrB,iBAAiB,EAAE,iBAAiB,EACpC,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,oBAAoB,EAC5B,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,IAAI,CAAC,CAiJf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,kBAAkB,GAAG,IAAI,EAClC,eAAe,EAAE,MAAM,GACtB,kBAAkB,GAAG,IAAI,CAmB3B"}
+{"version":3,"file":"inspect-handler.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/view-syncer/inspect-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAKjD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,uDAAuD,CAAC;AAE9F,OAAO,KAAK,EACV,kBAAkB,EAEnB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,6CAA6C,CAAC;AAGrD,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,2BAA2B,CAAC;AAMpE,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,oCAAoC,CAAC;AAE1E,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,iCAAiC,CAAC;AACvE,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,UAAU,CAAC;AAE1C,wBAAsB,aAAa,CACjC,EAAE,EAAE,UAAU,EACd,IAAI,EAAE,qBAAqB,EAC3B,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,aAAa,EACrB,iBAAiB,EAAE,iBAAiB,EACpC,aAAa,EAAE,MAAM,EAGrB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,oBAAoB,EAC5B,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,IAAI,CAAC,CAmJf;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,kBAAkB,GACzB,kBAAkB,CAUpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,kBAAkB,GAAG,IAAI,EAClC,eAAe,EAAE,MAAM,GACtB,kBAAkB,GAAG,IAAI,CAmB3B"}

package/out/zero-cache/src/services/view-syncer/inspect-handler.js

@@ -6,11 +6,11 @@ import { getServerVersion, isAdminPasswordValid } from "../../config/zero-config
 import { Database } from "../../../../zqlite/src/db.js";
 import { loadPermissions } from "../../auth/load-permissions.js";
 import { StatementRunner } from "../../db/statements.js";
-import { inspectAnalyzeQueryUpSchema } from "../../../../zero-protocol/src/inspect-up.js";
 import { _usingCtx } from "../../../../_virtual/_@oxc-project_runtime@0.130.0/helpers/usingCtx.js";
+import { inspectAnalyzeQueryUpSchema } from "../../../../zero-protocol/src/inspect-up.js";
 import { analyzeQuery } from "../analyze.js";
 //#region ../zero-cache/src/services/view-syncer/inspect-handler.ts
-async function handleInspect(lc, body, cvr, client, inspectorDelegate, clientGroupID, cvrStore, config, ctx) {
+async function handleInspect(lc, body, cvr, client, inspectorDelegate, clientGroupID, authOwner, cvrStore, config, ctx) {
 	if (body.op !== "authenticate" && !inspectorDelegate.isAuthenticated(clientGroupID)) {
 		lc.info?.("Client not authenticated to access the inspector protocol. Sending authentication challenge");
 		client.sendInspectResponse(lc, {
@@ -52,7 +52,7 @@ async function handleInspect(lc, body, cvr, client, inspectorDelegate, clientGro
 			case "authenticate": {
 				const password = body.value;
 				const ok = isAdminPasswordValid(lc, config, password);
-				if (ok) inspectorDelegate.setAuthenticated(clientGroupID);
+				if (ok) inspectorDelegate.setAuthenticated(clientGroupID, authOwner);
 				else inspectorDelegate.clearAuthenticated(clientGroupID);
 				client.sendInspectResponse(lc, {
 					op: "authenticated",
@@ -85,7 +85,7 @@ async function handleInspect(lc, body, cvr, client, inspectorDelegate, clientGro
 				client.sendInspectResponse(lc, {
 					op: "analyze-query",
 					id: body.id,
-					value: result
+					value: ctx.features.has(1) ? result : withoutFilterNodes(result)
 				});
 				break;
 			}
@@ -101,6 +101,20 @@ async function handleInspect(lc, body, cvr, client, inspectorDelegate, clientGro
 	}
 }
 /**
+* Removes the planner's `filter` nodes from `joinPlans` for clients that
+* can't parse them: a `filter` node fails an older client's parse of the
+* whole message, which disconnects it.
+*
+* @visibleForTesting
+*/
+function withoutFilterNodes(result) {
+	if (result.joinPlans === void 0) return result;
+	return {
+		...result,
+		joinPlans: result.joinPlans.filter((event) => !("nodeType" in event && event.nodeType === "filter"))
+	};
+}
+/**
 * Converts per-query server metrics to the appropriate wire format based on the
 * client's protocol version.
 *

package/out/zero-cache/src/services/view-syncer/inspect-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"inspect-handler.js","names":[],"sources":["../../../../../../zero-cache/src/services/view-syncer/inspect-handler.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {unreachable} from '../../../../shared/src/asserts.ts';\nimport {must} from '../../../../shared/src/must.ts';\nimport {TDigest} from '../../../../shared/src/tdigest.ts';\nimport * as v from '../../../../shared/src/valita.ts';\nimport type {\n  QueryServerMetrics,\n  ServerMetrics,\n} from '../../../../zero-protocol/src/inspect-down.ts';\nimport {\n  inspectAnalyzeQueryUpSchema,\n  type UnparsedInspectUpBody,\n} from '../../../../zero-protocol/src/inspect-up.ts';\nimport {Database} from '../../../../zqlite/src/db.ts';\nimport {loadPermissions} from '../../auth/load-permissions.ts';\nimport type {NormalizedZeroConfig} from '../../config/normalize.ts';\nimport {\n  getServerVersion,\n  isAdminPasswordValid,\n} from '../../config/zero-config.ts';\nimport {StatementRunner} from '../../db/statements.ts';\nimport type {InspectorDelegate} from '../../server/inspector-delegate.ts';\nimport {analyzeQuery} from '../analyze.ts';\nimport type {ClientHandler} from './client-handler.ts';\nimport type {ConnectionContext} from './connection-context-manager.ts';\nimport type {CVRStore} from './cvr-store.ts';\nimport type {CVRSnapshot} from './cvr.ts';\n\nexport async function handleInspect(\n  lc: LogContext,\n  body: UnparsedInspectUpBody,\n  cvr: CVRSnapshot,\n  client: ClientHandler,\n  inspectorDelegate: InspectorDelegate,\n  clientGroupID: string,\n  cvrStore: CVRStore,\n  config: NormalizedZeroConfig,\n  ctx: ConnectionContext,\n): Promise<void> {\n  // Check if the client is already authenticated. We only authenticate the clientGroup\n  // once per \"worker\".\n  if (\n    body.op !== 'authenticate' &&\n    !inspectorDelegate.isAuthenticated(clientGroupID)\n  ) {\n    lc.info?.(\n      'Client not authenticated to access the inspector protocol. Sending authentication challenge',\n    );\n    client.sendInspectResponse(lc, {\n      op: 'authenticated',\n      id: body.id,\n      value: false,\n    });\n    return;\n  }\n\n  try {\n    switch (body.op) {\n      case 'queries': {\n        const queryRows = await cvrStore.inspectQueries(\n          lc,\n          cvr.ttlClock,\n          body.clientID,\n        );\n\n        // Enhance query rows with server-side materialization metrics\n        const enhancedRows = queryRows.map(row => ({\n          ...row,\n          ast: row.ast ?? inspectorDelegate.getASTForQuery(row.queryID) ?? null,\n          metrics: metricsForProtocol(\n            inspectorDelegate.getMetricsJSONForQuery(row.queryID),\n            ctx.protocolVersion,\n          ),\n        }));\n\n        client.sendInspectResponse(lc, {\n          op: 'queries',\n          id: body.id,\n          value: enhancedRows,\n        });\n        break;\n      }\n\n      case 'metrics': {\n        client.sendInspectResponse(lc, {\n          op: 'metrics',\n          id: body.id,\n          value: inspectorDelegate.getMetricsJSON(),\n        });\n        break;\n      }\n\n      case 'version':\n        client.sendInspectResponse(lc, {\n          op: 'version',\n          id: body.id,\n          value: getServerVersion(config),\n        });\n        break;\n\n      case 'authenticate': {\n        const password = body.value;\n        const ok = isAdminPasswordValid(lc, config, password);\n        if (ok) {\n          inspectorDelegate.setAuthenticated(clientGroupID);\n        } else {\n          inspectorDelegate.clearAuthenticated(clientGroupID);\n        }\n\n        client.sendInspectResponse(lc, {\n          op: 'authenticated',\n          id: body.id,\n          value: ok,\n        });\n\n        break;\n      }\n\n      case 'analyze-query': {\n        const parsedBody = v.parse(body, inspectAnalyzeQueryUpSchema);\n        let ast = parsedBody.ast ?? parsedBody.value;\n        let legacyQuery = true;\n\n        if (parsedBody.name && parsedBody.args) {\n          // Get the AST from the API server by transforming the named query\n          ast = await inspectorDelegate.transformCustomQuery(\n            parsedBody.name,\n            parsedBody.args,\n            ctx,\n          );\n          legacyQuery = false;\n        }\n\n        if (ast === undefined) {\n          throw new Error(\n            'AST is required for analyze-query operation. Either provide an AST directly or ensure custom query transformation is configured.',\n          );\n        }\n\n        let permissions;\n        if (legacyQuery) {\n          using db = new Database(lc, config.replica.file);\n          const dbRunner = new StatementRunner(db);\n          const loaded = loadPermissions(lc, dbRunner, config.app.id, config);\n          if (loaded.permissions) {\n            permissions = loaded.permissions;\n          } else {\n            lc.info?.(\n              'No permissions loaded; analyze-query will run without applying permissions.',\n            );\n          }\n        }\n\n        const result = await analyzeQuery(\n          lc,\n          config,\n          must(cvr.clientSchema),\n          ast,\n          parsedBody.options?.syncedRows,\n          parsedBody.options?.vendedRows,\n          permissions,\n          ctx.auth?.type === 'jwt' ? ctx.auth : undefined,\n          parsedBody.options?.joinPlans,\n        );\n        client.sendInspectResponse(lc, {\n          op: 'analyze-query',\n          id: body.id,\n          value: result,\n        });\n        break;\n      }\n\n      default:\n        unreachable(body);\n    }\n  } catch (e) {\n    lc.warn?.('Error handling inspect message', e);\n    client.sendInspectResponse(lc, {\n      op: 'error',\n      id: body.id,\n      value: (e as Error).message,\n    });\n  }\n}\n\n/**\n * Converts per-query server metrics to the appropriate wire format based on the\n * client's protocol version.\n *\n * Protocol >= 51: new format — `query-hydration-server-ms` (plain number) +\n *   `query-update-server` (TDigest).\n * Protocol < 51: old format — `query-materialization-server` (TDigest) +\n *   `query-update-server` (TDigest). The scalar hydration time is wrapped into a\n *   one-point TDigest for backward compatibility.\n *\n * @visibleForTesting\n */\nexport function metricsForProtocol(\n  metrics: QueryServerMetrics | null,\n  protocolVersion: number,\n): QueryServerMetrics | null {\n  if (protocolVersion >= 51 || metrics === null) {\n    return metrics;\n  }\n  // Backward compat: wrap the scalar hydration ms into a one-point TDigest\n  // under the old field name so that 1.5 clients can parse the response.\n  const hydrateDigest = new TDigest();\n  const hydrateMs = metrics['query-hydration-server-ms'];\n  if (hydrateMs !== undefined) {\n    hydrateDigest.add(hydrateMs);\n  }\n  const legacyMetrics: ServerMetrics = {\n    'query-materialization-server': hydrateDigest.toJSON(),\n    'query-update-server': metrics['query-update-server'],\n  };\n  // Cast to QueryServerMetrics: this is intentional — for old-protocol clients\n  // we send the legacy ServerMetrics wire shape under the QueryServerMetrics type\n  // to satisfy TypeScript while preserving backward compatibility.\n  return legacyMetrics as unknown as QueryServerMetrics;\n}\n"],"mappings":";;;;;;;;;;;;AA4BA,eAAsB,cACpB,IACA,MACA,KACA,QACA,mBACA,eACA,UACA,QACA,KACe;CAGf,IACE,KAAK,OAAO,kBACZ,CAAC,kBAAkB,gBAAgB,aAAa,GAChD;EACA,GAAG,OACD,6FACF;EACA,OAAO,oBAAoB,IAAI;GAC7B,IAAI;GACJ,IAAI,KAAK;GACT,OAAO;EACT,CAAC;EACD;CACF;CAEA,IAAI;EACF,QAAQ,KAAK,IAAb;GACE,KAAK,WAAW;IAQd,MAAM,gBAAe,MAPG,SAAS,eAC/B,IACA,IAAI,UACJ,KAAK,QACP,GAG+B,KAAI,SAAQ;KACzC,GAAG;KACH,KAAK,IAAI,OAAO,kBAAkB,eAAe,IAAI,OAAO,KAAK;KACjE,SAAS,mBACP,kBAAkB,uBAAuB,IAAI,OAAO,GACpD,IAAI,eACN;IACF,EAAE;IAEF,OAAO,oBAAoB,IAAI;KAC7B,IAAI;KACJ,IAAI,KAAK;KACT,OAAO;IACT,CAAC;IACD;GACF;GAEA,KAAK;IACH,OAAO,oBAAoB,IAAI;KAC7B,IAAI;KACJ,IAAI,KAAK;KACT,OAAO,kBAAkB,eAAe;IAC1C,CAAC;IACD;GAGF,KAAK;IACH,OAAO,oBAAoB,IAAI;KAC7B,IAAI;KACJ,IAAI,KAAK;KACT,OAAO,iBAAiB,MAAM;IAChC,CAAC;IACD;GAEF,KAAK,gBAAgB;IACnB,MAAM,WAAW,KAAK;IACtB,MAAM,KAAK,qBAAqB,IAAI,QAAQ,QAAQ;IACpD,IAAI,IACF,kBAAkB,iBAAiB,aAAa;SAEhD,kBAAkB,mBAAmB,aAAa;IAGpD,OAAO,oBAAoB,IAAI;KAC7B,IAAI;KACJ,IAAI,KAAK;KACT,OAAO;IACT,CAAC;IAED;GACF;GAEA,KAAK,iBAAiB;IACpB,MAAM,aAAa,MAAQ,MAAM,2BAA2B;IAC5D,IAAI,MAAM,WAAW,OAAO,WAAW;IACvC,IAAI,cAAc;IAElB,IAAI,WAAW,QAAQ,WAAW,MAAM;KAEtC,MAAM,MAAM,kBAAkB,qBAC5B,WAAW,MACX,WAAW,MACX,GACF;KACA,cAAc;IAChB;IAEA,IAAI,QAAQ,KAAA,GACV,MAAM,IAAI,MACR,kIACF;IAGF,IAAI;IACJ,IAAI,aAAa,IAAA;;KAGf,MAAM,SAAS,gBAAgB,IAAI,IADd,gBAAA,YAAA,EADV,IAAI,SAAS,IAAI,OAAO,QAAQ,IAAI,CACV,CACF,GAAU,OAAO,IAAI,IAAI,MAAM;KAClE,IAAI,OAAO,aACT,cAAc,OAAO;UAErB,GAAG,OACD,6EACF;;;;;;IAIJ,MAAM,SAAS,MAAM,aACnB,IACA,QACA,KAAK,IAAI,YAAY,GACrB,KACA,WAAW,SAAS,YACpB,WAAW,SAAS,YACpB,aACA,IAAI,MAAM,SAAS,QAAQ,IAAI,OAAO,KAAA,GACtC,WAAW,SAAS,SACtB;IACA,OAAO,oBAAoB,IAAI;KAC7B,IAAI;KACJ,IAAI,KAAK;KACT,OAAO;IACT,CAAC;IACD;GACF;GAEA,SACE,YAAY,IAAI;EACpB;CACF,SAAS,GAAG;EACV,GAAG,OAAO,kCAAkC,CAAC;EAC7C,OAAO,oBAAoB,IAAI;GAC7B,IAAI;GACJ,IAAI,KAAK;GACT,OAAQ,EAAY;EACtB,CAAC;CACH;AACF;;;;;;;;;;;;;AAcA,SAAgB,mBACd,SACA,iBAC2B;CAC3B,IAAI,mBAAmB,MAAM,YAAY,MACvC,OAAO;CAIT,MAAM,gBAAgB,IAAI,QAAQ;CAClC,MAAM,YAAY,QAAQ;CAC1B,IAAI,cAAc,KAAA,GAChB,cAAc,IAAI,SAAS;CAS7B,OAAO;EANL,gCAAgC,cAAc,OAAO;EACrD,uBAAuB,QAAQ;CAK1B;AACT"}
+{"version":3,"file":"inspect-handler.js","names":[],"sources":["../../../../../../zero-cache/src/services/view-syncer/inspect-handler.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {unreachable} from '../../../../shared/src/asserts.ts';\nimport {must} from '../../../../shared/src/must.ts';\nimport {TDigest} from '../../../../shared/src/tdigest.ts';\nimport * as v from '../../../../shared/src/valita.ts';\nimport type {AnalyzeQueryResult} from '../../../../zero-protocol/src/analyze-query-result.ts';\nimport {FeatureFlag} from '../../../../zero-protocol/src/feature-flag.ts';\nimport type {\n  QueryServerMetrics,\n  ServerMetrics,\n} from '../../../../zero-protocol/src/inspect-down.ts';\nimport {\n  inspectAnalyzeQueryUpSchema,\n  type UnparsedInspectUpBody,\n} from '../../../../zero-protocol/src/inspect-up.ts';\nimport {Database} from '../../../../zqlite/src/db.ts';\nimport {loadPermissions} from '../../auth/load-permissions.ts';\nimport type {NormalizedZeroConfig} from '../../config/normalize.ts';\nimport {\n  getServerVersion,\n  isAdminPasswordValid,\n} from '../../config/zero-config.ts';\nimport {StatementRunner} from '../../db/statements.ts';\nimport type {InspectorDelegate} from '../../server/inspector-delegate.ts';\nimport {analyzeQuery} from '../analyze.ts';\nimport type {ClientHandler} from './client-handler.ts';\nimport type {ConnectionContext} from './connection-context-manager.ts';\nimport type {CVRStore} from './cvr-store.ts';\nimport type {CVRSnapshot} from './cvr.ts';\n\nexport async function handleInspect(\n  lc: LogContext,\n  body: UnparsedInspectUpBody,\n  cvr: CVRSnapshot,\n  client: ClientHandler,\n  inspectorDelegate: InspectorDelegate,\n  clientGroupID: string,\n  // The service handling the request, on whose behalf authentication is\n  // recorded (see InspectorDelegate.clearAuthenticated).\n  authOwner: object,\n  cvrStore: CVRStore,\n  config: NormalizedZeroConfig,\n  ctx: ConnectionContext,\n): Promise<void> {\n  // Check if the client is already authenticated. We only authenticate the clientGroup\n  // once per \"worker\".\n  if (\n    body.op !== 'authenticate' &&\n    !inspectorDelegate.isAuthenticated(clientGroupID)\n  ) {\n    lc.info?.(\n      'Client not authenticated to access the inspector protocol. Sending authentication challenge',\n    );\n    client.sendInspectResponse(lc, {\n      op: 'authenticated',\n      id: body.id,\n      value: false,\n    });\n    return;\n  }\n\n  try {\n    switch (body.op) {\n      case 'queries': {\n        const queryRows = await cvrStore.inspectQueries(\n          lc,\n          cvr.ttlClock,\n          body.clientID,\n        );\n\n        // Enhance query rows with server-side materialization metrics\n        const enhancedRows = queryRows.map(row => ({\n          ...row,\n          ast: row.ast ?? inspectorDelegate.getASTForQuery(row.queryID) ?? null,\n          metrics: metricsForProtocol(\n            inspectorDelegate.getMetricsJSONForQuery(row.queryID),\n            ctx.protocolVersion,\n          ),\n        }));\n\n        client.sendInspectResponse(lc, {\n          op: 'queries',\n          id: body.id,\n          value: enhancedRows,\n        });\n        break;\n      }\n\n      case 'metrics': {\n        client.sendInspectResponse(lc, {\n          op: 'metrics',\n          id: body.id,\n          value: inspectorDelegate.getMetricsJSON(),\n        });\n        break;\n      }\n\n      case 'version':\n        client.sendInspectResponse(lc, {\n          op: 'version',\n          id: body.id,\n          value: getServerVersion(config),\n        });\n        break;\n\n      case 'authenticate': {\n        const password = body.value;\n        const ok = isAdminPasswordValid(lc, config, password);\n        if (ok) {\n          inspectorDelegate.setAuthenticated(clientGroupID, authOwner);\n        } else {\n          inspectorDelegate.clearAuthenticated(clientGroupID);\n        }\n\n        client.sendInspectResponse(lc, {\n          op: 'authenticated',\n          id: body.id,\n          value: ok,\n        });\n\n        break;\n      }\n\n      case 'analyze-query': {\n        const parsedBody = v.parse(body, inspectAnalyzeQueryUpSchema);\n        let ast = parsedBody.ast ?? parsedBody.value;\n        let legacyQuery = true;\n\n        if (parsedBody.name && parsedBody.args) {\n          // Get the AST from the API server by transforming the named query\n          ast = await inspectorDelegate.transformCustomQuery(\n            parsedBody.name,\n            parsedBody.args,\n            ctx,\n          );\n          legacyQuery = false;\n        }\n\n        if (ast === undefined) {\n          throw new Error(\n            'AST is required for analyze-query operation. Either provide an AST directly or ensure custom query transformation is configured.',\n          );\n        }\n\n        let permissions;\n        if (legacyQuery) {\n          using db = new Database(lc, config.replica.file);\n          const dbRunner = new StatementRunner(db);\n          const loaded = loadPermissions(lc, dbRunner, config.app.id, config);\n          if (loaded.permissions) {\n            permissions = loaded.permissions;\n          } else {\n            lc.info?.(\n              'No permissions loaded; analyze-query will run without applying permissions.',\n            );\n          }\n        }\n\n        const result = await analyzeQuery(\n          lc,\n          config,\n          must(cvr.clientSchema),\n          ast,\n          parsedBody.options?.syncedRows,\n          parsedBody.options?.vendedRows,\n          permissions,\n          ctx.auth?.type === 'jwt' ? ctx.auth : undefined,\n          parsedBody.options?.joinPlans,\n        );\n        client.sendInspectResponse(lc, {\n          op: 'analyze-query',\n          id: body.id,\n          value: ctx.features.has(FeatureFlag.AnalyzeFilterNode)\n            ? result\n            : withoutFilterNodes(result),\n        });\n        break;\n      }\n\n      default:\n        unreachable(body);\n    }\n  } catch (e) {\n    lc.warn?.('Error handling inspect message', e);\n    client.sendInspectResponse(lc, {\n      op: 'error',\n      id: body.id,\n      value: (e as Error).message,\n    });\n  }\n}\n\n/**\n * Removes the planner's `filter` nodes from `joinPlans` for clients that\n * can't parse them: a `filter` node fails an older client's parse of the\n * whole message, which disconnects it.\n *\n * @visibleForTesting\n */\nexport function withoutFilterNodes(\n  result: AnalyzeQueryResult,\n): AnalyzeQueryResult {\n  if (result.joinPlans === undefined) {\n    return result;\n  }\n  return {\n    ...result,\n    joinPlans: result.joinPlans.filter(\n      event => !('nodeType' in event && event.nodeType === 'filter'),\n    ),\n  };\n}\n\n/**\n * Converts per-query server metrics to the appropriate wire format based on the\n * client's protocol version.\n *\n * Protocol >= 51: new format — `query-hydration-server-ms` (plain number) +\n *   `query-update-server` (TDigest).\n * Protocol < 51: old format — `query-materialization-server` (TDigest) +\n *   `query-update-server` (TDigest). The scalar hydration time is wrapped into a\n *   one-point TDigest for backward compatibility.\n *\n * @visibleForTesting\n */\nexport function metricsForProtocol(\n  metrics: QueryServerMetrics | null,\n  protocolVersion: number,\n): QueryServerMetrics | null {\n  if (protocolVersion >= 51 || metrics === null) {\n    return metrics;\n  }\n  // Backward compat: wrap the scalar hydration ms into a one-point TDigest\n  // under the old field name so that 1.5 clients can parse the response.\n  const hydrateDigest = new TDigest();\n  const hydrateMs = metrics['query-hydration-server-ms'];\n  if (hydrateMs !== undefined) {\n    hydrateDigest.add(hydrateMs);\n  }\n  const legacyMetrics: ServerMetrics = {\n    'query-materialization-server': hydrateDigest.toJSON(),\n    'query-update-server': metrics['query-update-server'],\n  };\n  // Cast to QueryServerMetrics: this is intentional — for old-protocol clients\n  // we send the legacy ServerMetrics wire shape under the QueryServerMetrics type\n  // to satisfy TypeScript while preserving backward compatibility.\n  return legacyMetrics as unknown as QueryServerMetrics;\n}\n"],"mappings":"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"}

package/out/zero-cache/src/services/view-syncer/pipeline-driver.d.ts

@@ -1,10 +1,10 @@
 import type { LogContext } from '@rocicorp/logger';
-import type { AST } from '../../../../zero-protocol/src/ast.ts';
+import type { AST, LiteralValue } from '../../../../zero-protocol/src/ast.ts';
 import type { ClientSchema } from '../../../../zero-protocol/src/client-schema.ts';
 import type { Row } from '../../../../zero-protocol/src/data.ts';
-import type { PrimaryKey } from '../../../../zero-protocol/src/primary-key.ts';
 import { ChangeType } from '../../../../zql/src/ivm/change-type.ts';
 import { type Input } from '../../../../zql/src/ivm/operator.ts';
+import type { PlanWarning } from '../../../../zql/src/planner/planner-warnings.ts';
 import type { ClientGroupStorage } from '../../../../zqlite/src/database-storage.ts';
 import { type LoadedPermissions } from '../../auth/load-permissions.ts';
 import type { LogConfig, ZeroConfig } from '../../config/zero-config.ts';
@@ -12,6 +12,9 @@ import type { LiteAndZqlSpec } from '../../db/specs.ts';
 import type { InspectorDelegate } from '../../server/inspector-delegate.ts';
 import { type RowKey } from '../../types/row-key.ts';
 import { type ShardID } from '../../types/shards.ts';
+import type { DeferredWritesBudget } from './deferred-writes-budget.ts';
+import { type QueryShape } from './query-shape.ts';
+import type { QueryStats } from './query-stats.ts';
 import type { Snapshotter } from './snapshotter.ts';
 type RowOp<Op extends Omit<ChangeType, ChangeType.CHILD>> = {
     readonly type: Op;
@@ -24,13 +27,37 @@ export type RowAdd = RowOp<ChangeType.ADD>;
 export type RowRemove = RowOp<ChangeType.REMOVE>;
 export type RowEdit = RowOp<ChangeType.EDIT>;
 export type RowChange = RowAdd | RowRemove | RowEdit;
-type QueryInfo = {
+export type QueryInfo = {
     readonly transformedAst: AST;
+    readonly originalAst?: AST | undefined;
     readonly transformationHash: string;
     readonly queryName?: string | undefined;
 };
+export type HydrationStats = {
+    /** The rows the hydration output. */
+    readonly rowCount: number;
+    /**
+     * The rows the hydration read from the replica, including rows that were
+     * then filtered out, e.g. by a filter that could not be pushed to SQLite or
+     * by an EXISTS that did not match. Much greater than {@link rowCount} means
+     * the query does a lot of work for the rows it returns.
+     */
+    readonly rowsRead: number;
+    /** What the planner warned about the plan it chose for the query. */
+    readonly planWarnings: readonly PlanWarning[];
+    /** The {@link queryShape} of the query, computed when it was hydrated. */
+    readonly shape: QueryShape;
+};
 export type PipelineHydrationReason = 'query-set-sync' | 'unchanged-query-rehydrate';
 type PipelineStopReason = 'replace-query' | 'remove-query' | 'reset' | 'destroy';
+export type AdvancementProgress = {
+    /** Raw ChangeLog entries read, including skipped entries and the current change. */
+    readonly changesScanned: number;
+    /** Yielded source changes whose push processing completed. */
+    readonly changesProcessed: number;
+    /** Raw entries omitted by the snapshot diff. */
+    readonly changesSkipped: number;
+};
 export type Timer = {
     elapsedLap: () => number;
     totalElapsed: () => number;
@@ -40,7 +67,7 @@ export type Timer = {
  */
 export declare class PipelineDriver {
     #private;
-    constructor(lc: LogContext, logConfig: LogConfig, snapshotter: Snapshotter, shardID: ShardID, storage: ClientGroupStorage, clientGroupID: string, inspectorDelegate: InspectorDelegate, yieldThresholdMs: () => number, enablePlanner?: boolean, config?: ZeroConfig);
+    constructor(lc: LogContext, logConfig: LogConfig, snapshotter: Snapshotter, shardID: ShardID, storage: ClientGroupStorage, clientGroupID: string, inspectorDelegate: InspectorDelegate, yieldThresholdMs: () => number, enablePlanner?: boolean, config?: ZeroConfig, deferredWrites?: DeferredWritesBudget, queryStats?: QueryStats | undefined);
     /**
      * Initializes the PipelineDriver to the current head of the database.
      * Queries can then be added (i.e. hydrated) with {@link addQuery()}.
@@ -70,6 +97,18 @@ export declare class PipelineDriver {
      * Returns the current upstream {app}.permissions, or `null` if none are defined.
      */
     currentPermissions(): LoadedPermissions | null;
+    /**
+     * Advances the snapshot to the head of the database without diffing the
+     * change log, in preparation for hydrating queries at head.
+     *
+     * Throws a {@link ResetPipelinesSignal} if the change log records a
+     * schema change since the previous snapshot. The table specs (and any
+     * TableSources built from them) were computed at or before that snapshot
+     * and are stale with respect to the new head, so the caller must
+     * {@link reset()} before hydrating. ({@link advance()} detects this when
+     * the diff encounters the RESET op; this path skips the diff and so must
+     * check explicitly.)
+     */
     advanceWithoutDiff(): string;
     /**
      * Clears storage used for the pipelines. Call this when the
@@ -78,7 +117,23 @@ export declare class PipelineDriver {
     destroy(): void;
     /** @return Map from query ID to PipelineInfo for all added queries. */
     queries(): ReadonlyMap<string, QueryInfo>;
+    /**
+     * Stats from the hydration of the pipeline for `queryID`, or `undefined` if
+     * the query has no pipeline.
+     */
+    hydrationStats(queryID: string): HydrationStats | undefined;
     totalHydrationTimeMs(): number;
+    /**
+     * The rows the sources hold in memory for the advancement in progress.
+     * The advancement's reservation from the {@link DeferredWritesBudget}
+     * bounds this.
+     */
+    get pendingRows(): number;
+    /**
+     * The estimated bytes of {@link pendingRows}, which are added to the
+     * {@link DeferredWritesBudget}'s held bytes as the advancement goes.
+     */
+    get pendingBytes(): number;
     /**
      * Adds a pipeline for the query. The method will hydrate the query using the
      * driver's current snapshot of the database and return a stream of results.
@@ -106,6 +161,16 @@ export declare class PipelineDriver {
      * Maintained incrementally by {@link addQuery} and {@link advance}.
      */
     rowSetSignature(queryID: string): bigint | undefined;
+    /**
+     * IDs of the queries whose {@link rowSetSignature} changed (by an ADD or
+     * REMOVE from {@link addQuery} or {@link advance}) since the last call to
+     * {@link clearChangedRowSetSignatures}.
+     */
+    changedRowSetSignatures(): ReadonlySet<string>;
+    /**
+     * Called once the {@link changedRowSetSignatures} have been persisted.
+     */
+    clearChangedRowSetSignatures(): void;
     /**
      * Returns the value of the row with the given primary key `pk`,
      * or `undefined` if there is no such row. The pipeline must have been
@@ -127,14 +192,23 @@ export declare class PipelineDriver {
         version: string;
         numChanges: number;
         changes: Iterable<RowChange | 'yield'>;
+        /** Available throughout iteration and after completion or an abort. */
+        progress: () => AdvancementProgress;
     };
 }
 /**
  * Core hydration logic used by {@link PipelineDriver#addQuery}, extracted to a
  * function for reuse by the analyze-query RPC path so that analysis hydrates
- * queries the same way the view-syncer does in production.
+ * queries the same way the view-syncer does in production. As there, the rows
+ * of a table outside `clientSchema` are keyed by its key in the replica.
  */
 export declare function hydrate(input: Input, hash: string, clientSchema: ClientSchema, tableSpecs: Map<string, LiteAndZqlSpec>): Iterable<RowChange | 'yield'>;
-export declare function hydrateInternal(input: Input, hash: string, primaryKeys: Map<string, PrimaryKey>, tableSpecs: Map<string, LiteAndZqlSpec>): Iterable<RowChange | 'yield'>;
+/**
+ * Returns the value of `childField` in the row of `input`, the pipeline of a
+ * scalar subquery: `null` if the field is `NULL`, or `undefined` if there is
+ * no row. Used by {@link PipelineDriver#addQuery} and the analyze-query RPC
+ * path to resolve scalar subqueries the same way.
+ */
+export declare function fetchScalarValue(input: Input, childField: string): LiteralValue | null | undefined;
 export {};
 //# sourceMappingURL=pipeline-driver.d.ts.map

package/out/zero-cache/src/services/view-syncer/pipeline-driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline-driver.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/view-syncer/pipeline-driver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAKjD,OAAO,KAAK,EAAC,GAAG,EAAe,MAAM,sCAAsC,CAAC;AAC5E,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,gDAAgD,CAAC;AACjF,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,uCAAuC,CAAC;AAC/D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,8CAA8C,CAAC;AAO7E,OAAO,EAAC,UAAU,EAAC,MAAM,wCAAwC,CAAC;AAGlE,OAAO,EAIL,KAAK,KAAK,EAGX,MAAM,qCAAqC,CAAC;AAY7C,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,4CAA4C,CAAC;AASnF,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAC,SAAS,EAAE,UAAU,EAAC,MAAM,6BAA6B,CAAC;AAEvE,OAAO,KAAK,EAAC,cAAc,EAAgB,MAAM,mBAAmB,CAAC;AAKrE,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAC,KAAK,MAAM,EAAC,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAC,KAAK,OAAO,EAAC,MAAM,uBAAuB,CAAC;AAOnD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,kBAAkB,CAAC;AAGlD,KAAK,KAAK,CAAC,EAAE,SAAS,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI;IAC1D,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AAE3C,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AAEjD,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAE7C,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAqBrD,KAAK,SAAS,GAAG;IACf,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC,CAAC;AAeF,MAAM,MAAM,uBAAuB,GAC/B,gBAAgB,GAChB,2BAA2B,CAAC;AAEhC,KAAK,kBAAkB,GACnB,eAAe,GACf,cAAc,GACd,OAAO,GACP,SAAS,CAAC;AA2Bd,MAAM,MAAM,KAAK,GAAG;IAClB,UAAU,EAAE,MAAM,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,MAAM,CAAC;CAC5B,CAAC;AAuFF;;GAEG;AACH,qBAAa,cAAc;;IA6CzB,YACE,EAAE,EAAE,UAAU,EACd,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,kBAAkB,EAC3B,aAAa,EAAE,MAAM,EACrB,iBAAiB,EAAE,iBAAiB,EACpC,gBAAgB,EAAE,MAAM,MAAM,EAC9B,aAAa,CAAC,EAAE,OAAO,EACvB,MAAM,CAAC,EAAE,UAAU,EAWpB;IAED;;;;;OAKG;IACH,IAAI,CAAC,YAAY,EAAE,YAAY,QAI9B;IAED;;OAEG;IACH,WAAW,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,EAAE,YAAY,QAS/B;IAiCD,mFAAmF;IACnF,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED;;;;OAIG;IACH,cAAc,IAAI,MAAM,CAGvB;IAED;;OAEG;IACH,kBAAkB,IAAI,iBAAiB,GAAG,IAAI,CAiB7C;IAED,kBAAkB,IAAI,MAAM,CAM3B;IAeD;;;OAGG;IACH,OAAO,SAQN;IAED,uEAAuE;IACvE,OAAO,IAAI,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAExC;IAED,oBAAoB,IAAI,MAAM,CAM7B;IAsHD;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CACN,kBAAkB,EAAE,MAAM,EAC1B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,GAAG,EACV,KAAK,EAAE,KAAK,EACZ,SAAS,CAAC,EAAE,MAAM,EAClB,eAAe,GAAE,uBAA0C,GAC1D,QAAQ,CAAC,SAAS,GAAG,OAAO,CAAC,CAW/B;IAiPD;;;OAGG;IACH,WAAW,CACT,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,kBAAmC,QAQhD;IAyBD;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEnD;IAyBD;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAIjD;IAED;;;;;;;;;;OAUG;IACH,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,QAAQ,CAAC,SAAS,GAAG,OAAO,CAAC,CAAC;KACxC,CAmBA;CAiTF;AA2OD;;;;GAIG;AACH,wBAAiB,OAAO,CACtB,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GACtC,QAAQ,CAAC,SAAS,GAAG,OAAO,CAAC,CAO/B;AAED,wBAAiB,eAAe,CAC9B,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACpC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GACtC,QAAQ,CAAC,SAAS,GAAG,OAAO,CAAC,CAQ/B"}
+{"version":3,"file":"pipeline-driver.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/view-syncer/pipeline-driver.ts"],"names":[],"mappings":"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"}