@prisma/orm-family-sql 8.0.0-rc.16-dev.7 → 8.0.0-rc.16-dev.9

package/dist/orm-client.mjs

@@ -2784,1389 +2784,1389 @@ function assertFieldHasEqualityTrait(context, namespaceId, modelName, fieldName)
 		trait: "equality"
 	} });
 }
-function hasThrough$1(relation) {
-	return relation.through !== void 0;
+function nullability(nullable) {
+	return nullable ? "may be null" : "is never null";
 }
-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
+function isFieldBuilder(value) {
+	return "build" in value && typeof value.build === "function";
+}
+function isListMultiplicity(value) {
+	return typeof value === "object" && value !== null && "elementNullable" in value && typeof value.elementNullable === "boolean";
+}
+function isMultiplicity(value) {
+	return value === void 0 || value === false || isListMultiplicity(value);
+}
+function isFieldSpec(value) {
+	return "codecId" in value && typeof value.codecId === "string" && "nullable" in value && typeof value.nullable === "boolean" && (!("many" in value) || isMultiplicity(value.many));
+}
+function multiplicity(many) {
+	return isListMultiplicity(many) ? { elementNullable: many.elementNullable } : false;
+}
+const FIELD_DECLARATION_FIX = "Declare each field with a field builder, such as field.temporal.timestamptz().optional(), or with { codecId, nullable }. Declare a list with .many() or many: { elementNullable: false }, or, when its elements may be null, with .many({ elementsNullable: true }) or many: { elementNullable: true }.";
+function declaredFieldSpec(name, declaration) {
+	if (typeof declaration === "object" && declaration !== null && isFieldBuilder(declaration)) {
+		const built = declaration.build();
+		const descriptor = typeof built === "object" && built !== null && "descriptor" in built ? built.descriptor : void 0;
+		const nullable = typeof built === "object" && built !== null && "nullable" in built ? built.nullable : void 0;
+		if (typeof descriptor !== "object" || descriptor === null || !("codecId" in descriptor) || typeof descriptor.codecId !== "string" || typeof nullable !== "boolean") throw ormError("ORM.ARGUMENT_INVALID", `Cannot define the fragment: the field builder for ${name} names no column type`, {
+			why: "A fragment for any model matches each declared field by its codec and nullability, and this builder refers to a named type instead of a column type.",
+			fix: "Declare the field with a builder that has a column type, such as field.text() or field.column(textColumn), or with { codecId, nullable }.",
+			meta: { field: name }
 		});
-		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
+		const many = typeof built === "object" && built !== null && "many" in built && built.many;
+		if (!isMultiplicity(many)) throw ormError("ORM.ARGUMENT_INVALID", `Cannot define the fragment: the field builder for ${name} builds a many that is not false or { elementNullable }`, {
+			why: `A field builder's build() returns many as false or undefined for one value, or as { elementNullable } with a boolean elementNullable for a list; received ${describeReceived(many)} for ${name}.`,
+			fix: FIELD_DECLARATION_FIX,
+			meta: { field: name }
 		});
-		return new ModelAccessorScope(binding, [...this.#visibleBindings, binding], this.#aliasCounter);
-	}
-	#allocateBinding(namespaceId, tableName, aliasKind) {
-		const storage = {
-			namespaceId,
-			tableName
+		return {
+			codecId: descriptor.codecId,
+			nullable,
+			many: multiplicity(many)
 		};
-		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);
-	const modelRelations = resolveModelRelations(contract, namespaceId, modelName);
-	const variantFieldColumns = variantName ? resolveVariantFieldColumns(contract, namespaceId, modelName, variantName) : {};
-	const variantCoordinates = variantName ? {
-		name: variantName,
-		relations: resolveModelRelations(contract, namespaceId, variantName),
-		tableName: resolvePolymorphismInfo(contract, namespaceId, modelName)?.variants.get(variantName)?.table ?? tableName
-	} : void 0;
-	const opsByCodecId = /* @__PURE__ */ new Map();
-	function registerOp(codecId, op) {
-		let existing = opsByCodecId.get(codecId);
-		if (!existing) {
-			existing = [];
-			opsByCodecId.set(codecId, existing);
-		}
-		existing.push(op);
-	}
-	for (const [name, entry] of Object.entries(context.queryOperations.entries())) {
-		const op = [name, entry];
-		const self = entry.self;
-		if (!self) continue;
-		if (self.codecId !== void 0) registerOp(self.codecId, op);
-		else if (self.traits !== void 0) for (const descriptor of context.codecDescriptors.values()) {
-			const descriptorTraits = descriptor.traits;
-			if (self.traits.every((t) => descriptorTraits.includes(t))) registerOp(descriptor.codecId, op);
-		}
 	}
-	return blindCast(new Proxy({}, { get(_target, prop) {
-		if (typeof prop !== "string") return;
-		if (variantCoordinates) {
-			const variantRelation = variantCoordinates.relations[prop];
-			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, 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 = codecTraits(context, column.codecId);
-		const operations = opsByCodecId.get(column.codecId) ?? [];
-		const codec = codecRefForStorageColumn(contract.storage, namespaceId, resolvedTable, columnName);
-		return createScalarFieldAccessor(fieldBinding, columnName, column.codecId, column.nullable, codec, traits, operations, context);
-	} }));
+	if (typeof declaration === "object" && declaration !== null && isFieldSpec(declaration)) return {
+		codecId: declaration.codecId,
+		nullable: declaration.nullable,
+		many: multiplicity(declaration.many)
+	};
+	throw ormError("ORM.ARGUMENT_INVALID", `Cannot define the fragment: the declaration of field ${name} is not a field builder or { codecId, nullable }`, {
+		why: `Each field of a fragment is declared with a field builder or with an object that has a string codecId, a boolean nullable and, for a list, many: { elementNullable } with a boolean elementNullable; received ${describeReceived(declaration)} for ${name}.`,
+		fix: FIELD_DECLARATION_FIX,
+		meta: { field: name }
+	});
 }
-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;
-		comparisonEntries.push([name, meta.create(column, codec)]);
-	}
-	const accessor = blindCast({
-		returnType: {
-			codecId,
-			nullable,
-			codec
-		},
-		buildAst: () => column,
-		...Object.fromEntries(comparisonEntries)
+function declaredFieldSpecs(declarations) {
+	if (typeof declarations !== "object" || declarations === null || Array.isArray(declarations)) throw ormError("ORM.ARGUMENT_INVALID", "Cannot define the fragment: the fields are not an object", {
+		why: `The first argument of fragment maps the name of each field the fragment needs to its declaration; received ${describeReceived(declarations)}.`,
+		fix: FIELD_DECLARATION_FIX,
+		meta: { argument: "fields" }
 	});
-	for (const [name, entry] of operations) accessor[name] = createExtensionMethodFactory(accessor, entry, context);
-	return blindCast(accessor);
+	return Object.entries(declarations).map(([name, declaration]) => [name, declaredFieldSpec(name, declaration)]);
 }
-function createExtensionMethodFactory(selfExpr, entry, context) {
-	return (...args) => {
-		const result = blindCast(entry.impl)(selfExpr, ...args);
-		const returnCodecId = result.returnType.codecId;
-		const returnTraits = codecTraits(context, returnCodecId);
-		if (returnTraits.includes("boolean")) return result.buildAst();
-		const resultAst = result.buildAst();
-		const returnCodec = { codecId: returnCodecId };
-		const methods = {};
-		for (const [resultMethodName, meta] of Object.entries(COMPARISON_METHODS_META)) {
-			if (meta.traits.some((t) => !returnTraits.includes(t))) continue;
-			methods[resultMethodName] = meta.create(resultAst, returnCodec);
-		}
-		return methods;
-	};
+/** Throws `ORM.ARGUMENT_INVALID` unless `body`, the body of a fragment, is a function. */
+function assertFragmentBody(body) {
+	if (typeof body !== "function") throw ormError("ORM.ARGUMENT_INVALID", "Cannot define the fragment: the body is not a function", {
+		why: `The body of a fragment is a function that receives a collection and returns one; received ${describeReceived(body)}.`,
+		fix: "Pass a function, such as (rows) => rows.where(...).",
+		meta: { argument: "body" }
+	});
 }
-const RELATION_ACCESSOR_METHOD_NAMES = /* @__PURE__ */ new Set([
-	"some",
-	"every",
-	"none",
-	"count"
-]);
-function createRelationFilterAccessor(context, parentNamespaceId, parentModelName, parentScope, relation) {
-	const relatedTableName = resolveModelTableName(context.contract, relation.toNamespace, relation.to);
-	const correlate = () => correlateRelatedRows(context, parentNamespaceId, parentModelName, parentScope, relatedTableName, relation);
-	const filters = {
-		some: (predicate) => buildExistsExpr(context, relation, correlate(), "some", predicate),
-		every: (predicate) => buildExistsExpr(context, relation, correlate(), "every", predicate),
-		none: (predicate) => buildExistsExpr(context, relation, correlate(), "none", predicate)
-	};
-	if (isToOneCardinality(relation.cardinality)) return new Proxy(filters, { get(target, prop) {
-		if (typeof prop !== "string") return void 0;
-		if (Object.hasOwn(target, prop)) return Reflect.get(target, prop);
-		if (RELATION_ACCESSOR_METHOD_NAMES.has(prop)) return void 0;
-		return relatedOrderableField(context, relation, relatedTableName, correlate, prop);
-	} });
-	return {
-		...filters,
-		count: (predicate) => createOrderable(() => buildRelationCountExpr(context, relation, correlate(), predicate))
-	};
+function hasContract(ctx) {
+	return "context" in ctx && typeof ctx.context === "object" && ctx.context !== null && "contract" in ctx.context && typeof ctx.context.contract === "object" && ctx.context.contract !== null;
 }
-function createOrderable(buildExpr) {
-	return {
-		asc: (options) => checkedOrderByItem("asc", buildExpr(), options),
-		desc: (options) => checkedOrderByItem("desc", buildExpr(), options)
-	};
+function isModelCollection(value) {
+	return typeof value === "object" && value !== null && "ctx" in value && typeof value.ctx === "object" && value.ctx !== null && hasContract(value.ctx) && "modelName" in value && typeof value.modelName === "string" && "namespaceId" in value && typeof value.namespaceId === "string";
 }
-function relatedOrderableField(context, relation, relatedTableName, correlate, fieldName) {
-	const fieldToColumn = getFieldToColumnMap(context.contract, relation.toNamespace, relation.to);
-	if (!Object.hasOwn(fieldToColumn, fieldName)) return void 0;
-	const columnName = fieldToColumn[fieldName];
-	if (columnName === void 0) return void 0;
-	const column = resolveColumn(context.contract, relation.toNamespace, relatedTableName, columnName);
-	if (!column || !hasTrait(context, column.codecId, "order")) return void 0;
-	return createOrderable(() => {
-		const rows = correlate();
-		return SubqueryExpr.of(rows.source.withProjection([ProjectionItem.of(columnName, rows.childScope.current.column(columnName))]).withWhere(rows.correlation));
+/** Throws `ORM.ARGUMENT_INVALID` unless `value`, what a fragment is applied to, is a collection. */
+function assertFragmentReceiver(value) {
+	if (!isModelCollection(value)) throw ormError("ORM.ARGUMENT_INVALID", "Cannot apply the fragment: it was not given a collection", {
+		why: `A fragment is applied to a collection, such as db.orm.public.Post; received ${describeReceived(value)}.`,
+		fix: "Pass the fragment to with on a collection: collection.with(fragment).",
+		meta: { argument: "collection" }
 	});
 }
-function buildRelationCountExpr(context, relation, rows, predicate) {
-	const childWhere = toRelationWhereExpr(context, relation.toNamespace, relation.to, predicate, rows.childScope);
-	return SubqueryExpr.of(rows.source.withProjection([ProjectionItem.of("count", plainAggregateExpr("count", void 0))]).withWhere(childWhere ? and(rows.correlation, childWhere) : rows.correlation));
+/** Throws `ORM.ARGUMENT_INVALID` unless `value` is a collection of the model and namespace a fragment for one model was made from. */
+function assertModelFragmentReceiver(source, value) {
+	assertFragmentReceiver(value);
+	if (value.modelName !== source.modelName || value.namespaceId !== source.namespaceId) {
+		const made = `${source.namespaceId}.${source.modelName}`;
+		const given = `${value.namespaceId}.${value.modelName}`;
+		throw ormError("ORM.ARGUMENT_INVALID", `Cannot apply a fragment for ${made} to a collection of ${given}`, {
+			why: `The fragment was made with ${made}.fragment(...), and its body was written for that model.`,
+			fix: `Apply the fragment to a collection of ${made}, or make a fragment from ${given}.`,
+			meta: {
+				model: source.modelName,
+				namespace: source.namespaceId,
+				receivedModel: value.modelName,
+				receivedNamespace: value.namespaceId
+			}
+		});
+	}
 }
-function correlateRelatedRows(context, parentNamespaceId, parentModelName, parentScope, relatedTableName, relation) {
-	if (hasThrough$1(relation)) {
-		const { through } = relation;
-		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));
-		return {
-			childScope,
-			source: SelectAst.from(childScope.current.tableSource(context.contract)).withJoins([JoinAst.inner(junctionBinding.tableSource(context.contract), junctionJoinOn)]),
-			correlation: buildPairedColumnExprs(junctionBinding, through.parentColumns, parentScope.current, parentLocalColumns),
-			keyColumn: firstJoinColumn(through.targetColumns, "targetColumns")
-		};
+/** The model as error messages name it: with its namespace when the contract has more than one. */
+function modelLabel(collection) {
+	return Object.keys(collection.ctx.context.contract.domain.namespaces).length > 1 ? `${collection.namespaceId}.${collection.modelName}` : collection.modelName;
+}
+/** Throws `ORM.ARGUMENT_INVALID` unless `result`, what a fragment's body returned, is a collection of the receiver's model, namespace and class. */
+function assertFragmentResult(receiver, result) {
+	if (!(isModelCollection(result) && result.modelName === receiver.modelName && result.namespaceId === receiver.namespaceId && result instanceof receiver.constructor)) {
+		const label = modelLabel(receiver);
+		throw ormError("ORM.ARGUMENT_INVALID", `Cannot apply the fragment to ${label}: its body did not return a collection of ${label}`, {
+			why: `The body of a fragment for any model returns the collection it received, after where, orderBy, limit or offset; it returned ${isModelCollection(result) ? `a collection of ${modelLabel(result)}` : describeReceived(result)}.`,
+			fix: "Return the collection the body receives, or one made from it by calling its methods.",
+			meta: {
+				model: receiver.modelName,
+				namespace: receiver.namespaceId,
+				returned: isModelCollection(result) ? result.modelName : describeReceived(result)
+			}
+		});
 	}
-	const childScope = parentScope.forRelation(relation.toNamespace, relatedTableName);
-	return {
-		childScope,
-		source: SelectAst.from(childScope.current.tableSource(context.contract)),
-		correlation: buildJoinWhere(context.contract, parentNamespaceId, parentModelName, parentScope.current, childScope.current, relation),
-		keyColumn: firstTargetColumn(context.contract, relation) ?? "id"
-	};
 }
-function buildExistsExpr(context, relation, rows, mode, predicate) {
-	const childWhere = toRelationWhereExpr(context, relation.toNamespace, relation.to, predicate, rows.childScope);
-	const filterPlan = planRelationFilterMode(rows.correlation, childWhere, mode);
-	if (filterPlan.kind === "constantTrue") return AndExpr.true();
-	const subquery = rows.source.withProjection([ProjectionItem.of("_exists", rows.childScope.current.column(rows.keyColumn))]).withWhere(filterPlan.where);
-	return filterPlan.notExists ? ExistsExpr.notExists(subquery) : ExistsExpr.exists(subquery);
+function elementNullability(elementNullable) {
+	return elementNullable ? "may be null" : "are never null";
 }
-function planRelationFilterMode(joinWhere, childWhere, mode) {
-	if (mode === "every") {
-		if (!childWhere) return { kind: "constantTrue" };
-		return {
-			kind: "exists",
-			notExists: true,
-			where: and(joinWhere, not(childWhere))
+function sameMultiplicity(a, b) {
+	return a === false || b === false ? a === b : a.elementNullable === b.elementNullable;
+}
+function fieldShape(many) {
+	return many === false ? "holds one value" : `is a list whose elements ${elementNullability(many.elementNullable)}`;
+}
+function declarationFor(many) {
+	if (many === false) return "as one value, without .many() or many";
+	return many.elementNullable ? "as a list whose elements may be null, with .many({ elementsNullable: true }) or many: { elementNullable: true }" : "as a list whose elements are never null, with .many() or many: { elementNullable: false }";
+}
+function describeField(field) {
+	const value = `with codec ${field.codecId} that ${nullability(field.nullable)}`;
+	return field.many === false ? value : `${value} and whose elements ${elementNullability(field.many.elementNullable)}`;
+}
+function assertFragmentFields(collection, fields) {
+	const { contract } = collection.ctx.context;
+	const { modelName, namespaceId } = collection;
+	const label = modelLabel(collection);
+	const model = modelOf(contract, namespaceId, modelName);
+	for (const [name, spec] of fields) {
+		const declared = `The fragment was declared for models that have a ${spec.many === false ? "field" : "list field"} ${name} ${describeField(spec)}.`;
+		const meta = {
+			model: modelName,
+			namespace: namespaceId,
+			field: name,
+			codecId: spec.codecId,
+			nullable: spec.nullable,
+			many: spec.many
 		};
+		const modelFields = model?.fields ?? {};
+		if (!Object.hasOwn(modelFields, name)) throw ormError("ORM.FIELD_UNKNOWN", `Cannot apply a fragment to ${label}: it has no field ${name}`, {
+			why: declared,
+			fix: `Apply the fragment to a model that has a field ${name}, or remove ${name} from the declaration in the fragment.`,
+			meta
+		});
+		const fieldMany = multiplicity(modelFields[name]?.many);
+		const column = resolveColumn(contract, namespaceId, collection.tableName, resolveFieldToColumn(contract, namespaceId, modelName, name));
+		const actual = column === void 0 ? `${label}.${name} has no column.` : fieldMany === false ? `${label}.${name} has codec ${column.codecId} and ${nullability(column.nullable)}.` : `${label}.${name} is a list ${describeField({
+			codecId: column.codecId,
+			nullable: column.nullable,
+			many: fieldMany
+		})}.`;
+		const sameCodecAndNullability = column?.codecId === spec.codecId && column.nullable === spec.nullable;
+		if (!sameCodecAndNullability || !sameMultiplicity(fieldMany, spec.many)) throw ormError("ORM.FIELD_UNKNOWN", `Cannot apply a fragment to ${label}: its field ${name} does not match the declaration`, {
+			why: `${declared} ${actual}`,
+			fix: sameCodecAndNullability ? `Apply the fragment to a model whose ${name} field ${fieldShape(spec.many)}, or declare ${name} ${declarationFor(fieldMany)}.` : `Apply the fragment to a model whose ${name} field has that codec and nullability, or change the declaration in the fragment.`,
+			meta
+		});
 	}
-	if (mode === "none") return {
-		kind: "exists",
-		notExists: true,
-		where: childWhere ? and(joinWhere, childWhere) : joinWhere
-	};
+}
+/**
+* Define a fragment for any model that has the declared fields. Reached as the `fragment` method of the client `orm()` returns.
+*/
+function defineFieldFragment(declarations, body) {
+	const fields = declaredFieldSpecs(declarations);
+	assertFragmentBody(body);
+	return blindCast((collection) => {
+		const receiver = collection;
+		assertFragmentReceiver(receiver);
+		assertFragmentFields(receiver, fields);
+		const result = body(blindCast(collection));
+		assertFragmentResult(receiver, result);
+		return result;
+	});
+}
+const SHOWN_LENGTH = 64;
+function shown(value) {
+	const characters = Array.from(value);
+	const cut = characters.length > SHOWN_LENGTH;
 	return {
-		kind: "exists",
-		notExists: false,
-		where: childWhere ? and(joinWhere, childWhere) : joinWhere
+		text: JSON.stringify(cut ? `${characters.slice(0, SHOWN_LENGTH).join("")}…` : value),
+		cut
 	};
 }
-function firstJoinColumn(columns, label) {
-	const first = columns[0];
-	if (!first) throw new InternalError(`Relation metadata is missing ${label}`);
-	return first;
+function describeReceived(value) {
+	if (value === void 0 || value === null) return String(value);
+	if (Array.isArray(value)) return "an array";
+	const kind = typeof value;
+	return kind === "object" ? "an object" : `a ${kind}`;
 }
-function buildPairedColumnExprs(leftTable, leftColumns, rightTable, rightColumns) {
-	if (leftColumns.length !== rightColumns.length) throw new InternalError(`Relation metadata has mismatched join column counts: ${leftColumns.length} left column(s), ${rightColumns.length} right column(s)`);
-	if (leftColumns.length === 0) throw new InternalError("Relation metadata is missing join columns");
-	const exprs = [];
-	for (let i = 0; i < leftColumns.length; i++) {
-		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(leftTable.column(left), rightTable.column(right)));
-	}
-	if (exprs.length === 1 && exprs[0]) return exprs[0];
-	return and(...exprs);
+function cutNote(subject, value) {
+	return value.cut ? ` The ${subject} above is cut to its first ${SHOWN_LENGTH} characters.` : "";
 }
-function toRelationWhereExpr(context, relatedNamespaceId, relatedModelName, predicate, scope) {
-	if (!predicate) return;
-	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)) {
-		if (value === void 0) continue;
-		const fieldAccessor = blindCast(accessor)[fieldName];
-		if (!fieldAccessor) throw ormError("ORM.FIELD_UNKNOWN", `Shorthand filter on "${relatedModelName}.${fieldName}": field is not defined on the model`, { meta: {
-			model: relatedModelName,
-			field: fieldName
-		} });
-		if (value === null) {
-			if (!fieldAccessor.isNull) throw new InternalError(`Shorthand filter on "${relatedModelName}.${fieldName}": isNull is unexpectedly missing — this is a bug in trait gating`);
-			exprs.push(fieldAccessor.isNull());
-			continue;
-		}
-		if (!fieldAccessor.eq) throw ormError("ORM.FILTER_UNSUPPORTED", `Shorthand filter on "${relatedModelName}.${fieldName}": field does not support equality comparisons`, { meta: {
-			model: relatedModelName,
-			field: fieldName,
-			trait: "equality"
-		} });
-		exprs.push(fieldAccessor.eq(value));
-	}
-	if (exprs.length === 0) return;
-	return exprs.length === 1 ? exprs[0] : and(...exprs);
+function fieldCodecId(collection, field) {
+	const { contract } = collection.ctx.context;
+	const column = resolveFieldToColumn(contract, collection.namespaceId, collection.modelName, field);
+	return resolveColumn(contract, collection.namespaceId, collection.tableName, column)?.codecId;
 }
-function buildJoinWhere(contract, parentNamespaceId, parentModelName, parentTable, relatedTable, relation) {
-	const localFields = relation.on?.localFields ?? [];
-	const targetFields = relation.on?.targetFields ?? [];
-	const joinExprs = [];
-	const count = Math.min(localFields.length, targetFields.length);
-	for (let i = 0; i < count; i++) {
-		const localField = localFields[i];
-		const targetField = targetFields[i];
-		if (!localField || !targetField) continue;
-		const localColumn = resolveFieldToColumn(contract, parentNamespaceId, parentModelName, localField);
-		const targetColumn = resolveFieldToColumn(contract, relation.toNamespace, relation.to, targetField);
-		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];
-	if (joinExprs.length === 1 && firstExpr !== void 0) return firstExpr;
-	return and(...joinExprs);
+function canOrder(collection, field) {
+	const codecId = fieldCodecId(collection, field);
+	return codecId !== void 0 && hasTrait(collection.ctx.context, codecId, "order");
 }
-function firstTargetColumn(contract, relation) {
-	const firstField = (relation.on?.targetFields)?.[0];
-	if (!firstField) return;
-	return resolveFieldToColumn(contract, relation.toNamespace, relation.to, firstField);
+function orderableFieldNames(collection) {
+	const model = modelOf(collection.ctx.context.contract, collection.namespaceId, collection.modelName);
+	return Object.keys(model?.fields ?? {}).filter((field) => canOrder(collection, field));
 }
-var GroupedCollection = class GroupedCollection {
-	ctx;
-	contract;
-	modelName;
-	tableName;
-	namespaceId;
-	preGroupState;
-	groupByFields;
-	groupByColumns;
-	havingFilters;
-	postGroup;
-	constructor(ctx, modelName, options) {
-		this.ctx = ctx;
-		this.contract = ctx.context.contract;
-		this.modelName = modelName;
-		this.tableName = options.tableName;
-		this.namespaceId = blindCast(options.namespaceId);
-		this.preGroupState = options.preGroupState;
-		this.groupByFields = options.groupByFields;
-		this.groupByColumns = options.groupByColumns;
-		this.havingFilters = options.havingFilters;
-		this.postGroup = options.postGroup;
-	}
-	#clone(overrides) {
-		return blindCast(new GroupedCollection(this.ctx, this.modelName, {
-			tableName: this.tableName,
-			namespaceId: this.namespaceId,
-			preGroupState: this.preGroupState,
-			groupByFields: this.groupByFields,
-			groupByColumns: this.groupByColumns,
-			havingFilters: this.havingFilters,
-			postGroup: this.postGroup,
-			...overrides
-		}));
-	}
-	having(predicate) {
-		const havingExpr = predicate(createHavingBuilder(this.contract, this.ctx.context.aggregateDescriptors, this.namespaceId, this.modelName, this.tableName));
-		return this.#clone({ havingFilters: [...this.havingFilters, havingExpr] });
-	}
-	/**
-	* Append an `ORDER BY` clause on the grouped rows themselves — orders by
-	* group key. Ordering by an aggregate alias needs a builder surface over
-	* the aliases and isn't supported here. Unlocks post-group `limit(...)` /
-	* `offset(...)`, which page a group order that would otherwise be undefined.
-	*/
-	orderBy(selection) {
-		const selectors = Array.isArray(selection) ? selection : [selection];
-		if (selectors.length === 0) throw ormError("ORM.ARGUMENT_INVALID", `orderBy() for model "${this.modelName}" requires at least one selector`, { meta: {
-			method: "orderBy",
-			model: this.modelName
-		} });
-		const accessor = createModelAccessor(this.ctx.context, this.namespaceId, this.modelName);
-		const nextOrders = selectors.map((selector) => selector(accessor));
-		return this.#clone({ postGroup: {
-			...this.postGroup,
-			orderBy: [...this.postGroup.orderBy, ...nextOrders]
-		} });
+function whyNotOrderable(collection, name) {
+	const { modelName } = collection;
+	const model = modelOf(collection.ctx.context.contract, collection.namespaceId, modelName);
+	const quoted = shown(name).text;
+	if (Object.hasOwn(model?.relations ?? {}, name)) return `${quoted} is a relation of ${modelName}, not a field.`;
+	if (!Object.hasOwn(model?.fields ?? {}, name)) return `${modelName} has no field ${quoted}.`;
+	return canOrder(collection, name) ? `${quoted} is not one of the fields allowed for ordering.` : `The codec ${fieldCodecId(collection, name)} of ${modelName}.${name} cannot be ordered.`;
+}
+/**
+* An `orderBy` selector for a field named by a string, such as an order parameter of a request. `allowed` lists the fields a request may order by. A name that is not in `allowed` or not an orderable field of the collection's model, and a direction other than `asc` or `desc`, throw `ORM.ARGUMENT_INVALID`. An undefined direction is `asc`.
+*
+* ```ts
+* db.Post.orderBy(orderByField(db.Post, input.orderBy, input.direction, ['title', 'createdAt']));
+* ```
+*/
+function orderByField(collection, name, direction, allowed) {
+	const receiver = collection;
+	if (!isModelCollection(receiver)) throw ormError("ORM.ARGUMENT_INVALID", "Cannot order: orderByField was not given a collection", {
+		why: `orderByField takes the collection it orders, such as db.orm.public.Post; received ${describeReceived(receiver)}.`,
+		fix: "Pass the collection the selector is for as the first argument.",
+		meta: { argument: "collection" }
+	});
+	const { modelName } = collection;
+	const requestedName = name;
+	const requestedDirection = direction === void 0 ? "asc" : direction;
+	const allowedList = allowed;
+	if (!Array.isArray(allowedList) || allowedList.some((field) => typeof field !== "string")) throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName}: the allowed fields are not a list of names`, {
+		why: `orderByField takes the list of fields a request may order by; received ${describeReceived(allowedList)}.`,
+		fix: `Pass an array of field names of ${modelName}, such as ['title', 'createdAt'].`,
+		meta: {
+			model: modelName,
+			argument: "allowed"
+		}
+	});
+	if (typeof requestedDirection !== "string") throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName}: the direction is not a string`, {
+		why: `An order direction is "asc" or "desc"; received ${describeReceived(requestedDirection)}.`,
+		fix: "Pass \"asc\" or \"desc\".",
+		meta: {
+			model: modelName,
+			direction: requestedDirection
+		}
+	});
+	if (!isOrderByDirection(requestedDirection)) {
+		const shownDirection = shown(requestedDirection);
+		throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName} in direction ${shownDirection.text}`, {
+			why: "An order direction is \"asc\" or \"desc\".",
+			fix: `Pass "asc" or "desc".${cutNote("direction", shownDirection)}`,
+			meta: {
+				model: modelName,
+				direction: requestedDirection
+			}
+		});
 	}
-	/**
-	* Apply `LIMIT n` to the grouped rows. Replaces any previous post-group
-	* limit. Requires a prior `orderBy(...)` — a database may return groups in
-	* any order, so "the first n groups" is undefined without one.
-	*/
-	limit(n) {
-		return this.#clone({ postGroup: {
-			...this.postGroup,
-			limit: typeof n === "number" ? n : toExpr(n)
-		} });
+	const orderable = orderableFieldNames(collection);
+	const names = allowedList.filter((field) => orderable.includes(field));
+	const orderByOneOf = names.length === 0 ? `Pass an allowed list that names at least one field of ${modelName} that can be ordered.` : `Order by one of: ${names.join(", ")}.`;
+	if (typeof requestedName !== "string") throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName}: the field name is not a string`, {
+		why: `An order field name is a string; received ${describeReceived(requestedName)}.`,
+		fix: orderByOneOf,
+		meta: {
+			model: modelName,
+			field: requestedName
+		}
+	});
+	if (!names.includes(requestedName)) {
+		const shownName = shown(requestedName);
+		throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName} by ${shownName.text}`, {
+			why: whyNotOrderable(collection, requestedName),
+			fix: `${orderByOneOf}${cutNote("name", shownName)}`,
+			meta: {
+				model: modelName,
+				field: requestedName
+			}
+		});
 	}
-	/**
-	* Apply `OFFSET n` to the grouped rows. Replaces any previous post-group
-	* offset. Requires a prior `orderBy(...)`, same as `limit(...)` — both
-	* pagination methods need a deterministic group order.
-	*/
-	offset(n) {
-		return this.#clone({ postGroup: {
-			...this.postGroup,
-			offset: typeof n === "number" ? n : toExpr(n)
-		} });
+	const field = blindCast(requestedName);
+	const order = requestedDirection;
+	return (row) => row[field][order]();
+}
+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);
 	}
-	/**
-	* 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`.
-	*/
-	get prepared() {
-		return { aggregate: (fn, configure) => this.#describeAggregate(fn, configure) };
+	static unaliased(storage) {
+		return new SqlTableBinding(storage, storage.tableName);
 	}
-	async aggregate(fn, configure) {
-		const description = this.#describeAggregate(fn, configure);
-		return description.consume(queryPlanRows(this.ctx.runtime, description.plan));
+	static aliased(storage, alias) {
+		return new SqlTableBinding(storage, alias);
 	}
-	#describeAggregate(fn, configure) {
-		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: {
-			method: "groupBy.aggregate",
-			model: this.modelName
-		} });
-		for (const [alias, selector] of aggregateEntries) if (!isAggregateSelector(selector)) throw ormError("ORM.AGGREGATE_SELECTOR_INVALID", `groupBy().aggregate() selector "${alias}" is invalid`, { meta: {
-			method: "groupBy.aggregate",
-			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.namespaceId, this.tableName, this.preGroupState, this.groupByColumns, aggregateSpec, combineWhereExprs(this.havingFilters), this.modelName, this.postGroup), annotationsMap);
-		const mapRow = createStorageRowMapper(this.contract, this.namespaceId, this.modelName);
+	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 {
-			plan: compiled,
-			async consume(source) {
-				return (await source.toArray()).map((row) => {
-					const mapped = mapRow(row);
-					for (const [alias] of aggregateEntries) mapped[alias] = row[alias];
-					return blindCast(mapped);
-				});
-			}
+			childScope: new ModelAccessorScope(initialChildScope.current, [...initialChildScope.#visibleBindings, junctionBinding], this.#aliasCounter),
+			junctionBinding
 		};
 	}
-};
-/**
-* The having metric methods, one per operation the registry contributes —
-* the runtime mirror of the contract's emitted aggregate map, which is what
-* types the surface as {@link HavingBuilder}. HAVING compares the value
-* inside the database, so only an operation's plain `AggregateExpr` form is
-* sound here: an operation outside the SQL aggregate alphabet exists only in
-* its descriptor-lowered form — a rendering for the driver boundary — and is
-* refused. The typed surface already excludes it; the runtime refusal covers
-* dynamic invocation.
-*/
-function createHavingBuilder(contract, aggregates, namespaceId, modelName, tableName) {
-	const fieldToColumn = getFieldToColumnMap(contract, namespaceId, modelName);
-	const builder = {};
-	for (const operation of aggregateOperationNames(aggregates)) builder[operation] = (field) => {
-		if (!isAggregateFn(operation)) throw ormError("ORM.AGGREGATE_PROJECTION_ONLY", `Aggregate operation '${operation}' is projection-only: it has no plain SQL form for HAVING, ORDER BY, or comparison positions.`, {
-			why: "An operation outside the SQL aggregate alphabet reaches SQL only through its descriptor's lowering hook — a rendering for the driver boundary. HAVING and ORDER BY compare the value inside the database, where that rendering would change SQL semantics.",
-			fix: `Project '${operation}' in a select and filter or order on the projected value, or use an operation from the SQL aggregate alphabet.`,
-			meta: { operation }
+	forJoinedSource(namespaceId, tableName) {
+		if (this.current.isStoredAt(namespaceId, tableName)) return this;
+		const binding = SqlTableBinding.unaliased({
+			namespaceId,
+			tableName
 		});
-		return createHavingComparisonMethods(new AggregateExpr(operation, field === void 0 ? void 0 : ColumnRef.of(tableName, fieldToColumn[field] ?? field)), () => resolveAggregate({
-			aggregates,
-			contract,
+		return new ModelAccessorScope(binding, [...this.#visibleBindings, binding], this.#aliasCounter);
+	}
+	#allocateBinding(namespaceId, tableName, aliasKind) {
+		const storage = {
 			namespaceId,
-			tableName,
-			fn: operation,
-			column: field === void 0 ? void 0 : fieldToColumn[field] ?? field
-		}).codec.codecId);
-	};
-	return blindCast(builder);
+			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 createHavingComparisonMethods(metric, outputCodecId) {
-	const buildBinaryExpr = (op, value) => {
-		const expression = predicateExpression(value);
-		if (expression !== void 0 && (expression.kind !== "prepared-param-ref" || expression.codec.codecId !== outputCodecId())) throw ormError("ORM.HAVING_EXPRESSION_UNSUPPORTED", "HAVING comparands require a prepared parameter with the aggregate output codec", { meta: { kind: expression.kind } });
-		return predicateComparison(op, metric, expression ?? LiteralExpr.of(value));
-	};
-	return {
-		eq(value) {
-			return buildBinaryExpr("eq", value);
-		},
-		neq(value) {
-			return buildBinaryExpr("neq", value);
-		},
-		gt(value) {
-			return buildBinaryExpr("gt", value);
-		},
-		lt(value) {
-			return buildBinaryExpr("lt", value);
-		},
-		gte(value) {
-			return buildBinaryExpr("gte", value);
+function createModelAccessorInScope(context, namespaceId, modelName, variantName, scope) {
+	const contract = context.contract;
+	const fieldToColumn = getFieldToColumnMap(contract, namespaceId, modelName);
+	const tableName = resolveModelTableName(contract, namespaceId, modelName);
+	const modelRelations = resolveModelRelations(contract, namespaceId, modelName);
+	const variantFieldColumns = variantName ? resolveVariantFieldColumns(contract, namespaceId, modelName, variantName) : {};
+	const variantCoordinates = variantName ? {
+		name: variantName,
+		relations: resolveModelRelations(contract, namespaceId, variantName),
+		tableName: resolvePolymorphismInfo(contract, namespaceId, modelName)?.variants.get(variantName)?.table ?? tableName
+	} : void 0;
+	const opsByCodecId = /* @__PURE__ */ new Map();
+	function registerOp(codecId, op) {
+		let existing = opsByCodecId.get(codecId);
+		if (!existing) {
+			existing = [];
+			opsByCodecId.set(codecId, existing);
+		}
+		existing.push(op);
+	}
+	for (const [name, entry] of Object.entries(context.queryOperations.entries())) {
+		const op = [name, entry];
+		const self = entry.self;
+		if (!self) continue;
+		if (self.codecId !== void 0) registerOp(self.codecId, op);
+		else if (self.traits !== void 0) for (const descriptor of context.codecDescriptors.values()) {
+			const descriptorTraits = descriptor.traits;
+			if (self.traits.every((t) => descriptorTraits.includes(t))) registerOp(descriptor.codecId, op);
+		}
+	}
+	return blindCast(new Proxy({}, { get(_target, prop) {
+		if (typeof prop !== "string") return;
+		if (variantCoordinates) {
+			const variantRelation = variantCoordinates.relations[prop];
+			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, 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 = codecTraits(context, column.codecId);
+		const operations = opsByCodecId.get(column.codecId) ?? [];
+		const codec = codecRefForStorageColumn(contract.storage, namespaceId, resolvedTable, columnName);
+		return createScalarFieldAccessor(fieldBinding, columnName, column.codecId, column.nullable, codec, traits, operations, context);
+	} }));
+}
+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;
+		comparisonEntries.push([name, meta.create(column, codec)]);
+	}
+	const accessor = blindCast({
+		returnType: {
+			codecId,
+			nullable,
+			codec
 		},
-		lte(value) {
-			return buildBinaryExpr("lte", value);
+		buildAst: () => column,
+		...Object.fromEntries(comparisonEntries)
+	});
+	for (const [name, entry] of operations) accessor[name] = createExtensionMethodFactory(accessor, entry, context);
+	return blindCast(accessor);
+}
+function createExtensionMethodFactory(selfExpr, entry, context) {
+	return (...args) => {
+		const result = blindCast(entry.impl)(selfExpr, ...args);
+		const returnCodecId = result.returnType.codecId;
+		const returnTraits = codecTraits(context, returnCodecId);
+		if (returnTraits.includes("boolean")) return result.buildAst();
+		const resultAst = result.buildAst();
+		const returnCodec = { codecId: returnCodecId };
+		const methods = {};
+		for (const [resultMethodName, meta] of Object.entries(COMPARISON_METHODS_META)) {
+			if (meta.traits.some((t) => !returnTraits.includes(t))) continue;
+			methods[resultMethodName] = meta.create(resultAst, returnCodec);
 		}
+		return methods;
 	};
 }
-function createIncludeScalar(fn, state, column) {
+const RELATION_ACCESSOR_METHOD_NAMES = /* @__PURE__ */ new Set([
+	"some",
+	"every",
+	"none",
+	"count"
+]);
+function createRelationFilterAccessor(context, parentNamespaceId, parentModelName, parentScope, relation) {
+	const relatedTableName = resolveModelTableName(context.contract, relation.toNamespace, relation.to);
+	const correlate = () => correlateRelatedRows(context, parentNamespaceId, parentModelName, parentScope, relatedTableName, relation);
+	const filters = {
+		some: (predicate) => buildExistsExpr(context, relation, correlate(), "some", predicate),
+		every: (predicate) => buildExistsExpr(context, relation, correlate(), "every", predicate),
+		none: (predicate) => buildExistsExpr(context, relation, correlate(), "none", predicate)
+	};
+	if (isToOneCardinality(relation.cardinality)) return new Proxy(filters, { get(target, prop) {
+		if (typeof prop !== "string") return void 0;
+		if (Object.hasOwn(target, prop)) return Reflect.get(target, prop);
+		if (RELATION_ACCESSOR_METHOD_NAMES.has(prop)) return void 0;
+		return relatedOrderableField(context, relation, relatedTableName, correlate, prop);
+	} });
 	return {
-		kind: "includeScalar",
-		fn,
-		state,
-		...column !== void 0 ? { column } : {}
+		...filters,
+		count: (predicate) => createOrderable(() => buildRelationCountExpr(context, relation, correlate(), predicate))
 	};
 }
-function createIncludeCombine(branches) {
+function createOrderable(buildExpr) {
 	return {
-		kind: "includeCombine",
-		branches
+		asc: (options) => checkedOrderByItem("asc", buildExpr(), options),
+		desc: (options) => checkedOrderByItem("desc", buildExpr(), options)
 	};
 }
-function isIncludeScalar(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const candidate = value;
-	return candidate.kind === "includeScalar" && typeof candidate.fn === "string" && isCollectionState(candidate.state);
-}
-function isIncludeCombine(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const candidate = value;
-	if (candidate.kind !== "includeCombine") return false;
-	if (typeof candidate.branches !== "object" || candidate.branches === null) return false;
-	return true;
-}
-function isCollectionStateCarrier(value) {
-	if (typeof value !== "object" || value === null) return false;
-	return isCollectionState(value.state);
+function relatedOrderableField(context, relation, relatedTableName, correlate, fieldName) {
+	const fieldToColumn = getFieldToColumnMap(context.contract, relation.toNamespace, relation.to);
+	if (!Object.hasOwn(fieldToColumn, fieldName)) return void 0;
+	const columnName = fieldToColumn[fieldName];
+	if (columnName === void 0) return void 0;
+	const column = resolveColumn(context.contract, relation.toNamespace, relatedTableName, columnName);
+	if (!column || !hasTrait(context, column.codecId, "order")) return void 0;
+	return createOrderable(() => {
+		const rows = correlate();
+		return SubqueryExpr.of(rows.source.withProjection([ProjectionItem.of(columnName, rows.childScope.current.column(columnName))]).withWhere(rows.correlation));
+	});
 }
-function isCollectionState(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const candidate = value;
-	return Array.isArray(candidate.filters) && Array.isArray(candidate.includes);
+function buildRelationCountExpr(context, relation, rows, predicate) {
+	const childWhere = toRelationWhereExpr(context, relation.toNamespace, relation.to, predicate, rows.childScope);
+	return SubqueryExpr.of(rows.source.withProjection([ProjectionItem.of("count", plainAggregateExpr("count", void 0))]).withWhere(childWhere ? and(rows.correlation, childWhere) : rows.correlation));
 }
-function createRelationMutator() {
+function correlateRelatedRows(context, parentNamespaceId, parentModelName, parentScope, relatedTableName, relation) {
+	if (hasThrough$1(relation)) {
+		const { through } = relation;
+		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));
+		return {
+			childScope,
+			source: SelectAst.from(childScope.current.tableSource(context.contract)).withJoins([JoinAst.inner(junctionBinding.tableSource(context.contract), junctionJoinOn)]),
+			correlation: buildPairedColumnExprs(junctionBinding, through.parentColumns, parentScope.current, parentLocalColumns),
+			keyColumn: firstJoinColumn(through.targetColumns, "targetColumns")
+		};
+	}
+	const childScope = parentScope.forRelation(relation.toNamespace, relatedTableName);
 	return {
-		create(data) {
-			return {
-				kind: "create",
-				data: Array.isArray(data) ? [...data] : [data]
-			};
-		},
-		connect(criteria) {
-			return {
-				kind: "connect",
-				criteria: Array.isArray(criteria) ? [...criteria] : [criteria]
-			};
-		},
-		disconnect(criteria) {
-			if (!criteria) return { kind: "disconnect" };
-			return {
-				kind: "disconnect",
-				criteria: [...criteria]
-			};
-		}
+		childScope,
+		source: SelectAst.from(childScope.current.tableSource(context.contract)),
+		correlation: buildJoinWhere(context.contract, parentNamespaceId, parentModelName, parentScope.current, childScope.current, relation),
+		keyColumn: firstTargetColumn(context.contract, relation) ?? "id"
 	};
 }
-function isRelationMutationDescriptor(value) {
-	if (!value || typeof value !== "object") return false;
-	const candidate = value;
-	if (candidate.kind !== "create" && candidate.kind !== "connect" && candidate.kind !== "disconnect") return false;
-	return true;
+function buildExistsExpr(context, relation, rows, mode, predicate) {
+	const childWhere = toRelationWhereExpr(context, relation.toNamespace, relation.to, predicate, rows.childScope);
+	const filterPlan = planRelationFilterMode(rows.correlation, childWhere, mode);
+	if (filterPlan.kind === "constantTrue") return AndExpr.true();
+	const subquery = rows.source.withProjection([ProjectionItem.of("_exists", rows.childScope.current.column(rows.keyColumn))]).withWhere(filterPlan.where);
+	return filterPlan.notExists ? ExistsExpr.notExists(subquery) : ExistsExpr.exists(subquery);
 }
-function isRelationMutationCallback(value) {
-	return typeof value === "function";
+function planRelationFilterMode(joinWhere, childWhere, mode) {
+	if (mode === "every") {
+		if (!childWhere) return { kind: "constantTrue" };
+		return {
+			kind: "exists",
+			notExists: true,
+			where: and(joinWhere, not(childWhere))
+		};
+	}
+	if (mode === "none") return {
+		kind: "exists",
+		notExists: true,
+		where: childWhere ? and(joinWhere, childWhere) : joinWhere
+	};
+	return {
+		kind: "exists",
+		notExists: false,
+		where: childWhere ? and(joinWhere, childWhere) : joinWhere
+	};
 }
-function hasThrough(relation) {
-	return relation.through !== void 0;
+function firstJoinColumn(columns, label) {
+	const first = columns[0];
+	if (!first) throw new InternalError(`Relation metadata is missing ${label}`);
+	return first;
 }
-function hasNestedMutationCallbacks(contract, namespaceId, modelName, data) {
-	const relationNames = new Set(Object.keys(resolveModelRelations(contract, namespaceId, modelName)));
-	for (const [fieldName, value] of Object.entries(data)) {
-		if (!relationNames.has(fieldName)) continue;
-		if (isRelationMutationCallback(value)) return true;
+function buildPairedColumnExprs(leftTable, leftColumns, rightTable, rightColumns) {
+	if (leftColumns.length !== rightColumns.length) throw new InternalError(`Relation metadata has mismatched join column counts: ${leftColumns.length} left column(s), ${rightColumns.length} right column(s)`);
+	if (leftColumns.length === 0) throw new InternalError("Relation metadata is missing join columns");
+	const exprs = [];
+	for (let i = 0; i < leftColumns.length; i++) {
+		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(leftTable.column(left), rightTable.column(right)));
 	}
-	return false;
+	if (exprs.length === 1 && exprs[0]) return exprs[0];
+	return and(...exprs);
 }
-async function executeNestedCreateMutation(options) {
-	return withMutationScope(options.runtime, async (scope) => createGraph(scope, options.context, options.namespaceId, options.modelName, options.data));
-}
-async function executeNestedUpdateMutation(options) {
-	return withMutationScope(options.runtime, async (scope) => updateFirstGraph(scope, options.context, options.namespaceId, options.modelName, options.filters, options.data));
-}
-function buildRowIdentityFilterFromRow(contract, namespaceId, modelName, row) {
-	const tableName = resolveModelTableName(contract, namespaceId, modelName);
-	const identityColumns = resolveRowIdentityColumns(contract, namespaceId, tableName);
-	if (identityColumns.length === 0) throw ormError("ORM.ROW_IDENTITY_MISSING", `Nested mutations on model "${modelName}" require table "${tableName}" to have a primary key or unique constraint`, { meta: {
-		model: modelName,
-		table: tableName
-	} });
-	const filter = {};
-	for (const column of identityColumns) {
-		const fieldName = toFieldName(contract, namespaceId, modelName, column);
-		const value = row[fieldName];
-		if (value === void 0) throw new InternalError(`Missing identity field "${fieldName}" while reloading model "${modelName}"`);
-		filter[fieldName] = value;
-	}
-	return filter;
-}
-async function withMutationScope(runtime, run) {
-	if (typeof runtime.transaction === "function") return runInTransaction(await runtime.transaction(), run);
-	if (typeof runtime.connection === "function") {
-		const connection = await runtime.connection();
-		try {
-			if (typeof connection.transaction === "function") return await runInTransaction(await connection.transaction(), run);
-			return await run(connection);
-		} finally {
-			await connection.release?.();
+function toRelationWhereExpr(context, relatedNamespaceId, relatedModelName, predicate, scope) {
+	if (!predicate) return;
+	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)) {
+		if (value === void 0) continue;
+		const fieldAccessor = blindCast(accessor)[fieldName];
+		if (!fieldAccessor) throw ormError("ORM.FIELD_UNKNOWN", `Shorthand filter on "${relatedModelName}.${fieldName}": field is not defined on the model`, { meta: {
+			model: relatedModelName,
+			field: fieldName
+		} });
+		if (value === null) {
+			if (!fieldAccessor.isNull) throw new InternalError(`Shorthand filter on "${relatedModelName}.${fieldName}": isNull is unexpectedly missing — this is a bug in trait gating`);
+			exprs.push(fieldAccessor.isNull());
+			continue;
 		}
+		if (!fieldAccessor.eq) throw ormError("ORM.FILTER_UNSUPPORTED", `Shorthand filter on "${relatedModelName}.${fieldName}": field does not support equality comparisons`, { meta: {
+			model: relatedModelName,
+			field: fieldName,
+			trait: "equality"
+		} });
+		exprs.push(fieldAccessor.eq(value));
 	}
-	return run(runtime);
+	if (exprs.length === 0) return;
+	return exprs.length === 1 ? exprs[0] : and(...exprs);
 }
-async function runInTransaction(transaction, run) {
-	try {
-		const result = await run(transaction);
-		if (typeof transaction.commit === "function") await transaction.commit();
-		return result;
-	} catch (error) {
-		if (typeof transaction.rollback === "function") await transaction.rollback();
-		throw error;
+function buildJoinWhere(contract, parentNamespaceId, parentModelName, parentTable, relatedTable, relation) {
+	const localFields = relation.on?.localFields ?? [];
+	const targetFields = relation.on?.targetFields ?? [];
+	const joinExprs = [];
+	const count = Math.min(localFields.length, targetFields.length);
+	for (let i = 0; i < count; i++) {
+		const localField = localFields[i];
+		const targetField = targetFields[i];
+		if (!localField || !targetField) continue;
+		const localColumn = resolveFieldToColumn(contract, parentNamespaceId, parentModelName, localField);
+		const targetColumn = resolveFieldToColumn(contract, relation.toNamespace, relation.to, targetField);
+		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];
+	if (joinExprs.length === 1 && firstExpr !== void 0) return firstExpr;
+	return and(...joinExprs);
 }
-async function createGraph(scope, context, namespaceId, modelName, input) {
-	const contract = context.contract;
-	const parsed = parseMutationInput(contract, namespaceId, modelName, input);
-	const { parentOwned, childOwned, junctionOwned } = partitionByOwnership(parsed.relationMutations);
-	const scalarData = { ...parsed.scalarData };
-	for (const relationMutation of parentOwned) {
-		if (relationMutation.mutation.kind === "disconnect") throw ormError("ORM.RELATION_MUTATION_UNSUPPORTED", "disconnect() is only supported in update() nested mutations", { meta: {
-			kind: "disconnect",
-			relation: relationMutation.relation.relationName
+function firstTargetColumn(contract, relation) {
+	const firstField = (relation.on?.targetFields)?.[0];
+	if (!firstField) return;
+	return resolveFieldToColumn(contract, relation.toNamespace, relation.to, firstField);
+}
+var GroupedCollection = class GroupedCollection {
+	ctx;
+	contract;
+	modelName;
+	tableName;
+	namespaceId;
+	preGroupState;
+	groupByFields;
+	groupByColumns;
+	havingFilters;
+	postGroup;
+	constructor(ctx, modelName, options) {
+		this.ctx = ctx;
+		this.contract = ctx.context.contract;
+		this.modelName = modelName;
+		this.tableName = options.tableName;
+		this.namespaceId = blindCast(options.namespaceId);
+		this.preGroupState = options.preGroupState;
+		this.groupByFields = options.groupByFields;
+		this.groupByColumns = options.groupByColumns;
+		this.havingFilters = options.havingFilters;
+		this.postGroup = options.postGroup;
+	}
+	#clone(overrides) {
+		return blindCast(new GroupedCollection(this.ctx, this.modelName, {
+			tableName: this.tableName,
+			namespaceId: this.namespaceId,
+			preGroupState: this.preGroupState,
+			groupByFields: this.groupByFields,
+			groupByColumns: this.groupByColumns,
+			havingFilters: this.havingFilters,
+			postGroup: this.postGroup,
+			...overrides
+		}));
+	}
+	having(predicate) {
+		const havingExpr = predicate(createHavingBuilder(this.contract, this.ctx.context.aggregateDescriptors, this.namespaceId, this.modelName, this.tableName));
+		return this.#clone({ havingFilters: [...this.havingFilters, havingExpr] });
+	}
+	/**
+	* Append an `ORDER BY` clause on the grouped rows themselves — orders by
+	* group key. Ordering by an aggregate alias needs a builder surface over
+	* the aliases and isn't supported here. Unlocks post-group `limit(...)` /
+	* `offset(...)`, which page a group order that would otherwise be undefined.
+	*/
+	orderBy(selection) {
+		const selectors = Array.isArray(selection) ? selection : [selection];
+		if (selectors.length === 0) throw ormError("ORM.ARGUMENT_INVALID", `orderBy() for model "${this.modelName}" requires at least one selector`, { meta: {
+			method: "orderBy",
+			model: this.modelName
+		} });
+		const accessor = createModelAccessor(this.ctx.context, this.namespaceId, this.modelName);
+		const nextOrders = selectors.map((selector) => selector(accessor));
+		return this.#clone({ postGroup: {
+			...this.postGroup,
+			orderBy: [...this.postGroup.orderBy, ...nextOrders]
 		} });
-		await applyParentOwnedMutation(scope, context, namespaceId, modelName, scalarData, relationMutation.relation, relationMutation.mutation);
 	}
-	for (const relationMutation of junctionOwned) {
-		if (relationMutation.mutation.kind === "disconnect") throw ormError("ORM.RELATION_MUTATION_UNSUPPORTED", "disconnect() is only supported in update() nested mutations", { meta: {
-			kind: "disconnect",
-			relation: relationMutation.relation.relationName
+	/**
+	* Apply `LIMIT n` to the grouped rows. Replaces any previous post-group
+	* limit. Requires a prior `orderBy(...)` — a database may return groups in
+	* any order, so "the first n groups" is undefined without one.
+	*/
+	limit(n) {
+		return this.#clone({ postGroup: {
+			...this.postGroup,
+			limit: typeof n === "number" ? n : toExpr(n)
 		} });
-		await preflightJunctionOwnedCreateMutation(scope, context, relationMutation);
 	}
-	const parentRow = await insertSingleRow(scope, context, namespaceId, modelName, scalarData);
-	for (const relationMutation of childOwned) {
-		if (relationMutation.mutation.kind === "disconnect") throw ormError("ORM.RELATION_MUTATION_UNSUPPORTED", "disconnect() is only supported in update() nested mutations", { meta: {
-			kind: "disconnect",
-			relation: relationMutation.relation.relationName
+	/**
+	* Apply `OFFSET n` to the grouped rows. Replaces any previous post-group
+	* offset. Requires a prior `orderBy(...)`, same as `limit(...)` — both
+	* pagination methods need a deterministic group order.
+	*/
+	offset(n) {
+		return this.#clone({ postGroup: {
+			...this.postGroup,
+			offset: typeof n === "number" ? n : toExpr(n)
 		} });
-		await applyChildOwnedMutation(scope, context, namespaceId, modelName, parentRow, relationMutation.relation, relationMutation.mutation);
 	}
-	for (const relationMutation of junctionOwned) await applyJunctionOwnedMutation(scope, context, namespaceId, modelName, parentRow, relationMutation.relation, relationMutation.mutation);
-	return parentRow;
-}
-async function updateFirstGraph(scope, context, namespaceId, modelName, filters, input) {
-	const contract = context.contract;
-	const existingRow = await findFirstByFilters(scope, contract, namespaceId, modelName, filters);
-	if (!existingRow) return null;
-	const parsed = parseMutationInput(contract, namespaceId, modelName, input);
-	const { parentOwned, childOwned, junctionOwned } = partitionByOwnership(parsed.relationMutations);
-	const scalarData = { ...parsed.scalarData };
-	for (const relationMutation of parentOwned) await applyParentOwnedMutation(scope, context, namespaceId, modelName, scalarData, relationMutation.relation, relationMutation.mutation);
-	for (const relationMutation of junctionOwned) await preflightJunctionOwnedCreateMutation(scope, context, relationMutation);
-	let parentRow = existingRow;
-	const mappedUpdateData = mapModelDataToStorageRow(contract, namespaceId, modelName, scalarData);
-	if (Object.keys(mappedUpdateData).length > 0) {
-		const tableName = resolveModelTableName(contract, namespaceId, modelName);
-		const appliedUpdateDefaults = context.applyMutationDefaults({
-			op: "update",
-			entry: tableName,
-			namespace: namespaceId,
-			values: mappedUpdateData
-		});
-		for (const def of appliedUpdateDefaults) mappedUpdateData[def.field] = def.value;
-		const identityWhere = shorthandToWhereExpr(context, namespaceId, modelName, castAs(buildRowIdentityFilterFromRow(contract, namespaceId, modelName, existingRow)));
-		if (!identityWhere) throw new InternalError(`Failed to build row identity filter for model "${modelName}"`);
-		const updatedRaw = (await queryPlanRows(scope, compileUpdateReturning(contract, namespaceId, tableName, mappedUpdateData, [identityWhere], void 0)).toArray())[0];
-		if (updatedRaw) parentRow = mapStorageRowToModelFields(contract, namespaceId, modelName, updatedRaw);
+	/**
+	* 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`.
+	*/
+	get prepared() {
+		return { aggregate: (fn, configure) => this.#describeAggregate(fn, configure) };
 	}
-	for (const relationMutation of childOwned) await applyChildOwnedMutation(scope, context, namespaceId, modelName, parentRow, relationMutation.relation, relationMutation.mutation);
-	for (const relationMutation of junctionOwned) await applyJunctionOwnedMutation(scope, context, namespaceId, modelName, parentRow, relationMutation.relation, relationMutation.mutation);
-	return parentRow;
-}
-function parseMutationInput(contract, namespaceId, modelName, input) {
-	const scalarData = {};
-	const relationDefinitions = new Map(getRelationDefinitions(contract, namespaceId, modelName).map((relation) => [relation.relationName, relation]));
-	const relationMutations = [];
-	for (const [fieldName, value] of Object.entries(input)) {
-		const relation = relationDefinitions.get(fieldName);
-		if (!relation) {
-			scalarData[fieldName] = value;
-			continue;
-		}
-		if (!isRelationMutationCallback(value)) throw ormError("ORM.RELATION_MUTATION_INVALID", `Relation field "${fieldName}" on model "${modelName}" expects a mutator callback`, { meta: {
-			relation: fieldName,
-			model: modelName,
-			problem: "missing-callback"
+	async aggregate(fn, configure) {
+		const description = this.#describeAggregate(fn, configure);
+		return description.consume(queryPlanRows(this.ctx.runtime, description.plan));
+	}
+	#describeAggregate(fn, configure) {
+		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: {
+			method: "groupBy.aggregate",
+			model: this.modelName
 		} });
-		const mutation = value(createRelationMutator());
-		if (!isRelationMutationDescriptor(mutation)) throw ormError("ORM.RELATION_MUTATION_INVALID", `Relation field "${fieldName}" on model "${modelName}" returned an invalid mutation descriptor`, { meta: {
-			relation: fieldName,
-			model: modelName,
-			problem: "invalid-descriptor"
+		for (const [alias, selector] of aggregateEntries) if (!isAggregateSelector(selector)) throw ormError("ORM.AGGREGATE_SELECTOR_INVALID", `groupBy().aggregate() selector "${alias}" is invalid`, { meta: {
+			method: "groupBy.aggregate",
+			model: this.modelName,
+			alias
 		} });
-		relationMutations.push({
-			relation,
-			mutation
-		});
-	}
-	return {
-		scalarData,
-		relationMutations
-	};
-}
-function partitionByOwnership(relationMutations) {
-	const parentOwned = [];
-	const childOwned = [];
-	const junctionOwned = [];
-	for (const relationMutation of relationMutations) {
-		if (hasThrough(relationMutation.relation)) {
-			junctionOwned.push({
-				relation: relationMutation.relation,
-				mutation: relationMutation.mutation
-			});
-			continue;
-		}
-		if (relationMutation.relation.cardinality === "N:1") {
-			parentOwned.push(relationMutation);
-			continue;
+		let annotationsMap;
+		if (configure !== void 0) {
+			const meta = createMetaBuilder("read", "groupBy.aggregate");
+			configure(meta);
+			if (meta.annotations.size > 0) annotationsMap = meta.annotations;
 		}
-		childOwned.push(relationMutation);
+		const compiled = mergeAnnotations(compileGroupedAggregate(this.contract, this.ctx.context.aggregateDescriptors, this.namespaceId, this.tableName, this.preGroupState, this.groupByColumns, aggregateSpec, combineWhereExprs(this.havingFilters), this.modelName, this.postGroup), annotationsMap);
+		const mapRow = createStorageRowMapper(this.contract, this.namespaceId, this.modelName);
+		return {
+			plan: compiled,
+			async consume(source) {
+				return (await source.toArray()).map((row) => {
+					const mapped = mapRow(row);
+					for (const [alias] of aggregateEntries) mapped[alias] = row[alias];
+					return blindCast(mapped);
+				});
+			}
+		};
 	}
-	return {
-		parentOwned,
-		childOwned,
-		junctionOwned
+};
+/**
+* The having metric methods, one per operation the registry contributes —
+* the runtime mirror of the contract's emitted aggregate map, which is what
+* types the surface as {@link HavingBuilder}. HAVING compares the value
+* inside the database, so only an operation's plain `AggregateExpr` form is
+* sound here: an operation outside the SQL aggregate alphabet exists only in
+* its descriptor-lowered form — a rendering for the driver boundary — and is
+* refused. The typed surface already excludes it; the runtime refusal covers
+* dynamic invocation.
+*/
+function createHavingBuilder(contract, aggregates, namespaceId, modelName, tableName) {
+	const fieldToColumn = getFieldToColumnMap(contract, namespaceId, modelName);
+	const builder = {};
+	for (const operation of aggregateOperationNames(aggregates)) builder[operation] = (field) => {
+		if (!isAggregateFn(operation)) throw ormError("ORM.AGGREGATE_PROJECTION_ONLY", `Aggregate operation '${operation}' is projection-only: it has no plain SQL form for HAVING, ORDER BY, or comparison positions.`, {
+			why: "An operation outside the SQL aggregate alphabet reaches SQL only through its descriptor's lowering hook — a rendering for the driver boundary. HAVING and ORDER BY compare the value inside the database, where that rendering would change SQL semantics.",
+			fix: `Project '${operation}' in a select and filter or order on the projected value, or use an operation from the SQL aggregate alphabet.`,
+			meta: { operation }
+		});
+		return createHavingComparisonMethods(new AggregateExpr(operation, field === void 0 ? void 0 : ColumnRef.of(tableName, fieldToColumn[field] ?? field)), () => resolveAggregate({
+			aggregates,
+			contract,
+			namespaceId,
+			tableName,
+			fn: operation,
+			column: field === void 0 ? void 0 : fieldToColumn[field] ?? field
+		}).codec.codecId);
 	};
+	return blindCast(builder);
 }
-async function applyParentOwnedMutation(scope, context, parentNamespaceId, parentModelName, scalarData, relation, mutation) {
-	const contract = context.contract;
-	if (mutation.kind === "disconnect") {
-		for (const localColumn of relation.localColumns) {
-			const parentFieldName = toFieldName(contract, parentNamespaceId, parentModelName, localColumn);
-			scalarData[parentFieldName] = null;
-		}
-		return;
-	}
-	if (mutation.kind === "create") {
-		const row = mutation.data[0];
-		if (!row) throw ormError("ORM.RELATION_MUTATION_INVALID", `create() nested mutation for relation "${relation.relationName}" requires data`, { meta: {
-			kind: "create",
-			relation: relation.relationName,
-			problem: "missing-data"
-		} });
-		copyRelatedValuesToParent(contract, parentNamespaceId, parentModelName, relation, scalarData, await createGraph(scope, context, relation.relatedNamespaceId, relation.relatedModelName, castAs(row)));
-		return;
-	}
-	const criterion = mutation.criteria[0];
-	if (!criterion) throw ormError("ORM.RELATION_MUTATION_INVALID", `connect() nested mutation for relation "${relation.relationName}" requires criterion`, { meta: {
-		kind: "connect",
-		relation: relation.relationName,
-		problem: "missing-criterion"
-	} });
-	const relatedRow = await findRowByCriterion(scope, context, relation.relatedNamespaceId, relation.relatedModelName, castAs(criterion));
-	if (!relatedRow) throw ormError("ORM.RELATION_ROW_MISSING", `connect() nested mutation for relation "${relation.relationName}" did not find a matching row`, { meta: {
-		kind: "connect",
-		relation: relation.relationName
-	} });
-	copyRelatedValuesToParent(contract, parentNamespaceId, parentModelName, relation, scalarData, relatedRow);
-}
-function copyRelatedValuesToParent(contract, parentNamespaceId, parentModelName, relation, scalarData, relatedRow) {
-	for (let i = 0; i < relation.localColumns.length; i++) {
-		const localColumn = relation.localColumns[i];
-		const targetColumn = relation.targetColumns[i];
-		if (!localColumn || !targetColumn) continue;
-		const parentFieldName = toFieldName(contract, parentNamespaceId, parentModelName, localColumn);
-		scalarData[parentFieldName] = relatedRow[toFieldName(contract, relation.relatedNamespaceId, relation.relatedModelName, targetColumn)];
-	}
-}
-async function applyChildOwnedMutation(scope, context, parentNamespaceId, parentModelName, parentRow, relation, mutation) {
-	const contract = context.contract;
-	const parentValues = readParentColumnValues(contract, parentNamespaceId, parentModelName, relation, parentRow);
-	if (mutation.kind === "create") {
-		for (const childInput of mutation.data) {
-			const payload = { ...castAs(childInput) };
-			for (const [childColumn, parentValue] of parentValues.entries()) {
-				const childFieldName = toFieldName(contract, relation.relatedNamespaceId, relation.relatedModelName, childColumn);
-				payload[childFieldName] = parentValue;
-			}
-			await createGraph(scope, context, relation.relatedNamespaceId, relation.relatedModelName, castAs(payload));
-		}
-		return;
-	}
-	if (mutation.kind === "connect") {
-		for (const criterion of mutation.criteria) {
-			const criterionWhere = shorthandToWhereExpr(context, relation.relatedNamespaceId, relation.relatedModelName, castAs(criterion));
-			if (!criterionWhere) throw ormError("ORM.RELATION_MUTATION_INVALID", `connect() nested mutation for relation "${relation.relationName}" requires non-empty criterion`, { meta: {
-				kind: "connect",
-				relation: relation.relationName,
-				problem: "empty-criterion"
-			} });
-			const setValues = {};
-			for (const [childColumn, parentValue] of parentValues.entries()) setValues[childColumn] = parentValue;
-			await executeUpdateCount(scope, contract, relation.relatedNamespaceId, relation.relatedTableName, setValues, [criterionWhere]);
+function createHavingComparisonMethods(metric, outputCodecId) {
+	const buildBinaryExpr = (op, value) => {
+		const expression = predicateExpression(value);
+		if (expression !== void 0 && (expression.kind !== "prepared-param-ref" || expression.codec.codecId !== outputCodecId())) throw ormError("ORM.HAVING_EXPRESSION_UNSUPPORTED", "HAVING comparands require a prepared parameter with the aggregate output codec", { meta: { kind: expression.kind } });
+		return predicateComparison(op, metric, expression ?? LiteralExpr.of(value));
+	};
+	return {
+		eq(value) {
+			return buildBinaryExpr("eq", value);
+		},
+		neq(value) {
+			return buildBinaryExpr("neq", value);
+		},
+		gt(value) {
+			return buildBinaryExpr("gt", value);
+		},
+		lt(value) {
+			return buildBinaryExpr("lt", value);
+		},
+		gte(value) {
+			return buildBinaryExpr("gte", value);
+		},
+		lte(value) {
+			return buildBinaryExpr("lte", value);
 		}
-		return;
-	}
-	const setValues = {};
-	for (const childColumn of parentValues.keys()) setValues[childColumn] = null;
-	if (!mutation.criteria || mutation.criteria.length === 0) {
-		const parentJoinWhere = buildChildJoinWhere(relation, parentValues);
-		await executeUpdateCount(scope, contract, relation.relatedNamespaceId, relation.relatedTableName, setValues, [parentJoinWhere]);
-		return;
-	}
-	for (const criterion of mutation.criteria) {
-		const criterionWhere = shorthandToWhereExpr(context, relation.relatedNamespaceId, relation.relatedModelName, castAs(criterion));
-		if (!criterionWhere) throw ormError("ORM.RELATION_MUTATION_INVALID", `disconnect() nested mutation for relation "${relation.relationName}" requires non-empty criterion`, { meta: {
-			kind: "disconnect",
-			relation: relation.relationName,
-			problem: "empty-criterion"
-		} });
-		const parentJoinWhere = buildChildJoinWhere(relation, parentValues);
-		await executeUpdateCount(scope, contract, relation.relatedNamespaceId, relation.relatedTableName, setValues, [and(parentJoinWhere, criterionWhere)]);
-	}
-}
-async function applyJunctionOwnedMutation(scope, context, parentNamespaceId, parentModelName, parentRow, relation, mutation) {
-	const contract = context.contract;
-	const parentPkValues = readJunctionParentValues(contract, parentNamespaceId, parentModelName, relation, parentRow);
-	assertJunctionPayloadWritable(relation, mutation.kind);
-	if (mutation.kind === "create") {
-		for (const childInput of mutation.data) await insertJunctionLink(scope, context, relation, parentPkValues, readJunctionTargetValues(contract, relation, await createGraph(scope, context, relation.relatedNamespaceId, relation.relatedModelName, castAs(childInput))), "create");
-		return;
-	}
-	if (mutation.kind === "connect") {
-		for (const criterion of mutation.criteria) await insertJunctionLink(scope, context, relation, parentPkValues, await resolveJunctionTargetValues(scope, context, relation, "connect", criterion), "connect");
-		return;
-	}
-	if (!mutation.criteria || mutation.criteria.length === 0) throw ormError("ORM.RELATION_MUTATION_INVALID", `disconnect() nested mutation for relation "${relation.relationName}" requires criterion`, { meta: {
-		kind: "disconnect",
-		relation: relation.relationName,
-		problem: "missing-criterion"
-	} });
-	for (const criterion of mutation.criteria) await deleteJunctionLink(scope, context, relation, parentPkValues, await resolveJunctionTargetValues(scope, context, relation, "disconnect", criterion));
-}
-async function preflightJunctionOwnedCreateMutation(scope, context, relationMutation) {
-	const { relation, mutation } = relationMutation;
-	assertJunctionMetadataShape(relation);
-	assertJunctionPayloadWritable(relation, mutation.kind);
-	if (mutation.kind !== "connect") return;
-	const seenTargetKeys = /* @__PURE__ */ new Set();
-	for (const criterion of mutation.criteria) {
-		const targetValues = await resolveJunctionTargetValues(scope, context, relation, "connect", criterion);
-		const targetKey = JSON.stringify([...targetValues.entries()]);
-		if (seenTargetKeys.has(targetKey)) throw ormError("ORM.RELATION_MUTATION_INVALID", `connect() nested mutation for relation "${relation.relationName}" resolved duplicate junction link targets; remove the duplicate criteria`, { meta: {
-			kind: "connect",
-			relation: relation.relationName,
-			problem: "duplicate-criteria"
-		} });
-		seenTargetKeys.add(targetKey);
-	}
-}
-function assertJunctionPayloadWritable(relation, mutationKind) {
-	const through = relation.through;
-	if (mutationKind !== "create" && mutationKind !== "connect" || through.requiredPayloadColumns.length === 0) return;
-	const cols = through.requiredPayloadColumns.map((c) => `\`${c}\``).join(", ");
-	throw ormError("ORM.RELATION_MUTATION_UNSUPPORTED", `Cannot \`${mutationKind}\` on relation \`${relation.relationName}\`: its junction \`${through.table}\` has required column(s) ${cols} the relation API can't populate. Write the \`${through.table}\` junction directly or use the SQL builder.`, { meta: {
-		kind: mutationKind,
-		relation: relation.relationName,
-		reason: "junction-required-columns",
-		junction: through.table
-	} });
-}
-async function resolveJunctionTargetValues(scope, context, relation, kind, criterion) {
-	const relatedRow = await findRowByCriterion(scope, context, relation.relatedNamespaceId, relation.relatedModelName, criterion);
-	if (!relatedRow) throw ormError("ORM.RELATION_ROW_MISSING", `${kind}() nested mutation for relation "${relation.relationName}" did not find a matching row`, { meta: {
-		kind,
-		relation: relation.relationName
-	} });
-	return readJunctionTargetValues(context.contract, relation, relatedRow);
-}
-function readJunctionParentValues(contract, parentNamespaceId, parentModelName, relation, parentRow) {
-	const values = /* @__PURE__ */ new Map();
-	assertJunctionParentMetadataLength(relation);
-	for (let i = 0; i < relation.through.parentColumns.length; i++) {
-		const junctionColumn = relation.through.parentColumns[i];
-		const parentColumn = relation.localColumns[i];
-		if (junctionColumn === void 0 || parentColumn === void 0) throw new InternalError(`Relation "${relation.relationName}" has incomplete junction metadata for parent columns`);
-		const parentFieldName = toFieldName(contract, parentNamespaceId, parentModelName, parentColumn);
-		const parentValue = parentRow[parentFieldName];
-		if (parentValue === void 0) throw new InternalError(`Nested mutation requires parent field "${parentFieldName}" to be present in returned row`);
-		values.set(junctionColumn, parentValue);
-	}
-	return values;
-}
-function readJunctionTargetValues(contract, relation, relatedRow) {
-	const values = /* @__PURE__ */ new Map();
-	assertJunctionTargetMetadataLength(relation);
-	for (let i = 0; i < relation.through.childColumns.length; i++) {
-		const junctionColumn = relation.through.childColumns[i];
-		const targetColumn = relation.through.targetColumns[i];
-		if (junctionColumn === void 0 || targetColumn === void 0) throw new InternalError(`Relation "${relation.relationName}" has incomplete junction metadata for target columns`);
-		const targetFieldName = toFieldName(contract, relation.relatedNamespaceId, relation.relatedModelName, targetColumn);
-		const targetValue = relatedRow[targetFieldName];
-		if (targetValue === void 0) throw new InternalError(`Nested mutation requires target field "${targetFieldName}" to be present in returned row`);
-		values.set(junctionColumn, targetValue);
-	}
-	return values;
-}
-function assertJunctionMetadataLength(relation, throughColumnName, throughColumns, pairedColumnName, pairedColumns) {
-	if (throughColumns.length === pairedColumns.length) return;
-	throw new InternalError(`Relation "${relation.relationName}" has invalid junction metadata: ${throughColumnName} has ${throughColumns.length} column(s), but ${pairedColumnName} has ${pairedColumns.length}`);
-}
-function assertJunctionParentMetadataLength(relation) {
-	assertJunctionMetadataLength(relation, "parentColumns", relation.through.parentColumns, "localColumns", relation.localColumns);
-}
-function assertJunctionTargetMetadataLength(relation) {
-	assertJunctionMetadataLength(relation, "childColumns", relation.through.childColumns, "targetColumns", relation.through.targetColumns);
+	};
 }
-function assertJunctionMetadataShape(relation) {
-	assertJunctionParentMetadataLength(relation);
-	assertJunctionTargetMetadataLength(relation);
+function createIncludeScalar(fn, state, column) {
+	return {
+		kind: "includeScalar",
+		fn,
+		state,
+		...column !== void 0 ? { column } : {}
+	};
 }
-function writeJunctionColumn(junctionRow, through, column, value, relationName) {
-	if (Object.hasOwn(junctionRow, column) && !Object.is(junctionRow[column], value)) throw ormError("ORM.RELATION_MUTATION_INVALID", `Cannot write junction "${through.table}": conflicting values for junction column "${column}"`, { meta: {
-		relation: relationName,
-		junction: through.table,
-		column
-	} });
-	junctionRow[column] = value;
+function createIncludeCombine(branches) {
+	return {
+		kind: "includeCombine",
+		branches
+	};
 }
-async function insertJunctionLink(scope, context, relation, parentPkValues, targetPkValues, mutationKind) {
-	const through = relation.through;
-	const junctionRow = {};
-	for (const [column, value] of parentPkValues.entries()) writeJunctionColumn(junctionRow, through, column, value, relation.relationName);
-	for (const [column, value] of targetPkValues.entries()) writeJunctionColumn(junctionRow, through, column, value, relation.relationName);
-	const applied = context.applyMutationDefaults({
-		op: "create",
-		entry: through.table,
-		namespace: through.namespaceId,
-		values: junctionRow
-	});
-	for (const def of applied) junctionRow[def.field] = def.value;
-	const compiled = compileInsertCount(context.contract, through.namespaceId, through.table, [junctionRow]);
-	try {
-		await scope.execute(compiled);
-	} catch (error) {
-		if (mutationKind === "connect" && isUniqueConstraintViolation(error)) throw ormError("ORM.RELATION_LINK_DUPLICATE", `connect() nested mutation for relation "${relation.relationName}" violated a unique constraint on junction "${through.table}"; the junction link may already be present`, {
-			meta: {
-				relation: relation.relationName,
-				junction: through.table
-			},
-			cause: error
-		});
-		throw error;
-	}
+function isIncludeScalar(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return candidate.kind === "includeScalar" && typeof candidate.fn === "string" && isCollectionState(candidate.state);
 }
-async function deleteJunctionLink(scope, context, relation, parentPkValues, targetPkValues) {
-	const through = relation.through;
-	const junctionRow = {};
-	for (const [column, value] of parentPkValues.entries()) writeJunctionColumn(junctionRow, through, column, value, relation.relationName);
-	for (const [column, value] of targetPkValues.entries()) writeJunctionColumn(junctionRow, through, column, value, relation.relationName);
-	const exprs = [];
-	for (const [column, value] of Object.entries(junctionRow)) exprs.push(BinaryExpr.eq(ColumnRef.of(through.table, column), LiteralExpr.of(value)));
-	const first = exprs[0];
-	const where = exprs.length === 1 && first !== void 0 ? first : and(...exprs);
-	const compiled = compileDeleteCount(context.contract, through.namespaceId, through.table, [where]);
-	await scope.execute(compiled);
+function isIncludeCombine(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	if (candidate.kind !== "includeCombine") return false;
+	if (typeof candidate.branches !== "object" || candidate.branches === null) return false;
+	return true;
 }
-function readParentColumnValues(contract, parentNamespaceId, parentModelName, relation, parentRow) {
-	const values = /* @__PURE__ */ new Map();
-	for (let i = 0; i < relation.localColumns.length; i++) {
-		const localColumn = relation.localColumns[i];
-		const targetColumn = relation.targetColumns[i];
-		if (!localColumn || !targetColumn) continue;
-		const parentFieldName = toFieldName(contract, parentNamespaceId, parentModelName, localColumn);
-		const parentValue = parentRow[parentFieldName];
-		if (parentValue === void 0) throw new InternalError(`Nested mutation requires parent field "${parentFieldName}" to be present in returned row`);
-		values.set(targetColumn, parentValue);
-	}
-	return values;
+function isCollectionStateCarrier(value) {
+	if (typeof value !== "object" || value === null) return false;
+	return isCollectionState(value.state);
 }
-function buildChildJoinWhere(relation, childValues) {
-	const exprs = [];
-	for (const [childColumn, parentValue] of childValues.entries()) exprs.push(BinaryExpr.eq(ColumnRef.of(relation.relatedTableName, childColumn), LiteralExpr.of(parentValue)));
-	const first = exprs[0];
-	if (exprs.length === 1 && first !== void 0) return first;
-	return and(...exprs);
+function isCollectionState(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return Array.isArray(candidate.filters) && Array.isArray(candidate.includes);
 }
-async function insertSingleRow(scope, context, namespaceId, modelName, data) {
-	const contract = context.contract;
-	const tableName = resolveModelTableName(contract, namespaceId, modelName);
-	const mappedData = mapModelDataToStorageRow(contract, namespaceId, modelName, data);
-	const applied = context.applyMutationDefaults({
-		op: "create",
-		entry: tableName,
-		namespace: namespaceId,
-		values: mappedData
-	});
-	for (const def of applied) mappedData[def.field] = def.value;
-	const firstRow = (await queryPlanRows(scope, compileInsertReturning(contract, namespaceId, tableName, [mappedData], void 0)).toArray())[0];
-	if (!firstRow) throw ormError("ORM.MUTATION_ROW_MISSING", `Nested create for model "${modelName}" did not return a row`, { meta: {
-		operation: "create",
-		model: modelName,
-		phase: "nested"
-	} });
-	return mapStorageRowToModelFields(contract, namespaceId, modelName, firstRow);
+function createRelationMutator() {
+	return {
+		create(data) {
+			return {
+				kind: "create",
+				data: Array.isArray(data) ? [...data] : [data]
+			};
+		},
+		connect(criteria) {
+			return {
+				kind: "connect",
+				criteria: Array.isArray(criteria) ? [...criteria] : [criteria]
+			};
+		},
+		disconnect(criteria) {
+			if (!criteria) return { kind: "disconnect" };
+			return {
+				kind: "disconnect",
+				criteria: [...criteria]
+			};
+		}
+	};
 }
-async function findRowByCriterion(scope, context, namespaceId, modelName, criterion) {
-	const contract = context.contract;
-	const whereExpr = shorthandToWhereExpr(context, namespaceId, modelName, castAs(criterion));
-	if (!whereExpr) throw ormError("ORM.RELATION_MUTATION_INVALID", `Nested connect for model "${modelName}" requires non-empty criterion`, { meta: {
-		kind: "connect",
-		model: modelName,
-		problem: "empty-criterion"
-	} });
-	const firstRow = (await queryPlanRows(scope, compileSelect(contract, namespaceId, resolveModelTableName(contract, namespaceId, modelName), {
-		...emptyState(),
-		filters: [whereExpr],
-		limit: 1
-	})).toArray())[0];
-	if (!firstRow) return null;
-	return mapStorageRowToModelFields(contract, namespaceId, modelName, firstRow);
+function isRelationMutationDescriptor(value) {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value;
+	if (candidate.kind !== "create" && candidate.kind !== "connect" && candidate.kind !== "disconnect") return false;
+	return true;
 }
-async function findFirstByFilters(scope, contract, namespaceId, modelName, filters) {
-	const firstRow = (await queryPlanRows(scope, compileSelect(contract, namespaceId, resolveModelTableName(contract, namespaceId, modelName), {
-		...emptyState(),
-		filters,
-		limit: 1
-	})).toArray())[0];
-	if (!firstRow) return null;
-	return mapStorageRowToModelFields(contract, namespaceId, modelName, firstRow);
+function isRelationMutationCallback(value) {
+	return typeof value === "function";
 }
-async function executeUpdateCount(scope, contract, namespaceId, tableName, setValues, filters) {
-	const compiled = compileUpdateCount(contract, namespaceId, tableName, setValues, filters);
-	await scope.execute(compiled);
+function hasThrough(relation) {
+	return relation.through !== void 0;
 }
-const relationDefsCache = /* @__PURE__ */ new WeakMap();
-function getRelationDefinitions(contract, namespaceId, modelName) {
-	let perContract = relationDefsCache.get(contract);
-	if (!perContract) {
-		perContract = /* @__PURE__ */ new Map();
-		relationDefsCache.set(contract, perContract);
+function hasNestedMutationCallbacks(contract, namespaceId, modelName, data) {
+	const relationNames = new Set(Object.keys(resolveModelRelations(contract, namespaceId, modelName)));
+	for (const [fieldName, value] of Object.entries(data)) {
+		if (!relationNames.has(fieldName)) continue;
+		if (isRelationMutationCallback(value)) return true;
 	}
-	const cacheKey = JSON.stringify([namespaceId, modelName]);
-	const cached = perContract.get(cacheKey);
-	if (cached) return cached;
-	const relations = resolveModelRelations(contract, namespaceId, modelName);
-	const definitions = Object.entries(relations).map(([relationName, relation]) => ({
-		relationName,
-		relatedModelName: relation.to,
-		relatedNamespaceId: relation.toNamespace,
-		relatedTableName: resolveModelTableName(contract, relation.toNamespace, relation.to),
-		cardinality: relation.cardinality,
-		localColumns: relation.on.localFields.map((f) => resolveFieldToColumn(contract, namespaceId, modelName, f)),
-		targetColumns: relation.on.targetFields.map((f) => resolveFieldToColumn(contract, relation.toNamespace, relation.to, f)),
-		through: relation.through ? {
-			table: relation.through.table,
-			namespaceId: relation.through.namespaceId,
-			parentColumns: relation.through.parentColumns,
-			childColumns: relation.through.childColumns,
-			targetColumns: relation.through.targetColumns,
-			requiredPayloadColumns: relation.through.requiredPayloadColumns
-		} : void 0
-	}));
-	perContract.set(cacheKey, definitions);
-	return definitions;
-}
-function toFieldName(contract, namespaceId, modelName, columnName) {
-	return getColumnToFieldMap(contract, namespaceId, modelName)[columnName] ?? columnName;
+	return false;
 }
-function nullability(nullable) {
-	return nullable ? "may be null" : "is never null";
+async function executeNestedCreateMutation(options) {
+	return withMutationScope(options.runtime, async (scope) => createGraph(scope, options.context, options.namespaceId, options.modelName, options.data));
 }
-function isFieldBuilder(value) {
-	return "build" in value && typeof value.build === "function";
+async function executeNestedUpdateMutation(options) {
+	return withMutationScope(options.runtime, async (scope) => updateFirstGraph(scope, options.context, options.namespaceId, options.modelName, options.filters, options.data));
 }
-function isListMultiplicity(value) {
-	return typeof value === "object" && value !== null && "elementNullable" in value && typeof value.elementNullable === "boolean";
+function buildRowIdentityFilterFromRow(contract, namespaceId, modelName, row) {
+	const tableName = resolveModelTableName(contract, namespaceId, modelName);
+	const identityColumns = resolveRowIdentityColumns(contract, namespaceId, tableName);
+	if (identityColumns.length === 0) throw ormError("ORM.ROW_IDENTITY_MISSING", `Nested mutations on model "${modelName}" require table "${tableName}" to have a primary key or unique constraint`, { meta: {
+		model: modelName,
+		table: tableName
+	} });
+	const filter = {};
+	for (const column of identityColumns) {
+		const fieldName = toFieldName(contract, namespaceId, modelName, column);
+		const value = row[fieldName];
+		if (value === void 0) throw new InternalError(`Missing identity field "${fieldName}" while reloading model "${modelName}"`);
+		filter[fieldName] = value;
+	}
+	return filter;
 }
-function isMultiplicity(value) {
-	return value === void 0 || value === false || isListMultiplicity(value);
+async function withMutationScope(runtime, run) {
+	if (typeof runtime.transaction === "function") return runInTransaction(await runtime.transaction(), run);
+	if (typeof runtime.connection === "function") {
+		const connection = await runtime.connection();
+		try {
+			if (typeof connection.transaction === "function") return await runInTransaction(await connection.transaction(), run);
+			return await run(connection);
+		} finally {
+			await connection.release?.();
+		}
+	}
+	return run(runtime);
 }
-function isFieldSpec(value) {
-	return "codecId" in value && typeof value.codecId === "string" && "nullable" in value && typeof value.nullable === "boolean" && (!("many" in value) || isMultiplicity(value.many));
+async function runInTransaction(transaction, run) {
+	try {
+		const result = await run(transaction);
+		if (typeof transaction.commit === "function") await transaction.commit();
+		return result;
+	} catch (error) {
+		if (typeof transaction.rollback === "function") await transaction.rollback();
+		throw error;
+	}
 }
-function multiplicity(many) {
-	return isListMultiplicity(many) ? { elementNullable: many.elementNullable } : false;
+async function createGraph(scope, context, namespaceId, modelName, input) {
+	const contract = context.contract;
+	const parsed = parseMutationInput(contract, namespaceId, modelName, input);
+	const { parentOwned, childOwned, junctionOwned } = partitionByOwnership(parsed.relationMutations);
+	const scalarData = { ...parsed.scalarData };
+	for (const relationMutation of parentOwned) {
+		if (relationMutation.mutation.kind === "disconnect") throw ormError("ORM.RELATION_MUTATION_UNSUPPORTED", "disconnect() is only supported in update() nested mutations", { meta: {
+			kind: "disconnect",
+			relation: relationMutation.relation.relationName
+		} });
+		await applyParentOwnedMutation(scope, context, namespaceId, modelName, scalarData, relationMutation.relation, relationMutation.mutation);
+	}
+	for (const relationMutation of junctionOwned) {
+		if (relationMutation.mutation.kind === "disconnect") throw ormError("ORM.RELATION_MUTATION_UNSUPPORTED", "disconnect() is only supported in update() nested mutations", { meta: {
+			kind: "disconnect",
+			relation: relationMutation.relation.relationName
+		} });
+		await preflightJunctionOwnedCreateMutation(scope, context, relationMutation);
+	}
+	const parentRow = await insertSingleRow(scope, context, namespaceId, modelName, scalarData);
+	for (const relationMutation of childOwned) {
+		if (relationMutation.mutation.kind === "disconnect") throw ormError("ORM.RELATION_MUTATION_UNSUPPORTED", "disconnect() is only supported in update() nested mutations", { meta: {
+			kind: "disconnect",
+			relation: relationMutation.relation.relationName
+		} });
+		await applyChildOwnedMutation(scope, context, namespaceId, modelName, parentRow, relationMutation.relation, relationMutation.mutation);
+	}
+	for (const relationMutation of junctionOwned) await applyJunctionOwnedMutation(scope, context, namespaceId, modelName, parentRow, relationMutation.relation, relationMutation.mutation);
+	return parentRow;
 }
-const FIELD_DECLARATION_FIX = "Declare each field with a field builder, such as field.temporal.timestamptz().optional(), or with { codecId, nullable }. Declare a list with .many() or many: { elementNullable: false }, or, when its elements may be null, with .many({ elementsNullable: true }) or many: { elementNullable: true }.";
-function declaredFieldSpec(name, declaration) {
-	if (typeof declaration === "object" && declaration !== null && isFieldBuilder(declaration)) {
-		const built = declaration.build();
-		const descriptor = typeof built === "object" && built !== null && "descriptor" in built ? built.descriptor : void 0;
-		const nullable = typeof built === "object" && built !== null && "nullable" in built ? built.nullable : void 0;
-		if (typeof descriptor !== "object" || descriptor === null || !("codecId" in descriptor) || typeof descriptor.codecId !== "string" || typeof nullable !== "boolean") throw ormError("ORM.ARGUMENT_INVALID", `Cannot define the scope: the field builder for ${name} names no column type`, {
-			why: "A scope for any model matches each declared field by its codec and nullability, and this builder refers to a named type instead of a column type.",
-			fix: "Declare the field with a builder that has a column type, such as field.text() or field.column(textColumn), or with { codecId, nullable }.",
-			meta: { field: name }
+async function updateFirstGraph(scope, context, namespaceId, modelName, filters, input) {
+	const contract = context.contract;
+	const existingRow = await findFirstByFilters(scope, contract, namespaceId, modelName, filters);
+	if (!existingRow) return null;
+	const parsed = parseMutationInput(contract, namespaceId, modelName, input);
+	const { parentOwned, childOwned, junctionOwned } = partitionByOwnership(parsed.relationMutations);
+	const scalarData = { ...parsed.scalarData };
+	for (const relationMutation of parentOwned) await applyParentOwnedMutation(scope, context, namespaceId, modelName, scalarData, relationMutation.relation, relationMutation.mutation);
+	for (const relationMutation of junctionOwned) await preflightJunctionOwnedCreateMutation(scope, context, relationMutation);
+	let parentRow = existingRow;
+	const mappedUpdateData = mapModelDataToStorageRow(contract, namespaceId, modelName, scalarData);
+	if (Object.keys(mappedUpdateData).length > 0) {
+		const tableName = resolveModelTableName(contract, namespaceId, modelName);
+		const appliedUpdateDefaults = context.applyMutationDefaults({
+			op: "update",
+			entry: tableName,
+			namespace: namespaceId,
+			values: mappedUpdateData
 		});
-		const many = typeof built === "object" && built !== null && "many" in built && built.many;
-		if (!isMultiplicity(many)) throw ormError("ORM.ARGUMENT_INVALID", `Cannot define the scope: the field builder for ${name} builds a many that is not false or { elementNullable }`, {
-			why: `A field builder's build() returns many as false or undefined for one value, or as { elementNullable } with a boolean elementNullable for a list; received ${describeReceived(many)} for ${name}.`,
-			fix: FIELD_DECLARATION_FIX,
-			meta: { field: name }
+		for (const def of appliedUpdateDefaults) mappedUpdateData[def.field] = def.value;
+		const identityWhere = shorthandToWhereExpr(context, namespaceId, modelName, castAs(buildRowIdentityFilterFromRow(contract, namespaceId, modelName, existingRow)));
+		if (!identityWhere) throw new InternalError(`Failed to build row identity filter for model "${modelName}"`);
+		const updatedRaw = (await queryPlanRows(scope, compileUpdateReturning(contract, namespaceId, tableName, mappedUpdateData, [identityWhere], void 0)).toArray())[0];
+		if (updatedRaw) parentRow = mapStorageRowToModelFields(contract, namespaceId, modelName, updatedRaw);
+	}
+	for (const relationMutation of childOwned) await applyChildOwnedMutation(scope, context, namespaceId, modelName, parentRow, relationMutation.relation, relationMutation.mutation);
+	for (const relationMutation of junctionOwned) await applyJunctionOwnedMutation(scope, context, namespaceId, modelName, parentRow, relationMutation.relation, relationMutation.mutation);
+	return parentRow;
+}
+function parseMutationInput(contract, namespaceId, modelName, input) {
+	const scalarData = {};
+	const relationDefinitions = new Map(getRelationDefinitions(contract, namespaceId, modelName).map((relation) => [relation.relationName, relation]));
+	const relationMutations = [];
+	for (const [fieldName, value] of Object.entries(input)) {
+		const relation = relationDefinitions.get(fieldName);
+		if (!relation) {
+			scalarData[fieldName] = value;
+			continue;
+		}
+		if (!isRelationMutationCallback(value)) throw ormError("ORM.RELATION_MUTATION_INVALID", `Relation field "${fieldName}" on model "${modelName}" expects a mutator callback`, { meta: {
+			relation: fieldName,
+			model: modelName,
+			problem: "missing-callback"
+		} });
+		const mutation = value(createRelationMutator());
+		if (!isRelationMutationDescriptor(mutation)) throw ormError("ORM.RELATION_MUTATION_INVALID", `Relation field "${fieldName}" on model "${modelName}" returned an invalid mutation descriptor`, { meta: {
+			relation: fieldName,
+			model: modelName,
+			problem: "invalid-descriptor"
+		} });
+		relationMutations.push({
+			relation,
+			mutation
 		});
-		return {
-			codecId: descriptor.codecId,
-			nullable,
-			many: multiplicity(many)
-		};
 	}
-	if (typeof declaration === "object" && declaration !== null && isFieldSpec(declaration)) return {
-		codecId: declaration.codecId,
-		nullable: declaration.nullable,
-		many: multiplicity(declaration.many)
+	return {
+		scalarData,
+		relationMutations
+	};
+}
+function partitionByOwnership(relationMutations) {
+	const parentOwned = [];
+	const childOwned = [];
+	const junctionOwned = [];
+	for (const relationMutation of relationMutations) {
+		if (hasThrough(relationMutation.relation)) {
+			junctionOwned.push({
+				relation: relationMutation.relation,
+				mutation: relationMutation.mutation
+			});
+			continue;
+		}
+		if (relationMutation.relation.cardinality === "N:1") {
+			parentOwned.push(relationMutation);
+			continue;
+		}
+		childOwned.push(relationMutation);
+	}
+	return {
+		parentOwned,
+		childOwned,
+		junctionOwned
 	};
-	throw ormError("ORM.ARGUMENT_INVALID", `Cannot define the scope: the declaration of field ${name} is not a field builder or { codecId, nullable }`, {
-		why: `Each field of a scope is declared with a field builder or with an object that has a string codecId, a boolean nullable and, for a list, many: { elementNullable } with a boolean elementNullable; received ${describeReceived(declaration)} for ${name}.`,
-		fix: FIELD_DECLARATION_FIX,
-		meta: { field: name }
-	});
-}
-function declaredFieldSpecs(declarations) {
-	if (typeof declarations !== "object" || declarations === null || Array.isArray(declarations)) throw ormError("ORM.ARGUMENT_INVALID", "Cannot define the scope: the fields are not an object", {
-		why: `The first argument of scope maps the name of each field the scope needs to its declaration; received ${describeReceived(declarations)}.`,
-		fix: FIELD_DECLARATION_FIX,
-		meta: { argument: "fields" }
-	});
-	return Object.entries(declarations).map(([name, declaration]) => [name, declaredFieldSpec(name, declaration)]);
-}
-/** Throws `ORM.ARGUMENT_INVALID` unless `body`, the body of a scope, is a function. */
-function assertScopeBody(body) {
-	if (typeof body !== "function") throw ormError("ORM.ARGUMENT_INVALID", "Cannot define the scope: the body is not a function", {
-		why: `The body of a scope is a function that receives a collection and returns one; received ${describeReceived(body)}.`,
-		fix: "Pass a function, such as (rows) => rows.where(...).",
-		meta: { argument: "body" }
-	});
-}
-function hasContract(ctx) {
-	return "context" in ctx && typeof ctx.context === "object" && ctx.context !== null && "contract" in ctx.context && typeof ctx.context.contract === "object" && ctx.context.contract !== null;
-}
-function isModelCollection(value) {
-	return typeof value === "object" && value !== null && "ctx" in value && typeof value.ctx === "object" && value.ctx !== null && hasContract(value.ctx) && "modelName" in value && typeof value.modelName === "string" && "namespaceId" in value && typeof value.namespaceId === "string";
 }
-/** Throws `ORM.ARGUMENT_INVALID` unless `value`, what a scope is applied to, is a collection. */
-function assertScopeReceiver(value) {
-	if (!isModelCollection(value)) throw ormError("ORM.ARGUMENT_INVALID", "Cannot apply the scope: it was not given a collection", {
-		why: `A scope is applied to a collection, such as db.orm.public.Post; received ${describeReceived(value)}.`,
-		fix: "Pass the scope to with on a collection: collection.with(scope).",
-		meta: { argument: "collection" }
-	});
-}
-/** Throws `ORM.ARGUMENT_INVALID` unless `value` is a collection of the model and namespace a scope for one model was made from. */
-function assertModelScopeReceiver(source, value) {
-	assertScopeReceiver(value);
-	if (value.modelName !== source.modelName || value.namespaceId !== source.namespaceId) {
-		const made = `${source.namespaceId}.${source.modelName}`;
-		const given = `${value.namespaceId}.${value.modelName}`;
-		throw ormError("ORM.ARGUMENT_INVALID", `Cannot apply a scope for ${made} to a collection of ${given}`, {
-			why: `The scope was made with ${made}.scope(...), and its body was written for that model.`,
-			fix: `Apply the scope to a collection of ${made}, or make a scope from ${given}.`,
-			meta: {
-				model: source.modelName,
-				namespace: source.namespaceId,
-				receivedModel: value.modelName,
-				receivedNamespace: value.namespaceId
-			}
-		});
+async function applyParentOwnedMutation(scope, context, parentNamespaceId, parentModelName, scalarData, relation, mutation) {
+	const contract = context.contract;
+	if (mutation.kind === "disconnect") {
+		for (const localColumn of relation.localColumns) {
+			const parentFieldName = toFieldName(contract, parentNamespaceId, parentModelName, localColumn);
+			scalarData[parentFieldName] = null;
+		}
+		return;
+	}
+	if (mutation.kind === "create") {
+		const row = mutation.data[0];
+		if (!row) throw ormError("ORM.RELATION_MUTATION_INVALID", `create() nested mutation for relation "${relation.relationName}" requires data`, { meta: {
+			kind: "create",
+			relation: relation.relationName,
+			problem: "missing-data"
+		} });
+		copyRelatedValuesToParent(contract, parentNamespaceId, parentModelName, relation, scalarData, await createGraph(scope, context, relation.relatedNamespaceId, relation.relatedModelName, castAs(row)));
+		return;
 	}
+	const criterion = mutation.criteria[0];
+	if (!criterion) throw ormError("ORM.RELATION_MUTATION_INVALID", `connect() nested mutation for relation "${relation.relationName}" requires criterion`, { meta: {
+		kind: "connect",
+		relation: relation.relationName,
+		problem: "missing-criterion"
+	} });
+	const relatedRow = await findRowByCriterion(scope, context, relation.relatedNamespaceId, relation.relatedModelName, castAs(criterion));
+	if (!relatedRow) throw ormError("ORM.RELATION_ROW_MISSING", `connect() nested mutation for relation "${relation.relationName}" did not find a matching row`, { meta: {
+		kind: "connect",
+		relation: relation.relationName
+	} });
+	copyRelatedValuesToParent(contract, parentNamespaceId, parentModelName, relation, scalarData, relatedRow);
 }
-/** The model as error messages name it: with its namespace when the contract has more than one. */
-function modelLabel(collection) {
-	return Object.keys(collection.ctx.context.contract.domain.namespaces).length > 1 ? `${collection.namespaceId}.${collection.modelName}` : collection.modelName;
+function copyRelatedValuesToParent(contract, parentNamespaceId, parentModelName, relation, scalarData, relatedRow) {
+	for (let i = 0; i < relation.localColumns.length; i++) {
+		const localColumn = relation.localColumns[i];
+		const targetColumn = relation.targetColumns[i];
+		if (!localColumn || !targetColumn) continue;
+		const parentFieldName = toFieldName(contract, parentNamespaceId, parentModelName, localColumn);
+		scalarData[parentFieldName] = relatedRow[toFieldName(contract, relation.relatedNamespaceId, relation.relatedModelName, targetColumn)];
+	}
 }
-/** Throws `ORM.ARGUMENT_INVALID` unless `result`, what a scope's body returned, is a collection of the receiver's model, namespace and class. */
-function assertScopeResult(receiver, result) {
-	if (!(isModelCollection(result) && result.modelName === receiver.modelName && result.namespaceId === receiver.namespaceId && result instanceof receiver.constructor)) {
-		const label = modelLabel(receiver);
-		throw ormError("ORM.ARGUMENT_INVALID", `Cannot apply the scope to ${label}: its body did not return a collection of ${label}`, {
-			why: `The body of a scope for any model returns the collection it received, after where, orderBy, limit or offset; it returned ${isModelCollection(result) ? `a collection of ${modelLabel(result)}` : describeReceived(result)}.`,
-			fix: "Return the collection the body receives, or one made from it by calling its methods.",
-			meta: {
-				model: receiver.modelName,
-				namespace: receiver.namespaceId,
-				returned: isModelCollection(result) ? result.modelName : describeReceived(result)
+async function applyChildOwnedMutation(scope, context, parentNamespaceId, parentModelName, parentRow, relation, mutation) {
+	const contract = context.contract;
+	const parentValues = readParentColumnValues(contract, parentNamespaceId, parentModelName, relation, parentRow);
+	if (mutation.kind === "create") {
+		for (const childInput of mutation.data) {
+			const payload = { ...castAs(childInput) };
+			for (const [childColumn, parentValue] of parentValues.entries()) {
+				const childFieldName = toFieldName(contract, relation.relatedNamespaceId, relation.relatedModelName, childColumn);
+				payload[childFieldName] = parentValue;
 			}
-		});
+			await createGraph(scope, context, relation.relatedNamespaceId, relation.relatedModelName, castAs(payload));
+		}
+		return;
+	}
+	if (mutation.kind === "connect") {
+		for (const criterion of mutation.criteria) {
+			const criterionWhere = shorthandToWhereExpr(context, relation.relatedNamespaceId, relation.relatedModelName, castAs(criterion));
+			if (!criterionWhere) throw ormError("ORM.RELATION_MUTATION_INVALID", `connect() nested mutation for relation "${relation.relationName}" requires non-empty criterion`, { meta: {
+				kind: "connect",
+				relation: relation.relationName,
+				problem: "empty-criterion"
+			} });
+			const setValues = {};
+			for (const [childColumn, parentValue] of parentValues.entries()) setValues[childColumn] = parentValue;
+			await executeUpdateCount(scope, contract, relation.relatedNamespaceId, relation.relatedTableName, setValues, [criterionWhere]);
+		}
+		return;
+	}
+	const setValues = {};
+	for (const childColumn of parentValues.keys()) setValues[childColumn] = null;
+	if (!mutation.criteria || mutation.criteria.length === 0) {
+		const parentJoinWhere = buildChildJoinWhere(relation, parentValues);
+		await executeUpdateCount(scope, contract, relation.relatedNamespaceId, relation.relatedTableName, setValues, [parentJoinWhere]);
+		return;
+	}
+	for (const criterion of mutation.criteria) {
+		const criterionWhere = shorthandToWhereExpr(context, relation.relatedNamespaceId, relation.relatedModelName, castAs(criterion));
+		if (!criterionWhere) throw ormError("ORM.RELATION_MUTATION_INVALID", `disconnect() nested mutation for relation "${relation.relationName}" requires non-empty criterion`, { meta: {
+			kind: "disconnect",
+			relation: relation.relationName,
+			problem: "empty-criterion"
+		} });
+		const parentJoinWhere = buildChildJoinWhere(relation, parentValues);
+		await executeUpdateCount(scope, contract, relation.relatedNamespaceId, relation.relatedTableName, setValues, [and(parentJoinWhere, criterionWhere)]);
 	}
 }
-function elementNullability(elementNullable) {
-	return elementNullable ? "may be null" : "are never null";
-}
-function sameMultiplicity(a, b) {
-	return a === false || b === false ? a === b : a.elementNullable === b.elementNullable;
-}
-function fieldShape(many) {
-	return many === false ? "holds one value" : `is a list whose elements ${elementNullability(many.elementNullable)}`;
-}
-function declarationFor(many) {
-	if (many === false) return "as one value, without .many() or many";
-	return many.elementNullable ? "as a list whose elements may be null, with .many({ elementsNullable: true }) or many: { elementNullable: true }" : "as a list whose elements are never null, with .many() or many: { elementNullable: false }";
-}
-function describeField(field) {
-	const value = `with codec ${field.codecId} that ${nullability(field.nullable)}`;
-	return field.many === false ? value : `${value} and whose elements ${elementNullability(field.many.elementNullable)}`;
+async function applyJunctionOwnedMutation(scope, context, parentNamespaceId, parentModelName, parentRow, relation, mutation) {
+	const contract = context.contract;
+	const parentPkValues = readJunctionParentValues(contract, parentNamespaceId, parentModelName, relation, parentRow);
+	assertJunctionPayloadWritable(relation, mutation.kind);
+	if (mutation.kind === "create") {
+		for (const childInput of mutation.data) await insertJunctionLink(scope, context, relation, parentPkValues, readJunctionTargetValues(contract, relation, await createGraph(scope, context, relation.relatedNamespaceId, relation.relatedModelName, castAs(childInput))), "create");
+		return;
+	}
+	if (mutation.kind === "connect") {
+		for (const criterion of mutation.criteria) await insertJunctionLink(scope, context, relation, parentPkValues, await resolveJunctionTargetValues(scope, context, relation, "connect", criterion), "connect");
+		return;
+	}
+	if (!mutation.criteria || mutation.criteria.length === 0) throw ormError("ORM.RELATION_MUTATION_INVALID", `disconnect() nested mutation for relation "${relation.relationName}" requires criterion`, { meta: {
+		kind: "disconnect",
+		relation: relation.relationName,
+		problem: "missing-criterion"
+	} });
+	for (const criterion of mutation.criteria) await deleteJunctionLink(scope, context, relation, parentPkValues, await resolveJunctionTargetValues(scope, context, relation, "disconnect", criterion));
 }
-function assertScopeFields(collection, fields) {
-	const { contract } = collection.ctx.context;
-	const { modelName, namespaceId } = collection;
-	const label = modelLabel(collection);
-	const model = modelOf(contract, namespaceId, modelName);
-	for (const [name, spec] of fields) {
-		const declared = `The scope was declared for models that have a ${spec.many === false ? "field" : "list field"} ${name} ${describeField(spec)}.`;
-		const meta = {
-			model: modelName,
-			namespace: namespaceId,
-			field: name,
-			codecId: spec.codecId,
-			nullable: spec.nullable,
-			many: spec.many
-		};
-		const modelFields = model?.fields ?? {};
-		if (!Object.hasOwn(modelFields, name)) throw ormError("ORM.FIELD_UNKNOWN", `Cannot apply a scope to ${label}: it has no field ${name}`, {
-			why: declared,
-			fix: `Apply the scope to a model that has a field ${name}, or remove ${name} from the declaration in the scope.`,
-			meta
-		});
-		const fieldMany = multiplicity(modelFields[name]?.many);
-		const column = resolveColumn(contract, namespaceId, collection.tableName, resolveFieldToColumn(contract, namespaceId, modelName, name));
-		const actual = column === void 0 ? `${label}.${name} has no column.` : fieldMany === false ? `${label}.${name} has codec ${column.codecId} and ${nullability(column.nullable)}.` : `${label}.${name} is a list ${describeField({
-			codecId: column.codecId,
-			nullable: column.nullable,
-			many: fieldMany
-		})}.`;
-		const sameCodecAndNullability = column?.codecId === spec.codecId && column.nullable === spec.nullable;
-		if (!sameCodecAndNullability || !sameMultiplicity(fieldMany, spec.many)) throw ormError("ORM.FIELD_UNKNOWN", `Cannot apply a scope to ${label}: its field ${name} does not match the declaration`, {
-			why: `${declared} ${actual}`,
-			fix: sameCodecAndNullability ? `Apply the scope to a model whose ${name} field ${fieldShape(spec.many)}, or declare ${name} ${declarationFor(fieldMany)}.` : `Apply the scope to a model whose ${name} field has that codec and nullability, or change the declaration in the scope.`,
-			meta
-		});
+async function preflightJunctionOwnedCreateMutation(scope, context, relationMutation) {
+	const { relation, mutation } = relationMutation;
+	assertJunctionMetadataShape(relation);
+	assertJunctionPayloadWritable(relation, mutation.kind);
+	if (mutation.kind !== "connect") return;
+	const seenTargetKeys = /* @__PURE__ */ new Set();
+	for (const criterion of mutation.criteria) {
+		const targetValues = await resolveJunctionTargetValues(scope, context, relation, "connect", criterion);
+		const targetKey = JSON.stringify([...targetValues.entries()]);
+		if (seenTargetKeys.has(targetKey)) throw ormError("ORM.RELATION_MUTATION_INVALID", `connect() nested mutation for relation "${relation.relationName}" resolved duplicate junction link targets; remove the duplicate criteria`, { meta: {
+			kind: "connect",
+			relation: relation.relationName,
+			problem: "duplicate-criteria"
+		} });
+		seenTargetKeys.add(targetKey);
 	}
 }
-/**
-* Define a scope for any model that has the declared fields. Reached as the `scope` method of the client `orm()` returns.
-*/
-function defineFieldScope(declarations, body) {
-	const fields = declaredFieldSpecs(declarations);
-	assertScopeBody(body);
-	return blindCast((collection) => {
-		const receiver = collection;
-		assertScopeReceiver(receiver);
-		assertScopeFields(receiver, fields);
-		const result = body(blindCast(collection));
-		assertScopeResult(receiver, result);
-		return result;
-	});
+function assertJunctionPayloadWritable(relation, mutationKind) {
+	const through = relation.through;
+	if (mutationKind !== "create" && mutationKind !== "connect" || through.requiredPayloadColumns.length === 0) return;
+	const cols = through.requiredPayloadColumns.map((c) => `\`${c}\``).join(", ");
+	throw ormError("ORM.RELATION_MUTATION_UNSUPPORTED", `Cannot \`${mutationKind}\` on relation \`${relation.relationName}\`: its junction \`${through.table}\` has required column(s) ${cols} the relation API can't populate. Write the \`${through.table}\` junction directly or use the SQL builder.`, { meta: {
+		kind: mutationKind,
+		relation: relation.relationName,
+		reason: "junction-required-columns",
+		junction: through.table
+	} });
 }
-const SHOWN_LENGTH = 64;
-function shown(value) {
-	const characters = Array.from(value);
-	const cut = characters.length > SHOWN_LENGTH;
-	return {
-		text: JSON.stringify(cut ? `${characters.slice(0, SHOWN_LENGTH).join("")}…` : value),
-		cut
-	};
+async function resolveJunctionTargetValues(scope, context, relation, kind, criterion) {
+	const relatedRow = await findRowByCriterion(scope, context, relation.relatedNamespaceId, relation.relatedModelName, criterion);
+	if (!relatedRow) throw ormError("ORM.RELATION_ROW_MISSING", `${kind}() nested mutation for relation "${relation.relationName}" did not find a matching row`, { meta: {
+		kind,
+		relation: relation.relationName
+	} });
+	return readJunctionTargetValues(context.contract, relation, relatedRow);
+}
+function readJunctionParentValues(contract, parentNamespaceId, parentModelName, relation, parentRow) {
+	const values = /* @__PURE__ */ new Map();
+	assertJunctionParentMetadataLength(relation);
+	for (let i = 0; i < relation.through.parentColumns.length; i++) {
+		const junctionColumn = relation.through.parentColumns[i];
+		const parentColumn = relation.localColumns[i];
+		if (junctionColumn === void 0 || parentColumn === void 0) throw new InternalError(`Relation "${relation.relationName}" has incomplete junction metadata for parent columns`);
+		const parentFieldName = toFieldName(contract, parentNamespaceId, parentModelName, parentColumn);
+		const parentValue = parentRow[parentFieldName];
+		if (parentValue === void 0) throw new InternalError(`Nested mutation requires parent field "${parentFieldName}" to be present in returned row`);
+		values.set(junctionColumn, parentValue);
+	}
+	return values;
 }
-function describeReceived(value) {
-	if (value === void 0 || value === null) return String(value);
-	if (Array.isArray(value)) return "an array";
-	const kind = typeof value;
-	return kind === "object" ? "an object" : `a ${kind}`;
+function readJunctionTargetValues(contract, relation, relatedRow) {
+	const values = /* @__PURE__ */ new Map();
+	assertJunctionTargetMetadataLength(relation);
+	for (let i = 0; i < relation.through.childColumns.length; i++) {
+		const junctionColumn = relation.through.childColumns[i];
+		const targetColumn = relation.through.targetColumns[i];
+		if (junctionColumn === void 0 || targetColumn === void 0) throw new InternalError(`Relation "${relation.relationName}" has incomplete junction metadata for target columns`);
+		const targetFieldName = toFieldName(contract, relation.relatedNamespaceId, relation.relatedModelName, targetColumn);
+		const targetValue = relatedRow[targetFieldName];
+		if (targetValue === void 0) throw new InternalError(`Nested mutation requires target field "${targetFieldName}" to be present in returned row`);
+		values.set(junctionColumn, targetValue);
+	}
+	return values;
 }
-function cutNote(subject, value) {
-	return value.cut ? ` The ${subject} above is cut to its first ${SHOWN_LENGTH} characters.` : "";
+function assertJunctionMetadataLength(relation, throughColumnName, throughColumns, pairedColumnName, pairedColumns) {
+	if (throughColumns.length === pairedColumns.length) return;
+	throw new InternalError(`Relation "${relation.relationName}" has invalid junction metadata: ${throughColumnName} has ${throughColumns.length} column(s), but ${pairedColumnName} has ${pairedColumns.length}`);
 }
-function fieldCodecId(collection, field) {
-	const { contract } = collection.ctx.context;
-	const column = resolveFieldToColumn(contract, collection.namespaceId, collection.modelName, field);
-	return resolveColumn(contract, collection.namespaceId, collection.tableName, column)?.codecId;
+function assertJunctionParentMetadataLength(relation) {
+	assertJunctionMetadataLength(relation, "parentColumns", relation.through.parentColumns, "localColumns", relation.localColumns);
 }
-function canOrder(collection, field) {
-	const codecId = fieldCodecId(collection, field);
-	return codecId !== void 0 && hasTrait(collection.ctx.context, codecId, "order");
+function assertJunctionTargetMetadataLength(relation) {
+	assertJunctionMetadataLength(relation, "childColumns", relation.through.childColumns, "targetColumns", relation.through.targetColumns);
 }
-function orderableFieldNames(collection) {
-	const model = modelOf(collection.ctx.context.contract, collection.namespaceId, collection.modelName);
-	return Object.keys(model?.fields ?? {}).filter((field) => canOrder(collection, field));
+function assertJunctionMetadataShape(relation) {
+	assertJunctionParentMetadataLength(relation);
+	assertJunctionTargetMetadataLength(relation);
 }
-function whyNotOrderable(collection, name) {
-	const { modelName } = collection;
-	const model = modelOf(collection.ctx.context.contract, collection.namespaceId, modelName);
-	const quoted = shown(name).text;
-	if (Object.hasOwn(model?.relations ?? {}, name)) return `${quoted} is a relation of ${modelName}, not a field.`;
-	if (!Object.hasOwn(model?.fields ?? {}, name)) return `${modelName} has no field ${quoted}.`;
-	return canOrder(collection, name) ? `${quoted} is not one of the fields allowed for ordering.` : `The codec ${fieldCodecId(collection, name)} of ${modelName}.${name} cannot be ordered.`;
+function writeJunctionColumn(junctionRow, through, column, value, relationName) {
+	if (Object.hasOwn(junctionRow, column) && !Object.is(junctionRow[column], value)) throw ormError("ORM.RELATION_MUTATION_INVALID", `Cannot write junction "${through.table}": conflicting values for junction column "${column}"`, { meta: {
+		relation: relationName,
+		junction: through.table,
+		column
+	} });
+	junctionRow[column] = value;
 }
-/**
-* An `orderBy` selector for a field named by a string, such as an order parameter of a request. `allowed` lists the fields a request may order by. A name that is not in `allowed` or not an orderable field of the collection's model, and a direction other than `asc` or `desc`, throw `ORM.ARGUMENT_INVALID`. An undefined direction is `asc`.
-*
-* ```ts
-* db.Post.orderBy(orderByField(db.Post, input.orderBy, input.direction, ['title', 'createdAt']));
-* ```
-*/
-function orderByField(collection, name, direction, allowed) {
-	const receiver = collection;
-	if (!isModelCollection(receiver)) throw ormError("ORM.ARGUMENT_INVALID", "Cannot order: orderByField was not given a collection", {
-		why: `orderByField takes the collection it orders, such as db.orm.public.Post; received ${describeReceived(receiver)}.`,
-		fix: "Pass the collection the selector is for as the first argument.",
-		meta: { argument: "collection" }
-	});
-	const { modelName } = collection;
-	const requestedName = name;
-	const requestedDirection = direction === void 0 ? "asc" : direction;
-	const allowedList = allowed;
-	if (!Array.isArray(allowedList) || allowedList.some((field) => typeof field !== "string")) throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName}: the allowed fields are not a list of names`, {
-		why: `orderByField takes the list of fields a request may order by; received ${describeReceived(allowedList)}.`,
-		fix: `Pass an array of field names of ${modelName}, such as ['title', 'createdAt'].`,
-		meta: {
-			model: modelName,
-			argument: "allowed"
-		}
-	});
-	if (typeof requestedDirection !== "string") throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName}: the direction is not a string`, {
-		why: `An order direction is "asc" or "desc"; received ${describeReceived(requestedDirection)}.`,
-		fix: "Pass \"asc\" or \"desc\".",
-		meta: {
-			model: modelName,
-			direction: requestedDirection
-		}
+async function insertJunctionLink(scope, context, relation, parentPkValues, targetPkValues, mutationKind) {
+	const through = relation.through;
+	const junctionRow = {};
+	for (const [column, value] of parentPkValues.entries()) writeJunctionColumn(junctionRow, through, column, value, relation.relationName);
+	for (const [column, value] of targetPkValues.entries()) writeJunctionColumn(junctionRow, through, column, value, relation.relationName);
+	const applied = context.applyMutationDefaults({
+		op: "create",
+		entry: through.table,
+		namespace: through.namespaceId,
+		values: junctionRow
 	});
-	if (!isOrderByDirection(requestedDirection)) {
-		const shownDirection = shown(requestedDirection);
-		throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName} in direction ${shownDirection.text}`, {
-			why: "An order direction is \"asc\" or \"desc\".",
-			fix: `Pass "asc" or "desc".${cutNote("direction", shownDirection)}`,
+	for (const def of applied) junctionRow[def.field] = def.value;
+	const compiled = compileInsertCount(context.contract, through.namespaceId, through.table, [junctionRow]);
+	try {
+		await scope.execute(compiled);
+	} catch (error) {
+		if (mutationKind === "connect" && isUniqueConstraintViolation(error)) throw ormError("ORM.RELATION_LINK_DUPLICATE", `connect() nested mutation for relation "${relation.relationName}" violated a unique constraint on junction "${through.table}"; the junction link may already be present`, {
 			meta: {
-				model: modelName,
-				direction: requestedDirection
-			}
+				relation: relation.relationName,
+				junction: through.table
+			},
+			cause: error
 		});
+		throw error;
 	}
-	const orderable = orderableFieldNames(collection);
-	const names = allowedList.filter((field) => orderable.includes(field));
-	const orderByOneOf = names.length === 0 ? `Pass an allowed list that names at least one field of ${modelName} that can be ordered.` : `Order by one of: ${names.join(", ")}.`;
-	if (typeof requestedName !== "string") throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName}: the field name is not a string`, {
-		why: `An order field name is a string; received ${describeReceived(requestedName)}.`,
-		fix: orderByOneOf,
-		meta: {
-			model: modelName,
-			field: requestedName
-		}
+}
+async function deleteJunctionLink(scope, context, relation, parentPkValues, targetPkValues) {
+	const through = relation.through;
+	const junctionRow = {};
+	for (const [column, value] of parentPkValues.entries()) writeJunctionColumn(junctionRow, through, column, value, relation.relationName);
+	for (const [column, value] of targetPkValues.entries()) writeJunctionColumn(junctionRow, through, column, value, relation.relationName);
+	const exprs = [];
+	for (const [column, value] of Object.entries(junctionRow)) exprs.push(BinaryExpr.eq(ColumnRef.of(through.table, column), LiteralExpr.of(value)));
+	const first = exprs[0];
+	const where = exprs.length === 1 && first !== void 0 ? first : and(...exprs);
+	const compiled = compileDeleteCount(context.contract, through.namespaceId, through.table, [where]);
+	await scope.execute(compiled);
+}
+function readParentColumnValues(contract, parentNamespaceId, parentModelName, relation, parentRow) {
+	const values = /* @__PURE__ */ new Map();
+	for (let i = 0; i < relation.localColumns.length; i++) {
+		const localColumn = relation.localColumns[i];
+		const targetColumn = relation.targetColumns[i];
+		if (!localColumn || !targetColumn) continue;
+		const parentFieldName = toFieldName(contract, parentNamespaceId, parentModelName, localColumn);
+		const parentValue = parentRow[parentFieldName];
+		if (parentValue === void 0) throw new InternalError(`Nested mutation requires parent field "${parentFieldName}" to be present in returned row`);
+		values.set(targetColumn, parentValue);
+	}
+	return values;
+}
+function buildChildJoinWhere(relation, childValues) {
+	const exprs = [];
+	for (const [childColumn, parentValue] of childValues.entries()) exprs.push(BinaryExpr.eq(ColumnRef.of(relation.relatedTableName, childColumn), LiteralExpr.of(parentValue)));
+	const first = exprs[0];
+	if (exprs.length === 1 && first !== void 0) return first;
+	return and(...exprs);
+}
+async function insertSingleRow(scope, context, namespaceId, modelName, data) {
+	const contract = context.contract;
+	const tableName = resolveModelTableName(contract, namespaceId, modelName);
+	const mappedData = mapModelDataToStorageRow(contract, namespaceId, modelName, data);
+	const applied = context.applyMutationDefaults({
+		op: "create",
+		entry: tableName,
+		namespace: namespaceId,
+		values: mappedData
 	});
-	if (!names.includes(requestedName)) {
-		const shownName = shown(requestedName);
-		throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName} by ${shownName.text}`, {
-			why: whyNotOrderable(collection, requestedName),
-			fix: `${orderByOneOf}${cutNote("name", shownName)}`,
-			meta: {
-				model: modelName,
-				field: requestedName
-			}
-		});
+	for (const def of applied) mappedData[def.field] = def.value;
+	const firstRow = (await queryPlanRows(scope, compileInsertReturning(contract, namespaceId, tableName, [mappedData], void 0)).toArray())[0];
+	if (!firstRow) throw ormError("ORM.MUTATION_ROW_MISSING", `Nested create for model "${modelName}" did not return a row`, { meta: {
+		operation: "create",
+		model: modelName,
+		phase: "nested"
+	} });
+	return mapStorageRowToModelFields(contract, namespaceId, modelName, firstRow);
+}
+async function findRowByCriterion(scope, context, namespaceId, modelName, criterion) {
+	const contract = context.contract;
+	const whereExpr = shorthandToWhereExpr(context, namespaceId, modelName, castAs(criterion));
+	if (!whereExpr) throw ormError("ORM.RELATION_MUTATION_INVALID", `Nested connect for model "${modelName}" requires non-empty criterion`, { meta: {
+		kind: "connect",
+		model: modelName,
+		problem: "empty-criterion"
+	} });
+	const firstRow = (await queryPlanRows(scope, compileSelect(contract, namespaceId, resolveModelTableName(contract, namespaceId, modelName), {
+		...emptyState(),
+		filters: [whereExpr],
+		limit: 1
+	})).toArray())[0];
+	if (!firstRow) return null;
+	return mapStorageRowToModelFields(contract, namespaceId, modelName, firstRow);
+}
+async function findFirstByFilters(scope, contract, namespaceId, modelName, filters) {
+	const firstRow = (await queryPlanRows(scope, compileSelect(contract, namespaceId, resolveModelTableName(contract, namespaceId, modelName), {
+		...emptyState(),
+		filters,
+		limit: 1
+	})).toArray())[0];
+	if (!firstRow) return null;
+	return mapStorageRowToModelFields(contract, namespaceId, modelName, firstRow);
+}
+async function executeUpdateCount(scope, contract, namespaceId, tableName, setValues, filters) {
+	const compiled = compileUpdateCount(contract, namespaceId, tableName, setValues, filters);
+	await scope.execute(compiled);
+}
+const relationDefsCache = /* @__PURE__ */ new WeakMap();
+function getRelationDefinitions(contract, namespaceId, modelName) {
+	let perContract = relationDefsCache.get(contract);
+	if (!perContract) {
+		perContract = /* @__PURE__ */ new Map();
+		relationDefsCache.set(contract, perContract);
 	}
-	const field = blindCast(requestedName);
-	const order = requestedDirection;
-	return (row) => row[field][order]();
+	const cacheKey = JSON.stringify([namespaceId, modelName]);
+	const cached = perContract.get(cacheKey);
+	if (cached) return cached;
+	const relations = resolveModelRelations(contract, namespaceId, modelName);
+	const definitions = Object.entries(relations).map(([relationName, relation]) => ({
+		relationName,
+		relatedModelName: relation.to,
+		relatedNamespaceId: relation.toNamespace,
+		relatedTableName: resolveModelTableName(contract, relation.toNamespace, relation.to),
+		cardinality: relation.cardinality,
+		localColumns: relation.on.localFields.map((f) => resolveFieldToColumn(contract, namespaceId, modelName, f)),
+		targetColumns: relation.on.targetFields.map((f) => resolveFieldToColumn(contract, relation.toNamespace, relation.to, f)),
+		through: relation.through ? {
+			table: relation.through.table,
+			namespaceId: relation.through.namespaceId,
+			parentColumns: relation.through.parentColumns,
+			childColumns: relation.through.childColumns,
+			targetColumns: relation.through.targetColumns,
+			requiredPayloadColumns: relation.through.requiredPayloadColumns
+		} : void 0
+	}));
+	perContract.set(cacheKey, definitions);
+	return definitions;
+}
+function toFieldName(contract, namespaceId, modelName, columnName) {
+	return getColumnToFieldMap(contract, namespaceId, modelName)[columnName] ?? columnName;
 }
 function normalizeWhereArg(arg, options) {
 	if (arg === void 0) return;
@@ -4218,7 +4218,7 @@ function listed(items, conjunction) {
 	const last = items.at(-1) ?? "";
 	return items.length > 1 ? `${items.slice(0, -1).join(", ")} ${conjunction} ${last}` : last;
 }
-const HIDDEN_BY_A_SCOPE = "A scope passed to with can add one without showing it at the call site.";
+const HIDDEN_BY_A_FRAGMENT = "A fragment passed to with can add one without showing it at the call site.";
 /** Throws `ORM.ARGUMENT_INVALID` when the collection has a limit, an offset, a cursor or a distinct selection, which `method`, a write of every matching row, would ignore. */
 function assertBulkWriteIgnoresNothing(state, modelName, method) {
 	const { nouns, calls } = presentParts(state, [
@@ -4231,7 +4231,7 @@ function assertBulkWriteIgnoresNothing(state, modelName, method) {
 	if (nouns.length === 0) return;
 	const { limit, offset, cursor, distinct, distinctOn } = state;
 	throw ormError("ORM.ARGUMENT_INVALID", `Cannot ${method} ${modelName}: the collection has ${listed(nouns, "and")}`, {
-		why: `${method} changes every row that matches the filter. The statement it runs cannot apply ${listed(nouns, "or")}, so it would change more rows than the chain asks for. ${HIDDEN_BY_A_SCOPE}`,
+		why: `${method} changes every row that matches the filter. The statement it runs cannot apply ${listed(nouns, "or")}, so it would change more rows than the chain asks for. ${HIDDEN_BY_A_FRAGMENT}`,
 		fix: `Remove ${listed(calls, "and")} before ${method}, or read the rows first and change them by their ids.`,
 		meta: {
 			model: modelName,
@@ -4257,7 +4257,7 @@ function assertRelationUpdateIgnoresNothing(state, modelName) {
 	if (nouns.length === 0) return;
 	const { orderBy, limit, offset, cursor, distinct, distinctOn } = state;
 	throw ormError("ORM.ARGUMENT_INVALID", `Cannot update ${modelName} with a relation mutation: the collection has ${listed(nouns, "and")}`, {
-		why: `An update that changes a relation finds its row by the filter alone. It would ignore ${listed(nouns, "and")}, and could change another row than first() returns. ${HIDDEN_BY_A_SCOPE}`,
+		why: `An update that changes a relation finds its row by the filter alone. It would ignore ${listed(nouns, "and")}, and could change another row than first() returns. ${HIDDEN_BY_A_FRAGMENT}`,
 		fix: `Remove ${listed(calls, "and")} before update, or filter to the one row, such as by its id.`,
 		meta: {
 			model: modelName,
@@ -4393,21 +4393,21 @@ var CollectionBase = class CollectionBase {
 		return fn(this);
 	}
 	/**
-	* Define a scope for this collection's model, such as a shared `select` and `include`. The body is typed once, against the model's plain collection. The scope accepts any collection of the model that `select` and `variant` have not narrowed.
+	* Define a query fragment for this collection's model, such as a shared `select` and `include`. The body is typed once, against the model's plain collection. The fragment accepts any collection of the model that `select` and `variant` have not narrowed.
 	*
 	* ```ts
-	* const summary = db.Post.scope((posts) => posts.select('id', 'title').include('user'));
+	* const summary = db.Post.fragment((posts) => posts.select('id', 'title').include('user'));
 	* db.User.include('posts', (posts) => posts.with(summary));
 	* ```
 	*/
-	scope(body) {
-		assertScopeBody(body);
+	fragment(body) {
+		assertFragmentBody(body);
 		const source = {
 			modelName: this.modelName,
 			namespaceId: this.namespaceId
 		};
 		return (collection) => {
-			assertModelScopeReceiver(source, collection);
+			assertModelFragmentReceiver(source, collection);
 			return body(blindCast(collection));
 		};
 	}
@@ -5438,7 +5438,7 @@ function orm(options) {
 	return new Proxy({}, { get(_target, prop) {
 		if (typeof prop !== "string") return;
 		if (Object.hasOwn(contract.domain.namespaces, prop)) return namespaceFacet(prop);
-		return prop === "scope" ? defineFieldScope : void 0;
+		return prop === "fragment" ? defineFieldFragment : void 0;
 	} });
 }
 function createCollectionRegistry(contract, collections) {