TML-2816: namespace-aware DSL/ORM surface — additive slice

packages/2-sql/1-core/contract/src/resolve-storage-table.ts

@@ -21,21 +21,41 @@ function tableInNamespace(
 }
 
 /**
- * Resolve a bare storage table name to its namespace coordinate and table IR by
- * scanning the contract's namespaces. For the single-namespace contracts in
- * scope the scan is exact; cross-namespace bare-name collisions are selected
- * explicitly (TML-2550).
+ * Resolve a bare storage table name to its namespace coordinate and table IR.
+ *
+ * When `namespaceId` is supplied, the table is resolved strictly within that
+ * namespace (no scan). When omitted, a bare name unique across namespaces
+ * resolves to its sole namespace; a bare name declared in more than one
+ * namespace throws a fail-fast diagnostic naming the candidate namespaces
+ * rather than silently selecting the first match.
  */
 export function resolveStorageTable(
   storage: SqlStorage,
   tableName: string,
+  namespaceId?: string,
 ): ResolvedStorageTable | undefined {
-  for (const namespaceId of Object.keys(storage.namespaces)) {
+  if (namespaceId !== undefined) {
     const table = tableInNamespace(storage.namespaces[namespaceId], tableName);
+    return table === undefined ? undefined : { namespaceId, table };
+  }
+
+  const matches: ResolvedStorageTable[] = [];
+  for (const candidateNamespaceId of Object.keys(storage.namespaces)) {
+    const table = tableInNamespace(storage.namespaces[candidateNamespaceId], tableName);
     if (table !== undefined) {
-      return { namespaceId, table };
+      matches.push({ namespaceId: candidateNamespaceId, table });
     }
   }
 
-  return undefined;
+  if (matches.length > 1) {
+    const candidates = matches
+      .map((match) => match.namespaceId)
+      .sort()
+      .join(', ');
+    throw new Error(
+      `Storage table "${tableName}" is ambiguous across namespaces [${candidates}]; qualify it with a namespace coordinate.`,
+    );
+  }
+
+  return matches[0];
 }

packages/2-sql/1-core/contract/test/resolve-storage-table.test.ts

@@ -17,6 +17,36 @@ function tableNamed(_name: string): StorageTable {
   });
 }
 
+function tableWithColumn(columnName: string): StorageTable {
+  return new StorageTable({
+    columns: {
+      id: { codecId: 'pg/int4@1', nativeType: 'int4', nullable: false },
+      [columnName]: { codecId: 'pg/text@1', nativeType: 'text', nullable: false },
+    },
+    primaryKey: { columns: ['id'] },
+    uniques: [],
+    indexes: [],
+    foreignKeys: [],
+  });
+}
+
+function twoNamespaceSameTableName(): {
+  storage: SqlStorage;
+  publicUsers: StorageTable;
+  authUsers: StorageTable;
+} {
+  const publicUsers = tableWithColumn('email_addr');
+  const authUsers = tableWithColumn('token_col');
+  const storage = new SqlStorage({
+    storageHash: 'sha256:test',
+    namespaces: {
+      public: buildSqlNamespace({ id: 'public', entries: { table: { users: publicUsers } } }),
+      auth: buildSqlNamespace({ id: 'auth', entries: { table: { users: authUsers } } }),
+    },
+  });
+  return { storage, publicUsers, authUsers };
+}
+
 describe('resolveStorageTable', () => {
   it('finds a table in whichever namespace declares it', () => {
     const authOnly = tableNamed('auth-only');
@@ -60,4 +90,31 @@ describe('resolveStorageTable', () => {
 
     expect(resolveStorageTable(storage, 'missing')).toBeUndefined();
   });
+
+  it('resolves a same-bare-name table strictly within the given namespace', () => {
+    const { storage, publicUsers, authUsers } = twoNamespaceSameTableName();
+
+    expect(resolveStorageTable(storage, 'users', 'public')).toEqual({
+      namespaceId: 'public',
+      table: publicUsers,
+    });
+    expect(resolveStorageTable(storage, 'users', 'auth')).toEqual({
+      namespaceId: 'auth',
+      table: authUsers,
+    });
+  });
+
+  it('throws naming the candidate namespaces for an ambiguous bare table name', () => {
+    const { storage } = twoNamespaceSameTableName();
+
+    expect(() => resolveStorageTable(storage, 'users')).toThrow(/ambiguous/i);
+    expect(() => resolveStorageTable(storage, 'users')).toThrow(/auth/);
+    expect(() => resolveStorageTable(storage, 'users')).toThrow(/public/);
+  });
+
+  it('returns undefined for an unknown table within a given namespace', () => {
+    const { storage } = twoNamespaceSameTableName();
+
+    expect(resolveStorageTable(storage, 'missing', 'public')).toBeUndefined();
+  });
 });

packages/2-sql/2-authoring/contract-psl/src/interpreter.ts

@@ -82,6 +82,8 @@ import {
   buildModelMappings,
   collectResolvedFields,
   type ModelNameMapping,
+  type ModelNamespaceEntry,
+  modelCoordinateKey,
   type ResolvedField,
 } from './psl-field-resolution';
 import {
@@ -594,6 +596,12 @@ 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>;
@@ -1166,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({
@@ -1201,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',
@@ -1269,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: {
@@ -1289,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,
@@ -1528,16 +1549,20 @@ function resolvePolymorphism(
 ): 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 baseModel = patched[baseName];
+    const baseKey = coordinateFor(baseName);
+    const baseModel = patched[baseKey];
     if (!baseModel || fieldNames.length === 0) continue;
     patched = {
       ...patched,
-      [baseName]: stripStorageOnlyDomainFields(baseModel, fieldNames),
+      [baseKey]: stripStorageOnlyDomainFields(baseModel, fieldNames),
     };
   }
 
@@ -1552,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)) {
@@ -1597,7 +1622,7 @@ function resolvePolymorphism(
 
     patched = {
       ...patched,
-      [modelName]: { ...model, discriminator: { field: decl.fieldName }, variants },
+      [coordinateFor(modelName)]: { ...model, discriminator: { field: decl.fieldName }, variants },
     };
   }
 
@@ -1626,7 +1651,7 @@ function resolvePolymorphism(
       continue;
     }
 
-    const variantModel = patched[variantName];
+    const variantModel = patched[coordinateFor(variantName)];
     if (!variantModel) continue;
 
     const baseMapping = modelMappings.get(baseDecl.baseName);
@@ -1646,7 +1671,7 @@ function resolvePolymorphism(
 
     patched = {
       ...patched,
-      [variantName]: stripStorageOnlyDomainFields(
+      [coordinateFor(variantName)]: stripStorageOnlyDomainFields(
         patchedVariant,
         syntheticPkFieldsByVariant.get(variantName) ?? [],
       ),
@@ -1883,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({
@@ -1891,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
@@ -1992,7 +2020,20 @@ 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[] = [];
@@ -2001,15 +2042,17 @@ export function interpretPslDocumentToSqlContract(
   // 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;
     }
     const result = buildModelNodeFromPsl({
       model,
       mapping,
       modelMappings,
+      modelMappingsByCoordinate,
       modelNames,
       compositeTypeNames,
       enumTypeDescriptors: allEnumTypeDescriptors,
@@ -2026,15 +2069,12 @@ 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]);
@@ -2135,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;
+      modelsForPatch[coordinate] = model;
     }
   }
   let patchedModels = patchModelDomainFields(modelsForPatch, modelResolvedFields);
@@ -2188,7 +2230,7 @@ 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