feat(emitter): emit through literal for N:M relations in contract.d.ts

Teach generateModelRelationsType to serialize the junction-table
descriptor (through.table / parentColumns / childColumns /
targetColumns) as a typed readonly literal when present in the relation
object.  Non-M:N relations (no through key) are byte-for-byte unchanged.

Adds three unit tests: M:N with single-column keys, M:N with a
composite parent key, and a regression guard that confirms through is
absent on a plain N:1 relation that carries only an on block.

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

Author: tensordreams

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

@@ -127,6 +127,24 @@ export function generateModelRelationsType(relations: Record<string, unknown>):
       );
     }
 
+    const through = relObj['through'] as
+      | {
+          table?: string;
+          parentColumns?: string[];
+          childColumns?: string[];
+          targetColumns?: string[];
+        }
+      | undefined;
+    if (through?.table && through.parentColumns && through.childColumns && through.targetColumns) {
+      const table = serializeValue(through.table);
+      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}] }`,
+      );
+    }
+
     if (parts.length > 0) {
       relationEntries.push(`readonly ${relName}: { ${parts.join('; ')} }`);
     }

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

@@ -343,6 +343,56 @@ describe('generateModelRelationsType', () => {
       }),
     ).toThrow('missing localFields or targetFields');
   });
+
+  it('emits through literal for N:M relations with junction metadata', () => {
+    const result = generateModelRelationsType({
+      tags: {
+        to: crossRef('Tag'),
+        cardinality: 'N:M',
+        through: {
+          table: 'post_tags',
+          parentColumns: ['postId'],
+          childColumns: ['tagId'],
+          targetColumns: ['id'],
+        },
+      },
+    });
+    expect(result).toContain("readonly model: 'Tag'");
+    expect(result).toContain("readonly cardinality: 'N:M'");
+    expect(result).toContain('readonly through:');
+    expect(result).toContain("readonly table: 'post_tags'");
+    expect(result).toContain("readonly parentColumns: readonly ['postId']");
+    expect(result).toContain("readonly childColumns: readonly ['tagId']");
+    expect(result).toContain("readonly targetColumns: readonly ['id']");
+  });
+
+  it('emits through with multi-column keys', () => {
+    const result = generateModelRelationsType({
+      roles: {
+        to: crossRef('Role'),
+        cardinality: 'N:M',
+        through: {
+          table: 'user_roles',
+          parentColumns: ['userId', 'tenantId'],
+          childColumns: ['roleId'],
+          targetColumns: ['id'],
+        },
+      },
+    });
+    expect(result).toContain("readonly parentColumns: readonly ['userId', 'tenantId']");
+  });
+
+  it('omits through when not present (non-N:M relations unchanged)', () => {
+    const result = generateModelRelationsType({
+      author: {
+        to: crossRef('User'),
+        cardinality: 'N:1',
+        on: { localFields: ['authorId'], targetFields: ['id'] },
+      },
+    });
+    expect(result).not.toContain('readonly through:');
+    expect(result).toContain("readonly localFields: readonly ['authorId']");
+  });
 });
 
 describe('deduplicateImports', () => {