@vibeorm/generator 2.0.2 → 2.1.1

package/dist/index.js

@@ -5,7 +5,7 @@ import { join } from "path";
 import { buildComputedManifest, validateComputedConfig } from "@vibeorm/schema";
 
 // packages/generator/src/emit-dts.ts
-import { VibeError as VibeError3 } from "@vibeorm/schema";
+import { DIALECT_CAPABILITIES, VibeError as VibeError3, providerToDialect as providerToDialect2 } from "@vibeorm/schema";
 
 // packages/generator/src/emit-js.ts
 import { internalError } from "@vibeorm/schema";
@@ -24,8 +24,10 @@ var EMPTY_BAKED_EXTENSIONS = {
   manifest: [],
   dtsImports: [],
   delegateDts: new Map,
+  readOnlyDelegateDts: new Map,
   moduleDts: [],
   clientDts: [],
+  readOnlyClientDts: [],
   empty: true
 };
 
@@ -46,6 +48,37 @@ class ImportCollector {
 function indent(lines) {
   return lines.map((line) => line.length === 0 ? line : `  ${line}`);
 }
+function readOnlyClassification(params) {
+  const { extension, contribution } = params;
+  const readOnly = contribution.readOnly;
+  if (readOnly === undefined)
+    return;
+  const refuse = (problem) => {
+    throw new VibeError({
+      code: "VIBE_CONFIG",
+      message: `extension "${extension.name}": readOnly ${problem}`,
+      meta: { extension: extension.name, kind: contribution.kind }
+    });
+  };
+  if (contribution.kind === "method" && readOnly !== true) {
+    refuse('must be `true` on a "method" contribution \u2014 a member list classifies a namespace');
+  }
+  if (contribution.kind === "namespace") {
+    if (readOnly === true) {
+      refuse('must list the readable members on a "namespace" contribution \u2014 `true` would also classify members added later');
+    } else if (readOnly.length === 0) {
+      refuse("names no members \u2014 omit it instead, which denies the whole namespace");
+    }
+  }
+  return readOnly;
+}
+function readOnlyLine(params) {
+  const { owner, property, readOnly } = params;
+  if (readOnly === undefined)
+    return;
+  const access = `${owner}[${JSON.stringify(property)}]`;
+  return readOnly === true ? `  readonly ${property}: ${access};` : `  readonly ${property}: Pick<${access}, ${readOnly.map((member) => JSON.stringify(member)).join(" | ")}>;`;
+}
 function bakeExtensions(params) {
   const { schema } = params;
   if (params.extensions.length === 0)
@@ -58,21 +91,33 @@ function bakeExtensions(params) {
   const dtsImports = new ImportCollector;
   const mounts = [];
   const delegateDts = new Map;
+  const readOnlyDelegateDts = new Map;
   const moduleDts = [];
   const clientDts = [];
+  const readOnlyClientDts = [];
   const useContribution = (paramsInner) => {
     const { extension, contribution, scope, model } = paramsInner;
     const property = scope === "model" ? extension.name : `$${extension.name}`;
+    const readOnly = readOnlyClassification({ extension, contribution });
     jsImports.add(contribution.imports);
     dtsImports.add(contribution.dtsImports);
     moduleDts.push(...contribution.dtsTypes ?? []);
-    mounts.push(`{ extension: ${JSON.stringify(extension.name)}, scope: ${JSON.stringify(scope)}, ${model === undefined ? "" : `model: ${JSON.stringify(model)}, `}property: ${JSON.stringify(property)}, create: ${contribution.runtimeGlue} }`);
+    mounts.push(`{ extension: ${JSON.stringify(extension.name)}, scope: ${JSON.stringify(scope)}, ${model === undefined ? "" : `model: ${JSON.stringify(model)}, `}property: ${JSON.stringify(property)}, ${readOnly === undefined ? "" : `readOnly: ${JSON.stringify(readOnly)}, `}create: ${contribution.runtimeGlue} }`);
     if (scope === "model" && model !== undefined) {
       const lines = delegateDts.get(model) ?? [];
       lines.push(...indent(contribution.dts));
       delegateDts.set(model, lines);
+      const classified = readOnlyLine({ owner: `${model}Delegate`, property, readOnly });
+      if (classified !== undefined) {
+        const readOnlyLines = readOnlyDelegateDts.get(model) ?? [];
+        readOnlyLines.push(classified);
+        readOnlyDelegateDts.set(model, readOnlyLines);
+      }
     } else {
       clientDts.push(...indent(contribution.dts));
+      const classified = readOnlyLine({ owner: "VibeClientInstance", property, readOnly });
+      if (classified !== undefined)
+        readOnlyClientDts.push(classified);
     }
   };
   for (const extension of sorted) {
@@ -125,8 +170,10 @@ function bakeExtensions(params) {
     manifest: sorted.map((extension) => extensionManifestEntry({ extension })),
     dtsImports: dtsImports.lines({ typeOnly: true }),
     delegateDts,
+    readOnlyDelegateDts,
     moduleDts,
     clientDts,
+    readOnlyClientDts,
     empty: false
   };
 }
@@ -300,7 +347,8 @@ function emitJs(params) {
   const hasComputed = computed.length > 0;
   const parts = [];
   parts.push(HEADER);
-  parts.push(`import { createClient } from "@vibeorm/runtime";`);
+  parts.push(`import { createClient, createSqlModel } from "@vibeorm/runtime";`);
+  parts.push(`export { sql, decode, sqlProjection } from "@vibeorm/runtime";`);
   if (baked.jsImports.length > 0)
     parts.push(baked.jsImports.join(`
 `));
@@ -309,6 +357,11 @@ function emitJs(params) {
   parts.push(`export { ${enumEntryExports({ view }).join(", ")} } from "./enums.js";`);
   parts.push(`/** The normalized Schema IR this client was generated from (plain data). */
 export const schema = ${serializeSchema({ schema: view.schema })};`);
+  parts.push(`/** Mapped identifiers and explicit projection decoders. */
+export const sqlModels = Object.freeze({
+${view.models.map((model) => `  [${tsString({ value: model.clientName })}]: (options = {}) => createSqlModel({ schema, model: ${tsString({ value: model.name })}, ...options }),`).join(`
+`)}
+});`);
   if (baked.empty && !hasComputed) {
     parts.push(`/** Build a typed client over a database adapter. */
 ` + `export function VibeClient(options) {
@@ -434,6 +487,12 @@ function updateOpsName(params) {
 function banner(params) {
   return `// \u2500\u2500\u2500 ${params.title} \u2500\u2500\u2500`;
 }
+function capabilitiesOf(params) {
+  return DIALECT_CAPABILITIES[providerToDialect2({ provider: params.view.schema.datasource.provider })];
+}
+function literalUnion(params) {
+  return params.members.map((member) => tsString({ value: member })).join(" | ");
+}
 function objectAlias(params) {
   const { name, lines } = params;
   if (lines.length === 0)
@@ -1030,7 +1089,7 @@ ${model.relations.map((relation) => `  ${propKey({ name: relation.name })}: ${re
   const listRelations = model.relations.filter((relation) => relation.isList);
   const hasCounts = listRelations.length > 0;
   const countLine = `  readonly _count?: boolean | { readonly select: ${n}CountSelect };`;
-  const relationSelectValue = (relation) => `boolean | ${relation.target}${relation.isList ? "FindManyArgs" : "Args"}`;
+  const relationSelectValue = (relation) => `boolean | ${relation.target}${relation.isList ? "RelationFindManyArgs" : "Args"}`;
   if (hasCounts) {
     parts.push(inputAlias({
       name: `${n}CountSelect`,
@@ -1082,6 +1141,8 @@ ${model.relations.map((relation) => `  ${propKey({ name: relation.name })}: ${re
     lines: [`  readonly is?: ${n}WhereInput | null;`, `  readonly isNot?: ${n}WhereInput | null;`]
   }));
   const whereLines = [
+    `  /** Constructed raw SQL; refused on scoped, read-only and field-masked handles. */`,
+    `  readonly $raw?: SqlFragment;`,
     `  readonly AND?: ${orMany({ type: `${n}WhereInput` })};`,
     `  readonly OR?: readonly ${n}WhereInput[];`,
     `  readonly NOT?: ${orMany({ type: `${n}WhereInput` })};`
@@ -1119,9 +1180,18 @@ ${model.relations.map((relation) => `  ${propKey({ name: relation.name })}: ${re
   | ${members.join(`
   | `)};`);
   }
+  const scalarOrderLines = model.fields.map((field) => `  readonly ${propKey({ name: field.name })}?: ${field.isOptional ? "SortOrderWithNulls" : "SortOrder"};`);
+  parts.push(inputAlias({ name: `${n}ScalarOrderByInput`, lines: scalarOrderLines }));
+  parts.push(inputAlias({
+    name: `${n}RelationOrderByInput`,
+    lines: model.fields.map((field) => `  readonly ${propKey({ name: field.name })}?: SortOrder;`)
+  }));
   parts.push(inputAlias({
     name: `${n}OrderByInput`,
-    lines: model.fields.map((field) => `  readonly ${propKey({ name: field.name })}?: ${field.isOptional ? "SortOrderWithNulls" : "SortOrder"};`)
+    lines: [
+      ...scalarOrderLines,
+      ...model.relations.map((relation) => `  readonly ${propKey({ name: relation.name })}?: ${relation.isList ? "{ readonly _count?: SortOrder | Skip }" : `${relation.target}RelationOrderByInput`};`)
+    ]
   }));
   parts.push(inputAlias({ name: `${n}CreateInput`, lines: checkedCreateLines({ model }) }));
   parts.push(inputAlias({ name: `${n}UncheckedCreateInput`, lines: uncheckedCreateLines({ model }) }));
@@ -1157,24 +1227,28 @@ ${model.relations.map((relation) => `  ${propKey({ name: relation.name })}: ${re
     aggregateOpProps.push(`  readonly _min?: ${n}MinAggregateInput;`);
     aggregateOpProps.push(`  readonly _max?: ${n}MaxAggregateInput;`);
   }
-  parts.push(inputAlias({
-    name: `${n}FindManyArgs`,
-    lines: [
-      `  readonly where?: ${n}WhereInput;`,
-      `  readonly orderBy?: ${orMany({ type: `${n}OrderByInput` })};`,
-      `  readonly select?: ${n}Select;`,
-      `  readonly include?: ${n}Include;`,
-      `  readonly omit?: ${n}OmitInput;`,
-      `  readonly cursor?: ${n}WhereUniqueInput;`,
-      `  readonly after?: KeysetToken;`,
-      `  readonly keyset?: KeysetOptions;`,
-      `  readonly take?: number;`,
-      `  readonly skip?: number;`,
-      `  readonly distinct?: ${orMany({ type: `${n}ScalarFieldEnum` })};`,
-      `  readonly relationStrategy?: RelationStrategy;`,
-      `  readonly lock?: "update";`
-    ]
-  }));
+  for (const nested of [false, true]) {
+    parts.push(inputAlias({
+      name: `${n}${nested ? "RelationFindManyArgs" : "FindManyArgs"}`,
+      lines: [
+        `  readonly where?: ${n}WhereInput;`,
+        `  readonly orderBy?: ${orMany({ type: `${n}${nested ? "ScalarOrderByInput" : "OrderByInput"}` })};`,
+        `  readonly select?: ${n}Select;`,
+        `  readonly include?: ${n}Include;`,
+        `  readonly omit?: ${n}OmitInput;`,
+        `  readonly take?: number;`,
+        `  readonly skip?: number;`,
+        ...!nested ? [
+          `  readonly cursor?: ${n}WhereUniqueInput;`,
+          `  readonly after?: KeysetToken;`,
+          `  readonly keyset?: KeysetOptions;`,
+          `  readonly distinct?: ${orMany({ type: `${n}ScalarFieldEnum` })};`,
+          `  readonly relationStrategy?: RelationStrategy;`,
+          lockArgumentLines()
+        ] : []
+      ]
+    }));
+  }
   parts.push(`export type ${n}FindFirstArgs = ${n}FindManyArgs;`);
   parts.push(inputAlias({
     name: `${n}FindUniqueArgs`,
@@ -1184,12 +1258,13 @@ ${model.relations.map((relation) => `  ${propKey({ name: relation.name })}: ${re
       `  readonly include?: ${n}Include;`,
       `  readonly omit?: ${n}OmitInput;`,
       `  readonly relationStrategy?: RelationStrategy;`,
-      `  readonly lock?: "update";`
+      lockArgumentLines()
     ]
   }));
   parts.push(inputAlias({
     name: `${n}CreateArgs`,
     lines: [
+      `  readonly onConflict?: never;`,
       `  readonly data: ${n}CreateInput | ${n}UncheckedCreateInput;`,
       `  readonly select?: ${n}Select;`,
       `  readonly include?: ${n}Include;`,
@@ -1197,14 +1272,9 @@ ${model.relations.map((relation) => `  ${propKey({ name: relation.name })}: ${re
     ]
   }));
   parts.push(`export type ${n}ConflictTarget = readonly ${n}ScalarFieldEnum[] | { readonly constraint: string };`);
-  parts.push(inputAlias({
-    name: `${n}CreateOnConflictInput`,
-    lines: [
-      `  readonly action: "nothing";`,
-      `  readonly target?: ${n}ConflictTarget;`,
-      `  readonly where?: string;`
-    ]
-  }));
+  parts.push(`export type ${n}CreateOnConflictInput =
+` + `  | { readonly action: "nothing"; readonly update?: never; readonly target?: ${n}ConflictTarget | Skip; readonly where?: string | Skip }` + (capabilitiesOf({ view }).returning ? `
+  | { readonly action: "update"; readonly target: ${n}ConflictTarget; readonly update: { ${model.fields.map((field) => `readonly ${propKey({ name: field.name })}?: SqlFragment`).join("; ")} }; readonly where?: string | Skip }` : "") + ";");
   parts.push(inputAlias({
     name: `${n}CreateOrSkipArgs`,
     lines: [
@@ -1237,7 +1307,7 @@ ${model.relations.map((relation) => `  ${propKey({ name: relation.name })}: ${re
       `  readonly data: readonly ${n}CreateManyInput[];`,
       `  readonly conflictTarget: ${n}ConflictTarget;`,
       `  readonly conflictWhere?: string;`,
-      `  readonly update: readonly ${n}ScalarFieldEnum[];`,
+      `  readonly update: readonly ${n}ScalarFieldEnum[] | { ${model.fields.map((field) => `readonly ${propKey({ name: field.name })}?: SqlFragment`).join("; ")} };`,
       `  readonly skipUpdatedAt?: boolean;`,
       `  readonly allowAnyUniqueConflict?: boolean;`
     ]
@@ -1301,7 +1371,7 @@ export type ${n}UpdateWhereInput = ${n}WhereUniqueInput & ${n}WhereInput;`);
     lines: [
       `  readonly select?: ${n}CountAggregateInput;`,
       `  readonly where?: ${n}WhereInput;`,
-      `  readonly orderBy?: ${orMany({ type: `${n}OrderByInput` })};`,
+      `  readonly orderBy?: ${orMany({ type: `${n}ScalarOrderByInput` })};`,
       `  readonly cursor?: ${n}WhereUniqueInput;`,
       `  readonly take?: number;`,
       `  readonly skip?: number;`
@@ -1311,7 +1381,7 @@ export type ${n}UpdateWhereInput = ${n}WhereUniqueInput & ${n}WhereInput;`);
     name: `${n}AggregateArgs`,
     lines: [
       `  readonly where?: ${n}WhereInput;`,
-      `  readonly orderBy?: ${orMany({ type: `${n}OrderByInput` })};`,
+      `  readonly orderBy?: ${orMany({ type: `${n}ScalarOrderByInput` })};`,
       `  readonly cursor?: ${n}WhereUniqueInput;`,
       `  readonly take?: number;`,
       `  readonly skip?: number;`,
@@ -1323,7 +1393,7 @@ export type ${n}UpdateWhereInput = ${n}WhereUniqueInput & ${n}WhereInput;`);
     lines: [
       `  readonly by: readonly ${n}ScalarFieldEnum[];`,
       `  readonly where?: ${n}WhereInput;`,
-      `  readonly orderBy?: ${orMany({ type: `${n}OrderByInput` })};`,
+      `  readonly orderBy?: ${orMany({ type: `${n}ScalarOrderByInput` })};`,
       `  readonly having?: ${n}WhereInput;`,
       `  readonly take?: number;`,
       `  readonly skip?: number;`,
@@ -1433,6 +1503,11 @@ ${relationCases}
   parts.push(`export type ${n}Delegate = {
 ${delegateMethods.join(`
 `)}
+};`);
+  parts.push(`/** ${n}'s read surface on a \`$readOnly()\` client. Writes are not declared, and are refused at runtime with \`VIBE_READ_ONLY\`. */
+` + `export type ${n}ReadOnlyDelegate = {
+${[...readMethods, ...aggregateMethods, ...params.readOnlyExtensionLines ?? []].join(`
+`)}
 };`);
   return parts.join(`
 
@@ -1462,7 +1537,7 @@ function emitViewTypesForModel(params) {
     name: `${n}ViewNestedArgs`,
     lines: [
       `  readonly where?: ${n}WhereInput;`,
-      `  readonly orderBy?: ${orMany({ type: `${n}OrderByInput` })};`,
+      `  readonly orderBy?: ${orMany({ type: `${n}ScalarOrderByInput` })};`,
       `  readonly take?: number;`,
       `  readonly skip?: number;`,
       `  readonly select?: ${n}ViewSelect;`,
@@ -1617,12 +1692,102 @@ ${lines.join(`
 };`
   ];
 }
-function instanceSurfaceLines(params) {
-  const { view, selfType } = params;
-  const delegateProps = view.models.map((model) => `  readonly ${propKey({ name: model.clientName })}: ${model.name}Delegate;`);
+function emitLockSection(params) {
+  const capabilities = capabilitiesOf(params);
+  const example = capabilities.rowLockWaitPolicies.includes("skipLocked") ? [
+    ` * @example Claim one queued job without waiting for another worker's row`,
+    ` * await db.$transaction(async (tx) => {`,
+    ` *   const [job] = await tx.job.findMany({`,
+    ` *     where: { status: "queued" },`,
+    ` *     take: 1,`,
+    ` *     lock: { strength: "update", wait: "skipLocked" },`,
+    ` *   });`,
+    ` *   if (job !== undefined) await tx.job.update({ where: { id: job.id }, data: { status: "running" } });`,
+    ` * });`
+  ] : [
+    ` * @example Read a row you are about to write`,
+    ` * await db.$transaction(async (tx) => {`,
+    ` *   const account = await tx.account.findUnique({ where: { id }, lock: "update" });`,
+    ` *   await tx.account.update({ where: { id }, data: { balance: account.balance - amount } });`,
+    ` * });`
+  ];
+  const body = capabilities.rowLockStrengths.length === 0 ? [
+    `/**`,
+    ` * A row-locking read. This database has NO locking-read clause, so the`,
+    ` * historical \`"update"\` request emits no clause at all \u2014 a documented`,
+    ` * no-op that costs nothing here, because its write transactions already`,
+    ` * exclude each other. Every other strength and wait policy is refused`,
+    ` * rather than silently downgraded, so they are absent from this type.`,
+    ` *`,
+    ` * Still REQUIRES a transaction: outside one the call is refused`,
+    ` * (\`VIBE_VALIDATION\`), so code written here stays portable.`,
+    ` *`,
+    ...example,
+    ` */`,
+    `export type RowLockRequest = "update";`
+  ] : [
+    `/**`,
+    ` * A row-locking read (\`SELECT \u2026 FOR UPDATE SKIP LOCKED\`).`,
+    ` *`,
+    ` * REQUIRES a transaction \u2014 call it on the client \`$transaction\` hands its`,
+    ` * callback. Outside one the lock would be released at statement end, so`,
+    ` * the call is refused with \`VIBE_VALIDATION\` instead.`,
+    ` *`,
+    ` * \`"update"\` is the shorthand for \`{ strength: "update", wait: "wait" }\`.`,
+    ` * \`wait\` is ONE policy, never several flags: \`"wait"\` blocks until the`,
+    ` * holder finishes (the default), \`"nowait"\` fails immediately with`,
+    ` * \`VIBE_LOCK_NOT_AVAILABLE\`, and \`"skipLocked"\` leaves locked rows out of`,
+    ` * the result. Refused with \`include\`/relation \`select\`, with \`distinct\`,`,
+    ` * and on views.`,
+    ` *`,
+    ...example,
+    ` */`,
+    `export type RowLockRequest =`,
+    `  | "update"`,
+    `  | {`,
+    `      readonly strength: ${literalUnion({ members: capabilities.rowLockStrengths })};`,
+    `      readonly wait?: ${literalUnion({ members: capabilities.rowLockWaitPolicies })};`,
+    `    };`
+  ];
+  return [banner({ title: "Row locks" }), body.join(`
+`)];
+}
+function lockArgumentLines() {
+  return [
+    `  /** Row-locking read \u2014 see {@link RowLockRequest}. Only inside \`$transaction\`. */`,
+    `  readonly lock?: RowLockRequest;`
+  ].join(`
+`);
+}
+function advisoryLockLines(params) {
+  if (!capabilitiesOf(params).advisoryLocks)
+    return "";
+  return `  /**
+` + `   * Lock an application-defined resource for the rest of the transaction \u2014
+` + `   * including one that has no row yet. BLOCKS until the lock is held.
+` + `   *
+` + `   * Released by commit and by rollback; there is no unlock call, so nothing
+` + `   * can leak onto a pooled connection. Only inside \`$transaction\` (outside
+` + `   * one the lock would be gone before the next statement).
+` + `   *
+` + `   * @example Serialize an import of a supplier's price list
+` + `   * await ${params.selfLabel}.$transaction(async (tx) => {
+` + `   *   await tx.$advisoryLock({ classId: 1, objectId: supplierId });
+` + `   *   await rebuildPrices(tx);
+` + `   * });
+` + `   */
+` + `  readonly $advisoryLock: (options: AdvisoryLockOptions) => Promise<void>;
+` + `  /** The same lock WITHOUT waiting: \`true\` when acquired, \`false\` when someone else holds it. The transaction stays usable either way. */
+` + `  readonly $tryAdvisoryLock: (options: AdvisoryLockOptions) => Promise<boolean>;
+`;
+}
+function delegateSurfaceLines(params) {
+  const { view, delegateSuffix } = params;
+  const typeOf = (model) => `${model.name}${delegateSuffix}`;
+  const delegateProps = view.models.map((model) => `  readonly ${propKey({ name: model.clientName })}: ${typeOf(model)};`);
   const modelsProps = view.models.flatMap((model) => {
-    const byClientName = `    readonly ${propKey({ name: model.clientName })}: ${model.name}Delegate;`;
-    return model.name === model.clientName ? [byClientName] : [byClientName, `    readonly ${propKey({ name: model.name })}: ${model.name}Delegate;`];
+    const byClientName = `    readonly ${propKey({ name: model.clientName })}: ${typeOf(model)};`;
+    return model.name === model.clientName ? [byClientName] : [byClientName, `    readonly ${propKey({ name: model.name })}: ${typeOf(model)};`];
   });
   return `${delegateProps.join(`
 `)}
@@ -1633,20 +1798,37 @@ ${modelsProps.join(`
   };
 ` + `  /** Subscribe to client events ("query" fires after every statement, with the same payload as onQuery \u2014 both fire). Returns an unsubscribe function. */
 ` + `  readonly $on: (event: "query", listener: (event: QueryEvent) => void) => () => void;
-` + `  /** ONE transaction. Callback form: everything on \`tx\` rides the same BEGIN/COMMIT; a throw rolls back. Array form (Prisma parity): UN-AWAITED delegate calls run sequentially in one transaction, results returned positionally. */
+`;
+}
+function transactionLines(params) {
+  const { transactionType, reads } = params;
+  const doc = reads ? `  /** ONE transaction of READS \u2014 a consistent snapshot. The callback's handle is read-only too, and the array form takes read operations only. */` : `  /** ONE transaction. Callback form: everything on \`tx\` rides the same BEGIN/COMMIT; a throw rolls back. Array form (Prisma parity): UN-AWAITED delegate calls run sequentially in one transaction, results returned positionally. */`;
+  return `${doc}
 ` + `  readonly $transaction: {
-` + `    <T>(fn: (tx: ${selfType}) => Promise<T>, options?: TransactionOptions): Promise<T>;
+` + `    <T>(fn: (tx: ${transactionType}) => Promise<T>, options?: TransactionOptions): Promise<T>;
 ` + `    <T extends readonly unknown[]>(operations: readonly [...T], options?: TransactionOptions): Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }>;
 ` + `  };
+`;
+}
+var RAW_SURFACE_LINES = `  readonly $querySql: <T>(params: { readonly query: SqlFragment; readonly decoder: ResultDecoder<T> }) => Promise<T[]>;
+` + `  readonly $executeSql: (params: { readonly query: SqlFragment }) => Promise<number>;
 ` + `  readonly $queryRaw: <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]) => Promise<T[]>;
 ` + `  readonly $executeRaw: (strings: TemplateStringsArray, ...values: unknown[]) => Promise<number>;
 ` + `  readonly $queryRawUnsafe: <T = Record<string, unknown>>(text: string, ...values: unknown[]) => Promise<T[]>;
 ` + `  readonly $executeRawUnsafe: (text: string, ...values: unknown[]) => Promise<number>;
-` + `  readonly $connect: () => Promise<void>;
+`;
+var CONNECTION_SURFACE_LINES = `  readonly $connect: () => Promise<void>;
 ` + `  readonly $disconnect: () => Promise<void>;
-` + `  /** Field-masking views (v1 defineView parity): a read-only masked projection of models. */
+`;
+var DEFINE_VIEW_LINE = `  /** Field-masking views (v1 defineView parity): a read-only masked projection of models. */
 ` + `  readonly $defineView: <D extends ViewDefinitionInput>(options: { readonly name: string; readonly definition: D }) => ViewClient<D>;
 `;
+var READ_ONLY_LINE = `  /** A read-only handle over this one: reads pass through, and every write, raw-SQL and control method is refused with \`VIBE_READ_ONLY\`. Closed under composition \u2014 transactions, views, scoped and policy handles built from it stay read-only. */
+` + `  readonly $readOnly: () => ReadOnlyClientInstance;
+`;
+function instanceSurfaceLines(params) {
+  const { view, transactionType, inTransaction, selfLabel } = params;
+  return delegateSurfaceLines({ view, delegateSuffix: "Delegate" }) + transactionLines({ transactionType, reads: false }) + RAW_SURFACE_LINES + (inTransaction ? advisoryLockLines({ view, selfLabel }) : "") + (inTransaction ? "" : CONNECTION_SURFACE_LINES) + DEFINE_VIEW_LINE;
 }
 function telemetryDeclarations() {
   return [
@@ -1765,6 +1947,8 @@ function emitClient(params) {
       `  readonly adapter: DatabaseAdapter;`,
       `  readonly onQuery?: (event: QueryEvent) => void;`,
       `  readonly relationStrategy?: RelationStrategy;`,
+      `  /** Opt-in concurrent relation loading: how many of ONE query's relation statements (siblings, \`_count\` entries, key chunks) may be in flight at once. Default 1; ignored inside \`$transaction\`. */`,
+      `  readonly relationLoading?: { readonly concurrency?: number };`,
       `  /** Append the primary key to ORDER BY when a find has no explicit orderBy (default false) \u2014 deterministic row order. */`,
       `  readonly defaultOrderByPk?: boolean;`,
       `  /** Append the primary key as a tie-breaker to \`distinct\` ordering (default true) \u2014 pins WHICH row represents each distinct key. */`,
@@ -1773,6 +1957,8 @@ function emitClient(params) {
       `  readonly validate?: WriteValidators;`,
       `  /** Opt-in operation telemetry: one event per public ORM call, with the statements it ran. Parameter values are redacted by default and the exporter can never change a database outcome. */`,
       `  readonly telemetry?: VibeTelemetryOptions;`,
+      `  /** Statement diagnostics: every statement over \`slowerThanMs\` is reported with its duration and, with \`explain\`, an automatic EXPLAIN summary on PostgreSQL/PGlite (\`"analyze"\` re-executes read statements). \`VIBEORM_DIAGNOSTICS=analyze:5\` switches it on for a run; local runs only. */`,
+      `  readonly diagnostics?: StatementDiagnosticsOptions;`,
       ...baked.empty ? [] : [
         `  /** The live extension instances \u2014 verified against the baked manifest. */`,
         `  readonly extensions?: readonly VibeExtension[];`
@@ -1792,7 +1978,21 @@ function emitClient(params) {
 `;
   if (nativeRls) {
     parts.push(`export type BoundVibeClientInstance = {
-` + instanceSurfaceLines({ view, selfType: "BoundVibeClientInstance" }) + clientExtensionLines + `};`);
+` + instanceSurfaceLines({
+      view,
+      transactionType: "BoundVibeTransactionClientInstance",
+      inTransaction: false,
+      selfLabel: "db"
+    }) + READ_ONLY_LINE + clientExtensionLines + `};`);
+    parts.push(`/** The bound handle inside \`$transaction\`: same identity, plus the locks that require a transaction, minus the connection lifecycle the transaction owns. */
+` + `export type BoundVibeTransactionClientInstance = {
+` + instanceSurfaceLines({
+      view,
+      transactionType: "BoundVibeTransactionClientInstance",
+      inTransaction: true,
+      selfLabel: "tx"
+    }) + READ_ONLY_LINE + clientExtensionLines + `  // Deliberately ABSENT: $connect / $disconnect (the open transaction owns the connection) and $withContext (identity is bound once, from the root).
+` + `};`);
     parts.push(`export type VibeClientInstance = {
 ` + `  /** Bind the request's identity context \u2014 ALL of it, every declared slot \u2014 and get the client that can actually query. */
 ` + `  readonly $withContext: (context: RlsContext) => BoundVibeClientInstance;
@@ -1800,11 +2000,25 @@ function emitClient(params) {
 ` + `  readonly $on: (event: "query", listener: (event: QueryEvent) => void) => () => void;
 ` + `  readonly $connect: () => Promise<void>;
 ` + `  readonly $disconnect: () => Promise<void>;
-` + `  // Deliberately ABSENT: model delegates, $models, $transaction, $queryRaw / $executeRaw / $queryRawUnsafe / $executeRawUnsafe, $defineView and every extension mount \u2014 an unbound client has no identity, so it cannot read or write a row. Bind one with $withContext.
+` + `  // Deliberately ABSENT: model delegates, $models, $transaction, $queryRaw / $executeRaw / $queryRawUnsafe / $executeRawUnsafe, $advisoryLock / $tryAdvisoryLock, $defineView, $readOnly and every extension mount \u2014 an unbound client has no identity, so it cannot read or write a row. Bind one with $withContext.
 ` + `};`);
   } else {
     parts.push(`export type VibeClientInstance = {
-` + instanceSurfaceLines({ view, selfType: "VibeClientInstance" }) + policyClientLines({ view }) + scopedClientLines({ view }) + clientExtensionLines + `};`);
+` + instanceSurfaceLines({
+      view,
+      transactionType: "VibeTransactionClientInstance",
+      inTransaction: false,
+      selfLabel: "db"
+    }) + policyClientLines({ view, selfType: "VibeClientInstance" }) + scopedClientLines({ view, scopedType: "ScopedClientInstance" }) + READ_ONLY_LINE + clientExtensionLines + `};`);
+    parts.push(`/** The handle \`$transaction\` gives its callback. A helper that REQUIRES a transaction takes this type, and an ordinary client no longer satisfies it. */
+` + `export type VibeTransactionClientInstance = {
+` + instanceSurfaceLines({
+      view,
+      transactionType: "VibeTransactionClientInstance",
+      inTransaction: true,
+      selfLabel: "tx"
+    }) + policyClientLines({ view, selfType: "VibeTransactionClientInstance" }) + scopedClientLines({ view, scopedType: "ScopedTransactionClientInstance" }) + READ_ONLY_LINE + clientExtensionLines + `  // Deliberately ABSENT: $connect / $disconnect \u2014 the open transaction owns the connection, and both are refused at runtime here too.
+` + `};`);
   }
   parts.push(`/** Build a typed client over a database adapter. */
 export declare function VibeClient(options: VibeClientOptions): VibeClientInstance;`);
@@ -1843,17 +2057,7 @@ function emitScopedSection(params) {
     const byClientName = `    readonly ${propKey({ name: model.clientName })}: ${scopedDelegateType(model)};`;
     return model.name === model.clientName ? [byClientName] : [byClientName, `    readonly ${propKey({ name: model.name })}: ${scopedDelegateType(model)};`];
   });
-  return [
-    banner({ title: "Tenant scoping ($scoped)" }),
-    `/** What a scoped handle does when this model appears INSIDE another model's nested write: "verify" (default) rewrites reference verbs into tenant-verified lookups; "refuse" rejects them. */
-export type ScopedNestedMode = "verify" | "refuse";`,
-    `/** Per-model tenancy classification \u2014 TOTAL: every model must be named ("none" = global, passes through untouched). */
-export type ScopedModelsConfig = {
-${entries.join(`
-`)}
-};`,
-    `export type ScopedClientInstance = {
-` + `${delegateProps.join(`
+  const scopedSurface = (params2) => `${delegateProps.join(`
 `)}
 ` + `  /** Delegates keyed by BOTH camelCase client name and model name \u2014 the same objects as the top-level properties (dynamic access). */
 ` + `  readonly $models: {
@@ -1864,14 +2068,27 @@ ${modelsProps.join(`
 ` + `  readonly $on: (event: "query", listener: (event: QueryEvent) => void) => () => void;
 ` + `  /** ONE transaction; the callback receives a handle that INHERITS the scope. The array form takes un-awaited scoped delegate calls. */
 ` + `  readonly $transaction: {
-` + `    <T>(fn: (tx: ScopedClientInstance) => Promise<T>, options?: TransactionOptions): Promise<T>;
+` + `    <T>(fn: (tx: ${params2.transactionType}) => Promise<T>, options?: TransactionOptions): Promise<T>;
 ` + `    <T extends readonly unknown[]>(operations: readonly [...T], options?: TransactionOptions): Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }>;
 ` + `  };
-` + `  readonly $connect: () => Promise<void>;
-` + `  readonly $disconnect: () => Promise<void>;
-` + `  /** Field-masking views compose over the scoped handle (columns \xD7 rows). */
+` + (params2.inTransaction ? advisoryLockLines({ view, selfLabel: "tx" }) : CONNECTION_SURFACE_LINES) + `  /** Field-masking views compose over the scoped handle (columns \xD7 rows). */
 ` + `  readonly $defineView: <D extends ViewDefinitionInput>(options: { readonly name: string; readonly definition: D }) => ViewClient<D>;
-` + `  // Deliberately ABSENT: $queryRaw / $executeRaw / $queryRawUnsafe / $executeRawUnsafe (raw SQL cannot be tenant-verified \u2014 use the base client) and $scoped (scope once, from the base client).
+` + READ_ONLY_LINE;
+  return [
+    banner({ title: "Tenant scoping ($scoped)" }),
+    `/** What a scoped handle does when this model appears INSIDE another model's nested write: "verify" (default) rewrites reference verbs into tenant-verified lookups; "refuse" rejects them. */
+export type ScopedNestedMode = "verify" | "refuse";`,
+    `/** Per-model tenancy classification \u2014 TOTAL: every model must be named ("none" = global, passes through untouched). */
+export type ScopedModelsConfig = {
+${entries.join(`
+`)}
+};`,
+    `export type ScopedClientInstance = {
+` + scopedSurface({ transactionType: "ScopedTransactionClientInstance", inTransaction: false }) + `  // Deliberately ABSENT: $queryRaw / $executeRaw / $queryRawUnsafe / $executeRawUnsafe (raw SQL cannot be tenant-verified \u2014 use the base client) and $scoped (scope once, from the base client).
+` + `};`,
+    `/** The scoped handle inside \`$transaction\`: same scope, plus the locks that require a transaction. */
+` + `export type ScopedTransactionClientInstance = {
+` + scopedSurface({ transactionType: "ScopedTransactionClientInstance", inTransaction: true }) + `  // Deliberately ABSENT: the raw-SQL doors, $scoped, and $connect / $disconnect (the open transaction owns the connection).
 ` + `};`
   ];
 }
@@ -1881,7 +2098,7 @@ function scopedClientLines(params) {
   if (params.view.models.some((model) => model.policy !== undefined))
     return "";
   return `  /** Tenant scoping: a total per-model tenancy map + a scope value \u2192 a NEW handle whose every call is confined to that tenant. scope: null builds the handle but refuses calls on scoped models. */
-` + `  readonly $scoped: (config: { readonly scope: string | number | bigint | null; readonly models: ScopedModelsConfig }) => ScopedClientInstance;
+` + `  readonly $scoped: (config: { readonly scope: string | number | bigint | null; readonly models: ScopedModelsConfig }) => ${params.scopedType};
 `;
 }
 function policyClientLines(params) {
@@ -1897,10 +2114,35 @@ function policyClientLines(params) {
   }
   const contextType = `{ ${[...contextKeys.entries()].map(([key, type]) => `readonly ${propKey({ name: key })}: ${type};`).join(" ")} }`;
   return `  /** Row scoping (@@policy): bind a per-request context; policied models fail closed without one. */
-` + `  readonly $withPolicy: (context: ${contextType}) => VibeClientInstance;
-` + `  /** Deliberate, greppable full-access escape from policy scoping. */
-` + `  readonly $bypassPolicy: () => VibeClientInstance;
+` + `  readonly $withPolicy: (context: ${contextType}) => ${params.selfType};
+` + `  /** Deliberate, greppable full-access escape from policy scoping. It escapes the ROW policy, never a read-only restriction. */
+` + `  readonly $bypassPolicy: () => ${params.selfType};
+`;
+}
+function emitReadOnlySection(params) {
+  const { view, baked } = params;
+  const extensionLines = baked.readOnlyClientDts.length === 0 ? "" : `${baked.readOnlyClientDts.join(`
+`)}
 `;
+  return [
+    banner({ title: "Read-only clients ($readOnly)" }),
+    `/**
+` + ` * A read-only handle. Application-level, not a database privilege: it refuses
+` + ` * the calls VibeORM would issue, and cannot stop another connection or a role
+` + ` * with write rights \u2014 use a read-only database role or transaction when the
+` + ` * database itself must enforce it.
+` + ` *
+` + ` * @example Hand a query resolver something that cannot write
+` + ` * const reader = db.$readOnly();
+` + ` * await reader.user.findMany();          // fine
+` + ` * await reader.user.upsertMany({ \u2026 });   // VIBE_READ_ONLY, and a compile error
+` + ` */
+` + `export type ReadOnlyClientInstance = {
+` + delegateSurfaceLines({ view, delegateSuffix: "ReadOnlyDelegate" }) + transactionLines({ transactionType: "ReadOnlyClientInstance", reads: true }) + DEFINE_VIEW_LINE + policyClientLines({ view, selfType: "ReadOnlyClientInstance" }) + scopedClientLines({ view, scopedType: "ReadOnlyClientInstance" }) + `  /** Idempotent \u2014 restricting an already-restricted handle returns the same handle. */
+` + `  readonly $readOnly: () => ReadOnlyClientInstance;
+` + extensionLines + `  // Deliberately ABSENT: every write method, $queryRaw / $executeRaw / $queryRawUnsafe / $executeRawUnsafe, $connect / $disconnect, $advisoryLock / $tryAdvisoryLock, $withContext, and every extension surface its author did not classify as a read.
+` + `};`
+  ];
 }
 function emitDts(params) {
   const { view } = params;
@@ -1920,8 +2162,21 @@ function emitDts(params) {
     ...baked.empty ? [] : ["VibeExtension"],
     ...hasComputed ? ["ComputedConfig"] : []
   ].sort();
+  const runtimeTypeImports = [
+    "SqlFragment",
+    "ResultDecoder",
+    "SqlColumn",
+    "DatabaseAdapter",
+    "DbNow",
+    "QueryEvent",
+    "Skip",
+    "StatementDiagnosticsOptions",
+    "TransactionOptions",
+    "WriteValidators",
+    ...capabilitiesOf({ view }).advisoryLocks ? ["AdvisoryLockOptions"] : []
+  ].sort();
   const importLines = [
-    `import type { DatabaseAdapter, DbNow, QueryEvent, Skip, TransactionOptions, WriteValidators } from "@vibeorm/runtime";`,
+    `import type { ${runtimeTypeImports.join(", ")} } from "@vibeorm/runtime";`,
     `import type { ${schemaTypeImports.join(", ")} } from "@vibeorm/schema";`,
     ...jsonTypeImportLines({ view }),
     ...baked.dtsImports,
@@ -1936,6 +2191,14 @@ export type { VibeErrorCode } from "@vibeorm/schema";
 export type { Skip } from "@vibeorm/runtime";
 ` + `export { ${enumEntryExports({ view }).join(", ")} };`);
   parts.push(PREAMBLE);
+  parts.push(`export { sql, decode, sqlProjection } from "@vibeorm/runtime";`);
+  parts.push(`export type { SqlFragment, ResultDecoder, ExtendedDateTime, SqlColumn } from "@vibeorm/runtime";`);
+  parts.push(`/** Mapped SQL references. No database handle or execution privileges are captured. */
+export declare const sqlModels: {
+${view.models.map((model) => `  readonly ${propKey({ name: model.clientName })}: (options?: { readonly alias?: string }) => { readonly table: SqlFragment; readonly fields: { ${model.fields.map((field) => `readonly ${propKey({ name: field.name })}: SqlColumn<${field.scalar === "Json" ? "unknown" : payloadFieldType({ field })}>`).join("; ")} } };`).join(`
+`)}
+};`);
+  parts.push(...emitLockSection({ view }));
   parts.push(...filterSection());
   for (const declared of view.enums)
     parts.push(emitEnum({ declared }));
@@ -1943,12 +2206,14 @@ export type { Skip } from "@vibeorm/runtime";
   const modelParts = [];
   for (const model of view.models) {
     const extensionLines = baked.delegateDts.get(model.name);
+    const readOnlyExtensionLines = baked.readOnlyDelegateDts.get(model.name);
     const modelComputed = computedByModel.get(model.name);
     modelParts.push(emitModel({
       model,
       view,
       registry,
       ...extensionLines === undefined ? {} : { extensionLines },
+      ...readOnlyExtensionLines === undefined ? {} : { readOnlyExtensionLines },
       ...modelComputed === undefined ? {} : { computed: modelComputed }
     }));
   }
@@ -1965,6 +2230,7 @@ export type { Skip } from "@vibeorm/runtime";
   }
   parts.push(...emitViewSection({ view }));
   parts.push(...emitScopedSection({ view }));
+  parts.push(...emitReadOnlySection({ view, baked }));
   parts.push(...emitRlsSection({ view }));
   parts.push(emitClient({ view, baked, hasComputed }));
   return `${parts.join(`
@@ -2151,4 +2417,4 @@ export {
   bakeExtensions
 };
 
-//# debugId=AC114FAAB4DBE66364756E2164756E21
+//# debugId=F1C487D9764B944164756E2164756E21