@supalive/core 1.20.1 → 1.21.0

package/dist/one-shot-query-BSK7adwG.js

@@ -0,0 +1,573 @@
+import { c as parentConn } from "./router-DP2ThAwh.js";
+import { n as stableStringify } from "./helper-zdJT5FUc.js";
+import { s as traceCacheCall } from "./query-LJranz0c.js";
+import { t as EMPTY_EPHEMERAL_KEYS } from "./ephemeral-CkidSG9y.js";
+import { r as evaluateCacheFreshness } from "./overlap-checker-DseE1Lvh.js";
+import { i as logger, l as DbWriter } from "./logger-BJNCJkFh.js";
+import { ROOT_CONTEXT, SpanKind, SpanStatusCode, context, isSpanContextValid, metrics, propagation, trace } from "@opentelemetry/api";
+import { sha1 } from "hash-wasm";
+//#region src/server/sub_hash.ts
+/** Compute stable hash using json-stable-stringify and SHA1. */
+async function getHashOf(input) {
+	return sha1((typeof input === "string" ? input : stableStringify(input)) ?? "");
+}
+/**
+* Default identity literal used when neither a procedure-level
+* `queryIdentity` override nor a per-session user is available.
+*/
+const ANONYMOUS_IDENTITY = "anonymous";
+/**
+* Resolve the segmentation key that participates in the subId/cacheKey hash for
+* a query. Shared by every query transport (WS subscribe, WS one-shot call, and
+* HTTP RPC) so identity — and therefore cache segmentation — is computed
+* identically regardless of how the query is invoked. Priority:
+*
+*   1. Procedure-level `queryIdentity` override:
+*        - `false`    → `ANONYMOUS_IDENTITY` (cache shared across users)
+*        - `string`   → that literal
+*        - `function` → serverCtx + input → string | null | undefined
+*   2. `getUserId(serverCtx)` → falls back to `ANONYMOUS_IDENTITY` when it
+*      returns null/undefined or isn't configured.
+*/
+function resolveQueryIdentity(procedure, serverCtx, input, getUserId) {
+	const override = procedure.queryIdentity;
+	if (override !== void 0) {
+		if (override === false) return ANONYMOUS_IDENTITY;
+		if (typeof override === "string") return override;
+		if (typeof override === "function") {
+			const value = override(serverCtx, input);
+			if (value === null || value === void 0) return ANONYMOUS_IDENTITY;
+			return value;
+		}
+	}
+	if (!getUserId) return ANONYMOUS_IDENTITY;
+	return getUserId(serverCtx) ?? "anonymous";
+}
+/**
+* Compute a subscription id from hash of procedure + input + queryIdentity.
+*
+* `queryIdentity` is the segmentation key for cache/subscriptions. By default
+* it is the authenticated user's id (so two users get distinct subscriptions
+* for the same query), but a procedure may override it to share cache/subs
+* across users (e.g. for a public, user-independent query).
+*/
+async function generateSubscriptionId(procedure, input, queryIdentity) {
+	return `sub_${await getHashOf(`${procedure}_${typeof input === "string" ? input : stableStringify(input)}_${queryIdentity}`)}`;
+}
+/**
+* Compute cache key from query name + args + queryIdentity. The identity
+* participates so that user-specific results don't poison each other's
+* cache when a procedure does authorize per-user.
+*/
+async function generateCacheKey(queryName, input, queryIdentity) {
+	return `ck_${await getHashOf(`${queryName}_${typeof input === "string" ? input : stableStringify(input)}_${queryIdentity}`)}`;
+}
+//#endregion
+//#region src/observability.ts
+let rootLogger = logger;
+/** Replace the process-wide root logger. Call once at startup, before creating
+* the server, to route Supalive's request/lifecycle logs through your own pino
+* instance. */
+function configureRootLogger(logger) {
+	rootLogger = logger;
+}
+/** The current root logger (defaults to the env-configured singleton). */
+function getRootLogger() {
+	return rootLogger;
+}
+const CLIENT_ERROR_CODES = /* @__PURE__ */ new Set([
+	"NOT_FOUND",
+	"BAD_REQUEST",
+	"INVALID_MESSAGE",
+	"PARSE_ERROR",
+	"UNAUTHENTICATED",
+	"RATE_LIMITED",
+	"METHOD_NOT_ALLOWED",
+	"TOO_MANY_CONCURRENT_MUTATIONS",
+	"TOO_MANY_CONCURRENT_ACTIONS",
+	"SUBSCRIBE_ERROR"
+]);
+/**
+* The bound observability surface for one server instance: an injectable logger,
+* OTel metric instruments, and the `record()` seam every operation funnels
+* through. Built once in the server constructor and shared with the HTTP RPC
+* handler.
+*/
+var Observability = class {
+	logger;
+	requestLog;
+	onEvent;
+	requestCounter;
+	durationHistogram;
+	activeConnections;
+	activeSubscriptions;
+	tracer;
+	constructor(opts = {}) {
+		const base = opts.logger ?? getRootLogger();
+		this.logger = opts.level ? base.child({}, { level: opts.level }) : base;
+		this.requestLog = opts.requestLog ?? "all";
+		this.onEvent = opts.onEvent;
+		const meterName = opts.meterName ?? "@supalive/core";
+		const meter = metrics.getMeter(meterName, opts.meterVersion);
+		this.tracer = trace.getTracer(meterName, opts.meterVersion);
+		this.requestCounter = meter.createCounter("supalive_requests_total", { description: "Total Supalive operations (WS calls, subscribes, HTTP RPC, jobs)." });
+		this.durationHistogram = meter.createHistogram("supalive_request_duration_ms", {
+			description: "Operation duration in milliseconds.",
+			unit: "ms"
+		});
+		this.activeConnections = meter.createUpDownCounter("supalive_active_connections", { description: "Currently open WebSocket connections." });
+		this.activeSubscriptions = meter.createUpDownCounter("supalive_active_subscriptions", { description: "Currently registered live-query subscriptions on this instance." });
+	}
+	/** Record one completed operation: metrics + optional onEvent + one log line,
+	*  and finalize the op's span (status/attributes/exception) when present. */
+	record(e) {
+		const traceId = this.finalizeSpan(e);
+		if (traceId) (e.extra ??= {}).traceId = traceId;
+		const attrs = {
+			transport: e.transport,
+			procedure: e.procedure ?? "",
+			kind: e.kind ?? "",
+			outcome: e.outcome,
+			code: e.code ?? ""
+		};
+		this.requestCounter.add(1, attrs);
+		this.durationHistogram.record(e.durationMs, attrs);
+		if (this.onEvent) try {
+			this.onEvent(e);
+		} catch {}
+		if (this.requestLog === "off") return;
+		if (e.outcome === "ok") {
+			if (this.requestLog !== "all") return;
+			this.logger.info(logFields(e), summary(e));
+			return;
+		}
+		const fields = logFields(e);
+		if (!e.error && e.code != null && CLIENT_ERROR_CODES.has(e.code)) this.logger.warn(fields, summary(e));
+		else this.logger.error({
+			...fields,
+			err: e.error
+		}, summary(e));
+	}
+	/**
+	* Start a SERVER span for an operation, as a child of `parent` (or the active
+	* context). No-op — returns a non-recording span — until a TracerProvider is
+	* registered by the app, so this costs nothing when tracing is disabled.
+	* Returns the span plus a context that has it active, for `context.with(...)`
+	* wrapping so nested handler work / `ctx.span` children attach correctly.
+	*/
+	startSpan(name, opts = {}) {
+		const parent = opts.parent ?? context.active();
+		const span = this.tracer.startSpan(name, {
+			kind: SpanKind.SERVER,
+			attributes: {
+				...opts.transport ? { "supalive.transport": opts.transport } : {},
+				...opts.procedure ? { "supalive.procedure": opts.procedure } : {},
+				...opts.kind ? { "supalive.kind": opts.kind } : {}
+			}
+		}, parent);
+		return {
+			span,
+			context: trace.setSpan(parent, span)
+		};
+	}
+	/**
+	* Continue a trace from an inbound carrier (HTTP headers, or a WS message's
+	* `trace` field). Returns a context to pass as `startSpan({ parent })`. When
+	* no propagator is registered / no trace context is present, returns the root
+	* context (a fresh trace).
+	*/
+	extractContext(carrier) {
+		return propagation.extract(ROOT_CONTEXT, carrier);
+	}
+	/** Set the span's final status/attributes from the event, then end it.
+	*  Returns the (valid) trace id for log correlation, or undefined. */
+	finalizeSpan(e) {
+		const span = e.span;
+		if (!span) return void 0;
+		try {
+			span.setAttribute("supalive.outcome", e.outcome);
+			if (e.code) span.setAttribute("supalive.code", e.code);
+			if (e.procedure) span.setAttribute("supalive.procedure", e.procedure);
+			if (e.kind) span.setAttribute("supalive.kind", e.kind);
+			if (e.outcome === "error") {
+				if (e.error instanceof Error) span.recordException(e.error);
+				span.setStatus({
+					code: SpanStatusCode.ERROR,
+					message: e.code
+				});
+			} else span.setStatus({ code: SpanStatusCode.OK });
+		} finally {
+			span.end();
+		}
+		const sc = span.spanContext();
+		return isSpanContextValid(sc) ? sc.traceId : void 0;
+	}
+	/** A request-scoped child logger for `ctx.log`, bound with the given fields
+	*  (reqId, procedure, and trace id when tracing is on). */
+	childLogger(fields) {
+		return this.logger.child(fields);
+	}
+	/**
+	* A LAZY request-scoped `ctx.log`. Most handlers never log, and pino's
+	* `.child()` (bindings merge + serialization) isn't free — so this defers the
+	* child creation until the first `debug/info/warn/error` call and reuses it
+	* after. When a handler logs nothing, no child logger is ever allocated; the
+	* only per-request cost is this small delegator object. Returns the narrow
+	* {@link HandlerLogger} surface the handler context exposes.
+	*/
+	lazyChildLogger(fields) {
+		const base = this.logger;
+		let child;
+		const get = () => child ??= base.child(fields);
+		return {
+			debug: (...args) => get().debug(...args),
+			info: (...args) => get().info(...args),
+			warn: (...args) => get().warn(...args),
+			error: (...args) => get().error(...args)
+		};
+	}
+	/** The span's trace id, or undefined when tracing is off / the span is
+	*  non-recording. For binding onto `ctx.log`. */
+	traceIdOf(span) {
+		if (!span) return void 0;
+		const sc = span.spanContext();
+		return isSpanContextValid(sc) ? sc.traceId : void 0;
+	}
+	connectionOpened() {
+		this.activeConnections.add(1);
+	}
+	connectionClosed() {
+		this.activeConnections.add(-1);
+	}
+	subscriptionAdded(n = 1) {
+		this.activeSubscriptions.add(n);
+	}
+	subscriptionRemoved(n = 1) {
+		this.activeSubscriptions.add(-n);
+	}
+};
+/** Start marker for an operation; pass to {@link elapsedMs} to get its duration. */
+function startTimer() {
+	return performance.now();
+}
+function elapsedMs(startedAt) {
+	return Math.round((performance.now() - startedAt) * 1e3) / 1e3;
+}
+const coreTracer = trace.getTracer("@supalive/core");
+/**
+* Run a query handler inside a `query <procedureName>` span, nested under
+* `parentContext` (the operation span) or the active context. The span is handed
+* to `run` so it becomes the query handler's `ctx.span` and the parent of any DB
+* spans. Cache HITs never call this (no execution), so a span appearing means a
+* real recompute — including the otherwise-invisible background reactive path,
+* where `parentContext` is omitted and the span is a root.
+*
+* No-op-cheap when tracing is off: the started span is non-recording, so we skip
+* the `context.with` and just run.
+*/
+function traceQueryExecution(procedureName, trigger, parentContext, run) {
+	const parent = parentContext ?? context.active();
+	const span = coreTracer.startSpan(`query ${procedureName}`, { attributes: {
+		"supalive.kind": "query",
+		"supalive.procedure": procedureName,
+		"supalive.trigger": trigger
+	} }, parent);
+	const exec = async () => {
+		try {
+			const r = await run(span);
+			span.setStatus({ code: SpanStatusCode.OK });
+			return r;
+		} catch (err) {
+			if (err instanceof Error) span.recordException(err);
+			span.setStatus({ code: SpanStatusCode.ERROR });
+			throw err;
+		} finally {
+			span.end();
+		}
+	};
+	return span.isRecording() ? context.with(trace.setSpan(parent, span), exec) : exec();
+}
+function logFields(e) {
+	const f = {
+		op: e.op,
+		transport: e.transport,
+		outcome: e.outcome,
+		durMs: e.durationMs
+	};
+	if (e.procedure) f.procedure = e.procedure;
+	if (e.kind) f.kind = e.kind;
+	if (e.code) f.code = e.code;
+	if (e.reqId) f.reqId = e.reqId;
+	if (e.sessionId) f.sessionId = e.sessionId;
+	if (e.userId != null) f.userId = e.userId;
+	if (e.extra) Object.assign(f, e.extra);
+	return f;
+}
+function summary(e) {
+	const label = e.procedure ? `${e.kind ?? e.op} ${e.procedure}` : e.op;
+	return `${e.transport} ${label} ${e.outcome}`;
+}
+//#endregion
+//#region src/db/read-routing.ts
+/**
+* Decide which connection a read should run on, by commit_ts high-water — the
+* single routing rule used by both the one-shot query path and the internal
+* caller.
+*
+* `minTs` is the reader's floor: the largest commit/snapshot ts it has already
+* observed and must not read behind (read-your-writes + monotonic reads). It is
+* clamped to `primaryTs` here, so a bogus/oversized value can at most force the
+* primary — never an error, never a value beyond what the primary has. A read
+* may use the replica ONLY when the replica has applied at least this floor
+* (`replicaTs >= minTs`); otherwise the replica is lagging past what the caller
+* has seen and the read stays on the primary.
+*
+* `primaryTs` is passed in (rather than loaded here) so it stays consistent with
+* whatever snapshot the caller already loaded at its seam — e.g. the one-shot
+* path uses it as the cache-freshness upper bound. The replica's ts is loaded
+* here, and only when a replica is actually configured (no wasted round trip on
+* primary-only deployments).
+*/
+async function resolveReadRouting(db, primaryLastSnapshotTs, minTs) {
+	const primaryImpl = db.impl;
+	minTs = minTs == 0n ? primaryLastSnapshotTs : minTs;
+	const floor = minTs > primaryLastSnapshotTs ? primaryLastSnapshotTs : minTs;
+	const replicaDb = db.replica;
+	const replicaImpl = replicaDb ? replicaDb.impl : primaryImpl;
+	const replicaTs = replicaDb ? await replicaImpl.getLatestSnapshotTimestamp() : primaryLastSnapshotTs;
+	const useReplica = replicaDb !== void 0 && replicaTs >= floor;
+	return {
+		primaryImpl,
+		primaryTs: primaryLastSnapshotTs,
+		replicaImpl,
+		replicaTs,
+		readImpl: useReplica ? replicaImpl : primaryImpl,
+		readTs: useReplica ? replicaTs : primaryLastSnapshotTs,
+		useReplica
+	};
+}
+/**
+* Build the per-handler `ctx.usePrimaryConn()` / `ctx.useReplicaConn()` methods
+* for a query, bound to a routing decision. Shared so the override semantics are
+* identical everywhere:
+*
+*   • `usePrimaryConn()` — force the primary (always safe).
+*   • `useReplicaConn({ readOwnWrite: true })` — force the primary (read-your-writes).
+*   • `useReplicaConn()` — the SAME caught-up gate as the default: the replica
+*     when it has applied the caller's floor, else the primary. It never binds a
+*     replica that is lagging past `minTs`, so opting in can't serve stale reads.
+*
+* Must be called before the handler's first read (`useConnection` throws
+* otherwise) — that's the contract the ctx methods expose to handlers.
+*/
+function makeConnRouting(reader, routing) {
+	return {
+		usePrimaryConn: (_opts) => reader.useConnection(routing.primaryImpl, routing.primaryTs),
+		useReplicaConn: (opts) => reader.useConnection(opts?.readOwnWrite ? routing.primaryImpl : routing.readImpl, opts?.readOwnWrite ? routing.primaryTs : routing.readTs)
+	};
+}
+//#endregion
+//#region src/server/one-shot-query.ts
+/**
+* Parent context for the `query <name>` span. IMPLICIT linking is the primary
+* mechanism: the caller's handler already runs inside `otelContext.with(
+* started.context, ...)`, so the active span IS the correct parent — return
+* `undefined` and let {@link traceQueryExecution} default to the ambient
+* context. The EXPLICIT fallback (the span carried on the caller's handlerObs,
+* i.e. the parent handler's `ctx.span`) is used only when the ambient context
+* is root — e.g. a detached/fire-and-forget internal call.
+*/
+function parentContextFor(handlerObs) {
+	if (trace.getSpan(context.active())) return void 0;
+	return handlerObs.span ? trace.setSpan(context.active(), handlerObs.span) : void 0;
+}
+/**
+* Execute a one-shot query (WS `call` or HTTP RPC) with the same caching model
+* as a live subscription — but without registering a tracked subscription.
+*
+* Flow (mirrors `handleSubscribe` / worker `register`):
+*   1. Resolve `queryIdentity` → `cacheKey` (identical segmentation to subs).
+*   2. Pick the read connection ONCE (replica when it's caught up to the client's
+*      `clientMinTs`, else primary) and use it for BOTH the freshness scan and
+*      the row reads, so a cache HIT offloads the primary too — not just a miss.
+*   3. Freshness check via {@link evaluateCacheFreshness} on that connection:
+*      cached metadata + the retention watermark + a between-ts commit-log scan.
+*   4. Fresh  → return the cached data.
+*      Stale/miss → recompute via `queryInternalOn` (on the chosen connection)
+*      and write BOTH the data and the metadata (readSet + snapshotTs) back, so
+*      a later one-shot or a fresh subscription can reuse it.
+*
+* The retention guard is what makes an untracked one-shot safe: nothing holds
+* the prune watermark down for it, so an entry whose snapshot has fallen below
+* the oldest retained commit log is treated as a miss (its freshness scan would
+* be incomplete).
+*
+* `lastSnapshotTs` is the primary freshness upper bound — the latest snapshot ts
+* as of this call. The caller loads it (via `db.getLatestSnapshotTimestamp()`)
+* and passes it in, exactly like the subscribe path loads it before `register`,
+* so the snapshot read lives at the caller seam rather than being hidden here.
+*
+* `clientMinTs` is the caller's read high-water (the largest commit/snapshot ts
+* it has already observed). It gates replica routing: a query only runs on the
+* replica when the replica has applied at least `clientMinTs` — otherwise reads
+* (and the freshness scan) stay on the primary, preserving read-your-writes and
+* monotonic reads. It is clamped to `lastSnapshotTs` here, so a client can at
+* most force the primary (never a value beyond it). Returns the data plus the
+* `ts` the result reflects, which the caller echoes so the client can advance
+* its high-water.
+*/
+async function runCachedQuery(deps, handlerObs, procedure, procedureName, input, serverCtx, lastSnapshotTs, clientMinTs) {
+	const queryIdentity = resolveQueryIdentity(procedure, serverCtx, input, deps.getUserId);
+	const cacheKey = await generateCacheKey(procedureName, stableStringify(input), queryIdentity);
+	const routing = await resolveReadRouting(deps.db, lastSnapshotTs, clientMinTs ?? 0n);
+	const readTs = routing.readTs;
+	const { metadata, freshness } = await traceCacheCall("freshness", async () => {
+		const metadata = await deps.cache.getQueryCacheMetaData(cacheKey);
+		return {
+			metadata,
+			freshness: await evaluateCacheFreshness(routing.readImpl, metadata, readTs, deps.getMinRetainedTs())
+		};
+	});
+	if (freshness.fresh) {
+		const cached = await traceCacheCall("get", async (setHit) => {
+			const c = await deps.cache.getQueryCacheFor(cacheKey);
+			setHit(!!(c && metadata && c.version === metadata.version));
+			return c;
+		});
+		if (cached && metadata && cached.version === metadata.version) {
+			if (readTs > metadata.lastSnapshotTs) deps.cache.advanceQueryCacheMetadata(cacheKey, {
+				lastSnapshotTs: readTs,
+				version: metadata.version,
+				readSet: metadata.readSet,
+				ephemeralKeys: metadata.ephemeralKeys
+			}).catch((err) => logger.error(err, "one-shot horizon advance failed"));
+			const servedTs = readTs > metadata.lastSnapshotTs ? readTs : metadata.lastSnapshotTs;
+			return {
+				data: cached.data,
+				ts: servedTs,
+				readSet: metadata.readSet
+			};
+		}
+	}
+	const result = await deps.db.queryInternalOn({
+		impl: routing.readImpl,
+		beginTs: readTs
+	}, async (ctx) => {
+		const fn = procedure.fn;
+		return traceQueryExecution(procedureName, "request", parentContextFor(handlerObs), (querySpan) => {
+			const qctx = {
+				db: ctx,
+				serverCtx,
+				...makeConnRouting(ctx, routing),
+				log: handlerObs.log,
+				span: querySpan
+			};
+			return fn(qctx, input);
+		});
+	});
+	await deps.cache.setQueryCacheAndMetadataFor(cacheKey, result.data, {
+		lastSnapshotTs: result.ts,
+		version: result.ts.toString(),
+		readSet: result.readSet,
+		ephemeralKeys: result.ephemeralKeys
+	}).catch((err) => logger.error(err, "one-shot query cache write failed"));
+	return {
+		data: result.data,
+		ts: result.ts,
+		readSet: result.readSet
+	};
+}
+/**
+* Cache-first evaluation of a nested query JOINED to a parent transaction — the
+* path behind `caller.<proc>.runQuery` when invoked from a query or mutation
+* handler (`parent` is the parent's live {@link DbReader}/{@link DbWriter}).
+*
+* The nested query shares the parent's SNAPSHOT + readSet: it reads on the
+* parent's own bound connection (`parent.db`) at the parent's `beginTs`, so the
+* freshness scan and any replica/primary connection the parent was routed to
+* stay consistent — a rebind can never mix snapshots. Reads made on a cache
+* MISS accumulate straight into the parent's readSet (making the parent re-run /
+* OCC-conflict on concurrent changes to what the nested query observed), and on
+* a HIT the cached entry's readSet is appended to the parent instead, so the
+* parent's subscription invalidation / OCC fencing still covers the rows the
+* nested query depends on.
+*
+* Mutation parents need two guards that query parents don't:
+*   1. **Pending writes** (the mutation has already written in this tx) — the
+*      cache is bypassed entirely: the nested query must see the parent's
+*      uncommitted writes (reads-your-writes), which the committed cache can't
+*      reflect, and caching that state would leak uncommitted data to other
+*      readers.
+*   2. **No write-back** — a `DbWriter`'s `beginTs` is `latest + 1` (a phantom,
+*      not a real committed ts), so a write-back would stamp a horizon no reader
+*      can ever reach and (worse) invert the freshness scan window. Rather than
+*      clamp it, mutation parents simply never write back: nothing rebuilds a
+*      nested read after the parent commits (unlike a tracked subscription), and
+*      the mutation's own commit usually invalidates the entry anyway. They only
+*      CONSUME cache hits written by query parents / one-shots — the cached
+*      entry's readSet is folded into the parent so OCC fencing still holds, and
+*      the horizon is never advanced for the same phantom-ts reason.
+*/
+async function runCachedQueryInParent(deps, handlerObs, procedure, procedureName, input, serverCtx, parent) {
+	const isMutationParent = parent instanceof DbWriter;
+	const cache = isMutationParent && parent.internalGetWriteSet().length > 0 ? void 0 : deps.cache;
+	const readImpl = parent.db;
+	const readTs = parent.beginTs;
+	const runOnParent = () => traceQueryExecution(procedureName, "request", parentContextFor(handlerObs), (querySpan) => {
+		const qctx = {
+			db: parent,
+			serverCtx,
+			...parentConn,
+			log: handlerObs.log,
+			span: querySpan
+		};
+		const fn = procedure.fn;
+		return fn(qctx, input);
+	});
+	const cacheKey = cache ? await generateCacheKey(procedureName, stableStringify(input), resolveQueryIdentity(procedure, serverCtx, input, deps.getUserId)) : void 0;
+	if (cache && cacheKey) {
+		const { metadata, freshness } = await traceCacheCall("freshness", async () => {
+			const metadata = await cache.getQueryCacheMetaData(cacheKey);
+			return {
+				metadata,
+				freshness: await evaluateCacheFreshness(readImpl, metadata, readTs, deps.getMinRetainedTs())
+			};
+		});
+		if (freshness.fresh) {
+			const cached = await traceCacheCall("get", async (setHit) => {
+				const c = await cache.getQueryCacheFor(cacheKey);
+				setHit(!!(c && metadata && c.version === metadata.version));
+				return c;
+			});
+			if (cached && metadata && cached.version === metadata.version) {
+				parent.appendInternalReadSet(metadata.readSet);
+				parent.appendInternalEphemeralKeys(metadata.ephemeralKeys);
+				if (!isMutationParent && readTs > metadata.lastSnapshotTs) cache.advanceQueryCacheMetadata(cacheKey, {
+					lastSnapshotTs: readTs,
+					version: metadata.version,
+					readSet: metadata.readSet,
+					ephemeralKeys: metadata.ephemeralKeys
+				}).catch((err) => logger.error(err, "nested query horizon advance failed"));
+				return cached.data;
+			}
+		}
+	}
+	const beforeLen = parent.internalGetReadSet().length;
+	const beforeEphemeralLen = parent.internalGetEphemeralKeys()?.length ?? 0;
+	const data = await runOnParent();
+	if (!isMutationParent && cache && cacheKey) {
+		const nestedReadSet = parent.internalGetReadSet().slice(beforeLen);
+		const nestedEphemeralKeys = parent.internalGetEphemeralKeys()?.slice(beforeEphemeralLen) ?? EMPTY_EPHEMERAL_KEYS;
+		await cache.setQueryCacheAndMetadataFor(cacheKey, data, {
+			lastSnapshotTs: parent.beginTs,
+			version: parent.beginTs.toString(),
+			readSet: nestedReadSet,
+			ephemeralKeys: nestedEphemeralKeys
+		}).catch((err) => logger.error(err, "nested query cache write failed"));
+	}
+	return data;
+}
+//#endregion
+export { elapsedMs as a, traceQueryExecution as c, generateSubscriptionId as d, getHashOf as f, configureRootLogger as i, ANONYMOUS_IDENTITY as l, runCachedQueryInParent as n, getRootLogger as o, resolveQueryIdentity as p, Observability as r, startTimer as s, runCachedQuery as t, generateCacheKey as u };
+
+//# sourceMappingURL=one-shot-query-BSK7adwG.js.map