@prisma/orm-family-sql 0.16.0 → 0.17.0-dev.2

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,32 +1508,51 @@ 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) {
-	const parentLocalRefs = resolveParentLocalRefs(parentSource, include, [include.localColumn]);
-	const parentLocalRef = parentLocalRefs[0];
-	assertDefined(parentLocalRef, `Include '${include.relationName}' has no parent-local column ref`);
+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;
 	const childTableRef = childSource.tableRef;
 	const state = scalar.state;
-	const joinExpr = BinaryExpr.eq(ColumnRef.of(childTableRef, include.targetColumn), parentLocalRef);
 	const childWhere = buildStateWhere(contract, childTableRef, state, {
 		filterTableName: include.relatedTableName,
 		namespaceId: include.relatedNamespaceId
 	});
-	const whereExpr = childWhere ? AndExpr.of([joinExpr, childWhere]) : joinExpr;
+	let whereExpr;
+	let junctionJoins = [];
+	if (include.through !== void 0) {
+		const artifacts = buildManyToManyJunctionArtifacts(parentLocalRefs, childTableRef, include.through);
+		whereExpr = childWhere ? AndExpr.of([artifacts.whereExpr, childWhere]) : artifacts.whereExpr;
+		junctionJoins = [artifacts.junctionJoin];
+	} else {
+		const parentLocalRef = parentLocalRefs[0];
+		assertDefined(parentLocalRef, `Include '${include.relationName}' has no parent-local column ref`);
+		const joinExpr = BinaryExpr.eq(ColumnRef.of(childTableRef, include.targetColumn), parentLocalRef);
+		whereExpr = childWhere ? AndExpr.of([joinExpr, childWhere]) : joinExpr;
+	}
 	const remappedOrderBy = childTableAlias && state.orderBy ? state.orderBy.map((item) => item.rewrite(createTableRefRemapper(include.relatedTableName, childTableRef))) : state.orderBy;
 	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, {}))]);
-		return SelectAst.from(tableSourceForContract(contract, include.relatedNamespaceId, include.relatedTableName, childTableAlias)).withProjection([ProjectionItem.of(include.relationName, jsonObjectExpr)]).withWhere(whereExpr);
+		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;
 	}
 	const innerAlias = `${include.relationName}__scalar`;
 	const hiddenOrderProjection = state.distinct !== void 0 && state.distinct.length > 0 && remappedOrderBy !== void 0 && remappedOrderBy.length > 0 ? remappedOrderBy.map((item, index) => ProjectionItem.of(`${include.relationName}__order_${index}`, item.expr)) : [];
 	const innerProjection = [...scalar.column !== void 0 ? [ProjectionItem.of(scalar.column, ColumnRef.of(childTableRef, scalar.column))] : [ProjectionItem.of("__row", LiteralExpr.of(1))], ...hiddenOrderProjection];
 	let inner = SelectAst.from(tableSourceForContract(contract, include.relatedNamespaceId, include.relatedTableName, childTableAlias)).withProjection(innerProjection).withWhere(whereExpr);
+	if (junctionJoins.length > 0) inner = inner.withJoins(junctionJoins);
 	if (state.distinctOn !== void 0 && state.distinctOn.length > 0) {
 		inner = inner.withDistinctOn(state.distinctOn.map((column) => ColumnRef.of(childTableRef, column)));
 		if (remappedOrderBy !== void 0 && remappedOrderBy.length > 0) inner = inner.withOrderBy(remappedOrderBy);
@@ -1522,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.
@@ -1557,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;
@@ -1577,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,
@@ -1592,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) {
@@ -1686,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 });
@@ -1710,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, {
@@ -1829,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) => {
@@ -1927,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);
@@ -2001,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));
@@ -2053,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;
 }
@@ -2086,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`
@@ -2095,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 [];
@@ -2123,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);
@@ -2308,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;
 		});
 	}
@@ -2360,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",
@@ -3400,7 +3443,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) {
@@ -3423,7 +3466,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() {
@@ -3438,7 +3481,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) {
@@ -3454,7 +3497,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) {
@@ -3509,7 +3552,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 };
 	* // }
 	* ```
 	*/
@@ -3681,7 +3724,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
@@ -3701,8 +3744,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()");