feat(sql-orm-client): disable nested create on required-payload M:N relations at the type level

Nested `.create` on an N:M relation whose junction carries a required
non-FK payload column now resolves its argument to `never`, surfacing a
compile-time error instead of only the runtime guard in
`mutation-executor.ts`. `connect`/`disconnect` typing is unchanged.

The derivation resolves the relation `through` to its junction model,
treats any non-join column as a payload column, and disables create when
any payload column is required (not nullable, no default). `User.roles`
(junction `user_roles` with required `level`) disables create; `User.tags`
(pure junction) keeps it.

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

Author: tensordreams

packages/3-extensions/sql-orm-client/src/types.ts

@@ -914,12 +914,104 @@ export type RelationMutation<TContract extends Contract<SqlStorage>, ModelName e
   | RelationMutationConnect<TContract, ModelName>
   | RelationMutationDisconnect<TContract, ModelName>;
 
-export interface RelationMutator<TContract extends Contract<SqlStorage>, ModelName extends string> {
+type RelationThrough<
+  TContract extends Contract<SqlStorage>,
+  ModelName extends string,
+  RelName extends string,
+> =
+  RelationsOf<TContract, ModelName> extends infer Rels extends Record<string, unknown>
+    ? RelName extends keyof Rels
+      ? Rels[RelName] extends {
+          readonly through: infer Through extends {
+            readonly table: string;
+            readonly parentColumns: readonly string[];
+            readonly childColumns: readonly string[];
+          };
+        }
+        ? Through
+        : never
+      : never
+    : never;
+
+/**
+ * Resolves a storage table name to its owning domain model by scanning the
+ * model map for the model whose `storage.table` matches. Junction tables
+ * (e.g. `user_roles`) surface their generated model (e.g. `UserRole`) so the
+ * junction's own field nullability/defaults can be inspected.
+ */
+type ModelNameForTable<TContract extends Contract<SqlStorage>, TableName extends string> = {
+  [M in keyof ModelsOf<TContract> & string]: ModelsOf<TContract>[M] extends {
+    readonly storage: { readonly table: TableName };
+  }
+    ? M
+    : never;
+}[keyof ModelsOf<TContract> & string];
+
+/**
+ * A junction field is a *payload* field when its backing column is neither a
+ * parent-side nor a child-side foreign-key column of the join. Those payload
+ * fields are the ones the relation API can't populate from `create`/`connect`.
+ */
+type JunctionPayloadFieldNames<
+  TContract extends Contract<SqlStorage>,
+  JunctionModel extends string,
+  JoinColumns extends string,
+> = {
+  [F in CreateFieldNames<TContract, JunctionModel>]: FieldColumnName<
+    TContract,
+    JunctionModel,
+    F
+  > extends JoinColumns
+    ? never
+    : F;
+}[CreateFieldNames<TContract, JunctionModel>];
+
+/**
+ * True when the relation's junction carries at least one required payload
+ * column — a non-join column that is not nullable and has no default. Such a
+ * relation can't be populated through nested `create`, so its create input is
+ * disabled at the type level (mirroring the runtime guard in
+ * `mutation-executor.ts`).
+ */
+type HasRequiredJunctionPayload<
+  TContract extends Contract<SqlStorage>,
+  ModelName extends string,
+  RelName extends string,
+> =
+  RelationThrough<TContract, ModelName, RelName> extends infer Through extends {
+    readonly table: string;
+    readonly parentColumns: readonly string[];
+    readonly childColumns: readonly string[];
+  }
+    ? ModelNameForTable<TContract, Through['table']> extends infer JunctionModel extends string
+      ? {
+          [F in JunctionPayloadFieldNames<
+            TContract,
+            JunctionModel,
+            Through['parentColumns'][number] | Through['childColumns'][number]
+          >]: IsOptionalCreateField<TContract, JunctionModel, F> extends true ? never : F;
+        }[JunctionPayloadFieldNames<
+          TContract,
+          JunctionModel,
+          Through['parentColumns'][number] | Through['childColumns'][number]
+        >] extends never
+        ? false
+        : true
+      : false
+    : false;
+
+export interface RelationMutator<
+  TContract extends Contract<SqlStorage>,
+  ModelName extends string,
+  CreateDisabled extends boolean = false,
+> {
   create(
-    data: MutationCreateInput<TContract, ModelName>,
+    data: CreateDisabled extends true ? never : MutationCreateInput<TContract, ModelName>,
   ): RelationMutationCreate<TContract, ModelName>;
   create(
-    data: readonly MutationCreateInput<TContract, ModelName>[],
+    data: CreateDisabled extends true
+      ? never
+      : readonly MutationCreateInput<TContract, ModelName>[],
   ): RelationMutationCreate<TContract, ModelName>;
   connect(
     criterion: RelationConnectCriterion<TContract, ModelName>,
@@ -938,7 +1030,11 @@ type RelationMutationCallback<
   ModelName extends string,
   RelName extends RelationNames<TContract, ModelName>,
 > = (
-  mutator: RelationMutator<TContract, RelatedModelName<TContract, ModelName, RelName> & string>,
+  mutator: RelationMutator<
+    TContract,
+    RelatedModelName<TContract, ModelName, RelName> & string,
+    HasRequiredJunctionPayload<TContract, ModelName, RelName>
+  >,
 ) => RelationMutation<TContract, RelatedModelName<TContract, ModelName, RelName> & string>;
 
 type RelationMutationFields<

packages/3-extensions/sql-orm-client/test/junction-create-disable.test-d.ts

@@ -0,0 +1,80 @@
+import { expectTypeOf, test } from 'vitest';
+import type { MutationCreateInput } from '../src/types';
+import type { Contract } from './fixtures/generated/contract';
+
+type RoleCreate = MutationCreateInput<Contract, 'Role'>;
+type TagCreate = MutationCreateInput<Contract, 'Tag'>;
+
+const roleCreate = { id: 'admin', name: 'Admin' } as RoleCreate;
+const tagCreate = { id: 'featured', name: 'Featured' } as TagCreate;
+const roleCriterion = { id: 'admin' } as { readonly id: NonNullable<RoleCreate['id']> };
+const tagCriterion = { id: 'featured' } as { readonly id: NonNullable<TagCreate['id']> };
+
+test('nested create on a relation whose junction has a required payload column is a type error', () => {
+  type Input = MutationCreateInput<Contract, 'User'>;
+
+  const input: Input = {
+    name: 'Alice',
+    email: 'alice@test.com',
+    roles: (mutator) =>
+      // @ts-expect-error - User.roles junction `user_roles` carries required column `level` the relation API can't populate, so nested create is disabled
+      mutator.create(roleCreate),
+  };
+
+  expectTypeOf(input).toExtend<Input>();
+});
+
+test('connect remains available on a required-payload junction relation', () => {
+  type Input = MutationCreateInput<Contract, 'User'>;
+
+  const input: Input = {
+    name: 'Alice',
+    email: 'alice@test.com',
+    roles: (mutator) => mutator.connect(roleCriterion),
+  };
+
+  expectTypeOf(input).toExtend<Input>();
+});
+
+test('disconnect remains available on a required-payload junction relation', () => {
+  type Input = MutationCreateInput<Contract, 'User'>;
+
+  const input: Input = {
+    name: 'Alice',
+    email: 'alice@test.com',
+    roles: (mutator) => mutator.disconnect([roleCriterion]),
+  };
+
+  expectTypeOf(input).toExtend<Input>();
+});
+
+test('nested create on a pure junction relation is allowed', () => {
+  type Input = MutationCreateInput<Contract, 'User'>;
+
+  const input: Input = {
+    name: 'Alice',
+    email: 'alice@test.com',
+    tags: (mutator) => mutator.create(tagCreate),
+  };
+
+  expectTypeOf(input).toExtend<Input>();
+});
+
+test('connect and disconnect remain available on a pure junction relation', () => {
+  type Input = MutationCreateInput<Contract, 'User'>;
+
+  const connectInput: Input = {
+    name: 'Alice',
+    email: 'alice@test.com',
+    tags: (mutator) => mutator.connect(tagCriterion),
+  };
+
+  const disconnectInput: Input = {
+    name: 'Alice',
+    email: 'alice@test.com',
+    tags: (mutator) => mutator.disconnect([tagCriterion]),
+  };
+
+  expectTypeOf(connectInput).toExtend<Input>();
+  expectTypeOf(disconnectInput).toExtend<Input>();
+});