@vibeorm/generator 2.1.0 → 2.2.0

package/dist/index.js

@@ -1,22 +1,151 @@
 // @bun
+// packages/generator/src/emit-module.ts
+import { createHash } from "crypto";
+import { VibeError as VibeError2, providerToDialect } from "@vibeorm/schema";
+
+// packages/generator/src/util.ts
+import { VibeError } from "@vibeorm/schema";
+function pascal(params) {
+  const { name } = params;
+  if (name.length === 0)
+    return name;
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+function clientNameOf(params) {
+  const { name } = params;
+  if (name.length === 0)
+    return name;
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}
+var IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function propKey(params) {
+  const { name } = params;
+  return IDENTIFIER_RE.test(name) ? name : JSON.stringify(name);
+}
+function tsString(params) {
+  return JSON.stringify(params.value);
+}
+function maybeParens(params) {
+  const { type } = params;
+  return type.includes("|") ? `(${type})` : type;
+}
+function stableStringify(params) {
+  return renderValue({ value: params.value, indent: "" });
+}
+function renderValue(params) {
+  const { value, indent } = params;
+  if (value === null)
+    return "null";
+  const kind = typeof value;
+  if (kind === "string" || kind === "number" || kind === "boolean")
+    return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    if (value.length === 0)
+      return "[]";
+    const inner = `${indent}  `;
+    const items = value.map((item) => inner + renderValue({ value: item, indent: inner }));
+    return `[
+${items.join(`,
+`)}
+${indent}]`;
+  }
+  if (kind === "object") {
+    const record = value;
+    const keys = Object.keys(record).filter((key) => record[key] !== undefined).sort();
+    if (keys.length === 0)
+      return "{}";
+    const inner = `${indent}  `;
+    const items = keys.map((key) => `${inner}${JSON.stringify(key)}: ${renderValue({ value: record[key], indent: inner })}`);
+    return `{
+${items.join(`,
+`)}
+${indent}}`;
+  }
+  throw new VibeError({
+    code: "VIBE_INTERNAL",
+    message: `internal: cannot serialize a ${kind} value into the generated client`,
+    meta: { kind }
+  });
+}
+
+// packages/generator/src/emit-module.ts
+var MODULE_DECLARATIONS = `import type { ClientContext, DatabaseAdapter, QueryOperation, TransactionOptions } from "@vibeorm/runtime";
+import type { DatabaseModuleManifest, SchemaIR } from "@vibeorm/schema";
+import type { VibeClientInstance, VibeTransactionClientInstance, ReadOnlyClientInstance } from "./index.js";
+export { sql, decode, sqlModels, sqlProjection } from "./index.js";
+export type ModuleClient = Omit<VibeClientInstance, "$connect" | "$disconnect" | "$transaction" | "$scoped" | "$withPolicy" | "$bypassPolicy" | "$readOnly"> & {
+  readonly $transaction: ModuleTransactionClient["$transaction"];
+  readonly $readOnly: () => ReadOnlyClientInstance;
+};
+export type ModuleTransactionClient = Omit<VibeTransactionClientInstance, "$transaction" | "$scoped" | "$withPolicy" | "$bypassPolicy"> & {
+  readonly $transaction: {
+    <T>(run: (tx: ModuleTransactionClient) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    <T extends readonly QueryOperation<unknown, "read" | "write">[]>(operations: readonly [...T], options?: TransactionOptions): Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }>;
+  };
+};
+export declare const databaseModule: {
+  readonly manifest: DatabaseModuleManifest;
+  readonly schema: SchemaIR;
+  readonly create: (params: { adapter: DatabaseAdapter }) => ModuleClient;
+  readonly bind: {
+    (params: { db: ClientContext<"root"> }): ModuleClient;
+    (params: { db: ClientContext<"transaction"> }): ModuleTransactionClient;
+    (params: { db: ClientContext<"readOnly"> }): ReadOnlyClientInstance;
+  };
+};
+`;
+function emitDatabaseModule(params) {
+  const { view, module } = params;
+  for (const key of ["id", "contract", "revision"]) {
+    if (typeof module[key] !== "string" || module[key].trim().length === 0 || module[key].includes("\x00"))
+      throw new VibeError2({ code: "VIBE_CONFIG", message: `Database module ${key} must be a non-empty identifier`, meta: { reason: "module_manifest", key } });
+  }
+  if (view.schema.rls !== undefined || view.schema.extensions.length > 0 || view.schema.models.some((model) => model.policy !== undefined))
+    throw new VibeError2({ code: "VIBE_UNSUPPORTED_CAPABILITY", message: `Module ${module.id} cannot declare extensions, policy or native RLS in this module protocol`, meta: { reason: "module_schema_feature", moduleId: module.id } });
+  const serialized = stableStringify({ value: view.schema });
+  const manifest = {
+    ...module,
+    protocol: 1,
+    dialect: providerToDialect({ provider: view.schema.datasource.provider }),
+    schemaChecksum: createHash("sha256").update(JSON.stringify(JSON.parse(serialized))).digest("hex")
+  };
+  return [
+    { name: "module.js", content: `// Generated package module. No connection or DDL on import.
+import { defineDatabaseModule } from "@vibeorm/runtime";
+import { schema } from "./schema.js";
+export { sql, decode, sqlModels, sqlProjection } from "./index.js";
+export const databaseModule = defineDatabaseModule({ ...${JSON.stringify(module)}, schema, manifest: ${JSON.stringify(manifest)} });
+` },
+    { name: "schema.js", content: `// Generated data-only schema and runtime manifest.
+export const schema = ${serialized};
+export const moduleManifest = ${JSON.stringify(manifest)};
+` },
+    { name: "schema.d.ts", content: `import type { SchemaIR, DatabaseModuleManifest } from "@vibeorm/schema";
+export declare const schema: SchemaIR;
+export declare const moduleManifest: DatabaseModuleManifest;
+` },
+    { name: "module.d.ts", content: MODULE_DECLARATIONS }
+  ];
+}
+
 // packages/generator/src/generate.ts
 import { mkdir, writeFile } from "fs/promises";
 import { join } from "path";
-import { buildComputedManifest, validateComputedConfig } from "@vibeorm/schema";
+import { VibeError as VibeError6, buildComputedManifest, validateComputedConfig } from "@vibeorm/schema";
 
 // packages/generator/src/emit-dts.ts
-import { DIALECT_CAPABILITIES, VibeError as VibeError3, providerToDialect as providerToDialect2 } from "@vibeorm/schema";
+import { DIALECT_CAPABILITIES, VibeError as VibeError4, providerToDialect as providerToDialect3 } from "@vibeorm/schema";
 
 // packages/generator/src/emit-js.ts
 import { internalError } from "@vibeorm/schema";
 
 // packages/generator/src/extension-bake.ts
 import {
-  VibeError,
+  VibeError as VibeError3,
   buildExtensionRegistry,
   extensionDeclarations,
   extensionManifestEntry,
-  providerToDialect
+  providerToDialect as providerToDialect2
 } from "@vibeorm/schema";
 var EMPTY_BAKED_EXTENSIONS = {
   jsImports: [],
@@ -54,7 +183,7 @@ function readOnlyClassification(params) {
   if (readOnly === undefined)
     return;
   const refuse = (problem) => {
-    throw new VibeError({
+    throw new VibeError3({
       code: "VIBE_CONFIG",
       message: `extension "${extension.name}": readOnly ${problem}`,
       meta: { extension: extension.name, kind: contribution.kind }
@@ -84,7 +213,7 @@ function bakeExtensions(params) {
   if (params.extensions.length === 0)
     return EMPTY_BAKED_EXTENSIONS;
   buildExtensionRegistry({ extensions: params.extensions });
-  const dialect = providerToDialect({ provider: schema.datasource.provider });
+  const dialect = providerToDialect2({ provider: schema.datasource.provider });
   const provider = schema.datasource.provider;
   const sorted = [...params.extensions].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
   const jsImports = new ImportCollector;
@@ -115,7 +244,7 @@ function bakeExtensions(params) {
       }
     } else {
       clientDts.push(...indent(contribution.dts));
-      const classified = readOnlyLine({ owner: "VibeClientInstance", property, readOnly });
+      const classified = readOnlyLine({ owner: schema.rls === undefined ? "VibeClientInstance" : "BoundVibeClientInstance", property, readOnly });
       if (classified !== undefined)
         readOnlyClientDts.push(classified);
     }
@@ -141,7 +270,7 @@ function bakeExtensions(params) {
           continue;
         const clash = model.fields.some((field) => field.name === extension.name) || model.relations.some((relation) => relation.name === extension.name);
         if (clash) {
-          throw new VibeError({
+          throw new VibeError3({
             code: "VIBE_CONFIG",
             message: `extension "${extension.name}" collides with a field/relation named "${extension.name}" on model "${model.name}" \u2014 rename one of them`,
             meta: { extension: extension.name, model: model.name }
@@ -178,71 +307,6 @@ function bakeExtensions(params) {
   };
 }
 
-// packages/generator/src/util.ts
-import { VibeError as VibeError2 } from "@vibeorm/schema";
-function pascal(params) {
-  const { name } = params;
-  if (name.length === 0)
-    return name;
-  return name.charAt(0).toUpperCase() + name.slice(1);
-}
-function clientNameOf(params) {
-  const { name } = params;
-  if (name.length === 0)
-    return name;
-  return name.charAt(0).toLowerCase() + name.slice(1);
-}
-var IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
-function propKey(params) {
-  const { name } = params;
-  return IDENTIFIER_RE.test(name) ? name : JSON.stringify(name);
-}
-function tsString(params) {
-  return JSON.stringify(params.value);
-}
-function maybeParens(params) {
-  const { type } = params;
-  return type.includes("|") ? `(${type})` : type;
-}
-function stableStringify(params) {
-  return renderValue({ value: params.value, indent: "" });
-}
-function renderValue(params) {
-  const { value, indent: indent2 } = params;
-  if (value === null)
-    return "null";
-  const kind = typeof value;
-  if (kind === "string" || kind === "number" || kind === "boolean")
-    return JSON.stringify(value);
-  if (Array.isArray(value)) {
-    if (value.length === 0)
-      return "[]";
-    const inner = `${indent2}  `;
-    const items = value.map((item) => inner + renderValue({ value: item, indent: inner }));
-    return `[
-${items.join(`,
-`)}
-${indent2}]`;
-  }
-  if (kind === "object") {
-    const record = value;
-    const keys = Object.keys(record).filter((key) => record[key] !== undefined).sort();
-    if (keys.length === 0)
-      return "{}";
-    const inner = `${indent2}  `;
-    const items = keys.map((key) => `${inner}${JSON.stringify(key)}: ${renderValue({ value: record[key], indent: inner })}`);
-    return `{
-${items.join(`,
-`)}
-${indent2}}`;
-  }
-  throw new VibeError2({
-    code: "VIBE_INTERNAL",
-    message: `internal: cannot serialize a ${kind} value into the generated client`,
-    meta: { kind }
-  });
-}
-
 // packages/generator/src/emit-js.ts
 var HEADER = `// Generated by VibeORM (@vibeorm/generator) \u2014 DO NOT EDIT.
 // Regenerate with \`vibeorm generate\` after every schema change.`;
@@ -459,13 +523,15 @@ var MINMAX_SCALARS = new Set([
 function payloadBaseType(params) {
   const { field } = params;
   if (field.jsonType !== undefined)
-    return field.jsonType.name;
+    return `import(${tsString({ value: field.jsonType.from })}).${field.jsonType.name}`;
   return field.enumName ?? PAYLOAD_TYPES[field.scalar];
 }
 function inputBaseType(params) {
   const { field } = params;
   if (field.jsonType !== undefined)
-    return field.jsonType.name;
+    return `import(${tsString({ value: field.jsonType.from })}).${field.jsonType.name}`;
+  if (field.isList && field.scalar === "DateTime")
+    return "Date | string";
   return field.enumName ?? INPUT_TYPES[field.scalar];
 }
 function filterName(params) {
@@ -488,7 +554,7 @@ 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 })];
+  return DIALECT_CAPABILITIES[providerToDialect3({ provider: params.view.schema.datasource.provider })];
 }
 function literalUnion(params) {
   return params.members.map((member) => tsString({ value: member })).join(" | ");
@@ -587,6 +653,10 @@ export type KeysetOptions = {
 /** Result of createMany/updateMany/deleteMany. */
 export type BatchPayload = { readonly count: number };
 
+/** Static operation classification only; runtime verifies instance ownership and active lifetime. */
+declare const vibeTransaction: unique symbol;
+export type VibeQueryPromise<T, Access extends "read" | "write" = "read"> = QueryOperation<T, Access>;
+
 /**
  * What upsertMany reports. \`count\` is the rows submitted after duplicate-key
  * validation \u2014 every one of them was inserted or updated, since the statement
@@ -609,7 +679,7 @@ type Provided<T> = Exclude<T, Skip | undefined>;
 type OmittedKeys<O> = keyof { [K in keyof O as O[K] extends true ? K : never]: 0 };
 
 /** Keys a selection has not RULED OUT \u2014 everything except a literal false/undefined. */
-type PossibleKeys<S> = keyof { [K in keyof S as S[K] extends false | undefined ? never : K]: 0 };
+type PossibleKeys<S> = keyof { [K in keyof S as S[K] extends false | undefined | Skip ? never : K]: 0 };
 
 /**
  * Keys whose flag can STILL be false or missing when the query runs \u2014 a widened
@@ -617,7 +687,7 @@ type PossibleKeys<S> = keyof { [K in keyof S as S[K] extends false | undefined ?
  * result type must not promise a field a run-time flag can switch off.
  */
 type UncertainKeys<S> = PossibleKeys<S> &
-  keyof { [K in keyof S as [false] extends [S[K]] ? K : [undefined] extends [S[K]] ? K : never]: 0 };
+  keyof { [K in keyof S as [false] extends [S[K]] ? K : [undefined] extends [S[K]] ? K : [Skip] extends [S[K]] ? K : never]: 0 };
 
 /** Keys the selection definitely turns on: a literal \`true\`, or a nested selection object. */
 type ExactKeys<S> = Exclude<PossibleKeys<S>, UncertainKeys<S>>;
@@ -892,7 +962,7 @@ function register(params) {
   const existing = registry.get(name);
   if (existing !== undefined) {
     if (existing !== text) {
-      throw new VibeError3({
+      throw new VibeError4({
         code: "VIBE_INTERNAL",
         message: `internal: nested input type "${name}" generated with two different bodies`,
         meta: { name }
@@ -1400,8 +1470,8 @@ export type ${n}UpdateWhereInput = ${n}WhereUniqueInput & ${n}WhereInput;`);
       ...aggregateOpProps
     ]
   }));
-  const exactPart = (source) => `${source}[K] extends false | undefined ? never : false extends ${source}[K] ? never : undefined extends ${source}[K] ? never : K`;
-  const uncertainPart = (source) => `${source}[K] extends false | undefined ? never : false extends ${source}[K] ? K : undefined extends ${source}[K] ? K : never`;
+  const exactPart = (source) => `${source}[K] extends false | undefined | Skip ? never : false extends ${source}[K] ? never : undefined extends ${source}[K] ? never : Skip extends ${source}[K] ? never : K`;
+  const uncertainPart = (source) => `${source}[K] extends false | undefined | Skip ? never : false extends ${source}[K] ? K : undefined extends ${source}[K] ? K : Skip extends ${source}[K] ? K : never`;
   parts.push(`type ${n}OmitBase<A> = A extends { readonly omit: infer O extends object }
 ` + `  ? Omit<${n}, PossibleKeys<O> & keyof ${n}> & { [K in UncertainKeys<O> & keyof ${n}]?: ${n}[K] }
 ` + `  : "omit" extends keyof A ? Omit<${n}, PossibleKeys<Provided<A["omit"]>> & keyof ${n}> & Partial<Pick<${n}, PossibleKeys<Provided<A["omit"]>> & keyof ${n}>> : ${n};`);
@@ -1411,10 +1481,11 @@ export type ${n}UpdateWhereInput = ${n}WhereUniqueInput & ${n}WhereInput;`);
     parts.push(`type ${n}CountResult<C> = C extends { readonly select: infer CS extends object }
 ` + `  ? { [K in keyof CS & (${listUnion}) as ${exactPart("CS")}]: number } &
 ` + `    { [K in keyof CS & (${listUnion}) as ${uncertainPart("CS")}]?: number }
-` + `  : { ${allCounts} };`);
+` + `  : C extends { readonly select: Skip } ? { ${allCounts} }
+` + `  : "select" extends keyof C ? Partial<{ ${allCounts} }> : { ${allCounts} };`);
     parts.push(`type ${n}CountPayload<S> = S extends { readonly _count: infer C extends true | object } ? { _count: ${n}CountResult<C> }
-` + `  : S extends { readonly _count: false | undefined } ? unknown
-` + `  : S extends { readonly _count?: infer C extends boolean | object } ? { _count?: ${n}CountResult<C> } : unknown;`);
+` + `  : S extends { readonly _count: false | undefined | Skip } ? unknown
+` + `  : S extends { readonly _count?: infer C extends boolean | object | Skip } ? { _count?: ${n}CountResult<Provided<C>> } : unknown;`);
   }
   if (hasRelations) {
     const relationCases = model.relations.map((relation) => {
@@ -1445,12 +1516,14 @@ ${relationCases}
 ` + `    { [K in keyof S & keyof ${n}Relations as ${exactPart("S")}]: ${n}RelationPayload<K, S[K]> } &
 ` + `    { [K in keyof S & keyof ${n}Relations as ${uncertainPart("S")}]?: ${n}RelationPayload<K, S[K]> }${hasCounts ? ` &
     ${n}CountPayload<S>` : ""}
+` + `  : A extends { readonly select: Skip } ? ${n}OmitBase<A> & ${n}IncludePayload<A>
 ` + `  : "select" extends keyof A ? Partial<${n}>
 ` + `  : ${n}OmitBase<A> & ${n}IncludePayload<A>;`);
   } else {
     parts.push(`export type ${n}GetPayload<A> = A extends { readonly select: infer S extends object }
 ` + `  ? { [K in keyof S & ${selectableEnum} as ${exactPart("S")}]: ${n}[K & keyof ${n}] } &
 ` + `    { [K in keyof S & ${selectableEnum} as ${uncertainPart("S")}]?: ${n}[K & keyof ${n}] }
+` + `  : A extends { readonly select: Skip } ? ${n}OmitBase<A>
 ` + `  : "select" extends keyof A ? Partial<${n}> : ${n}OmitBase<A>;`);
   }
   const aggregateFields = (fields, value) => `{ ${fields.map((field) => `${propKey({ name: field.name })}: ${value(field)}`).join("; ")} }`;
@@ -1470,33 +1543,33 @@ ${relationCases}
 ` + `  : "select" extends keyof A ? number | ${n}AggregateSelection<${n}AggregateValues["_count"], Provided<A["select"]>> : number;`);
   parts.push(`export type ${n}AggregateResult<A> =
 ` + `  { [K in keyof A & keyof ${n}AggregateValues as HasSelectedField<A[K]> extends true ? K : never]: ${n}AggregateSelection<${n}AggregateValues[K], A[K]> } &
-` + `  { [K in keyof A & keyof ${n}AggregateValues as HasSelectedField<A[K]> extends true ? never : K]?: ${n}AggregateSelection<${n}AggregateValues[K], Provided<A[K]>> };`);
+` + `  { [K in keyof A & keyof ${n}AggregateValues as A[K] extends false | undefined | Skip ? never : HasSelectedField<A[K]> extends true ? never : K]?: ${n}AggregateSelection<${n}AggregateValues[K], Provided<A[K]>> };`);
   parts.push(`export type ${n}GroupByResult<A extends ${n}GroupByArgs> =
 ` + `  (number extends A["by"]["length"] ? Partial<Pick<${n}, A["by"][number]>> : Pick<${n}, A["by"][number]>) & ${n}AggregateResult<A>;`);
   const readMethods = [
-    `  findMany<A extends ${n}FindManyArgs = {}>(args?: A): Promise<${n}GetPayload<A>[]>;`,
-    `  findFirst<A extends ${n}FindFirstArgs = {}>(args?: A): Promise<${n}GetPayload<A> | null>;`,
-    `  findFirstOrThrow<A extends ${n}FindFirstArgs = {}>(args?: A): Promise<${n}GetPayload<A>>;`,
-    `  findUnique<A extends ${n}FindUniqueArgs>(args: A): Promise<${n}GetPayload<A> | null>;`,
-    `  findUniqueOrThrow<A extends ${n}FindUniqueArgs>(args: A): Promise<${n}GetPayload<A>>;`
+    `  findMany<A extends ${n}FindManyArgs = {}>(args?: A): VibeQueryPromise<${n}GetPayload<A>[]>;`,
+    `  findFirst<A extends ${n}FindFirstArgs = {}>(args?: A): VibeQueryPromise<${n}GetPayload<A> | null>;`,
+    `  findFirstOrThrow<A extends ${n}FindFirstArgs = {}>(args?: A): VibeQueryPromise<${n}GetPayload<A>>;`,
+    `  findUnique<A extends ${n}FindUniqueArgs>(args: A): VibeQueryPromise<${n}GetPayload<A> | null>;`,
+    `  findUniqueOrThrow<A extends ${n}FindUniqueArgs>(args: A): VibeQueryPromise<${n}GetPayload<A>>;`
   ];
   const writeMethods = [
-    `  create<A extends ${n}CreateOrSkipArgs>(args: A): Promise<${n}GetPayload<A> | null>;`,
-    `  create<A extends ${n}CreateArgs>(args: A): Promise<${n}GetPayload<A>>;`,
-    `  createMany(args: ${n}CreateManyArgs): Promise<BatchPayload>;`,
-    `  createManyAndReturn<A extends ${n}CreateManyAndReturnArgs>(args: A): Promise<${n}GetPayload<A>[]>;`,
-    `  update<A extends ${n}UpdateArgs>(args: A): Promise<${n}GetPayload<A>>;`,
-    `  updateMany(args: ${n}UpdateManyArgs): Promise<BatchPayload>;`,
-    `  updateManyAndReturn<A extends ${n}UpdateManyAndReturnArgs>(args: A): Promise<${n}GetPayload<A>[]>;`,
-    `  upsert<A extends ${n}UpsertArgs>(args: A): Promise<${n}GetPayload<A>>;`,
-    `  upsertMany(args: ${n}UpsertManyArgs): Promise<UpsertManyPayload>;`,
-    `  delete<A extends ${n}DeleteArgs>(args: A): Promise<${n}GetPayload<A>>;`,
-    `  deleteMany(args?: ${n}DeleteManyArgs): Promise<BatchPayload>;`
+    `  create<A extends ${n}CreateOrSkipArgs>(args: A): VibeQueryPromise<${n}GetPayload<A> | null, "write">;`,
+    `  create<A extends ${n}CreateArgs>(args: A): VibeQueryPromise<${n}GetPayload<A>, "write">;`,
+    `  createMany(args: ${n}CreateManyArgs): VibeQueryPromise<BatchPayload, "write">;`,
+    `  createManyAndReturn<A extends ${n}CreateManyAndReturnArgs>(args: A): VibeQueryPromise<${n}GetPayload<A>[], "write">;`,
+    `  update<A extends ${n}UpdateArgs>(args: A): VibeQueryPromise<${n}GetPayload<A>, "write">;`,
+    `  updateMany(args: ${n}UpdateManyArgs): VibeQueryPromise<BatchPayload, "write">;`,
+    `  updateManyAndReturn<A extends ${n}UpdateManyAndReturnArgs>(args: A): VibeQueryPromise<${n}GetPayload<A>[], "write">;`,
+    `  upsert<A extends ${n}UpsertArgs>(args: A): VibeQueryPromise<${n}GetPayload<A>, "write">;`,
+    `  upsertMany(args: ${n}UpsertManyArgs): VibeQueryPromise<UpsertManyPayload, "write">;`,
+    `  delete<A extends ${n}DeleteArgs>(args: A): VibeQueryPromise<${n}GetPayload<A>, "write">;`,
+    `  deleteMany(args?: ${n}DeleteManyArgs): VibeQueryPromise<BatchPayload, "write">;`
   ];
   const aggregateMethods = [
-    `  count<A extends ${n}CountArgs = {}>(args?: A): Promise<${n}CountOutput<A>>;`,
-    `  aggregate<A extends ${n}AggregateArgs>(args: A): Promise<${n}AggregateResult<A>>;`,
-    `  groupBy<const A extends ${n}GroupByArgs>(args: A): Promise<${n}GroupByResult<A>[]>;`
+    `  count<A extends ${n}CountArgs = {}>(args?: A): VibeQueryPromise<${n}CountOutput<A>>;`,
+    `  aggregate<A extends ${n}AggregateArgs>(args: A): VibeQueryPromise<${n}AggregateResult<A>>;`,
+    `  groupBy<const A extends ${n}GroupByArgs>(args: A): VibeQueryPromise<${n}GroupByResult<A>[]>;`
   ];
   const delegateMethods = model.isView ? [...readMethods, ...aggregateMethods] : [...readMethods, ...writeMethods, ...aggregateMethods];
   delegateMethods.push(...params.extensionLines ?? []);
@@ -1570,8 +1643,8 @@ function emitViewTypesForModel(params) {
       `  readonly relationStrategy?: RelationStrategy;`
     ]
   }));
-  const exactPart = (source) => `${source}[K] extends false | undefined ? never : false extends ${source}[K] ? never : undefined extends ${source}[K] ? never : K`;
-  const uncertainPart = (source) => `${source}[K] extends false | undefined ? never : false extends ${source}[K] ? K : undefined extends ${source}[K] ? K : never`;
+  const exactPart = (source) => `${source}[K] extends false | undefined | Skip ? never : false extends ${source}[K] ? never : undefined extends ${source}[K] ? never : Skip extends ${source}[K] ? never : K`;
+  const uncertainPart = (source) => `${source}[K] extends false | undefined | Skip ? never : false extends ${source}[K] ? K : undefined extends ${source}[K] ? K : Skip extends ${source}[K] ? K : never`;
   parts.push(`type ${n}ViewSelectScalars<F, A> = A extends { readonly select: infer S extends object }
 ` + `  ? { [K in keyof S & keyof F & ${n}ScalarFieldEnum as ${exactPart("S")}]: ${n}[K & keyof ${n}] } &
 ` + `    { [K in keyof S & keyof F & ${n}ScalarFieldEnum as ${uncertainPart("S")}]?: ${n}[K & keyof ${n}] }
@@ -1651,19 +1724,6 @@ ${view.models.map((model) => `  ${propKey({ name: model.clientName })}: ${model.
   }
   return parts;
 }
-function jsonTypeImportLines(params) {
-  const bySpecifier = new Map;
-  for (const model of params.view.models) {
-    for (const field of model.fields) {
-      if (field.jsonType === undefined)
-        continue;
-      const names = bySpecifier.get(field.jsonType.from) ?? new Set;
-      names.add(field.jsonType.name);
-      bySpecifier.set(field.jsonType.from, names);
-    }
-  }
-  return [...bySpecifier.keys()].sort().map((from) => `import type { ${[...bySpecifier.get(from)].sort().join(", ")} } from ${tsString({ value: from })};`);
-}
 function hasNativeRls(params) {
   return params.view.schema.rls !== undefined;
 }
@@ -1806,7 +1866,7 @@ function transactionLines(params) {
   return `${doc}
 ` + `  readonly $transaction: {
 ` + `    <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]> }>;
+` + `    <T extends readonly VibeQueryPromise<unknown, ${reads ? '"read"' : '"read" | "write"'}>[]>(operations: readonly [...T], options?: TransactionOptions): Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }>;
 ` + `  };
 `;
 }
@@ -1828,7 +1888,8 @@ var READ_ONLY_LINE = `  /** A read-only handle over this one: reads pass through
 `;
 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;
+  return (inTransaction ? `  readonly [vibeTransaction]: true;
+` : "") + 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 [
@@ -1945,8 +2006,12 @@ function emitClient(params) {
     name: "VibeClientOptions",
     lines: [
       `  readonly adapter: DatabaseAdapter;`,
+      `  /** Strict argument validation defaults to true; false restores legacy omission of undefined values. */`,
+      `  readonly strictArguments?: boolean;`,
       `  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. */`,
@@ -1955,6 +2020,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[];`
@@ -1973,7 +2040,7 @@ function emitClient(params) {
 `)}
 `;
   if (nativeRls) {
-    parts.push(`export type BoundVibeClientInstance = {
+    parts.push(`export type BoundVibeClientInstance = ClientContext<"restricted"> & {
 ` + instanceSurfaceLines({
       view,
       transactionType: "BoundVibeTransactionClientInstance",
@@ -1981,7 +2048,7 @@ function emitClient(params) {
       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 = {
+` + `export type BoundVibeTransactionClientInstance = ClientContext<"restricted"> & {
 ` + instanceSurfaceLines({
       view,
       transactionType: "BoundVibeTransactionClientInstance",
@@ -1989,7 +2056,7 @@ function emitClient(params) {
       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 = {
+    parts.push(`export type VibeClientInstance = ClientContext<"restricted"> & {
 ` + `  /** 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;
 ` + `  /** Subscribe to client events ("query" fires after every statement, with the same payload as onQuery \u2014 both fire). Returns an unsubscribe function. */
@@ -1999,7 +2066,7 @@ function emitClient(params) {
 ` + `  // 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 = {
+    parts.push(`export type VibeClientInstance = ClientContext<"root"> & {
 ` + instanceSurfaceLines({
       view,
       transactionType: "VibeTransactionClientInstance",
@@ -2007,7 +2074,7 @@ function emitClient(params) {
       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 = {
+` + `export type VibeTransactionClientInstance = ClientContext<"transaction"> & {
 ` + instanceSurfaceLines({
       view,
       transactionType: "VibeTransactionClientInstance",
@@ -2053,7 +2120,8 @@ 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)};`];
   });
-  const scopedSurface = (params2) => `${delegateProps.join(`
+  const scopedSurface = (params2) => (params2.inTransaction ? `  readonly [vibeTransaction]: true;
+` : "") + `${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: {
@@ -2065,7 +2133,7 @@ ${modelsProps.join(`
 ` + `  /** 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: ${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]> }>;
+` + `    <T extends readonly VibeQueryPromise<unknown, "read" | "write">[]>(operations: readonly [...T], options?: TransactionOptions): Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }>;
 ` + `  };
 ` + (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>;
@@ -2133,7 +2201,7 @@ function emitReadOnlySection(params) {
 ` + ` * await reader.user.findMany();          // fine
 ` + ` * await reader.user.upsertMany({ \u2026 });   // VIBE_READ_ONLY, and a compile error
 ` + ` */
-` + `export type ReadOnlyClientInstance = {
+` + `export type ReadOnlyClientInstance = ClientContext<"readOnly"> & {
 ` + 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.
@@ -2159,6 +2227,8 @@ function emitDts(params) {
     ...hasComputed ? ["ComputedConfig"] : []
   ].sort();
   const runtimeTypeImports = [
+    "ClientContext",
+    "QueryOperation",
     "SqlFragment",
     "ResultDecoder",
     "SqlColumn",
@@ -2166,6 +2236,7 @@ function emitDts(params) {
     "DbNow",
     "QueryEvent",
     "Skip",
+    "StatementDiagnosticsOptions",
     "TransactionOptions",
     "WriteValidators",
     ...capabilitiesOf({ view }).advisoryLocks ? ["AdvisoryLockOptions"] : []
@@ -2173,7 +2244,6 @@ function emitDts(params) {
   const importLines = [
     `import type { ${runtimeTypeImports.join(", ")} } from "@vibeorm/runtime";`,
     `import type { ${schemaTypeImports.join(", ")} } from "@vibeorm/schema";`,
-    ...jsonTypeImportLines({ view }),
     ...baked.dtsImports,
     `import { ${enumEntryExports({ view }).join(", ")} } from "./enums.js";`
   ];
@@ -2235,7 +2305,7 @@ ${view.models.map((model) => `  readonly ${propKey({ name: model.clientName })}:
 }
 
 // packages/generator/src/schema-view.ts
-import { VibeError as VibeError4, assertValidSchemaIR, enumStorageOf, isEnumType } from "@vibeorm/schema";
+import { VibeError as VibeError5, assertValidSchemaIR, enumStorageOf, isEnumType } from "@vibeorm/schema";
 import { postgresDialect, renderRlsPolicy } from "@vibeorm/sql";
 var JSON_TYPE_RE = /@type\(\s*([A-Za-z_$][A-Za-z0-9_$]*)\s+from\s+"([^"]+)"\s*\)/;
 function parseJsonTypeAnnotation(params) {
@@ -2254,7 +2324,7 @@ function buildFieldView(params) {
   const enumRef = isEnumType(field.type);
   const annotation = parseJsonTypeAnnotation({ comment: field.documentation });
   if (annotation !== null && (enumRef || field.type !== "Json")) {
-    throw new VibeError4({
+    throw new VibeError5({
       code: "VIBE_SCHEMA_INVALID",
       message: `@type(...) annotation on ${model}.${field.name} \u2014 typed JSON is only valid on Json fields`,
       meta: { model, field: field.name }
@@ -2328,7 +2398,7 @@ function buildModelView(params) {
       target: relation.targetModel,
       type: relation.type,
       isList: relation.isList,
-      isOptional: relation.isOptional,
+      isOptional: relation.isOptional || !relation.isList && (relation.fields?.length ?? 0) === 0,
       fkFields: relation.fields ?? [],
       inverseName: target === undefined ? null : resolveInverse({ relation, target })
     };
@@ -2391,12 +2461,15 @@ async function generateClient(params) {
     validateComputedConfig({ schema, computed: params.computed });
     computed = buildComputedManifest({ computed: params.computed });
   }
+  if (params.module !== undefined && (!baked.empty || computed.length > 0))
+    throw new VibeError6({ code: "VIBE_UNSUPPORTED_CAPABILITY", message: "Package modules do not support computed fields or extension mounts in this protocol", meta: { reason: "module_schema_feature", moduleId: params.module.id } });
   const outputs = [
     { name: "index.js", content: emitJs({ view, baked, computed }) },
     { name: "index.d.ts", content: emitDts({ view, baked, computed }) },
     { name: "enums.js", content: emitEnumsJs({ view }) },
     { name: "enums.d.ts", content: emitEnumsDts({ view }) },
-    { name: "README.md", content: README }
+    { name: "README.md", content: README },
+    ...params.module === undefined ? [] : emitDatabaseModule({ view, module: params.module })
   ];
   await mkdir(outDir, { recursive: true });
   const files = [];
@@ -2412,4 +2485,4 @@ export {
   bakeExtensions
 };
 
-//# debugId=43DBEE51B9E7189D64756E2164756E21
+//# debugId=732A6C5C8F7D397B64756E2164756E21