@vibeorm/runtime 2.0.1 → 2.1.0

package/dist/index.js

@@ -1,4 +1,54 @@
 // @bun
+// packages/runtime/src/index.ts
+import { sql as sql2, decode as decode2 } from "@vibeorm/sql";
+
+// packages/runtime/src/sql.ts
+import { VibeError, isEnumType } from "@vibeorm/schema";
+import { decode, sql } from "@vibeorm/sql";
+function sqlProjection(params) {
+  const entries = Object.entries(params.fields);
+  if (entries.length === 0)
+    throw new VibeError({ code: "VIBE_VALIDATION", message: "A SQL projection needs at least one field" });
+  return Object.freeze({
+    sql: sql.join({ items: entries.map(([name, column]) => sql`${column.sql} AS ${sql.ident({ parts: [name] })}`) }),
+    decoder: decode.object({ fields: Object.fromEntries(entries.map(([name, column]) => [name, column.decoder])) })
+  });
+}
+var SCALAR_DECODERS = Object.freeze({
+  String: decode.string,
+  Boolean: decode.boolean,
+  Int: decode.int,
+  Float: decode.float,
+  BigInt: decode.bigInt,
+  Decimal: decode.decimal,
+  DateTime: decode.dateTime,
+  Json: decode.json,
+  Bytes: decode.bytes
+});
+function createSqlModel(params) {
+  const model = params.schema.models.find((entry) => entry.name === params.model);
+  if (model === undefined)
+    throw new VibeError({ code: "VIBE_VALIDATION", message: "Unknown SQL model" });
+  const tableName = model.dbName ?? model.name;
+  const table = sql.ident({ parts: [tableName] });
+  const fields = Object.fromEntries(model.fields.filter((field) => field.isUnsupported !== true).map((field) => {
+    let decoder;
+    if (isEnumType(field.type)) {
+      const name = field.type.enum;
+      const declared = params.schema.enums.find((entry) => entry.name === name);
+      if (declared === undefined)
+        throw new VibeError({ code: "VIBE_SCHEMA_INVALID", message: "Unknown enum in SQL model" });
+      decoder = decode.enum({ values: declared.values });
+    } else
+      decoder = SCALAR_DECODERS[field.type];
+    if (field.isList)
+      decoder = decode.array({ decoder });
+    if (field.isOptional)
+      decoder = decode.nullable({ decoder });
+    return [field.name, Object.freeze({ sql: sql.ident({ parts: [params.alias ?? tableName, field.dbName ?? field.name] }), decoder })];
+  }));
+  return Object.freeze({ table: params.alias === undefined ? table : sql`${table} AS ${sql.ident({ parts: [params.alias] })}`, fields: Object.freeze(fields) });
+}
 // packages/runtime/src/adapter.ts
 function toSqlExecutor(params) {
   const { adapter } = params;
@@ -11,11 +61,11 @@ function toSqlExecutor(params) {
   };
 }
 // packages/runtime/src/db-now.ts
-import { VibeError } from "@vibeorm/schema";
+import { VibeError as VibeError2 } from "@vibeorm/schema";
 function dbNow(options) {
   const offset = options?.plusSeconds ?? 0;
   if (typeof offset !== "number" || !Number.isFinite(offset)) {
-    throw new VibeError({
+    throw new VibeError2({
       code: "VIBE_VALIDATION",
       message: `dbNow plusSeconds must be a finite number of seconds (fractional is fine), got ${String(offset)}`,
       meta: { plusSeconds: offset }
@@ -33,8 +83,116 @@ function isDbNow(value) {
   const candidate = value;
   return candidate.__vibeDbNow === true && typeof candidate.offsetSeconds === "number" && Number.isFinite(candidate.offsetSeconds);
 }
+// packages/runtime/src/advisory-lock.ts
+import { VibeError as VibeError3, unsupportedCapability } from "@vibeorm/schema";
+import { ADVISORY_KEY_BOUNDS } from "@vibeorm/sql";
+function validationError(params) {
+  return new VibeError3({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta });
+}
+function readInt32(params) {
+  const { value, member, method } = params;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < ADVISORY_KEY_BOUNDS.pair.min || value > ADVISORY_KEY_BOUNDS.pair.max) {
+    throw validationError({
+      message: `${method}({ ${member} }) must be a 32-bit integer ` + `(${ADVISORY_KEY_BOUNDS.pair.min} \u2026 ${ADVISORY_KEY_BOUNDS.pair.max}), got ${String(value)}`,
+      meta: { method, member, value: typeof value === "number" ? value : String(value) }
+    });
+  }
+  return value;
+}
+function readInt64(params) {
+  const { value, method } = params;
+  if (typeof value === "bigint") {
+    if (value < ADVISORY_KEY_BOUNDS.single.min || value > ADVISORY_KEY_BOUNDS.single.max) {
+      throw validationError({
+        message: `${method}({ key }) must fit a 64-bit integer, got ${value.toString()}`,
+        meta: { method, member: "key", value: value.toString() }
+      });
+    }
+    return value;
+  }
+  if (typeof value === "number" && Number.isSafeInteger(value))
+    return BigInt(value);
+  throw validationError({
+    message: `${method}({ key }) must be a bigint or a safe integer, got ${String(value)} \u2014 ` + `a number past 2^53 cannot name one specific lock key, so pass a bigint (e.g. 9007199254740993n)`,
+    meta: { method, member: "key", value: String(value) }
+  });
+}
+function compileAdvisoryLock(params) {
+  const { dialect, method, inTransaction, options } = params;
+  if (!dialect.capabilities.advisoryLocks) {
+    throw unsupportedCapability({
+      dialect: dialect.name,
+      feature: `${method}()`,
+      hint: dialect.name === "mysql" ? "mysql's GET_LOCK is SESSION-scoped \u2014 it survives a rollback, so it cannot be released with the transaction. Serialize on a real row instead (a lock table with one row per resource)" : "serialize on a real row instead (a lock table with one row per resource)"
+    });
+  }
+  if (!inTransaction) {
+    throw validationError({
+      message: `${method}() requires a transaction \u2014 call it on the client $transaction hands its callback. ` + `Outside one, the lock is released before the next statement runs`,
+      meta: { method }
+    });
+  }
+  if (typeof options !== "object" || options === null || Array.isArray(options)) {
+    throw validationError({
+      message: `${method}() takes { key } or { classId, objectId }, plus an optional mode, got ${String(options)}`,
+      meta: { method }
+    });
+  }
+  const request = options;
+  const hasSingle = "key" in request;
+  const hasPair = "classId" in request || "objectId" in request;
+  if (hasSingle && hasPair) {
+    throw validationError({
+      message: `${method}() takes ONE key form: { key } or { classId, objectId }. They are different lock spaces, ` + `so naming both cannot be resolved`,
+      meta: { method }
+    });
+  }
+  for (const member of Object.keys(request)) {
+    if (member === "mode" || member === "key" || member === "classId" || member === "objectId")
+      continue;
+    throw validationError({
+      message: `${method}() has no "${member}" option \u2014 it takes { key } or { classId, objectId } and an optional mode`,
+      meta: { method, member }
+    });
+  }
+  const mode = readMode({ value: request.mode, method });
+  if (hasSingle) {
+    const key2 = { key: readInt64({ value: request.key, method }) };
+    return statementFor({ method, mode, key: key2 });
+  }
+  if (!("classId" in request) || !("objectId" in request)) {
+    throw validationError({
+      message: `${method}({ classId, objectId }) needs BOTH halves of the two-key form`,
+      meta: { method }
+    });
+  }
+  const key = {
+    classId: readInt32({ value: request.classId, member: "classId", method }),
+    objectId: readInt32({ value: request.objectId, member: "objectId", method })
+  };
+  return statementFor({ method, mode, key });
+}
+function readMode(params) {
+  const { value, method } = params;
+  if (value === undefined || value === "exclusive")
+    return "exclusive";
+  if (value === "shared")
+    return "shared";
+  throw validationError({
+    message: `${method}({ mode }) must be "exclusive" or "shared", got ${String(value)}`,
+    meta: { method, mode: String(value) }
+  });
+}
+function statementFor(params) {
+  return {
+    kind: "advisoryLock",
+    mode: params.mode,
+    wait: params.method === "$tryAdvisoryLock" ? "nowait" : "wait",
+    key: params.key
+  };
+}
 // packages/runtime/src/model-meta.ts
-import { VibeError as VibeError2, enumStorageOf, isEnumType, validateComputedConfig } from "@vibeorm/schema";
+import { VibeError as VibeError4, enumStorageOf, isEnumType as isEnumType2, validateComputedConfig } from "@vibeorm/schema";
 import { enumMembershipCodec } from "@vibeorm/sql";
 function toClientName(params) {
   const { name } = params;
@@ -131,7 +289,7 @@ function defaultOriginOf(params) {
 }
 function buildFieldMeta(params) {
   const { model, field, enums } = params;
-  const enumName = isEnumType(field.type) ? field.type.enum : null;
+  const enumName = isEnumType2(field.type) ? field.type.enum : null;
   const enumDef = enumName === null ? undefined : enums.get(enumName);
   const enumStorage = enumName === null ? null : enumStorageOf({ enumDef: enumDef ?? {} });
   return {
@@ -163,7 +321,7 @@ function buildModelMeta(params) {
     for (const name of model.primaryKey.fields) {
       const field = fieldByName.get(name);
       if (field === undefined) {
-        throw new VibeError2({
+        throw new VibeError4({
           code: "VIBE_SCHEMA_INVALID",
           message: `model "${model.name}" declares composite primary-key field "${name}", which does not exist`,
           meta: { model: model.name, field: name }
@@ -269,7 +427,7 @@ function getModelMeta(params) {
   const { meta, model } = params;
   const found = meta.modelByName.get(model);
   if (found === undefined) {
-    throw new VibeError2({
+    throw new VibeError4({
       code: "VIBE_VALIDATION",
       message: `unknown model "${model}"`,
       meta: { model, known: [...new Set(meta.models.map((entry) => entry.name))] }
@@ -282,20 +440,20 @@ function getFieldMeta(params) {
   const found = model.fieldByName.get(field);
   if (found === undefined) {
     if (model.computed !== null && model.computed.has(field)) {
-      throw new VibeError2({
+      throw new VibeError4({
         code: "VIBE_VALIDATION",
         message: `"${field}" on model "${model.name}" is a computed field \u2014 computed fields appear in results (select/omit) only, not in ${context}`,
         meta: { model: model.name, field, context, computed: true }
       });
     }
     if (model.relationByName.has(field)) {
-      throw new VibeError2({
+      throw new VibeError4({
         code: "VIBE_VALIDATION",
         message: `"${field}" on model "${model.name}" is a relation \u2014 not valid in ${context} here (relation writes use nested-write verbs, relation reads use select/include)`,
         meta: { model: model.name, field, context }
       });
     }
-    throw new VibeError2({
+    throw new VibeError4({
       code: "VIBE_VALIDATION",
       message: `unknown field "${field}" on model "${model.name}" in ${context}`,
       meta: { model: model.name, field, context }
@@ -305,7 +463,7 @@ function getFieldMeta(params) {
 }
 // packages/runtime/src/codecs.ts
 import { JSON_TRANSPORT, projectionOutputName, parsePgArrayLiteral, toPgArrayLiteral } from "@vibeorm/sql";
-import { VibeError as VibeError3, isEnumType as isEnumType2 } from "@vibeorm/schema";
+import { VibeError as VibeError5, isEnumType as isEnumType3 } from "@vibeorm/schema";
 import { DIALECT_CODECS, decodeIsNoop } from "@vibeorm/sql";
 import {
   DIALECT_CODECS as DIALECT_CODECS2,
@@ -317,7 +475,7 @@ import {
 function getCodec(params) {
   const { dialect, type } = params;
   const table = DIALECT_CODECS[dialect];
-  return isEnumType2(type) ? table.String : table[type];
+  return isEnumType3(type) ? table.String : table[type];
 }
 function fieldCodec(params) {
   const { dialect, field } = params;
@@ -357,7 +515,7 @@ var DECIMAL_LITERAL = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
 function toRealNumber(params) {
   const { field, value } = params;
   const refuse = () => {
-    throw new VibeError3({
+    throw new VibeError5({
       code: "VIBE_VALIDATION",
       message: `"${String(value)}" is not a numeric value for the Decimal field "${field.name}"`,
       meta: { field: field.name, value }
@@ -426,20 +584,20 @@ function wirePlanKey(wire) {
 }
 function fieldDecoder(params) {
   const { dialect, field, wire } = params;
-  const decode = fieldCodec({ dialect, field }).decode;
+  const decode2 = fieldCodec({ dialect, field }).decode;
   if (isPostgresEnumList({ dialect, field })) {
     return (value) => decodeValue({ dialect, field, value });
   }
-  if (decode === IDENTITY_DECODE)
+  if (decode2 === IDENTITY_DECODE)
     return null;
   if (field.isList) {
     if (field.scalarType === "Json" && decodeIsNoop({ scalarType: "Json", wire }))
       return null;
-    return (value) => Array.isArray(value) ? value.map((element) => element === null || element === undefined ? element : decode(element)) : decode(value);
+    return (value) => Array.isArray(value) ? value.map((element) => element === null || element === undefined ? element : decode2(element)) : decode2(value);
   }
   if (field.scalarType !== null && decodeIsNoop({ scalarType: field.scalarType, wire }))
     return null;
-  return decode;
+  return decode2;
 }
 function buildDecodePlan(params) {
   const { dialect, model, wire } = params;
@@ -447,12 +605,12 @@ function buildDecodePlan(params) {
   const inPlace = [];
   const renamedColumns = [];
   for (const field of model.fields) {
-    const decode = fieldDecoder({ dialect, field, ...wire === undefined ? {} : { wire } });
-    byColumn.set(field.columnName, { name: field.name, decode });
+    const decode2 = fieldDecoder({ dialect, field, ...wire === undefined ? {} : { wire } });
+    byColumn.set(field.columnName, { name: field.name, decode: decode2 });
     if (field.columnName !== field.name)
       renamedColumns.push(field.columnName);
-    if (decode !== null)
-      inPlace.push({ column: field.columnName, decode });
+    if (decode2 !== null)
+      inPlace.push({ column: field.columnName, decode: decode2 });
   }
   return { byColumn, renamedColumns, decoders: inPlace, inPlace: renamedColumns.length > 0 ? null : inPlace };
 }
@@ -579,12 +737,12 @@ function getJsonDecodePlan(model) {
   const inPlace = [];
   const renamedColumns = [];
   for (const field of model.fields) {
-    const decode = field.scalarType === "Json" ? null : field.scalarType === "Bytes" && !field.isList ? decodeBase64Bytes : fieldDecoder({ dialect: "postgres", field });
-    byColumn.set(field.columnName, { name: field.name, decode });
+    const decode2 = field.scalarType === "Json" ? null : field.scalarType === "Bytes" && !field.isList ? decodeBase64Bytes : fieldDecoder({ dialect: "postgres", field });
+    byColumn.set(field.columnName, { name: field.name, decode: decode2 });
     if (field.columnName !== field.name)
       renamedColumns.push(field.columnName);
-    if (decode !== null)
-      inPlace.push({ column: field.columnName, decode });
+    if (decode2 !== null)
+      inPlace.push({ column: field.columnName, decode: decode2 });
   }
   plan = { byColumn, renamedColumns, decoders: inPlace, inPlace: renamedColumns.length > 0 ? null : inPlace };
   jsonDecodePlanCache.set(model, plan);
@@ -597,7 +755,7 @@ function positionalMaterializer(params) {
     const output = projectionOutputName({ column });
     const entry = plan.byColumn.get(output);
     if (entry === undefined)
-      throw new VibeError3({ code: "VIBE_INTERNAL", message: "positional projection has no schema field", meta: { model: model.name, column: output } });
+      throw new VibeError5({ code: "VIBE_INTERNAL", message: "positional projection has no schema field", meta: { model: model.name, column: output } });
     return entry;
   });
   const width = slots.length;
@@ -605,7 +763,7 @@ function positionalMaterializer(params) {
   const chunked = width > chunkSize;
   const count = Math.ceil(width / chunkSize);
   const invalid = () => {
-    throw new VibeError3({ code: "VIBE_INTERNAL", message: "positional relation payload does not match its SQL projection", meta: { model: model.name, expectedColumns: width } });
+    throw new VibeError5({ code: "VIBE_INTERNAL", message: "positional relation payload does not match its SQL projection", meta: { model: model.name, expectedColumns: width } });
   };
   if (width === 0 || new Set(slots.map((slot) => slot.name)).size !== width)
     return invalid();
@@ -647,7 +805,7 @@ function decodeAggregateValue(params) {
   return field === null ? value : decodeValue({ dialect, field, value });
 }
 // packages/runtime/src/lateral-projection.ts
-import { VibeError as VibeError4, unsupportedCapability } from "@vibeorm/schema";
+import { VibeError as VibeError6, unsupportedCapability as unsupportedCapability2 } from "@vibeorm/schema";
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date);
 }
@@ -664,7 +822,7 @@ function lateralProjection(params) {
   const columns = names.map((name) => {
     const field = model.fieldByName.get(name);
     if (field === undefined)
-      throw new VibeError4({ code: "VIBE_INTERNAL", message: "lateral projection references an unknown field", meta: { model: model.name, field: name } });
+      throw new VibeError6({ code: "VIBE_INTERNAL", message: "lateral projection references an unknown field", meta: { model: model.name, field: name } });
     return Object.freeze(applyLateralTransform({ model, column: { table: LATERAL_CHILD_ALIAS, name: field.columnName } }));
   });
   const descriptor = Object.freeze({ columns: Object.freeze(columns), hiddenOrder: Object.freeze(hiddenOrder) });
@@ -702,7 +860,7 @@ function applyLateralTransform(params) {
   if (scalar !== "BigInt" && scalar !== "Decimal" && scalar !== "Bytes")
     return column;
   if (field.isList) {
-    throw unsupportedCapability({
+    throw unsupportedCapability2({
       dialect: "postgres",
       feature: `join-strategy relation loading of ${model.name}.${field.name} (${scalar}[])`,
       hint: 'list columns of BigInt/Decimal/Bytes have no faithful JSON wire form \u2014 use the portable "query" relation strategy'
@@ -712,7 +870,8 @@ function applyLateralTransform(params) {
 }
 
 // packages/runtime/src/query-builder.ts
-import { VibeError as VibeError8, unsupportedCapability as unsupportedCapability3 } from "@vibeorm/schema";
+import { isSqlFragment, mapConflictColumns } from "@vibeorm/sql";
+import { VibeError as VibeError10, unsupportedCapability as unsupportedCapability4 } from "@vibeorm/schema";
 import {
   SQL_DEFAULT_CELL,
   containsPattern,
@@ -723,11 +882,12 @@ import {
   jsonParamCell,
   startsWithPattern
 } from "@vibeorm/sql";
+import { describeRowLock } from "@vibeorm/sql";
 
 // packages/runtime/src/bulk-upsert.ts
-import { VibeError as VibeError5, unsupportedCapability as unsupportedCapability2 } from "@vibeorm/schema";
-function validationError(params) {
-  return new VibeError5({
+import { VibeError as VibeError7, unsupportedCapability as unsupportedCapability3 } from "@vibeorm/schema";
+function validationError2(params) {
+  return new VibeError7({
     code: "VIBE_VALIDATION",
     message: params.message,
     ...params.meta === undefined ? {} : { meta: params.meta }
@@ -767,7 +927,7 @@ function uniqueGroupsOf(params) {
 function resolveUpsertConflictTarget(params) {
   const { model, target } = params;
   if (target === undefined) {
-    throw validationError({
+    throw validationError2({
       message: `upsertMany on ${model.clientName} needs an explicit conflictTarget \u2014 the unique group that decides which stored row an incoming row replaces`,
       meta: { model: model.name }
     });
@@ -775,7 +935,7 @@ function resolveUpsertConflictTarget(params) {
   if (typeof target === "object" && target !== null && !Array.isArray(target) && typeof target.constraint === "string") {
     const constraint = target.constraint;
     if (constraint.length === 0 || Object.keys(target).length !== 1) {
-      throw validationError({
+      throw validationError2({
         message: `conflictTarget on ${model.clientName}.upsertMany() must be a field-name array or { constraint: string }`,
         meta: { model: model.name }
       });
@@ -783,7 +943,7 @@ function resolveUpsertConflictTarget(params) {
     return { kind: "constraint", constraint };
   }
   if (!Array.isArray(target) || target.length === 0 || target.some((name) => typeof name !== "string")) {
-    throw validationError({
+    throw validationError2({
       message: `conflictTarget on ${model.clientName}.upsertMany() must be a non-empty field-name array or { constraint: string }`,
       meta: { model: model.name }
     });
@@ -792,7 +952,7 @@ function resolveUpsertConflictTarget(params) {
   for (const name of target) {
     const field = model.fieldByName.get(name);
     if (field === undefined) {
-      throw validationError({
+      throw validationError2({
         message: `unknown field "${name}" in conflictTarget on ${model.clientName}.upsertMany()`,
         meta: { model: model.name, field: name }
       });
@@ -801,7 +961,7 @@ function resolveUpsertConflictTarget(params) {
   }
   const signature = [...fields.map((field) => field.columnName)].sort((left, right) => left < right ? -1 : 1).join("\x00");
   if (!uniqueGroupSignatures({ model }).has(signature)) {
-    throw validationError({
+    throw validationError2({
       message: `conflictTarget [${fields.map((field) => field.name).join(", ")}] on ${model.clientName}.upsertMany() is not a declared unique group of ${model.name} \u2014 an arbiter without a unique index cannot decide which row an incoming row replaces`,
       meta: { model: model.name, fields: fields.map((field) => field.name) }
     });
@@ -815,7 +975,7 @@ function assertConflictTargetIsEnforceable(params) {
   const groups = uniqueGroupSignatures({ model });
   if (groups.size <= 1)
     return;
-  throw unsupportedCapability2({
+  throw unsupportedCapability3({
     dialect: dialect.name,
     feature: `an enforced conflict target on ${model.clientName}.upsertMany() (${model.name} declares ${groups.size} unique groups)`,
     hint: "mysql's ON DUPLICATE KEY UPDATE fires on ANY unique index, so another one can decide the conflict \u2014 pass allowAnyUniqueConflict: true to accept that, or gate the call per dialect"
@@ -824,7 +984,7 @@ function assertConflictTargetIsEnforceable(params) {
 function resolveUpsertUpdateFields(params) {
   const { model, update, targetColumns, skipUpdatedAt } = params;
   if (!Array.isArray(update) || update.length === 0 || update.some((name) => typeof name !== "string")) {
-    throw validationError({
+    throw validationError2({
       message: `update on ${model.clientName}.upsertMany() must be a non-empty array of field names \u2014 the columns a conflicting row takes from the incoming row`,
       meta: { model: model.name }
     });
@@ -834,19 +994,19 @@ function resolveUpsertUpdateFields(params) {
   for (const name of update) {
     const field = model.fieldByName.get(name);
     if (field === undefined) {
-      throw validationError({
+      throw validationError2({
         message: `unknown field "${name}" in update on ${model.clientName}.upsertMany()`,
         meta: { model: model.name, field: name }
       });
     }
     if (targetColumns.has(field.columnName)) {
-      throw validationError({
+      throw validationError2({
         message: `update on ${model.clientName}.upsertMany() cannot rewrite "${field.name}": it is part of the conflict target, the value that decides which row is being replaced`,
         meta: { model: model.name, field: field.name }
       });
     }
     if (model.policy !== undefined && model.policy.field === field.name) {
-      throw validationError({
+      throw validationError2({
         message: `update on ${model.clientName}.upsertMany() cannot rewrite "${field.name}": it is ${model.name}'s tenant field (@@policy), and a batch that moves rows between tenants is never what an ingestion feed meant`,
         meta: { model: model.name, field: field.name }
       });
@@ -873,7 +1033,7 @@ function assertUpsertRowsBindColumns(params) {
     for (const column of targetColumns) {
       if (column in row)
         continue;
-      throw validationError({
+      throw validationError2({
         message: `row ${index} of ${model.clientName}.upsertMany() does not set conflict-target column "${column}" \u2014 an incoming row without the arbiter's value cannot replace anything`,
         meta: { model: model.name, row: index, column }
       });
@@ -881,7 +1041,7 @@ function assertUpsertRowsBindColumns(params) {
     for (const field of updateFields) {
       if (field.columnName in row)
         continue;
-      throw validationError({
+      throw validationError2({
         message: `row ${index} of ${model.clientName}.upsertMany() does not set "${field.name}", which the update list overwrites \u2014 the conflict arm would write the column default over a stored value; give every row a value or drop "${field.name}" from update`,
         meta: { model: model.name, row: index, field: field.name }
       });
@@ -913,7 +1073,7 @@ function assertNoDuplicateConflictKeys(params) {
     const key = conflictKeyOf({ row: compiled[index], columns: targetColumns });
     const first = firstIndexByKey.get(key);
     if (first !== undefined) {
-      throw validationError({
+      throw validationError2({
         message: `${model.clientName}.upsertMany() got the same conflict key twice \u2014 rows ${first} and ${index} both address (${targetColumns.join(", ")}); deduplicate the feed before submitting it, because the databases disagree about what one statement writing a key twice means (postgres refuses it, mysql keeps the last one)`,
         meta: { model: model.name, rows: [first, index], columns: [...targetColumns] }
       });
@@ -938,7 +1098,7 @@ function assertNoDuplicateSecondaryUniques(params) {
       const key = conflictKeyOf({ row, columns });
       const first = firstIndexByKey.get(key);
       if (first !== undefined) {
-        throw unsupportedCapability2({
+        throw unsupportedCapability3({
           dialect: dialect.name,
           feature: `${model.clientName}.upsertMany() with rows ${first} and ${index} carrying the same ${fields.map((field) => field.name).join(" + ")}`,
           hint: `ON DUPLICATE KEY UPDATE has no conflict target: it resolves through whichever unique index an incoming row matches, so row ${index} would UPDATE row ${first} through unique (${columns.join(", ")}) and one of the two rows you submitted would silently not exist. Deduplicate the feed on those columns as well as on the conflict target, or submit the colliding rows in separate calls. allowAnyUniqueConflict widens which STORED row a single incoming row may replace; it does not authorise two submitted rows collapsing into one`
@@ -978,7 +1138,7 @@ function assertConflictKeysFit(params) {
       const length = typeof value === "string" ? Array.from(value).length : value instanceof Uint8Array ? value.byteLength : 0;
       if (length <= capacity)
         continue;
-      throw validationError({
+      throw validationError2({
         message: `${params.model.clientName}.upsertMany() row ${index} conflict key "${field.name}" exceeds its column capacity ${capacity}. The database can truncate it and merge distinct input keys; shorten the value or migrate to a wider column.`,
         meta: { model: params.model.name, field: field.name, row: index, capacity }
       });
@@ -1020,7 +1180,7 @@ function assertConflictKeysAreComparable(params) {
   if (target.kind === "constraint") {
     if (engineComparesEveryPair)
       return;
-    throw unsupportedCapability2({
+    throw unsupportedCapability3({
       dialect: dialect.name,
       feature: `a ${statementCount > 1 ? "chunked " : ""}${model.clientName}.upsertMany() batch arbitrated by constraint "${target.constraint}"`,
       hint: statementCount > 1 ? `a named constraint hides which columns decide the conflict, so only the engine can tell whether two incoming rows address the same stored row \u2014 and it only compares rows inside ONE statement, while this batch of ${model.name} rows needs ${statementCount}. Submit fewer rows per call, or name the unique group's fields instead of the constraint` : "a named constraint hides which columns decide the conflict, so this dialect would silently keep the last of two rows that address the same stored row"
@@ -1038,7 +1198,7 @@ function assertConflictKeysAreComparable(params) {
       notes.push(`@collation("${field.collation}")`);
     return notes.length === 0 ? `${field.name} (column "${field.columnName}")` : `${field.name} (column "${field.columnName}", ${notes.join(", ")})`;
   }).join(", ");
-  throw unsupportedCapability2({
+  throw unsupportedCapability3({
     dialect: dialect.name,
     feature: `${model.clientName}.upsertMany() on conflict target ${described}`,
     hint: statementCount > 1 ? `only the database can tell whether two of these keys address the same stored row \u2014 its column type, collation, scale or precision decides \u2014 and it only compares rows inside ONE statement, while this batch of ${model.name} rows needs ${statementCount}. Submit fewer rows per call, or ${remedyFor({ dialect, fields: opaque })}` : `only the database can tell whether two of these keys address the same stored row \u2014 its column type, collation, scale or precision decides \u2014 and this dialect answers a doubled key by silently keeping the last row instead of refusing it. Deduplicate the feed against the same rule the column uses, or ${remedyFor({ dialect, fields: opaque })}`
@@ -1046,7 +1206,7 @@ function assertConflictKeysAreComparable(params) {
 }
 
 // packages/runtime/src/keyset.ts
-import { VibeError as VibeError6 } from "@vibeorm/schema";
+import { VibeError as VibeError8 } from "@vibeorm/schema";
 var KEYSET_TOKEN_VERSION = 1;
 var KEYSET_TOKEN_PREFIX = "vk1.";
 var KEYSET_MAX_PAGE_SIZE = 1e4;
@@ -1056,10 +1216,10 @@ var DATETIME_NEEDS_PRECISION_ASSERTION = Object.freeze({
   sqlite: false
 });
 function keysetValidation(params) {
-  return new VibeError6({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta });
+  return new VibeError8({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta });
 }
 function keysetUnsupported(params) {
-  return new VibeError6({
+  return new VibeError8({
     code: "VIBE_UNSUPPORTED_CAPABILITY",
     message: params.message,
     meta: params.meta
@@ -1442,9 +1602,9 @@ function decodeKeysetToken(params) {
 }
 
 // packages/runtime/src/relation-plan.ts
-import { VibeError as VibeError7, implicitJoinTable } from "@vibeorm/schema";
-function validationError2(params) {
-  return new VibeError7({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta });
+import { VibeError as VibeError9, implicitJoinTable } from "@vibeorm/schema";
+function validationError3(params) {
+  return new VibeError9({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta });
 }
 function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
@@ -1461,7 +1621,7 @@ function findReverseRelation(params) {
 function keyFields(params) {
   const { model, names, relation, what } = params;
   if (names === undefined || names.length === 0) {
-    throw validationError2({
+    throw validationError3({
       message: `relation "${relation.name}" on ${relation.model} has no ${what} \u2014 the schema cannot be loaded through`,
       meta: { model: relation.model, relation: relation.name }
     });
@@ -1469,7 +1629,7 @@ function keyFields(params) {
   return names.map((name) => {
     const field = model.fieldByName.get(name);
     if (field === undefined) {
-      throw new VibeError7({
+      throw new VibeError9({
         code: "VIBE_SCHEMA_INVALID",
         message: `relation "${relation.name}" on ${relation.model} names unknown ${what} field "${name}"`,
         meta: { model: relation.model, relation: relation.name }
@@ -1481,7 +1641,7 @@ function keyFields(params) {
 function singleKeyPair(params) {
   const { link, what } = params;
   if (link.parentKeys.length !== 1 || link.childKeys.length !== 1) {
-    throw new VibeError7({
+    throw new VibeError9({
       code: "VIBE_UNSUPPORTED_CAPABILITY",
       message: `${what} on relation "${link.relation.name}" of ${link.relation.model} needs a single-column relation key \u2014 this relation links ${link.parentKeys.length} columns; use an explicit junction model`,
       meta: { model: link.relation.model, relation: link.relation.name, arity: link.parentKeys.length }
@@ -1493,7 +1653,7 @@ function singlePrimaryKey(params) {
   const { model, relation } = params;
   const pk = model.primaryKey;
   if (pk.length !== 1) {
-    throw validationError2({
+    throw validationError3({
       message: `implicit many-to-many relation "${relation.name}" needs a single-column primary key on ${model.name}`,
       meta: { model: model.name, relation: relation.name }
     });
@@ -1520,7 +1680,7 @@ function resolveRelationLinkUncached(params) {
   const target = getModelMeta({ meta, model: relation.targetModel });
   if (relation.type === "manyToMany") {
     if (relation.model === relation.targetModel) {
-      throw new VibeError7({
+      throw new VibeError9({
         code: "VIBE_SCHEMA_INVALID",
         message: `relation "${relation.name}" on ${relation.model} is an implicit self many-to-many: both sides own the ` + `same join-table column, so this field and its inverse would read the same rows. Model each direction ` + `with an explicit junction model.`,
         meta: { model: relation.model, relation: relation.name, targetModel: relation.targetModel }
@@ -1562,7 +1722,7 @@ function resolveRelationLinkUncached(params) {
   }
   const reverse = findReverseRelation({ relation, target });
   if (reverse === null || reverse.fields === undefined || reverse.fields.length === 0) {
-    throw new VibeError7({
+    throw new VibeError9({
       code: "VIBE_SCHEMA_INVALID",
       message: `relation "${relation.name}" on ${relation.model} has no foreign-key counterpart on ${relation.targetModel}`,
       meta: { model: relation.model, relation: relation.name, target: relation.targetModel }
@@ -1587,7 +1747,7 @@ function pairedKeys(params) {
   const parentKeys = keyFields({ model, names: parentNames, relation, what: "fields" });
   const childKeys = keyFields({ model: target, names: childNames, relation, what: "references" });
   if (parentKeys.length !== childKeys.length) {
-    throw new VibeError7({
+    throw new VibeError9({
       code: "VIBE_SCHEMA_INVALID",
       message: `relation "${relation.name}" on ${relation.model} links ${parentKeys.length} field(s) to ${childKeys.length} reference(s) \u2014 a foreign key must pair every column`,
       meta: { model: relation.model, relation: relation.name }
@@ -1600,7 +1760,7 @@ var TO_ONE_ARG_KEYS = ["where", "select", "include", "omit"];
 function toNonNegativeInteger(params) {
   const { value, what, relation } = params;
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
-    throw validationError2({
+    throw validationError3({
       message: `${what} on relation "${relation}" must be a non-negative integer`,
       meta: { relation, argument: what, value }
     });
@@ -1617,7 +1777,7 @@ function compileChildSelect(params) {
       continue;
     if (model.computed !== null && model.computed.has(name)) {
       if (value !== true) {
-        throw validationError2({
+        throw validationError3({
           message: `select.${name} must be true or false on model "${model.name}"`,
           meta: { model: model.name, field: name }
         });
@@ -1626,13 +1786,13 @@ function compileChildSelect(params) {
     }
     const field = model.fieldByName.get(name);
     if (field === undefined) {
-      throw validationError2({
+      throw validationError3({
         message: `unknown field "${name}" on model "${model.name}" in select`,
         meta: { model: model.name, field: name }
       });
     }
     if (value !== true) {
-      throw validationError2({
+      throw validationError3({
         message: `select.${name} must be true or false on model "${model.name}"`,
         meta: { model: model.name, field: name }
       });
@@ -1644,7 +1804,7 @@ function compileChildSelect(params) {
 function compileChildOmit(params) {
   const { model, omit, relation } = params;
   if (!isPlainObject2(omit)) {
-    throw validationError2({
+    throw validationError3({
       message: `omit on relation "${relation}" must be an object`,
       meta: { model: model.name, relation }
     });
@@ -1654,13 +1814,13 @@ function compileChildOmit(params) {
     if (value === undefined || value === false)
       continue;
     if (value !== true) {
-      throw validationError2({
+      throw validationError3({
         message: `omit.${name} must be true or false on model "${model.name}"`,
         meta: { model: model.name, relation, field: name }
       });
     }
     if (model.relationByName.has(name)) {
-      throw validationError2({
+      throw validationError3({
         message: `omit.${name} on model "${model.name}" \u2014 omit takes scalar fields; a relation is excluded by not including it`,
         meta: { model: model.name, relation, field: name }
       });
@@ -1668,7 +1828,7 @@ function compileChildOmit(params) {
     if (model.computed !== null && model.computed.has(name))
       continue;
     if (!model.fieldByName.has(name)) {
-      throw validationError2({
+      throw validationError3({
         message: `unknown field "${name}" on model "${model.name}" in omit`,
         meta: { model: model.name, relation, field: name }
       });
@@ -1677,7 +1837,7 @@ function compileChildOmit(params) {
   }
   const kept = model.fields.filter((field) => !omitted.has(field.name)).map((field) => field.name);
   if (kept.length === 0) {
-    throw validationError2({
+    throw validationError3({
       message: `omit on relation "${relation}" removes every field of model "${model.name}"`,
       meta: { model: model.name, relation }
     });
@@ -1702,14 +1862,14 @@ function resolveCountNode(params) {
   const { meta, model, name, where } = params;
   const relation = model.relationByName.get(name);
   if (relation === undefined || !relation.isList) {
-    throw validationError2({
+    throw validationError3({
       message: `_count.select.${name} on model "${model.name}" must name a list relation`,
       meta: { model: model.name, relation: name }
     });
   }
   const link = resolveRelationLink({ meta, model, relation });
   if (where !== undefined && link.target.policy !== undefined) {
-    throw validationError2({
+    throw validationError3({
       message: `_count of ${model.name}.${name} cannot take a filter because ${link.target.name} declares @@policy \u2014 a filtered count would not apply the policy predicate; count the relation with a scoped child query instead`,
       meta: { model: model.name, relation: name }
     });
@@ -1722,7 +1882,7 @@ function resolveCounts(params) {
     return model.relations.filter((relation) => relation.isList).map((relation) => resolveCountNode({ meta, model, name: relation.name, where: undefined }));
   }
   if (!isPlainObject2(spec) || !isPlainObject2(spec.select)) {
-    throw validationError2({
+    throw validationError3({
       message: `_count on model "${model.name}" must be true or { select: { relation: true } }`,
       meta: { model: model.name }
     });
@@ -1736,7 +1896,7 @@ function resolveCounts(params) {
       continue;
     }
     if (!isPlainObject2(value)) {
-      throw validationError2({
+      throw validationError3({
         message: `_count.select.${name} on model "${model.name}" must be true, false, or { where: \u2026 }`,
         meta: { model: model.name, relation: name }
       });
@@ -1745,7 +1905,7 @@ function resolveCounts(params) {
       if (value[key] === undefined)
         continue;
       if (!COUNT_ENTRY_KEYS.includes(key)) {
-        throw validationError2({
+        throw validationError3({
           message: `_count.select.${name} on model "${model.name}" takes only "where" \u2014 got "${key}"`,
           meta: { model: model.name, relation: name, argument: key }
         });
@@ -1753,7 +1913,7 @@ function resolveCounts(params) {
     }
     const where = value.where;
     if (where !== undefined && !isPlainObject2(where)) {
-      throw validationError2({
+      throw validationError3({
         message: `_count.select.${name}.where on model "${model.name}" must be an object`,
         meta: { model: model.name, relation: name }
       });
@@ -1773,27 +1933,27 @@ function resolveNode(params) {
     if (raw[key] === undefined)
       continue;
     if (!allowed.includes(key)) {
-      throw validationError2({
+      throw validationError3({
         message: `unsupported argument "${key}" on relation "${relation.name}" \u2014 supported: ${allowed.join(", ")}`,
         meta: { model: model.name, relation: relation.name, argument: key }
       });
     }
   }
   if (raw.select !== undefined && raw.include !== undefined) {
-    throw validationError2({
+    throw validationError3({
       message: `relation "${relation.name}" cannot use select and include together`,
       meta: { model: model.name, relation: relation.name }
     });
   }
   if (raw.select !== undefined && raw.omit !== undefined) {
-    throw validationError2({
+    throw validationError3({
       message: `relation "${relation.name}" cannot use select and omit together \u2014 select names fields to keep, omit fields to drop`,
       meta: { model: model.name, relation: relation.name }
     });
   }
   const where = raw.where === undefined ? undefined : (() => {
     if (!isPlainObject2(raw.where)) {
-      throw validationError2({
+      throw validationError3({
         message: `where on relation "${relation.name}" must be an object`,
         meta: { model: model.name, relation: relation.name }
       });
@@ -1865,13 +2025,13 @@ function resolveRelationSelection(params) {
         continue;
       if (!model.relationByName.has(key)) {
         const isScalar = model.fieldByName.has(key);
-        throw validationError2({
+        throw validationError3({
           message: isScalar ? `"${key}" on model "${model.name}" is a scalar field \u2014 include takes relations, use select for scalars` : `unknown relation "${key}" on model "${model.name}" in include`,
           meta: { model: model.name, relation: key }
         });
       }
       if (value !== true && !isPlainObject2(value)) {
-        throw validationError2({
+        throw validationError3({
           message: `include.${key} on model "${model.name}" must be true or an object`,
           meta: { model: model.name, relation: key }
         });
@@ -1936,8 +2096,8 @@ var AGG_FN_BY_KEY = {
   _min: "min",
   _max: "max"
 };
-function validationError3(params) {
-  return new VibeError8({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta });
+function validationError4(params) {
+  return new VibeError10({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta });
 }
 function isPlainObject3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date) && !(value instanceof Uint8Array);
@@ -1957,40 +2117,115 @@ function columnRef(params) {
   const { field, table } = params;
   return table === undefined ? { name: field.columnName } : { table, name: field.columnName };
 }
+var ROW_LOCK_STRENGTHS = Object.freeze([
+  "update",
+  "noKeyUpdate",
+  "share",
+  "keyShare"
+]);
+var ROW_LOCK_WAIT_POLICIES = Object.freeze([
+  "wait",
+  "nowait",
+  "skipLocked"
+]);
+var DEFAULT_ROW_LOCK = Object.freeze({ strength: "update", wait: "wait" });
+function readLockRequest(params) {
+  const { value, model, method } = params;
+  const where = `lock on ${model.clientName}.${method}()`;
+  if (value === "update")
+    return DEFAULT_ROW_LOCK;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw validationError4({
+      message: `${where} must be "update" or { strength, wait? }, got ${JSON.stringify(value) ?? String(value)}`,
+      meta: { model: model.name, method, lock: value }
+    });
+  }
+  const request = value;
+  for (const key of Object.keys(request)) {
+    if (key === "strength" || key === "wait")
+      continue;
+    throw validationError4({
+      message: `${where} has no "${key}" member \u2014 a lock is { strength, wait? }, where wait is ` + `one of ${ROW_LOCK_WAIT_POLICIES.map((policy) => `"${policy}"`).join(" | ")} ` + `(one policy, never several flags)`,
+      meta: { model: model.name, method, member: key }
+    });
+  }
+  const strength = request.strength;
+  if (typeof strength !== "string" || !ROW_LOCK_STRENGTHS.includes(strength)) {
+    throw validationError4({
+      message: `${where} needs strength: ${ROW_LOCK_STRENGTHS.map((item) => `"${item}"`).join(" | ")}, got ${String(strength)}`,
+      meta: { model: model.name, method, strength }
+    });
+  }
+  const wait = request.wait;
+  if (wait !== undefined && (typeof wait !== "string" || !ROW_LOCK_WAIT_POLICIES.includes(wait))) {
+    throw validationError4({
+      message: `${where} needs wait: ${ROW_LOCK_WAIT_POLICIES.map((item) => `"${item}"`).join(" | ")}, got ${String(wait)}`,
+      meta: { model: model.name, method, wait }
+    });
+  }
+  return {
+    strength,
+    wait: wait === undefined ? "wait" : wait
+  };
+}
 function compileLock(params) {
-  const { args, model, method, hasRelations } = params;
+  const { dialect, args, model, method, hasRelations } = params;
   if (args.lock === undefined)
-    return false;
+    return null;
   if (model.isView) {
-    throw validationError3({
+    throw validationError4({
       message: `lock on ${model.clientName}.${method}() \u2014 a view row cannot be locked; lock the underlying table's rows instead`,
       meta: { model: model.name, method }
     });
   }
-  if (args.lock !== "update") {
-    throw validationError3({
-      message: `lock on ${model.clientName}.${method}() must be "update", got ${String(args.lock)}`,
-      meta: { model: model.name, method, lock: args.lock }
-    });
-  }
+  const lock = readLockRequest({ value: args.lock, model, method });
   if (args.distinct !== undefined) {
-    throw validationError3({
+    throw validationError4({
       message: `lock cannot combine with distinct on ${model.clientName}.${method}() \u2014 postgres rejects FOR UPDATE with DISTINCT`,
       meta: { model: model.name, method }
     });
   }
   if (hasRelations) {
-    throw validationError3({
+    throw validationError4({
       message: `lock cannot combine with relation loading on ${model.clientName}.${method}() \u2014 lock the parent row alone, then read relations inside the same transaction`,
       meta: { model: model.name, method }
     });
   }
-  return true;
+  assertLockIsExpressible({ dialect, lock, model, method });
+  return lock;
+}
+function assertLockIsExpressible(params) {
+  const { dialect, lock, model, method } = params;
+  const { rowLockStrengths, rowLockWaitPolicies } = dialect.capabilities;
+  const site = `${describeRowLock({ lock })} on ${model.clientName}.${method}()`;
+  if (rowLockStrengths.length === 0) {
+    if (lock.strength === "update" && lock.wait === "wait")
+      return;
+    throw unsupportedCapability4({
+      dialect: dialect.name,
+      feature: site,
+      hint: `${dialect.name} has no locking-read clause at all. Only lock: "update" is accepted there, ` + `as the documented no-op its single-writer transactions already provide`
+    });
+  }
+  if (!rowLockStrengths.includes(lock.strength)) {
+    throw unsupportedCapability4({
+      dialect: dialect.name,
+      feature: site,
+      hint: `${dialect.name} has these lock strengths: ${rowLockStrengths.join(", ")}`
+    });
+  }
+  if (!rowLockWaitPolicies.includes(lock.wait)) {
+    throw unsupportedCapability4({
+      dialect: dialect.name,
+      feature: site,
+      hint: `${dialect.name} has these lock wait policies: ${rowLockWaitPolicies.join(", ")}`
+    });
+  }
 }
 function compileConflictTarget(params) {
   const { dialect, meta, model, method, target, where } = params;
   if ((target !== undefined || where !== undefined) && dialect.doNothingForm === "insertIgnore") {
-    throw unsupportedCapability3({
+    throw unsupportedCapability4({
       dialect: dialect.name,
       feature: `a conflict target on ${model.clientName}.${method}()`,
       hint: "mysql's INSERT IGNORE / ON DUPLICATE KEY fire on ANY duplicate key \u2014 no target can be named; gate the call per dialect"
@@ -2000,7 +2235,7 @@ function compileConflictTarget(params) {
   if (target !== undefined) {
     if (Array.isArray(target)) {
       if (target.length === 0) {
-        throw validationError3({
+        throw validationError4({
           message: `onConflict target on ${model.clientName}.${method}() must name at least one field`,
           meta: { model: model.name, method }
         });
@@ -2008,7 +2243,7 @@ function compileConflictTarget(params) {
       out.columns = target.map((name) => getFieldMeta({ model, field: String(name), context: "onConflict target" }).columnName);
     } else if (isPlainObject3(target) && typeof target.constraint === "string" && target.constraint.length > 0 && Object.keys(target).length === 1) {
       if (!dialect.capabilities.conflictTargetConstraint) {
-        throw unsupportedCapability3({
+        throw unsupportedCapability4({
           dialect: dialect.name,
           feature: "a named-constraint conflict target (ON CONFLICT ON CONSTRAINT)",
           hint: "only postgres supports ON CONSTRAINT targets \u2014 name the indexed columns instead"
@@ -2016,7 +2251,7 @@ function compileConflictTarget(params) {
       }
       out.constraint = target.constraint;
     } else {
-      throw validationError3({
+      throw validationError4({
         message: `onConflict target on ${model.clientName}.${method}() must be a field-name array or { constraint: string }`,
         meta: { model: model.name, method }
       });
@@ -2024,20 +2259,20 @@ function compileConflictTarget(params) {
   }
   if (where !== undefined) {
     if (out.columns === undefined) {
-      throw validationError3({
+      throw validationError4({
         message: `onConflict where on ${model.clientName}.${method}() needs a column-list target \u2014 the predicate refines "(columns) WHERE \u2026"`,
         meta: { model: model.name, method }
       });
     }
     if (!dialect.capabilities.partialIndexes) {
-      throw unsupportedCapability3({
+      throw unsupportedCapability4({
         dialect: dialect.name,
         feature: "a partial-index conflict target",
         hint: "this dialect has no partial indexes to target"
       });
     }
     if (typeof where !== "string" || where.trim().length === 0) {
-      throw validationError3({
+      throw validationError4({
         message: `onConflict where on ${model.clientName}.${method}() must be the partial index's raw predicate string (the schema declaration's where: text)`,
         meta: { model: model.name, method }
       });
@@ -2049,13 +2284,13 @@ function compileConflictTarget(params) {
 function compileDbNowWrite(params) {
   const { model, field, value } = params;
   if (field.scalarType !== "DateTime" || field.isList) {
-    throw validationError3({
+    throw validationError4({
       message: `dbNow() writes the database clock into a DateTime field \u2014 ${model.name}.${field.name} is ${String(field.enumName ?? field.scalarType)}${field.isList ? "[]" : ""}`,
       meta: { model: model.name, field: field.name }
     });
   }
   if (field.isId || field.isUnique || model.primaryKey.some((candidate) => candidate.name === field.name)) {
-    throw validationError3({
+    throw validationError4({
       message: `dbNow() on ${model.name}.${field.name} \u2014 a key field cannot take a database-computed value; the client could not re-address the written row`,
       meta: { model: model.name, field: field.name }
     });
@@ -2065,7 +2300,7 @@ function compileDbNowWrite(params) {
 function compileDbNowFilter(params) {
   const { model, field, value } = params;
   if (field.scalarType !== "DateTime" || field.isList) {
-    throw validationError3({
+    throw validationError4({
       message: `dbNow() compares against a DateTime field \u2014 ${model.name}.${field.name} is ${String(field.enumName ?? field.scalarType)}${field.isList ? "[]" : ""}`,
       meta: { model: model.name, field: field.name }
     });
@@ -2075,7 +2310,7 @@ function compileDbNowFilter(params) {
 function requireObject(params) {
   const { value, what, model } = params;
   if (!isPlainObject3(value)) {
-    throw validationError3({
+    throw validationError4({
       message: `${what} must be an object on model "${model.name}"`,
       meta: { model: model.name, argument: what }
     });
@@ -2085,13 +2320,13 @@ function requireObject(params) {
 function toNonNegativeInteger2(params) {
   const { value, what, model } = params;
   if (typeof value !== "number" || !Number.isSafeInteger(value)) {
-    throw validationError3({
+    throw validationError4({
       message: `${what} must be an integer on model "${model.name}", got ${String(value)}`,
       meta: { model: model.name, argument: what, value }
     });
   }
   if (value < 0) {
-    throw validationError3({
+    throw validationError4({
       message: `negative ${what} is not supported here \u2014 only findMany's take may be negative (backwards pagination)`,
       meta: { model: model.name, argument: what, value }
     });
@@ -2105,7 +2340,7 @@ function assertArgs(params) {
     if (args[key] === undefined)
       continue;
     if (!allowed.includes(key)) {
-      throw validationError3({
+      throw validationError4({
         message: `unsupported argument "${key}" for ${model.clientName}.${method}() \u2014 supported: ${allowed.join(", ")}`,
         meta: { model: model.name, method, argument: key, allowed }
       });
@@ -2116,7 +2351,7 @@ function assertListFilterable(params) {
   const { dialect, model, field, operator } = params;
   if (dialect.capabilities.scalarArrays)
     return;
-  throw unsupportedCapability3({
+  throw unsupportedCapability4({
     dialect: dialect.name,
     feature: `scalar list filter "${operator}" on ${model.name}.${field.name}`,
     hint: "only postgres has native array columns \u2014 model the list as a related table instead"
@@ -2126,7 +2361,7 @@ function assertListWritable(params) {
   const { dialect, model, field } = params;
   if (!field.isList || dialect.capabilities.scalarArrays)
     return;
-  throw unsupportedCapability3({
+  throw unsupportedCapability4({
     dialect: dialect.name,
     feature: `writing the scalar list ${model.name}.${field.name}`,
     hint: "only postgres has native array columns \u2014 model the list as a related table instead"
@@ -2135,7 +2370,7 @@ function assertListWritable(params) {
 function compileStringPattern(params) {
   const { operator, operand, field, model } = params;
   if (typeof operand !== "string") {
-    throw validationError3({
+    throw validationError4({
       message: `"${operator}" on ${model.name}.${field.name} expects a string`,
       meta: { model: model.name, field: field.name, operator }
     });
@@ -2162,7 +2397,7 @@ function compileListFieldFilter(params) {
           break;
         }
         if (!Array.isArray(operand)) {
-          throw validationError3({
+          throw validationError4({
             message: `"equals" on the list ${model.name}.${field.name} expects an array or null`,
             meta: { model: model.name, field: field.name, operator }
           });
@@ -2186,7 +2421,7 @@ function compileListFieldFilter(params) {
       case "hasEvery":
       case "hasSome": {
         if (!Array.isArray(operand)) {
-          throw validationError3({
+          throw validationError4({
             message: `"${operator}" on ${model.name}.${field.name} expects an array`,
             meta: { model: model.name, field: field.name, operator }
           });
@@ -2197,7 +2432,7 @@ function compileListFieldFilter(params) {
       }
       case "isEmpty": {
         if (typeof operand !== "boolean") {
-          throw validationError3({
+          throw validationError4({
             message: `"isEmpty" on ${model.name}.${field.name} expects a boolean`,
             meta: { model: model.name, field: field.name, operator }
           });
@@ -2206,7 +2441,7 @@ function compileListFieldFilter(params) {
         break;
       }
       default:
-        throw validationError3({
+        throw validationError4({
           message: `unknown list filter "${operator}" on ${model.name}.${field.name} \u2014 lists take equals, has, hasEvery, hasSome, isEmpty`,
           meta: { model: model.name, field: field.name, operator }
         });
@@ -2225,7 +2460,7 @@ function compileJsonFieldFilter(params) {
   const rawPath = filter.path;
   if (rawPath !== undefined) {
     if (!Array.isArray(rawPath) || rawPath.some((seg) => typeof seg !== "string" && typeof seg !== "number")) {
-      throw validationError3({
+      throw validationError4({
         message: `"path" on ${model.name}.${field.name} must be an array of keys (strings) and indexes (numbers)`,
         meta: { model: model.name, field: field.name }
       });
@@ -2234,7 +2469,7 @@ function compileJsonFieldFilter(params) {
   const path = rawPath ?? [];
   const mode = filter.mode;
   if (mode !== undefined && mode !== "insensitive" && mode !== "default") {
-    throw validationError3({
+    throw validationError4({
       message: `mode must be "insensitive" or "default" on ${model.name}.${field.name}`,
       meta: { model: model.name, field: field.name, mode }
     });
@@ -2243,7 +2478,7 @@ function compileJsonFieldFilter(params) {
   const requireOp = (op) => {
     if (dialect.supportedJsonOps.includes(op))
       return;
-    throw unsupportedCapability3({
+    throw unsupportedCapability4({
       dialect: dialect.name,
       feature: `json filter "${op}" on ${model.name}.${field.name}`,
       hint: `this dialect can express: ${dialect.supportedJsonOps.join(", ")}`
@@ -2256,7 +2491,7 @@ function compileJsonFieldFilter(params) {
     if (operator === "equals" || operator === "not") {
       if (operand === null) {
         if (path.length > 0) {
-          throw validationError3({
+          throw validationError4({
             message: `"${operator}: null" with a path on ${model.name}.${field.name} is ambiguous (SQL NULL vs JSON null) \u2014 omit the path to test column NULL`,
             meta: { model: model.name, field: field.name, operator }
           });
@@ -2277,7 +2512,7 @@ function compileJsonFieldFilter(params) {
     }
     if (JSON_STRING_OPS.includes(operator)) {
       if (typeof operand !== "string") {
-        throw validationError3({
+        throw validationError4({
           message: `"${operator}" on ${model.name}.${field.name} expects a string`,
           meta: { model: model.name, field: field.name, operator }
         });
@@ -2300,13 +2535,13 @@ function compileJsonFieldFilter(params) {
       conditions.push({ kind: "jsonFilter", column, path, op, value: operand });
       continue;
     }
-    throw validationError3({
+    throw validationError4({
       message: `unknown json filter "${operator}" on ${model.name}.${field.name} \u2014 supported: path, mode, equals, not, ${[...JSON_STRING_OPS, ...JSON_ARRAY_OPS].join(", ")}`,
       meta: { model: model.name, field: field.name, operator }
     });
   }
   if (conditions.length === 0) {
-    throw validationError3({
+    throw validationError4({
       message: `json filter on ${model.name}.${field.name} needs at least one operator`,
       meta: { model: model.name, field: field.name }
     });
@@ -2329,14 +2564,14 @@ function compileOperatorFilter(params) {
   const mode = filter.mode;
   if (mode !== undefined) {
     if (mode !== "insensitive" && mode !== "strict" && mode !== "default") {
-      throw validationError3({
+      throw validationError4({
         message: `mode must be "insensitive", "strict" or "default" on ${model.name}.${field.name}`,
         meta: { model: model.name, field: field.name, mode }
       });
     }
     const others = entries.filter(([operator]) => operator !== "mode");
     if (others.length === 0 || others.some(([operator]) => !modeCompanions.includes(operator))) {
-      throw validationError3({
+      throw validationError4({
         message: `mode is only supported with ${modeCompanions.join("/")} on ${model.name}.${field.name}`,
         meta: { model: model.name, field: field.name }
       });
@@ -2347,7 +2582,7 @@ function compileOperatorFilter(params) {
   const ciCollated = (params2) => params2.dialect.name === "mysql" && params2.field.collation?.toLowerCase().endsWith("_ci") === true;
   const requireStringOperand = (operator, operand) => {
     if (typeof operand !== "string") {
-      throw validationError3({
+      throw validationError4({
         message: `mode: "${String(mode)}" with ${operator} on ${model.name}.${field.name} expects a string`,
         meta: { model: model.name, field: field.name }
       });
@@ -2421,14 +2656,14 @@ function compileOperatorFilter(params) {
       case "in":
       case "notIn": {
         if (!Array.isArray(operand)) {
-          throw validationError3({
+          throw validationError4({
             message: `"${operator}" on ${model.name}.${field.name} expects an array`,
             meta: { model: model.name, field: field.name, operator }
           });
         }
         for (const item of operand) {
           if (isDbNow(item)) {
-            throw validationError3({
+            throw validationError4({
               message: `dbNow() cannot ride an "${operator}" list on ${model.name}.${field.name} \u2014 compare with lt/lte/gt/gte/equals instead`,
               meta: { model: model.name, field: field.name, operator }
             });
@@ -2486,7 +2721,7 @@ function compileOperatorFilter(params) {
           }));
           break;
         }
-        throw validationError3({
+        throw validationError4({
           message: `unknown filter operator "${operator}" on ${model.name}.${field.name}`,
           meta: { model: model.name, field: field.name, operator }
         });
@@ -2512,7 +2747,7 @@ function compileFieldFilter(params) {
   }
   if (Array.isArray(value)) {
     if (!field.isList) {
-      throw validationError3({
+      throw validationError4({
         message: `array filter value on ${model.name}.${field.name} \u2014 only list fields compare against arrays`,
         meta: { model: model.name, field: field.name }
       });
@@ -2523,7 +2758,7 @@ function compileFieldFilter(params) {
   if (isPlainObject3(value)) {
     return compileOperatorFilter({ ctx, model, field, filter: value, qualify });
   }
-  throw validationError3({
+  throw validationError4({
     message: `unsupported filter value for ${model.name}.${field.name}`,
     meta: { model: model.name, field: field.name }
   });
@@ -2607,7 +2842,7 @@ function buildRelationExists(params) {
 function requirePredicateObject(params) {
   const { model, relation, operator, operand } = params;
   if (!isPlainObject3(operand)) {
-    throw validationError3({
+    throw validationError4({
       message: `"${operator}" on relation ${model.name}.${relation.name} expects a where object`,
       meta: { model: model.name, relation: relation.name, operator }
     });
@@ -2620,7 +2855,7 @@ function compileRelationFilter(params) {
   const outer = qualify ?? model.tableName;
   if (relation.isList) {
     if (!isPlainObject3(value)) {
-      throw validationError3({
+      throw validationError4({
         message: `filter on relation ${model.name}.${relation.name} must be { some | every | none: \u2026 }`,
         meta: { model: model.name, relation: relation.name }
       });
@@ -2658,14 +2893,14 @@ function compileRelationFilter(params) {
           }));
           break;
         default:
-          throw validationError3({
+          throw validationError4({
             message: `unknown relation filter "${operator}" on ${model.name}.${relation.name} \u2014 to-many relations take some/every/none`,
             meta: { model: model.name, relation: relation.name, operator }
           });
       }
     }
     if (conditions2.length === 0) {
-      throw validationError3({
+      throw validationError4({
         message: `filter on relation ${model.name}.${relation.name} must contain some, every or none`,
         meta: { model: model.name, relation: relation.name }
       });
@@ -2692,7 +2927,7 @@ function compileRelationFilter(params) {
         isNotArm = value[key];
         hasIsNot = true;
       } else {
-        throw validationError3({
+        throw validationError4({
           message: `relation filter on ${model.name}.${relation.name} cannot mix "${key}" with is/isNot`,
           meta: { model: model.name, relation: relation.name, operator: key }
         });
@@ -2702,7 +2937,7 @@ function compileRelationFilter(params) {
     isArm = value;
     hasIs = true;
   } else {
-    throw validationError3({
+    throw validationError4({
       message: `filter on relation ${model.name}.${relation.name} must be a where object, { is | isNot: \u2026 } or null`,
       meta: { model: model.name, relation: relation.name }
     });
@@ -2756,6 +2991,12 @@ function compileWhereInternal(params) {
   for (const [key, value] of Object.entries(where)) {
     if (value === undefined)
       continue;
+    if (key === "$raw") {
+      if (!isSqlFragment(value))
+        throw validationError4({ message: "$raw requires a constructed SQL fragment" });
+      operands.push({ kind: "composed", fragment: value });
+      continue;
+    }
     if (key === "AND") {
       operands.push({ kind: "and", operands: compileWhereGroup({ ctx, model, value, key, qualify }) });
       continue;
@@ -2797,20 +3038,20 @@ function compileOrderTerm(params) {
   if (isPlainObject3(spec)) {
     const { sort, nulls } = spec;
     if (sort !== "asc" && sort !== "desc") {
-      throw validationError3({
+      throw validationError4({
         message: `orderBy sort must be "asc" or "desc" on ${model.name}.${field.name}`,
         meta: { model: model.name, field: field.name, sort }
       });
     }
     if (nulls !== undefined && nulls !== "first" && nulls !== "last") {
-      throw validationError3({
+      throw validationError4({
         message: `orderBy nulls must be "first" or "last" on ${model.name}.${field.name}`,
         meta: { model: model.name, field: field.name, nulls }
       });
     }
     return nulls === undefined ? { column, direction: sort } : { column, direction: sort, nulls };
   }
-  throw validationError3({
+  throw validationError4({
     message: `orderBy on ${model.name}.${field.name} must be "asc", "desc" or { sort, nulls }`,
     meta: { model: model.name, field: field.name }
   });
@@ -2846,7 +3087,7 @@ function compileRelationOrderTerms(params) {
   const requireDirection = (value, what) => {
     if (value === "asc" || value === "desc")
       return value;
-    throw validationError3({
+    throw validationError4({
       message: `${what} on ${model.name}.${relation.name} must be "asc" or "desc" \u2014 nulls placement is not supported on relation orderBy`,
       meta: { model: model.name, relation: relation.name }
     });
@@ -2856,7 +3097,7 @@ function compileRelationOrderTerms(params) {
       continue;
     if (key === "_count") {
       if (!isList) {
-        throw validationError3({
+        throw validationError4({
           message: `orderBy.${relation.name}._count on model "${model.name}" needs a list relation \u2014 "${relation.name}" is to-one`,
           meta: { model: model.name, relation: relation.name }
         });
@@ -2888,7 +3129,7 @@ function compileRelationOrderTerms(params) {
       continue;
     }
     if (isList) {
-      throw validationError3({
+      throw validationError4({
         message: `orderBy.${relation.name}.${key} on model "${model.name}" \u2014 a to-many relation orders by _count only (a scalar across many rows is ambiguous)`,
         meta: { model: model.name, relation: relation.name, field: key }
       });
@@ -2946,7 +3187,7 @@ function compileSelect(params) {
     if (model.computed !== null && model.computed.has(name))
       continue;
     if (value !== true) {
-      throw validationError3({
+      throw validationError4({
         message: `select.${name} must be true or false on model "${model.name}"`,
         meta: { model: model.name, field: name }
       });
@@ -2954,7 +3195,7 @@ function compileSelect(params) {
     names.push(getFieldMeta({ model, field: name, context: "select" }).name);
   }
   if (names.length === 0 && !allowEmpty) {
-    throw validationError3({
+    throw validationError4({
       message: `select on model "${model.name}" must include at least one field`,
       meta: { model: model.name }
     });
@@ -2972,7 +3213,7 @@ function resolveComputedSelection(params) {
       if (!specs.has(name) || value === undefined || value === false)
         continue;
       if (value !== true) {
-        throw validationError3({
+        throw validationError4({
           message: `select.${name} must be true or false on model "${model.name}"`,
           meta: { model: model.name, field: name }
         });
@@ -3040,7 +3281,7 @@ function expandCompoundWhere(params) {
     for (const field of fields) {
       const member = spec[field.name];
       if (member === undefined) {
-        throw validationError3({
+        throw validationError4({
           message: `${what}.${key} on model "${model.name}" needs every member field (${fields.map((entry) => entry.name).join(", ")}) \u2014 "${field.name}" is missing`,
           meta: { model: model.name, key, field: field.name }
         });
@@ -3073,7 +3314,7 @@ function assertUniqueWhere(params) {
     ...model.singleIndexUniques.map((single) => single.fields[0].name),
     ...model.compoundUniques.keys()
   ];
-  throw validationError3({
+  throw validationError4({
     message: `${model.clientName}.${method}() needs a unique where \u2014 one of: ${candidates.join(", ")}`,
     meta: { model: model.name, method, candidates }
   });
@@ -3203,7 +3444,7 @@ function compileCreateRow(params) {
       continue;
     }
     if (Array.isArray(value) && value.some((item) => isDbNow(item))) {
-      throw validationError3({
+      throw validationError4({
         message: `dbNow() cannot be a list element (${model.name}.${entry.field.name})`,
         meta: { model: model.name, field: entry.field.name }
       });
@@ -3246,14 +3487,14 @@ function orderedColumns(params) {
 function compileAtomicOperation(params) {
   const { model, field, operator, operand } = params;
   if (field.scalarType === null || !NUMERIC_TYPES.includes(field.scalarType)) {
-    throw validationError3({
+    throw validationError4({
       message: `"${operator}" needs a numeric field, but ${model.name}.${field.name} is ${String(field.enumName ?? field.scalarType)}`,
       meta: { model: model.name, field: field.name, operator }
     });
   }
   const numeric = typeof operand === "bigint" ? Number(operand) : operand;
   if (typeof numeric !== "number" || !Number.isFinite(numeric)) {
-    throw validationError3({
+    throw validationError4({
       message: `"${operator}" on ${model.name}.${field.name} expects a number`,
       meta: { model: model.name, field: field.name, operator, operand }
     });
@@ -3284,7 +3525,7 @@ function compileUpdateSet(params) {
       continue;
     }
     if (Array.isArray(value) && value.some((item) => isDbNow(item))) {
-      throw validationError3({
+      throw validationError4({
         message: `dbNow() cannot be a list element (${model.name}.${field.name})`,
         meta: { model: model.name, field: field.name }
       });
@@ -3292,7 +3533,7 @@ function compileUpdateSet(params) {
     if (isPlainObject3(value) && field.scalarType !== "Json") {
       const entries = Object.entries(value).filter(([, operand2]) => operand2 !== undefined);
       if (entries.length !== 1) {
-        throw validationError3({
+        throw validationError4({
           message: `update of ${model.name}.${field.name} must use exactly one operation`,
           meta: { model: model.name, field: field.name, operations: entries.map(([key]) => key) }
         });
@@ -3308,7 +3549,7 @@ function compileUpdateSet(params) {
       }
       const atomic = ATOMIC_OPERATIONS[operator];
       if (atomic === undefined) {
-        throw validationError3({
+        throw validationError4({
           message: `unknown update operation "${operator}" on ${model.name}.${field.name}`,
           meta: { model: model.name, field: field.name, operator }
         });
@@ -3326,7 +3567,7 @@ function compileUpdateSet(params) {
     }
   }
   if (Object.keys(set).length === 0) {
-    throw validationError3({
+    throw validationError4({
       message: `update of model "${model.name}" must change at least one field`,
       meta: { model: model.name }
     });
@@ -3337,7 +3578,7 @@ function compileCreateRows(params) {
   const { dialect, model, data } = params;
   const items = Array.isArray(data) ? data : [data];
   if (items.length === 0) {
-    throw validationError3({
+    throw validationError4({
       message: `${params.method ?? "createMany"} on model "${model.name}" needs at least one row`,
       meta: { model: model.name }
     });
@@ -3388,7 +3629,7 @@ function compileCreateRows(params) {
 function compileTake(params) {
   const { value, model } = params;
   if (typeof value !== "number" || !Number.isSafeInteger(value)) {
-    throw validationError3({
+    throw validationError4({
       message: `take must be an integer on model "${model.name}", got ${String(value)}`,
       meta: { model: model.name, argument: "take", value }
     });
@@ -3404,7 +3645,7 @@ function parseCursor(params) {
   });
   const entries = Object.entries(spec).filter(([, value]) => value !== undefined);
   if (entries.length === 0) {
-    throw validationError3({
+    throw validationError4({
       message: `cursor on model "${model.name}" needs a unique field value`,
       meta: { model: model.name }
     });
@@ -3414,7 +3655,7 @@ function parseCursor(params) {
   for (const [name, value] of entries) {
     const field = getFieldMeta({ model, field: name, context: "cursor" });
     if (!isDirectValue(value)) {
-      throw validationError3({
+      throw validationError4({
         message: `cursor.${name} on model "${model.name}" must be a direct value`,
         meta: { model: model.name, field: name }
       });
@@ -3426,7 +3667,7 @@ function parseCursor(params) {
     const field = fields[0];
     const isSingleIndexUnique = model.singleIndexUniques.some((single) => single.fields[0].name === field.name);
     if (!field.isId && !field.isUnique && !isSingleIndexUnique) {
-      throw validationError3({
+      throw validationError4({
         message: `cursor field ${model.name}.${field.name} must be @id or @unique \u2014 a non-unique cursor cannot identify a position`,
         meta: { model: model.name, field: field.name }
       });
@@ -3440,7 +3681,7 @@ function parseCursor(params) {
         model.primaryKey.map((field) => field.name).join(" + ") || "none",
         ...model.compoundUniques.keys()
       ];
-      throw validationError3({
+      throw validationError4({
         message: `multi-field cursor on model "${model.name}" must be exactly the composite primary key or a composite @@unique group (${candidates.join(", ")})`,
         meta: { model: model.name, fields: [...names] }
       });
@@ -3451,7 +3692,7 @@ function parseCursor(params) {
 function keysetFieldOfTerm(params) {
   const { dialect, model, term } = params;
   if (!("column" in term)) {
-    throw unsupportedCapability3({
+    throw unsupportedCapability4({
       dialect: dialect.name,
       feature: `keyset pagination over a relation or aggregate orderBy on model "${model.name}"`,
       hint: "order by scalar columns plus a unique tie-breaker; a correlated subquery value is not on the row, so no position can describe it"
@@ -3459,7 +3700,7 @@ function keysetFieldOfTerm(params) {
   }
   const field = model.fieldByColumn.get(term.column.name);
   if (field === undefined) {
-    throw unsupportedCapability3({
+    throw unsupportedCapability4({
       dialect: dialect.name,
       feature: `keyset pagination over a computed order key on model "${model.name}"`,
       hint: "order by scalar columns plus a unique tie-breaker"
@@ -3488,7 +3729,7 @@ function parseKeysetOptions(params) {
   const spec = requireObject({ value, what: "keyset", model });
   for (const key of Object.keys(spec)) {
     if (key !== "timestampPrecision") {
-      throw validationError3({
+      throw validationError4({
         message: `unknown keyset option "${key}" on model "${model.name}" \u2014 only timestampPrecision is supported`,
         meta: { model: model.name, option: key, reason: "keyset-option-unknown" }
       });
@@ -3498,7 +3739,7 @@ function parseKeysetOptions(params) {
   if (precision === undefined)
     return {};
   if (precision !== "milliseconds") {
-    throw validationError3({
+    throw validationError4({
       message: `keyset.timestampPrecision on model "${model.name}" must be "milliseconds"`,
       meta: { model: model.name, value: precision, reason: "keyset-option-invalid" }
     });
@@ -3508,25 +3749,25 @@ function parseKeysetOptions(params) {
 function buildKeysetBound(params) {
   const { dialect, model, args, userOrder, sqlOrder, colRefOf } = params;
   if (args.cursor !== undefined) {
-    throw validationError3({
+    throw validationError4({
       message: `after and cursor cannot combine on model "${model.name}" \u2014 a keyset position and a unique-key cursor are two different pagination forms`,
       meta: { model: model.name, reason: "keyset-cursor-conflict" }
     });
   }
   if (args.distinct !== undefined) {
-    throw validationError3({
+    throw validationError4({
       message: `after cannot combine with distinct on model "${model.name}" \u2014 deduplication reorders the result, so a position in the requested order does not address it`,
       meta: { model: model.name, reason: "keyset-distinct-unsupported" }
     });
   }
   if (args.skip !== undefined) {
-    throw validationError3({
+    throw validationError4({
       message: `after cannot combine with skip on model "${model.name}" \u2014 keyset pagination has no offset, and an offset on top of it is not keyset pagination`,
       meta: { model: model.name, reason: "keyset-skip-unsupported" }
     });
   }
   if (userOrder.length === 0) {
-    throw validationError3({
+    throw validationError4({
       message: `after on model "${model.name}" needs an orderBy \u2014 a position has no meaning without an order`,
       meta: { model: model.name, reason: "keyset-order-required" }
     });
@@ -3621,7 +3862,7 @@ function normalizeDistinct(params) {
   const { model, distinct } = params;
   const names = typeof distinct === "string" ? [distinct] : distinct;
   if (!Array.isArray(names) || names.length === 0 || names.some((name) => typeof name !== "string")) {
-    throw validationError3({
+    throw validationError4({
       message: `distinct on model "${model.name}" must be a field name or a non-empty array of field names`,
       meta: { model: model.name }
     });
@@ -3679,7 +3920,7 @@ function buildFindShape(params) {
     baseOrder = model.primaryKey.map((field) => ({ column: colRefOf(field), direction: "asc" }));
   }
   if (backward && baseOrder.length === 0) {
-    throw validationError3({
+    throw validationError4({
       message: `negative take on model "${model.name}" needs an orderBy (or a primary key) to reverse`,
       meta: { model: model.name }
     });
@@ -3693,13 +3934,13 @@ function buildFindShape(params) {
   let distinctOuterOrder = null;
   if (args.distinct !== undefined) {
     if (backward) {
-      throw validationError3({
+      throw validationError4({
         message: `distinct cannot combine with a negative take on model "${model.name}"`,
         meta: { model: model.name }
       });
     }
     if (orderTerms.some((term) => ("select" in term))) {
-      throw validationError3({
+      throw validationError4({
         message: `distinct cannot combine with a relation orderBy on model "${model.name}"`,
         meta: { model: model.name }
       });
@@ -3750,7 +3991,7 @@ function buildFindShape(params) {
     const leadingColumns = leading.filter((term) => ("column" in term));
     const coherent = leadingColumns.length === leading.length && leading.length === cursor.fields.length && new Set(leadingColumns.map((term) => term.column.name)).size === leading.length && leadingColumns.every((term) => cursorIndexByColumn.has(term.column.name));
     if (!coherent) {
-      throw validationError3({
+      throw validationError4({
         message: `cursor pagination on model "${model.name}" needs orderBy to lead with the cursor field(s) ${cursor.fields.map((field) => `"${field.name}"`).join(", ")} \u2014 a cursor bound over a different ordering is not cursor pagination`,
         meta: { model: model.name, cursorFields: cursor.fields.map((field) => field.name) }
       });
@@ -3782,7 +4023,7 @@ function buildFindShape(params) {
   }
   if (args.after !== undefined) {
     if (typeof args.after !== "string") {
-      throw validationError3({
+      throw validationError4({
         message: `after on model "${model.name}" must be a keyset token string`,
         meta: { model: model.name, reason: "keyset-token-malformed" }
       });
@@ -4060,13 +4301,13 @@ function compileOmit(params) {
     if (value === undefined || value === false)
       continue;
     if (value !== true) {
-      throw validationError3({
+      throw validationError4({
         message: `omit.${name} must be true or false on model "${model.name}"`,
         meta: { model: model.name, field: name }
       });
     }
     if (model.relationByName.has(name)) {
-      throw validationError3({
+      throw validationError4({
         message: `omit.${name} on model "${model.name}" \u2014 omit takes scalar fields; a relation is excluded by not including it`,
         meta: { model: model.name, field: name }
       });
@@ -4077,7 +4318,7 @@ function compileOmit(params) {
   }
   const kept = model.fields.filter((field) => !omitted.has(field.name)).map((field) => field.name);
   if (kept.length === 0) {
-    throw validationError3({
+    throw validationError4({
       message: `omit on model "${model.name}" removes every field`,
       meta: { model: model.name }
     });
@@ -4092,14 +4333,14 @@ function validateAggregatedField(params) {
   if (key === "_count")
     return;
   if (field.isList) {
-    throw validationError3({
+    throw validationError4({
       message: `${key} cannot aggregate the list field ${model.name}.${field.name}`,
       meta: { model: model.name, field: field.name, key }
     });
   }
   if (key === "_avg" || key === "_sum") {
     if (field.scalarType === null || !NUMERIC_TYPES.includes(field.scalarType)) {
-      throw validationError3({
+      throw validationError4({
         message: `${key} needs a numeric field, but ${model.name}.${field.name} is ${String(field.enumName ?? field.scalarType)}`,
         meta: { model: model.name, field: field.name, key }
       });
@@ -4107,7 +4348,7 @@ function validateAggregatedField(params) {
     return;
   }
   if (field.scalarType === "Json" || field.scalarType === "Bytes" || field.scalarType === "Boolean") {
-    throw validationError3({
+    throw validationError4({
       message: `${key} cannot aggregate ${model.name}.${field.name} (${field.scalarType} has no ordering)`,
       meta: { model: model.name, field: field.name, key }
     });
@@ -4135,14 +4376,14 @@ function compileAggregations(params) {
       if (flag === undefined || flag === false)
         continue;
       if (flag !== true) {
-        throw validationError3({
+        throw validationError4({
           message: `${key}.${name} must be true or false on model "${model.name}"`,
           meta: { model: model.name, field: name, key }
         });
       }
       if (name === "_all") {
         if (key !== "_count") {
-          throw validationError3({
+          throw validationError4({
             message: `${key}._all is not valid \u2014 _all only counts rows (_count)`,
             meta: { model: model.name, key }
           });
@@ -4169,7 +4410,7 @@ function compileAggregations(params) {
     }
   }
   if (selections.length === 0 && method === "aggregate") {
-    throw validationError3({
+    throw validationError4({
       message: `${model.clientName}.aggregate() needs at least one of ${AGGREGATE_KEYS.join(", ")}`,
       meta: { model: model.name }
     });
@@ -4190,7 +4431,7 @@ function compileAggregatePredicate(params) {
   let field = null;
   if (selector === "_all") {
     if (key !== "_count") {
-      throw validationError3({
+      throw validationError4({
         message: `having ${key}._all is not valid \u2014 _all only counts rows (_count)`,
         meta: { model: model.name, key }
       });
@@ -4209,7 +4450,7 @@ function compileAggregatePredicate(params) {
       continue;
     const op = HAVING_OPERATOR_MAP[operator];
     if (op === undefined) {
-      throw validationError3({
+      throw validationError4({
         message: `unknown having operator "${operator}" on ${key} of ${model.name}.${selector} \u2014 supported: ${Object.keys(HAVING_OPERATOR_MAP).join(", ")}`,
         meta: { model: model.name, key, operator }
       });
@@ -4218,7 +4459,7 @@ function compileAggregatePredicate(params) {
     out.push({ kind: "aggCmp", op, agg, value });
   }
   if (out.length === 0) {
-    throw validationError3({
+    throw validationError4({
       message: `having ${key}.${selector} on model "${model.name}" needs an operator`,
       meta: { model: model.name, key }
     });
@@ -4264,7 +4505,7 @@ function compileHaving(params) {
     const requireGrouped = () => {
       if (byNames.has(field.name))
         return;
-      throw validationError3({
+      throw validationError4({
         message: `having on ${model.name}.${field.name} needs the field in \`by\` \u2014 only grouped columns and aggregates exist after grouping`,
         meta: { model: model.name, field: field.name }
       });
@@ -4317,7 +4558,7 @@ function compileGroupByOrder(params) {
           if (direction === undefined)
             continue;
           if (direction !== "asc" && direction !== "desc") {
-            throw validationError3({
+            throw validationError4({
               message: `orderBy ${name}.${selector} must be "asc" or "desc" on model "${model.name}"`,
               meta: { model: model.name, key: name, selector }
             });
@@ -4325,7 +4566,7 @@ function compileGroupByOrder(params) {
           let agg;
           if (selector === "_all") {
             if (key !== "_count") {
-              throw validationError3({
+              throw validationError4({
                 message: `orderBy ${name}._all is not valid \u2014 _all only counts rows (_count)`,
                 meta: { model: model.name, key: name }
               });
@@ -4343,7 +4584,7 @@ function compileGroupByOrder(params) {
       }
       const field = getFieldMeta({ model, field: name, context: "orderBy" });
       if (!byNames.has(field.name)) {
-        throw validationError3({
+        throw validationError4({
           message: `orderBy on ${model.name}.${field.name} \u2014 groupBy can only order by fields in \`by\` or by aggregates`,
           meta: { model: model.name, field: field.name }
         });
@@ -4389,7 +4630,7 @@ function resolveStrategy(params) {
   const { dialect, model, method, args, hasRelations, defaultRelationStrategy } = params;
   const explicit = args.relationStrategy;
   if (explicit !== undefined && explicit !== "query" && explicit !== "join") {
-    throw validationError3({
+    throw validationError4({
       message: `relationStrategy on ${model.clientName}.${method}() must be "query" or "join"`,
       meta: { model: model.name, method, relationStrategy: explicit }
     });
@@ -4399,7 +4640,7 @@ function resolveStrategy(params) {
   const strategy = explicit ?? defaultRelationStrategy ?? "query";
   if (strategy === "join" && !dialect.capabilities.lateralJoin) {
     if (explicit !== undefined || hasRelations) {
-      throw unsupportedCapability3({
+      throw unsupportedCapability4({
         dialect: dialect.name,
         feature: 'relationStrategy "join"',
         hint: 'lateral joins are postgres-only \u2014 use the portable "query" strategy on this dialect'
@@ -4441,7 +4682,7 @@ function buildQuery(params) {
       if (args.select[key] === undefined || args.select[key] === false)
         continue;
       if (key === "_count" || model.relationByName.has(key)) {
-        throw validationError3({
+        throw validationError4({
           message: `select.${key} on ${model.clientName}.${method}() \u2014 relations are not supported on this method`,
           meta: { model: model.name, method, field: key }
         });
@@ -4457,7 +4698,7 @@ function buildQuery(params) {
     defaultRelationStrategy: params.defaultRelationStrategy
   });
   if (args.select !== undefined && args.omit !== undefined) {
-    throw validationError3({
+    throw validationError4({
       message: `select and omit cannot combine on ${model.clientName}.${method}() \u2014 select names fields to keep, omit fields to drop`,
       meta: { model: model.name, method }
     });
@@ -4523,7 +4764,7 @@ function buildQuery(params) {
   switch (method) {
     case "findMany":
     case "findFirst": {
-      const locked = compileLock({ args, model, method, hasRelations: relations !== null });
+      const locked = compileLock({ dialect, args, model, method, hasRelations: relations !== null });
       const shape = buildFindShape({
         dialect,
         meta,
@@ -4536,13 +4777,13 @@ function buildQuery(params) {
       });
       return {
         ...base,
-        statement: locked ? { ...shape.statement, lockForUpdate: true } : shape.statement,
+        statement: locked === null ? shape.statement : { ...shape.statement, rowLock: locked },
         reverseRows: shape.reverseRows,
         resortBy: shape.resortBy
       };
     }
     case "findUnique": {
-      const locked = compileLock({ args, model, method, hasRelations: relations !== null });
+      const locked = compileLock({ dialect, args, model, method, hasRelations: relations !== null });
       const where = expandCompoundWhere({
         model,
         where: requireObject({ value: args.where, what: "where", model })
@@ -4559,7 +4800,7 @@ function buildQuery(params) {
       });
       return {
         ...base,
-        statement: locked ? { ...shape.statement, lockForUpdate: true } : shape.statement
+        statement: locked === null ? shape.statement : { ...shape.statement, rowLock: locked }
       };
     }
     case "count": {
@@ -4583,7 +4824,7 @@ function buildQuery(params) {
           if (flag === undefined || flag === false)
             continue;
           if (flag !== true) {
-            throw validationError3({
+            throw validationError4({
               message: `select.${name} must be true or false on ${model.clientName}.count()`,
               meta: { model: model.name, field: name }
             });
@@ -4604,7 +4845,7 @@ function buildQuery(params) {
           aggSelects.push({ agg: { fn: "count", column: { name: field.columnName } }, alias: field.name });
         }
         if (selections.length === 0) {
-          throw validationError3({
+          throw validationError4({
             message: `count select on model "${model.name}" must include _all or at least one field`,
             meta: { model: model.name }
           });
@@ -4707,7 +4948,7 @@ function buildQuery(params) {
       const byRaw = args.by;
       const byList = typeof byRaw === "string" ? [byRaw] : byRaw;
       if (!Array.isArray(byList) || byList.length === 0 || byList.some((name) => typeof name !== "string")) {
-        throw validationError3({
+        throw validationError4({
           message: `groupBy on model "${model.name}" needs \`by\`: a field name or a non-empty array of field names`,
           meta: { model: model.name }
         });
@@ -4715,7 +4956,7 @@ function buildQuery(params) {
       const byFields = byList.map((name) => {
         const field = getFieldMeta({ model, field: name, context: "by" });
         if (field.isList || field.scalarType === "Json") {
-          throw validationError3({
+          throw validationError4({
             message: `groupBy cannot group by ${model.name}.${field.name} (${field.isList ? "list" : "Json"} fields have no grouping equality)`,
             meta: { model: model.name, field: field.name }
           });
@@ -4754,16 +4995,16 @@ function buildQuery(params) {
       if (args.onConflict !== undefined) {
         const spec = requireObject({ value: args.onConflict, what: "onConflict", model });
         for (const key of Object.keys(spec)) {
-          if (key !== "action" && key !== "target" && key !== "where") {
-            throw validationError3({
-              message: `unknown onConflict key "${key}" on ${model.clientName}.create() \u2014 expected action/target/where`,
+          if (key !== "action" && key !== "target" && key !== "where" && key !== "update") {
+            throw validationError4({
+              message: `unknown onConflict key "${key}" on ${model.clientName}.create() \u2014 expected action/target/where/update`,
               meta: { model: model.name, key }
             });
           }
         }
-        if (spec.action !== "nothing") {
-          throw validationError3({
-            message: `onConflict.action on ${model.clientName}.create() must be "nothing" (conflicting rows are skipped \u2014 to update instead, use upsert())`,
+        if (spec.action !== "nothing" && spec.action !== "update") {
+          throw validationError4({
+            message: `onConflict.action on ${model.clientName}.create() must be "nothing" or "update"`,
             meta: { model: model.name }
           });
         }
@@ -4775,17 +5016,39 @@ function buildQuery(params) {
           target: spec.target,
           where: spec.where
         });
-        conflictClause = {
-          doNothing: true,
-          ...compiled.columns === undefined ? {} : { columns: compiled.columns },
-          ...compiled.constraint === undefined ? {} : { constraint: compiled.constraint },
-          ...compiled.conflictWhere === undefined ? {} : { conflictWhere: compiled.conflictWhere }
-        };
+        if (spec.action === "nothing" && spec.update !== undefined)
+          throw validationError4({ message: "DO NOTHING cannot carry update expressions" });
+        if (spec.action === "update") {
+          if (!dialect.capabilities.returning)
+            throw unsupportedCapability4({ dialect: dialect.name, feature: "create onConflict update returning", hint: "use upsertMany for a count-only conflict update" });
+          if (compiled.columns === undefined && compiled.constraint === undefined)
+            throw validationError4({ message: "A conflict update requires an explicit target" });
+          const updates = requireObject({ value: spec.update, what: "onConflict.update", model });
+          const fields = resolveUpsertUpdateFields({ model, update: Object.keys(updates), targetColumns: new Set(compiled.columns ?? []), skipUpdatedAt: true });
+          const columns2 = Object.fromEntries(model.fields.map((field) => [field.name, field.columnName]));
+          conflictClause = {
+            columns: compiled.columns ?? [],
+            ...compiled.constraint === undefined ? {} : { constraint: compiled.constraint },
+            ...compiled.conflictWhere === undefined ? {} : { conflictWhere: compiled.conflictWhere },
+            update: Object.fromEntries(fields.map((field) => {
+              const fragment = updates[field.name];
+              if (!isSqlFragment(fragment))
+                throw validationError4({ message: "Conflict update expressions must be constructed SQL fragments" });
+              return [field.columnName, mapConflictColumns({ fragment, columns: columns2 })];
+            }))
+          };
+        } else
+          conflictClause = {
+            doNothing: true,
+            ...compiled.columns === undefined ? {} : { columns: compiled.columns },
+            ...compiled.constraint === undefined ? {} : { constraint: compiled.constraint },
+            ...compiled.conflictWhere === undefined ? {} : { conflictWhere: compiled.conflictWhere }
+          };
       }
       const row = compileCreateRow({ dialect, model, data: args.data });
       const columns = orderedColumns({ model, values: row.values });
       if (columns.length === 0) {
-        throw validationError3({
+        throw validationError4({
           message: `create on model "${model.name}" needs at least one field value`,
           meta: { model: model.name }
         });
@@ -4806,7 +5069,7 @@ function buildQuery(params) {
     case "createMany":
     case "createManyAndReturn": {
       if (method === "createManyAndReturn" && !dialect.capabilities.createManyAndReturn) {
-        throw unsupportedCapability3({
+        throw unsupportedCapability4({
           dialect: dialect.name,
           feature: "createManyAndReturn",
           hint: "this dialect cannot RETURNING multiple inserted rows \u2014 use createMany then findMany"
@@ -4820,7 +5083,7 @@ function buildQuery(params) {
         const spec = requireObject({ value: args.skipDuplicates, what: "skipDuplicates", model });
         for (const key of Object.keys(spec)) {
           if (key !== "target" && key !== "where") {
-            throw validationError3({
+            throw validationError4({
               message: `unknown skipDuplicates key "${key}" on ${model.clientName}.${method}() \u2014 expected target/where`,
               meta: { model: model.name, key }
             });
@@ -4858,7 +5121,7 @@ function buildQuery(params) {
     case "upsertMany": {
       for (const flag of ["skipUpdatedAt", "allowAnyUniqueConflict"]) {
         if (args[flag] !== undefined && typeof args[flag] !== "boolean") {
-          throw validationError3({
+          throw validationError4({
             message: `${flag} on ${model.clientName}.upsertMany() must be a boolean, got ${String(args[flag])}`,
             meta: { model: model.name, argument: flag }
           });
@@ -4871,9 +5134,10 @@ function buildQuery(params) {
       });
       const conflictTarget = resolveUpsertConflictTarget({ model, target: args.conflictTarget });
       const targetColumns = conflictTarget.kind === "columns" ? conflictTarget.fields.map((field) => field.columnName) : [];
+      const expressionUpdate = isPlainObject3(args.update) ? args.update : undefined;
       const updateFields = resolveUpsertUpdateFields({
         model,
-        update: args.update,
+        update: expressionUpdate === undefined ? args.update : Object.keys(expressionUpdate),
         targetColumns: new Set(targetColumns),
         skipUpdatedAt: args.skipUpdatedAt === true
       });
@@ -4917,7 +5181,14 @@ function buildQuery(params) {
         columns: targetColumns,
         ...namedConstraint === undefined ? {} : { constraint: namedConstraint },
         ...partialArbiter === undefined ? {} : { conflictWhere: partialArbiter },
-        update: Object.fromEntries(updateFields.map((field) => [field.columnName, excludedRef({ column: field.columnName })]))
+        update: Object.fromEntries(updateFields.map((field) => {
+          if (expressionUpdate === undefined || !Object.hasOwn(expressionUpdate, field.name))
+            return [field.columnName, excludedRef({ column: field.columnName })];
+          const fragment = expressionUpdate[field.name];
+          if (!isSqlFragment(fragment))
+            throw validationError4({ message: "Conflict update expressions must be constructed SQL fragments" });
+          return [field.columnName, mapConflictColumns({ fragment, columns: Object.fromEntries(model.fields.map((entry) => [entry.name, entry.columnName])) })];
+        }))
       };
       const upsertStatements = upsertGroups.map((group) => ({
         kind: "insert",
@@ -4938,14 +5209,14 @@ function buildQuery(params) {
     case "updateManyAndReturn": {
       const isUnique = method === "update";
       if (method === "updateManyAndReturn" && !dialect.capabilities.returning) {
-        throw unsupportedCapability3({
+        throw unsupportedCapability4({
           dialect: dialect.name,
           feature: "updateManyAndReturn",
           hint: "this dialect has no RETURNING \u2014 use updateMany then findMany, accepting that the read is a separate, unprotected statement"
         });
       }
       if (args.skipUpdatedAt !== undefined && typeof args.skipUpdatedAt !== "boolean") {
-        throw validationError3({
+        throw validationError4({
           message: `skipUpdatedAt on ${model.clientName}.${method}() must be a boolean, got ${String(args.skipUpdatedAt)}`,
           meta: { model: model.name, method }
         });
@@ -4977,13 +5248,13 @@ function buildQuery(params) {
       if (args.onConflict !== undefined) {
         const spec = requireObject({ value: args.onConflict, what: "onConflict", model });
         if (typeof spec.constraint !== "string" || spec.constraint.length === 0 || Object.keys(spec).length !== 1) {
-          throw validationError3({
+          throw validationError4({
             message: `onConflict on ${model.clientName}.upsert() must be { constraint: string } \u2014 the named unique constraint that arbitrates the conflict`,
             meta: { model: model.name }
           });
         }
         if (!dialect.capabilities.conflictTargetConstraint) {
-          throw unsupportedCapability3({
+          throw unsupportedCapability4({
             dialect: dialect.name,
             feature: "a named-constraint conflict target on upsert",
             hint: "only postgres supports ON CONFLICT ON CONSTRAINT \u2014 rely on the where-derived column target instead"
@@ -5001,7 +5272,7 @@ function buildQuery(params) {
       const targetFields = conflictTargetGroup({ model, where }).fields;
       for (const field of targetFields) {
         if (!(field.columnName in row.values)) {
-          throw new VibeError8({
+          throw new VibeError10({
             code: "VIBE_INTERNAL",
             message: `upsert on ${model.name}: create data does not bind conflict-target column "${field.columnName}" \u2014 this shape must run the find-then-write fallback flow`,
             meta: { model: model.name, column: field.columnName }
@@ -5012,7 +5283,7 @@ function buildQuery(params) {
       for (const [key, value] of Object.entries(where)) {
         if (value === undefined || nativeTargetNames.has(key))
           continue;
-        throw new VibeError8({
+        throw new VibeError10({
           code: "VIBE_INTERNAL",
           message: `upsert on ${model.name}: where field "${key}" is not part of the conflict target \u2014 guarded upserts must run the find-then-write fallback flow`,
           meta: { model: model.name, field: key }
@@ -5065,7 +5336,7 @@ function buildQuery(params) {
 import { getSqlDialect, renderStatement } from "@vibeorm/sql";
 
 // packages/runtime/src/relation-key.ts
-import { VibeError as VibeError9 } from "@vibeorm/schema";
+import { VibeError as VibeError11 } from "@vibeorm/schema";
 function relationValueKey(params) {
   const { value } = params;
   if (value === null || value === undefined)
@@ -5098,7 +5369,7 @@ function relationTupleKey(params) {
     if (value === null || value === undefined)
       return null;
     if (typeof value === "object" && !(value instanceof Date) && !(value instanceof Uint8Array)) {
-      throw new VibeError9({
+      throw new VibeError11({
         code: "VIBE_UNSUPPORTED_CAPABILITY",
         message: "a relation key of this type cannot be compared faithfully in memory \u2014 relation links support String, Int, BigInt, Boolean, DateTime and Bytes keys",
         meta: { received: Object.prototype.toString.call(value) }
@@ -5124,7 +5395,7 @@ function assertWriteScope(params) {
 }
 
 // packages/runtime/src/nested-writes.ts
-import { VibeError as VibeError10 } from "@vibeorm/schema";
+import { VibeError as VibeError12 } from "@vibeorm/schema";
 function parentTupleOf(params) {
   const { link, row } = params;
   return link.parentKeys.map((field) => row[field.name]);
@@ -5160,7 +5431,7 @@ function detachAssignment(params) {
   const { fields, op, verb, target } = params;
   const optional = fields.filter((field) => field.isOptional);
   if (optional.length === 0) {
-    throw validationError4({
+    throw validationError5({
       message: `nested "${verb}" on ${op.link.relation.model}.${op.name} needs an optional foreign key on ${target}.${fields.map((field) => field.name).join(", ")} \u2014 a required relation cannot be detached`,
       meta: { relation: op.name, verb }
     });
@@ -5170,11 +5441,11 @@ function detachAssignment(params) {
     out[field.name] = null;
   return out;
 }
-function validationError4(params) {
-  return new VibeError10({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta });
+function validationError5(params) {
+  return new VibeError12({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta });
 }
 function notFound(params) {
-  return new VibeError10({ code: "VIBE_NOT_FOUND", message: params.message, meta: params.meta });
+  return new VibeError12({ code: "VIBE_NOT_FOUND", message: params.message, meta: params.meta });
 }
 function isPlainObject4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date) && !(value instanceof Uint8Array);
@@ -5225,7 +5496,7 @@ function partitionData(params) {
       continue;
     }
     if (!isPlainObject4(value)) {
-      throw validationError4({
+      throw validationError5({
         message: `relation ${model.name}.${key} in data must be an object of nested-write operations`,
         meta: { model: model.name, relation: key }
       });
@@ -5239,7 +5510,7 @@ function partitionData(params) {
         continue;
       }
       if (!allowed.includes(verb)) {
-        throw validationError4({
+        throw validationError5({
           message: `unknown nested-write operation "${verb}" on ${model.name}.${key} (${phase}) \u2014 supported: ${allowed.join(", ")}`,
           meta: { model: model.name, relation: key, verb, phase }
         });
@@ -5247,7 +5518,7 @@ function partitionData(params) {
       verbs[verb] = operand;
     }
     if (Object.keys(verbs).length === 0) {
-      throw validationError4({
+      throw validationError5({
         message: `relation ${model.name}.${key} in data carries no nested-write operation`,
         meta: { model: model.name, relation: key }
       });
@@ -5260,14 +5531,14 @@ function toItems(params) {
   const { op, verb, operand } = params;
   const list = Array.isArray(operand) ? operand : [operand];
   if (!op.link.relation.isList && Array.isArray(operand)) {
-    throw validationError4({
+    throw validationError5({
       message: `nested "${verb}" on to-one relation ${op.link.relation.model}.${op.name} cannot take an array`,
       meta: { relation: op.name, verb }
     });
   }
   return list.map((item) => {
     if (!isPlainObject4(item)) {
-      throw validationError4({
+      throw validationError5({
         message: `nested "${verb}" on ${op.link.relation.model}.${op.name} expects object items`,
         meta: { relation: op.name, verb }
       });
@@ -5279,7 +5550,7 @@ function requireShape(params) {
   const { op, verb, item, keys } = params;
   for (const key of keys) {
     if (!isPlainObject4(item[key])) {
-      throw validationError4({
+      throw validationError5({
         message: `nested "${verb}" on ${op.link.relation.model}.${op.name} needs an object "${key}"`,
         meta: { relation: op.name, verb, missing: key }
       });
@@ -5399,7 +5670,7 @@ function singleVerb(params) {
   const { op } = params;
   const entries = Object.entries(op.verbs);
   if (entries.length !== 1) {
-    throw validationError4({
+    throw validationError5({
       message: `to-one relation ${op.link.relation.model}.${op.name} takes exactly one nested-write operation, got: ${entries.map(([verb]) => verb).join(", ")}`,
       meta: { relation: op.name, verbs: entries.map(([verb]) => verb) }
     });
@@ -5553,7 +5824,7 @@ function updateDataOf(params) {
   if ("data" in operand && isPlainObject4(operand.data))
     return operand.data;
   if ("data" in operand) {
-    throw validationError4({
+    throw validationError5({
       message: `nested "update" on ${op.link.relation.model}.${op.name} needs an object "data"`,
       meta: { relation: op.name }
     });
@@ -5610,7 +5881,7 @@ async function resolveOwnerUpdateVerb(params) {
       if (operand === false)
         return;
       if (!link.relation.isOptional) {
-        throw validationError4({
+        throw validationError5({
           message: `nested "disconnect" on required relation ${link.relation.model}.${op.name} \u2014 connect a replacement instead`,
           meta: { relation: op.name }
         });
@@ -5622,7 +5893,7 @@ async function resolveOwnerUpdateVerb(params) {
       if (operand === false)
         return;
       if (!link.relation.isOptional) {
-        throw validationError4({
+        throw validationError5({
           message: `nested "delete" on required relation ${link.relation.model}.${op.name} \u2014 the parent cannot exist without it`,
           meta: { relation: op.name }
         });
@@ -5642,7 +5913,7 @@ async function resolveOwnerUpdateVerb(params) {
     }
     case "update": {
       if (!isPlainObject4(operand)) {
-        throw validationError4({
+        throw validationError5({
           message: `nested "update" on ${link.relation.model}.${op.name} expects an object`,
           meta: { relation: op.name }
         });
@@ -5665,7 +5936,7 @@ async function resolveOwnerUpdateVerb(params) {
     }
     default: {
       if (!isPlainObject4(operand)) {
-        throw validationError4({
+        throw validationError5({
           message: `nested "upsert" on ${link.relation.model}.${op.name} expects an object`,
           meta: { relation: op.name }
         });
@@ -5806,7 +6077,7 @@ async function applyChildUpdateOps(params) {
       case "update": {
         if (link.kind === "toOneInverse") {
           if (!isPlainObject4(operand)) {
-            throw validationError4({
+            throw validationError5({
               message: `nested "update" on ${link.relation.model}.${op.name} expects an object`,
               meta: { relation: op.name }
             });
@@ -5869,7 +6140,7 @@ async function applyChildUpdateOps(params) {
         for (const item of items) {
           const data = item.data;
           if (!isPlainObject4(data)) {
-            throw validationError4({
+            throw validationError5({
               message: `nested "updateMany" on ${link.relation.model}.${op.name} needs an object "data"`,
               meta: { relation: op.name }
             });
@@ -5940,7 +6211,7 @@ async function applyChildUpdateOps(params) {
       default: {
         if (link.kind === "toOneInverse") {
           if (!isPlainObject4(operand)) {
-            throw validationError4({
+            throw validationError5({
               message: `nested "upsert" on ${link.relation.model}.${op.name} expects an object`,
               meta: { relation: op.name }
             });
@@ -6278,7 +6549,7 @@ function previewOperation(params) {
   };
 }
 // packages/runtime/src/diagnostics/plan.ts
-import { VibeError as VibeError11, unsupportedCapability as unsupportedCapability4 } from "@vibeorm/schema";
+import { VibeError as VibeError13, unsupportedCapability as unsupportedCapability5 } from "@vibeorm/schema";
 import { NATIVE_RLS, getSqlDialect as getSqlDialect2, renderPostgresExplain, renderPostgresWorkload, renderStatement as renderStatement2 } from "@vibeorm/sql";
 var PLAN_DEFAULTS = Object.freeze({ maxNodes: 200, maxConditionLength: 2000 });
 var CONDITION_KEYS = [
@@ -6297,7 +6568,7 @@ var CONDITION_KEYS = [
   "Output"
 ];
 function planError(params) {
-  return new VibeError11({ code: "VIBE_ADAPTER", message: params.message, meta: {} });
+  return new VibeError13({ code: "VIBE_ADAPTER", message: params.message, meta: {} });
 }
 function asRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
@@ -6330,14 +6601,14 @@ function parsePostgresPlan(params) {
   const maxNodes = params.maxNodes ?? PLAN_DEFAULTS.maxNodes;
   const includeLiterals = params.includeLiterals === true;
   if (!Number.isInteger(maxNodes) || maxNodes < 1) {
-    throw new VibeError11({ code: "VIBE_CONFIG", message: `maxNodes must be a positive integer, got ${String(maxNodes)}`, meta: { maxNodes } });
+    throw new VibeError13({ code: "VIBE_CONFIG", message: `maxNodes must be a positive integer, got ${String(maxNodes)}`, meta: { maxNodes } });
   }
   let parsed = payload;
   if (typeof payload === "string") {
     try {
       parsed = JSON.parse(payload);
     } catch {
-      throw new VibeError11({
+      throw new VibeError13({
         code: "VIBE_ADAPTER",
         message: "EXPLAIN returned malformed JSON",
         meta: { reason: "malformed-plan-json", mode }
@@ -6404,7 +6675,7 @@ function parsePostgresPlan(params) {
 }
 var WRITE_LEADERS = ["INSERT", "UPDATE", "DELETE", "MERGE", "TRUNCATE", "CREATE", "DROP", "ALTER", "GRANT", "REVOKE", "COPY", "CALL", "DO"];
 function refuse(params) {
-  return new VibeError11({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta ?? {} });
+  return new VibeError13({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta ?? {} });
 }
 function assertExecutableRead(params) {
   const normalized = normalizeSql({ text: params.text });
@@ -6443,7 +6714,7 @@ async function readPlanContext(params) {
 }
 function requirePostgres(params) {
   if (params.dialect !== "postgres") {
-    throw unsupportedCapability4({
+    throw unsupportedCapability5({
       dialect: params.dialect,
       feature: "query plan inspection",
       hint: "plan inspection is PostgreSQL-shaped; operation tracing (telemetry) works on every dialect"
@@ -6452,7 +6723,7 @@ function requirePostgres(params) {
   return getSqlDialect2({ dialect: params.dialect });
 }
 async function explainSql(params) {
-  const { executor, sql, rlsContext } = params;
+  const { executor, sql: sql2, rlsContext } = params;
   const mode = params.mode ?? "estimate";
   const dialect = requirePostgres({ dialect: params.dialect });
   const warnings = [];
@@ -6469,7 +6740,7 @@ async function explainSql(params) {
         meta: { mode }
       });
     }
-    assertExecutableRead({ text: sql.text });
+    assertExecutableRead({ text: sql2.text });
     warnings.push("this statement was EXECUTED to produce observed rows and milliseconds; a read-only transaction and a keyword check are not a proof of safety, because a SELECT can call a function with side effects");
   }
   const contextKeys = rlsContext === undefined ? [] : Object.keys(rlsContext);
@@ -6495,7 +6766,7 @@ async function explainSql(params) {
     const context = await readPlanContext({ executor, dialect, rlsContextKeys: contextKeys });
     if (!context.representative) {
       if (params.requireRepresentativeContext === true) {
-        throw new VibeError11({
+        throw new VibeError13({
           code: "VIBE_RLS_CONTEXT",
           message: `refusing to report a plan taken under a non-representative identity: ${context.reason ?? "role bypasses row policies"}`,
           meta: { currentUser: context.currentUser, bypassRls: context.bypassRls, superuser: context.superuser }
@@ -6505,7 +6776,7 @@ async function explainSql(params) {
     }
     const explain = renderPostgresExplain({
       dialect,
-      query: { text: sql.text, values: [...sql.values], returning: "none" },
+      query: { text: sql2.text, values: [...sql2.values], returning: "none" },
       options: mode === "analyze" ? { analyze: true, buffers: true } : {}
     });
     const rows = await run(explain);
@@ -6577,7 +6848,7 @@ async function explainOperation(params) {
   });
 }
 // packages/runtime/src/diagnostics/workload.ts
-import { unsupportedCapability as unsupportedCapability5 } from "@vibeorm/schema";
+import { unsupportedCapability as unsupportedCapability6 } from "@vibeorm/schema";
 import { getSqlDialect as getSqlDialect3, renderPostgresWorkload as renderPostgresWorkload2 } from "@vibeorm/sql";
 var STATEMENTS_INFO_MIN_VERSION = 140000;
 var STATEMENTS_MIN_VERSION = 130000;
@@ -6610,7 +6881,7 @@ async function readAvailability(params) {
 async function readWorkloadStatistics(params) {
   const { executor } = params;
   if (params.dialect !== "postgres") {
-    throw unsupportedCapability5({
+    throw unsupportedCapability6({
       dialect: params.dialect,
       feature: "workload statistics (pg_stat_statements)",
       hint: "server workload statistics are PostgreSQL-only; operation telemetry works on every dialect"
@@ -6688,7 +6959,7 @@ async function readWorkloadStatistics(params) {
   };
 }
 // packages/runtime/src/diagnostics/insight.ts
-import { VibeError as VibeError12 } from "@vibeorm/schema";
+import { VibeError as VibeError14 } from "@vibeorm/schema";
 var DIAGNOSTIC_THRESHOLDS = Object.freeze({
   repeatThreshold: 5,
   minRepeatThreshold: 2,
@@ -6706,7 +6977,7 @@ function bounded(params) {
   if (value === undefined)
     return fallback;
   if (!Number.isInteger(value) || value < min || value > max) {
-    throw new VibeError12({
+    throw new VibeError14({
       code: "VIBE_CONFIG",
       message: `${name} must be an integer between ${min} and ${max}, got ${String(value)}`,
       meta: { [name]: value }
@@ -6929,11 +7200,11 @@ function recommendFromPlan(params) {
   return findings.slice(0, maxFindings);
 }
 // packages/runtime/src/relation-loader.ts
-import { VibeError as VibeError14 } from "@vibeorm/schema";
+import { VibeError as VibeError16 } from "@vibeorm/schema";
 import { renderStatement as renderStatement3 } from "@vibeorm/sql";
 
 // packages/runtime/src/computed.ts
-import { VibeError as VibeError13 } from "@vibeorm/schema";
+import { VibeError as VibeError15 } from "@vibeorm/schema";
 function sameNeeds(a, b) {
   if (a.length !== b.length)
     return false;
@@ -6969,7 +7240,7 @@ function assertComputedManifest(params) {
     problems.push(`"${key}" is configured but missing from the generated client`);
   }
   if (problems.length > 0) {
-    throw new VibeError13({
+    throw new VibeError15({
       code: "VIBE_STALE_CLIENT",
       message: `computed-field config changed since generate; run vibeorm generate \u2014 ${problems.join("; ")}`,
       meta: { problems }
@@ -7101,7 +7372,7 @@ function chunkKeys(params) {
     const rendered = renderStatement3({ dialect: ctx.dialect, statement: build(keys.slice(0, 1)) });
     fixed = rendered.values.length - (expands ? arity : 1);
     if (fixed + arity > budget) {
-      throw new VibeError14({
+      throw new VibeError16({
         code: "VIBE_UNSUPPORTED_CAPABILITY",
         message: `relation "${relation}" needs ${fixed + arity} bound parameters for its own predicate, more than ${ctx.dialect.name}'s ${budget}-parameter statement budget \u2014 narrow the nested filter`,
         meta: { relation, dialect: ctx.dialect.name, required: fixed + arity, budget }
@@ -7231,7 +7502,7 @@ async function loadManyToMany(params) {
   const link = node.link;
   const join = link.join;
   if (join === null) {
-    throw new VibeError14({
+    throw new VibeError16({
       code: "VIBE_INTERNAL",
       message: `manyToMany relation "${node.name}" resolved without join-table wiring`
     });
@@ -7510,7 +7781,7 @@ async function attachLateralRelations(params) {
         try {
           parsed = JSON.parse(raw);
         } catch (cause) {
-          throw new VibeError14({
+          throw new VibeError16({
             code: "VIBE_INTERNAL",
             message: `relation column "${column}" returned text that is not valid JSON`,
             meta: { relation: node.name },
@@ -7520,7 +7791,7 @@ async function attachLateralRelations(params) {
       }
       if (isList) {
         if (!Array.isArray(parsed)) {
-          throw new VibeError14({ code: "VIBE_INTERNAL", message: "to-many relation payload must be an array", meta: { relation: node.name } });
+          throw new VibeError16({ code: "VIBE_INTERNAL", message: "to-many relation payload must be an array", meta: { relation: node.name } });
         }
         const children = parsed.map(decodePosition);
         for (const child of children) {
@@ -7552,7 +7823,7 @@ async function attachLateralRelations(params) {
       const raw = row[column];
       const count = typeof raw === "number" || typeof raw === "bigint" || typeof raw === "string" && /^\d+$/.test(raw) ? Number(raw) : NaN;
       if (!Number.isSafeInteger(count) || count < 0) {
-        throw new VibeError14({ code: "VIBE_INTERNAL", message: "relation count payload must be a non-negative safe integer", meta: { relation: selection.counts[index]?.name } });
+        throw new VibeError16({ code: "VIBE_INTERNAL", message: "relation count payload must be a non-negative safe integer", meta: { relation: selection.counts[index]?.name } });
       }
       counts[selection.counts[index].name] = count;
       delete row[column];
@@ -7561,7 +7832,7 @@ async function attachLateralRelations(params) {
   }
 }
 // packages/runtime/src/extensions.ts
-import { VibeError as VibeError15, extensionManifestEntry } from "@vibeorm/schema";
+import { VibeError as VibeError17, extensionManifestEntry } from "@vibeorm/schema";
 function assertExtensionManifest(params) {
   const { manifest } = params;
   const instances = params.instances ?? [];
@@ -7584,7 +7855,7 @@ function assertExtensionManifest(params) {
     problems.push(`"${name}" is configured but missing from the generated client`);
   }
   if (problems.length > 0) {
-    throw new VibeError15({
+    throw new VibeError17({
       code: "VIBE_STALE_CLIENT",
       message: `extension list changed since generate; run vibeorm generate \u2014 ${problems.join("; ")}`,
       meta: { manifest, problems }
@@ -7599,7 +7870,7 @@ function buildExtensionOperatorMap(params) {
     for (const operator of extension.sql?.whereOperators ?? []) {
       const existing = owner.get(operator.name);
       if (existing !== undefined) {
-        throw new VibeError15({
+        throw new VibeError17({
           code: "VIBE_CONFIG",
           message: `where operator "${operator.name}" is claimed by both "${existing}" and "${extension.name}"`,
           meta: { operator: operator.name }
@@ -7615,7 +7886,7 @@ function buildExtensionOperatorMap(params) {
           options: extension.options
         });
         if ("error" in compiled) {
-          throw new VibeError15({
+          throw new VibeError17({
             code: "VIBE_VALIDATION",
             message: `"${operator.name}" on ${model}.${field}: ${compiled.error}`,
             meta: { model, field, operator: operator.name, extension: extension.name }
@@ -7647,9 +7918,53 @@ function buildConnectHooks(params) {
   return hooks;
 }
 // packages/runtime/src/views.ts
-import { VibeError as VibeError16 } from "@vibeorm/schema";
-function validationError5(params) {
-  return new VibeError16({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta });
+import { VibeError as VibeError19 } from "@vibeorm/schema";
+
+// packages/runtime/src/sql-access.ts
+import { VibeError as VibeError18 } from "@vibeorm/schema";
+import { isSqlFragment as isSqlFragment2 } from "@vibeorm/sql";
+function containsSqlFragment(value, seen = new Set) {
+  if (isSqlFragment2(value))
+    return true;
+  if (typeof value !== "object" || value === null || seen.has(value))
+    return false;
+  seen.add(value);
+  if (Array.isArray(value))
+    return value.some((entry) => containsSqlFragment(entry, seen));
+  return Object.values(value).some((entry) => containsSqlFragment(entry, seen));
+}
+function restrictedSqlArgs(params) {
+  const seen = new Map;
+  const copy = (value) => {
+    if (isSqlFragment2(value))
+      throw new VibeError18({ code: "VIBE_VALIDATION", message: `SQL fragments are unavailable through ${params.path}; use the unrestricted client`, meta: { path: params.path } });
+    if (typeof value !== "object" || value === null)
+      return value;
+    if (seen.has(value))
+      return seen.get(value);
+    if (Array.isArray(value)) {
+      const out2 = [];
+      seen.set(value, out2);
+      for (const item of value)
+        out2.push(copy(item));
+      return out2;
+    }
+    if (value instanceof Date)
+      return new Date(value.getTime());
+    if (value instanceof Uint8Array)
+      return new Uint8Array(value);
+    const out = Object.create(null);
+    seen.set(value, out);
+    for (const [key, child] of Object.entries(value))
+      out[key] = copy(child);
+    return out;
+  };
+  return copy(params.value);
+}
+
+// packages/runtime/src/views.ts
+function validationError6(params) {
+  return new VibeError19({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta });
 }
 
 class ViewResult {
@@ -7704,7 +8019,7 @@ function isPlainObject5(value) {
 function resolveDefinition(params) {
   const { meta, name, definition } = params;
   if (!isPlainObject5(definition)) {
-    throw validationError5({
+    throw validationError6({
       message: `view "${name}": definition must be an object of { modelKey: { field: true } }`,
       meta: { view: name }
     });
@@ -7715,13 +8030,13 @@ function resolveDefinition(params) {
       continue;
     const model = meta.modelByName.get(key);
     if (model === undefined) {
-      throw validationError5({
+      throw validationError6({
         message: `view "${name}": unknown model "${key}" in the definition`,
         meta: { view: name, model: key }
       });
     }
     if (!isPlainObject5(fieldSpec)) {
-      throw validationError5({
+      throw validationError6({
         message: `view "${name}": definition.${key} must be an object of { field: true }`,
         meta: { view: name, model: model.name }
       });
@@ -7731,14 +8046,14 @@ function resolveDefinition(params) {
       if (flag === undefined || flag === false)
         continue;
       if (flag !== true) {
-        throw validationError5({
+        throw validationError6({
           message: `view "${name}": definition.${key}.${field} must be true`,
           meta: { view: name, model: model.name, field }
         });
       }
       if (!model.fieldByName.has(field)) {
         const isRelation = model.relationByName.has(field);
-        throw validationError5({
+        throw validationError6({
           message: isRelation ? `view "${name}": "${field}" on model "${model.name}" is a relation \u2014 a view definition lists scalar fields; relations are restricted through the related model's own entry` : `view "${name}": unknown field "${field}" on model "${model.name}"`,
           meta: { view: name, model: model.name, field }
         });
@@ -7746,7 +8061,7 @@ function resolveDefinition(params) {
       fields.add(field);
     }
     if (fields.size === 0) {
-      throw validationError5({
+      throw validationError6({
         message: `view "${name}": definition.${key} exposes no fields`,
         meta: { view: name, model: model.name }
       });
@@ -7754,7 +8069,7 @@ function resolveDefinition(params) {
     resolved.set(model.clientName, { model, fields });
   }
   if (resolved.size === 0) {
-    throw validationError5({
+    throw validationError6({
       message: `view "${name}": the definition names no models`,
       meta: { view: name }
     });
@@ -7776,7 +8091,7 @@ function revealSet(params) {
   if (reveal === undefined)
     return revealed;
   if (!isPlainObject5(reveal)) {
-    throw validationError5({
+    throw validationError6({
       message: `view "${name}": reveal must be an object of { field: true }`,
       meta: { view: name, model: mask.model.name }
     });
@@ -7785,13 +8100,13 @@ function revealSet(params) {
     if (flag === undefined || flag === false)
       continue;
     if (flag !== true) {
-      throw validationError5({
+      throw validationError6({
         message: `view "${name}": reveal.${field} must be true or false`,
         meta: { view: name, model: mask.model.name, field }
       });
     }
     if (!mask.model.fieldByName.has(field)) {
-      throw validationError5({
+      throw validationError6({
         message: `view "${name}": cannot reveal "${field}" \u2014 not a scalar field of model "${mask.model.name}"`,
         meta: { view: name, model: mask.model.name, field }
       });
@@ -7805,7 +8120,7 @@ function mergeLevel(params) {
   const { meta, name, definition, mask, args } = params;
   const model = mask.model;
   if (args.omit !== undefined) {
-    throw validationError5({
+    throw validationError6({
       message: `view "${name}": omit is not available on a view query \u2014 the definition already restricts ${model.name}'s fields`,
       meta: { view: name, model: model.name }
     });
@@ -7814,7 +8129,7 @@ function mergeLevel(params) {
   let scalars;
   const userSelect = args.select;
   if (userSelect !== undefined && !isPlainObject5(userSelect)) {
-    throw validationError5({
+    throw validationError6({
       message: `view "${name}": select must be an object`,
       meta: { view: name, model: model.name }
     });
@@ -7838,7 +8153,7 @@ function mergeLevel(params) {
     if (source === undefined)
       return;
     if (!isPlainObject5(source)) {
-      throw validationError5({
+      throw validationError6({
         message: `view "${name}": ${argName} must be an object`,
         meta: { view: name, model: model.name }
       });
@@ -7853,7 +8168,7 @@ function mergeLevel(params) {
       if (model.relationByName.has(key))
         relationSpecs.set(key, spec);
       else if (argName === "include") {
-        throw validationError5({
+        throw validationError6({
           message: `view "${name}": unknown relation "${key}" on model "${model.name}" in include`,
           meta: { view: name, model: model.name, relation: key }
         });
@@ -7886,7 +8201,7 @@ function mergeLevel(params) {
       continue;
     }
     if (!isPlainObject5(spec)) {
-      throw validationError5({
+      throw validationError6({
         message: `view "${name}": include.${relationName} must be true or an object`,
         meta: { view: name, model: model.name, relation: relationName }
       });
@@ -7947,9 +8262,9 @@ var VIEW_WRITE_METHODS = [
 function createViewDelegate(params) {
   const { meta, name, definition, mask, delegate } = params;
   const merge = (args) => {
-    const raw = args ?? {};
+    const raw = restrictedSqlArgs({ value: args ?? {}, path: "$defineView" });
     if (!isPlainObject5(raw)) {
-      throw validationError5({
+      throw validationError6({
         message: `view "${name}": query args must be an object`,
         meta: { view: name, model: mask.model.name }
       });
@@ -7982,13 +8297,13 @@ function createViewDelegate(params) {
       const { merged, plan } = merge(args);
       return wrapRows({ rows: [await delegate.findUniqueOrThrow(merged)], plan })[0];
     },
-    count: (args) => delegate.count(args),
-    aggregate: (args) => delegate.aggregate(args),
-    groupBy: (args) => delegate.groupBy(args)
+    count: (args) => delegate.count(restrictedSqlArgs({ value: args, path: "$defineView" })),
+    aggregate: (args) => delegate.aggregate(restrictedSqlArgs({ value: args, path: "$defineView" })),
+    groupBy: (args) => delegate.groupBy(restrictedSqlArgs({ value: args, path: "$defineView" }))
   };
   for (const method of VIEW_WRITE_METHODS) {
     view[method] = () => {
-      throw validationError5({
+      throw validationError6({
         message: `view "${name}" is read-only \u2014 ${method}() is not available on a field-masking view; write through the base client instead`,
         meta: { view: name, model: mask.model.name, method }
       });
@@ -8003,7 +8318,7 @@ function createView(params) {
   for (const [clientName, mask] of resolved) {
     const delegate = models[clientName];
     if (delegate === undefined) {
-      throw new VibeError16({
+      throw new VibeError19({
         code: "VIBE_INTERNAL",
         message: `view "${name}": no delegate for model "${mask.model.name}"`,
         meta: { view: name, model: mask.model.name }
@@ -8019,9 +8334,9 @@ function attachDefineView(params) {
   Object.defineProperty(client, "$defineView", { value, enumerable: true });
 }
 // packages/runtime/src/validators.ts
-import { VibeError as VibeError17 } from "@vibeorm/schema";
+import { VibeError as VibeError20 } from "@vibeorm/schema";
 function validationFailed(params) {
-  return new VibeError17({
+  return new VibeError20({
     code: "VIBE_VALIDATION",
     message: `validation failed for ${params.model}.${params.field}: ${params.issues[0]?.message ?? "invalid value"}`,
     meta: { model: params.model, field: params.field, issues: params.issues }
@@ -8030,7 +8345,7 @@ function validationFailed(params) {
 function validateValue(params) {
   const result = params.schema["~standard"].validate(params.value);
   if (result instanceof Promise) {
-    throw new VibeError17({
+    throw new VibeError20({
       code: "VIBE_VALIDATION",
       message: `async validator on ${params.model}.${params.field} \u2014 write validators must be synchronous (validate before calling the client for async rules)`,
       meta: { model: params.model, field: params.field }
@@ -8153,9 +8468,270 @@ function deferPolicyOperation(params) {
 }
 
 // packages/runtime/src/policy.ts
-import { VibeError as VibeError18 } from "@vibeorm/schema";
+import { VibeError as VibeError21 } from "@vibeorm/schema";
+
+// packages/runtime/src/read-only.ts
+import { ReadOnlyClientError } from "@vibeorm/schema";
+var READ_DELEGATE_METHODS = Object.freeze([
+  "findMany",
+  "findFirst",
+  "findFirstOrThrow",
+  "findUnique",
+  "findUniqueOrThrow",
+  "count",
+  "aggregate",
+  "groupBy"
+]);
+var WRITE_DELEGATE_METHODS = Object.freeze([
+  "create",
+  "createMany",
+  "createManyAndReturn",
+  "update",
+  "updateMany",
+  "updateManyAndReturn",
+  "upsert",
+  "upsertMany",
+  "delete",
+  "deleteMany"
+]);
+var DELEGATE_METHOD_ACCESS = Object.freeze(Object.fromEntries([
+  ...READ_DELEGATE_METHODS.map((method) => [method, "read"]),
+  ...WRITE_DELEGATE_METHODS.map((method) => [method, "write"])
+]));
+function delegateMethodAccess(params) {
+  return Object.hasOwn(DELEGATE_METHOD_ACCESS, params.method) ? DELEGATE_METHOD_ACCESS[params.method] : undefined;
+}
+var CLIENT_MEMBER_ACCESS = Object.freeze({
+  $models: "rebuilt",
+  $on: "forwarded",
+  $transaction: "rebuilt",
+  $defineView: "rebuilt",
+  $scoped: "rebuilt",
+  $withPolicy: "rebuilt",
+  $bypassPolicy: "rebuilt",
+  $readOnly: "rebuilt",
+  $querySql: "raw",
+  $executeSql: "raw",
+  $queryRaw: "raw",
+  $executeRaw: "raw",
+  $queryRawUnsafe: "raw",
+  $executeRawUnsafe: "raw",
+  $connect: "control",
+  $disconnect: "control",
+  $advisoryLock: "control",
+  $tryAdvisoryLock: "control",
+  $withContext: "control"
+});
+function clientMemberAccess(params) {
+  return Object.hasOwn(CLIENT_MEMBER_ACCESS, params.member) ? CLIENT_MEMBER_ACCESS[params.member] : undefined;
+}
+var REASON_HINTS = Object.freeze({
+  write: "it writes rows \u2014 run it on the writable client",
+  raw: "raw SQL is not available on a read-only client (a SELECT-shaped statement is not proof of a read); run it on the writable client, or use a database read-only role when the database itself must enforce it",
+  control: "it controls the connection or the transaction rather than reading; run it on the writable client",
+  unclassified: "it is not classified as a read \u2014 extensions opt in per surface, and anything unclassified stays denied",
+  foreign_operation: "$transaction([...]) on a read-only client takes read operations only; this one would write"
+});
+function readOnlyRefusal(params) {
+  const { path, reason } = params;
+  return new ReadOnlyClientError({
+    path,
+    reason,
+    message: `$readOnly: ${path}${reason === "foreign_operation" ? "" : "()"} is not available on a read-only client \u2014 ${REASON_HINTS[reason]}`,
+    ...params.meta === undefined ? {} : { meta: params.meta }
+  });
+}
+var contexts = new WeakMap;
+var facades = new WeakMap;
+function bound(params) {
+  const { value, receiver } = params;
+  return typeof value === "function" ? value.bind(receiver) : undefined;
+}
+function classifiedMount(params) {
+  const { value, readOnly } = params;
+  if (readOnly === undefined)
+    return;
+  if (readOnly === true)
+    return typeof value === "function" ? (...args) => {
+      if (containsSqlFragment(args))
+        return Promise.reject(readOnlyRefusal({ path: "extension", reason: "raw" }));
+      return value(...restrictedSqlArgs({ value: args, path: "$readOnly extension" }));
+    } : undefined;
+  if (typeof value !== "object" || value === null)
+    return;
+  const source = value;
+  const namespace = {};
+  for (const member of readOnly) {
+    const fn = bound({ value: source[member], receiver: namespace });
+    if (fn !== undefined)
+      namespace[member] = (...args) => {
+        if (containsSqlFragment(args))
+          return Promise.reject(readOnlyRefusal({ path: member, reason: "raw" }));
+        return fn(...restrictedSqlArgs({ value: args, path: "$readOnly extension" }));
+      };
+  }
+  return Object.freeze(namespace);
+}
+function readOnlyDelegate(params) {
+  const { model, mounts } = params;
+  const base = params.base;
+  const delegate = {};
+  for (const method of READ_DELEGATE_METHODS) {
+    const fn = bound({ value: base[method], receiver: base });
+    if (fn !== undefined)
+      delegate[method] = (...args) => {
+        if (containsSqlFragment(args))
+          return Promise.reject(readOnlyRefusal({ path: `${model.clientName}.${method}`, reason: "raw" }));
+        const operation = fn(...args);
+        params.operations.restrictSql?.({ value: operation });
+        return operation;
+      };
+  }
+  for (const method of WRITE_DELEGATE_METHODS) {
+    const refusal = () => Promise.reject(readOnlyRefusal({
+      path: `${model.clientName}.${method}`,
+      reason: "write",
+      meta: { model: model.name, method }
+    }));
+    delegate[method] = refusal;
+  }
+  for (const mount of mounts) {
+    if (mount.scope !== "model" || mount.model !== model.name)
+      continue;
+    const classified = classifiedMount({ value: base[mount.property], readOnly: mount.readOnly });
+    delegate[mount.property] = classified ?? (() => Promise.reject(readOnlyRefusal({
+      path: `${model.clientName}.${mount.property}`,
+      reason: "unclassified",
+      meta: { model: model.name, method: mount.property, extension: mount.extension }
+    })));
+  }
+  return Object.freeze(delegate);
+}
+function refuseBatch(params) {
+  for (const operation of params.operations) {
+    params.bridge.refuse({ value: operation, reason: params.reason });
+  }
+  return Promise.reject(params.reason);
+}
+function buildReadOnly(params) {
+  const { client, context } = params;
+  const { meta, mounts, operations } = context;
+  const models = {};
+  const facade = {};
+  for (const model of meta.models) {
+    const base = client.$models[model.name];
+    if (base === undefined)
+      continue;
+    const delegate = readOnlyDelegate({ base, model, mounts, operations });
+    models[model.name] = delegate;
+    models[model.clientName] = delegate;
+  }
+  facade.$models = Object.freeze(models);
+  for (const model of meta.models) {
+    const delegate = models[model.clientName];
+    if (delegate !== undefined) {
+      Object.defineProperty(facade, model.clientName, { value: delegate, enumerable: true });
+    }
+  }
+  facade.$on = client.$on.bind(client);
+  facade.$transaction = (arg, options) => {
+    if (typeof arg === "function") {
+      const run = arg;
+      return client.$transaction((tx) => run(readOnlyOver({ client: tx, context })), options);
+    }
+    if (Array.isArray(arg)) {
+      for (const operation of arg) {
+        const method = operations.methodOf({ value: operation });
+        if (method === undefined)
+          continue;
+        if (delegateMethodAccess({ method }) === "read") {
+          operations.restrictSql?.({ value: operation });
+          continue;
+        }
+        return refuseBatch({
+          operations: arg,
+          reason: readOnlyRefusal({
+            path: `$transaction([\u2026 ${method}() \u2026])`,
+            reason: "foreign_operation",
+            meta: { method }
+          }),
+          bridge: operations
+        });
+      }
+      return client.$transaction(arg, options);
+    }
+    return client.$transaction(arg, options);
+  };
+  attachDefineView({ client: facade, meta, models });
+  const derive = (member) => {
+    const source = client[member];
+    if (source === undefined)
+      return;
+    facade[member] = (arg) => {
+      const derived = source.call(client, arg);
+      return readOnlyOver({ client: derived, context });
+    };
+  };
+  derive("$scoped");
+  derive("$withPolicy");
+  derive("$bypassPolicy");
+  facade.$readOnly = () => facade;
+  for (const [member, access] of Object.entries(CLIENT_MEMBER_ACCESS)) {
+    if (access !== "raw" && access !== "control")
+      continue;
+    const reason = access === "raw" ? "raw" : "control";
+    facade[member] = member === "$withContext" ? () => {
+      throw readOnlyRefusal({ path: member, reason, meta: { method: member } });
+    } : () => Promise.reject(readOnlyRefusal({ path: member, reason, meta: { method: member } }));
+  }
+  for (const mount of mounts) {
+    if (mount.scope !== "client")
+      continue;
+    const classified = classifiedMount({ value: client[mount.property], readOnly: mount.readOnly });
+    facade[mount.property] = classified ?? (() => Promise.reject(readOnlyRefusal({
+      path: mount.property,
+      reason: "unclassified",
+      meta: { method: mount.property, extension: mount.extension }
+    })));
+  }
+  return Object.freeze(facade);
+}
+function readOnlyOver(params) {
+  const existing = facades.get(params.client);
+  if (existing !== undefined)
+    return existing;
+  const built = buildReadOnly(params);
+  facades.set(params.client, built);
+  return built;
+}
+function attachReadOnly(params) {
+  const context = {
+    meta: params.meta,
+    mounts: params.mounts ?? [],
+    operations: params.operations
+  };
+  contexts.set(params.client, context);
+  Object.defineProperty(params.client, "$readOnly", {
+    value: () => readOnlyOver({ client: params.client, context }),
+    enumerable: true,
+    configurable: true
+  });
+}
+function inheritReadOnly(params) {
+  const context = contexts.get(params.from);
+  if (context === undefined)
+    return;
+  contexts.set(params.to, context);
+  Object.defineProperty(params.to, "$readOnly", {
+    value: () => readOnlyOver({ client: params.to, context }),
+    enumerable: true,
+    configurable: true
+  });
+}
+
+// packages/runtime/src/policy.ts
 function policyError(message, meta) {
-  return new VibeError18({ code: "VIBE_VALIDATION", message, meta: meta ?? {} });
+  return new VibeError21({ code: "VIBE_VALIDATION", message, meta: meta ?? {} });
 }
 function policiedModels(meta) {
   return meta.models.filter((model) => model.policy !== undefined);
@@ -8364,13 +8940,15 @@ function scopeSelection(params) {
   return out;
 }
 function scopeArgs(params) {
-  const { meta, model, args, context } = params;
+  const { meta, model, context } = params;
+  const args = restrictedSqlArgs({ value: params.args, path: "$withPolicy" });
   const scoped = scopeSelection({ meta, model, args, context });
   return scoped.where === undefined ? scoped : { ...scoped, where: scopeWhere({ meta, model, where: scoped.where, context }) };
 }
 var REFERENCE_VERBS = ["connect", "connectOrCreate", "set", "disconnect", "update", "updateMany", "delete", "deleteMany", "upsert"];
 function forceWriteData(params) {
-  const { meta, model, data, context, phase } = params;
+  const { meta, model, context, phase } = params;
+  const data = restrictedSqlArgs({ value: params.data, path: "$withPolicy" });
   let out = { ...data };
   if (model.policy !== undefined) {
     const value = predicateFor({ model, context })[model.policy.field];
@@ -8499,7 +9077,7 @@ function scopedDelegate(params) {
     const pkWhere = pk.length === 1 ? { [pk[0]]: target[pk[0]] } : { [pkClientKey()]: Object.fromEntries(pk.map((name) => [name, target[name]])) };
     return write(raw, pkWhere);
   };
-  const notFound2 = (method) => new VibeError18({ code: "VIBE_NOT_FOUND", message: `${method} on ${model.name}: no row matches the unique where inside the bound policy context`, meta: { model: model.name, method } });
+  const notFound2 = (method) => new VibeError21({ code: "VIBE_NOT_FOUND", message: `${method} on ${model.name}: no row matches the unique where inside the bound policy context`, meta: { model: model.name, method } });
   return {
     findMany: (args) => base.findMany(scopeFind(args)),
     findFirst: (args) => base.findFirst(scopeFind(args)),
@@ -8533,7 +9111,7 @@ function scopedDelegate(params) {
       })
     })),
     upsertMany: () => {
-      throw new VibeError18({
+      throw new VibeError21({
         code: "VIBE_UNSUPPORTED_CAPABILITY",
         message: "upsertMany is not available on a policy-bound client: its conflict target is not policy-checked yet",
         meta: { model: model.name }
@@ -8542,7 +9120,7 @@ function scopedDelegate(params) {
     updateManyAndReturn: (args) => deferred(() => {
       const run = base.updateManyAndReturn;
       if (run === undefined) {
-        throw new VibeError18({
+        throw new VibeError21({
           code: "VIBE_UNSUPPORTED_CAPABILITY",
           message: "updateManyAndReturn is not available on this delegate",
           meta: { model: model.name }
@@ -8613,7 +9191,7 @@ function globalDelegate(params) {
     updateManyAndReturn: (args) => deferred(() => {
       const run = base.updateManyAndReturn;
       if (run === undefined) {
-        throw new VibeError18({
+        throw new VibeError21({
           code: "VIBE_UNSUPPORTED_CAPABILITY",
           message: "updateManyAndReturn is not available on this delegate"
         });
@@ -8624,7 +9202,7 @@ function globalDelegate(params) {
     upsertMany: (args) => deferred(() => {
       if (params.policyBound === false)
         return base.upsertMany(args);
-      throw new VibeError18({
+      throw new VibeError21({
         code: "VIBE_UNSUPPORTED_CAPABILITY",
         message: "upsertMany is not available on a policy-bound client: its conflict target is not policy-checked yet"
       });
@@ -8722,6 +9300,7 @@ function attachPolicy(params) {
     }
     Object.defineProperty(scoped, "$models", { value: scopedModels, enumerable: true });
     attachDefineView({ client: scoped, meta, models: scopedModels });
+    inheritReadOnly({ from: client, to: scoped });
     Object.defineProperty(scoped, "$transaction", {
       value: (arg, options) => typeof arg === "function" ? client.$transaction((tx) => arg(buildScopedOver(tx, context)), options) : client.$transaction(arg, options),
       enumerable: true
@@ -8753,6 +9332,7 @@ function attachPolicy(params) {
     }
     Object.defineProperty(inner, "$models", { value: scopedModels, enumerable: true });
     attachDefineView({ client: inner, meta, models: scopedModels });
+    inheritReadOnly({ from: tx, to: inner });
     Object.defineProperty(inner, "$transaction", {
       value: (arg, options) => typeof arg === "function" ? tx.$transaction((nested) => arg(buildScopedOver(nested, context)), options) : tx.$transaction(arg, options),
       enumerable: true,
@@ -8773,13 +9353,14 @@ function attachPolicy(params) {
       }
       Object.defineProperty(bypass, "$models", { value: models, enumerable: true });
       attachDefineView({ client: bypass, meta, models });
+      inheritReadOnly({ from: client, to: bypass });
       return bypass;
     },
     enumerable: true
   });
 }
 // packages/runtime/src/scoped.ts
-import { ScopedQueryError, VibeError as VibeError19 } from "@vibeorm/schema";
+import { ScopedQueryError, VibeError as VibeError22 } from "@vibeorm/schema";
 function refusal(params) {
   return new ScopedQueryError(params);
 }
@@ -9511,7 +10092,7 @@ function rewriteScopedCall(params) {
   const entry = entryOf(ctx, model);
   const scoped = entry.kind !== "none";
   const root = `${model.clientName}.${method}`;
-  const args = { ...params.args ?? {} };
+  const args = restrictedSqlArgs({ value: params.args ?? {}, path: "$scoped" });
   const ownPred = () => requirePred({ ctx, model, path: root });
   const walkOwnWhere = (where, path) => isPlainObject8(where) ? walkWhere({ ctx, model, where, path }) : where;
   if (FIND_LIKE.includes(method)) {
@@ -9689,7 +10270,7 @@ function forbidden(params) {
     message: `$scoped: ${params.method} is not available on a scoped handle \u2014 raw SQL cannot be tenant-verified; run it on the BASE client (the deliberate unscoped escape)`
   });
 }
-var RAW_METHODS = ["$queryRaw", "$executeRaw", "$queryRawUnsafe", "$executeRawUnsafe"];
+var RAW_METHODS = ["$querySql", "$executeSql", "$queryRaw", "$executeRaw", "$queryRawUnsafe", "$executeRawUnsafe"];
 function buildScopedOver(params) {
   const { ctx, client } = params;
   const scoped = Object.create(client);
@@ -9705,6 +10286,7 @@ function buildScopedOver(params) {
   }
   Object.defineProperty(scoped, "$models", { value: scopedModels, enumerable: true });
   attachDefineView({ client: scoped, meta: ctx.meta, models: scopedModels });
+  inheritReadOnly({ from: client, to: scoped });
   Object.defineProperty(scoped, "$transaction", {
     value: (arg, options) => typeof arg === "function" ? client.$transaction((tx) => arg(buildScopedOver({ ctx, client: tx })), options) : client.$transaction(arg, options),
     enumerable: true
@@ -9733,7 +10315,7 @@ function attachScoped(params) {
   Object.defineProperty(client, "$scoped", {
     value: (config) => {
       if (!isPlainObject8(config) || !isPlainObject8(config.models)) {
-        throw new VibeError19({
+        throw new VibeError22({
           code: "VIBE_VALIDATION",
           message: "$scoped takes { scope: string | number | bigint | null, models: { <Model>: \u2026 } }"
         });
@@ -9749,7 +10331,7 @@ function attachScoped(params) {
       }
       const scope = config.scope;
       if (scope !== null && typeof scope !== "string" && typeof scope !== "number" && typeof scope !== "bigint") {
-        throw new VibeError19({
+        throw new VibeError22({
           code: "VIBE_VALIDATION",
           message: `$scoped: scope must be a string, number, bigint or null \u2014 got ${typeof scope}`
         });
@@ -9765,7 +10347,7 @@ function attachScoped(params) {
   });
 }
 // packages/runtime/src/rls-readiness.ts
-import { VibeError as VibeError20, assertValidSchemaIR, unsupportedCapability as unsupportedCapability6 } from "@vibeorm/schema";
+import { VibeError as VibeError23, assertValidSchemaIR, unsupportedCapability as unsupportedCapability7 } from "@vibeorm/schema";
 import { NATIVE_RLS as NATIVE_RLS2, getSqlDialect as getSqlDialect4, renderRlsPolicy, renderRlsRole, NATIVE_RLS_PROBE_POLICY, renderRlsReadinessQuery, renderRlsProbeTable } from "@vibeorm/sql";
 import { RLS_READINESS_SQL, NATIVE_RLS_PROBE_POLICY as NATIVE_RLS_PROBE_POLICY2 } from "@vibeorm/sql";
 function textOf(params) {
@@ -9816,10 +10398,10 @@ function unprotectedTablesOf(params) {
 function requireNativeRls(params) {
   const dialect = getSqlDialect4({ dialect: params.adapter.dialect });
   if (!dialect.capabilities.nativeRowLevelSecurity) {
-    throw unsupportedCapability6({ dialect: dialect.name, feature: "nativeRowLevelSecurity" });
+    throw unsupportedCapability7({ dialect: dialect.name, feature: "nativeRowLevelSecurity" });
   }
   if (params.schema.rls === undefined) {
-    throw new VibeError20({
+    throw new VibeError23({
       code: "VIBE_CONFIG",
       message: "Native row-level security readiness requires a schema that declares native RLS"
     });
@@ -10231,7 +10813,7 @@ async function inspectNativeRls(params) {
 function requireEmbeddedRole(params) {
   const { role } = params;
   if (typeof role !== "string" || role.length === 0 || role.includes("\x00")) {
-    throw new VibeError20({
+    throw new VibeError23({
       code: "VIBE_CONFIG",
       message: "PGlite native row-level security requires a pre-existing restricted runtime role (nativeRls.runtimeRole) \u2014 its default embedded session is privileged and bypasses every policy",
       meta: { provider: "pglite" }
@@ -10243,7 +10825,7 @@ function assertNativeRlsReady(params) {
   const { report } = params;
   if (report.ready)
     return;
-  throw new VibeError20({
+  throw new VibeError23({
     code: "VIBE_CONFIG",
     message: `Native row-level security is not ready on this database: ${report.problems.map((problem) => `${problem.name} (${problem.status})`).join(", ")}`,
     meta: {
@@ -10268,11 +10850,13 @@ function formatNativeRlsReport(params) {
   return lines;
 }
 // packages/runtime/src/client.ts
-import { RlsContextError as RlsContextError2, VibeError as VibeError24, assertValidSchemaIR as assertValidSchemaIR2, unsupportedCapability as unsupportedCapability7 } from "@vibeorm/schema";
-import { ParamCollector, getSqlDialect as getSqlDialect5, renderRlsContext, renderRlsPolicy as renderRlsPolicy2, renderRlsRole as renderRlsRole2 } from "@vibeorm/sql";
+import { compileSql } from "@vibeorm/sql";
+import { RlsContextError as RlsContextError2, VibeError as VibeError27, assertValidSchemaIR as assertValidSchemaIR2, unsupportedCapability as unsupportedCapability8 } from "@vibeorm/schema";
+import { ADVISORY_LOCK_RESULT_COLUMN, ParamCollector, getSqlDialect as getSqlDialect5, renderRlsContext, renderRlsPolicy as renderRlsPolicy2, renderRlsRole as renderRlsRole2, renderStatement as renderStatement5 } from "@vibeorm/sql";
 
 // packages/runtime/src/render-cache.ts
 import {
+  isSqlFragment as isSqlFragment3,
   isDbNowMarker,
   isJsonParamCell,
   isListSetOperation,
@@ -10285,12 +10869,25 @@ var MAX_ENTRIES = 512;
 
 class StatementRenderCache {
   entries = new Map;
+  get size() {
+    return this.entries.size;
+  }
   get(key) {
-    return this.entries.get(key);
+    const slot = this.entries.get(key);
+    if (slot === undefined)
+      return;
+    this.entries.delete(key);
+    this.entries.set(key, slot);
+    return slot;
   }
   set(key, slot) {
-    if (this.entries.size >= MAX_ENTRIES && !this.entries.has(key))
-      this.entries.clear();
+    if (this.entries.has(key)) {
+      this.entries.delete(key);
+    } else if (this.entries.size >= MAX_ENTRIES) {
+      const oldest = this.entries.keys().next();
+      if (!oldest.done)
+        this.entries.delete(oldest.value);
+    }
     this.entries.set(key, slot);
   }
 }
@@ -10477,6 +11074,7 @@ function walkExpr(walk2, dialect, expr) {
       return true;
     case "jsonFilter":
       return false;
+    case "composed":
     case "fragment":
       return false;
     case "raw":
@@ -10601,8 +11199,9 @@ function walkSelect(walk2, dialect, statement) {
     walk2.key += `t${statement.limit}`;
   if (statement.offset !== undefined)
     walk2.key += `s${statement.offset}`;
-  if (statement.lockForUpdate === true)
-    walk2.key += "u";
+  if (statement.rowLock !== undefined) {
+    walk2.key += `u:${statement.rowLock.strength}/${statement.rowLock.wait}`;
+  }
   walk2.key += "}";
   return true;
 }
@@ -10651,6 +11250,8 @@ function walkInsert(walk2, dialect, statement) {
       }
       walk2.key += ")";
     } else {
+      if (Object.values(onConflict.update).some(isSqlFragment3))
+        return false;
       walk2.key += "U(";
       if (onConflict.constraint !== undefined) {
         walk2.key += "K";
@@ -10716,6 +11317,7 @@ function walkStatement(walk2, dialect, statement) {
     case "rlsPolicy":
     case "rlsContext":
     case "rlsRole":
+    case "advisoryLock":
       return false;
   }
 }
@@ -10760,11 +11362,11 @@ function renderStatementCached(params) {
 }
 
 // packages/runtime/src/strict-args.ts
-import { VibeError as VibeError21 } from "@vibeorm/schema";
+import { VibeError as VibeError24 } from "@vibeorm/schema";
 var SKIP = Symbol.for("vibeorm.skip");
 function explicitUndefined(params) {
   const { model, method, path } = params;
-  return new VibeError21({
+  return new VibeError24({
     code: "VIBE_VALIDATION",
     message: `${model}.${method}(): explicit undefined at ${path} \u2014 an undefined value is refused ` + `because it would silently drop the property (widening a filter or losing a write). ` + `Omit the property, or pass SKIP to omit it deliberately; ` + `VibeClient({ strictArguments: false }) restores the legacy behaviour.`,
     meta: { model, method, path }
@@ -10941,10 +11543,10 @@ function bindRlsContext(params) {
 }
 
 // packages/runtime/src/telemetry/recorder.ts
-import { VibeError as VibeError23 } from "@vibeorm/schema";
+import { VibeError as VibeError26 } from "@vibeorm/schema";
 
 // packages/runtime/src/telemetry/config.ts
-import { VibeError as VibeError22 } from "@vibeorm/schema";
+import { VibeError as VibeError25 } from "@vibeorm/schema";
 var TELEMETRY_DEFAULTS = Object.freeze({
   captureSql: false,
   captureParameterValues: false,
@@ -10959,7 +11561,7 @@ var TELEMETRY_DEFAULTS = Object.freeze({
   latencyBucketsMs: Object.freeze([1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000])
 });
 function configError(params) {
-  return new VibeError22({
+  return new VibeError25({
     code: "VIBE_CONFIG",
     message: `telemetry: ${params.message}`,
     ...params.meta === undefined ? {} : { meta: params.meta }
@@ -11047,7 +11649,7 @@ function deriveStage(params) {
   return "decode";
 }
 function errorCodeOf(error) {
-  return error instanceof VibeError23 ? error.code : undefined;
+  return error instanceof VibeError26 ? error.code : undefined;
 }
 function newHistogram(bounds) {
   return { counts: new Array(bounds.length + 1).fill(0), sum: 0, count: 0 };
@@ -11421,15 +12023,23 @@ async function instrumentStatement(params) {
 // packages/runtime/src/client.ts
 function notFound2(params) {
   const { model, method } = params;
-  return new VibeError24({
+  return new VibeError27({
     code: "VIBE_NOT_FOUND",
     message: `no ${model} record matched the where clause of ${method}()`,
     meta: { model, method }
   });
 }
+function transactionLifecycleRefusal(params) {
+  const { method } = params;
+  return new VibeError27({
+    code: "VIBE_VALIDATION",
+    message: `${method}() is not available on a transaction client \u2014 the connection is owned by the open transaction; call it on the client that started the transaction`,
+    meta: { method, inTransaction: true }
+  });
+}
 function viewIsReadOnly(params) {
   const { model, method } = params;
-  return new VibeError24({
+  return new VibeError27({
     code: "VIBE_VALIDATION",
     message: `${model} is a view \u2014 ${method}() is not available on views (they are read-only); write to the underlying table instead`,
     meta: { model, method }
@@ -11535,7 +12145,7 @@ async function engineTransaction(params) {
     const support = engine.adapter.budgets?.transactionDeadline;
     const requested = options.deadline.enforcement ?? "between-statements";
     if (support === undefined || support === "unsupported" || requested === "cancel-running-statements" && support !== "cancel-running-statements") {
-      throw new VibeError24({
+      throw new VibeError27({
         code: "VIBE_UNSUPPORTED_CAPABILITY",
         message: "the adapter does not declare support for the requested transaction deadline",
         meta: { provider: engine.adapter.provider, feature: "transactionDeadline", requested, supported: support ?? "undeclared" }
@@ -11634,105 +12244,141 @@ function settleWith(params) {
     scope.settle({ outcome: "failure", error });
   });
 }
+var createQueryPromise;
+var queryPromiseMethod;
+var queryPromiseOwnerError;
+var refuseQueryPromise;
+var claimQueryPromise;
+var restrictQueryPromise;
+var queryPromises = new WeakSet;
+function isQueryPromise(value) {
+  return typeof value === "object" && value !== null && queryPromises.has(value);
+}
 
 class QueryPromise extends Promise {
   static get [Symbol.species]() {
     return Promise;
   }
-  target;
-  dispatch;
-  settle;
-  started = false;
-  scope;
-  static create(params) {
+  #target;
+  #operationMethod;
+  #dispatch;
+  #settle;
+  #started = false;
+  #scope;
+  static {
+    createQueryPromise = QueryPromise.#create;
+    queryPromiseMethod = ({ value }) => value.#operationMethod;
+    queryPromiseOwnerError = ({ value, engine }) => value.#ownerError({ engine });
+    refuseQueryPromise = ({ value, reason }) => value.#refuse({ reason });
+    claimQueryPromise = ({ value }) => value.#claim();
+    restrictQueryPromise = ({ value }) => {
+      value.#target = { ...value.#target, readOnlySql: true };
+    };
+  }
+  static #create(params) {
     let resolve;
     let reject;
     const instance = new QueryPromise((res, rej) => {
       resolve = res;
       reject = rej;
     });
-    instance.target = params.engine;
-    instance.dispatch = params.run;
-    instance.settle = { resolve, reject };
-    instance.scope = beginOperation({
+    queryPromises.add(instance);
+    instance.#target = params.engine;
+    instance.#operationMethod = params.method ?? "unknown";
+    instance.#dispatch = params.run;
+    instance.#settle = { resolve, reject };
+    instance.#scope = beginOperation({
       engine: params.engine,
       kind: params.kind ?? "model",
       model: params.model ?? null,
       method: params.method ?? "unknown"
     });
     queueMicrotask(() => {
-      instance.start();
+      instance.#start();
     });
     return instance;
   }
-  start() {
-    if (this.started)
+  #start() {
+    if (this.#started)
       return;
-    this.started = true;
-    const scope = this.scope;
+    this.#started = true;
+    const scope = this.#scope;
     scope?.dispatch();
-    const target = scope === undefined ? this.target : { ...this.target, operation: scope };
-    const running = target.rlsSchema === undefined && target.lifetime === undefined ? this.dispatch(target) : executeOperation({ engine: target, run: this.dispatch });
+    const target = scope === undefined ? this.#target : { ...this.#target, operation: scope };
+    const running = target.rlsSchema === undefined && target.lifetime === undefined ? this.#dispatch(target) : executeOperation({ engine: target, run: this.#dispatch });
     if (scope !== undefined)
       settleWith({ scope, running });
-    running.then(this.settle.resolve, this.settle.reject);
+    running.then(this.#settle.resolve, this.#settle.reject);
   }
   then(onfulfilled, onrejected) {
-    this.start();
+    this.#start();
     return super.then(onfulfilled, onrejected);
   }
-  ownerError(params) {
+  #ownerError(params) {
     const { engine } = params;
-    const state = engineStateError({ engine: this.target });
+    const state = engineStateError({ engine: this.#target });
     if (state !== undefined)
       return state;
-    if (engine.rlsSchema === undefined && this.target.rlsSchema === undefined)
+    if (engine.rlsSchema === undefined && this.#target.rlsSchema === undefined)
       return;
-    if (this.target.rootIdentity !== engine.rootIdentity || this.target.lifetime !== engine.lifetime || !sameRecord(this.target.context?.settings ?? {}, engine.context?.settings ?? {}))
+    if (this.#target.rootIdentity !== engine.rootIdentity || this.#target.lifetime !== engine.lifetime || !sameRecord(this.#target.context?.settings ?? {}, engine.context?.settings ?? {}))
       return new RlsContextError2({ reason: "conflicting" });
     return;
   }
-  refuse(params) {
-    if (this.started)
+  #refuse(params) {
+    if (this.#started)
       return;
-    this.started = true;
-    this.scope?.settle({ outcome: "failure", stage: "refused", error: params.reason });
-    this.settle.reject(params.reason);
+    this.#started = true;
+    this.#scope?.settle({ outcome: "failure", stage: "refused", error: params.reason });
+    this.#settle.reject(params.reason);
     super.then(undefined, () => {});
   }
-  claim() {
-    if (this.started) {
-      throw new VibeError24({
+  #claim() {
+    if (this.#started) {
+      throw new VibeError27({
         code: "VIBE_VALIDATION",
         message: "$transaction([...]) needs operations that have not dispatched \u2014 pass delegate calls in the same tick they are created (this one was awaited or created earlier and already executed outside the transaction)"
       });
     }
-    this.started = true;
-    const scope = this.scope;
+    this.#started = true;
+    const scope = this.#scope;
     return {
       start: (target) => {
+        if (this.#target.readOnlySql === true)
+          target = { ...target, readOnlySql: true };
         if (scope !== undefined && target.operation !== undefined) {
           scope.reparent({ parentOperationId: target.operation.id });
         }
         scope?.dispatch();
         const running = executeOperation({
           engine: scope === undefined ? target : { ...target, operation: scope },
-          run: this.dispatch
+          run: this.#dispatch
         });
         if (scope !== undefined)
           settleWith({ scope, running });
-        running.then(this.settle.resolve, this.settle.reject);
+        running.then(this.#settle.resolve, this.#settle.reject);
         super.then(undefined, () => {});
         return running;
       },
       abort: (reason) => {
         scope?.settle({ outcome: "failure", stage: "refused", error: reason });
-        this.settle.reject(reason);
+        this.#settle.reject(reason);
         super.then(undefined, () => {});
       }
     };
   }
 }
+var LAZY_OPERATIONS = {
+  restrictSql: ({ value }) => {
+    if (isQueryPromise(value))
+      restrictQueryPromise({ value });
+  },
+  methodOf: (params) => isQueryPromise(params.value) ? queryPromiseMethod({ value: params.value }) : undefined,
+  refuse: (params) => {
+    if (isQueryPromise(params.value))
+      refuseQueryPromise({ value: params.value, reason: params.reason });
+  }
+};
 async function runRows(params) {
   const { engine, plan } = params;
   const renderStarted = renderClock({ engine });
@@ -11759,9 +12405,9 @@ async function runRows(params) {
 }
 async function runBoundAffected(params) {
   const { adapter, text: text2, values } = params;
-  const bound = adapter.executeAffected;
-  if (bound !== undefined)
-    return await bound.call(adapter, { text: text2, values });
+  const bound2 = adapter.executeAffected;
+  if (bound2 !== undefined)
+    return await bound2.call(adapter, { text: text2, values });
   return await adapter.executeUnsafe({ text: text2, values });
 }
 async function runAffected(params) {
@@ -11800,14 +12446,26 @@ async function runAffected(params) {
   });
   return result.affectedRows;
 }
+var LOCKABLE_METHODS = Object.freeze(["findMany", "findFirst", "findUnique"]);
 function plan(params) {
   const { engine, model, method, args } = params;
-  if (args !== undefined && args["lock"] !== undefined && engine.inTransaction !== true) {
-    throw new VibeError24({
-      code: "VIBE_VALIDATION",
-      message: `lock on ${model}.${method}() requires a transaction \u2014 call it on the client $transaction hands its callback (outside one, the lock would release at statement end)`,
-      meta: { model, method }
-    });
+  if (engine.readOnlySql === true && containsSqlFragment(args))
+    throw readOnlyRefusal({ path: `${model}.${method}`, reason: "raw" });
+  if (args !== undefined && args["lock"] !== undefined) {
+    if (engine.inTransaction !== true) {
+      throw new VibeError27({
+        code: "VIBE_VALIDATION",
+        message: `lock on ${model}.${method}() requires a transaction \u2014 call it on the client $transaction hands its callback (outside one, the lock would release at statement end)`,
+        meta: { model, method }
+      });
+    }
+    if (!LOCKABLE_METHODS.includes(method)) {
+      throw new VibeError27({
+        code: "VIBE_VALIDATION",
+        message: `lock on ${model}.${method}() is not supported \u2014 only ${LOCKABLE_METHODS.join(", ")} take a lock. ` + `Lock the rows with a find inside the transaction, then write them`,
+        meta: { model, method }
+      });
+    }
   }
   return buildQuery({
     meta: engine.meta,
@@ -11822,6 +12480,19 @@ function plan(params) {
     }
   });
 }
+var OVERLAY_ROW_LOCK = Object.freeze({ strength: "update", wait: "wait" });
+function readAcquiredVerdict(params) {
+  const value = params.result.rows[0]?.[ADVISORY_LOCK_RESULT_COLUMN];
+  if (value === true || value === 1 || value === "t" || value === "true" || value === "1")
+    return true;
+  if (value === false || value === 0 || value === "f" || value === "false" || value === "0")
+    return false;
+  throw new VibeError27({
+    code: "VIBE_INTERNAL",
+    message: `internal: ${params.method}() expected a boolean "${ADVISORY_LOCK_RESULT_COLUMN}" column, got ${String(value)}`,
+    meta: { method: params.method, value: String(value) }
+  });
+}
 async function refetch(params) {
   const { engine, source, where } = params;
   const selectArg = source.selectArg;
@@ -11831,7 +12502,7 @@ async function refetch(params) {
     method: "findUnique",
     args: selectArg === null ? { where } : { where, select: selectArg }
   });
-  const locked = params.lock === true ? { ...followUp, statement: { ...followUp.statement, lockForUpdate: true } } : followUp;
+  const locked = params.lock === true ? { ...followUp, statement: { ...followUp.statement, rowLock: OVERLAY_ROW_LOCK } } : followUp;
   const rows = await runRows({ engine, plan: locked });
   return rows[0] ?? null;
 }
@@ -11858,7 +12529,7 @@ async function insertedKeyWhere(params) {
   const keyField = source.model.primaryKey[0];
   const lastInsertIdSql = engine.dialect.lastInsertIdSql;
   if (lastInsertIdSql === null || source.model.primaryKey.length !== 1 || keyField === undefined) {
-    throw unsupportedCapability7({
+    throw unsupportedCapability8({
       dialect: engine.dialect.name,
       feature: `${source.method} on ${source.model.name} without RETURNING`,
       hint: "this model's key is assigned by the database and cannot be read back on this dialect"
@@ -11876,7 +12547,7 @@ async function insertedKeyWhere(params) {
   });
   const id = result.rows[0]?.id;
   if (id === undefined || id === null) {
-    throw new VibeError24({
+    throw new VibeError27({
       code: "VIBE_INTERNAL",
       message: `could not read back the generated key for ${source.model.name}`,
       meta: { model: source.model.name }
@@ -12006,7 +12677,7 @@ async function runUpsertFallback(params) {
   const probeSource = plan({ engine, model: model.name, method: "findUnique", args: { where: args.where } });
   const probePlan = {
     ...probeSource,
-    statement: { ...probeSource.statement, lockForUpdate: true }
+    statement: { ...probeSource.statement, rowLock: OVERLAY_ROW_LOCK }
   };
   const createSource = plan({
     engine,
@@ -12034,6 +12705,8 @@ async function runUpsertFallback(params) {
 function relationExecutor(params) {
   const { engine } = params;
   return async ({ statement, model, method }) => {
+    if (engine.readOnlySql === true && containsSqlFragment(statement))
+      throw readOnlyRefusal({ path: `${model}.${method}`, reason: "raw" });
     const rendered = renderStatementCached({ dialect: engine.dialect, statement, cache: engine.renderCache });
     return await runStatement({
       engine,
@@ -12133,7 +12806,7 @@ function makeWriteContext(params) {
     transactional: (fn) => engine.adapter.transaction((txAdapter) => fn(makeRunner({ engine: { ...engine, adapter: txAdapter, inTransaction: true } })))
   };
 }
-function readOnlyDelegate(params) {
+function readOnlyDelegate2(params) {
   const { delegate, model } = params;
   const refuse2 = (method) => async () => {
     throw viewIsReadOnly({ model, method });
@@ -12193,7 +12866,7 @@ function createDelegate(params) {
     const skipping = args.onConflict !== undefined;
     if (hasNestedWrites({ model: modelMeta, data: args.data })) {
       if (skipping) {
-        throw new VibeError24({
+        throw new VibeError27({
           code: "VIBE_VALIDATION",
           message: `onConflict cannot combine with nested writes on ${modelMeta.name}.create() \u2014 insert the parent row alone, then connect relations`,
           meta: { model: modelMeta.name }
@@ -12294,7 +12967,7 @@ function createDelegate(params) {
   const upsert = async (target, args) => {
     const modelMeta = getModelMeta({ meta: target.meta, model });
     if (hasNestedWrites({ model: modelMeta, data: args.create }) || hasNestedWrites({ model: modelMeta, data: args.update })) {
-      throw new VibeError24({
+      throw new VibeError27({
         code: "VIBE_VALIDATION",
         message: `nested writes are not supported inside upsert arms on ${modelMeta.name} \u2014 use create()/update() with nested data`,
         meta: { model: modelMeta.name }
@@ -12302,7 +12975,7 @@ function createDelegate(params) {
     }
     if (!upsertUsesNativeStatement({ model: modelMeta, args })) {
       if (args.onConflict !== undefined) {
-        throw new VibeError24({
+        throw new VibeError27({
           code: "VIBE_VALIDATION",
           message: `onConflict on ${modelMeta.name}.upsert() needs the native single-statement path \u2014 this shape (a guard field beyond the conflict target, or create data not binding the where's key) runs the find-then-write fallback, which cannot honor an explicit conflict target`,
           meta: { model: modelMeta.name }
@@ -12397,7 +13070,7 @@ function createDelegate(params) {
       return assembleAggregates({ engine: target, model: built.model, spec, row, into: out });
     });
   };
-  const lazy = (method, run) => QueryPromise.create({ engine, run, model, method });
+  const lazy = (method, run) => createQueryPromise({ engine, run, model, method });
   const delegate = {
     findMany: (args) => lazy("findMany", (target) => findMany(target, args)),
     findFirst: (args) => lazy("findFirst", (target) => findFirst(target, args)),
@@ -12429,7 +13102,7 @@ function createDelegate(params) {
     groupBy: (args) => lazy("groupBy", (target) => groupBy(target, args))
   };
   const meta = getModelMeta({ meta: engine.meta, model });
-  return meta.isView ? readOnlyDelegate({ delegate, model: meta.name }) : delegate;
+  return meta.isView ? readOnlyDelegate2({ delegate, model: meta.name }) : delegate;
 }
 var WRITE_METHODS = [
   "create",
@@ -12495,13 +13168,13 @@ function buildClient(params) {
     models[model.name] = delegate;
     models[model.clientName] = delegate;
   }
-  const runRaw = async (method, statement) => {
+  const runRaw = async (method, statement, decodeRows2) => {
     const scope = beginOperation({ engine, kind: "raw", model: null, method });
     scope?.dispatch();
     const running = executeOperation({
       engine: scope === undefined ? engine : { ...engine, operation: scope },
       run: async (target) => {
-        return await runStatement({
+        const result = await runStatement({
           engine: target,
           kind: "raw",
           model: null,
@@ -12511,6 +13184,8 @@ function buildClient(params) {
           rowCount: (value) => method.startsWith("$query") ? value.rows.length : value.affectedRows,
           run: () => statement.values.length > 0 ? runBoundAffected({ adapter: target.adapter, text: statement.text, values: statement.values }) : target.adapter.executeUnsafe(statement)
         });
+        decodeRows2?.(result.rows);
+        return result;
       }
     });
     if (scope === undefined)
@@ -12525,33 +13200,67 @@ function buildClient(params) {
     });
     return await running;
   };
+  const runAdvisoryLock = async (params2) => {
+    const { method, options } = params2;
+    assertEngineActive({ engine });
+    const statement = compileAdvisoryLock({
+      dialect: engine.dialect,
+      method,
+      inTransaction: engine.inTransaction === true,
+      options
+    });
+    const rendered = renderStatement5({ dialect: engine.dialect, statement });
+    const scope = beginOperation({ engine, kind: "raw", model: null, method });
+    scope?.dispatch();
+    const target = scope === undefined ? engine : { ...engine, operation: scope };
+    const running = runStatement({
+      engine: target,
+      kind: "raw",
+      model: null,
+      method,
+      text: rendered.text,
+      values: rendered.values,
+      rowCount: (value) => value.rows.length,
+      run: () => runBoundAffected({
+        adapter: target.adapter,
+        text: rendered.text,
+        values: bindValues({ adapter: target.adapter, values: rendered.values })
+      })
+    });
+    if (scope !== undefined)
+      settleWith({ scope, running });
+    const result = await running;
+    if (statement.wait === "wait")
+      return true;
+    return readAcquiredVerdict({ method, result });
+  };
   const runOperations = (operations, options) => {
     const scope = beginOperation({ engine, kind: "transaction", model: null, method: "$transaction" });
     const claimed = [];
     let claimError = null;
     let identityError = engineStateError({ engine });
     for (const operation of operations) {
-      if (identityError === undefined && operation instanceof QueryPromise)
-        identityError = operation.ownerError({ engine });
+      if (identityError === undefined && isQueryPromise(operation))
+        identityError = queryPromiseOwnerError({ value: operation, engine });
     }
     if (identityError !== undefined) {
       for (const operation of operations) {
-        if (operation instanceof QueryPromise)
-          operation.refuse({ reason: identityError });
+        if (isQueryPromise(operation))
+          refuseQueryPromise({ value: operation, reason: identityError });
       }
       scope?.settle({ outcome: "failure", stage: "refused", error: identityError });
       return Promise.reject(identityError);
     }
     for (const operation of operations) {
-      if (!(operation instanceof QueryPromise)) {
-        claimError = new VibeError24({
+      if (!isQueryPromise(operation)) {
+        claimError = new VibeError27({
           code: "VIBE_VALIDATION",
           message: "$transaction([...]) takes query promises from model delegate calls \u2014 a foreign promise is already running and cannot join the transaction"
         });
         break;
       }
       try {
-        claimed.push(operation.claim());
+        claimed.push(claimQueryPromise({ value: operation }));
       } catch (error) {
         claimError = error;
         break;
@@ -12561,8 +13270,8 @@ function buildClient(params) {
       for (const entry of claimed)
         entry.abort(claimError);
       for (const operation of operations) {
-        if (operation instanceof QueryPromise)
-          operation.refuse({ reason: claimError });
+        if (isQueryPromise(operation))
+          refuseQueryPromise({ value: operation, reason: claimError });
       }
       scope?.settle({ outcome: "failure", stage: "refused", error: claimError });
       return Promise.reject(claimError);
@@ -12609,7 +13318,7 @@ function buildClient(params) {
     $models: models,
     $on: (event, listener) => {
       if (event !== "query") {
-        throw new VibeError24({
+        throw new VibeError27({
           code: "VIBE_VALIDATION",
           message: `unknown client event "${String(event)}" \u2014 supported: "query"`,
           meta: { event }
@@ -12621,15 +13330,34 @@ function buildClient(params) {
       };
     },
     $transaction: (fnOrOperations, options) => Array.isArray(fnOrOperations) ? runOperations(fnOrOperations, options) : runCallbackTransaction(fnOrOperations, options),
+    $querySql: async ({ query, decoder }) => {
+      assertEngineActive({ engine });
+      if (decoder === null || typeof decoder !== "object" || typeof decoder.decode !== "function")
+        throw new VibeError27({ code: "VIBE_VALIDATION", message: "$querySql requires an explicit result decoder" });
+      const statement = compileSql({ dialect: engine.dialect, query });
+      let output = [];
+      await runRaw("$querySql", statement, (rows) => {
+        output = rows.map((value) => decoder.decode({ value, dialect: engine.dialect.name, ...engine.adapter.wire === undefined ? {} : { wire: engine.adapter.wire } }));
+      });
+      return output;
+    },
+    $executeSql: async ({ query }) => {
+      assertEngineActive({ engine });
+      return (await runRaw("$executeSql", compileSql({ dialect: engine.dialect, query }))).affectedRows;
+    },
     $queryRaw: async (strings, ...values) => (await runRaw("$queryRaw", buildRawStatement({ dialect: engine.dialect, strings, values }))).rows,
     $executeRaw: async (strings, ...values) => (await runRaw("$executeRaw", buildRawStatement({ dialect: engine.dialect, strings, values }))).affectedRows,
     $queryRawUnsafe: async (text2, ...values) => (await runRaw("$queryRawUnsafe", { text: text2, values })).rows,
     $executeRawUnsafe: async (text2, ...values) => (await runRaw("$executeRawUnsafe", { text: text2, values })).affectedRows,
+    $advisoryLock: async (options) => {
+      await runAdvisoryLock({ method: "$advisoryLock", options });
+    },
+    $tryAdvisoryLock: (options) => runAdvisoryLock({ method: "$tryAdvisoryLock", options }),
     $connect: async () => {
       assertEngineActive({ engine, requireContext: false });
+      if (engine.inTransaction === true)
+        throw transactionLifecycleRefusal({ method: "$connect" });
       if (engine.rlsSchema !== undefined) {
-        if (engine.inTransaction)
-          throw new RlsContextError2({ reason: "conflicting" });
         await engine.adapter.connect();
         await engineTransaction({ engine, requireContext: false, run: async (target) => {
           for (const hook of engine.connectHooks ?? []) {
@@ -12647,8 +13375,8 @@ function buildClient(params) {
     },
     $disconnect: async () => {
       assertEngineActive({ engine, requireContext: false });
-      if (engine.rlsSchema !== undefined && engine.inTransaction)
-        throw new RlsContextError2({ reason: "conflicting" });
+      if (engine.inTransaction === true)
+        throw transactionLifecycleRefusal({ method: "$disconnect" });
       await engine.adapter.disconnect();
       await engine.telemetry?.flush();
     }
@@ -12665,7 +13393,7 @@ function buildClient(params) {
   if (engine.rlsSchema === undefined)
     attachScoped({ client, meta: engine.meta, ...wrapDelegate === undefined ? {} : { wrapDelegate } });
   if (engine.rlsSchema === undefined) {
-    registerPolicyOperations({ client, factory: (run) => QueryPromise.create({
+    registerPolicyOperations({ client, factory: (run) => createQueryPromise({
       engine,
       model: null,
       method: "$policyOperation",
@@ -12673,9 +13401,15 @@ function buildClient(params) {
       run: (target) => engineTransaction({ engine: target, run: (transactionEngine) => run(buildClient({ engine: transactionEngine })) })
     }) });
     attachPolicy({ client, meta: engine.meta, ...wrapDelegate === undefined ? {} : { wrapDelegate } });
+    attachReadOnly({
+      client,
+      meta: engine.meta,
+      ...engine.extensionMounts === undefined ? {} : { mounts: engine.extensionMounts },
+      operations: LAZY_OPERATIONS
+    });
   } else {
     const refuseLegacy = () => {
-      throw new VibeError24({ code: "VIBE_CONFIG", message: "Native row-level security cannot be combined with application policy or tenant scoping" });
+      throw new VibeError27({ code: "VIBE_CONFIG", message: "Native row-level security cannot be combined with application policy or tenant scoping" });
     };
     Object.defineProperties(client, {
       $withContext: { enumerable: true, value: (context) => {
@@ -12688,6 +13422,14 @@ function buildClient(params) {
       $withPolicy: { value: refuseLegacy },
       $bypassPolicy: { value: refuseLegacy }
     });
+    if (engine.context !== undefined) {
+      attachReadOnly({
+        client,
+        meta: engine.meta,
+        ...engine.extensionMounts === undefined ? {} : { mounts: engine.extensionMounts },
+        operations: LAZY_OPERATIONS
+      });
+    }
     for (const delegate of Object.values(models))
       Object.freeze(delegate);
     Object.freeze(models);
@@ -12737,7 +13479,7 @@ function makeMountContext(params) {
     compileWhere: ({ where, model: modelName, qualify }) => {
       const target = modelName === undefined ? model : getModelMeta({ meta: engine.meta, model: modelName });
       if (target === null) {
-        throw new VibeError24({
+        throw new VibeError27({
           code: "VIBE_INTERNAL",
           message: `extension "${extension}" compiled a where with no model in scope`,
           meta: { extension }
@@ -12760,30 +13502,30 @@ function createMountSurface(params) {
     return original;
   const wrap = (value, path) => {
     if (typeof value === "function") {
-      return (...args) => QueryPromise.create({ engine, run: async (target) => {
+      return (...args) => createQueryPromise({ engine, run: async (target) => {
         let current = mount.create(makeMountContext({ engine: target, extension: mount.extension, model }));
         let receiver = undefined;
         for (const key of path) {
           receiver = current;
           if (current === null || typeof current !== "object" && typeof current !== "function")
-            throw new VibeError24({ code: "VIBE_CONFIG", message: "Extension mount changed its method shape" });
+            throw new VibeError27({ code: "VIBE_CONFIG", message: "Extension mount changed its method shape" });
           current = Reflect.get(current, key);
         }
         if (typeof current !== "function")
-          throw new VibeError24({ code: "VIBE_CONFIG", message: "Extension mount changed its method shape" });
+          throw new VibeError27({ code: "VIBE_CONFIG", message: "Extension mount changed its method shape" });
         return Reflect.apply(current, receiver, args);
       } });
     }
     if (value === null || typeof value !== "object")
       return value;
     if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
-      throw new VibeError24({ code: "VIBE_CONFIG", message: "Native RLS extension mounts must expose plain objects and methods" });
+      throw new VibeError27({ code: "VIBE_CONFIG", message: "Native RLS extension mounts must expose plain objects and methods" });
     }
     const result = {};
     for (const key of Reflect.ownKeys(value)) {
       const descriptor = Object.getOwnPropertyDescriptor(value, key);
       if (!("value" in descriptor))
-        throw new VibeError24({ code: "VIBE_CONFIG", message: "Native RLS extension mount accessors are unsupported" });
+        throw new VibeError27({ code: "VIBE_CONFIG", message: "Native RLS extension mount accessors are unsupported" });
       Object.defineProperty(result, key, { value: wrap(descriptor.value, [...path, key]), enumerable: descriptor.enumerable });
     }
     return Object.freeze(result);
@@ -12800,7 +13542,7 @@ function attachExtensionMounts(params) {
       const model = getModelMeta({ meta: engine.meta, model: mount.model ?? "" });
       const delegate = models[model.name];
       if (delegate === undefined || mount.property in delegate) {
-        throw new VibeError24({
+        throw new VibeError27({
           code: "VIBE_CONFIG",
           message: `extension "${mount.extension}" cannot mount "${mount.property}" on ${model.name} \u2014 the name is taken`,
           meta: { extension: mount.extension, model: model.name, property: mount.property }
@@ -12811,7 +13553,7 @@ function attachExtensionMounts(params) {
       continue;
     }
     if (!mount.property.startsWith("$") || mount.property in client) {
-      throw new VibeError24({
+      throw new VibeError27({
         code: "VIBE_CONFIG",
         message: `extension "${mount.extension}" cannot mount client property "${mount.property}" \u2014 root mounts are $-prefixed and must not collide`,
         meta: { extension: mount.extension, property: mount.property }
@@ -12828,7 +13570,7 @@ function createClient(params) {
   if (schema.rls !== undefined) {
     const dialect = getSqlDialect5({ dialect: dialectName });
     if (!dialect.capabilities.nativeRowLevelSecurity)
-      throw unsupportedCapability7({ dialect: dialectName, feature: "nativeRowLevelSecurity" });
+      throw unsupportedCapability8({ dialect: dialectName, feature: "nativeRowLevelSecurity" });
     assertValidSchemaIR2({ schema });
     for (const model of schema.models) {
       if (model.rls !== "unprotected")
@@ -12837,9 +13579,9 @@ function createClient(params) {
     const role = options?.nativeRls?.runtimeRole;
     if (adapter.provider === "pglite") {
       if (typeof role !== "string" || role.length === 0 || role.includes("\x00"))
-        throw new VibeError24({ code: "VIBE_CONFIG", message: "PGlite native row-level security requires a pre-existing restricted runtimeRole; embedded binding is not a boundary against the host process" });
+        throw new VibeError27({ code: "VIBE_CONFIG", message: "PGlite native row-level security requires a pre-existing restricted runtimeRole; embedded binding is not a boundary against the host process" });
     } else if (role !== undefined) {
-      throw new VibeError24({ code: "VIBE_CONFIG", message: "Server native row-level security must use the runtime login role, not a runtimeRole switch" });
+      throw new VibeError27({ code: "VIBE_CONFIG", message: "Server native row-level security must use the runtime login role, not a runtimeRole switch" });
     }
   }
   if (extensions?.manifest !== undefined) {
@@ -12849,7 +13591,7 @@ function createClient(params) {
     assertComputedManifest({ manifest: computed.manifest, specs: computed.specs });
   }
   if (computed === undefined && options !== undefined && options["computed"] !== undefined) {
-    throw new VibeError24({
+    throw new VibeError27({
       code: "VIBE_CONFIG",
       message: "this client was generated without computed fields \u2014 declare them in vibeorm.config.ts and re-run vibeorm generate",
       meta: {}
@@ -12880,9 +13622,9 @@ function createClient(params) {
   });
 }
 // packages/runtime/src/keyset-iterator.ts
-import { VibeError as VibeError25 } from "@vibeorm/schema";
+import { VibeError as VibeError28 } from "@vibeorm/schema";
 function validation(params) {
-  return new VibeError25({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta });
+  return new VibeError28({ code: "VIBE_VALIDATION", message: params.message, meta: params.meta });
 }
 function projectionFor(params) {
   const { plan: plan2, select, omit } = params;
@@ -12959,7 +13701,7 @@ function iterateKeyset(options) {
       });
       if (advanced === false) {
         stop();
-        throw new VibeError25({
+        throw new VibeError28({
           code: "VIBE_DATA_INVALID",
           message: `keyset traversal of "${options.model}" is not advancing: the engine returned a row that does not sort after the previous position. ` + "The ordering is not total, or a cursor value lost precision \u2014 a DateTime column finer than milliseconds asserted as millisecond-exact does this.",
           meta: { model: options.model, order: plan2.signature, reason: "keyset-position-not-advancing" }
@@ -13032,7 +13774,7 @@ function iterateKeyset(options) {
   return iterator;
 }
 // packages/runtime/src/telemetry/collector.ts
-import { VibeError as VibeError26 } from "@vibeorm/schema";
+import { VibeError as VibeError29 } from "@vibeorm/schema";
 function createTelemetryCollector(params) {
   const throwOn = new Set(params?.throwOn ?? []);
   const operations = [];
@@ -13042,7 +13784,7 @@ function createTelemetryCollector(params) {
   let shutdowns = 0;
   const hostile = (phase) => {
     if (throwOn.has(phase)) {
-      throw new VibeError26({
+      throw new VibeError29({
         code: "VIBE_INTERNAL",
         message: `telemetry collector: deliberate ${phase} failure`,
         meta: { reason: "telemetry-collector-deliberate-failure", phase }
@@ -13098,7 +13840,7 @@ function createTelemetryCollector(params) {
     operationFor: (lookup) => {
       const matches = operations.filter((event) => event.method === lookup.method && (lookup.model === undefined || event.model === lookup.model));
       if (matches.length > 1) {
-        throw new VibeError26({
+        throw new VibeError29({
           code: "VIBE_VALIDATION",
           message: `telemetry collector: ${matches.length} operations match ${lookup.model ?? "*"}.${lookup.method}`,
           meta: {
@@ -13118,6 +13860,8 @@ export {
   updateWithNested,
   toSqlExecutor,
   toClientName,
+  sqlProjection,
+  sql2 as sql,
   rewriteScopedCall,
   resolveTelemetryConfig,
   resolveScopedModels,
@@ -13126,6 +13870,7 @@ export {
   resolveRelationLink,
   recommendFromPlan,
   readWorkloadStatistics,
+  readOnlyRefusal,
   queryFingerprint,
   previewOperation,
   parsePostgresPlan,
@@ -13138,6 +13883,7 @@ export {
   isDbNow,
   inspectNativeRlsTransaction,
   inspectNativeRls,
+  inheritReadOnly,
   hasNestedWrites,
   getModelMeta,
   getFieldMeta,
@@ -13152,17 +13898,20 @@ export {
   explainOperation,
   encodeValue,
   encodeKeysetToken,
+  delegateMethodAccess,
   decodeValue,
   decodeRows,
   decodeRow,
   decodeKeysetToken,
   decodeIsNoop2 as decodeIsNoop,
   decodeAggregateValue,
+  decode2 as decode,
   dbNow,
   createWithNested,
   createView,
   createTelemetryRecorder,
   createTelemetryCollector,
+  createSqlModel,
   createScopeRewriter,
   createClient,
   compileWhere,
@@ -13170,6 +13919,8 @@ export {
   compileOrderBy,
   compileKeysetOrderPlan,
   compileKeysetOrderInputs,
+  compileAdvisoryLock,
+  clientMemberAccess,
   checkStrictArguments,
   buildRuntimeMeta,
   buildQuery,
@@ -13177,6 +13928,7 @@ export {
   buildConnectHooks,
   attachScoped,
   attachRelations,
+  attachReadOnly,
   attachPolicy,
   attachLateralRelations,
   attachDefineView,
@@ -13187,10 +13939,12 @@ export {
   applyComputedFields,
   analyzeOperationTelemetry,
   affectedRowsAreRowCounts,
+  WRITE_DELEGATE_METHODS,
   ViewResult,
   TELEMETRY_DEFAULTS,
   SQLITE_CODECS,
   SKIP,
+  READ_DELEGATE_METHODS,
   POSTGRES_CODECS,
   PLAN_DEFAULTS,
   MYSQL_CODECS,
@@ -13199,7 +13953,9 @@ export {
   KEYSET_MAX_PAGE_SIZE,
   DIALECT_CODECS2 as DIALECT_CODECS,
   DIAGNOSTIC_THRESHOLDS,
-  COUNT_ALIAS
+  DELEGATE_METHOD_ACCESS,
+  COUNT_ALIAS,
+  CLIENT_MEMBER_ACCESS
 };
 
-//# debugId=1CBBB74E5D888E3564756E2164756E21
+//# debugId=89575B8D7F621EF764756E2164756E21