@prisma/orm-family-sql 8.0.0-rc.18-dev.17 → 8.0.0-rc.18-dev.19

package/dist/orm-client.mjs

@@ -8,13 +8,16 @@ import { n as codecRefForStorageColumn } from "./codec-descriptor-registry-4kw8F
 import { t as createFunctions } from "./functions-0YWByawj.mjs";
 import { t as createIndexReferences } from "./index-reference-DR62gjQS.mjs";
 import { o as settlementOf } from "./transaction-state-BfXhs7D7-3k10jZ8I.mjs";
+import { p as findActivitySource } from "./exports-DVsHk8HP-DrH_2a-H.mjs";
 import { structuredError } from "@prisma/orm-framework/utils/structured-error";
 import { ifDefined } from "@prisma/orm-framework/utils/defined";
 import { blindCast, castAs } from "@prisma/orm-framework/utils/casts";
 import { InternalError, isInternalError } from "@prisma/orm-framework/utils/internal-error";
 import { domainModelsAtDefaultNamespace } from "@prisma/orm-framework/contract/types";
+import { canonicalStringify } from "@prisma/orm-framework/utils/canonical-stringify";
 import { AsyncIterableResult, createMetaBuilder, isRuntimeError, runtimeError } from "@prisma/orm-framework/components/runtime";
 import { assertDefined, invariant } from "@prisma/orm-framework/utils/assertions";
+import { hashContent } from "@prisma/orm-framework/utils/hash-content";
 //#region ../../../3-extensions/sql-orm-client/dist/index.mjs
 const operationNamesByRegistry = /* @__PURE__ */ new WeakMap();
 /**
@@ -954,54 +957,20 @@ function checkedOrderByItem(dir, expr, options) {
 function deriveParamsFromAst(ast) {
 	return { params: collectOrderedParamRefs(ast).map((p) => p.kind === "param-ref" ? p.value : void 0) };
 }
-function buildOrmPlanMeta(contract, annotations) {
-	const annotationRecord = annotations !== void 0 && annotations.size > 0 ? Object.freeze(Object.fromEntries(annotations)) : void 0;
+function buildOrmPlanMeta(contract) {
 	return {
 		target: contract.target,
 		targetFamily: contract.targetFamily,
 		storageHash: contract.storage.storageHash,
 		...ifDefined("profileHash", contract.profileHash),
-		...ifDefined("annotations", annotationRecord),
 		lane: "orm-client"
 	};
 }
-function buildOrmQueryPlan(contract, ast, params, annotations) {
+function buildOrmQueryPlan(contract, ast, params) {
 	return Object.freeze({
 		ast,
 		params: [...params],
-		meta: buildOrmPlanMeta(contract, annotations)
-	});
-}
-/**
-* Merges annotations into an existing `SqlQueryPlan`'s
-* `meta.annotations` and returns a new frozen plan.
-*
-* Used by the ORM dispatch path to attach terminal-call annotations to
-* plans produced by mutation compile functions (which don't take
-* annotations as parameters). Reads compile through `compileSelect`-
-* family functions that pass `state.annotations` directly to
-* `buildOrmQueryPlan`; this helper is the alternate path for write
-* terminals where annotations arrive at the call site, not via state.
-*
-* Returns the input plan unchanged when `annotations` is undefined
-* or empty. Reserved namespaces already on the input plan (`codecs`, target keys such as `pg`)
-* win over caller-supplied entries under the same key —
-* see the reserved-namespace policy on `defineAnnotation`.
-*/
-function mergeAnnotations(plan, annotations) {
-	if (annotations === void 0 || annotations.size === 0) return plan;
-	const callerEntries = {};
-	for (const [namespace, value] of annotations) callerEntries[namespace] = value;
-	const mergedAnnotations = Object.freeze({
-		...callerEntries,
-		...plan.meta.annotations ?? {}
-	});
-	return Object.freeze({
-		...plan,
-		meta: Object.freeze({
-			...plan.meta,
-			annotations: mergedAnnotations
-		})
+		meta: buildOrmPlanMeta(contract)
 	});
 }
 function bindWhereExpr(contract, expr, aliases) {
@@ -1349,8 +1318,7 @@ function emptyState(tables) {
 		limit: void 0,
 		offset: void 0,
 		variantValue: void 0,
-		locking: void 0,
-		annotations: /* @__PURE__ */ new Map()
+		locking: void 0
 	};
 }
 function emptyGroupPagingState() {
@@ -2370,7 +2338,7 @@ function collectionSelectAst(contract, modelName, state) {
 function compileSelect(contract, modelName, state) {
 	const ast = collectionSelectAst(contract, modelName, state);
 	const { params } = deriveParamsFromAst(ast);
-	return buildOrmQueryPlan(contract, ast, params, state.annotations);
+	return buildOrmQueryPlan(contract, ast, params);
 }
 function collectionSelectWithIncludesAst(contract, aggregates, modelName, state) {
 	assertLockCompatible(state);
@@ -2395,7 +2363,7 @@ function collectionSelectWithIncludesAst(contract, aggregates, modelName, state)
 function compileSelectWithIncludes(contract, aggregates, modelName, state) {
 	const ast = collectionSelectWithIncludesAst(contract, aggregates, modelName, state);
 	const { params } = deriveParamsFromAst(ast);
-	return buildOrmQueryPlan(contract, ast, params, state.annotations);
+	return buildOrmQueryPlan(contract, ast, params);
 }
 function queryPlanRows(scope, plan) {
 	return scope.query(plan);
@@ -2572,24 +2540,37 @@ function describeCollectionFirstOrThrow(options) {
 		consume: (source) => rows.consume(source).firstOrThrow()
 	};
 }
-function dispatchCollectionRows(options) {
-	const { context, runtime, state, modelName, namespaceId } = options;
-	const descriptionOptions = {
-		context,
-		state,
-		modelName,
-		namespaceId
-	};
+function describeCollectionQuery(options) {
+	const { context, state, modelName, namespaceId } = options;
 	if (state.includes.length === 0) {
-		const query = describeExecutionRows(descriptionOptions);
-		return query.consume(queryPlanRows(runtime, query.plan));
+		const query = describeExecutionRows(options);
+		return {
+			plan: () => query.plan,
+			rows: (scope) => runQuery(scope, query)
+		};
 	}
 	resolvePolymorphismInfo(context.contract, namespaceId, modelName);
-	const generator = async function* () {
-		const query = describeExecutionRows(descriptionOptions);
-		yield* query.consume(queryPlanRows(runtime, query.plan));
+	let compiled;
+	const query = () => {
+		compiled ??= describeExecutionRows(options);
+		return compiled;
+	};
+	return {
+		plan: () => query().plan,
+		rows: (scope) => {
+			const generator = async function* () {
+				yield* runQuery(scope, query());
+			};
+			return new AsyncIterableResult(generator());
+		}
 	};
-	return new AsyncIterableResult(generator());
+}
+function runQuery(scope, query) {
+	return query.consume(queryPlanRows(scope, query.plan));
+}
+function dispatchCollectionRows(options) {
+	const { runtime, ...descriptionOptions } = options;
+	return describeCollectionQuery(descriptionOptions).rows(runtime);
 }
 function consumeIncludeRows(context, state, namespaceId, modelName, rows) {
 	const { contract } = context;
@@ -3805,6 +3786,313 @@ function buildJoinWhere(contract, parentNamespaceId, parentModelName, parentTabl
 	if (joinExprs.length === 1 && firstExpr !== void 0) return firstExpr;
 	return and(...joinExprs);
 }
+/** The hash input of a read is the content hash of the plan it sends first. */
+function planHashInput(plan) {
+	return (source) => source.planContentHash(plan());
+}
+/** The hash input of a prepared read is the content hash of the statement with the parameters this execution binds. */
+function preparedHashInput(statement, params) {
+	return (source) => source.planContentHash({
+		statement,
+		params
+	});
+}
+/** A write's statements depend on earlier results, so its hash input is the model it writes. */
+function modelHashInput(namespaceId, modelName) {
+	return async () => ({
+		namespace: namespaceId,
+		model: modelName
+	});
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const ormResults = {
+	rows: (value) => Array.isArray(value),
+	row: (value) => isRecord(value),
+	rowOrNull: (value) => value === null || isRecord(value),
+	count: (value) => typeof value === "number"
+};
+async function ormCallContentHash(source, call) {
+	return hashContent(canonicalStringify({
+		kind: "orm-call",
+		method: call.method,
+		hashInput: await call.hashInput(source)
+	}));
+}
+/** Starts the call in the same turn as the terminal method, so a runtime closed after the method returns waits for it. The content hash is computed only when a middleware asks for it. */
+function startOrmCall(source, call) {
+	return source.startActivity({
+		kind: "orm-call",
+		contentHash: () => ormCallContentHash(source, call),
+		...call.annotations === void 0 ? {} : { annotations: call.annotations }
+	});
+}
+/** Ends a call whose work failed. The runtime has ended the activity `failed` even when `end` rejects, so the caller gets the error that failed the call; the error from `end`, such as one an `activityEnded` hook threw, becomes its `cause` when it has none. */
+async function endFailed(handle, failure) {
+	try {
+		await handle.end({ outcome: "failed" });
+	} catch (endError) {
+		if (failure instanceof Error && failure.cause === void 0) failure.cause = endError;
+	}
+}
+async function interceptedResult(handle, call, intercepted) {
+	const { result } = intercepted;
+	if (!call.accepts(result)) {
+		const invalid = ormError("ORM.INTERCEPTED_RESULT_INVALID", `A middleware answered ${call.method}() with a value that is not a result of ${call.method}()`, { meta: { method: call.method } });
+		await endFailed(handle, invalid);
+		throw invalid;
+	}
+	await handle.end({ outcome: "succeeded" });
+	return result;
+}
+function activitySourceOf(queryable, method) {
+	const source = findActivitySource(queryable);
+	if (source === void 0) throw ormError("ORM.ACTIVITY_SOURCE_MISSING", `${method}() runs as an orm-call activity, and the queryable it was given has no activity source`, {
+		fix: "Pass the ORM a runtime, connection or transaction from the SQL runtime, or a wrapper that keeps its [activitySource] member.",
+		meta: { method }
+	});
+	return source;
+}
+async function runOrmCall(queryable, call, run) {
+	const handle = await startOrmCall(activitySourceOf(queryable, call.method), call);
+	if (handle.intercepted !== void 0) return interceptedResult(handle, call, handle.intercepted);
+	let result;
+	try {
+		result = await run(handle);
+	} catch (error) {
+		await endFailed(handle, error);
+		throw error;
+	}
+	await handle.end({
+		outcome: "succeeded",
+		result
+	});
+	return result;
+}
+/** The call ends when the caller reads to the end, stops early or the stream fails. Its result holds the rows only when it carries annotations, so an unannotated stream does not hold its rows. */
+function streamOrmCall(queryable, call, run) {
+	return new AsyncIterableResult(new OrmCallRows(activitySourceOf(queryable, call.method), call, run));
+}
+const done = {
+	done: true,
+	value: void 0
+};
+/**
+* The rows of a streaming call. The call starts on the first `next()`. Like an async generator, it runs one `next()`, `return()` or `throw()` at a time and queues the calls that overlap it; unlike one, it forwards each row from the statement's iterator with a single promise.
+*/
+var OrmCallRows = class {
+	#source;
+	#call;
+	#run;
+	#state = "idle";
+	#handle;
+	#inner;
+	#intercepted;
+	#collected;
+	#busy = false;
+	#waiting = [];
+	constructor(source, call, run) {
+		this.#source = source;
+		this.#call = call;
+		this.#run = run;
+	}
+	next() {
+		return this.#enqueue(() => this.#next());
+	}
+	return() {
+		return this.#enqueue(() => this.#return());
+	}
+	throw(error) {
+		return this.#enqueue(() => this.#throw(error));
+	}
+	[Symbol.asyncIterator]() {
+		return this;
+	}
+	async [Symbol.asyncDispose]() {
+		await this.return();
+	}
+	#enqueue(operation) {
+		if (!this.#busy) {
+			this.#busy = true;
+			return operation();
+		}
+		return new Promise((resolve, reject) => {
+			this.#waiting.push(() => {
+				operation().then(resolve, reject);
+			});
+		});
+	}
+	#release() {
+		const waiting = this.#waiting.shift();
+		if (waiting === void 0) this.#busy = false;
+		else waiting();
+	}
+	#next() {
+		switch (this.#state) {
+			case "idle": return this.#start().then(() => this.#next(), (error) => {
+				this.#release();
+				throw error;
+			});
+			case "running": return this.#nextRow();
+			case "intercepted": {
+				const row = this.#intercepted?.next();
+				this.#release();
+				if (row === void 0 || row.done === true) {
+					this.#state = "finished";
+					return Promise.resolve(done);
+				}
+				return Promise.resolve({
+					done: false,
+					value: row.value
+				});
+			}
+			default:
+				this.#release();
+				return Promise.resolve(done);
+		}
+	}
+	async #return() {
+		try {
+			const handle = this.#handle;
+			if (this.#state !== "running" || handle === void 0) {
+				this.#state = "finished";
+				return done;
+			}
+			this.#state = "finished";
+			try {
+				await this.#inner?.return?.();
+			} catch (error) {
+				await endFailed(handle, error);
+				throw error;
+			}
+			await handle.end({ outcome: "stopped" });
+			return done;
+		} finally {
+			this.#release();
+		}
+	}
+	async #throw(error) {
+		try {
+			const handle = this.#handle;
+			if (this.#state !== "running" || handle === void 0) {
+				this.#state = "finished";
+				throw error;
+			}
+			this.#state = "finished";
+			try {
+				await this.#inner?.return?.();
+			} catch {}
+			await endFailed(handle, error);
+			throw error;
+		} finally {
+			this.#release();
+		}
+	}
+	async #start() {
+		let handle;
+		try {
+			handle = await startOrmCall(this.#source, this.#call);
+		} catch (error) {
+			this.#state = "finished";
+			throw error;
+		}
+		this.#handle = handle;
+		if (handle.intercepted !== void 0) {
+			try {
+				const rows = await interceptedResult(handle, this.#call, handle.intercepted);
+				this.#intercepted = rows[Symbol.iterator]();
+			} catch (error) {
+				this.#state = "finished";
+				throw error;
+			}
+			this.#state = "intercepted";
+			return;
+		}
+		const annotations = this.#call.annotations;
+		this.#collected = annotations !== void 0 && annotations.size > 0 ? [] : void 0;
+		try {
+			this.#inner = this.#run(handle)[Symbol.asyncIterator]();
+		} catch (error) {
+			this.#state = "finished";
+			await endFailed(handle, error);
+			throw error;
+		}
+		this.#state = "running";
+	}
+	#nextRow() {
+		const inner = this.#inner;
+		const handle = this.#handle;
+		if (inner === void 0 || handle === void 0) {
+			this.#release();
+			return Promise.resolve(done);
+		}
+		let pending;
+		try {
+			pending = inner.next();
+		} catch (error) {
+			return this.#fail(handle, error);
+		}
+		return pending.then((result) => {
+			if (result.done !== true) {
+				this.#collected?.push(result.value);
+				this.#release();
+				return result;
+			}
+			this.#state = "finished";
+			const collected = this.#collected;
+			return handle.end(collected === void 0 ? { outcome: "succeeded" } : {
+				outcome: "succeeded",
+				result: collected
+			}).then(() => {
+				this.#release();
+				return done;
+			}, (endError) => {
+				this.#release();
+				throw endError;
+			});
+		}, (error) => this.#fail(handle, error));
+	}
+	async #fail(handle, error) {
+		try {
+			this.#state = "finished";
+			await endFailed(handle, error);
+			throw error;
+		} finally {
+			this.#release();
+		}
+	}
+};
+const preparedOrmCall = Symbol("preparedOrmCall");
+function asPreparedOrmCall(preparable, call) {
+	return {
+		...preparable,
+		[preparedOrmCall]: call
+	};
+}
+function isPreparableOrmCall(preparable) {
+	return preparedOrmCall in preparable;
+}
+function preparedOrmCallOf(preparable) {
+	return isPreparableOrmCall(preparable) ? preparable[preparedOrmCall] : void 0;
+}
+function preparedRowsCall(method, annotations, consume) {
+	return (target, rows, hashInput) => streamOrmCall(target, {
+		method,
+		annotations,
+		hashInput,
+		accepts: ormResults.rows
+	}, (queryable) => consume(rows(queryable)));
+}
+function preparedValueCall(method, annotations, consume, accepts) {
+	return (target, rows, hashInput) => runOrmCall(target, {
+		method,
+		annotations,
+		hashInput,
+		accepts
+	}, (queryable) => consume(rows(queryable)));
+}
+const groupedAggregateMethod = "groupBy.aggregate";
 var GroupedCollection = class GroupedCollection {
 	ctx;
 	contract;
@@ -3892,21 +4180,34 @@ var GroupedCollection = class GroupedCollection {
 			offset: typeof n === "number" ? n : toExpr(n)
 		} });
 	}
+	get prepared() {
+		return { aggregate: (fn, configure) => {
+			const description = this.#describeAggregate(fn);
+			return asPreparedOrmCall(description, preparedValueCall(groupedAggregateMethod, this.#annotations(configure), description.consume, ormResults.rows));
+		} };
+	}
 	/**
 	* Read terminal: run a grouped aggregate query.
 	*
 	* Accepts an optional `configure` callback that receives a
-	* `MetaBuilder<'read'>` for attaching typed annotations.
-	* Annotations are merged into the compiled plan's `meta.annotations`.
+	* `MetaBuilder<'read'>` for attaching typed annotations to the call.
 	*/
-	get prepared() {
-		return { aggregate: (fn, configure) => this.#describeAggregate(fn, configure) };
-	}
 	async aggregate(fn, configure) {
-		const description = this.#describeAggregate(fn, configure);
-		return description.consume(queryPlanRows(this.ctx.runtime, description.plan));
+		const description = this.#describeAggregate(fn);
+		return runOrmCall(this.ctx.runtime, {
+			method: groupedAggregateMethod,
+			annotations: this.#annotations(configure),
+			hashInput: planHashInput(() => description.plan),
+			accepts: ormResults.rows
+		}, (queryable) => runQuery(queryable, description));
+	}
+	#annotations(configure) {
+		if (configure === void 0) return void 0;
+		const meta = createMetaBuilder("read", groupedAggregateMethod);
+		configure(meta);
+		return meta.annotations.size > 0 ? meta.annotations : void 0;
 	}
-	#describeAggregate(fn, configure) {
+	#describeAggregate(fn) {
 		const aggregateSpec = fn(createAggregateBuilder(this.contract, this.ctx.context.aggregateDescriptors, this.namespaceId, this.modelName));
 		const aggregateEntries = Object.entries(aggregateSpec);
 		if (aggregateEntries.length === 0) throw ormError("ORM.AGGREGATE_SELECTOR_MISSING", "groupBy().aggregate() requires at least one aggregation selector", { meta: {
@@ -3918,13 +4219,7 @@ var GroupedCollection = class GroupedCollection {
 			model: this.modelName,
 			alias
 		} });
-		let annotationsMap;
-		if (configure !== void 0) {
-			const meta = createMetaBuilder("read", "groupBy.aggregate");
-			configure(meta);
-			if (meta.annotations.size > 0) annotationsMap = meta.annotations;
-		}
-		const compiled = mergeAnnotations(compileGroupedAggregate(this.contract, this.ctx.context.aggregateDescriptors, this.preGroupState, this.groupByColumns, aggregateSpec, combineWhereExprs(this.havingFilters), this.modelName, this.postGroup), annotationsMap);
+		const compiled = compileGroupedAggregate(this.contract, this.ctx.context.aggregateDescriptors, this.preGroupState, this.groupByColumns, aggregateSpec, combineWhereExprs(this.havingFilters), this.modelName, this.postGroup);
 		const mapRow = createStorageRowMapper(this.contract, this.namespaceId, this.modelName);
 		return {
 			plan: compiled,
@@ -5002,36 +5297,33 @@ function whereOf(collection) {
 	const { context, state } = collection;
 	return countMutationWhere(context.contract, state.tables, state.filters, state.variantValue);
 }
-function queryGraph(graph, ctx, annotations, callerRows) {
+function queryGraph(graph, ctx, callerRows) {
 	returnCallerColumns(graph, callerRows);
 	const [only, ...others] = graph.nodes();
 	if (only !== void 0 && others.length === 0 && only[0] === graph.result) {
 		const [id, node] = only;
-		const run = runOn(ctx, annotations);
+		const run = runOn(ctx, ctx.runtime);
 		return shapeRows(graph, id, rowStream(node.execute(inputsOf(graph, id, []), run)), callerRows);
 	}
 	const generator = async function* () {
-		yield* (await runAllNodes(graph, ctx, annotations, callerRows)).rows;
+		yield* (await runAllNodes(graph, ctx, callerRows)).rows;
 	};
 	return new AsyncIterableResult(generator());
 }
-async function executeGraph(graph, ctx, annotations) {
-	return { affectedRows: (await runAllNodes(graph, ctx, annotations, void 0)).count };
+async function executeGraph(graph, ctx) {
+	return { affectedRows: (await runAllNodes(graph, ctx, void 0)).count };
 }
 function returnCallerColumns(graph, callerRows) {
 	const { context, modelName, state } = callerRows;
 	const columns = returningProjection(context.contract, modelName, state.tables.root, state.selectedFields);
 	for (const [id, node] of graph.nodes()) if (id === graph.result && node instanceof StatementNode) graph.replace(id, node.withReturning(columns));
 }
-function runAllNodes(graph, ctx, annotations, callerRows) {
-	if (graph.nodes().length > 1) return withMutationScope(ctx.runtime, (scope) => runNodesInOrder(graph, {
-		...ctx,
-		runtime: scope
-	}, annotations, callerRows));
-	return runNodesInOrder(graph, ctx, annotations, callerRows);
+function runAllNodes(graph, ctx, callerRows) {
+	if (graph.nodes().length > 1) return withMutationScope(ctx.runtime, (scope) => runNodesInOrder(graph, ctx, scope, callerRows));
+	return runNodesInOrder(graph, ctx, ctx.runtime, callerRows);
 }
-async function runNodesInOrder(graph, ctx, annotations, callerRows) {
-	const run = runOn(ctx, annotations);
+async function runNodesInOrder(graph, ctx, scope, callerRows) {
+	const run = runOn(ctx, scope);
 	const collected = [];
 	let rows = [];
 	let count = 0;
@@ -5055,12 +5347,12 @@ function inputsOf(graph, id, collected) {
 	else outputs[name] = slot.length === 0 ? null : slot.map(outputOf);
 	return outputs;
 }
-function runOn(ctx, annotations) {
+function runOn(ctx, scope) {
 	const { contract } = ctx.context;
-	const planOf = (ast) => mergeAnnotations(buildOrmQueryPlan(contract, ast, deriveParamsFromAst(ast).params), annotations);
+	const planOf = (ast) => buildOrmQueryPlan(contract, ast, deriveParamsFromAst(ast).params);
 	return {
-		query: (ast) => queryPlanRows(ctx.runtime, planOf(ast)),
-		execute: async (ast) => (await ctx.runtime.execute(planOf(ast))).affectedRows
+		query: (ast) => queryPlanRows(scope, planOf(ast)),
+		execute: async (ast) => (await scope.execute(planOf(ast))).affectedRows
 	};
 }
 function shapeRows(graph, id, storageRows, callerRows) {
@@ -5560,22 +5852,36 @@ var CollectionBase = class CollectionBase {
 		return this.#cloneSelf({ offset: typeof n === "number" ? n : toExpr(n) });
 	}
 	all(configure) {
-		return this.#withAnnotationsFromMeta(configure, "all").#dispatch();
+		const annotations = this.#collectAnnotationsFromMeta(configure, "read", "all");
+		const query = describeCollectionQuery(this.#descriptionOptions());
+		return streamOrmCall(this.ctx.runtime, this.#readCall("all", annotations, query.plan, ormResults.rows), query.rows);
 	}
 	get prepared() {
 		return blindCast({
-			aggregate: (fn, configure) => this.#describeAggregate(fn, configure),
+			aggregate: (fn, configure) => this.#preparedAggregate(fn, configure),
 			all: (configure) => {
-				return describeCollectionRows(this.#withAnnotationsFromMeta(configure, "all").#descriptionOptions());
+				const annotations = this.#collectAnnotationsFromMeta(configure, "read", "all");
+				const description = describeCollectionRows(this.#descriptionOptions());
+				return asPreparedOrmCall(description, preparedRowsCall("all", annotations, description.consume));
 			},
 			first: (filter, configure) => {
-				return describeCollectionFirst(this.#forFirst(filter, configure, "first").#descriptionOptions());
+				const scoped = this.#forFirst(filter);
+				const annotations = this.#collectAnnotationsFromMeta(configure, "read", "first");
+				const description = describeCollectionFirst(scoped.#descriptionOptions());
+				return asPreparedOrmCall(description, preparedValueCall("first", annotations, description.consume, ormResults.rowOrNull));
 			},
 			firstOrThrow: (filter, configure) => {
-				return describeCollectionFirstOrThrow(this.#forFirst(filter, configure, "firstOrThrow").#descriptionOptions());
+				const scoped = this.#forFirst(filter);
+				const annotations = this.#collectAnnotationsFromMeta(configure, "read", "firstOrThrow");
+				const description = describeCollectionFirstOrThrow(scoped.#descriptionOptions());
+				return asPreparedOrmCall(description, preparedValueCall("firstOrThrow", annotations, description.consume, ormResults.row));
 			}
 		});
 	}
+	#preparedAggregate(fn, configure) {
+		const description = this.#describeAggregate(fn);
+		return asPreparedOrmCall(description, preparedValueCall("aggregate", this.#collectAnnotationsFromMeta(configure, "read", "aggregate"), description.consume, ormResults.row));
+	}
 	#descriptionOptions() {
 		return {
 			context: this.ctx.context,
@@ -5584,20 +5890,49 @@ var CollectionBase = class CollectionBase {
 			namespaceId: this.namespaceId
 		};
 	}
-	#forFirst(filter, configure, terminalName) {
-		return (filter === void 0 ? this : typeof filter === "function" ? this.where(filter) : this.where(filter)).limit(1).#withAnnotationsFromMeta(configure, terminalName);
+	#forFirst(filter) {
+		return (filter === void 0 ? this : typeof filter === "function" ? this.where(filter) : this.where(filter)).limit(1);
+	}
+	#readCall(method, annotations, plan, accepts) {
+		return {
+			method,
+			annotations,
+			hashInput: planHashInput(plan),
+			accepts
+		};
+	}
+	#writeCall(method, annotations, accepts) {
+		return {
+			method,
+			annotations,
+			hashInput: modelHashInput(this.namespaceId, this.modelName),
+			accepts
+		};
+	}
+	#on(queryable) {
+		return {
+			...this.ctx,
+			runtime: queryable
+		};
 	}
 	async first(filter, configure) {
-		return consumeFirstRow(this.#forFirst(filter, configure, "first").#dispatch());
+		const scoped = this.#forFirst(filter);
+		const annotations = this.#collectAnnotationsFromMeta(configure, "read", "first");
+		const query = describeCollectionQuery(scoped.#descriptionOptions());
+		return runOrmCall(this.ctx.runtime, this.#readCall("first", annotations, query.plan, ormResults.rowOrNull), (queryable) => consumeFirstRow(query.rows(queryable)));
 	}
 	async firstOrThrow(filter, configure) {
-		return this.#forFirst(filter, configure, "firstOrThrow").#dispatch().firstOrThrow();
+		const scoped = this.#forFirst(filter);
+		const annotations = this.#collectAnnotationsFromMeta(configure, "read", "firstOrThrow");
+		const query = describeCollectionQuery(scoped.#descriptionOptions());
+		return runOrmCall(this.ctx.runtime, this.#readCall("firstOrThrow", annotations, query.plan, ormResults.row), (queryable) => query.rows(queryable).firstOrThrow());
 	}
 	async aggregate(fn, configure) {
-		const description = this.#describeAggregate(fn, configure);
-		return description.consume(queryPlanRows(this.ctx.runtime, description.plan));
+		const description = this.#describeAggregate(fn);
+		const annotations = this.#collectAnnotationsFromMeta(configure, "read", "aggregate");
+		return runOrmCall(this.ctx.runtime, this.#readCall("aggregate", annotations, () => description.plan, ormResults.row), (queryable) => runQuery(queryable, description));
 	}
-	#describeAggregate(fn, configure) {
+	#describeAggregate(fn) {
 		assertLockCompatible(this.state, "aggregate");
 		const aggregateSpec = fn(createAggregateBuilder(this.contract, this.ctx.context.aggregateDescriptors, this.namespaceId, this.modelName));
 		const entries = Object.entries(aggregateSpec);
@@ -5610,8 +5945,7 @@ var CollectionBase = class CollectionBase {
 			model: this.modelName,
 			alias
 		} });
-		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "read", "aggregate");
-		const compiled = mergeAnnotations(compileAggregate(this.contract, this.ctx.context.aggregateDescriptors, this.state, aggregateSpec, this.modelName), annotationsMap);
+		const compiled = compileAggregate(this.contract, this.ctx.context.aggregateDescriptors, this.state, aggregateSpec, this.modelName);
 		const results = entries.map(([alias, selector]) => {
 			const resolved = resolveAggregate({
 				aggregates: this.ctx.context.aggregateDescriptors,
@@ -5640,24 +5974,27 @@ var CollectionBase = class CollectionBase {
 	async create(data, configure) {
 		assertLockCompatible(this.state, "mutation");
 		assertReturningCapability(this.contract, "create()");
-		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "create");
+		const annotations = this.#collectAnnotationsFromMeta(configure, "write", "create");
+		return runOrmCall(this.ctx.runtime, this.#writeCall("create", annotations, ormResults.row), (queryable) => this.#create(queryable, data));
+	}
+	async #create(queryable, data) {
 		if (hasNestedMutationCallbacks(this.contract, this.namespaceId, this.modelName, blindCast(data))) {
 			const createdRow = await executeNestedCreateMutation({
 				context: this.ctx.context,
-				runtime: this.ctx.runtime,
+				runtime: queryable,
 				namespaceId: this.namespaceId,
 				modelName: this.modelName,
 				data: blindCast(data)
 			});
 			const identityCriterion = buildRowIdentityFilterFromRow(this.contract, this.namespaceId, this.modelName, createdRow);
-			const reloaded = await this.#reloadMutationRowByIdentity(identityCriterion);
+			const reloaded = await this.#reloadMutationRowByIdentity(queryable, identityCriterion);
 			if (!reloaded) throw ormError("ORM.MUTATION_ROW_MISSING", `create() for model "${this.modelName}" did not return a row`, { meta: {
 				operation: "create",
 				model: this.modelName
 			} });
 			return reloaded;
 		}
-		const created = (await this.#createAllWithAnnotations([blindCast(data)], annotationsMap))[0];
+		const created = (await this.#createAllRows([blindCast(data)])(queryable))[0];
 		if (created) return created;
 		throw ormError("ORM.MUTATION_ROW_MISSING", `create() for model "${this.modelName}" did not return a row`, { meta: {
 			operation: "create",
@@ -5668,21 +6005,24 @@ var CollectionBase = class CollectionBase {
 		assertLockCompatible(this.state, "mutation");
 		const { options, configureCallback } = splitCreateArguments(optionsOrConfigure, configure);
 		const conflictSkip = this.#resolveConflictSkip(options, "createAll()");
-		return this.#createAllWithAnnotations(data, this.#collectAnnotationsFromMeta(configureCallback, "write", "createAll"), conflictSkip);
+		const annotations = this.#collectAnnotationsFromMeta(configureCallback, "write", "createAll");
+		return streamOrmCall(this.ctx.runtime, this.#writeCall("createAll", annotations, ormResults.rows), this.#createAllRows(data, conflictSkip));
 	}
-	#createAllWithAnnotations(data, annotationsMap, conflictSkip) {
+	#createAllRows(data, conflictSkip) {
 		if (data.length === 0) {
 			const generator = async function* () {};
-			return new AsyncIterableResult(generator());
+			return () => new AsyncIterableResult(generator());
 		}
 		assertReturningCapability(this.contract, "createAll()");
 		const rows = blindCast(data);
 		const mtiContext = this.#resolveMtiCreateContext();
 		if (mtiContext) {
 			const variantTable = requireVariantTable(this.state.tables, mtiContext.variant.value);
-			return queryGraph(createAllVariantGraph(this.#descriptionWithoutIncludes(), variantTable, mtiContext.variant.modelName, this.#variantCreateRows(rows, mtiContext, variantTable)), this.ctx, annotationsMap, this.#descriptionWithoutIncludes());
+			const graph = createAllVariantGraph(this.#descriptionWithoutIncludes(), variantTable, mtiContext.variant.modelName, this.#variantCreateRows(rows, mtiContext, variantTable));
+			return (queryable) => queryGraph(graph, this.#on(queryable), this.#descriptionWithoutIncludes());
 		}
-		return queryGraph(createAllGraph(this.#descriptionOptions(), this.#createValues(rows), conflictSkip), this.ctx, annotationsMap, this.#descriptionOptions());
+		const graph = createAllGraph(this.#descriptionOptions(), this.#createValues(rows), conflictSkip);
+		return (queryable) => queryGraph(graph, this.#on(queryable), this.#descriptionOptions());
 	}
 	#createValues(rows) {
 		const mappedRows = this.#mapCreateRows(rows);
@@ -5807,17 +6147,24 @@ var CollectionBase = class CollectionBase {
 		assertLockCompatible(this.state, "mutation");
 		const { options, configureCallback } = splitCreateArguments(optionsOrConfigure, configure);
 		const conflictSkip = this.#resolveConflictSkip(options, "createAndCount()");
-		if (data.length === 0) return 0;
+		const annotations = this.#collectAnnotationsFromMeta(configureCallback, "write", "createAndCount");
+		const call = this.#writeCall("createAndCount", annotations, ormResults.count);
+		if (data.length === 0) return runOrmCall(this.ctx.runtime, call, async () => 0);
 		this.#assertNotMtiVariant("createAndCount()");
-		const annotationsMap = this.#collectAnnotationsFromMeta(configureCallback, "write", "createAndCount");
 		const rows = blindCast(data);
-		return (await executeGraph(createAllGraph(this.#descriptionWithoutIncludes(), this.#createValues(rows), conflictSkip), this.ctx, annotationsMap)).affectedRows;
+		const graph = createAllGraph(this.#descriptionWithoutIncludes(), this.#createValues(rows), conflictSkip);
+		return this.#countCall(call, graph);
+	}
+	#countCall(call, graph) {
+		return runOrmCall(this.ctx.runtime, call, async (queryable) => {
+			return (await executeGraph(graph, this.#on(queryable))).affectedRows;
+		});
 	}
 	async upsert(input, configure) {
 		assertLockCompatible(this.state, "mutation");
 		assertReturningCapability(this.contract, "upsert()");
 		this.#assertNotMtiVariant("upsert()");
-		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "upsert");
+		const annotations = this.#collectAnnotationsFromMeta(configure, "write", "upsert");
 		const createValues = this.#mapCreateRows([blindCast(input.create)])[0] ?? {};
 		applyCreateDefaults(this.ctx, this.namespaceId, this.tableName, [createValues]);
 		const updateValues = mapModelDataToStorageRow(this.contract, this.namespaceId, this.modelName, input.update);
@@ -5827,22 +6174,28 @@ var CollectionBase = class CollectionBase {
 			method: "upsert",
 			model: this.modelName
 		} });
-		const row = await consumeFirstRow(queryGraph(upsertGraph(this.#descriptionOptions(), createValues, updateValues, conflictColumns), this.ctx, annotationsMap, this.#descriptionOptions()));
-		if (row) return row;
-		throw ormError("ORM.MUTATION_ROW_MISSING", `upsert() for model "${this.modelName}" did not return a row`, { meta: {
-			operation: "upsert",
-			model: this.modelName
-		} });
+		const graph = upsertGraph(this.#descriptionOptions(), createValues, updateValues, conflictColumns);
+		return runOrmCall(this.ctx.runtime, this.#writeCall("upsert", annotations, ormResults.row), async (queryable) => {
+			const row = await consumeFirstRow(queryGraph(graph, this.#on(queryable), this.#descriptionOptions()));
+			if (row) return row;
+			throw ormError("ORM.MUTATION_ROW_MISSING", `upsert() for model "${this.modelName}" did not return a row`, { meta: {
+				operation: "upsert",
+				model: this.modelName
+			} });
+		});
 	}
 	async update(data, configure) {
 		assertLockCompatible(this.state, "mutation");
 		assertReturningCapability(this.contract, "update()");
-		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "update");
+		const annotations = this.#collectAnnotationsFromMeta(configure, "write", "update");
+		return runOrmCall(this.ctx.runtime, this.#writeCall("update", annotations, ormResults.rowOrNull), (queryable) => this.#update(queryable, data));
+	}
+	async #update(queryable, data) {
 		if (hasNestedMutationCallbacks(this.contract, this.namespaceId, this.modelName, blindCast(data))) {
 			assertRelationUpdateIgnoresNothing(this.state, this.modelName);
 			const updatedRow = await executeNestedUpdateMutation({
 				context: this.ctx.context,
-				runtime: this.ctx.runtime,
+				runtime: queryable,
 				namespaceId: this.namespaceId,
 				modelName: this.modelName,
 				tables: this.state.tables,
@@ -5851,45 +6204,55 @@ var CollectionBase = class CollectionBase {
 			});
 			if (!updatedRow) return null;
 			const identityCriterion = buildRowIdentityFilterFromRow(this.contract, this.namespaceId, this.modelName, updatedRow);
-			return this.#reloadMutationRowByIdentity(identityCriterion);
+			return this.#reloadMutationRowByIdentity(queryable, identityCriterion);
 		}
 		assertModelFieldNames(this.contract, this.namespaceId, this.modelName, blindCast(data));
 		const values = this.#updateValues(blindCast(data));
-		return consumeFirstRow(queryGraph(updateFirstGraph(this.#descriptionOptions(), values), this.ctx, annotationsMap, this.#descriptionOptions()));
+		return consumeFirstRow(queryGraph(updateFirstGraph(this.#descriptionOptions(), values), this.#on(queryable), this.#descriptionOptions()));
 	}
 	updateAll(data, configure) {
 		assertBulkWriteIgnoresNothing(this.state, this.modelName, "updateAll");
 		assertLockCompatible(this.state, "mutation");
-		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "updateAll");
+		const annotations = this.#collectAnnotationsFromMeta(configure, "write", "updateAll");
 		assertReturningCapability(this.contract, "updateAll()");
-		return queryGraph(updateAllGraph(this.#descriptionOptions(), this.#updateValues(data)), this.ctx, annotationsMap, this.#descriptionOptions());
+		const graph = updateAllGraph(this.#descriptionOptions(), this.#updateValues(data));
+		return this.#rowsCall("updateAll", annotations, graph);
+	}
+	#rowsCall(method, annotations, graph) {
+		return streamOrmCall(this.ctx.runtime, this.#writeCall(method, annotations, ormResults.rows), (queryable) => queryGraph(graph, this.#on(queryable), this.#descriptionOptions()));
+	}
+	#firstRowCall(method, annotations, graph) {
+		return runOrmCall(this.ctx.runtime, this.#writeCall(method, annotations, ormResults.rowOrNull), (queryable) => consumeFirstRow(queryGraph(graph, this.#on(queryable), this.#descriptionOptions())));
 	}
 	async updateAndCount(data, configure) {
 		assertBulkWriteIgnoresNothing(this.state, this.modelName, "updateAndCount");
 		assertLockCompatible(this.state, "mutation");
 		const values = this.#updateValues(data);
 		const graph = Object.keys(values).length === 0 ? new Graph() : updateAllGraph(this.#descriptionWithoutIncludes(), values);
-		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "updateAndCount");
-		return (await executeGraph(graph, this.ctx, annotationsMap)).affectedRows;
+		const annotations = this.#collectAnnotationsFromMeta(configure, "write", "updateAndCount");
+		return this.#countCall(this.#writeCall("updateAndCount", annotations, ormResults.count), graph);
 	}
 	async delete(configure) {
 		assertLockCompatible(this.state, "mutation");
 		assertReturningCapability(this.contract, "delete()");
-		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "delete");
-		return consumeFirstRow(queryGraph(deleteFirstGraph(this.#descriptionOptions()), this.ctx, annotationsMap, this.#descriptionOptions()));
+		const annotations = this.#collectAnnotationsFromMeta(configure, "write", "delete");
+		const graph = deleteFirstGraph(this.#descriptionOptions());
+		return this.#firstRowCall("delete", annotations, graph);
 	}
 	deleteAll(configure) {
 		assertBulkWriteIgnoresNothing(this.state, this.modelName, "deleteAll");
 		assertLockCompatible(this.state, "mutation");
-		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "deleteAll");
+		const annotations = this.#collectAnnotationsFromMeta(configure, "write", "deleteAll");
 		assertReturningCapability(this.contract, "deleteAll()");
-		return queryGraph(deleteAllGraph(this.#descriptionOptions()), this.ctx, annotationsMap, this.#descriptionOptions());
+		const graph = deleteAllGraph(this.#descriptionOptions());
+		return this.#rowsCall("deleteAll", annotations, graph);
 	}
 	async deleteAndCount(configure) {
 		assertBulkWriteIgnoresNothing(this.state, this.modelName, "deleteAndCount");
 		assertLockCompatible(this.state, "mutation");
-		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "deleteAndCount");
-		return (await executeGraph(deleteAllGraph(this.#descriptionWithoutIncludes()), this.ctx, annotationsMap)).affectedRows;
+		const annotations = this.#collectAnnotationsFromMeta(configure, "write", "deleteAndCount");
+		const graph = deleteAllGraph(this.#descriptionWithoutIncludes());
+		return this.#countCall(this.#writeCall("deleteAndCount", annotations, ormResults.count), graph);
 	}
 	#descriptionWithoutIncludes() {
 		return {
@@ -5905,10 +6268,10 @@ var CollectionBase = class CollectionBase {
 		if (Object.keys(values).length > 0) applyUpdateDefaults(this.ctx, this.namespaceId, this.tableName, values);
 		return values;
 	}
-	async #reloadMutationRowByIdentity(criterion) {
-		return this.#reloadMutationRowByCriterion(criterion, "row identity");
+	async #reloadMutationRowByIdentity(queryable, criterion) {
+		return this.#reloadMutationRowByCriterion(queryable, criterion, "row identity");
 	}
-	async #reloadMutationRowByCriterion(criterion, criterionLabel) {
+	async #reloadMutationRowByCriterion(queryable, criterion, criterionLabel) {
 		const whereExpr = shorthandToWhereExpr(this.ctx.context, this.namespaceId, this.modelName, blindCast(criterion), this.state.tables.root);
 		if (!whereExpr) throw new InternalError(`Failed to build ${criterionLabel} filter for mutation result on model "${this.modelName}"`);
 		const resultState = {
@@ -5920,7 +6283,7 @@ var CollectionBase = class CollectionBase {
 		};
 		return (await dispatchCollectionRows({
 			context: this.ctx.context,
-			runtime: this.ctx.runtime,
+			runtime: queryable,
 			state: resultState,
 			modelName: this.modelName,
 			namespaceId: this.namespaceId
@@ -5942,12 +6305,6 @@ var CollectionBase = class CollectionBase {
 		});
 		return this.#cloneSelf({ locking: [...this.state.locking ?? [], clause] });
 	}
-	#clone(overrides) {
-		return this.#createSelf({
-			...this.state,
-			...overrides
-		});
-	}
 	#cloneSelf(overrides) {
 		return blindCast(this.#createSelf({
 			...this.state,
@@ -5978,48 +6335,6 @@ var CollectionBase = class CollectionBase {
 			includeRefinementMode: options.includeRefinementMode ?? this.includeRefinementMode
 		}));
 	}
-	#dispatch() {
-		return dispatchCollectionRows({
-			context: this.ctx.context,
-			runtime: this.ctx.runtime,
-			state: this.state,
-			modelName: this.modelName,
-			namespaceId: this.namespaceId
-		});
-	}
-	/**
-	* Invokes the user-supplied configurator (if any) against a freshly
-	* constructed read meta builder, and returns a clone whose
-	* `state.annotations` carries the recorded map. Used by read
-	* terminals that flow annotations through state (`all`, `first`).
-	*
-	* Returns the receiver unchanged when no configurator was supplied
-	* or when the configurator did not call `meta.annotate(...)`. The
-	* meta builder's `annotate` method enforces applicability at the
-	* type level and at runtime, so terminal code does not need to
-	* re-validate.
-	*/
-	#withAnnotationsFromMeta(configure, terminalName) {
-		if (configure === void 0) return this;
-		const meta = createMetaBuilder("read", terminalName);
-		configure(meta);
-		if (meta.annotations.size === 0) return this;
-		const next = new Map(this.state.annotations);
-		for (const [namespace, value] of meta.annotations) next.set(namespace, value);
-		return blindCast(this.#clone({ annotations: next }));
-	}
-	/**
-	* Invokes the user-supplied configurator (if any) against a freshly
-	* constructed meta builder of the given operation kind, and returns
-	* the recorded annotation map (or `undefined` when empty). Used by
-	* terminals where annotations don't flow through `state` — the
-	* compiled plan is post-wrapped via `mergeAnnotations` instead.
-	* Read terminals `all` and `first` populate `state.annotations`
-	* via `#withAnnotationsFromMeta` instead; `aggregate` uses this
-	* post-wrap path because `compileAggregate` does not forward `state.annotations` into the plan.
-	* The meta builder's `annotate` method enforces applicability at the
-	* type level and at runtime.
-	*/
 	#collectAnnotationsFromMeta(configure, kind, terminalName) {
 		if (configure === void 0) return;
 		const meta = createMetaBuilder(kind, terminalName);
@@ -6146,7 +6461,10 @@ async function prepareQuery(runtime, declaration, callback) {
 }
 function createPreparedRowQuery(description, statement) {
 	return Object.freeze({ query(target, params, options) {
-		return description.consume(statement.query(target, params, options));
+		const rows = (queryable) => statement.query(queryable, params, options);
+		const call = preparedOrmCallOf(description);
+		if (call === void 0) return description.consume(rows(target));
+		return call(target, rows, preparedHashInput(statement, params));
 	} });
 }
 //#endregion