feat(sql-contract): add N:M cardinality and through descriptor to contract shape

Extend ContractReferenceRelation to accept cardinality 'N:M' and an
optional through: { table, parentColumns, childColumns, targetColumns }.
Three places updated in lockstep:

- domain-types.ts: add 'N:M' to cardinality union, add ContractRelationThrough
  type and optional through field
- validators.ts: add 'N:M' to ContractReferenceRelationSchema enum, add
  ContractRelationThroughSchema with its own '+': 'reject' guard
- data-contract-sql-v1.json: add through object to ModelRelation def
- build-contract.ts: remove the 'as ContractRelation['cardinality']' cast
  (now unnecessary), rename emitted parentCols/childCols to parentColumns/
  childColumns, populate targetColumns from the target model's PK
- mongo-orm collection-state.ts: align local cardinality type from 'M:N' to
  'N:M' (trivial consumer fix required by the type widening)

New round-trip test: author User-UserTag-Tag M:N via rel.manyToMany,
emit, validateSqlContractFully passes, and through descriptor is asserted.

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

Author: tensordreams

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

@@ -30,10 +30,18 @@ export type ContractRelationOn = {
   readonly targetFields: readonly string[];
 };
 
+export type ContractRelationThrough = {
+  readonly table: string;
+  readonly parentColumns: readonly string[];
+  readonly childColumns: readonly string[];
+  readonly targetColumns: readonly string[];
+};
+
 export type ContractReferenceRelation = {
   readonly to: CrossReference;
-  readonly cardinality: '1:1' | '1:N' | 'N:1';
+  readonly cardinality: '1:1' | '1:N' | 'N:1' | 'N:M';
   readonly on: ContractRelationOn;
+  readonly through?: ContractRelationThrough;
 };
 
 export type ContractEmbedRelation = {

packages/2-mongo-family/5-query-builders/orm/src/collection-state.ts

@@ -5,7 +5,7 @@ export interface MongoIncludeExpr {
   readonly from: string;
   readonly localField: string;
   readonly foreignField: string;
-  readonly cardinality: '1:1' | 'N:1' | '1:N' | 'M:N';
+  readonly cardinality: '1:1' | 'N:1' | '1:N' | 'N:M';
 }
 
 export interface MongoCollectionState {

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

@@ -370,15 +370,24 @@ const ModelStorageSchema = type({
   fields: type({ '[string]': ModelStorageFieldSchema }),
 });
 
+const ContractRelationThroughSchema = type({
+  '+': 'reject',
+  table: 'string',
+  parentColumns: type.string.array().readonly(),
+  childColumns: type.string.array().readonly(),
+  targetColumns: type.string.array().readonly(),
+});
+
 const ContractReferenceRelationSchema = type({
   '+': 'reject',
   to: CrossReferenceSchema,
-  cardinality: "'1:1' | '1:N' | 'N:1'",
+  cardinality: "'1:1' | '1:N' | 'N:1' | 'N:M'",
   on: type({
     '+': 'reject',
     localFields: type.string.array().readonly(),
     targetFields: type.string.array().readonly(),
   }),
+  'through?': ContractRelationThroughSchema,
 });
 
 const ContractEmbedRelationSchema = type({

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

@@ -586,6 +586,33 @@
               "items": { "type": "string" }
             }
           }
+        },
+        "through": {
+          "type": "object",
+          "description": "Junction table descriptor for N:M relations",
+          "additionalProperties": false,
+          "properties": {
+            "table": {
+              "type": "string",
+              "description": "Junction table name"
+            },
+            "parentColumns": {
+              "type": "array",
+              "description": "Junction columns referencing the parent FK",
+              "items": { "type": "string" }
+            },
+            "childColumns": {
+              "type": "array",
+              "description": "Junction columns referencing the target FK",
+              "items": { "type": "string" }
+            },
+            "targetColumns": {
+              "type": "array",
+              "description": "Target anchor columns (PK) the childColumns reference",
+              "items": { "type": "string" }
+            }
+          },
+          "required": ["table", "parentColumns", "childColumns", "targetColumns"]
         }
       },
       "required": ["to", "cardinality"]

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

@@ -489,10 +489,7 @@ export function buildSqlContractFromDefinition(
           relation.toModel,
           resolveModelNamespaceId(targetModel, modelNameToNamespaceId, target),
         ),
-        // RelationDefinition.cardinality includes 'N:M' which isn't in
-        // ContractReferenceRelation yet — cast is needed until the contract
-        // type is extended to cover many-to-many.
-        cardinality: relation.cardinality as ContractRelation['cardinality'],
+        cardinality: relation.cardinality,
         on: {
           localFields: relation.on.parentColumns.map((col) => columnToField.get(col) ?? col),
           targetFields: relation.on.childColumns.map((col) => targetColumnToField.get(col) ?? col),
@@ -501,8 +498,9 @@ export function buildSqlContractFromDefinition(
           ? {
               through: {
                 table: relation.through.table,
-                parentCols: relation.through.parentColumns,
-                childCols: relation.through.childColumns,
+                parentColumns: relation.through.parentColumns,
+                childColumns: relation.through.childColumns,
+                targetColumns: targetModel.id?.columns ?? ([] as const),
               },
             }
           : undefined),

packages/2-sql/2-authoring/contract-ts/test/contract-builder.dsl.test.ts

@@ -1,4 +1,7 @@
+import type { Contract } from '@prisma-next/contract/types';
 import type { FamilyPackRef, TargetPackRef } from '@prisma-next/framework-components/components';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import { validateSqlContractFully } from '@prisma-next/sql-contract/validators';
 import { describe, expect, expectTypeOf, it } from 'vitest';
 import { type ContractInput, defineContract, field, model, rel } from '../src/contract-builder';
 import { modelsMapForAssertions, modelsOf } from './contract-test-helpers';
@@ -958,4 +961,82 @@ describe('self-referential and circular relations', () => {
       },
     });
   });
+
+  it('M:N relation round-trips through validateContract with through descriptor intact', () => {
+    const UserTag = model('UserTag', {
+      fields: {
+        userId: field.column(textColumn).column('user_id'),
+        tagId: field.column(textColumn).column('tag_id'),
+      },
+    })
+      .attributes(({ fields, constraints }) => ({
+        id: constraints.id([fields.userId, fields.tagId]),
+      }))
+      .sql({ table: 'user_tag' });
+
+    const TagBase = model('Tag', {
+      fields: {
+        id: field.column(textColumn).id(),
+        name: field.column(textColumn),
+      },
+    }).sql({ table: 'tag' });
+
+    const UserBase = model('User', {
+      fields: {
+        id: field.column(textColumn).id(),
+        email: field.column(textColumn),
+      },
+    });
+
+    const Tag = TagBase.relations({
+      users: rel.manyToMany(() => UserBase, {
+        through: () => UserTag,
+        from: 'tagId',
+        to: 'userId',
+      }),
+    });
+
+    const User = UserBase.relations({
+      tags: rel.manyToMany(() => Tag, {
+        through: () => UserTag,
+        from: 'userId',
+        to: 'tagId',
+      }),
+    }).sql({ table: 'app_user' });
+
+    const contract = defineTestContract({
+      models: { User, Tag, UserTag },
+    });
+
+    expect(() => validateSqlContractFully<Contract<SqlStorage>>(contract)).not.toThrow();
+
+    const contractModels = modelsOf(contract) as Record<
+      string,
+      { relations: Record<string, unknown> }
+    >;
+    expect(contractModels['User']?.relations).toMatchObject({
+      tags: {
+        to: crossRef('Tag', 'public'),
+        cardinality: 'N:M',
+        through: {
+          table: 'user_tag',
+          parentColumns: ['user_id'],
+          childColumns: ['tag_id'],
+          targetColumns: ['id'],
+        },
+      },
+    });
+    expect(contractModels['Tag']?.relations).toMatchObject({
+      users: {
+        to: crossRef('User', 'public'),
+        cardinality: 'N:M',
+        through: {
+          table: 'user_tag',
+          parentColumns: ['tag_id'],
+          childColumns: ['user_id'],
+          targetColumns: ['id'],
+        },
+      },
+    });
+  });
 });

packages/2-sql/2-authoring/contract-ts/test/contract.edge-cases.test.ts

@@ -130,7 +130,7 @@ describe('SqlContractSerializer edge cases', () => {
           },
           relations: {
             posts: {
-              on: { parentCols: ['id'], childCols: ['userId'] },
+              on: { localFields: ['id'], targetFields: ['userId'] },
               cardinality: '1:N',
             },
           },