feat(contract): carry junction namespaceId on the emitted through descriptor

Nothing constrains the source, target, and junction tables of an N:M
relation to one namespace, so resolving the junction by bare table name
is ambiguous under cross-namespace collisions (TML-2550). Mirror the
FK-reference shape: the emitted through block now carries the junction's
namespaceId (JSON schema + arktype validator + ContractRelationThrough +
build-contract emission + contract.d.ts literal), and the orm-client
resolver reads it from the contract — looking the junction up in its
declared namespace — instead of re-deriving by name scan.

Follows up wmadden's review on #678 (domain-types.ts 'Needs namespace').

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

Author: tensordreams

packages/1-framework/0-foundation/contract/src/domain-types.ts

@@ -32,6 +32,7 @@ export type ContractRelationOn = {
 
 export type ContractRelationThrough = {
   readonly table: string;
+  readonly namespaceId: string;
   readonly parentColumns: readonly string[];
   readonly childColumns: readonly string[];
   readonly targetColumns: readonly string[];

packages/1-framework/3-tooling/emitter/src/domain-type-generation.ts

@@ -130,18 +130,26 @@ export function generateModelRelationsType(relations: Record<string, unknown>):
     const through = relObj['through'] as
       | {
           table?: string;
+          namespaceId?: string;
           parentColumns?: string[];
           childColumns?: string[];
           targetColumns?: string[];
         }
       | undefined;
-    if (through?.table && through.parentColumns && through.childColumns && through.targetColumns) {
+    if (
+      through?.table &&
+      through.namespaceId &&
+      through.parentColumns &&
+      through.childColumns &&
+      through.targetColumns
+    ) {
       const table = serializeValue(through.table);
+      const namespaceId = serializeValue(through.namespaceId);
       const parentColumns = through.parentColumns.map((c) => serializeValue(c)).join(', ');
       const childColumns = through.childColumns.map((c) => serializeValue(c)).join(', ');
       const targetColumns = through.targetColumns.map((c) => serializeValue(c)).join(', ');
       parts.push(
-        `readonly through: { readonly table: ${table}; readonly parentColumns: readonly [${parentColumns}]; readonly childColumns: readonly [${childColumns}]; readonly targetColumns: readonly [${targetColumns}] }`,
+        `readonly through: { readonly table: ${table}; readonly namespaceId: ${namespaceId}; readonly parentColumns: readonly [${parentColumns}]; readonly childColumns: readonly [${childColumns}]; readonly targetColumns: readonly [${targetColumns}] }`,
       );
     }
 

packages/1-framework/3-tooling/emitter/test/domain-type-generation.test.ts

@@ -351,6 +351,7 @@ describe('generateModelRelationsType', () => {
         cardinality: 'N:M',
         through: {
           table: 'post_tags',
+          namespaceId: 'public',
           parentColumns: ['postId'],
           childColumns: ['tagId'],
           targetColumns: ['id'],
@@ -361,6 +362,7 @@ describe('generateModelRelationsType', () => {
     expect(result).toContain("readonly cardinality: 'N:M'");
     expect(result).toContain('readonly through:');
     expect(result).toContain("readonly table: 'post_tags'");
+    expect(result).toContain("readonly namespaceId: 'public'");
     expect(result).toContain("readonly parentColumns: readonly ['postId']");
     expect(result).toContain("readonly childColumns: readonly ['tagId']");
     expect(result).toContain("readonly targetColumns: readonly ['id']");
@@ -373,6 +375,7 @@ describe('generateModelRelationsType', () => {
         cardinality: 'N:M',
         through: {
           table: 'user_roles',
+          namespaceId: 'public',
           parentColumns: ['userId', 'tenantId'],
           childColumns: ['roleId'],
           targetColumns: ['id'],

packages/2-sql/1-core/contract/src/validators.ts

@@ -364,6 +364,7 @@ const ModelStorageSchema = type({
 const ContractRelationThroughSchema = type({
   '+': 'reject',
   table: 'string',
+  namespaceId: 'string',
   parentColumns: type.string.array().readonly(),
   childColumns: type.string.array().readonly(),
   targetColumns: type.string.array().readonly(),

packages/2-sql/2-authoring/contract-ts/schemas/data-contract-sql-v1.json

@@ -596,6 +596,10 @@
               "type": "string",
               "description": "Junction table name"
             },
+            "namespaceId": {
+              "type": "string",
+              "description": "Namespace the junction table lives in"
+            },
             "parentColumns": {
               "type": "array",
               "description": "Junction columns referencing the parent FK",
@@ -612,7 +616,7 @@
               "items": { "type": "string" }
             }
           },
-          "required": ["table", "parentColumns", "childColumns", "targetColumns"]
+          "required": ["table", "namespaceId", "parentColumns", "childColumns", "targetColumns"]
         }
       },
       "required": ["to", "cardinality"]

packages/2-sql/2-authoring/contract-ts/src/build-contract.ts

@@ -301,6 +301,12 @@ export function buildSqlContractFromDefinition(
   const defaultNamespaceId = definition.target.defaultNamespaceId;
   const targetFamily = 'sql';
   const modelsByName = new Map(definition.models.map((m) => [m.modelName, m]));
+  const tableNamespaceByName = new Map(
+    definition.models.map((m) => [
+      m.tableName,
+      m.namespaceId !== undefined && m.namespaceId.length > 0 ? m.namespaceId : defaultNamespaceId,
+    ]),
+  );
 
   const tablesByNamespace: Record<string, Record<string, StorageTable>> = {};
   const tableNameToNamespaceId = new Map<string, string>();
@@ -494,6 +500,7 @@ export function buildSqlContractFromDefinition(
           ? {
               through: {
                 table: relation.through.table,
+                namespaceId: tableNamespaceByName.get(relation.through.table) ?? defaultNamespaceId,
                 parentColumns: relation.through.parentColumns,
                 childColumns: relation.through.childColumns,
                 targetColumns: targetModel.id?.columns ?? ([] as const),

packages/3-extensions/sql-orm-client/src/collection-contract.ts

@@ -200,8 +200,6 @@ export function getCompleteColumnToFieldMap(
 }
 
 interface ResolvedThrough extends ContractRelationThrough {
-  /** Namespace of the junction table, resolved from storage. */
-  readonly namespaceId?: string;
   readonly requiredPayloadColumns: readonly string[];
 }
 
@@ -257,13 +255,20 @@ export function resolveIncludeRelation(
 function resolveThrough(
   contract: Contract<SqlStorage>,
   raw:
-    | { table?: unknown; parentColumns?: unknown; childColumns?: unknown; targetColumns?: unknown }
+    | {
+        table?: unknown;
+        namespaceId?: unknown;
+        parentColumns?: unknown;
+        childColumns?: unknown;
+        targetColumns?: unknown;
+      }
     | undefined,
 ): ResolvedThrough | undefined {
   if (!raw) return undefined;
-  const { table, parentColumns, childColumns, targetColumns } = raw;
+  const { table, namespaceId, parentColumns, childColumns, targetColumns } = raw;
   if (
     typeof table !== 'string' ||
+    typeof namespaceId !== 'string' ||
     !Array.isArray(parentColumns) ||
     !Array.isArray(childColumns) ||
     !Array.isArray(targetColumns)
@@ -275,10 +280,10 @@ function resolveThrough(
     ...castAs<readonly string[]>(parentColumns),
     ...castAs<readonly string[]>(childColumns),
   ]);
-  const resolvedJunction = resolveTableForContract(contract, table);
+  const junctionTable = contract.storage.namespaces[namespaceId]?.tables[table];
   const requiredPayloadColumns: string[] = [];
-  if (resolvedJunction) {
-    for (const [colName, col] of Object.entries(resolvedJunction.table.columns)) {
+  if (junctionTable) {
+    for (const [colName, col] of Object.entries(junctionTable.columns)) {
       if (!fkColumnSet.has(colName) && !col.nullable && col.default === undefined) {
         requiredPayloadColumns.push(colName);
       }
@@ -287,11 +292,11 @@ function resolveThrough(
 
   return {
     table,
+    namespaceId,
     parentColumns: castAs<readonly string[]>(parentColumns),
     childColumns: castAs<readonly string[]>(childColumns),
     targetColumns: castAs<readonly string[]>(targetColumns),
     requiredPayloadColumns,
-    ...(resolvedJunction !== undefined ? { namespaceId: resolvedJunction.namespaceId } : {}),
   };
 }
 
@@ -322,6 +327,7 @@ export function resolveModelRelations(
       on?: { localFields?: unknown; targetFields?: unknown };
       through?: {
         table?: unknown;
+        namespaceId?: unknown;
         parentColumns?: unknown;
         childColumns?: unknown;
         targetColumns?: unknown;

packages/3-extensions/sql-orm-client/test/collection-contract.test.ts

@@ -405,6 +405,7 @@ describe('resolveModelRelations() through descriptor', () => {
                     on: { localFields: ['id'], targetFields: targetColumns },
                     through: {
                       table: junctionTable,
+                      namespaceId: 'public',
                       parentColumns,
                       childColumns,
                       targetColumns,