@prisma-next/sql-contract-psl 0.0.1 → 0.3.0-dev.114

package/src/interpreter.ts

@@ -5,7 +5,7 @@ import type {
 } from '@prisma-next/config/config-types';
 import type { TargetPackRef } from '@prisma-next/contract/framework-components';
 import type { ContractIR } from '@prisma-next/contract/ir';
-import type { ColumnDefault } from '@prisma-next/contract/types';
+import type { ColumnDefault, ExecutionMutationDefaultValue } from '@prisma-next/contract/types';
 import type {
   ParsePslDocumentResult,
   PslAttribute,
@@ -14,7 +14,16 @@ import type {
   PslSpan,
 } from '@prisma-next/psl-parser';
 import { defineContract } from '@prisma-next/sql-contract-ts/contract-builder';
+import { assertDefined, invariant } from '@prisma-next/utils/assertions';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import {
+  type ControlMutationDefaultRegistry,
+  type ControlMutationDefaults,
+  lowerDefaultFunctionWithRegistry,
+  type MutationDefaultGeneratorDescriptor,
+  parseDefaultFunctionCall,
+} from './default-function-registry';
 
 type ColumnDescriptor = {
   readonly codecId: string;
@@ -25,31 +34,12 @@ type ColumnDescriptor = {
 
 export interface InterpretPslDocumentToSqlContractIRInput {
   readonly document: ParsePslDocumentResult;
-  readonly target?: TargetPackRef<'sql', 'postgres'>;
+  readonly target: TargetPackRef<'sql', 'postgres'>;
+  readonly scalarTypeDescriptors: ReadonlyMap<string, ColumnDescriptor>;
   readonly composedExtensionPacks?: readonly string[];
+  readonly controlMutationDefaults?: ControlMutationDefaults;
 }
 
-const DEFAULT_POSTGRES_TARGET: TargetPackRef<'sql', 'postgres'> = {
-  kind: 'target',
-  familyId: 'sql',
-  targetId: 'postgres',
-  id: 'postgres',
-  version: '0.0.1',
-  capabilities: {},
-};
-
-const SCALAR_COLUMN_MAP: Record<string, ColumnDescriptor> = {
-  String: { codecId: 'pg/text@1', nativeType: 'text' },
-  Boolean: { codecId: 'pg/bool@1', nativeType: 'bool' },
-  Int: { codecId: 'pg/int4@1', nativeType: 'int4' },
-  BigInt: { codecId: 'pg/int8@1', nativeType: 'int8' },
-  Float: { codecId: 'pg/float8@1', nativeType: 'float8' },
-  Decimal: { codecId: 'pg/numeric@1', nativeType: 'numeric' },
-  DateTime: { codecId: 'pg/timestamptz@1', nativeType: 'timestamptz' },
-  Json: { codecId: 'pg/jsonb@1', nativeType: 'jsonb' },
-  Bytes: { codecId: 'pg/bytea@1', nativeType: 'bytea' },
-};
-
 const REFERENTIAL_ACTION_MAP = {
   NoAction: 'noAction',
   Restrict: 'restrict',
@@ -68,10 +58,61 @@ type ResolvedField = {
   readonly columnName: string;
   readonly descriptor: ColumnDescriptor;
   readonly defaultValue?: ColumnDefault;
+  readonly executionDefault?: ExecutionMutationDefaultValue;
   readonly isId: boolean;
   readonly isUnique: boolean;
 };
 
+type ParsedRelationAttribute = {
+  readonly relationName?: string;
+  readonly fields?: readonly string[];
+  readonly references?: readonly string[];
+  readonly constraintName?: string;
+  readonly onDelete?: string;
+  readonly onUpdate?: string;
+};
+
+type FkRelationMetadata = {
+  readonly declaringModelName: string;
+  readonly declaringFieldName: string;
+  readonly declaringTableName: string;
+  readonly targetModelName: string;
+  readonly targetTableName: string;
+  readonly relationName?: string;
+  readonly localColumns: readonly string[];
+  readonly referencedColumns: readonly string[];
+};
+
+type ModelBackrelationCandidate = {
+  readonly modelName: string;
+  readonly tableName: string;
+  readonly field: PslField;
+  readonly targetModelName: string;
+  readonly relationName?: string;
+};
+
+type ModelRelationMetadata = {
+  readonly fieldName: string;
+  readonly toModel: string;
+  readonly toTable: string;
+  readonly cardinality: '1:N' | 'N:1';
+  readonly parentTable: string;
+  readonly parentColumns: readonly string[];
+  readonly childTable: string;
+  readonly childColumns: readonly string[];
+};
+
+type ResolvedModelEntry = {
+  readonly model: PslModel;
+  readonly mapping: ModelNameMapping;
+  readonly resolvedFields: readonly ResolvedField[];
+};
+
+function fkRelationPairKey(declaringModelName: string, targetModelName: string): string {
+  // NOTE: We assume PSL model identifiers do not contain the `::` separator.
+  return `${declaringModelName}::${targetModelName}`;
+}
+
 type ModelNameMapping = {
   readonly model: PslModel;
   readonly tableName: string;
@@ -83,18 +124,36 @@ type DynamicTableBuilder = {
     name: string,
     options: { type: ColumnDescriptor; nullable?: true; default?: ColumnDefault },
   ): DynamicTableBuilder;
+  generated(
+    name: string,
+    options: { type: ColumnDescriptor; generated: ExecutionMutationDefaultValue },
+  ): DynamicTableBuilder;
   unique(columns: readonly string[]): DynamicTableBuilder;
   primaryKey(columns: readonly string[]): DynamicTableBuilder;
   index(columns: readonly string[]): DynamicTableBuilder;
   foreignKey(
     columns: readonly string[],
     references: { table: string; columns: readonly string[] },
-    options?: { onDelete?: string; onUpdate?: string },
+    options?: { name?: string; onDelete?: string; onUpdate?: string },
   ): DynamicTableBuilder;
 };
 
 type DynamicModelBuilder = {
   field(name: string, column: string): DynamicModelBuilder;
+  relation(
+    name: string,
+    options: {
+      toModel: string;
+      toTable: string;
+      cardinality: '1:1' | '1:N' | 'N:1';
+      on: {
+        parentTable: string;
+        parentColumns: readonly string[];
+        childTable: string;
+        childColumns: readonly string[];
+      };
+    },
+  ): DynamicModelBuilder;
 };
 
 type DynamicContractBuilder = {
@@ -124,8 +183,11 @@ function lowerFirst(value: string): string {
   return value[0]?.toLowerCase() + value.slice(1);
 }
 
-function getAttribute(attributes: readonly PslAttribute[], name: string): PslAttribute | undefined {
-  return attributes.find((attribute) => attribute.name === name);
+function getAttribute(
+  attributes: readonly PslAttribute[] | undefined,
+  name: string,
+): PslAttribute | undefined {
+  return attributes?.find((attribute) => attribute.name === name);
 }
 
 function getNamedArgument(attribute: PslAttribute, name: string): string | undefined {
@@ -145,6 +207,21 @@ function getPositionalArgument(attribute: PslAttribute, index = 0): string | und
   return entry.value;
 }
 
+function getPositionalArgumentEntry(
+  attribute: PslAttribute,
+  index = 0,
+): { value: string; span: PslSpan } | undefined {
+  const entries = attribute.args.filter((arg) => arg.kind === 'positional');
+  const entry = entries[index];
+  if (!entry || entry.kind !== 'positional') {
+    return undefined;
+  }
+  return {
+    value: entry.value,
+    span: entry.span,
+  };
+}
+
 function unquoteStringLiteral(value: string): string {
   const trimmed = value.trim();
   const match = trimmed.match(/^(['"])(.*)\1$/);
@@ -156,6 +233,8 @@ function unquoteStringLiteral(value: string): string {
 
 function parseQuotedStringLiteral(value: string): string | undefined {
   const trimmed = value.trim();
+  // This intentionally accepts either '...' or "..." and relies on PSL's
+  // own string literal rules to disallow unescaped interior delimiters.
   const match = trimmed.match(/^(['"])(.*)\1$/);
   if (!match) {
     return undefined;
@@ -176,14 +255,8 @@ function parseFieldList(value: string): readonly string[] | undefined {
   return parts;
 }
 
-function parseDefaultValueExpression(expression: string): ColumnDefault | undefined {
+function parseDefaultLiteralValue(expression: string): ColumnDefault | undefined {
   const trimmed = expression.trim();
-  if (trimmed === 'autoincrement()') {
-    return { kind: 'function', expression: 'autoincrement()' };
-  }
-  if (trimmed === 'now()') {
-    return { kind: 'function', expression: 'now()' };
-  }
   if (trimmed === 'true' || trimmed === 'false') {
     return { kind: 'literal', value: trimmed === 'true' };
   }
@@ -197,6 +270,103 @@ function parseDefaultValueExpression(expression: string): ColumnDefault | undefi
   return undefined;
 }
 
+function lowerDefaultForField(input: {
+  readonly modelName: string;
+  readonly fieldName: string;
+  readonly defaultAttribute: PslAttribute;
+  readonly columnDescriptor: ColumnDescriptor;
+  readonly generatorDescriptorById: ReadonlyMap<string, MutationDefaultGeneratorDescriptor>;
+  readonly sourceId: string;
+  readonly defaultFunctionRegistry: ControlMutationDefaultRegistry;
+  readonly diagnostics: ContractSourceDiagnostic[];
+}): {
+  readonly defaultValue?: ColumnDefault;
+  readonly executionDefault?: ExecutionMutationDefaultValue;
+} {
+  const positionalEntries = input.defaultAttribute.args.filter((arg) => arg.kind === 'positional');
+  const namedEntries = input.defaultAttribute.args.filter((arg) => arg.kind === 'named');
+
+  if (namedEntries.length > 0 || positionalEntries.length !== 1) {
+    input.diagnostics.push({
+      code: 'PSL_INVALID_DEFAULT_FUNCTION_ARGUMENT',
+      message: `Field "${input.modelName}.${input.fieldName}" requires exactly one positional @default(...) expression.`,
+      sourceId: input.sourceId,
+      span: input.defaultAttribute.span,
+    });
+    return {};
+  }
+
+  const expressionEntry = getPositionalArgumentEntry(input.defaultAttribute);
+  if (!expressionEntry) {
+    input.diagnostics.push({
+      code: 'PSL_INVALID_DEFAULT_FUNCTION_ARGUMENT',
+      message: `Field "${input.modelName}.${input.fieldName}" requires a positional @default(...) expression.`,
+      sourceId: input.sourceId,
+      span: input.defaultAttribute.span,
+    });
+    return {};
+  }
+
+  const literalDefault = parseDefaultLiteralValue(expressionEntry.value);
+  if (literalDefault) {
+    return { defaultValue: literalDefault };
+  }
+
+  const defaultFunctionCall = parseDefaultFunctionCall(expressionEntry.value, expressionEntry.span);
+  if (!defaultFunctionCall) {
+    input.diagnostics.push({
+      code: 'PSL_INVALID_DEFAULT_VALUE',
+      message: `Unsupported default value "${expressionEntry.value}"`,
+      sourceId: input.sourceId,
+      span: input.defaultAttribute.span,
+    });
+    return {};
+  }
+
+  const lowered = lowerDefaultFunctionWithRegistry({
+    call: defaultFunctionCall,
+    registry: input.defaultFunctionRegistry,
+    context: {
+      sourceId: input.sourceId,
+      modelName: input.modelName,
+      fieldName: input.fieldName,
+      columnCodecId: input.columnDescriptor.codecId,
+    },
+  });
+
+  if (!lowered.ok) {
+    input.diagnostics.push(lowered.diagnostic);
+    return {};
+  }
+
+  if (lowered.value.kind === 'storage') {
+    return { defaultValue: lowered.value.defaultValue };
+  }
+
+  const generatorDescriptor = input.generatorDescriptorById.get(lowered.value.generated.id);
+  if (!generatorDescriptor) {
+    input.diagnostics.push({
+      code: 'PSL_INVALID_DEFAULT_APPLICABILITY',
+      message: `Default generator "${lowered.value.generated.id}" is not available in the composed mutation default registry.`,
+      sourceId: input.sourceId,
+      span: expressionEntry.span,
+    });
+    return {};
+  }
+
+  if (!generatorDescriptor.applicableCodecIds.includes(input.columnDescriptor.codecId)) {
+    input.diagnostics.push({
+      code: 'PSL_INVALID_DEFAULT_APPLICABILITY',
+      message: `Default generator "${generatorDescriptor.id}" is not applicable to "${input.modelName}.${input.fieldName}" with codecId "${input.columnDescriptor.codecId}".`,
+      sourceId: input.sourceId,
+      span: expressionEntry.span,
+    });
+    return {};
+  }
+
+  return { executionDefault: lowered.value.generated };
+}
+
 function parseMapName(input: {
   readonly attribute: PslAttribute | undefined;
   readonly defaultValue: string;
@@ -263,10 +433,313 @@ function parsePgvectorLength(input: {
   return parsed;
 }
 
+function getPositionalArguments(attribute: PslAttribute): readonly string[] {
+  return attribute.args
+    .filter((arg) => arg.kind === 'positional')
+    .map((arg) => (arg.kind === 'positional' ? arg.value : ''));
+}
+
+function pushInvalidAttributeArgument(input: {
+  readonly diagnostics: ContractSourceDiagnostic[];
+  readonly sourceId: string;
+  readonly span: PslSpan;
+  readonly message: string;
+}): undefined {
+  input.diagnostics.push({
+    code: 'PSL_INVALID_ATTRIBUTE_ARGUMENT',
+    message: input.message,
+    sourceId: input.sourceId,
+    span: input.span,
+  });
+  return undefined;
+}
+
+function parseOptionalSingleIntegerArgument(input: {
+  readonly attribute: PslAttribute;
+  readonly diagnostics: ContractSourceDiagnostic[];
+  readonly sourceId: string;
+  readonly entityLabel: string;
+  readonly minimum: number;
+  readonly valueLabel: string;
+}): number | null | undefined {
+  if (input.attribute.args.some((arg) => arg.kind === 'named')) {
+    return pushInvalidAttributeArgument({
+      diagnostics: input.diagnostics,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+      message: `${input.entityLabel} @${input.attribute.name} accepts zero or one positional integer argument.`,
+    });
+  }
+
+  const positionalArguments = getPositionalArguments(input.attribute);
+  if (positionalArguments.length > 1) {
+    return pushInvalidAttributeArgument({
+      diagnostics: input.diagnostics,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+      message: `${input.entityLabel} @${input.attribute.name} accepts zero or one positional integer argument.`,
+    });
+  }
+  if (positionalArguments.length === 0) {
+    return null;
+  }
+
+  const parsed = Number(unquoteStringLiteral(positionalArguments[0] ?? ''));
+  if (!Number.isInteger(parsed) || parsed < input.minimum) {
+    return pushInvalidAttributeArgument({
+      diagnostics: input.diagnostics,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+      message: `${input.entityLabel} @${input.attribute.name} requires a ${input.valueLabel}.`,
+    });
+  }
+
+  return parsed;
+}
+
+function parseOptionalNumericArguments(input: {
+  readonly attribute: PslAttribute;
+  readonly diagnostics: ContractSourceDiagnostic[];
+  readonly sourceId: string;
+  readonly entityLabel: string;
+}): { precision: number; scale?: number } | null | undefined {
+  if (input.attribute.args.some((arg) => arg.kind === 'named')) {
+    return pushInvalidAttributeArgument({
+      diagnostics: input.diagnostics,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+      message: `${input.entityLabel} @${input.attribute.name} accepts zero, one, or two positional integer arguments.`,
+    });
+  }
+
+  const positionalArguments = getPositionalArguments(input.attribute);
+  if (positionalArguments.length > 2) {
+    return pushInvalidAttributeArgument({
+      diagnostics: input.diagnostics,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+      message: `${input.entityLabel} @${input.attribute.name} accepts zero, one, or two positional integer arguments.`,
+    });
+  }
+  if (positionalArguments.length === 0) {
+    return null;
+  }
+
+  const precision = Number(unquoteStringLiteral(positionalArguments[0] ?? ''));
+  if (!Number.isInteger(precision) || precision < 1) {
+    return pushInvalidAttributeArgument({
+      diagnostics: input.diagnostics,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+      message: `${input.entityLabel} @${input.attribute.name} requires a positive integer precision.`,
+    });
+  }
+
+  if (positionalArguments.length === 1) {
+    return { precision };
+  }
+
+  const scale = Number(unquoteStringLiteral(positionalArguments[1] ?? ''));
+  if (!Number.isInteger(scale) || scale < 0) {
+    return pushInvalidAttributeArgument({
+      diagnostics: input.diagnostics,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+      message: `${input.entityLabel} @${input.attribute.name} requires a non-negative integer scale.`,
+    });
+  }
+
+  return { precision, scale };
+}
+
+/**
+ * Declarative specification for @db.* native type attributes.
+ *
+ * Argument kinds:
+ * - `noArgs`: No arguments accepted; `codecId: null` means inherit from baseDescriptor.
+ * - `optionalLength`: Zero or one positional integer (minimum 1), stored as `{ length }`.
+ * - `optionalPrecision`: Zero or one positional integer (minimum 0), stored as `{ precision }`.
+ * - `optionalNumeric`: Zero, one, or two positional integers (precision + scale).
+ */
+type NativeTypeSpec =
+  | {
+      readonly args: 'noArgs';
+      readonly baseType: string;
+      readonly codecId: string | null;
+      readonly nativeType: string;
+    }
+  | {
+      readonly args: 'optionalLength';
+      readonly baseType: string;
+      readonly codecId: string;
+      readonly nativeType: string;
+    }
+  | {
+      readonly args: 'optionalPrecision';
+      readonly baseType: string;
+      readonly codecId: string;
+      readonly nativeType: string;
+    }
+  | {
+      readonly args: 'optionalNumeric';
+      readonly baseType: string;
+      readonly codecId: string;
+      readonly nativeType: string;
+    };
+
+const NATIVE_TYPE_SPECS: Readonly<Record<string, NativeTypeSpec>> = {
+  'db.VarChar': {
+    args: 'optionalLength',
+    baseType: 'String',
+    codecId: 'sql/varchar@1',
+    nativeType: 'character varying',
+  },
+  'db.Char': {
+    args: 'optionalLength',
+    baseType: 'String',
+    codecId: 'sql/char@1',
+    nativeType: 'character',
+  },
+  'db.Uuid': { args: 'noArgs', baseType: 'String', codecId: null, nativeType: 'uuid' },
+  'db.SmallInt': { args: 'noArgs', baseType: 'Int', codecId: 'pg/int2@1', nativeType: 'int2' },
+  'db.Real': { args: 'noArgs', baseType: 'Float', codecId: 'pg/float4@1', nativeType: 'float4' },
+  'db.Numeric': {
+    args: 'optionalNumeric',
+    baseType: 'Decimal',
+    codecId: 'pg/numeric@1',
+    nativeType: 'numeric',
+  },
+  'db.Timestamp': {
+    args: 'optionalPrecision',
+    baseType: 'DateTime',
+    codecId: 'pg/timestamp@1',
+    nativeType: 'timestamp',
+  },
+  'db.Timestamptz': {
+    args: 'optionalPrecision',
+    baseType: 'DateTime',
+    codecId: 'pg/timestamptz@1',
+    nativeType: 'timestamptz',
+  },
+  'db.Date': { args: 'noArgs', baseType: 'DateTime', codecId: null, nativeType: 'date' },
+  'db.Time': {
+    args: 'optionalPrecision',
+    baseType: 'DateTime',
+    codecId: 'pg/time@1',
+    nativeType: 'time',
+  },
+  'db.Timetz': {
+    args: 'optionalPrecision',
+    baseType: 'DateTime',
+    codecId: 'pg/timetz@1',
+    nativeType: 'timetz',
+  },
+  'db.Json': { args: 'noArgs', baseType: 'Json', codecId: 'pg/json@1', nativeType: 'json' },
+};
+
+function resolveDbNativeTypeAttribute(input: {
+  readonly attribute: PslAttribute;
+  readonly baseType: string;
+  readonly baseDescriptor: ColumnDescriptor;
+  readonly diagnostics: ContractSourceDiagnostic[];
+  readonly sourceId: string;
+  readonly entityLabel: string;
+}): ColumnDescriptor | undefined {
+  const spec = NATIVE_TYPE_SPECS[input.attribute.name];
+  if (!spec) {
+    input.diagnostics.push({
+      code: 'PSL_UNSUPPORTED_NAMED_TYPE_ATTRIBUTE',
+      message: `${input.entityLabel} uses unsupported attribute "@${input.attribute.name}"`,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+    });
+    return undefined;
+  }
+
+  if (input.baseType !== spec.baseType) {
+    return pushInvalidAttributeArgument({
+      diagnostics: input.diagnostics,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+      message: `${input.entityLabel} uses @${input.attribute.name} on unsupported base type "${input.baseType}". Expected "${spec.baseType}".`,
+    });
+  }
+
+  switch (spec.args) {
+    case 'noArgs': {
+      if (getPositionalArguments(input.attribute).length > 0 || input.attribute.args.length > 0) {
+        return pushInvalidAttributeArgument({
+          diagnostics: input.diagnostics,
+          sourceId: input.sourceId,
+          span: input.attribute.span,
+          message: `${input.entityLabel} @${input.attribute.name} does not accept arguments.`,
+        });
+      }
+      return {
+        codecId: spec.codecId ?? input.baseDescriptor.codecId,
+        nativeType: spec.nativeType,
+      };
+    }
+    case 'optionalLength': {
+      const length = parseOptionalSingleIntegerArgument({
+        attribute: input.attribute,
+        diagnostics: input.diagnostics,
+        sourceId: input.sourceId,
+        entityLabel: input.entityLabel,
+        minimum: 1,
+        valueLabel: 'positive integer length',
+      });
+      if (length === undefined) {
+        return undefined;
+      }
+      return {
+        codecId: spec.codecId,
+        nativeType: spec.nativeType,
+        ...(length === null ? {} : { typeParams: { length } }),
+      };
+    }
+    case 'optionalPrecision': {
+      const precision = parseOptionalSingleIntegerArgument({
+        attribute: input.attribute,
+        diagnostics: input.diagnostics,
+        sourceId: input.sourceId,
+        entityLabel: input.entityLabel,
+        minimum: 0,
+        valueLabel: 'non-negative integer precision',
+      });
+      if (precision === undefined) {
+        return undefined;
+      }
+      return {
+        codecId: spec.codecId,
+        nativeType: spec.nativeType,
+        ...(precision === null ? {} : { typeParams: { precision } }),
+      };
+    }
+    case 'optionalNumeric': {
+      const numeric = parseOptionalNumericArguments({
+        attribute: input.attribute,
+        diagnostics: input.diagnostics,
+        sourceId: input.sourceId,
+        entityLabel: input.entityLabel,
+      });
+      if (numeric === undefined) {
+        return undefined;
+      }
+      return {
+        codecId: spec.codecId,
+        nativeType: spec.nativeType,
+        ...(numeric === null ? {} : { typeParams: numeric }),
+      };
+    }
+  }
+}
+
 function resolveColumnDescriptor(
   field: PslField,
   enumTypeDescriptors: Map<string, ColumnDescriptor>,
   namedTypeDescriptors: Map<string, ColumnDescriptor>,
+  scalarTypeDescriptors: ReadonlyMap<string, ColumnDescriptor>,
 ): ColumnDescriptor | undefined {
   if (field.typeRef && namedTypeDescriptors.has(field.typeRef)) {
     return namedTypeDescriptors.get(field.typeRef);
@@ -277,7 +750,7 @@ function resolveColumnDescriptor(
   if (enumTypeDescriptors.has(field.typeName)) {
     return enumTypeDescriptors.get(field.typeName);
   }
-  return SCALAR_COLUMN_MAP[field.typeName];
+  return scalarTypeDescriptors.get(field.typeName);
 }
 
 function collectResolvedFields(
@@ -288,16 +761,22 @@ function collectResolvedFields(
   namedTypeBaseTypes: Map<string, string>,
   modelNames: Set<string>,
   composedExtensions: Set<string>,
+  defaultFunctionRegistry: ControlMutationDefaultRegistry,
+  generatorDescriptorById: ReadonlyMap<string, MutationDefaultGeneratorDescriptor>,
   diagnostics: ContractSourceDiagnostic[],
   sourceId: string,
+  scalarTypeDescriptors: ReadonlyMap<string, ColumnDescriptor>,
 ): ResolvedField[] {
   const resolvedFields: ResolvedField[] = [];
 
   for (const field of model.fields) {
     if (field.list) {
+      if (modelNames.has(field.typeName)) {
+        continue;
+      }
       diagnostics.push({
         code: 'PSL_UNSUPPORTED_FIELD_LIST',
-        message: `Field "${model.name}.${field.name}" uses list types, which are not supported in SQL PSL provider v1`,
+        message: `Field "${model.name}.${field.name}" uses a scalar/storage list type, which is not supported in SQL PSL provider v1. Model-typed lists are only supported as backrelation navigation fields when they match an FK-side relation.`,
         sourceId,
         span: field.span,
       });
@@ -337,7 +816,12 @@ function collectResolvedFields(
       continue;
     }
 
-    let descriptor = resolveColumnDescriptor(field, enumTypeDescriptors, namedTypeDescriptors);
+    let descriptor = resolveColumnDescriptor(
+      field,
+      enumTypeDescriptors,
+      namedTypeDescriptors,
+      scalarTypeDescriptors,
+    );
     const pgvectorColumnAttribute = getAttribute(field.attributes, 'pgvector.column');
     if (pgvectorColumnAttribute) {
       if (!composedExtensions.has('pgvector')) {
@@ -368,7 +852,7 @@ function collectResolvedFields(
           if (length !== undefined) {
             descriptor = {
               codecId: 'pg/vector@1',
-              nativeType: `vector(${length})`,
+              nativeType: 'vector',
               typeParams: { length },
             };
           }
@@ -387,22 +871,47 @@ function collectResolvedFields(
     }
 
     const defaultAttribute = getAttribute(field.attributes, 'default');
-    const defaultValueRaw = defaultAttribute ? getPositionalArgument(defaultAttribute) : undefined;
-    const defaultValue = defaultValueRaw ? parseDefaultValueExpression(defaultValueRaw) : undefined;
-    if (defaultAttribute && defaultValueRaw && !defaultValue) {
+    const loweredDefault = defaultAttribute
+      ? lowerDefaultForField({
+          modelName: model.name,
+          fieldName: field.name,
+          defaultAttribute,
+          columnDescriptor: descriptor,
+          generatorDescriptorById,
+          sourceId,
+          defaultFunctionRegistry,
+          diagnostics,
+        })
+      : {};
+    if (field.optional && loweredDefault.executionDefault) {
+      const generatorDescription =
+        loweredDefault.executionDefault.kind === 'generator'
+          ? `"${loweredDefault.executionDefault.id}"`
+          : 'for this field';
       diagnostics.push({
-        code: 'PSL_INVALID_DEFAULT_VALUE',
-        message: `Unsupported default value "${defaultValueRaw}"`,
+        code: 'PSL_INVALID_DEFAULT_FUNCTION_ARGUMENT',
+        message: `Field "${model.name}.${field.name}" cannot be optional when using execution default ${generatorDescription}. Remove "?" or use a storage default.`,
         sourceId,
-        span: defaultAttribute.span,
+        span: defaultAttribute?.span ?? field.span,
       });
+      continue;
+    }
+    if (loweredDefault.executionDefault) {
+      const generatorDescriptor = generatorDescriptorById.get(loweredDefault.executionDefault.id);
+      const generatedDescriptor = generatorDescriptor?.resolveGeneratedColumnDescriptor?.({
+        generated: loweredDefault.executionDefault,
+      });
+      if (generatedDescriptor) {
+        descriptor = generatedDescriptor;
+      }
     }
     const mappedColumnName = mapping.fieldColumns.get(field.name) ?? field.name;
     resolvedFields.push({
       field,
       columnName: mappedColumnName,
       descriptor,
-      ...(defaultValue ? { defaultValue } : {}),
+      ...ifDefined('defaultValue', loweredDefault.defaultValue),
+      ...ifDefined('executionDefault', loweredDefault.executionDefault),
       isId: Boolean(getAttribute(field.attributes, 'id')),
       isUnique: Boolean(getAttribute(field.attributes, 'unique')),
     });
@@ -420,6 +929,155 @@ function hasSameSpan(a: PslSpan, b: ContractSourceDiagnosticSpan): boolean {
   );
 }
 
+function compareStrings(left: string, right: string): -1 | 0 | 1 {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+}
+
+function indexFkRelations(input: { readonly fkRelationMetadata: readonly FkRelationMetadata[] }): {
+  readonly modelRelations: Map<string, ModelRelationMetadata[]>;
+  readonly fkRelationsByPair: Map<string, FkRelationMetadata[]>;
+} {
+  const modelRelations = new Map<string, ModelRelationMetadata[]>();
+  const fkRelationsByPair = new Map<string, FkRelationMetadata[]>();
+
+  for (const relation of input.fkRelationMetadata) {
+    const existing = modelRelations.get(relation.declaringModelName);
+    const current = existing ?? [];
+    if (!existing) {
+      modelRelations.set(relation.declaringModelName, current);
+    }
+    current.push({
+      fieldName: relation.declaringFieldName,
+      toModel: relation.targetModelName,
+      toTable: relation.targetTableName,
+      cardinality: 'N:1',
+      parentTable: relation.declaringTableName,
+      parentColumns: relation.localColumns,
+      childTable: relation.targetTableName,
+      childColumns: relation.referencedColumns,
+    });
+
+    const pairKey = fkRelationPairKey(relation.declaringModelName, relation.targetModelName);
+    const pairRelations = fkRelationsByPair.get(pairKey);
+    if (!pairRelations) {
+      fkRelationsByPair.set(pairKey, [relation]);
+      continue;
+    }
+    pairRelations.push(relation);
+  }
+
+  return { modelRelations, fkRelationsByPair };
+}
+
+function applyBackrelationCandidates(input: {
+  readonly backrelationCandidates: readonly ModelBackrelationCandidate[];
+  readonly fkRelationsByPair: Map<string, readonly FkRelationMetadata[]>;
+  readonly modelRelations: Map<string, ModelRelationMetadata[]>;
+  readonly diagnostics: ContractSourceDiagnostic[];
+  readonly sourceId: string;
+}): void {
+  for (const candidate of input.backrelationCandidates) {
+    const pairKey = fkRelationPairKey(candidate.targetModelName, candidate.modelName);
+    const pairMatches = input.fkRelationsByPair.get(pairKey) ?? [];
+    const matches = candidate.relationName
+      ? pairMatches.filter((relation) => relation.relationName === candidate.relationName)
+      : [...pairMatches];
+
+    if (matches.length === 0) {
+      input.diagnostics.push({
+        code: 'PSL_ORPHANED_BACKRELATION_LIST',
+        message: `Backrelation list field "${candidate.modelName}.${candidate.field.name}" has no matching FK-side relation on model "${candidate.targetModelName}". Add @relation(fields: [...], references: [...]) on the FK-side relation or use an explicit join model for many-to-many.`,
+        sourceId: input.sourceId,
+        span: candidate.field.span,
+      });
+      continue;
+    }
+    if (matches.length > 1) {
+      input.diagnostics.push({
+        code: 'PSL_AMBIGUOUS_BACKRELATION_LIST',
+        message: `Backrelation list field "${candidate.modelName}.${candidate.field.name}" matches multiple FK-side relations on model "${candidate.targetModelName}". Add @relation(name: "...") (or @relation("...")) to both sides to disambiguate.`,
+        sourceId: input.sourceId,
+        span: candidate.field.span,
+      });
+      continue;
+    }
+
+    invariant(matches.length === 1, 'Backrelation matching requires exactly one match');
+    const matched = matches[0];
+    assertDefined(matched, 'Backrelation matching requires a defined relation match');
+
+    const existing = input.modelRelations.get(candidate.modelName);
+    const current = existing ?? [];
+    if (!existing) {
+      input.modelRelations.set(candidate.modelName, current);
+    }
+    current.push({
+      fieldName: candidate.field.name,
+      toModel: matched.declaringModelName,
+      toTable: matched.declaringTableName,
+      cardinality: '1:N',
+      parentTable: candidate.tableName,
+      parentColumns: matched.referencedColumns,
+      childTable: matched.declaringTableName,
+      childColumns: matched.localColumns,
+    });
+  }
+}
+
+function emitModelsWithRelations(input: {
+  readonly builder: DynamicContractBuilder;
+  readonly resolvedModels: ResolvedModelEntry[];
+  readonly modelRelations: Map<string, readonly ModelRelationMetadata[]>;
+}): DynamicContractBuilder {
+  let nextBuilder = input.builder;
+
+  const sortedModels = input.resolvedModels.sort((left, right) => {
+    const tableComparison = compareStrings(left.mapping.tableName, right.mapping.tableName);
+    if (tableComparison === 0) {
+      return compareStrings(left.model.name, right.model.name);
+    }
+    return tableComparison;
+  });
+
+  for (const entry of sortedModels) {
+    const relationEntries = [...(input.modelRelations.get(entry.model.name) ?? [])].sort(
+      (left, right) => compareStrings(left.fieldName, right.fieldName),
+    );
+    nextBuilder = nextBuilder.model(
+      entry.model.name,
+      entry.mapping.tableName,
+      (modelBuilder: DynamicModelBuilder) => {
+        let next = modelBuilder;
+        for (const resolvedField of entry.resolvedFields) {
+          next = next.field(resolvedField.field.name, resolvedField.columnName);
+        }
+        for (const relation of relationEntries) {
+          next = next.relation(relation.fieldName, {
+            toModel: relation.toModel,
+            toTable: relation.toTable,
+            cardinality: relation.cardinality,
+            on: {
+              parentTable: relation.parentTable,
+              parentColumns: relation.parentColumns,
+              childTable: relation.childTable,
+              childColumns: relation.childColumns,
+            },
+          });
+        }
+        return next;
+      },
+    );
+  }
+
+  return nextBuilder;
+}
+
 function mapParserDiagnostics(document: ParsePslDocumentResult): ContractSourceDiagnostic[] {
   return document.diagnostics.map((diagnostic) => ({
     code: diagnostic.code,
@@ -547,33 +1205,82 @@ function buildModelMappings(
   return result;
 }
 
+function validateNavigationListFieldAttributes(input: {
+  readonly modelName: string;
+  readonly field: PslField;
+  readonly sourceId: string;
+  readonly composedExtensions: Set<string>;
+  readonly diagnostics: ContractSourceDiagnostic[];
+}): boolean {
+  let valid = true;
+  for (const attribute of input.field.attributes) {
+    if (attribute.name === 'relation') {
+      continue;
+    }
+    if (attribute.name.startsWith('pgvector.') && !input.composedExtensions.has('pgvector')) {
+      input.diagnostics.push({
+        code: 'PSL_EXTENSION_NAMESPACE_NOT_COMPOSED',
+        message: `Attribute "@${attribute.name}" uses unrecognized namespace "pgvector". Add extension pack "pgvector" to extensionPacks in prisma-next.config.ts.`,
+        sourceId: input.sourceId,
+        span: attribute.span,
+      });
+      valid = false;
+      continue;
+    }
+    input.diagnostics.push({
+      code: 'PSL_UNSUPPORTED_FIELD_ATTRIBUTE',
+      message: `Field "${input.modelName}.${input.field.name}" uses unsupported attribute "@${attribute.name}"`,
+      sourceId: input.sourceId,
+      span: attribute.span,
+    });
+    valid = false;
+  }
+  return valid;
+}
+
 function parseRelationAttribute(input: {
   readonly attribute: PslAttribute;
   readonly modelName: string;
   readonly fieldName: string;
   readonly sourceId: string;
   readonly diagnostics: ContractSourceDiagnostic[];
-}):
-  | {
-      readonly fields: readonly string[];
-      readonly references: readonly string[];
-      readonly onDelete?: string;
-      readonly onUpdate?: string;
-    }
-  | undefined {
-  for (const arg of input.attribute.args) {
-    if (arg.kind === 'positional') {
+}): ParsedRelationAttribute | undefined {
+  const positionalEntries = input.attribute.args.filter((arg) => arg.kind === 'positional');
+  if (positionalEntries.length > 1) {
+    input.diagnostics.push({
+      code: 'PSL_INVALID_RELATION_ATTRIBUTE',
+      message: `Relation field "${input.modelName}.${input.fieldName}" has too many positional arguments`,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+    });
+    return undefined;
+  }
+
+  let relationNameFromPositional: string | undefined;
+  const positionalNameEntry = getPositionalArgumentEntry(input.attribute);
+  if (positionalNameEntry) {
+    const parsedName = parseQuotedStringLiteral(positionalNameEntry.value);
+    if (!parsedName) {
       input.diagnostics.push({
         code: 'PSL_INVALID_RELATION_ATTRIBUTE',
-        message: `Relation field "${input.modelName}.${input.fieldName}" must use named arguments`,
+        message: `Relation field "${input.modelName}.${input.fieldName}" positional relation name must be a quoted string literal`,
         sourceId: input.sourceId,
-        span: arg.span,
+        span: positionalNameEntry.span,
       });
       return undefined;
     }
+    relationNameFromPositional = parsedName;
+  }
+
+  for (const arg of input.attribute.args) {
+    if (arg.kind === 'positional') {
+      continue;
+    }
     if (
+      arg.name !== 'name' &&
       arg.name !== 'fields' &&
       arg.name !== 'references' &&
+      arg.name !== 'map' &&
       arg.name !== 'onDelete' &&
       arg.name !== 'onUpdate'
     ) {
@@ -587,58 +1294,151 @@ function parseRelationAttribute(input: {
     }
   }
 
-  const fieldsRaw = getNamedArgument(input.attribute, 'fields');
-  const referencesRaw = getNamedArgument(input.attribute, 'references');
-  if (!fieldsRaw || !referencesRaw) {
+  const namedRelationNameRaw = getNamedArgument(input.attribute, 'name');
+  const namedRelationName = namedRelationNameRaw
+    ? parseQuotedStringLiteral(namedRelationNameRaw)
+    : undefined;
+  if (namedRelationNameRaw && !namedRelationName) {
     input.diagnostics.push({
       code: 'PSL_INVALID_RELATION_ATTRIBUTE',
-      message: `Relation field "${input.modelName}.${input.fieldName}" requires fields and references arguments`,
+      message: `Relation field "${input.modelName}.${input.fieldName}" named relation name must be a quoted string literal`,
       sourceId: input.sourceId,
       span: input.attribute.span,
     });
     return undefined;
   }
-  const fields = parseFieldList(fieldsRaw);
-  const references = parseFieldList(referencesRaw);
-  if (!fields || !references || fields.length === 0 || references.length === 0) {
+
+  if (
+    relationNameFromPositional &&
+    namedRelationName &&
+    relationNameFromPositional !== namedRelationName
+  ) {
+    input.diagnostics.push({
+      code: 'PSL_INVALID_RELATION_ATTRIBUTE',
+      message: `Relation field "${input.modelName}.${input.fieldName}" has conflicting positional and named relation names`,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+    });
+    return undefined;
+  }
+  const relationName = namedRelationName ?? relationNameFromPositional;
+
+  const constraintNameRaw = getNamedArgument(input.attribute, 'map');
+  const constraintName = constraintNameRaw
+    ? parseQuotedStringLiteral(constraintNameRaw)
+    : undefined;
+  if (constraintNameRaw && !constraintName) {
+    input.diagnostics.push({
+      code: 'PSL_INVALID_RELATION_ATTRIBUTE',
+      message: `Relation field "${input.modelName}.${input.fieldName}" map argument must be a quoted string literal`,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+    });
+    return undefined;
+  }
+
+  const fieldsRaw = getNamedArgument(input.attribute, 'fields');
+  const referencesRaw = getNamedArgument(input.attribute, 'references');
+  if ((fieldsRaw && !referencesRaw) || (!fieldsRaw && referencesRaw)) {
     input.diagnostics.push({
       code: 'PSL_INVALID_RELATION_ATTRIBUTE',
-      message: `Relation field "${input.modelName}.${input.fieldName}" requires bracketed fields and references lists`,
+      message: `Relation field "${input.modelName}.${input.fieldName}" requires fields and references arguments`,
       sourceId: input.sourceId,
       span: input.attribute.span,
     });
     return undefined;
   }
 
+  let fields: readonly string[] | undefined;
+  let references: readonly string[] | undefined;
+  if (fieldsRaw && referencesRaw) {
+    const parsedFields = parseFieldList(fieldsRaw);
+    const parsedReferences = parseFieldList(referencesRaw);
+    if (
+      !parsedFields ||
+      !parsedReferences ||
+      parsedFields.length === 0 ||
+      parsedReferences.length === 0
+    ) {
+      input.diagnostics.push({
+        code: 'PSL_INVALID_RELATION_ATTRIBUTE',
+        message: `Relation field "${input.modelName}.${input.fieldName}" requires bracketed fields and references lists`,
+        sourceId: input.sourceId,
+        span: input.attribute.span,
+      });
+      return undefined;
+    }
+    fields = parsedFields;
+    references = parsedReferences;
+  }
+
+  const onDeleteArgument = getNamedArgument(input.attribute, 'onDelete');
+  const onUpdateArgument = getNamedArgument(input.attribute, 'onUpdate');
+
   return {
-    fields,
-    references,
-    ...(getNamedArgument(input.attribute, 'onDelete')
-      ? { onDelete: unquoteStringLiteral(getNamedArgument(input.attribute, 'onDelete') ?? '') }
-      : {}),
-    ...(getNamedArgument(input.attribute, 'onUpdate')
-      ? { onUpdate: unquoteStringLiteral(getNamedArgument(input.attribute, 'onUpdate') ?? '') }
-      : {}),
+    ...ifDefined('relationName', relationName),
+    ...ifDefined('fields', fields),
+    ...ifDefined('references', references),
+    ...ifDefined('constraintName', constraintName),
+    ...ifDefined('onDelete', onDeleteArgument ? unquoteStringLiteral(onDeleteArgument) : undefined),
+    ...ifDefined('onUpdate', onUpdateArgument ? unquoteStringLiteral(onUpdateArgument) : undefined),
   };
 }
 
 export function interpretPslDocumentToSqlContractIR(
   input: InterpretPslDocumentToSqlContractIRInput,
 ): Result<ContractIR, ContractSourceDiagnostics> {
+  const sourceId = input.document.ast.sourceId;
+  if (!input.target) {
+    return notOk({
+      summary: 'PSL to SQL Contract IR normalization failed',
+      diagnostics: [
+        {
+          code: 'PSL_TARGET_CONTEXT_REQUIRED',
+          message: 'PSL interpretation requires an explicit target context from composition.',
+          sourceId,
+        },
+      ],
+    });
+  }
+  if (!input.scalarTypeDescriptors) {
+    return notOk({
+      summary: 'PSL to SQL Contract IR normalization failed',
+      diagnostics: [
+        {
+          code: 'PSL_SCALAR_TYPE_CONTEXT_REQUIRED',
+          message: 'PSL interpretation requires composed scalar type descriptors.',
+          sourceId,
+        },
+      ],
+    });
+  }
+
   const diagnostics: ContractSourceDiagnostic[] = mapParserDiagnostics(input.document);
   const modelNames = new Set(input.document.ast.models.map((model) => model.name));
-  const sourceId = input.document.ast.sourceId;
   const composedExtensions = new Set(input.composedExtensionPacks ?? []);
+  const defaultFunctionRegistry =
+    input.controlMutationDefaults?.defaultFunctionRegistry ?? new Map<string, never>();
+  const generatorDescriptors = input.controlMutationDefaults?.generatorDescriptors ?? [];
+  const generatorDescriptorById = new Map<string, MutationDefaultGeneratorDescriptor>();
+  for (const descriptor of generatorDescriptors) {
+    generatorDescriptorById.set(descriptor.id, descriptor);
+  }
 
-  let builder = defineContract().target(
-    input.target ?? DEFAULT_POSTGRES_TARGET,
-  ) as unknown as DynamicContractBuilder;
+  let builder = defineContract().target(input.target) as DynamicContractBuilder;
   const enumTypeDescriptors = new Map<string, ColumnDescriptor>();
   const namedTypeDescriptors = new Map<string, ColumnDescriptor>();
   const namedTypeBaseTypes = new Map<string, string>();
 
   for (const enumDeclaration of input.document.ast.enums) {
-    const nativeType = enumDeclaration.name.toLowerCase();
+    const nativeType = parseMapName({
+      attribute: getAttribute(enumDeclaration.attributes, 'map'),
+      defaultValue: enumDeclaration.name,
+      sourceId,
+      diagnostics,
+      entityLabel: `Enum "${enumDeclaration.name}"`,
+      span: enumDeclaration.span,
+    });
     const descriptor: ColumnDescriptor = {
       codecId: 'pg/enum@1',
       nativeType,
@@ -654,7 +1454,8 @@ export function interpretPslDocumentToSqlContractIR(
 
   for (const declaration of input.document.ast.types?.declarations ?? []) {
     const baseDescriptor =
-      enumTypeDescriptors.get(declaration.baseType) ?? SCALAR_COLUMN_MAP[declaration.baseType];
+      enumTypeDescriptors.get(declaration.baseType) ??
+      input.scalarTypeDescriptors.get(declaration.baseType);
     if (!baseDescriptor) {
       diagnostics.push({
         code: 'PSL_UNSUPPORTED_NAMED_TYPE_BASE',
@@ -667,8 +1468,11 @@ export function interpretPslDocumentToSqlContractIR(
     namedTypeBaseTypes.set(declaration.name, declaration.baseType);
 
     const pgvectorAttribute = getAttribute(declaration.attributes, 'pgvector.column');
+    const dbNativeTypeAttribute = declaration.attributes.find((attribute) =>
+      attribute.name.startsWith('db.'),
+    );
     const unsupportedNamedTypeAttribute = declaration.attributes.find(
-      (attribute) => attribute.name !== 'pgvector.column',
+      (attribute) => attribute.name !== 'pgvector.column' && !attribute.name.startsWith('db.'),
     );
     if (unsupportedNamedTypeAttribute) {
       diagnostics.push({
@@ -680,6 +1484,16 @@ export function interpretPslDocumentToSqlContractIR(
       continue;
     }
 
+    if (pgvectorAttribute && dbNativeTypeAttribute) {
+      diagnostics.push({
+        code: 'PSL_UNSUPPORTED_NAMED_TYPE_ATTRIBUTE',
+        message: `Named type "${declaration.name}" cannot combine @pgvector.column with @${dbNativeTypeAttribute.name}.`,
+        sourceId,
+        span: dbNativeTypeAttribute.span,
+      });
+      continue;
+    }
+
     if (pgvectorAttribute) {
       if (!composedExtensions.has('pgvector')) {
         diagnostics.push({
@@ -710,17 +1524,41 @@ export function interpretPslDocumentToSqlContractIR(
       }
       namedTypeDescriptors.set(declaration.name, {
         codecId: 'pg/vector@1',
-        nativeType: `vector(${length})`,
-        typeRef: declaration.name,
+        nativeType: 'vector',
+        typeParams: { length },
       });
       builder = builder.storageType(declaration.name, {
         codecId: 'pg/vector@1',
-        nativeType: `vector(${length})`,
+        nativeType: 'vector',
         typeParams: { length },
       });
       continue;
     }
 
+    if (dbNativeTypeAttribute) {
+      const descriptor = resolveDbNativeTypeAttribute({
+        attribute: dbNativeTypeAttribute,
+        baseType: declaration.baseType,
+        baseDescriptor,
+        diagnostics,
+        sourceId,
+        entityLabel: `Named type "${declaration.name}"`,
+      });
+      if (!descriptor) {
+        continue;
+      }
+      namedTypeDescriptors.set(declaration.name, {
+        ...descriptor,
+        typeRef: declaration.name,
+      });
+      builder = builder.storageType(declaration.name, {
+        codecId: descriptor.codecId,
+        nativeType: descriptor.nativeType,
+        typeParams: descriptor.typeParams ?? {},
+      });
+      continue;
+    }
+
     const descriptor: ColumnDescriptor = {
       codecId: baseDescriptor.codecId,
       nativeType: baseDescriptor.nativeType,
@@ -735,6 +1573,13 @@ export function interpretPslDocumentToSqlContractIR(
   }
 
   const modelMappings = buildModelMappings(input.document.ast.models, diagnostics, sourceId);
+  const resolvedModels: Array<{
+    model: PslModel;
+    mapping: ModelNameMapping;
+    resolvedFields: ResolvedField[];
+  }> = [];
+  const fkRelationMetadata: FkRelationMetadata[] = [];
+  const backrelationCandidates: ModelBackrelationCandidate[] = [];
 
   for (const model of input.document.ast.models) {
     const mapping = modelMappings.get(model.name);
@@ -750,9 +1595,13 @@ export function interpretPslDocumentToSqlContractIR(
       namedTypeBaseTypes,
       modelNames,
       composedExtensions,
+      defaultFunctionRegistry,
+      generatorDescriptorById,
       diagnostics,
       sourceId,
+      input.scalarTypeDescriptors,
     );
+    resolvedModels.push({ model, mapping, resolvedFields });
 
     const primaryKeyColumns = resolvedFields
       .filter((field) => field.isId)
@@ -766,6 +1615,63 @@ export function interpretPslDocumentToSqlContractIR(
       });
     }
 
+    for (const field of model.fields) {
+      if (!field.list || !modelNames.has(field.typeName)) {
+        continue;
+      }
+      const attributesValid = validateNavigationListFieldAttributes({
+        modelName: model.name,
+        field,
+        sourceId,
+        composedExtensions,
+        diagnostics,
+      });
+      const relationAttribute = getAttribute(field.attributes, 'relation');
+      let relationName: string | undefined;
+      if (relationAttribute) {
+        const parsedRelation = parseRelationAttribute({
+          attribute: relationAttribute,
+          modelName: model.name,
+          fieldName: field.name,
+          sourceId,
+          diagnostics,
+        });
+        if (!parsedRelation) {
+          continue;
+        }
+        if (parsedRelation.fields || parsedRelation.references) {
+          diagnostics.push({
+            code: 'PSL_INVALID_RELATION_ATTRIBUTE',
+            message: `Backrelation list field "${model.name}.${field.name}" cannot declare fields/references; define them on the FK-side relation field`,
+            sourceId,
+            span: relationAttribute.span,
+          });
+          continue;
+        }
+        if (parsedRelation.onDelete || parsedRelation.onUpdate) {
+          diagnostics.push({
+            code: 'PSL_INVALID_RELATION_ATTRIBUTE',
+            message: `Backrelation list field "${model.name}.${field.name}" cannot declare onDelete/onUpdate; define referential actions on the FK-side relation field`,
+            sourceId,
+            span: relationAttribute.span,
+          });
+          continue;
+        }
+        relationName = parsedRelation.relationName;
+      }
+      if (!attributesValid) {
+        continue;
+      }
+
+      backrelationCandidates.push({
+        modelName: model.name,
+        tableName,
+        field,
+        targetModelName: field.typeName,
+        ...ifDefined('relationName', relationName),
+      });
+    }
+
     const relationAttributes = model.fields
       .map((field) => ({
         field,
@@ -779,16 +1685,23 @@ export function interpretPslDocumentToSqlContractIR(
       let table = tableBuilder;
 
       for (const resolvedField of resolvedFields) {
-        const options: {
-          type: ColumnDescriptor;
-          nullable?: true;
-          default?: ColumnDefault;
-        } = {
-          type: resolvedField.descriptor,
-          ...(resolvedField.field.optional ? { nullable: true as const } : {}),
-          ...(resolvedField.defaultValue ? { default: resolvedField.defaultValue } : {}),
-        };
-        table = table.column(resolvedField.columnName, options);
+        if (resolvedField.executionDefault) {
+          table = table.generated(resolvedField.columnName, {
+            type: resolvedField.descriptor,
+            generated: resolvedField.executionDefault,
+          });
+        } else {
+          const options: {
+            type: ColumnDescriptor;
+            nullable?: true;
+            default?: ColumnDefault;
+          } = {
+            type: resolvedField.descriptor,
+            ...ifDefined('nullable', resolvedField.field.optional ? (true as const) : undefined),
+            ...ifDefined('default', resolvedField.defaultValue),
+          };
+          table = table.column(resolvedField.columnName, options);
+        }
 
         if (resolvedField.isUnique) {
           table = table.unique([resolvedField.columnName]);
@@ -851,6 +1764,10 @@ export function interpretPslDocumentToSqlContractIR(
       }
 
       for (const relationAttribute of relationAttributes) {
+        if (relationAttribute.field.list) {
+          continue;
+        }
+
         if (!modelNames.has(relationAttribute.field.typeName)) {
           diagnostics.push({
             code: 'PSL_INVALID_RELATION_TARGET',
@@ -871,6 +1788,15 @@ export function interpretPslDocumentToSqlContractIR(
         if (!parsedRelation) {
           continue;
         }
+        if (!parsedRelation.fields || !parsedRelation.references) {
+          diagnostics.push({
+            code: 'PSL_INVALID_RELATION_ATTRIBUTE',
+            message: `Relation field "${model.name}.${relationAttribute.field.name}" requires fields and references arguments`,
+            sourceId,
+            span: relationAttribute.relation.span,
+          });
+          continue;
+        }
 
         const targetMapping = modelMappings.get(relationAttribute.field.typeName);
         if (!targetMapping) {
@@ -907,6 +1833,15 @@ export function interpretPslDocumentToSqlContractIR(
         if (!referencedColumns) {
           continue;
         }
+        if (localColumns.length !== referencedColumns.length) {
+          diagnostics.push({
+            code: 'PSL_INVALID_RELATION_ATTRIBUTE',
+            message: `Relation field "${model.name}.${relationAttribute.field.name}" must provide the same number of fields and references`,
+            sourceId,
+            span: relationAttribute.relation.span,
+          });
+          continue;
+        }
 
         const onDelete = parsedRelation.onDelete
           ? normalizeReferentialAction({
@@ -938,24 +1873,42 @@ export function interpretPslDocumentToSqlContractIR(
             columns: referencedColumns,
           },
           {
-            ...(onDelete ? { onDelete } : {}),
-            ...(onUpdate ? { onUpdate } : {}),
+            ...ifDefined('name', parsedRelation.constraintName),
+            ...ifDefined('onDelete', onDelete),
+            ...ifDefined('onUpdate', onUpdate),
           },
         );
+
+        fkRelationMetadata.push({
+          declaringModelName: model.name,
+          declaringFieldName: relationAttribute.field.name,
+          declaringTableName: tableName,
+          targetModelName: targetMapping.model.name,
+          targetTableName: targetMapping.tableName,
+          ...ifDefined('relationName', parsedRelation.relationName),
+          localColumns,
+          referencedColumns,
+        });
       }
 
       return table;
     });
-
-    builder = builder.model(model.name, tableName, (modelBuilder: DynamicModelBuilder) => {
-      let next = modelBuilder;
-      for (const resolvedField of resolvedFields) {
-        next = next.field(resolvedField.field.name, resolvedField.columnName);
-      }
-      return next;
-    });
   }
 
+  const { modelRelations, fkRelationsByPair } = indexFkRelations({ fkRelationMetadata });
+  applyBackrelationCandidates({
+    backrelationCandidates,
+    fkRelationsByPair,
+    modelRelations,
+    diagnostics,
+    sourceId,
+  });
+  builder = emitModelsWithRelations({
+    builder,
+    resolvedModels,
+    modelRelations,
+  });
+
   if (diagnostics.length > 0) {
     const dedupedDiagnostics = diagnostics.filter(
       (diagnostic, index, allDiagnostics) =>