@prisma-next/sql-contract-psl 0.12.0 → 0.13.0-dev.1

package/src/interpreter.ts

@@ -8,6 +8,7 @@ import type {
   ContractField,
   ContractModel,
   ContractValueObject,
+  ControlPolicy,
 } from '@prisma-next/contract/types';
 import { crossRef } from '@prisma-next/contract/types';
 import type {
@@ -23,7 +24,6 @@ import type {
   MutationDefaultGeneratorDescriptor,
 } from '@prisma-next/framework-components/control';
 import type { Namespace } from '@prisma-next/framework-components/ir';
-import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import type {
   ParsePslDocumentResult,
   PslAttribute,
@@ -37,17 +37,21 @@ import type {
 import {
   isPostgresEnumStorageEntry,
   type PostgresEnumStorageEntry,
+  type SqlModelStorage,
   type SqlNamespaceTablesInput,
   type StorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
 import {
   buildSqlContractFromDefinition,
+  type FieldNode,
   type ForeignKeyNode,
   type IndexNode,
   type ModelNode,
   type PrimaryKeyNode,
+  type RelationNode,
   type UniqueConstraintNode,
 } from '@prisma-next/sql-contract-ts/contract-builder';
+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 {
@@ -58,6 +62,7 @@ import {
   mapFieldNamesToColumns,
   parseAttributeFieldList,
   parseConstraintMapArgument,
+  parseControlPolicyAttribute,
   parseMapName,
   parseObjectLiteralStringMap,
   parseQuotedStringLiteral,
@@ -77,6 +82,8 @@ import {
   buildModelMappings,
   collectResolvedFields,
   type ModelNameMapping,
+  type ModelNamespaceEntry,
+  modelCoordinateKey,
   type ResolvedField,
 } from './psl-field-resolution';
 import {
@@ -97,6 +104,16 @@ export interface InterpretPslDocumentToSqlContractInput {
   readonly composedExtensionPackRefs?: readonly ExtensionPackRef<'sql', string>[];
   readonly controlMutationDefaults?: ControlMutationDefaults;
   readonly authoringContributions?: AuthoringContributions;
+  /**
+   * Extension contracts keyed by space ID. Required for cross-space FK
+   * resolution. A composed space must have an entry here; if the space ID
+   * appears in `composedExtensionPacks` but is absent from this map, the
+   * interpreter emits `PSL_UNKNOWN_CONTRACT_SPACE` and fails fast — there
+   * is no silent fallback. If a space's contract is present but the
+   * referenced model or namespace is not found in it, the interpreter
+   * emits `PSL_UNKNOWN_CROSS_SPACE_TARGET`.
+   */
+  readonly composedExtensionContracts: ReadonlyMap<string, Contract>;
   /**
    * Target-supplied `Namespace` factory threaded into
    * `buildSqlContractFromDefinition` for the contract's
@@ -229,10 +246,6 @@ const UNSPECIFIED_PSL_NAMESPACE_NAME = '__unspecified__';
  * slot empty (which means the late-bound default at the `StorageTable`
  * layer; emitted JSON omits the field).
  */
-function defaultSqlNamespaceIdForTarget(targetId: string): string {
-  return targetId === 'postgres' ? 'public' : UNBOUND_NAMESPACE_ID;
-}
-
 function resolveNamespaceIdForSqlTarget(input: {
   readonly bucketName: string;
   readonly targetId: string;
@@ -583,11 +596,19 @@ interface BuildModelNodeInput {
   readonly model: PslModel;
   readonly mapping: ModelNameMapping;
   readonly modelMappings: ReadonlyMap<string, ModelNameMapping>;
+  /**
+   * Model mappings keyed by `(namespaceId, modelName)` coordinate. Used to
+   * resolve a namespace-qualified relation target (`auth.User`) to the exact
+   * model even when the bare name is shared across namespaces.
+   */
+  readonly modelMappingsByCoordinate: ReadonlyMap<string, ModelNameMapping>;
   readonly modelNames: Set<string>;
   readonly compositeTypeNames: ReadonlySet<string>;
   readonly enumTypeDescriptors: Map<string, ColumnDescriptor>;
   readonly namedTypeDescriptors: Map<string, ColumnDescriptor>;
   readonly composedExtensions: Set<string>;
+  /** Extension contracts keyed by space ID for cross-space FK table-name resolution. */
+  readonly composedExtensionContracts: ReadonlyMap<string, Contract>;
   readonly familyId: string;
   readonly targetId: string;
   readonly authoringContributions: AuthoringContributions | undefined;
@@ -605,6 +626,8 @@ interface BuildModelNodeResult {
   readonly fkRelationMetadata: FkRelationMetadata[];
   readonly backrelationCandidates: ModelBackrelationCandidate[];
   readonly resolvedFields: readonly ResolvedField[];
+  /** Cross-contract-space relation nodes that bypass the local back-relation matching. */
+  readonly crossSpaceRelations: RelationNode[];
 }
 
 function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult {
@@ -647,6 +670,8 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
     : undefined;
   const hasInlinePrimaryKey = primaryKey !== undefined;
   let blockPrimaryKeyDeclared = false;
+  let controlPolicyDeclared = false;
+  let controlPolicy: ControlPolicy | undefined;
 
   const resultBackrelationCandidates: ModelBackrelationCandidate[] = [];
   for (const field of model.fields) {
@@ -733,6 +758,27 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
     if (modelAttribute.name === 'discriminator' || modelAttribute.name === 'base') {
       continue;
     }
+    if (modelAttribute.name === 'control') {
+      if (controlPolicyDeclared) {
+        diagnostics.push({
+          code: 'PSL_DUPLICATE_ATTRIBUTE',
+          message: `\`@@control\` declared more than once on model "${model.name}".`,
+          sourceId,
+          span: modelAttribute.span,
+        });
+        continue;
+      }
+      controlPolicyDeclared = true;
+      const parsed = parseControlPolicyAttribute({
+        attribute: modelAttribute,
+        sourceId,
+        diagnostics,
+      });
+      if (parsed !== undefined) {
+        controlPolicy = parsed;
+      }
+      continue;
+    }
     const attributeLabel = `Model "${model.name}" @@${modelAttribute.name}`;
     if (modelAttribute.name === 'id') {
       if (blockPrimaryKeyDeclared) {
@@ -937,13 +983,183 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
   }
 
   const resultFkRelationMetadata: FkRelationMetadata[] = [];
+  const resultCrossSpaceRelations: RelationNode[] = [];
   for (const relationAttribute of relationAttributes) {
+    const {
+      typeName: fieldTypeName,
+      typeNamespaceId: fieldTypeNamespaceId,
+      typeContractSpaceId: fieldTypeContractSpaceId,
+    } = relationAttribute.field;
+
     if (relationAttribute.field.list) {
+      // F-list: cross-space list relations are explicitly unsupported (Option B does not
+      // navigate, so a list target makes no sense to carry). Emit a diagnostic instead of
+      // silently dropping the field — the author needs to know the field was ignored.
+      if (fieldTypeContractSpaceId !== undefined) {
+        diagnostics.push({
+          code: 'PSL_UNSUPPORTED_CROSS_SPACE_LIST',
+          message: `Relation field "${model.name}.${relationAttribute.field.name}" is a cross-space list relation (type "${fieldTypeContractSpaceId}:${fieldTypeNamespaceId !== undefined ? `${fieldTypeNamespaceId}.` : ''}${fieldTypeName}[]"). Cross-space relations must be singular in v0.1 — list cross-space relations are not supported.`,
+          sourceId,
+          span: relationAttribute.field.span,
+        });
+      }
+      continue;
+    }
+
+    // Cross-contract-space relation: the target model lives in a different contract space
+    // identified by `typeContractSpaceId` (e.g. `supabase:auth.User`).
+    if (fieldTypeContractSpaceId !== undefined) {
+      // Fail fast if the space has no entry in composedExtensionContracts (AC5 PSL half).
+      const extContractForSpace = input.composedExtensionContracts.get(fieldTypeContractSpaceId);
+      if (extContractForSpace === undefined) {
+        diagnostics.push({
+          code: 'PSL_UNKNOWN_CONTRACT_SPACE',
+          message: `Relation field "${model.name}.${relationAttribute.field.name}" references contract space "${fieldTypeContractSpaceId}" which is not declared in extensionPacks. Add "${fieldTypeContractSpaceId}" to extensionPacks in prisma-next.config.ts.`,
+          sourceId,
+          span: relationAttribute.field.span,
+          data: { space: fieldTypeContractSpaceId, suggestedPack: fieldTypeContractSpaceId },
+        });
+        continue;
+      }
+
+      const parsedRelation = parseRelationAttribute({
+        attribute: relationAttribute.relation,
+        modelName: model.name,
+        fieldName: relationAttribute.field.name,
+        sourceId,
+        diagnostics,
+      });
+      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 localColumns = mapFieldNamesToColumns({
+        modelName: model.name,
+        fieldNames: parsedRelation.fields,
+        mapping,
+        sourceId,
+        diagnostics,
+        span: relationAttribute.relation.span,
+        entityLabel: `Relation field "${model.name}.${relationAttribute.field.name}"`,
+      });
+      if (!localColumns) {
+        continue;
+      }
+
+      // For cross-space references the `references` list provides field names from the remote
+      // model. Since the interpreter has no access to the extension contract, these field names
+      // are treated as column names directly (matching the TS builder's cross-space path).
+      const referencedColumns = parsedRelation.references;
+
+      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({
+            modelName: model.name,
+            fieldName: relationAttribute.field.name,
+            actionName: 'onDelete',
+            actionToken: parsedRelation.onDelete,
+            sourceId,
+            span: relationAttribute.field.span,
+            diagnostics,
+          })
+        : undefined;
+      const onUpdate = parsedRelation.onUpdate
+        ? normalizeReferentialAction({
+            modelName: model.name,
+            fieldName: relationAttribute.field.name,
+            actionName: 'onUpdate',
+            actionToken: parsedRelation.onUpdate,
+            sourceId,
+            span: relationAttribute.field.span,
+            diagnostics,
+          })
+        : undefined;
+
+      // Target namespace: use the colon-prefix namespace qualifier, or `__unbound__` when the
+      // no-namespace form is used (e.g. `supabase:User` → AC3).
+      const crossTargetNamespaceId = fieldTypeNamespaceId ?? '__unbound__';
+
+      // Target table name: resolved from the extension contract. The get() check above
+      // guarantees extContractForSpace is defined here; if the model or namespace is not
+      // found in it, emit PSL_UNKNOWN_CROSS_SPACE_TARGET (user typo).
+      const extContract = extContractForSpace;
+      const resolvedTable =
+        extContract.domain.namespaces[crossTargetNamespaceId]?.models[fieldTypeName]?.storage[
+          'table'
+        ];
+      if (typeof resolvedTable !== 'string') {
+        const availableModels =
+          Object.keys(extContract.domain.namespaces[crossTargetNamespaceId]?.models ?? {}).join(
+            ', ',
+          ) || '(none)';
+        diagnostics.push({
+          code: 'PSL_UNKNOWN_CROSS_SPACE_TARGET',
+          message: `Relation field "${model.name}.${relationAttribute.field.name}" references model "${fieldTypeName}" in namespace "${crossTargetNamespaceId}" of space "${fieldTypeContractSpaceId}", but that model was not found in the extension contract. Available models: ${availableModels}`,
+          sourceId,
+          span: relationAttribute.field.span,
+          data: {
+            space: fieldTypeContractSpaceId,
+            namespace: crossTargetNamespaceId,
+            model: fieldTypeName,
+          },
+        });
+        continue;
+      }
+      const crossTargetTableName = resolvedTable;
+
+      foreignKeyNodes.push({
+        columns: localColumns,
+        references: {
+          model: fieldTypeName,
+          table: crossTargetTableName,
+          columns: referencedColumns,
+          namespaceId: crossTargetNamespaceId,
+          spaceId: fieldTypeContractSpaceId,
+        },
+        ...ifDefined('name', parsedRelation.constraintName),
+        ...ifDefined('onDelete', onDelete),
+        ...ifDefined('onUpdate', onUpdate),
+      });
+
+      // Build the cross-space RelationNode directly (no local back-relation candidate).
+      // `buildSqlContractFromDefinition` recognises `spaceId` on a RelationNode and routes it
+      // through the cross-space domain-relation path (produces a non-navigable CrossReference).
+      resultCrossSpaceRelations.push({
+        fieldName: relationAttribute.field.name,
+        toModel: fieldTypeName,
+        toTable: crossTargetTableName,
+        cardinality: 'N:1',
+        spaceId: fieldTypeContractSpaceId,
+        namespaceId: crossTargetNamespaceId,
+        on: {
+          parentTable: tableName,
+          parentColumns: localColumns,
+          childTable: crossTargetTableName,
+          childColumns: referencedColumns,
+        },
+      });
+
       continue;
     }
 
-    const { typeName: fieldTypeName, typeNamespaceId: fieldTypeNamespaceId } =
-      relationAttribute.field;
     const qualifiedTypeName = fieldTypeNamespaceId
       ? `${fieldTypeNamespaceId}.${fieldTypeName}`
       : fieldTypeName;
@@ -958,19 +1174,23 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
       continue;
     }
 
-    if (fieldTypeNamespaceId !== undefined) {
-      const resolvedTargetNamespaceId = input.modelNamespaceIds.get(fieldTypeName);
-      const normalizedQualifier =
-        fieldTypeNamespaceId === 'unbound' ? '__unbound__' : fieldTypeNamespaceId;
-      if (resolvedTargetNamespaceId !== normalizedQualifier) {
-        diagnostics.push({
-          code: 'PSL_INVALID_RELATION_TARGET',
-          message: `Relation field "${model.name}.${relationAttribute.field.name}" references unknown model "${qualifiedTypeName}"`,
-          sourceId,
-          span: relationAttribute.field.span,
-        });
-        continue;
-      }
+    const normalizedQualifier =
+      fieldTypeNamespaceId === undefined
+        ? undefined
+        : fieldTypeNamespaceId === 'unbound'
+          ? '__unbound__'
+          : fieldTypeNamespaceId;
+    if (
+      normalizedQualifier !== undefined &&
+      !input.modelMappingsByCoordinate.has(modelCoordinateKey(normalizedQualifier, fieldTypeName))
+    ) {
+      diagnostics.push({
+        code: 'PSL_INVALID_RELATION_TARGET',
+        message: `Relation field "${model.name}.${relationAttribute.field.name}" references unknown model "${qualifiedTypeName}"`,
+        sourceId,
+        span: relationAttribute.field.span,
+      });
+      continue;
     }
 
     const parsedRelation = parseRelationAttribute({
@@ -993,7 +1213,12 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
       continue;
     }
 
-    const targetMapping = input.modelMappings.get(fieldTypeName);
+    const targetMapping =
+      normalizedQualifier !== undefined
+        ? input.modelMappingsByCoordinate.get(
+            modelCoordinateKey(normalizedQualifier, fieldTypeName),
+          )
+        : input.modelMappings.get(fieldTypeName);
     if (!targetMapping) {
       diagnostics.push({
         code: 'PSL_INVALID_RELATION_TARGET',
@@ -1061,7 +1286,10 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
         })
       : undefined;
 
-    const targetNamespaceId = input.modelNamespaceIds.get(targetMapping.model.name);
+    const targetNamespaceId =
+      normalizedQualifier !== undefined
+        ? normalizedQualifier
+        : input.modelNamespaceIds.get(targetMapping.model.name);
     foreignKeyNodes.push({
       columns: localColumns,
       references: {
@@ -1081,6 +1309,7 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
       declaringTableName: tableName,
       targetModelName: targetMapping.model.name,
       targetTableName: targetMapping.tableName,
+      ...ifDefined('targetNamespaceId', targetNamespaceId),
       ...ifDefined('relationName', parsedRelation.relationName),
       localColumns,
       referencedColumns,
@@ -1103,8 +1332,10 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
       ...(uniqueConstraints.length > 0 ? { uniques: uniqueConstraints } : {}),
       ...(indexNodes.length > 0 ? { indexes: indexNodes } : {}),
       ...(foreignKeyNodes.length > 0 ? { foreignKeys: foreignKeyNodes } : {}),
+      ...ifDefined('control', controlPolicy),
     },
     fkRelationMetadata: resultFkRelationMetadata,
+    crossSpaceRelations: resultCrossSpaceRelations,
     backrelationCandidates: resultBackrelationCandidates,
     resolvedFields,
   };
@@ -1310,12 +1541,31 @@ function resolvePolymorphism(
   modelNames: Set<string>,
   modelMappings: ReadonlyMap<string, ModelNameMapping>,
   modelNamespaceIds: ReadonlyMap<string, string>,
-  targetId: string,
+  defaultNamespaceId: string,
+  syntheticPkFieldsByVariant: ReadonlyMap<string, readonly string[]>,
+  stiBaseFieldsByBase: ReadonlyMap<string, readonly string[]>,
   sourceId: string,
   diagnostics: ContractSourceDiagnostic[],
 ): Record<string, ContractModel> {
   let patched = models;
 
+  const coordinateFor = (modelName: string): string =>
+    modelCoordinateKey(modelNamespaceIds.get(modelName) ?? defaultNamespaceId, modelName);
+
+  // STI variant columns were materialised onto the base storage table so the
+  // variants' `storage.fields` resolve. They are storage-only on the base — the
+  // domain field belongs to the variant — so strip them from the base model's
+  // domain + storage field maps (the table column, built upstream, stays).
+  for (const [baseName, fieldNames] of stiBaseFieldsByBase) {
+    const baseKey = coordinateFor(baseName);
+    const baseModel = patched[baseKey];
+    if (!baseModel || fieldNames.length === 0) continue;
+    patched = {
+      ...patched,
+      [baseKey]: stripStorageOnlyDomainFields(baseModel, fieldNames),
+    };
+  }
+
   for (const [modelName, decl] of discriminatorDeclarations) {
     if (baseDeclarations.has(modelName)) {
       diagnostics.push({
@@ -1327,7 +1577,7 @@ function resolvePolymorphism(
       continue;
     }
 
-    const model = patched[modelName];
+    const model = patched[coordinateFor(modelName)];
     if (!model) continue;
 
     if (!Object.hasOwn(model.fields, decl.fieldName)) {
@@ -1372,7 +1622,7 @@ function resolvePolymorphism(
 
     patched = {
       ...patched,
-      [modelName]: { ...model, discriminator: { field: decl.fieldName }, variants },
+      [coordinateFor(modelName)]: { ...model, discriminator: { field: decl.fieldName }, variants },
     };
   }
 
@@ -1401,7 +1651,7 @@ function resolvePolymorphism(
       continue;
     }
 
-    const variantModel = patched[variantName];
+    const variantModel = patched[coordinateFor(variantName)];
     if (!variantModel) continue;
 
     const baseMapping = modelMappings.get(baseDecl.baseName);
@@ -1410,22 +1660,211 @@ function resolvePolymorphism(
       variantMapping?.model.attributes.some((attr) => attr.name === 'map') ?? false;
     const resolvedTable = hasExplicitMap ? variantMapping?.tableName : baseMapping?.tableName;
 
+    const patchedVariant: ContractModel = {
+      ...variantModel,
+      base: crossRef(
+        baseDecl.baseName,
+        modelNamespaceIds.get(baseDecl.baseName) ?? defaultNamespaceId,
+      ),
+      ...(resolvedTable ? { storage: { ...variantModel.storage, table: resolvedTable } } : {}),
+    };
+
     patched = {
       ...patched,
-      [variantName]: {
-        ...variantModel,
-        base: crossRef(
-          baseDecl.baseName,
-          modelNamespaceIds.get(baseDecl.baseName) ?? defaultSqlNamespaceIdForTarget(targetId),
-        ),
-        ...(resolvedTable ? { storage: { ...variantModel.storage, table: resolvedTable } } : {}),
-      },
+      [coordinateFor(variantName)]: stripStorageOnlyDomainFields(
+        patchedVariant,
+        syntheticPkFieldsByVariant.get(variantName) ?? [],
+      ),
     };
   }
 
   return patched;
 }
 
+/**
+ * Multi-table-inheritance variants (`@@base` + their own `@@map`) live in a
+ * separate table from their base. The ORM joins that table to the base on the
+ * shared primary key (`base.id = variant.id`), so the variant storage table
+ * must carry the base PK column even though the variant domain model declares
+ * only its own fields. This enriches each MTI variant's `ModelNode` with that
+ * link column, a primary key on it, and a FK back to the base table.
+ *
+ * The link column is reported back per variant in `syntheticPkFieldsByVariant`
+ * so the domain-model patch can drop it again — keeping the variant's domain
+ * surface thin (its create/read inputs don't gain a redundant `id`) while the
+ * storage table stays joinable. Single-table-inheritance variants (no own
+ * table) are left untouched.
+ */
+function materializeMtiVariantStorageLinks(
+  modelNodes: readonly ModelNode[],
+  baseDeclarations: ReadonlyMap<string, BaseDeclaration>,
+  stiVariantNames: ReadonlySet<string>,
+): { modelNodes: ModelNode[]; syntheticPkFieldsByVariant: Map<string, readonly string[]> } {
+  const nodeByModel = new Map(modelNodes.map((node) => [node.modelName, node]));
+  const syntheticPkFieldsByVariant = new Map<string, readonly string[]>();
+
+  const enriched = modelNodes.map((node): ModelNode => {
+    const baseDecl = baseDeclarations.get(node.modelName);
+    if (!baseDecl) return node;
+    const baseNode = nodeByModel.get(baseDecl.baseName);
+    if (!baseNode) return node;
+    // Single-table inheritance (no own `@@map`) shares the base table; it gets
+    // its columns materialised onto the base instead (see
+    // {@link materializeStiVariantStorageColumns}), never a link column.
+    if (stiVariantNames.has(node.modelName)) return node;
+    const basePrimaryKey = baseNode.id;
+    if (!basePrimaryKey || basePrimaryKey.columns.length === 0) return node;
+
+    const existingColumns = new Set(node.fields.map((field) => field.columnName));
+    const linkFields: FieldNode[] = [];
+    for (const pkColumn of basePrimaryKey.columns) {
+      if (existingColumns.has(pkColumn)) continue;
+      const baseField = baseNode.fields.find(
+        (field): field is FieldNode => 'descriptor' in field && field.columnName === pkColumn,
+      );
+      if (!baseField) continue;
+      linkFields.push({
+        fieldName: baseField.fieldName,
+        columnName: pkColumn,
+        descriptor: baseField.descriptor,
+        nullable: false,
+      });
+    }
+    if (linkFields.length === 0) return node;
+
+    syntheticPkFieldsByVariant.set(
+      node.modelName,
+      linkFields.map((field) => field.fieldName),
+    );
+
+    const foreignKey: ForeignKeyNode = {
+      columns: basePrimaryKey.columns,
+      references: {
+        model: baseNode.modelName,
+        table: baseNode.tableName,
+        columns: basePrimaryKey.columns,
+        ...ifDefined('namespaceId', baseNode.namespaceId),
+      },
+      constraint: true,
+      // The link columns are the variant's own primary key, which already
+      // carries a unique index — a separate FK backing index would be redundant.
+      index: false,
+      // Deleting a base row must delete its variant extension row — classic
+      // multi-table-inheritance semantics.
+      onDelete: 'cascade',
+    };
+
+    return {
+      ...node,
+      fields: [...linkFields, ...node.fields],
+      id: { columns: basePrimaryKey.columns },
+      foreignKeys: [...(node.foreignKeys ?? []), foreignKey],
+    };
+  });
+
+  return { modelNodes: enriched, syntheticPkFieldsByVariant };
+}
+
+/**
+ * Single-table-inheritance variants (`@@base` with no own `@@map`) share the
+ * base table: `resolvePolymorphism` points the variant's `storage.table` at the
+ * base, and the ORM reads variant-declared fields straight off the base table.
+ * For that to validate and round-trip, the base storage table must physically
+ * carry every STI variant's declared columns. This enriches the base
+ * `ModelNode` with those columns.
+ *
+ * The materialised columns are always nullable in storage: the base table hosts
+ * every variant's rows, so a column a variant declares as required is still
+ * NULL on sibling-variant rows. The variant's domain field keeps its declared
+ * nullability — required-in-domain / nullable-in-storage is the intended STI
+ * shape.
+ *
+ * Collisions (two variants declaring the same column, or a variant column name
+ * clashing with a base column) are resolved skip-if-exists here, mirroring the
+ * MTI link guard; surfacing them as diagnostics is tracked separately
+ * (TML-2827).
+ */
+function materializeStiVariantStorageColumns(
+  modelNodes: readonly ModelNode[],
+  baseDeclarations: ReadonlyMap<string, BaseDeclaration>,
+  stiVariantNames: ReadonlySet<string>,
+): { modelNodes: ModelNode[]; stiBaseFieldsByBase: Map<string, readonly string[]> } {
+  if (stiVariantNames.size === 0) {
+    return { modelNodes: [...modelNodes], stiBaseFieldsByBase: new Map() };
+  }
+
+  const nodeByModel = new Map(modelNodes.map((node) => [node.modelName, node]));
+  type StiColumn = ModelNode['fields'][number];
+  const stiColumnsByBase = new Map<string, StiColumn[]>();
+
+  for (const variantName of stiVariantNames) {
+    const variantNode = nodeByModel.get(variantName);
+    const baseDecl = baseDeclarations.get(variantName);
+    if (!variantNode || !baseDecl) continue;
+    const baseNode = nodeByModel.get(baseDecl.baseName);
+    if (!baseNode) continue;
+
+    const baseColumns = new Set(baseNode.fields.map((field) => field.columnName));
+    const claimed = stiColumnsByBase.get(baseDecl.baseName) ?? [];
+    const claimedColumns = new Set(claimed.map((field) => field.columnName));
+
+    for (const field of variantNode.fields) {
+      if (baseColumns.has(field.columnName) || claimedColumns.has(field.columnName)) {
+        continue;
+      }
+      claimedColumns.add(field.columnName);
+      claimed.push({ ...field, nullable: true });
+    }
+    stiColumnsByBase.set(baseDecl.baseName, claimed);
+  }
+
+  // The materialised columns exist on the base STORAGE table so the variants'
+  // `storage.fields` resolve, but they are NOT base DOMAIN fields — `severity`
+  // belongs to `Bug`, not to `Task`. Report the materialised field names per
+  // base so the domain patch can strip them from the base model (the table
+  // column stays); this is the STI analogue of `syntheticPkFieldsByVariant`.
+  const stiBaseFieldsByBase = new Map<string, readonly string[]>();
+  for (const [baseName, columns] of stiColumnsByBase) {
+    stiBaseFieldsByBase.set(
+      baseName,
+      columns.map((field) => field.fieldName),
+    );
+  }
+
+  const enriched = modelNodes.map((node): ModelNode => {
+    // STI variant: contributes a domain model but no storage table of its own.
+    if (stiVariantNames.has(node.modelName)) {
+      return { ...node, sharesBaseTable: true };
+    }
+    const stiColumns = stiColumnsByBase.get(node.modelName);
+    if (!stiColumns || stiColumns.length === 0) return node;
+    return { ...node, fields: [...node.fields, ...stiColumns] };
+  });
+
+  return { modelNodes: enriched, stiBaseFieldsByBase };
+}
+
+/**
+ * Drop the storage-only link fields (added by
+ * {@link materializeMtiVariantStorageLinks}) from a variant's domain model, so
+ * the domain surface stays thin while the storage table keeps the link column.
+ */
+function stripStorageOnlyDomainFields(
+  model: ContractModel,
+  fieldNames: readonly string[],
+): ContractModel {
+  if (fieldNames.length === 0) return model;
+  const fields = { ...model.fields };
+  for (const name of fieldNames) delete fields[name];
+  const storage = blindCast<
+    SqlModelStorage,
+    'SQL interpreter domain models always carry SqlModelStorage'
+  >(model.storage);
+  const storageFields = { ...storage.fields };
+  for (const name of fieldNames) delete storageFields[name];
+  return { ...model, fields, storage: { ...storage, fields: storageFields } };
+}
+
 export function interpretPslDocumentToSqlContract(
   input: InterpretPslDocumentToSqlContractInput,
 ): Result<Contract, ContractSourceDiagnostics> {
@@ -1469,6 +1908,7 @@ export function interpretPslDocumentToSqlContract(
   // remains the input to the rest of the interpreter so non-namespace
   // concerns stay structurally identical to before.
   const models: PslModel[] = [];
+  const modelEntries: ModelNamespaceEntry[] = [];
   const modelNamespaceIds = new Map<string, string>();
   for (const namespace of input.document.ast.namespaces) {
     const resolvedNamespaceId = resolveNamespaceIdForSqlTarget({
@@ -1477,11 +1917,13 @@ export function interpretPslDocumentToSqlContract(
     });
     for (const model of namespace.models) {
       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
@@ -1514,6 +1956,8 @@ export function interpretPslDocumentToSqlContract(
   const modelNames = new Set(models.map((model) => model.name));
   const compositeTypeNames = new Set(compositeTypes.map((ct) => ct.name));
   const composedExtensions = new Set(input.composedExtensionPacks ?? []);
+  const composedExtensionContracts: ReadonlyMap<string, Contract> =
+    input.composedExtensionContracts;
   const defaultFunctionRegistry: ControlMutationDefaultRegistry =
     input.controlMutationDefaults?.defaultFunctionRegistry ?? new Map();
   const generatorDescriptors = input.controlMutationDefaults?.generatorDescriptors ?? [];
@@ -1576,14 +2020,31 @@ export function interpretPslDocumentToSqlContract(
 
   const storageTypes = { ...enumResult.storageTypes, ...namedTypeResult.storageTypes };
 
-  const modelMappings = buildModelMappings(models, diagnostics, sourceId);
+  const modelMappingsByCoordinate = buildModelMappings(
+    modelEntries,
+    defaultNamespaceId,
+    diagnostics,
+    sourceId,
+  );
+  // Bare-name view for unqualified relation targets and polymorphism, where
+  // resolution is by bare model name. When a bare name is shared across
+  // namespaces this collapses to the last entry; qualified relation targets
+  // and per-model lowering use the coordinate-keyed map above instead.
+  const modelMappings = new Map<string, ModelNameMapping>();
+  for (const mapping of modelMappingsByCoordinate.values()) {
+    modelMappings.set(mapping.model.name, mapping);
+  }
   const modelNodes: ModelNode[] = [];
   const fkRelationMetadata: FkRelationMetadata[] = [];
   const backrelationCandidates: ModelBackrelationCandidate[] = [];
   const modelResolvedFields = new Map<string, readonly ResolvedField[]>();
+  // Cross-space relation nodes keyed by declaring model name — merged into
+  // modelRelations after local back-relation matching so they bypass that step.
+  const crossSpaceRelationsByModel = new Map<string, RelationNode[]>();
 
-  for (const model of models) {
-    const mapping = modelMappings.get(model.name);
+  for (const { model, namespaceId } of modelEntries) {
+    const coordinate = modelCoordinateKey(namespaceId ?? defaultNamespaceId, model.name);
+    const mapping = modelMappingsByCoordinate.get(coordinate);
     if (!mapping) {
       continue;
     }
@@ -1591,11 +2052,13 @@ export function interpretPslDocumentToSqlContract(
       model,
       mapping,
       modelMappings,
+      modelMappingsByCoordinate,
       modelNames,
       compositeTypeNames,
       enumTypeDescriptors: allEnumTypeDescriptors,
       namedTypeDescriptors: namedTypeResult.namedTypeDescriptors,
       composedExtensions,
+      composedExtensionContracts,
       familyId: input.target.familyId,
       targetId: input.target.targetId,
       authoringContributions: input.authoringContributions,
@@ -1606,15 +2069,16 @@ export function interpretPslDocumentToSqlContract(
       diagnostics,
       modelNamespaceIds,
     });
-    const resolvedNamespaceId = modelNamespaceIds.get(model.name);
     modelNodes.push(
-      resolvedNamespaceId !== undefined
-        ? { ...result.modelNode, namespaceId: resolvedNamespaceId }
-        : result.modelNode,
+      namespaceId !== undefined ? { ...result.modelNode, namespaceId } : result.modelNode,
     );
     fkRelationMetadata.push(...result.fkRelationMetadata);
     backrelationCandidates.push(...result.backrelationCandidates);
-    modelResolvedFields.set(model.name, result.resolvedFields);
+    modelResolvedFields.set(coordinate, result.resolvedFields);
+    if (result.crossSpaceRelations.length > 0) {
+      const existing = crossSpaceRelationsByModel.get(model.name) ?? [];
+      crossSpaceRelationsByModel.set(model.name, [...existing, ...result.crossSpaceRelations]);
+    }
   }
 
   const { modelRelations, fkRelationsByPair } = indexFkRelations({ fkRelationMetadata });
@@ -1626,12 +2090,44 @@ export function interpretPslDocumentToSqlContract(
     sourceId,
   });
 
+  // Merge cross-space relations into modelRelations after local back-relation matching.
+  // Cross-space targets have no local back-relation candidates, so they bypass that step.
+  for (const [modelName, relations] of crossSpaceRelationsByModel) {
+    const existing = modelRelations.get(modelName);
+    if (existing) {
+      existing.push(...relations);
+    } else {
+      modelRelations.set(modelName, [...relations]);
+    }
+  }
+
   const { discriminatorDeclarations, baseDeclarations } = collectPolymorphismDeclarations(
     models,
     sourceId,
     diagnostics,
   );
 
+  // A variant with `@@base` but no own `@@map` is single-table inheritance:
+  // it shares the base table. (`@@map` ⇒ multi-table inheritance.) This is the
+  // authoritative STI/MTI signal — the variant's resolved table name is not,
+  // because a no-`@@map` STI variant still gets a `lowerFirst(name)` default
+  // table name that differs from the base before `resolvePolymorphism` rewrites
+  // it onto the base table.
+  const stiVariantNames = new Set<string>();
+  for (const variantName of baseDeclarations.keys()) {
+    const variantMapping = modelMappings.get(variantName);
+    const hasExplicitMap =
+      variantMapping?.model.attributes.some((attr) => attr.name === 'map') ?? false;
+    if (!hasExplicitMap) {
+      stiVariantNames.add(variantName);
+    }
+  }
+
+  const { modelNodes: mtiLinkedModelNodes, syntheticPkFieldsByVariant } =
+    materializeMtiVariantStorageLinks(modelNodes, baseDeclarations, stiVariantNames);
+  const { modelNodes: stiColumnModelNodes, stiBaseFieldsByBase } =
+    materializeStiVariantStorageColumns(mtiLinkedModelNodes, baseDeclarations, stiVariantNames);
+
   const valueObjects = buildValueObjects({
     compositeTypes,
     enumTypeDescriptors: allEnumTypeDescriptors,
@@ -1667,7 +2163,7 @@ export function interpretPslDocumentToSqlContract(
       ? { namespaceTypes: namespaceEnumStorageTypes }
       : {}),
     ...ifDefined('createNamespace', input.createNamespace),
-    models: modelNodes.map((model) => ({
+    models: stiColumnModelNodes.map((model) => ({
       ...model,
       ...(modelRelations.has(model.modelName)
         ? {
@@ -1679,15 +2175,17 @@ 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.
   const modelsForPatch: Record<string, ContractModel> = {};
-  for (const namespaceSlice of Object.values(contract.domain.namespaces)) {
+  for (const [namespaceId, namespaceSlice] of Object.entries(contract.domain.namespaces)) {
     for (const [modelName, model] of Object.entries(namespaceSlice.models)) {
-      if (Object.hasOwn(modelsForPatch, modelName)) {
-        throw new Error(
-          `duplicate model name "${modelName}" across domain namespaces during PSL interpretation`,
-        );
+      const coordinate = modelCoordinateKey(namespaceId, modelName);
+      if (Object.hasOwn(modelsForPatch, coordinate)) {
+        throw new Error(`duplicate model "${namespaceId}.${modelName}" during PSL interpretation`);
       }
-      modelsForPatch[modelName] = model as ContractModel;
+      modelsForPatch[coordinate] = model;
     }
   }
   let patchedModels = patchModelDomainFields(modelsForPatch, modelResolvedFields);
@@ -1700,7 +2198,9 @@ export function interpretPslDocumentToSqlContract(
     modelNames,
     modelMappings,
     modelNamespaceIds,
-    input.target.targetId,
+    input.target.defaultNamespaceId,
+    syntheticPkFieldsByVariant,
+    stiBaseFieldsByBase,
     sourceId,
     polyDiagnostics,
   );
@@ -1730,13 +2230,13 @@ export function interpretPslDocumentToSqlContract(
             models: Object.fromEntries(
               Object.entries(namespaceSlice.models).map(([modelName, model]) => [
                 modelName,
-                patchedModels[modelName] ?? model,
+                patchedModels[modelCoordinateKey(namespaceId, modelName)] ?? model,
               ]),
             ),
             ...(namespaceSlice.valueObjects !== undefined
               ? { valueObjects: namespaceSlice.valueObjects }
               : {}),
-            ...(namespaceId === defaultSqlNamespaceIdForTarget(input.target.targetId) &&
+            ...(namespaceId === input.target.defaultNamespaceId &&
             Object.keys(valueObjects).length > 0
               ? { valueObjects }
               : {}),