@prisma/orm-family-sql 8.0.0-rc.2-dev.3 → 8.0.0-rc.20-dev.1

package/dist/builder__runtime.mjs

@@ -1,9 +1,12 @@
-import { C as LiteralExpr, D as OrExpr, F as SubqueryExpr, I as TableSource, L as UpdateAst, O as OrderByItem, P as SelectAst, S as ListExpression, T as NullCheckExpr, V as isAggregateFn, _ as InsertAst, c as DeleteAst, g as IdentifierRef, j as ProjectionItem, k as ParamRef, l as DerivedTableSource, n as AndExpr, o as ColumnRef, p as ExistsExpr, r as BinaryExpr, t as AggregateExpr, y as JoinAst } from "./types-Dt4e_jC--COeP8xzN.mjs";
-import { t as collectOrderedParamRefs } from "./util-DQQgv2j1-D6INZaRG.mjs";
-import { a as toExpr, n as codecOf, r as createRawSql } from "./expression-CX5mTA-z.mjs";
-import { n as codecRefForStorageColumn } from "./codec-descriptor-registry-N0dhtKaH.mjs";
+import { A as ParamRef, F as SelectAst, G as isOrderByNulls, L as TableSource, M as ProjectionItem, R as UpdateAst, U as isAggregateFn, W as isOrderByDirection, _ as InsertAst, c as DeleteAst, g as IdentifierRef, k as OrderByItem, l as DerivedTableSource, n as AndExpr, o as ColumnRef, t as AggregateExpr, w as LockingClause, y as JoinAst } from "./types-NTQsD2MS-xcLtvKO9.mjs";
+import { r as isAggregateProjection, t as collectOrderedParamRefs } from "./util-BBgcP3gI-CpL-0VuC.mjs";
+import { D as lockWaitPolicyOf, E as lockStrengthCapabilities, T as lockOptionCapabilities, w as lockIncompatible } from "./ast-D0miQ1B6.mjs";
+import { i as createRawSql, s as toExpr, t as ExpressionImpl } from "./expression-impl-B-XNINxr-BhN2sysZ.mjs";
+import { n as codecRefForStorageColumn } from "./codec-descriptor-registry-CiiFzMtb.mjs";
+import { t as createFunctions } from "./functions-CsOoN7I3.mjs";
+import { t as createIndexReferences } from "./index-reference-BQSrkRfT.mjs";
 import { assertAnnotationsApplicable } from "@prisma/orm-framework/components/runtime";
-//#region ../../../2-sql/4-lanes/sql-builder/dist/runtime/index.mjs
+//#region ../../../2-sql-family/4-lanes/sql-builder/dist/runtime/index.mjs
 /**
 * **Last-resort escape hatch for unsafe type assertions. Not a sanctioned tool to reach for.**
 *
@@ -42,6 +45,55 @@ import { assertAnnotationsApplicable } from "@prisma/orm-framework/components/ru
 function blindCast(input) {
 	return input;
 }
+function createFieldProxy(scope) {
+	return new Proxy(blindCast({}), { get(_target, prop) {
+		if (Object.hasOwn(scope.topLevel, prop)) {
+			const topField = scope.topLevel[prop];
+			if (topField) return new ExpressionImpl(IdentifierRef.of(prop), topField);
+		}
+		if (Object.hasOwn(scope.namespaces, prop)) {
+			const nsFields = scope.namespaces[prop];
+			if (nsFields) return createNamespaceProxy(prop, nsFields);
+		}
+	} });
+}
+function createNamespaceProxy(namespaceName, fields) {
+	return new Proxy({}, { get(_target, prop) {
+		if (Object.hasOwn(fields, prop)) {
+			const field = fields[prop];
+			if (field) return new ExpressionImpl(ColumnRef.of(namespaceName, prop), field);
+		}
+	} });
+}
+/**
+* A bug in Prisma 8, not a user error. Never catch this except at the
+* outermost boundary for crash reporting — an InternalError means an invariant
+* broke and the process cannot reliably continue. User-facing failures use
+* `structuredError` with a dotted code instead.
+*/
+var InternalError = class extends Error {
+	isPrismaInternalError = true;
+	constructor(message, options) {
+		super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
+		this.name = "InternalError";
+	}
+};
+/**
+* Asserts that a value is defined (not null or undefined).
+* Use for invariants where the value should always exist at runtime.
+*
+* @throws Error if value is null or undefined
+*
+* @example
+* ```typescript
+* const table = storage.namespaces[namespaceId].entries.table[tableName];
+* assertDefined(table, `Table "${tableName}" not found`);
+* // table is now narrowed to non-nullable
+* ```
+*/
+function assertDefined(value, message) {
+	if (value === null || value === void 0) throw new InternalError(message);
+}
 /**
 * Returns an object with the key/value if value is defined, otherwise an empty object.
 *
@@ -85,31 +137,6 @@ function structuredError(code, message, options) {
 	});
 }
 /**
-* Runtime wrapper around a relational-core AST expression node. Carries ScopeField metadata (codecId, nullable) so aggregate-like combinators can propagate the input codec onto their result.
-*
-* `codec` records the column-bound {@link CodecRef} when the field-proxy knows the binding — both the namespaced form (`f.user.email` → `ColumnRef`) and the top-level shortcut (`f.email` → `IdentifierRef`) stamp the ref derived from contract storage. `codecOf(expression)` exposes it for operation implementations forwarding the ref to `toExpr`.
-*
-* `projectionAst` carries the descriptor-lowered rendering of the expression, where a target declares one (e.g. SQLite's `CAST(count(*) AS TEXT)`). Lowering exists to carry the value across the driver boundary, so only the projection site consumes it — predicate and ordering positions (`buildAst()`) keep the plain form, where the rendering would change SQL semantics.
-*/
-var ExpressionImpl = class {
-	ast;
-	projectionAst;
-	returnType;
-	codec;
-	constructor(ast, returnType, codec, projectionAst) {
-		this.ast = ast;
-		this.returnType = returnType;
-		this.codec = codec;
-		this.projectionAst = projectionAst;
-	}
-	buildAst() {
-		return this.ast;
-	}
-	buildProjectionAst() {
-		return this.projectionAst ?? this.ast;
-	}
-};
-/**
 * An aggregate whose operation lies outside the SQL aggregate alphabet: the expression exists only in its descriptor-lowered form, so only the projection may consume it.
 *
 * Predicate and ordering positions build the plain form through `buildAst()` and are refused at authoring time — the lowered rendering exists to carry the value across the driver boundary, and comparing or sorting by it inside the database would change SQL semantics (a textual rendering compares lexicographically).
@@ -117,7 +144,7 @@ var ExpressionImpl = class {
 var ProjectionOnlyExpressionImpl = class extends ExpressionImpl {
 	operation;
 	constructor(operation, lowered, returnType) {
-		super(lowered, returnType, void 0, lowered);
+		super(lowered, returnType, lowered);
 		this.operation = operation;
 	}
 	buildAst() {
@@ -134,111 +161,6 @@ var ProjectionOnlyExpressionImpl = class extends ExpressionImpl {
 function projectionAstOf(expr) {
 	return expr instanceof ExpressionImpl ? expr.buildProjectionAst() : expr.buildAst();
 }
-function createFieldProxy(scope) {
-	return new Proxy({}, { get(_target, prop) {
-		if (Object.hasOwn(scope.topLevel, prop)) {
-			const topField = scope.topLevel[prop];
-			if (topField) return new ExpressionImpl(IdentifierRef.of(prop), topField, topField.codec);
-		}
-		if (Object.hasOwn(scope.namespaces, prop)) {
-			const nsFields = scope.namespaces[prop];
-			if (nsFields) return createNamespaceProxy(prop, nsFields);
-		}
-	} });
-}
-function createNamespaceProxy(namespaceName, fields) {
-	return new Proxy({}, { get(_target, prop) {
-		if (Object.hasOwn(fields, prop)) {
-			const field = fields[prop];
-			if (field) return new ExpressionImpl(ColumnRef.of(namespaceName, prop), field, field.codec);
-		}
-	} });
-}
-/**
-* A bug in Prisma Next, not a user error. Never catch this except at the
-* outermost boundary for crash reporting — an InternalError means an invariant
-* broke and the process cannot reliably continue. User-facing failures use
-* `structuredError` with a dotted code instead.
-*/
-var InternalError = class extends Error {
-	isPrismaInternalError = true;
-	constructor(message, options) {
-		super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
-		this.name = "InternalError";
-	}
-};
-/**
-* Asserts that a value is defined (not null or undefined).
-* Use for invariants where the value should always exist at runtime.
-*
-* @throws Error if value is null or undefined
-*
-* @example
-* ```typescript
-* const table = storage.namespaces[namespaceId].entries.table[tableName];
-* assertDefined(table, `Table "${tableName}" not found`);
-* // table is now narrowed to non-nullable
-* ```
-*/
-function assertDefined(value, message) {
-	if (value === null || value === void 0) throw new InternalError(message);
-}
-const BOOL_FIELD = {
-	codecId: "pg/bool@1",
-	nullable: false
-};
-const resolve = toExpr;
-/**
-* Resolve a binary-comparison operand into an AST expression, threading the column-bound side's {@link CodecRef} to the raw-value side.
-*
-* For `fns.eq(f.email, 'alice@example.com')`, `f.email` is the column-bound expression carrying a `ColumnRef` AST and a `CodecRef` derived from contract storage; the raw string operand has no codec context. By deriving the codec context from the column-bound side and forwarding it via `toExpr(value, codec)`, the resulting `ParamRef` carries the `CodecRef` that encode-side dispatch needs to materialise the per-instance codec for parameterized codec ids (`vector(1024)` vs. `vector(1536)`).
-*/
-function resolveOperand(operand, otherCodec) {
-	if (isExpressionLike(operand)) return operand.buildAst();
-	return toExpr(operand, otherCodec);
-}
-function isExpressionLike(value) {
-	return typeof value === "object" && value !== null && "buildAst" in value && typeof value.buildAst === "function";
-}
-/**
-* Resolves an Expression via `buildAst()`, or wraps a raw value as a `LiteralExpr` — an SQL literal inlined into the query text, not a bound parameter.
-*
-* Used for `and` / `or` operands. The usual operand is an `Expression<bool>` (e.g. the result of `fns.eq`), which this function passes through by calling `buildAst()`. The only time the raw-value branch fires is when the caller writes `fns.and(true, x)` or similar — inlining `TRUE`/`FALSE` literals lets the SQL planner statically simplify `TRUE AND x` to `x`, which it cannot do for an opaque `ParamRef`.
-*/
-function toLiteralExpr(value) {
-	if (typeof value === "object" && value !== null && "buildAst" in value && typeof value.buildAst === "function") return value.buildAst();
-	return new LiteralExpr(value);
-}
-function boolExpr(astNode) {
-	return new ExpressionImpl(astNode, BOOL_FIELD);
-}
-function binaryWithSharedCodec(a, b, build) {
-	const aCodec = codecOf(a);
-	return build(resolveOperand(a, codecOf(b)), resolveOperand(b, aCodec));
-}
-function eq(a, b) {
-	if (b === null) return boolExpr(NullCheckExpr.isNull(resolve(a)));
-	if (a === null) return boolExpr(NullCheckExpr.isNull(resolve(b)));
-	return boolExpr(binaryWithSharedCodec(a, b, (l, r) => new BinaryExpr("eq", l, r)));
-}
-function ne(a, b) {
-	if (b === null) return boolExpr(NullCheckExpr.isNotNull(resolve(a)));
-	if (a === null) return boolExpr(NullCheckExpr.isNotNull(resolve(b)));
-	return boolExpr(binaryWithSharedCodec(a, b, (l, r) => new BinaryExpr("neq", l, r)));
-}
-function comparison(a, b, op) {
-	return boolExpr(binaryWithSharedCodec(a, b, (l, r) => new BinaryExpr(op, l, r)));
-}
-function inOrNotIn(expr, valuesOrSubquery, op) {
-	const left = expr.buildAst();
-	const leftCodec = codecOf(expr);
-	const binaryFn = op === "in" ? BinaryExpr.in : BinaryExpr.notIn;
-	if (Array.isArray(valuesOrSubquery)) {
-		const refs = valuesOrSubquery.map((v) => resolveOperand(v, leftCodec));
-		return boolExpr(binaryFn(left, ListExpression.of(refs)));
-	}
-	return boolExpr(binaryFn(left, SubqueryExpr.of(valuesOrSubquery.buildAst())));
-}
 /**
 * Build an aggregate through the target's own answer for it.
 *
@@ -294,24 +216,7 @@ function aggregate(aggregates, operation, expr) {
 		expr: inputAst,
 		inputCodec
 	});
-	return new ExpressionImpl(ast, returnType, void 0, projectionAst);
-}
-function createBuiltinFunctions(rawCodecInferer) {
-	return {
-		eq: (a, b) => eq(a, b),
-		ne: (a, b) => ne(a, b),
-		gt: (a, b) => comparison(a, b, "gt"),
-		gte: (a, b) => comparison(a, b, "gte"),
-		lt: (a, b) => comparison(a, b, "lt"),
-		lte: (a, b) => comparison(a, b, "lte"),
-		and: (...exprs) => boolExpr(AndExpr.of(exprs.map(toLiteralExpr))),
-		or: (...exprs) => boolExpr(OrExpr.of(exprs.map(toLiteralExpr))),
-		exists: (subquery) => boolExpr(ExistsExpr.exists(subquery.buildAst())),
-		notExists: (subquery) => boolExpr(ExistsExpr.notExists(subquery.buildAst())),
-		in: (expr, valuesOrSubquery) => inOrNotIn(expr, valuesOrSubquery, "in"),
-		notIn: (expr, valuesOrSubquery) => inOrNotIn(expr, valuesOrSubquery, "notIn"),
-		raw: createRawSql(rawCodecInferer)
-	};
+	return new ExpressionImpl(ast, returnType, projectionAst);
 }
 /**
 * The aggregate implementations, one per operation the registry contributes,
@@ -332,22 +237,28 @@ function createAggregateOnlyFunctions(aggregates) {
 	}
 	return Object.fromEntries(methods);
 }
-function createFunctions(operations, rawCodecInferer) {
-	const builtins = createBuiltinFunctions(rawCodecInferer);
-	return new Proxy({}, { get(_target, prop) {
-		if (Object.hasOwn(builtins, prop)) return builtins[prop];
-		const op = operations[prop];
-		if (op) return op.impl;
-	} });
-}
 function createAggregateFunctions(operations, rawCodecInferer, aggregateRegistry) {
 	const baseFns = createFunctions(operations, rawCodecInferer);
 	const aggregates = createAggregateOnlyFunctions(aggregateRegistry);
-	return new Proxy({}, { get(_target, prop) {
+	return new Proxy(blindCast({}), { get(_target, prop) {
 		if (Object.hasOwn(aggregates, prop)) return aggregates[prop];
-		return baseFns[prop];
+		return blindCast(baseFns)[prop];
 	} });
 }
+/**
+* Builds the raw lane a client exposes as `db.raw`.
+*
+* The tag binds the adapter's codec inferer and the contract here, once. An
+* authoring site then carries only its template, its row spec, and a
+* terminator.
+*
+* The row type is phantom: no value holds it. The target-agnostic tag types it
+* as `unknown`, and the contract says what each declared column decodes to.
+*/
+function createRawLane(options) {
+	const tag = blindCast(createRawSql(options.rawCodecInferer, { contract: options.context.contract }));
+	return Object.freeze({ sql: tag });
+}
 function resolveTableInNamespace(storage, namespaceId, tableName) {
 	const namespace = storage.namespaces[namespaceId];
 	if (namespace === void 0) return void 0;
@@ -355,6 +266,83 @@ function resolveTableInNamespace(storage, namespaceId, tableName) {
 	if (tables === void 0 || !Object.hasOwn(tables, tableName)) return void 0;
 	return tables[tableName];
 }
+const NOTHING = {
+	columns: [],
+	subqueries: []
+};
+/** The columns an expression reads itself, and the subqueries inside it, which read their own sources. */
+function readsOf(expression) {
+	return expression.fold({
+		empty: NOTHING,
+		combine: (a, b) => ({
+			columns: [...a.columns, ...b.columns],
+			subqueries: [...a.subqueries, ...b.subqueries]
+		}),
+		columnRef: (columnRef) => ({
+			columns: [columnRef],
+			subqueries: []
+		}),
+		select: (subquery) => ({
+			columns: [],
+			subqueries: [subquery]
+		})
+	});
+}
+function aliasOf(source) {
+	return source.kind === "table-source" ? source.alias ?? source.name : source.alias;
+}
+function assertReadsIn(expressions, visible) {
+	for (const expression of expressions) {
+		const { columns, subqueries } = readsOf(expression);
+		for (const column of columns) if (!visible.has(column.table)) throw columnOutsideQuery(column, visible);
+		for (const subquery of subqueries) assertSelectReads(subquery, visible);
+	}
+}
+function assertSelectReads(select, outer) {
+	const sources = [select.from, ...(select.joins ?? []).map((join) => join.source)].filter((source) => source !== void 0);
+	const visible = /* @__PURE__ */ new Set([...outer, ...sources.map(aliasOf).filter((alias) => alias !== void 0)]);
+	for (const source of sources) {
+		if (source.kind === "derived-table-source") assertSelectReads(source.query, visible);
+		if (source.kind === "function-source") assertReadsIn(source.args, visible);
+	}
+	assertReadsIn([
+		...select.projection.map((item) => item.expr),
+		...select.where === void 0 ? [] : [select.where],
+		...(select.orderBy ?? []).map((item) => item.expr),
+		...select.groupBy ?? [],
+		...select.having === void 0 ? [] : [select.having],
+		...select.distinctOn ?? [],
+		...(select.joins ?? []).flatMap((join) => join.on.kind === "eq-col-join-on" ? [join.on.left, join.on.right] : [join.on])
+	], visible);
+}
+/**
+* Refuses a statement that reads a column of an alias none of its sources, or of the queries around it, has. An expression built outside the query's callbacks, such as an index read from `table.as('other').indexes`, can name any alias.
+*/
+function assertColumnsInScope(ast) {
+	switch (ast.kind) {
+		case "select":
+			assertSelectReads(ast, /* @__PURE__ */ new Set());
+			return;
+		case "update":
+			assertReadsIn([...Object.values(ast.set), ...ast.where === void 0 ? [] : [ast.where]], /* @__PURE__ */ new Set([aliasOf(ast.table) ?? ast.table.name]));
+			return;
+		case "delete":
+			assertReadsIn(ast.where === void 0 ? [] : [ast.where], /* @__PURE__ */ new Set([aliasOf(ast.table) ?? ast.table.name]));
+			return;
+		default: return;
+	}
+}
+function columnOutsideQuery(column, visible) {
+	const sources = [...visible];
+	return structuredError("ORM.ARGUMENT_INVALID", `The query reads column "${column.column}" of "${column.table}", which is not one of its sources (${sources.map((source) => `"${source}"`).join(", ")}).`, {
+		fix: "Read the column, or the index, from a table the query selects from or joins, under the alias it has in the query.",
+		meta: {
+			alias: column.table,
+			column: column.column,
+			sources
+		}
+	});
+}
 var BuilderBase = class {
 	ctx;
 	constructor(ctx) {
@@ -387,6 +375,7 @@ function emptyState(from, scope) {
 		offset: void 0,
 		distinct: void 0,
 		distinctOn: void 0,
+		locking: void 0,
 		scope,
 		rowFields: {},
 		annotations: /* @__PURE__ */ new Map()
@@ -403,7 +392,33 @@ function combineWhereExprs(exprs) {
 	if (exprs.length === 1) return exprs[0];
 	return AndExpr.of(exprs);
 }
+const lockConflictKinds = [
+	"distinct",
+	"distinctOn",
+	"groupBy",
+	"having"
+];
+function lockConflictOf(state) {
+	const conflicts = {
+		distinct: state.distinct !== void 0,
+		distinctOn: state.distinctOn !== void 0 && state.distinctOn.length > 0,
+		groupBy: state.groupBy.length > 0,
+		having: state.having !== void 0
+	};
+	return lockConflictKinds.find((conflict) => conflicts[conflict]);
+}
+function assertLockable(state) {
+	if (state.locking === void 0) return;
+	const conflict = lockConflictOf(state);
+	if (conflict !== void 0) throw lockIncompatible(conflict, `A locking clause cannot be combined with ${conflict}`);
+	const item = state.projections.find(isAggregateProjection);
+	if (item !== void 0) throw lockIncompatible("aggregate", `A locking clause cannot be combined with an aggregate or window function in the projection (column "${item.alias}")`);
+}
+function assertNotLocked(state) {
+	if (state.locking !== void 0) throw lockIncompatible("subquery", "A locked select cannot be used as a subquery");
+}
 function buildSelectAst(state) {
+	assertLockable(state);
 	const where = combineWhereExprs(state.where);
 	return new SelectAst({
 		from: state.from,
@@ -417,10 +432,12 @@ function buildSelectAst(state) {
 		having: state.having,
 		limit: state.limit,
 		offset: state.offset,
+		locking: state.locking,
 		selectAllIntent: void 0
 	});
 }
 function buildQueryPlan(ast, ctx, annotations) {
+	assertColumnsInScope(ast);
 	const paramValues = collectOrderedParamRefs(ast).map((r) => r.kind === "param-ref" ? r.value : void 0);
 	const annotationsRecord = annotations !== void 0 && annotations.size > 0 ? Object.freeze(Object.fromEntries(annotations)) : void 0;
 	const meta = Object.freeze({
@@ -501,6 +518,10 @@ function assertCapability(ctx, required, methodName) {
 		capability: `${ns}.${key}`
 	} });
 }
+function codecRefOf(field, ctx) {
+	if (field.codec !== void 0) return field.codec;
+	return ctx.materializesWithoutTypeParams(field.codecId) ? { codecId: field.codecId } : void 0;
+}
 function resolveSelectArgs(args, scope, ctx) {
 	const projections = [];
 	const newRowFields = {};
@@ -512,7 +533,7 @@ function resolveSelectArgs(args, scope, ctx) {
 		for (const colName of args) {
 			const field = scope.topLevel[colName];
 			if (!field) throw structuredError("ORM.COLUMN_UNKNOWN", `Column "${colName}" not found in scope`, { meta: { column: colName } });
-			projections.push(ProjectionItem.of(colName, IdentifierRef.of(colName), field.codec));
+			projections.push(ProjectionItem.of(colName, IdentifierRef.of(colName), codecRefOf(field, ctx)));
 			newRowFields[colName] = field;
 		}
 		return {
@@ -526,7 +547,7 @@ function resolveSelectArgs(args, scope, ctx) {
 		const fns = createAggregateFunctions(ctx.queryOperationTypes, ctx.rawCodecInferer, ctx.aggregates);
 		const result = exprFn(createFieldProxy(scope), fns);
 		const field = result.returnType;
-		projections.push(ProjectionItem.of(alias, projectionAstOf(result), field.codec));
+		projections.push(ProjectionItem.of(alias, projectionAstOf(result), codecRefOf(field, ctx)));
 		newRowFields[alias] = field;
 		return {
 			projections,
@@ -539,7 +560,7 @@ function resolveSelectArgs(args, scope, ctx) {
 		const record = callbackFn(createFieldProxy(scope), fns);
 		for (const [key, expr] of Object.entries(record)) {
 			const field = expr.returnType;
-			projections.push(ProjectionItem.of(key, projectionAstOf(expr), field.codec));
+			projections.push(ProjectionItem.of(key, projectionAstOf(expr), codecRefOf(field, ctx)));
 			newRowFields[key] = field;
 		}
 		return {
@@ -550,17 +571,19 @@ function resolveSelectArgs(args, scope, ctx) {
 	throw structuredError("ORM.ARGUMENT_INVALID", "Invalid .select() arguments");
 }
 function resolveOrderBy(arg, options, scope, rowFields, ctx, useAggregateFns) {
-	const dir = options?.direction ?? "asc";
+	const direction = options?.direction ?? "asc";
+	const nulls = options?.nulls;
+	if (!isOrderByDirection(direction)) throw structuredError("ORM.ARGUMENT_INVALID", "orderBy direction must be \"asc\" or \"desc\"", { meta: { direction: String(direction) } });
+	if (nulls !== void 0 && !isOrderByNulls(nulls)) throw structuredError("ORM.ARGUMENT_INVALID", "orderBy nulls must be \"first\" or \"last\"", { meta: { nulls: String(nulls) } });
+	const toOrderByItem = (expr) => new OrderByItem(expr, direction, nulls);
 	if (typeof arg === "string") {
 		if (!(arg in orderByScopeOf(scope, rowFields).topLevel)) throw structuredError("ORM.COLUMN_UNKNOWN", `Column "${arg}" not found in scope for orderBy`, { meta: { column: arg } });
-		const expr = IdentifierRef.of(arg);
-		return dir === "asc" ? OrderByItem.asc(expr) : OrderByItem.desc(expr);
+		return toOrderByItem(IdentifierRef.of(arg));
 	}
 	if (typeof arg === "function") {
 		const combined = orderByScopeOf(scope, rowFields);
 		const fns = useAggregateFns ? createAggregateFunctions(ctx.queryOperationTypes, ctx.rawCodecInferer, ctx.aggregates) : createFunctions(ctx.queryOperationTypes, ctx.rawCodecInferer);
-		const result = arg(createFieldProxy(combined), fns);
-		return dir === "asc" ? OrderByItem.asc(result.buildAst()) : OrderByItem.desc(result.buildAst());
+		return toOrderByItem(arg(createFieldProxy(combined), fns).buildAst());
 	}
 	throw structuredError("ORM.ARGUMENT_INVALID", "Invalid orderBy argument");
 }
@@ -640,6 +663,7 @@ var QueryBase = class extends BuilderBase {
 		return new GroupedQueryImpl(cloneState(this.state, { groupBy: [...this.state.groupBy, ...exprs] }), this.ctx);
 	}
 	as(alias) {
+		assertNotLocked(this.state);
 		const ast = buildSelectAst(this.state);
 		const derivedSource = DerivedTableSource.as(alias, ast);
 		const scope = {
@@ -655,6 +679,7 @@ var QueryBase = class extends BuilderBase {
 		return this.state.rowFields;
 	}
 	buildAst() {
+		assertNotLocked(this.state);
 		return buildSelectAst(this.state);
 	}
 	build() {
@@ -683,6 +708,21 @@ var SelectQueryImpl = class SelectQueryImpl extends QueryBase {
 		const item = resolveOrderBy(arg, options, this.state.scope, this.state.rowFields, this.ctx, false);
 		return this.clone(cloneState(this.state, { orderBy: [...this.state.orderBy, item] }));
 	}
+	forUpdate = this._gate(lockStrengthCapabilities.forUpdate, "forUpdate", (options) => this.lock("forUpdate", options));
+	forNoKeyUpdate = this._gate(lockStrengthCapabilities.forNoKeyUpdate, "forNoKeyUpdate", (options) => this.lock("forNoKeyUpdate", options));
+	forShare = this._gate(lockStrengthCapabilities.forShare, "forShare", (options) => this.lock("forShare", options));
+	forKeyShare = this._gate(lockStrengthCapabilities.forKeyShare, "forKeyShare", (options) => this.lock("forKeyShare", options));
+	lock(strength, options) {
+		const of = options?.of !== void 0 && options.of.length > 0 ? options.of : void 0;
+		if (of !== void 0) assertCapability(this.ctx, lockOptionCapabilities.of, strength);
+		const waitPolicy = lockWaitPolicyOf(strength, options);
+		if (waitPolicy !== void 0) assertCapability(this.ctx, lockOptionCapabilities[waitPolicy], strength);
+		const clause = LockingClause.of(strength, {
+			...ifDefined("of", of),
+			...ifDefined("waitPolicy", waitPolicy)
+		});
+		return this.clone(cloneState(this.state, { locking: [...this.state.locking ?? [], clause] }));
+	}
 };
 var GroupedQueryImpl = class GroupedQueryImpl extends QueryBase {
 	clone(state) {
@@ -800,16 +840,19 @@ function buildParamValues(values, namespaceId, table, tableName, op, ctx) {
 	for (const def of ctx.applyMutationDefaults({
 		op,
 		namespace: namespaceId,
-		table: tableName,
+		entry: tableName,
 		values
 	})) {
-		const codec = table.columns[def.column] ? codecRefFor(ctx, namespaceId, tableName, def.column) : void 0;
-		params[def.column] = ParamRef.of(def.value, codec ? { codec } : void 0);
+		const codec = table.columns[def.field] ? codecRefFor(ctx, namespaceId, tableName, def.field) : void 0;
+		params[def.field] = ParamRef.of(def.value, codec ? { codec } : void 0);
 	}
 	return params;
 }
-function buildReturningProjections(tableName, columns, rowFields) {
-	return columns.map((col) => ProjectionItem.of(col, ColumnRef.of(tableName, col), rowFields[col]?.codec));
+function buildReturningProjections(tableName, columns, rowFields, ctx) {
+	return columns.map((col) => {
+		const field = rowFields[col];
+		return ProjectionItem.of(col, ColumnRef.of(tableName, col), field === void 0 ? void 0 : codecRefOf(field, ctx));
+	});
 }
 function evaluateWhere(whereCallback, scope, queryOperationTypes, rawCodecInferer) {
 	return whereCallback(createFieldProxy(scope), createFunctions(queryOperationTypes, rawCodecInferer)).buildAst();
@@ -825,11 +868,11 @@ function buildSetExpressions(exprs, namespaceId, table, tableName, op, ctx) {
 	for (const def of ctx.applyMutationDefaults({
 		op,
 		namespace: namespaceId,
-		table: tableName,
+		entry: tableName,
 		values: exprs
-	})) if (!(def.column in set)) {
-		const codec = table.columns[def.column] ? codecRefFor(ctx, namespaceId, tableName, def.column) : void 0;
-		set[def.column] = ParamRef.of(def.value, ifDefined("codec", codec));
+	})) if (!(def.field in set)) {
+		const codec = table.columns[def.field] ? codecRefFor(ctx, namespaceId, tableName, def.field) : void 0;
+		set[def.field] = ParamRef.of(def.value, ifDefined("codec", codec));
 	}
 	return set;
 }
@@ -878,7 +921,7 @@ var InsertQueryImpl = class InsertQueryImpl extends BuilderBase {
 		if (this.#rows.length === 0) throw structuredError("ORM.MUTATION_DATA_MISSING", "insert() called with an empty row array — at least one row is required");
 		const paramRows = this.#rows.map((rowValues) => buildParamValues(rowValues, this.#namespaceId, this.#table, this.#tableName, "create", this.ctx));
 		let ast = InsertAst.into(this.#tableSource).withRows(paramRows);
-		if (this.#returningColumns.length > 0) ast = ast.withReturning(buildReturningProjections(this.#tableName, this.#returningColumns, this.#rowFields));
+		if (this.#returningColumns.length > 0) ast = ast.withReturning(buildReturningProjections(this.#tableName, this.#returningColumns, this.#rowFields, this.ctx));
 		return buildQueryPlan(ast, this.ctx, this.#annotations);
 	}
 };
@@ -925,7 +968,7 @@ var UpdateQueryImpl = class UpdateQueryImpl extends BuilderBase {
 	}
 	build() {
 		let ast = UpdateAst.table(this.#tableSource).withSet(this.#setExpressions).withWhere(combineWhereExprs(this.#whereExprs));
-		if (this.#returningColumns.length > 0) ast = ast.withReturning(buildReturningProjections(this.#tableName, this.#returningColumns, this.#rowFields));
+		if (this.#returningColumns.length > 0) ast = ast.withReturning(buildReturningProjections(this.#tableName, this.#returningColumns, this.#rowFields, this.ctx));
 		return buildQueryPlan(ast, this.ctx, this.#annotations);
 	}
 };
@@ -969,7 +1012,7 @@ var DeleteQueryImpl = class DeleteQueryImpl extends BuilderBase {
 	build() {
 		const whereExpr = combineWhereExprs(this.#whereCallbacks.map((cb) => evaluateWhere(cb, this.#scope, this.ctx.queryOperationTypes, this.ctx.rawCodecInferer)));
 		let ast = DeleteAst.from(this.#tableSource).withWhere(whereExpr);
-		if (this.#returningColumns.length > 0) ast = ast.withReturning(buildReturningProjections(this.#tableName, this.#returningColumns, this.#rowFields));
+		if (this.#returningColumns.length > 0) ast = ast.withReturning(buildReturningProjections(this.#tableName, this.#returningColumns, this.#rowFields, this.ctx));
 		return buildQueryPlan(ast, this.ctx, this.#annotations);
 	}
 };
@@ -978,13 +1021,16 @@ function tableSourceForProxy(tableName, alias, namespaceId) {
 }
 var TableProxyImpl = class TableProxyImpl extends BuilderBase {
 	#tableName;
+	#alias;
 	#table;
 	#namespaceId;
 	#fromSource;
 	#scope;
+	#indexes;
 	constructor(tableName, table, alias, ctx, namespaceId) {
 		super(ctx);
 		this.#tableName = tableName;
+		this.#alias = alias;
 		this.#table = table;
 		this.#namespaceId = namespaceId;
 		this.#scope = tableToScope(alias, table, {
@@ -1006,6 +1052,27 @@ var TableProxyImpl = class TableProxyImpl extends BuilderBase {
 		}]));
 		return blindCast(Object.freeze(refs));
 	}
+	/**
+	* The table's indexes, keyed by the name the contract source gave each. An index's columns are this table's columns under its alias, so `post.as('p').indexes.post_search` reads `p`'s columns. A name more than one index shares is refused when it is read.
+	*/
+	get indexes() {
+		this.#indexes ??= this.#indexReferences();
+		return this.#indexes;
+	}
+	#indexReferences() {
+		const fields = this.#scope.namespaces[this.#alias];
+		assertDefined(fields, "a table proxy scopes its own alias");
+		return blindCast(createIndexReferences({
+			namespaceId: this.#namespaceId,
+			tableName: this.#tableName,
+			table: this.#table,
+			column: (column) => {
+				const field = fields[column];
+				assertDefined(field, `an index covers a column of table "${this.#tableName}"`);
+				return new ExpressionImpl(ColumnRef.of(this.#alias, column), field);
+			}
+		}));
+	}
 	lateralJoin = this._gate({ sql: { lateral: true } }, "lateralJoin", (alias, builder) => {
 		return this.#toJoined().lateralJoin(alias, builder);
 	});
@@ -1054,8 +1121,13 @@ var TableProxyImpl = class TableProxyImpl extends BuilderBase {
 		return new JoinedTablesImpl(emptyState(this.#fromSource, this.#scope), this.ctx);
 	}
 };
-/** The key `raw`, which the SQL surface answers with the raw statement tag; no storage namespace may claim it. */
-const RAW_TAG_KEY = "raw";
+function descriptorMaterializesWithoutTypeParams(descriptor) {
+	if (descriptor === void 0) return false;
+	const schema = descriptor.paramsSchema;
+	if (schema === void 0) return true;
+	const result = schema["~standard"].validate({});
+	return !(result instanceof Promise) && result.issues === void 0;
+}
 function sql(options) {
 	const { context, rawCodecInferer } = options;
 	const ctx = {
@@ -1066,14 +1138,12 @@ function sql(options) {
 		storage: context.contract.storage,
 		applyMutationDefaults: (options) => context.applyMutationDefaults(options),
 		rawCodecInferer,
-		aggregates: context.aggregateDescriptors
+		aggregates: context.aggregateDescriptors,
+		materializesWithoutTypeParams: (codecId) => descriptorMaterializesWithoutTypeParams(context.codecDescriptors.descriptorFor(codecId))
 	};
 	const { storage } = context.contract;
-	if (Object.hasOwn(storage.namespaces, RAW_TAG_KEY)) throw structuredError("ORM.NAMESPACE_RESERVED", `The SQL surface exposes the raw statement tag as "db.${RAW_TAG_KEY}", so a storage namespace named "${RAW_TAG_KEY}" cannot be reached through it. Rename the namespace in the schema.`, { meta: { namespaceId: RAW_TAG_KEY } });
-	const raw = blindCast(createRawSql(rawCodecInferer, { contract: context.contract }));
 	return new Proxy(blindCast({}), { get(_target, prop) {
 		if (typeof prop !== "string") return;
-		if (prop === RAW_TAG_KEY) return raw;
 		if (!Object.hasOwn(storage.namespaces, prop)) return;
 		const namespaceId = prop;
 		return new Proxy({}, { get(_facetTarget, tableName) {
@@ -1084,6 +1154,6 @@ function sql(options) {
 	} });
 }
 //#endregion
-export { ExpressionImpl, createAggregateFunctions, createFieldProxy, createFunctions, sql };
+export { ExpressionImpl, createAggregateFunctions, createFieldProxy, createFunctions, createRawLane, sql };
 
 //# sourceMappingURL=builder__runtime.mjs.map