@prisma-next/sql-contract-psl 0.13.0 → 0.14.0-dev.10

package/src/interpreter.ts

@@ -14,9 +14,14 @@ import { crossRef } from '@prisma-next/contract/types';
 import type {
   AuthoringContributions,
   AuthoringEntityContext,
-  AuthoringEntityTypeDescriptor,
+  AuthoringPslBlockDescriptorNamespace,
+  PslExtensionBlock,
 } from '@prisma-next/framework-components/authoring';
-import { instantiateAuthoringEntityType } from '@prisma-next/framework-components/authoring';
+import {
+  instantiateAuthoringEntityType,
+  isAuthoringPslBlockDescriptor,
+} from '@prisma-next/framework-components/authoring';
+import type { CodecLookup } from '@prisma-next/framework-components/codec';
 import type { ExtensionPackRef, TargetPackRef } from '@prisma-next/framework-components/components';
 import type {
   ControlMutationDefaultRegistry,
@@ -24,25 +29,24 @@ import type {
   MutationDefaultGeneratorDescriptor,
 } from '@prisma-next/framework-components/control';
 import type { Namespace } from '@prisma-next/framework-components/ir';
-import type {
-  ParsePslDocumentResult,
-  PslAttribute,
-  PslCompositeType,
-  PslEnum,
-  PslField,
-  PslModel,
-  PslNamedTypeDeclaration,
-  PslNamespace,
-} from '@prisma-next/psl-parser';
 import {
-  isPostgresEnumStorageEntry,
-  type PostgresEnumStorageEntry,
-  type SqlModelStorage,
-  type SqlNamespaceTablesInput,
-  type StorageTypeInstance,
-} from '@prisma-next/sql-contract/types';
+  type BlockSymbol,
+  type CompositeTypeSymbol,
+  type FieldSymbol,
+  keywordPslSpan,
+  type ModelSymbol,
+  type NamespaceSymbol,
+  nodePslSpan,
+  type ResolvedAttribute,
+  type ScalarSymbol,
+  type SymbolTable,
+  type TypeAliasSymbol,
+} from '@prisma-next/psl-parser';
+import type { SourceFile } from '@prisma-next/psl-parser/syntax';
+import type { SqlModelStorage, SqlNamespaceTablesInput } from '@prisma-next/sql-contract/types';
 import {
   buildSqlContractFromDefinition,
+  type EnumTypeHandle,
   type FieldNode,
   type ForeignKeyNode,
   type IndexNode,
@@ -51,9 +55,11 @@ import {
   type RelationNode,
   type UniqueConstraintNode,
 } from '@prisma-next/sql-contract-ts/contract-builder';
+import { invariant } from '@prisma-next/utils/assertions';
 import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
+
 import {
   findDuplicateFieldName,
   getAttribute,
@@ -63,7 +69,6 @@ import {
   parseAttributeFieldList,
   parseConstraintMapArgument,
   parseControlPolicyAttribute,
-  parseMapName,
   parseObjectLiteralStringMap,
   parseQuotedStringLiteral,
 } from './psl-attribute-parsing';
@@ -71,12 +76,8 @@ import type { ColumnDescriptor } from './psl-column-resolution';
 import {
   checkUncomposedNamespace,
   getAuthoringEntity,
-  instantiatePslTypeConstructor,
   reportUncomposedNamespace,
-  resolveDbNativeTypeAttribute,
   resolveFieldTypeDescriptor,
-  resolvePslTypeConstructorDescriptor,
-  toNamedTypeFieldDescriptor,
 } from './psl-column-resolution';
 import {
   buildModelMappings,
@@ -86,6 +87,7 @@ import {
   modelCoordinateKey,
   type ResolvedField,
 } from './psl-field-resolution';
+import { resolveNamedTypeDeclarations } from './psl-named-type-resolution';
 import {
   applyBackrelationCandidates,
   type FkRelationMetadata,
@@ -96,8 +98,12 @@ import {
   validateNavigationListFieldAttributes,
 } from './psl-relation-resolution';
 
+type NamedTypeSymbol = ScalarSymbol | TypeAliasSymbol;
+
 export interface InterpretPslDocumentToSqlContractInput {
-  readonly document: ParsePslDocumentResult;
+  readonly symbolTable: SymbolTable;
+  readonly sourceFile: SourceFile;
+  readonly sourceId: string;
   readonly target: TargetPackRef<'sql', string>;
   readonly scalarTypeDescriptors: ReadonlyMap<string, ColumnDescriptor>;
   readonly composedExtensionPacks?: readonly string[];
@@ -124,6 +130,8 @@ export interface InterpretPslDocumentToSqlContractInput {
    * `SqlUnboundNamespace` singleton.
    */
   readonly createNamespace?: (input: SqlNamespaceTablesInput) => Namespace;
+  readonly codecLookup?: CodecLookup;
+  readonly seedDiagnostics?: readonly ContractSourceDiagnostic[];
 }
 
 function buildComposedExtensionPackRefs(
@@ -152,27 +160,6 @@ function buildComposedExtensionPackRefs(
   );
 }
 
-function diagnosticDedupKey(diagnostic: ContractSourceDiagnostic): string {
-  const span = diagnostic.span;
-  const spanKey = span
-    ? `${span.start.offset}:${span.end.offset}:${span.start.line}:${span.end.line}`
-    : '';
-  return `${diagnostic.code}\u0000${diagnostic.sourceId}\u0000${spanKey}\u0000${diagnostic.message}`;
-}
-
-function dedupeDiagnostics(
-  diagnostics: readonly ContractSourceDiagnostic[],
-): ContractSourceDiagnostic[] {
-  const seen = new Map<string, ContractSourceDiagnostic>();
-  for (const diagnostic of diagnostics) {
-    const key = diagnosticDedupKey(diagnostic);
-    if (!seen.has(key)) {
-      seen.set(key, diagnostic);
-    }
-  }
-  return [...seen.values()];
-}
-
 function compareStrings(left: string, right: string): -1 | 0 | 1 {
   if (left < right) {
     return -1;
@@ -183,15 +170,6 @@ function compareStrings(left: string, right: string): -1 | 0 | 1 {
   return 0;
 }
 
-function mapParserDiagnostics(document: ParsePslDocumentResult): ContractSourceDiagnostic[] {
-  return document.diagnostics.map((diagnostic) => ({
-    code: diagnostic.code,
-    message: diagnostic.message,
-    sourceId: diagnostic.sourceId,
-    span: diagnostic.span,
-  }));
-}
-
 /**
  * Name of the framework-parser synthesised bucket for top-level
  * declarations. Re-declared here so the per-target dispatch does not
@@ -263,337 +241,113 @@ function resolveNamespaceIdForSqlTarget(input: {
 }
 
 function validateNamespaceBlocksForSqlTarget(input: {
-  readonly namespaces: readonly PslNamespace[];
+  readonly namespaces: readonly NamespaceSymbol[];
   readonly targetId: string;
   readonly sourceId: string;
+  readonly sourceFile: SourceFile;
   readonly diagnostics: ContractSourceDiagnostic[];
 }): void {
   if (input.targetId === 'sqlite') {
     for (const namespace of input.namespaces) {
-      if (namespace.name === UNSPECIFIED_PSL_NAMESPACE_NAME) {
-        continue;
-      }
       input.diagnostics.push({
         code: 'PSL_UNSUPPORTED_NAMESPACE_BLOCK',
         message: `SQLite does not support \`namespace ${namespace.name} { … }\` blocks (SQLite has no schema concept; declare models at the document top level instead).`,
         sourceId: input.sourceId,
-        span: namespace.span,
+        span: nodePslSpan(namespace.node.syntax, input.sourceFile),
       });
     }
     return;
   }
 
   if (input.targetId === 'postgres') {
-    const namedBlocks = input.namespaces.filter((ns) => ns.name !== UNSPECIFIED_PSL_NAMESPACE_NAME);
-    const hasUnbound = namedBlocks.some((ns) => ns.name === 'unbound');
-    const hasSibling = namedBlocks.some((ns) => ns.name !== 'unbound');
+    const hasUnbound = input.namespaces.some((ns) => ns.name === 'unbound');
+    const hasSibling = input.namespaces.some((ns) => ns.name !== 'unbound');
     if (hasUnbound && hasSibling) {
-      const unboundBlock = namedBlocks.find((ns) => ns.name === 'unbound');
+      const unboundBlock = input.namespaces.find((ns) => ns.name === 'unbound');
       input.diagnostics.push({
         code: 'PSL_RESERVED_NAMESPACE_NAME',
         message:
           'Namespace "unbound" is reserved for the late-binding sentinel mapping and cannot appear alongside other named namespace blocks. ' +
           'Use `namespace unbound { … }` alone (no sibling named namespaces) for late-binding multi-tenant contracts.',
         sourceId: input.sourceId,
-        ...ifDefined('span', unboundBlock?.span),
+        ...(unboundBlock !== undefined
+          ? { span: nodePslSpan(unboundBlock.node.syntax, input.sourceFile) }
+          : {}),
       });
     }
   }
 }
 
 interface ProcessEnumDeclarationsInput {
-  readonly enums: readonly PslEnum[];
+  readonly enumBlocks: readonly PslExtensionBlock[];
   readonly sourceId: string;
-  readonly enumEntityDescriptor: AuthoringEntityTypeDescriptor | undefined;
+  readonly authoringContributions: AuthoringContributions | undefined;
   readonly entityContext: AuthoringEntityContext;
   readonly diagnostics: ContractSourceDiagnostic[];
 }
 
 function processEnumDeclarations(input: ProcessEnumDeclarationsInput): {
-  readonly storageTypes: Record<string, StorageTypeInstance | PostgresEnumStorageEntry>;
+  readonly enumHandles: Record<string, EnumTypeHandle>;
   readonly enumTypeDescriptors: Map<string, ColumnDescriptor>;
 } {
-  const storageTypes: Record<string, StorageTypeInstance | PostgresEnumStorageEntry> = {};
+  const enumHandles: Record<string, EnumTypeHandle> = {};
   const enumTypeDescriptors = new Map<string, ColumnDescriptor>();
 
-  if (input.enums.length === 0) {
-    return { storageTypes, enumTypeDescriptors };
+  if (input.enumBlocks.length === 0) {
+    return { enumHandles, enumTypeDescriptors };
   }
 
-  if (!input.enumEntityDescriptor) {
-    // The PSL `enum X { … }` syntax only resolves when the active
-    // pack composition contributes an `enum` entity-type factory (the
-    // Postgres target pack does so today via
-    // `authoring.entityTypes.enum`). Without the contribution we
-    // surface a diagnostic per declaration rather than silently
-    // swallowing the syntax.
-    for (const enumDeclaration of input.enums) {
+  const enumDescriptor = getAuthoringEntity(input.authoringContributions, ['enum']);
+  if (!enumDescriptor) {
+    for (const decl of input.enumBlocks) {
       input.diagnostics.push({
-        code: 'PSL_UNSUPPORTED_NAMED_TYPE_BASE',
-        message: `Enum "${enumDeclaration.name}" requires the active target pack to contribute an enum entity-type helper`,
+        code: 'PSL_ENUM_MISSING_FACTORY',
+        message: `enum "${decl.name}" requires an "enum" entityType factory in the active authoring contributions`,
         sourceId: input.sourceId,
-        span: enumDeclaration.span,
+        span: decl.span,
       });
     }
-    return { storageTypes, enumTypeDescriptors };
+    return { enumHandles, enumTypeDescriptors };
   }
 
-  for (const enumDeclaration of input.enums) {
-    const nativeType = parseMapName({
-      attribute: getAttribute(enumDeclaration.attributes, 'map'),
-      defaultValue: enumDeclaration.name,
-      sourceId: input.sourceId,
-      diagnostics: input.diagnostics,
-      entityLabel: `Enum "${enumDeclaration.name}"`,
-      span: enumDeclaration.span,
-    });
-    const values = enumDeclaration.values.map((value) => value.name);
-    const constructed = instantiateAuthoringEntityType(
+  for (const decl of input.enumBlocks) {
+    const handle = instantiateAuthoringEntityType(
       'enum',
-      input.enumEntityDescriptor,
-      [{ name: enumDeclaration.name, nativeType, values }],
+      enumDescriptor,
+      [decl],
       input.entityContext,
     );
-    if (!isPostgresEnumStorageEntry(constructed)) {
-      input.diagnostics.push({
-        code: 'PSL_UNSUPPORTED_NAMED_TYPE_BASE',
-        message: `Enum "${enumDeclaration.name}": enum entity-type factory must return a PostgresEnumStorageEntry-shaped value (kind: 'postgres-enum')`,
-        sourceId: input.sourceId,
-        span: enumDeclaration.span,
-      });
-      continue;
-    }
-    const descriptor: ColumnDescriptor = {
-      codecId: constructed.codecId,
-      nativeType: constructed.nativeType,
-      typeRef: enumDeclaration.name,
-    };
-    enumTypeDescriptors.set(enumDeclaration.name, descriptor);
-    storageTypes[enumDeclaration.name] = constructed;
-  }
-
-  return { storageTypes, enumTypeDescriptors };
-}
-
-interface ResolveNamedTypeDeclarationsInput {
-  readonly declarations: readonly PslNamedTypeDeclaration[];
-  readonly sourceId: string;
-  readonly enumTypeDescriptors: ReadonlyMap<string, ColumnDescriptor>;
-  readonly scalarTypeDescriptors: ReadonlyMap<string, ColumnDescriptor>;
-  readonly composedExtensions: ReadonlySet<string>;
-  readonly familyId: string;
-  readonly targetId: string;
-  readonly authoringContributions: AuthoringContributions | undefined;
-  readonly diagnostics: ContractSourceDiagnostic[];
-}
-
-function validateNamedTypeAttributes(input: {
-  readonly declaration: PslNamedTypeDeclaration;
-  readonly sourceId: string;
-  readonly diagnostics: ContractSourceDiagnostic[];
-  readonly composedExtensions: ReadonlySet<string>;
-  readonly authoringContributions: AuthoringContributions | undefined;
-  readonly allowDbNativeType: boolean;
-  readonly familyId: string;
-  readonly targetId: string;
-}): {
-  readonly dbNativeTypeAttribute: PslAttribute | undefined;
-  readonly hasUnsupportedNamedTypeAttribute: boolean;
-} {
-  const dbNativeTypeAttributes = input.allowDbNativeType
-    ? input.declaration.attributes.filter((attribute) => attribute.name.startsWith('db.'))
-    : [];
-  const [dbNativeTypeAttribute, ...extraDbNativeTypeAttributes] = dbNativeTypeAttributes;
-  let hasUnsupportedNamedTypeAttribute = false;
-
-  for (const extra of extraDbNativeTypeAttributes) {
-    input.diagnostics.push({
-      code: 'PSL_INVALID_ATTRIBUTE_ARGUMENT',
-      message: `Named type "${input.declaration.name}" can declare at most one @db.* attribute`,
-      sourceId: input.sourceId,
-      span: extra.span,
-    });
-    hasUnsupportedNamedTypeAttribute = true;
-  }
 
-  for (const attribute of input.declaration.attributes) {
-    if (input.allowDbNativeType && attribute.name.startsWith('db.')) {
-      continue;
-    }
-
-    const uncomposedNamespace = checkUncomposedNamespace(attribute.name, input.composedExtensions, {
-      familyId: input.familyId,
-      targetId: input.targetId,
-      authoringContributions: input.authoringContributions,
-    });
-    if (uncomposedNamespace) {
-      reportUncomposedNamespace({
-        subjectLabel: `Attribute "@${attribute.name}"`,
-        namespace: uncomposedNamespace,
-        sourceId: input.sourceId,
-        span: attribute.span,
-        diagnostics: input.diagnostics,
-      });
-      hasUnsupportedNamedTypeAttribute = true;
-      continue;
-    }
+    if (handle === undefined || handle === null) continue;
 
-    input.diagnostics.push({
-      code: 'PSL_UNSUPPORTED_NAMED_TYPE_ATTRIBUTE',
-      message: `Named type "${input.declaration.name}" uses unsupported attribute "${attribute.name}"`,
-      sourceId: input.sourceId,
-      span: attribute.span,
+    const enumHandle = blindCast<EnumTypeHandle, 'enum factory returns EnumTypeHandle'>(handle);
+    enumHandles[decl.name] = enumHandle;
+    enumTypeDescriptors.set(decl.name, {
+      codecId: enumHandle.codecId,
+      nativeType: enumHandle.nativeType,
     });
-    hasUnsupportedNamedTypeAttribute = true;
   }
 
-  return { dbNativeTypeAttribute, hasUnsupportedNamedTypeAttribute };
+  return { enumHandles, enumTypeDescriptors };
 }
 
-function resolveNamedTypeDeclarations(input: ResolveNamedTypeDeclarationsInput): {
-  readonly storageTypes: Record<string, StorageTypeInstance | PostgresEnumStorageEntry>;
-  readonly namedTypeDescriptors: Map<string, ColumnDescriptor>;
-} {
-  const storageTypes: Record<string, StorageTypeInstance | PostgresEnumStorageEntry> = {};
-  const namedTypeDescriptors = new Map<string, ColumnDescriptor>();
-
-  for (const declaration of input.declarations) {
-    if (declaration.typeConstructor) {
-      const { hasUnsupportedNamedTypeAttribute } = validateNamedTypeAttributes({
-        declaration,
-        sourceId: input.sourceId,
-        diagnostics: input.diagnostics,
-        composedExtensions: input.composedExtensions,
-        authoringContributions: input.authoringContributions,
-        allowDbNativeType: false,
-        familyId: input.familyId,
-        targetId: input.targetId,
-      });
-      if (hasUnsupportedNamedTypeAttribute) {
-        continue;
-      }
-
-      const helperPath = declaration.typeConstructor.path.join('.');
-      const typeConstructor = resolvePslTypeConstructorDescriptor({
-        call: declaration.typeConstructor,
-        authoringContributions: input.authoringContributions,
-        composedExtensions: input.composedExtensions,
-        familyId: input.familyId,
-        targetId: input.targetId,
-        diagnostics: input.diagnostics,
-        sourceId: input.sourceId,
-        unsupportedCode: 'PSL_UNSUPPORTED_NAMED_TYPE_CONSTRUCTOR',
-        unsupportedMessage: `Named type "${declaration.name}" references unsupported constructor "${helperPath}"`,
-      });
-      if (!typeConstructor) {
-        continue;
-      }
-
-      const storageType = instantiatePslTypeConstructor({
-        call: declaration.typeConstructor,
-        descriptor: typeConstructor,
-        diagnostics: input.diagnostics,
-        sourceId: input.sourceId,
-        entityLabel: `Named type "${declaration.name}"`,
-      });
-      if (!storageType) {
-        continue;
-      }
-
-      namedTypeDescriptors.set(
-        declaration.name,
-        toNamedTypeFieldDescriptor(declaration.name, storageType),
-      );
-      storageTypes[declaration.name] = {
-        kind: 'codec-instance',
-        codecId: storageType.codecId,
-        nativeType: storageType.nativeType,
-        typeParams: storageType.typeParams ?? {},
-      };
-      continue;
-    }
-
-    // Parser invariant: when typeConstructor is absent, baseType is defined.
-    // The check below narrows `baseType` for TypeScript and guards against a
-    // parser regression; it is unreachable under a correct parser.
-    if (declaration.baseType === undefined) {
-      input.diagnostics.push({
-        code: 'PSL_UNSUPPORTED_NAMED_TYPE_BASE',
-        message: `Named type "${declaration.name}" must declare a base type or constructor`,
-        sourceId: input.sourceId,
-        span: declaration.span,
-      });
-      continue;
-    }
-    const { baseType } = declaration;
-    const baseDescriptor =
-      input.enumTypeDescriptors.get(baseType) ?? input.scalarTypeDescriptors.get(baseType);
-    if (!baseDescriptor) {
-      input.diagnostics.push({
-        code: 'PSL_UNSUPPORTED_NAMED_TYPE_BASE',
-        message: `Named type "${declaration.name}" references unsupported base type "${baseType}"`,
-        sourceId: input.sourceId,
-        span: declaration.span,
-      });
-      continue;
-    }
-
-    const { dbNativeTypeAttribute, hasUnsupportedNamedTypeAttribute } = validateNamedTypeAttributes(
-      {
-        declaration,
-        sourceId: input.sourceId,
-        diagnostics: input.diagnostics,
-        composedExtensions: input.composedExtensions,
-        authoringContributions: input.authoringContributions,
-        allowDbNativeType: true,
-        familyId: input.familyId,
-        targetId: input.targetId,
-      },
-    );
-    if (hasUnsupportedNamedTypeAttribute) {
-      continue;
-    }
-
-    if (dbNativeTypeAttribute) {
-      const descriptor = resolveDbNativeTypeAttribute({
-        attribute: dbNativeTypeAttribute,
-        baseType,
-        baseDescriptor,
-        diagnostics: input.diagnostics,
-        sourceId: input.sourceId,
-        entityLabel: `Named type "${declaration.name}"`,
-      });
-      if (!descriptor) {
-        continue;
-      }
-      namedTypeDescriptors.set(
-        declaration.name,
-        toNamedTypeFieldDescriptor(declaration.name, descriptor),
-      );
-      storageTypes[declaration.name] = {
-        kind: 'codec-instance',
-        codecId: descriptor.codecId,
-        nativeType: descriptor.nativeType,
-        typeParams: descriptor.typeParams ?? {},
-      };
-      continue;
+/** Generic top-level blocks are supported only when a composed descriptor claims their keyword. */
+function composedBlockKeywords(
+  authoringContributions: AuthoringContributions | undefined,
+): ReadonlySet<string> {
+  const keywords = new Set<string>();
+  const descriptors: AuthoringPslBlockDescriptorNamespace =
+    authoringContributions?.pslBlockDescriptors ?? {};
+  for (const [keyword, value] of Object.entries(descriptors)) {
+    if (isAuthoringPslBlockDescriptor(value)) {
+      keywords.add(keyword);
     }
-
-    const descriptor = toNamedTypeFieldDescriptor(declaration.name, baseDescriptor);
-    namedTypeDescriptors.set(declaration.name, descriptor);
-    storageTypes[declaration.name] = {
-      kind: 'codec-instance',
-      codecId: baseDescriptor.codecId,
-      nativeType: baseDescriptor.nativeType,
-      typeParams: {},
-    };
   }
-
-  return { storageTypes, namedTypeDescriptors };
+  return keywords;
 }
 
 interface BuildModelNodeInput {
-  readonly model: PslModel;
+  readonly model: ModelSymbol;
   readonly mapping: ModelNameMapping;
   readonly modelMappings: ReadonlyMap<string, ModelNameMapping>;
   /**
@@ -619,6 +373,7 @@ interface BuildModelNodeInput {
   readonly diagnostics: ContractSourceDiagnostic[];
   /** Resolved namespace id keyed by model name — used to stamp the target namespace on FKs. */
   readonly modelNamespaceIds: ReadonlyMap<string, string>;
+  readonly enumHandles?: ReadonlyMap<string, EnumTypeHandle>;
 }
 
 interface BuildModelNodeResult {
@@ -650,6 +405,7 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
     diagnostics,
     sourceId,
     scalarTypeDescriptors: input.scalarTypeDescriptors,
+    ...ifDefined('enumHandles', input.enumHandles),
   });
 
   const inlineIdFields = resolvedFields.filter((field) => field.isId);
@@ -674,7 +430,7 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
   let controlPolicy: ControlPolicy | undefined;
 
   const resultBackrelationCandidates: ModelBackrelationCandidate[] = [];
-  for (const field of model.fields) {
+  for (const field of Object.values(model.fields)) {
     if (!field.list || !input.modelNames.has(field.typeName)) {
       continue;
     }
@@ -734,12 +490,12 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
     });
   }
 
-  const relationAttributes = model.fields
+  const relationAttributes = Object.values(model.fields)
     .map((field) => ({
       field,
       relation: getAttribute(field.attributes, 'relation'),
     }))
-    .filter((entry): entry is { field: PslField; relation: PslAttribute } =>
+    .filter((entry): entry is { field: FieldSymbol; relation: ResolvedAttribute } =>
       Boolean(entry.relation),
     );
   const uniqueConstraints: UniqueConstraintNode[] = resolvedFields
@@ -820,9 +576,7 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
         });
         continue;
       }
-      const nullableFieldName = fieldNames.find(
-        (name) => model.fields.find((f) => f.name === name)?.optional === true,
-      );
+      const nullableFieldName = fieldNames.find((name) => model.fields[name]?.optional === true);
       if (nullableFieldName !== undefined) {
         diagnostics.push({
           code: 'PSL_INVALID_ATTRIBUTE_ARGUMENT',
@@ -1307,6 +1061,7 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
       declaringModelName: model.name,
       declaringFieldName: relationAttribute.field.name,
       declaringTableName: tableName,
+      ...ifDefined('declaringNamespaceId', input.modelNamespaceIds.get(model.name)),
       targetModelName: targetMapping.model.name,
       targetTableName: targetMapping.tableName,
       ...ifDefined('targetNamespaceId', targetNamespaceId),
@@ -1320,14 +1075,18 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
     modelNode: {
       modelName: model.name,
       tableName,
-      fields: resolvedFields.map((resolvedField) => ({
-        fieldName: resolvedField.field.name,
-        columnName: resolvedField.columnName,
-        descriptor: resolvedField.descriptor,
-        nullable: resolvedField.field.optional,
-        ...ifDefined('default', resolvedField.defaultValue),
-        ...ifDefined('executionDefaults', resolvedField.executionDefaults),
-      })),
+      fields: resolvedFields.map((resolvedField) => {
+        const enumHandle = input.enumHandles?.get(resolvedField.field.typeName);
+        return {
+          fieldName: resolvedField.field.name,
+          columnName: resolvedField.columnName,
+          descriptor: resolvedField.descriptor,
+          nullable: resolvedField.nullable,
+          ...ifDefined('default', resolvedField.defaultValue),
+          ...ifDefined('executionDefaults', resolvedField.executionDefaults),
+          ...ifDefined('enumTypeHandle', enumHandle),
+        };
+      }),
       ...ifDefined('id', primaryKey),
       ...(uniqueConstraints.length > 0 ? { uniques: uniqueConstraints } : {}),
       ...(indexNodes.length > 0 ? { indexes: indexNodes } : {}),
@@ -1342,7 +1101,7 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
 }
 
 interface BuildValueObjectsInput {
-  readonly compositeTypes: readonly PslCompositeType[];
+  readonly compositeTypes: readonly CompositeTypeSymbol[];
   readonly enumTypeDescriptors: ReadonlyMap<string, ColumnDescriptor>;
   readonly namedTypeDescriptors: ReadonlyMap<string, ColumnDescriptor>;
   readonly scalarTypeDescriptors: ReadonlyMap<string, ColumnDescriptor>;
@@ -1372,7 +1131,7 @@ function buildValueObjects(input: BuildValueObjectsInput): Record<string, Contra
 
   for (const compositeType of compositeTypes) {
     const fields: Record<string, ContractField> = {};
-    for (const field of compositeType.fields) {
+    for (const field of Object.values(compositeType.fields)) {
       if (compositeTypeNames.has(field.typeName)) {
         const result: ContractField = {
           type: { kind: 'valueObject', name: field.typeName },
@@ -1468,7 +1227,7 @@ type BaseDeclaration = {
 };
 
 function collectPolymorphismDeclarations(
-  models: readonly PslModel[],
+  models: readonly ModelSymbol[],
   sourceId: string,
   diagnostics: ContractSourceDiagnostic[],
 ): {
@@ -1491,7 +1250,7 @@ function collectPolymorphismDeclarations(
           });
           continue;
         }
-        const discField = model.fields.find((f) => f.name === fieldName);
+        const discField = model.fields[fieldName];
         if (discField && discField.typeName !== 'String') {
           diagnostics.push({
             code: 'PSL_INVALID_ATTRIBUTE_ARGUMENT',
@@ -1868,7 +1627,7 @@ function stripStorageOnlyDomainFields(
 export function interpretPslDocumentToSqlContract(
   input: InterpretPslDocumentToSqlContractInput,
 ): Result<Contract, ContractSourceDiagnostics> {
-  const sourceId = input.document.ast.sourceId;
+  const sourceId = input.sourceId;
   if (!input.target) {
     return notOk({
       summary: 'PSL to SQL contract interpretation failed',
@@ -1894,65 +1653,57 @@ export function interpretPslDocumentToSqlContract(
     });
   }
 
-  const diagnostics: ContractSourceDiagnostic[] = mapParserDiagnostics(input.document);
+  const { topLevel } = input.symbolTable;
+  const sourceFile = input.sourceFile;
+  const namespaceSymbols = Object.values(topLevel.namespaces);
+  const diagnostics: ContractSourceDiagnostic[] = [...(input.seedDiagnostics ?? [])];
   validateNamespaceBlocksForSqlTarget({
-    namespaces: input.document.ast.namespaces,
+    namespaces: namespaceSymbols,
     targetId: input.target.targetId,
     sourceId,
+    sourceFile,
     diagnostics,
   });
-  // Per-target namespace resolution: walk each AST bucket once,
-  // recording every model's resolved `namespaceId` for later threading
-  // into the `ModelNode` build. The resolution rules are target-local
-  // (see `resolveNamespaceIdForSqlTarget`); the flattened model list
-  // remains the input to the rest of the interpreter so non-namespace
-  // concerns stay structurally identical to before.
-  const models: PslModel[] = [];
+  const models: ModelSymbol[] = [];
   const modelEntries: ModelNamespaceEntry[] = [];
   const modelNamespaceIds = new Map<string, string>();
-  for (const namespace of input.document.ast.namespaces) {
+  const compositeTypes: CompositeTypeSymbol[] = [];
+
+  const collectScope = (
+    bucketName: string,
+    scopeModels: Iterable<ModelSymbol>,
+    scopeCompositeTypes: Iterable<CompositeTypeSymbol>,
+  ): void => {
     const resolvedNamespaceId = resolveNamespaceIdForSqlTarget({
-      bucketName: namespace.name,
+      bucketName,
       targetId: input.target.targetId,
     });
-    for (const model of namespace.models) {
+    for (const model of scopeModels) {
       models.push(model);
       modelEntries.push({ model, namespaceId: resolvedNamespaceId });
       if (resolvedNamespaceId !== undefined) {
         modelNamespaceIds.set(model.name, resolvedNamespaceId);
       }
     }
-  }
-  const defaultNamespaceId = input.target.defaultNamespaceId;
-  // Top-level enums (the __unspecified__ bucket) route to `storageTypes`;
-  // enums inside a named namespace block route to `namespaceTypes[nsId]`.
-  const topLevelEnums = input.document.ast.namespaces
-    .filter((ns) => ns.name === UNSPECIFIED_PSL_NAMESPACE_NAME)
-    .flatMap((ns) => ns.enums);
-  const namedNamespaceEnumsByNsId = new Map<string, readonly PslEnum[]>();
-  for (const ns of input.document.ast.namespaces) {
-    if (ns.name === UNSPECIFIED_PSL_NAMESPACE_NAME || ns.enums.length === 0) {
-      continue;
+    for (const compositeType of scopeCompositeTypes) {
+      compositeTypes.push(compositeType);
     }
-    const resolvedId = resolveNamespaceIdForSqlTarget({
-      bucketName: ns.name,
-      targetId: input.target.targetId,
-    });
-    if (resolvedId === undefined) {
-      continue;
-    }
-    // Read-then-merge so that any future change to the PSL parser (or to
-    // `resolveNamespaceIdForSqlTarget`) that produces two AST entries
-    // resolving to the same `resolvedId` would accumulate their enums
-    // rather than silently dropping the earlier set. Today the parser
-    // already merges duplicate `namespace <name> { … }` blocks into a
-    // single AST entry per name, so this loop sees one `ns` per
-    // resolvedId and the merge degrades to a plain set.
-    const existing = namedNamespaceEnumsByNsId.get(resolvedId) ?? [];
-    namedNamespaceEnumsByNsId.set(resolvedId, [...existing, ...ns.enums]);
+  };
+
+  collectScope(
+    UNSPECIFIED_PSL_NAMESPACE_NAME,
+    Object.values(topLevel.models),
+    Object.values(topLevel.compositeTypes),
+  );
+  for (const namespace of namespaceSymbols) {
+    collectScope(
+      namespace.name,
+      Object.values(namespace.models),
+      Object.values(namespace.compositeTypes),
+    );
   }
+  const defaultNamespaceId = input.target.defaultNamespaceId;
 
-  const compositeTypes = input.document.ast.namespaces.flatMap((ns) => ns.compositeTypes);
   const modelNames = new Set(models.map((model) => model.name));
   const compositeTypeNames = new Set(compositeTypes.map((ct) => ct.name));
   const composedExtensions = new Set(input.composedExtensionPacks ?? []);
@@ -1966,48 +1717,76 @@ export function interpretPslDocumentToSqlContract(
     generatorDescriptorById.set(descriptor.id, descriptor);
   }
 
-  const enumEntityDescriptor = getAuthoringEntity(input.authoringContributions, ['enum']);
-  const enumEntityContext = {
-    family: input.target.familyId,
-    target: input.target.targetId,
+  const isEnumBlock = (block: BlockSymbol): boolean => block.keyword === 'enum';
+  const legitimateBlockKeywords = composedBlockKeywords(input.authoringContributions);
+  const reportUnsupportedTopLevelBlock = (block: BlockSymbol): void => {
+    diagnostics.push({
+      code: 'PSL_UNSUPPORTED_TOP_LEVEL_BLOCK',
+      message: `Unsupported top-level block "${block.keyword}"`,
+      sourceId,
+      span: keywordPslSpan(block.node.syntax, block.keyword, sourceFile),
+    });
   };
 
+  const topLevelEnums = Object.values(topLevel.blocks)
+    .filter((block) => {
+      if (!legitimateBlockKeywords.has(block.keyword)) {
+        reportUnsupportedTopLevelBlock(block);
+        return false;
+      }
+      return isEnumBlock(block);
+    })
+    .map((block) => block.block);
+  for (const namespace of namespaceSymbols) {
+    for (const block of Object.values(namespace.blocks)) {
+      if (isEnumBlock(block)) {
+        diagnostics.push({
+          code: 'PSL_ENUM_NAMESPACE_NOT_SUPPORTED',
+          message: `enum "${block.name}" inside namespace "${namespace.name}" is not supported; declare enum at the top level`,
+          sourceId,
+          span: nodePslSpan(block.node.syntax, sourceFile),
+        });
+        continue;
+      }
+      if (!legitimateBlockKeywords.has(block.keyword)) {
+        reportUnsupportedTopLevelBlock(block);
+      }
+    }
+  }
+
   const enumResult = processEnumDeclarations({
-    enums: topLevelEnums,
+    enumBlocks: topLevelEnums,
     sourceId,
-    enumEntityDescriptor,
-    entityContext: enumEntityContext,
+    authoringContributions: input.authoringContributions,
+    entityContext: {
+      family: input.target.familyId,
+      target: input.target.targetId,
+      ...ifDefined('codecLookup', input.codecLookup),
+      sourceId,
+      diagnostics: {
+        push: (d) => {
+          diagnostics.push(
+            blindCast<ContractSourceDiagnostic, 'sink diagnostics are span-compatible'>(d),
+          );
+        },
+      },
+    },
     diagnostics,
   });
 
-  // Process enums declared in named namespace blocks and collect them into
-  // `namespaceTypes` keyed by the resolved namespace id.
   const allEnumTypeDescriptors = new Map(enumResult.enumTypeDescriptors);
-  const namespaceEnumStorageTypes: Record<string, Record<string, PostgresEnumStorageEntry>> = {};
-  for (const [nsId, nsEnums] of namedNamespaceEnumsByNsId) {
-    const nsEnumResult = processEnumDeclarations({
-      enums: nsEnums,
-      sourceId,
-      enumEntityDescriptor,
-      entityContext: enumEntityContext,
-      diagnostics,
-    });
-    for (const [name, descriptor] of nsEnumResult.enumTypeDescriptors) {
-      allEnumTypeDescriptors.set(name, descriptor);
-    }
-    const nsEntries: Record<string, PostgresEnumStorageEntry> = {};
-    for (const [name, entry] of Object.entries(nsEnumResult.storageTypes)) {
-      if (isPostgresEnumStorageEntry(entry)) {
-        nsEntries[name] = entry;
-      }
-    }
-    if (Object.keys(nsEntries).length > 0) {
-      namespaceEnumStorageTypes[nsId] = nsEntries;
-    }
-  }
+
+  const validEnumHandles: Record<string, EnumTypeHandle> = { ...enumResult.enumHandles };
+
+  const enumHandlesByName = new Map(Object.entries(validEnumHandles));
+
+  const namedTypeSymbols: readonly NamedTypeSymbol[] = [
+    ...Object.values(topLevel.scalars),
+    ...Object.values(topLevel.typeAliases),
+  ];
 
   const namedTypeResult = resolveNamedTypeDeclarations({
-    declarations: input.document.ast.types?.declarations ?? [],
+    declarations: namedTypeSymbols,
     sourceId,
     enumTypeDescriptors: allEnumTypeDescriptors,
     scalarTypeDescriptors: input.scalarTypeDescriptors,
@@ -2018,7 +1797,7 @@ export function interpretPslDocumentToSqlContract(
     diagnostics,
   });
 
-  const storageTypes = { ...enumResult.storageTypes, ...namedTypeResult.storageTypes };
+  const storageTypes = { ...namedTypeResult.storageTypes };
 
   const modelMappingsByCoordinate = buildModelMappings(
     modelEntries,
@@ -2068,6 +1847,7 @@ export function interpretPslDocumentToSqlContract(
       sourceId,
       diagnostics,
       modelNamespaceIds,
+      ...(enumHandlesByName.size > 0 ? { enumHandles: enumHandlesByName } : {}),
     });
     modelNodes.push(
       namespaceId !== undefined ? { ...result.modelNode, namespaceId } : result.modelNode,
@@ -2081,10 +1861,20 @@ export function interpretPslDocumentToSqlContract(
     }
   }
 
-  const { modelRelations, fkRelationsByPair } = indexFkRelations({ fkRelationMetadata });
+  const { modelRelations, fkRelationsByPair, fkRelationsByDeclaringModel } = indexFkRelations({
+    fkRelationMetadata,
+  });
+  const modelIdColumns = new Map<string, readonly string[]>();
+  for (const modelNode of modelNodes) {
+    if (modelNode.id) {
+      modelIdColumns.set(modelNode.modelName, modelNode.id.columns);
+    }
+  }
   applyBackrelationCandidates({
     backrelationCandidates,
     fkRelationsByPair,
+    fkRelationsByDeclaringModel,
+    modelIdColumns,
     modelRelations,
     diagnostics,
     sourceId,
@@ -2144,7 +1934,7 @@ export function interpretPslDocumentToSqlContract(
   if (diagnostics.length > 0) {
     return notOk({
       summary: 'PSL to SQL contract interpretation failed',
-      diagnostics: dedupeDiagnostics(diagnostics),
+      diagnostics,
     });
   }
 
@@ -2159,9 +1949,7 @@ export function interpretPslDocumentToSqlContract(
       ),
     ),
     ...(Object.keys(storageTypes).length > 0 ? { storageTypes } : {}),
-    ...(Object.keys(namespaceEnumStorageTypes).length > 0
-      ? { namespaceTypes: namespaceEnumStorageTypes }
-      : {}),
+    ...(Object.keys(validEnumHandles).length > 0 ? { enums: validEnumHandles } : {}),
     ...ifDefined('createNamespace', input.createNamespace),
     models: stiColumnModelNodes.map((model) => ({
       ...model,
@@ -2175,16 +1963,16 @@ export function interpretPslDocumentToSqlContract(
     })),
   });
 
-  // Keyed by `(namespaceId, modelName)` coordinate so two models that share a
-  // bare name across namespaces stay distinct through the patch/polymorphism
-  // passes; only a genuine same-namespace duplicate is an error.
+  // Include namespace in patch keys so same bare model names across namespaces
+  // stay distinct; same-coordinate duplicates were already collapsed first-wins.
   const modelsForPatch: Record<string, ContractModel> = {};
   for (const [namespaceId, namespaceSlice] of Object.entries(contract.domain.namespaces)) {
     for (const [modelName, model] of Object.entries(namespaceSlice.models)) {
       const coordinate = modelCoordinateKey(namespaceId, modelName);
-      if (Object.hasOwn(modelsForPatch, coordinate)) {
-        throw new Error(`duplicate model "${namespaceId}.${modelName}" during PSL interpretation`);
-      }
+      invariant(
+        !Object.hasOwn(modelsForPatch, coordinate),
+        `symbol table guarantees coordinate uniqueness; duplicate model "${namespaceId}.${modelName}" reached interpretation`,
+      );
       modelsForPatch[coordinate] = model;
     }
   }
@@ -2233,6 +2021,7 @@ export function interpretPslDocumentToSqlContract(
                 patchedModels[modelCoordinateKey(namespaceId, modelName)] ?? model,
               ]),
             ),
+            ...(namespaceSlice.enum !== undefined ? { enum: namespaceSlice.enum } : {}),
             ...(namespaceSlice.valueObjects !== undefined
               ? { valueObjects: namespaceSlice.valueObjects }
               : {}),