@prisma/orm-family-sql 0.17.0-dev.1 → 0.17.0-dev.11

package/dist/orm-client.mjs

@@ -1,11 +1,11 @@
 import { t as resolveStorageTable } from "./resolve-storage-table-DZsfnzeW.mjs";
 import { i as isUniqueConstraintViolation } from "./dist-x6jvtkKM.mjs";
-import { C as LiteralExpr, D as OrExpr, F as SubqueryExpr, I as TableSource, L as UpdateAst, O as OrderByItem, P as SelectAst, R as WindowFuncExpr, S as ListExpression, T as NullCheckExpr, V as isWhereExpr, _ as InsertAst, b as JsonArrayAggExpr, c as DeleteAst, f as EqColJoinOn, j as ProjectionItem, k as ParamRef, l as DerivedTableSource, n as AndExpr, o as ColumnRef, p as ExistsExpr, r as BinaryExpr, s as DefaultValueExpr, t as AggregateExpr, v as InsertOnConflict, w as NotExpr, x as JsonObjectExpr, y as JoinAst } from "./types-BgkZru_1-H7yfikSQ.mjs";
+import { B as isWhereExpr, C as LiteralExpr, D as OrExpr, F as SubqueryExpr, I as TableSource, L as UpdateAst, O as OrderByItem, P as SelectAst, R as WindowFuncExpr, S as ListExpression, T as NullCheckExpr, _ as InsertAst, b as JsonArrayAggExpr, c as DeleteAst, f as EqColJoinOn, j as ProjectionItem, k as ParamRef, l as DerivedTableSource, n as AndExpr, o as ColumnRef, p as ExistsExpr, r as BinaryExpr, s as DefaultValueExpr, t as AggregateExpr, v as InsertOnConflict, w as NotExpr, x as JsonObjectExpr, y as JoinAst } from "./types-D43EhRac-DOJmnq_t.mjs";
 import { t as collectOrderedParamRefs } from "./util-DQQgv2j1-D6INZaRG.mjs";
-import { n as JsonDocumentProjection, r as NativeJsonValueProjection, t as CodecJsonValueProjection } from "./ast-BstHjAoG.mjs";
+import { n as JsonDocumentProjection, r as NativeJsonValueProjection, t as CodecJsonValueProjection } from "./ast-DDAyIKdt.mjs";
 import { n as codecRefForStorageColumn } from "./codec-descriptor-registry-BJVJRftS.mjs";
 import { structuredError } from "@prisma/orm-framework/utils/structured-error";
-import { InternalError, assertNever } from "@prisma/orm-framework/utils/internal-error";
+import { InternalError } from "@prisma/orm-framework/utils/internal-error";
 import { domainModelsAtDefaultNamespace } from "@prisma/orm-framework/contract/types";
 import { blindCast, castAs } from "@prisma/orm-framework/utils/casts";
 import { ifDefined } from "@prisma/orm-framework/utils/defined";
@@ -372,42 +372,27 @@ function isAggregateSelector(value) {
 	if (candidate.kind !== "aggregate") return false;
 	return candidate.fn === "count" || candidate.fn === "sum" || candidate.fn === "avg" || candidate.fn === "min" || candidate.fn === "max";
 }
+/**
+* The selector's result type is the contract's to state — it varies by target, operation, and the field's own codec — so the builder erases it here and each method's declared return type names it.
+*/
 function createFieldAggregateSelector(fieldToColumn, field, fn) {
-	const fieldName = field;
 	return {
 		kind: "aggregate",
 		fn,
-		column: fieldToColumn[fieldName] ?? fieldName
+		column: fieldToColumn[field] ?? field
 	};
 }
-function normalizeAggregateResult(aggregateSpec, row) {
-	const result = {};
-	for (const [alias, selector] of Object.entries(aggregateSpec)) {
-		const value = row[alias];
-		if (value === null) {
-			result[alias] = null;
-			continue;
-		}
-		if (value === void 0) {
-			result[alias] = selector.fn === "count" ? 0 : null;
-			continue;
-		}
-		if (typeof value === "number") {
-			result[alias] = value;
-			continue;
-		}
-		if (typeof value === "bigint") {
-			result[alias] = Number(value);
-			continue;
-		}
-		if (typeof value === "string") {
-			const numeric = Number(value);
-			result[alias] = Number.isNaN(numeric) ? value : numeric;
-			continue;
-		}
-		result[alias] = value;
-	}
-	return result;
+/**
+* What an aggregate reads as when there is no row to read at all.
+*
+* SQL answers an empty input set itself — `count` collapses to zero, the rest
+* to null — so this covers only the degenerate case of a result set with no
+* row: an absent aggregate alias, or an include whose envelope never arrived.
+* Zero is a `bigint` because that is what both targets' `count` codecs decode
+* to; a count is a cardinality, and cardinalities are not capped at 2^53.
+*/
+function emptyAggregateResult(fn) {
+	return fn === "count" ? 0n : null;
 }
 function mapFieldsToColumns(contract, namespaceId, modelName, fieldNames) {
 	const fieldToColumn = getFieldToColumnMap(contract, namespaceId, modelName);
@@ -423,6 +408,43 @@ function mapCursorValuesToColumns(contract, namespaceId, modelName, cursorValues
 	}
 	return mappedCursor;
 }
+/**
+* What an aggregate resolves to: the codec its result carries, and the expression the target wants built for it.
+*
+* An aggregate over a column resolves against that column's own codec, so a target that widens `sum` over small integers and preserves it over decimals answers differently per column without the caller knowing either rule. Where a target also needs the result rendered a particular way — a value its driver cannot otherwise carry — the descriptor's lowering says so, and the codec it declared stays the codec regardless.
+*
+* A pair the composed stack declares no overload for is rejected before any SQL is built: an undeclared aggregate has no result identity to project or decode, and executing it anyway would hand back the driver-native value the declared-codec path exists to replace.
+*/
+function resolveAggregate(query) {
+	const input = inputCodecRef(query);
+	const resolved = query.aggregates.resolve(query.fn, input);
+	if (resolved === void 0) throw unsupportedAggregate(query, input);
+	return {
+		codec: resolved.output,
+		input,
+		lower: resolved.lower
+	};
+}
+/** The codec an aggregate's result carries. Rejects a pair the composed stack declares no overload for, exactly as planning does. */
+function resolveAggregateOutputCodec(query) {
+	return resolveAggregate(query).codec;
+}
+function unsupportedAggregate(query, input) {
+	return ormError("ORM.AGGREGATE_UNSUPPORTED", input === void 0 ? `The composed target declares no '${query.fn}' aggregate for a call without an input.` : `The composed target declares no '${query.fn}' aggregate over codec '${input.codecId}' (column '${query.column}' of table '${query.tableName}').`, {
+		why: "An aggregate result decodes through the codec its target declares; an undeclared pair has no declared result to type or decode.",
+		fix: `Aggregate a column the target declares '${query.fn}' for, or contribute an aggregate descriptor for this pair.`,
+		meta: {
+			operation: query.fn,
+			table: query.tableName,
+			...ifDefined("column", query.column),
+			...ifDefined("inputCodecId", input?.codecId)
+		}
+	});
+}
+/** The codec of the value being aggregated — the column's own, or none where the aggregate is over rows. */
+function inputCodecRef(query) {
+	return query.column === void 0 ? void 0 : codecRefForStorageColumn(query.contract.storage, query.namespaceId, query.tableName, query.column);
+}
 function stripHiddenMappedFields(contract, namespaceId, modelName, mapped, hiddenColumns) {
 	if (hiddenColumns.length === 0) return;
 	const columnToField = getColumnToFieldMap(contract, namespaceId, modelName);
@@ -575,20 +597,22 @@ function combineWhereExprs(filters) {
 	if (filters.length === 1) return filters[0];
 	return AndExpr.of(filters);
 }
-function toAggregateProjection(contract, namespaceId, tableName, selector) {
-	if (selector.fn === "count") return {
-		expr: AggregateExpr.count(),
-		codec: void 0
-	};
-	if (!selector.column) throw ormError("ORM.AGGREGATE_SELECTOR_INVALID", `Aggregate selector "${selector.fn}" requires a field`, { meta: { fn: selector.fn } });
-	const expr = new AggregateExpr(selector.fn, ColumnRef.of(tableName, selector.column));
-	if (selector.fn === "min" || selector.fn === "max") return {
-		expr,
-		codec: codecRefForStorageColumn(contract.storage, namespaceId, tableName, selector.column)
-	};
+function toAggregateProjection(contract, aggregates, namespaceId, tableName, selector) {
+	const { codec, input: inputCodec, lower } = resolveAggregate({
+		aggregates,
+		contract,
+		namespaceId,
+		tableName,
+		fn: selector.fn,
+		column: selector.column
+	});
+	const inputExpr = selector.column === void 0 ? void 0 : ColumnRef.of(tableName, selector.column);
 	return {
-		expr,
-		codec: void 0
+		expr: lower !== void 0 ? lower({
+			expr: inputExpr,
+			inputCodec
+		}) : new AggregateExpr(selector.fn, inputExpr),
+		codec
 	};
 }
 function validateGroupedComparable(value) {
@@ -655,7 +679,7 @@ function validateGroupedHavingExpr(expr) {
 		rawExpr: rejectHavingExpr
 	});
 }
-function compileAggregate(contract, namespaceId, tableName, filters, aggregateSpec) {
+function compileAggregate(contract, aggregates, namespaceId, tableName, filters, aggregateSpec) {
 	const entries = Object.entries(aggregateSpec);
 	if (entries.length === 0) throw ormError("ORM.AGGREGATE_SELECTOR_MISSING", "aggregate() requires at least one aggregation selector", { meta: {
 		method: "aggregate",
@@ -663,7 +687,7 @@ function compileAggregate(contract, namespaceId, tableName, filters, aggregateSp
 		tableName
 	} });
 	const projection = entries.map(([alias, selector]) => {
-		const { expr, codec } = toAggregateProjection(contract, namespaceId, tableName, selector);
+		const { expr, codec } = toAggregateProjection(contract, aggregates, namespaceId, tableName, selector);
 		return ProjectionItem.of(alias, expr, codec);
 	});
 	let ast = SelectAst.from(tableSourceForContract(contract, namespaceId, tableName)).withProjection(projection);
@@ -672,7 +696,7 @@ function compileAggregate(contract, namespaceId, tableName, filters, aggregateSp
 	const { params } = deriveParamsFromAst(ast);
 	return buildOrmQueryPlan(contract, ast, params);
 }
-function compileGroupedAggregate(contract, namespaceId, tableName, filters, groupByColumns, aggregateSpec, havingExpr) {
+function compileGroupedAggregate(contract, aggregates, namespaceId, tableName, filters, groupByColumns, aggregateSpec, havingExpr) {
 	if (groupByColumns.length === 0) throw ormError("ORM.GROUP_BY_FIELD_MISSING", "groupBy() requires at least one field", { meta: {
 		namespaceId,
 		tableName
@@ -684,7 +708,7 @@ function compileGroupedAggregate(contract, namespaceId, tableName, filters, grou
 		tableName
 	} });
 	const projection = [...groupByColumns.map((column) => ProjectionItem.of(column, ColumnRef.of(tableName, column), codecRefForStorageColumn(contract.storage, namespaceId, tableName, column))), ...entries.map(([alias, selector]) => {
-		const { expr, codec } = toAggregateProjection(contract, namespaceId, tableName, selector);
+		const { expr, codec } = toAggregateProjection(contract, aggregates, namespaceId, tableName, selector);
 		return ProjectionItem.of(alias, expr, codec);
 	})];
 	let ast = SelectAst.from(tableSourceForContract(contract, namespaceId, tableName)).withProjection(projection).withGroupBy(groupByColumns.map((column) => ColumnRef.of(tableName, column)));
@@ -1020,11 +1044,13 @@ function bindSelectAst(contract, ast) {
 *   correlated subquery, a combine branch, or the object a child row set is
 *   aggregated from. Its parts were made canonical at the level that produced
 *   them; this level only nests it.
-* - `native`: the value has no codec identity. An aggregate is the case that
-*   arises today: `COUNT(*)` and `SUM(col)` are computed, and the aggregate's
-*   own result type is not the column's codec. Native is what a value with no
-*   codec identity means, which is a different thing from defaulting a codec
-*   to identity — that, the project forbids.
+* - `native`: the value has no codec identity. The case that reaches it is an
+*   aggregate the target declares no overload for — SQLite computes `sum` over
+*   a text column from whatever leading numbers the rows held, and declines to
+*   type the result. Native is what a value with no codec identity means, which
+*   is a different thing from defaulting a codec to identity — that, the
+*   project forbids. An aggregate the target does declare carries the codec the
+*   registry resolved for it, like any other value.
 *
 * A document never carries a codec and a codec-bearing column is never a
 * document, so the first two cases cannot both apply.
@@ -1216,8 +1242,8 @@ function resolveChildTableSource(include, parentLocalRefs) {
 * Each nested include contributes a single projection item whose
 * expression is a correlated subquery.
 */
-function buildNestedIncludeProjections(contract, parentSource, includes) {
-	return includes.map((nested) => buildCorrelatedIncludeProjection(contract, parentSource, nested).projection);
+function buildNestedIncludeProjections(contract, aggregates, parentSource, includes) {
+	return includes.map((nested) => buildCorrelatedIncludeProjection(contract, aggregates, parentSource, nested).projection);
 }
 /**
 * The aliases a level's nested includes contribute. Each such subquery
@@ -1320,7 +1346,7 @@ function buildManyToManyJunctionArtifacts(parentLocalRefs, childTableRef, throug
 		junctionJoin: JoinAst.inner(TableSource.named(junctionTable, void 0, namespaceId), joinOn, false)
 	};
 }
-function buildIncludeChildRowsSelect(contract, parentSource, include) {
+function buildIncludeChildRowsSelect(contract, aggregates, parentSource, include) {
 	const childState = include.nested;
 	const parentLocalRefs = resolveParentLocalRefs(parentSource, include, localColumnsForRowInclude(include));
 	const childSource = resolveChildTableSource(include, parentLocalRefs);
@@ -1347,6 +1373,7 @@ function buildIncludeChildRowsSelect(contract, parentSource, include) {
 	}
 	if (childState.distinct !== void 0 && childState.distinct.length > 0 && childState.includes.length > 0) return buildDistinctNonLeafChildRowsSelect({
 		contract,
+		aggregates,
 		include,
 		childTableAlias,
 		childTableRef,
@@ -1359,7 +1386,7 @@ function buildIncludeChildRowsSelect(contract, parentSource, include) {
 	});
 	const polyJoinsAndProjection = buildChildPolymorphismJoinsAndProjection(contract, include, childTableAlias, childTableRef);
 	const scalarProjection = buildProjection(contract, include.relatedNamespaceId, include.relatedTableName, polyJoinsAndProjection.baseSelectedFields, childTableRef);
-	const nestedProjections = buildNestedIncludeProjections(contract, {
+	const nestedProjections = buildNestedIncludeProjections(contract, aggregates, {
 		baseTableName: include.relatedTableName,
 		tableRef: childTableRef,
 		variantColumnsProjected: false
@@ -1397,7 +1424,7 @@ function buildIncludeChildRowsSelect(contract, parentSource, include) {
 	};
 }
 function buildDistinctNonLeafChildRowsSelect(options) {
-	const { contract, include, childTableAlias, childTableRef, rowsAlias, childOrderBy, hiddenOrderProjection, aggregateOrderBy, whereExpr, junctionJoins } = options;
+	const { contract, aggregates, include, childTableAlias, childTableRef, rowsAlias, childOrderBy, hiddenOrderProjection, aggregateOrderBy, whereExpr, junctionJoins } = options;
 	const childState = include.nested;
 	const grandchildJoinColumns = Array.from(new Set(childState.includes.flatMap((nested) => nested.localTableName === include.relatedTableName ? localColumnsForRowInclude(nested) : [])));
 	const { selectedForQuery } = augmentSelectionForJoinColumns(childState.selectedFields, grandchildJoinColumns);
@@ -1433,7 +1460,7 @@ function buildDistinctNonLeafChildRowsSelect(options) {
 	if (childState.offset !== void 0) innerSelect = innerSelect.withOffset(childState.offset);
 	const distinctAlias = `${include.relationName}__distinct`;
 	const outerScalarProjection = buildProjection(contract, include.relatedNamespaceId, include.relatedTableName, visiblePolyProjection.baseSelectedFields, distinctAlias);
-	const outerNestedProjections = buildNestedIncludeProjections(contract, {
+	const outerNestedProjections = buildNestedIncludeProjections(contract, aggregates, {
 		baseTableName: include.relatedTableName,
 		tableRef: distinctAlias,
 		variantColumnsProjected: true
@@ -1481,7 +1508,15 @@ function buildDistinctNonLeafChildRowsSelect(options) {
 * `distinct`) is dropped at the SQL level since reordering does not
 * change which rows are aggregated.
 */
-function buildIncludeChildScalarSelect(contract, parentSource, include, scalar) {
+function buildIncludeChildScalarSelect(contract, aggregates, parentSource, include, scalar) {
+	const { codec: resultCodec, input: inputCodec, lower: resultLowering } = resolveAggregate({
+		aggregates,
+		contract,
+		namespaceId: include.relatedNamespaceId,
+		tableName: include.relatedTableName,
+		fn: scalar.fn,
+		column: scalar.column
+	});
 	const parentLocalRefs = resolveParentLocalRefs(parentSource, include, localColumnsForRowInclude(include));
 	const childSource = resolveChildTableSource(include, parentLocalRefs);
 	const childTableAlias = childSource.alias;
@@ -1507,8 +1542,8 @@ function buildIncludeChildScalarSelect(contract, parentSource, include, scalar)
 	const hasPagination = state.limit !== void 0 || state.offset !== void 0;
 	const hasDistinct = state.distinct !== void 0 && state.distinct.length > 0 || state.distinctOn !== void 0 && state.distinctOn.length > 0;
 	if (!(hasPagination || hasDistinct)) {
-		const aggregateExpr = buildIncludeAggregateExpr(scalar, childTableRef);
-		const jsonObjectExpr = JsonObjectExpr.fromEntries([JsonObjectExpr.entry("value", jsonEntryProjection(aggregateExpr, {}))]);
+		const aggregateExpr = buildIncludeAggregateExpr(scalar, childTableRef, resultLowering, inputCodec);
+		const jsonObjectExpr = JsonObjectExpr.fromEntries([JsonObjectExpr.entry("value", jsonEntryProjection(aggregateExpr, { codec: resultCodec }))]);
 		let select = SelectAst.from(tableSourceForContract(contract, include.relatedNamespaceId, include.relatedTableName, childTableAlias)).withProjection([ProjectionItem.of(include.relationName, jsonObjectExpr)]).withWhere(whereExpr);
 		if (junctionJoins.length > 0) select = select.withJoins(junctionJoins);
 		return select;
@@ -1533,21 +1568,17 @@ function buildIncludeChildScalarSelect(contract, parentSource, include, scalar)
 	} else if (remappedOrderBy !== void 0 && remappedOrderBy.length > 0) inner = inner.withOrderBy(remappedOrderBy);
 	if (state.limit !== void 0) inner = inner.withLimit(state.limit);
 	if (state.offset !== void 0) inner = inner.withOffset(state.offset);
-	const outerAggregateExpr = buildIncludeAggregateExpr(scalar, innerAlias);
-	const outerJsonObjectExpr = JsonObjectExpr.fromEntries([JsonObjectExpr.entry("value", jsonEntryProjection(outerAggregateExpr, {}))]);
+	const outerAggregateExpr = buildIncludeAggregateExpr(scalar, innerAlias, resultLowering, inputCodec);
+	const outerJsonObjectExpr = JsonObjectExpr.fromEntries([JsonObjectExpr.entry("value", jsonEntryProjection(outerAggregateExpr, { codec: resultCodec }))]);
 	return SelectAst.from(DerivedTableSource.as(innerAlias, inner)).withProjection([ProjectionItem.of(include.relationName, outerJsonObjectExpr)]);
 }
-function buildIncludeAggregateExpr(scalar, childTableRef) {
-	if (scalar.fn === "count") return AggregateExpr.count();
-	if (scalar.column === void 0) throw ormError("ORM.AGGREGATE_SELECTOR_INVALID", `Aggregate selector "${scalar.fn}" requires a column`, { meta: { fn: scalar.fn } });
-	const columnRef = ColumnRef.of(childTableRef, scalar.column);
-	switch (scalar.fn) {
-		case "sum": return AggregateExpr.sum(columnRef);
-		case "avg": return AggregateExpr.avg(columnRef);
-		case "min": return AggregateExpr.min(columnRef);
-		case "max": return AggregateExpr.max(columnRef);
-		default: return assertNever(scalar.fn);
-	}
+function buildIncludeAggregateExpr(scalar, childTableRef, lower, inputCodec) {
+	const expr = scalar.column === void 0 ? void 0 : ColumnRef.of(childTableRef, scalar.column);
+	if (lower !== void 0) return lower({
+		expr,
+		inputCodec
+	});
+	return new AggregateExpr(scalar.fn, expr);
 }
 /**
 * Build the inner SELECT for a `combine({ a, b, ... })` include.
@@ -1568,13 +1599,13 @@ function buildIncludeAggregateExpr(scalar, childTableRef) {
 * branch fan out naturally because the row builder is invoked with
 * a synthetic IncludeExpr whose `nested` is the branch's state.
 */
-function buildIncludeChildCombineSelect(contract, parentSource, include, branches) {
+function buildIncludeChildCombineSelect(contract, aggregates, parentSource, include, branches) {
 	const branchEntries = Object.entries(branches);
 	if (branchEntries.length === 0) throw ormError("ORM.INCLUDE_INVALID", `combine() include "${include.relationName}" has no branches`, { meta: { relation: include.relationName } });
 	const compiledBranches = branchEntries.map(([name, branch]) => ({
 		name,
 		alias: `${include.relationName}__combine__${name}`,
-		select: buildIncludeChildCombineBranchSelect(contract, parentSource, include, branch)
+		select: buildIncludeChildCombineBranchSelect(contract, aggregates, parentSource, include, branch)
 	}));
 	const jsonObjectExpr = JsonObjectExpr.fromEntries(compiledBranches.map((branch) => JsonObjectExpr.entry(branch.name, jsonEntryProjection(ColumnRef.of(branch.alias, include.relationName), { document: true }))));
 	const [firstBranch, ...restBranches] = compiledBranches;
@@ -1588,9 +1619,9 @@ function buildIncludeChildCombineSelect(contract, parentSource, include, branche
 * relation name. Dispatches to the standalone scalar / row builders
 * with the branch's state spliced into a synthetic IncludeExpr.
 */
-function buildIncludeChildCombineBranchSelect(contract, parentSource, include, branch) {
-	if (branch.kind === "scalar") return buildIncludeChildScalarSelect(contract, parentSource, include, branch.selector);
-	return buildIncludeChildRowsAggregateSelect(contract, parentSource, {
+function buildIncludeChildCombineBranchSelect(contract, aggregates, parentSource, include, branch) {
+	if (branch.kind === "scalar") return buildIncludeChildScalarSelect(contract, aggregates, parentSource, include, branch.selector);
+	return buildIncludeChildRowsAggregateSelect(contract, aggregates, parentSource, {
 		...include,
 		nested: branch.state,
 		scalar: void 0,
@@ -1603,24 +1634,24 @@ function buildIncludeChildCombineBranchSelect(contract, parentSource, include, b
 * name. Used by both the standalone row correlated-subquery path and
 * by combine's row branches.
 */
-function buildIncludeChildRowsAggregateSelect(contract, parentSource, include) {
-	const { childRows, childProjection, documentAliases, rowsAlias, aggregateOrderBy } = buildIncludeChildRowsSelect(contract, parentSource, include);
+function buildIncludeChildRowsAggregateSelect(contract, aggregates, parentSource, include) {
+	const { childRows, childProjection, documentAliases, rowsAlias, aggregateOrderBy } = buildIncludeChildRowsSelect(contract, aggregates, parentSource, include);
 	const jsonObjectExpr = JsonObjectExpr.fromEntries(childProjection.map((item) => JsonObjectExpr.entry(item.alias, jsonEntryProjection(ColumnRef.of(rowsAlias, item.alias), {
 		codec: item.codec,
 		document: documentAliases.has(item.alias)
 	}))));
 	return SelectAst.from(DerivedTableSource.as(rowsAlias, childRows)).withProjection([ProjectionItem.of(include.relationName, JsonArrayAggExpr.of(jsonEntryProjection(jsonObjectExpr, { document: true }), "emptyArray", aggregateOrderBy))]);
 }
-function buildCorrelatedIncludeProjection(contract, parentSource, include) {
+function buildCorrelatedIncludeProjection(contract, aggregates, parentSource, include) {
 	if (include.scalar) {
-		const scalarSelect = buildIncludeChildScalarSelect(contract, parentSource, include, include.scalar);
+		const scalarSelect = buildIncludeChildScalarSelect(contract, aggregates, parentSource, include, include.scalar);
 		return { projection: ProjectionItem.of(include.relationName, SubqueryExpr.of(scalarSelect)) };
 	}
 	if (include.combine) {
-		const combineSelect = buildIncludeChildCombineSelect(contract, parentSource, include, include.combine);
+		const combineSelect = buildIncludeChildCombineSelect(contract, aggregates, parentSource, include, include.combine);
 		return { projection: ProjectionItem.of(include.relationName, SubqueryExpr.of(combineSelect)) };
 	}
-	const aggregateQuery = buildIncludeChildRowsAggregateSelect(contract, parentSource, include);
+	const aggregateQuery = buildIncludeChildRowsAggregateSelect(contract, aggregates, parentSource, include);
 	return { projection: ProjectionItem.of(include.relationName, SubqueryExpr.of(aggregateQuery)) };
 }
 function buildSelectAst(contract, tableName, state, options) {
@@ -1697,7 +1728,7 @@ function compileSelect(contract, namespaceId, tableName, state, modelName) {
 	const { params } = deriveParamsFromAst(ast);
 	return buildOrmQueryPlan(contract, ast, params, state.annotations);
 }
-function compileSelectWithIncludes(contract, namespaceId, tableName, state, modelName) {
+function compileSelectWithIncludes(contract, aggregates, namespaceId, tableName, state, modelName) {
 	const includeJoins = [];
 	const includeProjection = [];
 	const topLevelWhere = buildStateWhere(contract, tableName, state, { namespaceId });
@@ -1721,7 +1752,7 @@ function compileSelectWithIncludes(contract, namespaceId, tableName, state, mode
 		variantColumnsProjected: false
 	};
 	for (const include of state.includes) {
-		const artifact = buildCorrelatedIncludeProjection(contract, parentSource, include);
+		const artifact = buildCorrelatedIncludeProjection(contract, aggregates, parentSource, include);
 		includeProjection.push(artifact.projection);
 	}
 	const ast = buildSelectAst(contract, tableName, {
@@ -1840,7 +1871,7 @@ function dispatchWithIncludes(options) {
 	const generator = async function* () {
 		const { scope, release } = await acquireRuntimeScope(runtime);
 		try {
-			const parentRowsRaw = await executeQueryPlan(scope, compileSelectWithIncludes(contract, namespaceId, tableName, state, modelName)).toArray();
+			const parentRowsRaw = await executeQueryPlan(scope, compileSelectWithIncludes(contract, context.aggregateDescriptors, namespaceId, tableName, state, modelName)).toArray();
 			if (parentRowsRaw.length === 0) return;
 			const polyInfo = resolvePolymorphismInfo(contract, namespaceId, modelName);
 			const parentRows = parentRowsRaw.map((row) => {
@@ -1938,7 +1969,7 @@ function buildIdentityInFilter(contract, namespaceId, tableName, identityColumns
 * declared shape (see `decodeCombineIncludePayload`).
 */
 async function decodeIncludePayload(contract, context, include, raw) {
-	if (include.scalar) return Promise.resolve(decodeScalarIncludePayload(include, include.scalar, raw));
+	if (include.scalar) return Promise.resolve(decodeScalarIncludePayload(contract, context, include, include.scalar, raw));
 	if (include.combine) return decodeCombineIncludePayload(contract, context, include, include.combine, raw);
 	const rawChildren = parseIncludedRows(include, raw);
 	const polyInfo = resolvePolymorphismInfo(contract, include.relatedNamespaceId, include.relatedModelName);
@@ -2012,6 +2043,7 @@ async function decodeIncludedColumnValue(ref, codecId, codec, value) {
 	}
 	return decodeIncludedJsonValue(ref, codecId, codec, value);
 }
+/** `ref` names the value for a decode failure; an aggregate names its relation where a column would name itself. */
 function decodeIncludedJsonValue(ref, codecId, codec, value) {
 	try {
 		return codec.decodeJson(blindCast(value));
@@ -2064,7 +2096,7 @@ async function decodeCombineIncludePayload(contract, context, include, branches,
 			scalar: void 0,
 			combine: void 0
 		}, branchRaw);
-		else result[branchName] = decodeScalarIncludePayload(include, branch.selector, branchRaw);
+		else result[branchName] = decodeScalarIncludePayload(contract, context, include, branch.selector, branchRaw);
 	}
 	return result;
 }
@@ -2097,8 +2129,9 @@ function describeEnvelopeShape(value) {
 * loudly naming the include relation rather than soft-handling.
 * Mirrors `parseCombineEnvelope`'s strict shape gate.
 *
-* Values are passed through unchanged — no JS-side `Number()` coercion
-* and no JS-side empty-relation defaulting. SQL semantics drive the
+* The value passes through its own codec — the one the planner projected it
+* under — because it arrived inside a JSON document, where a count past 2^53
+* would otherwise have been read as a rounded number. SQL semantics drive the
 * empty-relation case: `COUNT(*)` over an empty input set is `0`;
 * `SUM` / `AVG` / `MIN` / `MAX` over an empty input set return SQL
 * `NULL`, which surfaces as `null` here. The outer `raw === null`
@@ -2106,11 +2139,24 @@ function describeEnvelopeShape(value) {
 * dispatch the correlated subquery always produces a row, so the inner
 * envelope's `value` is always set by SQL.
 */
-function decodeScalarIncludePayload(include, scalar, raw) {
-	if (raw === null || raw === void 0) return emptyScalarResult(scalar.fn);
+function decodeScalarIncludePayload(contract, context, include, scalar, raw) {
+	if (raw === null || raw === void 0) return emptyAggregateResult(scalar.fn);
 	const parsed = parseIncludePayload(raw);
 	if (!isPlainObjectEnvelope(parsed)) throw new InternalError(`scalar() envelope for include "${include.relationName}" has unexpected shape (expected object, got ${describeEnvelopeShape(parsed)}); this indicates a planner or decoder bug.`);
-	return parsed["value"];
+	const value = parsed["value"];
+	if (value === null || value === void 0) return emptyAggregateResult(scalar.fn);
+	const codecRef = resolveAggregateOutputCodec({
+		aggregates: context.aggregateDescriptors,
+		contract,
+		namespaceId: include.relatedNamespaceId,
+		tableName: include.relatedTableName,
+		fn: scalar.fn,
+		column: scalar.column
+	});
+	return decodeIncludedJsonValue({
+		table: include.relatedTableName,
+		column: include.relationName
+	}, codecRef.codecId, context.contractCodecs.forCodecRef(codecRef), value);
 }
 function parseIncludedRows(include, value) {
 	if (value === null || value === void 0) return [];
@@ -2134,9 +2180,6 @@ function parseIncludePayload(value) {
 function coerceSingleQueryIncludeResult(rows, cardinality) {
 	return isToOneCardinality(cardinality) ? rows[0] ?? null : rows;
 }
-function emptyScalarResult(fn) {
-	return fn === "count" ? 0 : null;
-}
 function createMutationRowMapper(contract, namespaceId, modelName, variantName) {
 	const polyInfo = resolvePolymorphismInfo(contract, namespaceId, modelName);
 	return polyInfo ? (row) => mapPolymorphicRow(contract, namespaceId, modelName, polyInfo, row, variantName) : (row) => mapStorageRowToModelFields(contract, namespaceId, modelName, row);
@@ -2319,10 +2362,10 @@ var GroupedCollection = class GroupedCollection {
 			configure(meta);
 			if (meta.annotations.size > 0) annotationsMap = meta.annotations;
 		}
-		const compiled = mergeAnnotations(compileGroupedAggregate(this.contract, this.namespaceId, this.tableName, this.baseFilters, this.groupByColumns, aggregateSpec, combineWhereExprs(this.havingFilters)), annotationsMap);
+		const compiled = mergeAnnotations(compileGroupedAggregate(this.contract, this.ctx.context.aggregateDescriptors, this.namespaceId, this.tableName, this.baseFilters, this.groupByColumns, aggregateSpec, combineWhereExprs(this.havingFilters)), annotationsMap);
 		return (await executeQueryPlan(this.ctx.runtime, compiled).toArray()).map((row) => {
 			const mapped = mapStorageRowToModelFields(this.contract, this.namespaceId, this.modelName, row);
-			for (const [alias, selector] of aggregateEntries) mapped[alias] = coerceAggregateValue(selector.fn, row[alias]);
+			for (const [alias] of aggregateEntries) mapped[alias] = row[alias];
 			return mapped;
 		});
 	}
@@ -2371,17 +2414,6 @@ function createHavingComparisonMethods(metric) {
 		}
 	};
 }
-function coerceAggregateValue(fn, value) {
-	if (value === null) return null;
-	if (value === void 0) return fn === "count" ? 0 : null;
-	if (typeof value === "number") return value;
-	if (typeof value === "bigint") return Number(value);
-	if (typeof value === "string") {
-		const numeric = Number(value);
-		return Number.isNaN(numeric) ? value : numeric;
-	}
-	return value;
-}
 const aggregateFns = /* @__PURE__ */ new Set([
 	"count",
 	"sum",
@@ -2427,7 +2459,91 @@ function isCollectionState(value) {
 function hasThrough$1(relation) {
 	return relation.through !== void 0;
 }
+var SqlTableBinding = class SqlTableBinding {
+	#storage;
+	#reference;
+	constructor(storage, reference) {
+		this.#storage = Object.freeze({ ...storage });
+		this.#reference = reference;
+		Object.freeze(this);
+	}
+	static unaliased(storage) {
+		return new SqlTableBinding(storage, storage.tableName);
+	}
+	static aliased(storage, alias) {
+		return new SqlTableBinding(storage, alias);
+	}
+	column(columnName) {
+		return ColumnRef.of(this.#reference, columnName);
+	}
+	tableSource(contract) {
+		return tableSourceForContract(contract, this.#storage.namespaceId, this.#storage.tableName, this.#reference);
+	}
+	isReferencedAs(candidate) {
+		return this.#reference === candidate;
+	}
+	isStoredAt(namespaceId, tableName) {
+		return this.#storage.namespaceId === namespaceId && this.#storage.tableName === tableName;
+	}
+};
+var ModelAccessorScope = class ModelAccessorScope {
+	current;
+	#visibleBindings;
+	#aliasCounter;
+	constructor(current, visibleBindings, aliasCounter) {
+		this.current = current;
+		this.#visibleBindings = Object.freeze([...visibleBindings]);
+		this.#aliasCounter = aliasCounter;
+		Object.freeze(this);
+	}
+	static root(namespaceId, tableName) {
+		const binding = SqlTableBinding.unaliased({
+			namespaceId,
+			tableName
+		});
+		return new ModelAccessorScope(binding, [binding], { nextId: 1 });
+	}
+	forRelation(namespaceId, tableName) {
+		const binding = this.#allocateBinding(namespaceId, tableName, "rel");
+		return new ModelAccessorScope(binding, [...this.#visibleBindings, binding], this.#aliasCounter);
+	}
+	forManyToManyRelation(childNamespaceId, childTableName, junctionNamespaceId, junctionTableName) {
+		const initialChildScope = this.forRelation(childNamespaceId, childTableName);
+		const junctionBinding = initialChildScope.#allocateBinding(junctionNamespaceId, junctionTableName, "junction");
+		return {
+			childScope: new ModelAccessorScope(initialChildScope.current, [...initialChildScope.#visibleBindings, junctionBinding], this.#aliasCounter),
+			junctionBinding
+		};
+	}
+	forJoinedSource(namespaceId, tableName) {
+		if (this.current.isStoredAt(namespaceId, tableName)) return this;
+		const binding = SqlTableBinding.unaliased({
+			namespaceId,
+			tableName
+		});
+		return new ModelAccessorScope(binding, [...this.#visibleBindings, binding], this.#aliasCounter);
+	}
+	#allocateBinding(namespaceId, tableName, aliasKind) {
+		const storage = {
+			namespaceId,
+			tableName
+		};
+		if (!this.#visibleBindings.some((binding) => binding.isReferencedAs(tableName))) return SqlTableBinding.unaliased(storage);
+		return SqlTableBinding.aliased(storage, this.#allocateAlias(aliasKind));
+	}
+	#allocateAlias(kind) {
+		while (true) {
+			const alias = `__orm_${kind}_${this.#aliasCounter.nextId}`;
+			this.#aliasCounter.nextId += 1;
+			if (!this.#visibleBindings.some((binding) => binding.isReferencedAs(alias))) return alias;
+		}
+	}
+};
 function createModelAccessor(context, namespaceId, modelName, variantName) {
+	const tableName = resolveModelTableName(context.contract, namespaceId, modelName);
+	return createModelAccessorInScope(context, namespaceId, modelName, variantName, ModelAccessorScope.root(namespaceId, tableName));
+}
+function createModelAccessorInScope(context, namespaceId, modelName, variantName, scope) {
 	const contract = context.contract;
 	const fieldToColumn = getFieldToColumnMap(contract, namespaceId, modelName);
 	const tableName = resolveModelTableName(contract, namespaceId, modelName);
@@ -2461,19 +2577,20 @@ function createModelAccessor(context, namespaceId, modelName, variantName) {
 		if (typeof prop !== "string") return;
 		if (variantCoordinates) {
 			const variantRelation = variantCoordinates.relations[prop];
-			if (variantRelation) return createRelationFilterAccessor(context, namespaceId, variantCoordinates.name, variantCoordinates.tableName, prop, variantRelation);
+			if (variantRelation) return createRelationFilterAccessor(context, namespaceId, variantCoordinates.name, scope.forJoinedSource(namespaceId, variantCoordinates.tableName), variantRelation);
 		}
 		const relation = modelRelations[prop];
-		if (relation) return createRelationFilterAccessor(context, namespaceId, modelName, tableName, prop, relation);
+		if (relation) return createRelationFilterAccessor(context, namespaceId, modelName, scope, relation);
 		const variantField = variantFieldColumns[prop];
 		const resolvedTable = variantField?.table ?? tableName;
+		const fieldBinding = scope.forJoinedSource(namespaceId, resolvedTable).current;
 		const columnName = variantField?.column ?? fieldToColumn[prop] ?? prop;
 		const column = resolveColumn(contract, namespaceId, resolvedTable, columnName);
 		if (!column) return;
 		const traits = context.codecDescriptors.descriptorFor(column.codecId)?.traits ?? [];
 		const operations = opsByCodecId.get(column.codecId) ?? [];
 		const codec = codecRefForStorageColumn(contract.storage, namespaceId, resolvedTable, columnName);
-		return createScalarFieldAccessor(resolvedTable, columnName, column.codecId, column.nullable, codec, traits, operations, context);
+		return createScalarFieldAccessor(fieldBinding, columnName, column.codecId, column.nullable, codec, traits, operations, context);
 	} }));
 }
 function resolveColumn(contract, namespaceId, tableName, columnName) {
@@ -2490,8 +2607,8 @@ function resolveColumn(contract, namespaceId, tableName, columnName) {
 		nullable: column.nullable
 	};
 }
-function createScalarFieldAccessor(tableName, columnName, codecId, nullable, codec, traits, operations, context) {
-	const column = ColumnRef.of(tableName, columnName);
+function createScalarFieldAccessor(tableBinding, columnName, codecId, nullable, codec, traits, operations, context) {
+	const column = tableBinding.column(columnName);
 	const comparisonEntries = [];
 	for (const [name, meta] of Object.entries(COMPARISON_METHODS_META)) {
 		if (meta.traits.some((t) => !traits.includes(t))) continue;
@@ -2526,42 +2643,41 @@ function createExtensionMethodFactory(selfExpr, entry, context) {
 		return methods;
 	};
 }
-function createRelationFilterAccessor(context, parentNamespaceId, parentModelName, parentTableName, relationName, relation) {
+function createRelationFilterAccessor(context, parentNamespaceId, parentModelName, parentScope, relation) {
 	const relatedTableName = resolveModelTableName(context.contract, relation.toNamespace, relation.to);
 	return {
-		some: (predicate) => buildExistsExpr(context, parentNamespaceId, parentModelName, parentTableName, relatedTableName, relationName, relation, {
+		some: (predicate) => buildExistsExpr(context, parentNamespaceId, parentModelName, parentScope, relatedTableName, relation, {
 			mode: "some",
 			predicate
 		}),
-		every: (predicate) => buildExistsExpr(context, parentNamespaceId, parentModelName, parentTableName, relatedTableName, relationName, relation, {
+		every: (predicate) => buildExistsExpr(context, parentNamespaceId, parentModelName, parentScope, relatedTableName, relation, {
 			mode: "every",
 			predicate
 		}),
-		none: (predicate) => buildExistsExpr(context, parentNamespaceId, parentModelName, parentTableName, relatedTableName, relationName, relation, {
+		none: (predicate) => buildExistsExpr(context, parentNamespaceId, parentModelName, parentScope, relatedTableName, relation, {
 			mode: "none",
 			predicate
 		})
 	};
 }
-function buildExistsExpr(context, parentNamespaceId, parentModelName, parentTableName, relatedTableName, relationName, relation, options) {
-	if (hasThrough$1(relation)) return buildManyToManyExistsExpr(context, parentNamespaceId, parentModelName, parentTableName, relatedTableName, relationName, relation, options);
-	const filterPlan = planRelationFilterMode(buildJoinWhere(context.contract, parentNamespaceId, parentModelName, parentTableName, relatedTableName, relation), toRelationWhereExpr(context, relation.toNamespace, relation.to, options.predicate), options.mode);
+function buildExistsExpr(context, parentNamespaceId, parentModelName, parentScope, relatedTableName, relation, options) {
+	if (hasThrough$1(relation)) return buildManyToManyExistsExpr(context, parentNamespaceId, parentModelName, parentScope, relatedTableName, relation, options);
+	const childScope = parentScope.forRelation(relation.toNamespace, relatedTableName);
+	const filterPlan = planRelationFilterMode(buildJoinWhere(context.contract, parentNamespaceId, parentModelName, parentScope.current, childScope.current, relation), toRelationWhereExpr(context, relation.toNamespace, relation.to, options.predicate, childScope), options.mode);
 	if (filterPlan.kind === "constantTrue") return AndExpr.true();
 	const selectProjectionColumn = firstTargetColumn(context.contract, relation) ?? "id";
-	const subquery = SelectAst.from(tableSourceForContract(context.contract, relation.toNamespace, relatedTableName)).withProjection([ProjectionItem.of("_exists", ColumnRef.of(relatedTableName, selectProjectionColumn))]).withWhere(filterPlan.where);
+	const subquery = SelectAst.from(childScope.current.tableSource(context.contract)).withProjection([ProjectionItem.of("_exists", childScope.current.column(selectProjectionColumn))]).withWhere(filterPlan.where);
 	return filterPlan.notExists ? ExistsExpr.notExists(subquery) : ExistsExpr.exists(subquery);
 }
-function buildManyToManyExistsExpr(context, parentNamespaceId, parentModelName, parentTableName, relatedTableName, relationName, relation, options) {
+function buildManyToManyExistsExpr(context, parentNamespaceId, parentModelName, parentScope, relatedTableName, relation, options) {
 	const { through } = relation;
-	const junctionTable = through.table;
-	const relatedTableAlias = parentNamespaceId === relation.toNamespace && parentTableName === relatedTableName ? `${relationName}__child` : void 0;
-	const relatedTableRef = relatedTableAlias ?? relatedTableName;
-	const junctionJoinOn = buildPairedColumnExprs(junctionTable, through.childColumns, relatedTableRef, through.targetColumns);
+	const { childScope, junctionBinding } = parentScope.forManyToManyRelation(relation.toNamespace, relatedTableName, through.namespaceId, through.table);
+	const junctionJoinOn = buildPairedColumnExprs(junctionBinding, through.childColumns, childScope.current, through.targetColumns);
 	const parentLocalColumns = relation.on.localFields.map((field) => resolveFieldToColumn(context.contract, parentNamespaceId, parentModelName, field));
-	const filterPlan = planRelationFilterMode(buildPairedColumnExprs(junctionTable, through.parentColumns, parentTableName, parentLocalColumns), remapColumnRefs(relatedTableName, relatedTableRef, toRelationWhereExpr(context, relation.toNamespace, relation.to, options.predicate)), options.mode);
+	const filterPlan = planRelationFilterMode(buildPairedColumnExprs(junctionBinding, through.parentColumns, parentScope.current, parentLocalColumns), toRelationWhereExpr(context, relation.toNamespace, relation.to, options.predicate, childScope), options.mode);
 	if (filterPlan.kind === "constantTrue") return AndExpr.true();
 	const firstTargetCol = firstJoinColumn(through.targetColumns, "targetColumns");
-	const subquery = SelectAst.from(tableSourceForContract(context.contract, relation.toNamespace, relatedTableName, relatedTableAlias)).withJoins([JoinAst.inner(TableSource.named(junctionTable, void 0, through.namespaceId), junctionJoinOn)]).withProjection([ProjectionItem.of("_exists", ColumnRef.of(relatedTableRef, firstTargetCol))]).withWhere(filterPlan.where);
+	const subquery = SelectAst.from(childScope.current.tableSource(context.contract)).withJoins([JoinAst.inner(junctionBinding.tableSource(context.contract), junctionJoinOn)]).withProjection([ProjectionItem.of("_exists", childScope.current.column(firstTargetCol))]).withWhere(filterPlan.where);
 	return filterPlan.notExists ? ExistsExpr.notExists(subquery) : ExistsExpr.exists(subquery);
 }
 function planRelationFilterMode(joinWhere, childWhere, mode) {
@@ -2584,10 +2700,6 @@ function planRelationFilterMode(joinWhere, childWhere, mode) {
 		where: childWhere ? and(joinWhere, childWhere) : joinWhere
 	};
 }
-function remapColumnRefs(tableName, tableRef, expr) {
-	if (!expr || tableName === tableRef) return expr;
-	return expr.rewrite({ columnRef: (column) => column.table === tableName ? ColumnRef.of(tableRef, column.column) : column });
-}
 function firstJoinColumn(columns, label) {
 	const first = columns[0];
 	if (!first) throw new InternalError(`Relation metadata is missing ${label}`);
@@ -2601,14 +2713,14 @@ function buildPairedColumnExprs(leftTable, leftColumns, rightTable, rightColumns
 		const left = leftColumns[i];
 		const right = rightColumns[i];
 		if (!left || !right) throw new InternalError(`Relation metadata is missing a join column pair at index ${i}`);
-		exprs.push(BinaryExpr.eq(ColumnRef.of(leftTable, left), ColumnRef.of(rightTable, right)));
+		exprs.push(BinaryExpr.eq(leftTable.column(left), rightTable.column(right)));
 	}
 	if (exprs.length === 1 && exprs[0]) return exprs[0];
 	return and(...exprs);
 }
-function toRelationWhereExpr(context, relatedNamespaceId, relatedModelName, predicate) {
+function toRelationWhereExpr(context, relatedNamespaceId, relatedModelName, predicate, scope) {
 	if (!predicate) return;
-	const accessor = createModelAccessor(context, relatedNamespaceId, relatedModelName);
+	const accessor = createModelAccessorInScope(context, relatedNamespaceId, relatedModelName, void 0, scope);
 	if (typeof predicate === "function") return predicate(accessor);
 	const exprs = [];
 	for (const [fieldName, value] of Object.entries(predicate)) {
@@ -2633,7 +2745,7 @@ function toRelationWhereExpr(context, relatedNamespaceId, relatedModelName, pred
 	if (exprs.length === 0) return;
 	return exprs.length === 1 ? exprs[0] : and(...exprs);
 }
-function buildJoinWhere(contract, parentNamespaceId, parentModelName, parentTableName, relatedTableName, relation) {
+function buildJoinWhere(contract, parentNamespaceId, parentModelName, parentTable, relatedTable, relation) {
 	const localFields = relation.on?.localFields ?? [];
 	const targetFields = relation.on?.targetFields ?? [];
 	const joinExprs = [];
@@ -2644,7 +2756,7 @@ function buildJoinWhere(contract, parentNamespaceId, parentModelName, parentTabl
 		if (!localField || !targetField) continue;
 		const localColumn = resolveFieldToColumn(contract, parentNamespaceId, parentModelName, localField);
 		const targetColumn = resolveFieldToColumn(contract, relation.toNamespace, relation.to, targetField);
-		joinExprs.push(BinaryExpr.eq(ColumnRef.of(relatedTableName, targetColumn), ColumnRef.of(parentTableName, localColumn)));
+		joinExprs.push(BinaryExpr.eq(relatedTable.column(targetColumn), parentTable.column(localColumn)));
 	}
 	if (joinExprs.length === 0) throw new InternalError("Relation metadata is missing join columns");
 	const firstExpr = joinExprs[0];
@@ -3411,7 +3523,7 @@ var Collection = class Collection {
 	*   .where({ published: true })
 	*   .groupBy('userId')
 	*   .aggregate((agg) => ({ count: agg.count(), totalViews: agg.sum('views') }));
-	* // [{ userId: 1, count: 3, totalViews: 120 }, ...]
+	* // [{ userId: 1, count: 3n, totalViews: 120n }, ...]
 	* ```
 	*/
 	groupBy(...fields) {
@@ -3434,7 +3546,7 @@ var Collection = class Collection {
 	*
 	* ```typescript
 	* const users = await db.orm.User.include('posts', (posts) => posts.count()).all();
-	* // each user row: { ...user, posts: number }
+	* // each user row: { ...user, posts: bigint }
 	* ```
 	*/
 	count() {
@@ -3449,7 +3561,7 @@ var Collection = class Collection {
 	*
 	* ```typescript
 	* const users = await db.orm.User.include('posts', (posts) => posts.sum('views')).all();
-	* // each user row: { ...user, posts: number | null }
+	* // each user row: { ...user, posts: bigint | null } — an int4 column's sum widens to int8
 	* ```
 	*/
 	sum(field) {
@@ -3465,7 +3577,7 @@ var Collection = class Collection {
 	*
 	* ```typescript
 	* const users = await db.orm.User.include('posts', (posts) => posts.avg('views')).all();
-	* // each user row: { ...user, posts: number | null }
+	* // each user row: { ...user, posts: string | null } — PostgreSQL averages integers as numeric
 	* ```
 	*/
 	avg(field) {
@@ -3520,7 +3632,7 @@ var Collection = class Collection {
 	* ).all();
 	* // each user row: {
 	* //   ...user,
-	* //   posts: { recent: Post[]; total: number; averageViews: number | null };
+	* //   posts: { recent: Post[]; total: bigint; averageViews: string | null };
 	* // }
 	* ```
 	*/
@@ -3692,7 +3804,7 @@ var Collection = class Collection {
 	*     averageViews: agg.avg('views'),
 	*     maxViews: agg.max('views'),
 	*   }));
-	* // { total: 42, averageViews: 17.3, maxViews: 9001 }
+	* // { total: 42n, averageViews: '17.3000000000000000', maxViews: 9001 }
 	* ```
 	*
 	* Accepts an optional `configure` callback that receives a
@@ -3712,8 +3824,11 @@ var Collection = class Collection {
 			alias
 		} });
 		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "read", "aggregate");
-		const compiled = mergeAnnotations(compileAggregate(this.contract, this.namespaceId, this.tableName, this.state.filters, aggregateSpec), annotationsMap);
-		return normalizeAggregateResult(aggregateSpec, (await executeQueryPlan(this.ctx.runtime, compiled).toArray())[0] ?? {});
+		const compiled = mergeAnnotations(compileAggregate(this.contract, this.ctx.context.aggregateDescriptors, this.namespaceId, this.tableName, this.state.filters, aggregateSpec), annotationsMap);
+		const row = (await executeQueryPlan(this.ctx.runtime, compiled).toArray())[0] ?? {};
+		const result = {};
+		for (const [alias, selector] of entries) result[alias] = row[alias] ?? emptyAggregateResult(selector.fn);
+		return blindCast(result);
 	}
 	async create(data, configure) {
 		assertReturningCapability(this.contract, "create()");
@@ -4032,9 +4147,10 @@ var Collection = class Collection {
 		} });
 	}
 	/**
-	* Write terminal: update matching rows and return the first one (or
-	* `null` when no row matched). Requires a prior `.where(...)` —
-	* calling `update(...)` on an unfiltered collection is a type error.
+	* Write terminal: update a single matching row — the first one the
+	* filter matches — and return it (or `null` when no row matched).
+	* Requires a prior `.where(...)` — calling `update(...)` on an
+	* unfiltered collection is a type error.
 	*
 	* Related rows can be created or relinked through relation
 	* callbacks on parent/child-owned relations (one-to-one or
@@ -4175,9 +4291,10 @@ var Collection = class Collection {
 		return matchingRows.length;
 	}
 	/**
-	* Write terminal: delete matching rows and return the first deleted
-	* row (or `null` when no row matched). Requires a prior `.where(...)`
-	* — calling `delete()` on an unfiltered collection is a type error.
+	* Write terminal: delete a single matching row — the first one the
+	* filter matches — and return it (or `null` when no row matched).
+	* Requires a prior `.where(...)` — calling `delete()` on an
+	* unfiltered collection is a type error.
 	*
 	* ```typescript
 	* const deleted = await db.orm.User.where({ id: 1 }).delete();