@prisma-next/sql-contract 0.13.0 → 0.14.0-dev.10

package/src/validators.ts

@@ -6,50 +6,48 @@ import {
   CrossReferenceSchema,
 } from '@prisma-next/contract/types';
 import { validateContractDomain } from '@prisma-next/contract/validate-domain';
-import { type Namespace, UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
+import {
+  type AnyEntityKindDescriptor,
+  isPlainRecord,
+  type Namespace,
+  UNBOUND_NAMESPACE_ID,
+} from '@prisma-next/framework-components/ir';
 import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { type Type, type } from 'arktype';
+import { composeSqlEntityKinds } from './entity-kinds';
 import { buildSqlNamespaceMap } from './ir/build-sql-namespace';
+
+export {
+  CheckConstraintSchema,
+  ColumnDefaultFunctionSchema,
+  ColumnDefaultLiteralSchema,
+  ColumnDefaultSchema,
+  ForeignKeyReferenceSchema,
+  ForeignKeySchema,
+  ForeignKeySourceSchema,
+  IndexSchema,
+  ReferentialActionSchema,
+  StorageTableSchema,
+  StorageValueSetSchema,
+} from './ir/storage-entry-schemas';
+
 import { SqlUnboundNamespace } from './ir/sql-unbound-namespace';
 import {
-  type ForeignKeyInput,
-  type ForeignKeyReferenceInput,
-  type PrimaryKeyInput,
-  type ReferentialAction,
   type SqlModelStorage,
   SqlStorage,
   type SqlStorageInput,
+  type StorageColumn,
   type StorageTable,
   type StorageTypeInstanceInput,
-  type UniqueConstraintInput,
 } from './types';
 
-type ColumnDefaultLiteral = {
-  readonly kind: 'literal';
-  readonly value: string | number | boolean | Record<string, unknown> | unknown[] | null;
-};
-type ColumnDefaultFunction = { readonly kind: 'function'; readonly expression: string };
-const literalKindSchema = type("'literal'");
-const functionKindSchema = type("'function'");
 const generatorKindSchema = type("'generator'");
 const ControlPolicySchema = type("'managed' | 'tolerated' | 'external' | 'observed'");
 const generatorIdSchema = type('string').narrow((value, ctx) => {
   return /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value) ? true : ctx.mustBe('a flat generator id');
 });
 
-export const ColumnDefaultLiteralSchema = type.declare<ColumnDefaultLiteral>().type({
-  kind: literalKindSchema,
-  value: 'string | number | boolean | null | unknown[] | Record<string, unknown>',
-});
-
-export const ColumnDefaultFunctionSchema = type.declare<ColumnDefaultFunction>().type({
-  kind: functionKindSchema,
-  expression: 'string',
-});
-
-export const ColumnDefaultSchema = ColumnDefaultLiteralSchema.or(ColumnDefaultFunctionSchema);
-
 const ExecutionMutationDefaultValueSchema = type({
   '+': 'reject',
   kind: generatorKindSchema,
@@ -61,6 +59,7 @@ const ExecutionMutationDefaultSchema = type({
   '+': 'reject',
   ref: {
     '+': 'reject',
+    namespace: 'string',
     table: 'string',
     column: 'string',
   },
@@ -77,31 +76,14 @@ const ExecutionSchema = type({
   },
 });
 
-const ValueSetRefSchema = type({
-  plane: "'domain' | 'storage'",
+const DomainEnumRefSchema = type({
+  plane: "'domain'",
   namespaceId: 'string',
-  entityKind: "'enum' | 'value-set'",
-  name: 'string',
+  entityKind: "'enum'",
+  entityName: 'string',
   'spaceId?': 'string',
 });
 
-const StorageColumnSchema = type({
-  '+': 'reject',
-  nativeType: 'string',
-  codecId: 'string',
-  nullable: 'boolean',
-  'typeParams?': 'Record<string, unknown>',
-  'typeRef?': 'string',
-  'default?': ColumnDefaultSchema,
-  'control?': ControlPolicySchema,
-  'valueSet?': ValueSetRefSchema,
-}).narrow((col, ctx) => {
-  if (col.typeParams !== undefined && col.typeRef !== undefined) {
-    return ctx.mustBe('a column with either typeParams or typeRef, not both');
-  }
-  return true;
-});
-
 /**
  * Codec-triple entry persisted under `storage.types[name]`. Carries an
  * enumerable literal `kind: 'codec-instance'` discriminator so the
@@ -117,32 +99,9 @@ const StorageTypeInstanceSchema = type
     'typeParams?': 'Record<string, unknown>',
   });
 
-/**
- * Postgres native enum entry under `storage.namespaces[namespaceId].entries.type[name]`.
- * Document-scoped `storage.types` carries codec aliases only
- * (`DocumentScopedStorageTypeSchema`).
- */
-const PostgresEnumTypeSchema = type({
-  kind: "'postgres-enum'",
-  'name?': 'string',
-  'nativeType?': 'string',
-  values: type.string.array().readonly(),
-  'control?': ControlPolicySchema,
-});
-
 /** Document-scoped `storage.types`: codec triples only. */
 const DocumentScopedStorageTypeSchema = StorageTypeInstanceSchema;
 
-/**
- * Storage value-set entry under `storage.namespaces[id].entries.valueSet[name]`.
- * Carries a `kind: 'value-set'` discriminator (enumerable, survives JSON) and an
- * ordered `values` array of codec-encoded permitted values.
- */
-export const StorageValueSetSchema = type({
-  kind: "'value-set'",
-  values: type.string.array().readonly(),
-});
-
 /**
  * Domain enum entry under `domain.namespaces[id].enum[name]`.
  * Carries the codec id and an ordered `members` array of `{name, value}` pairs.
@@ -152,174 +111,82 @@ export const ContractEnumSchema = type({
   codecId: 'string',
   members: type({
     name: 'string',
-    value: 'string',
+    value: 'string | number | boolean | null | unknown[] | Record<string, unknown>',
   })
     .array()
     .readonly(),
 });
 
-const PrimaryKeySchema = type.declare<PrimaryKeyInput>().type({
-  columns: type.string.array().readonly(),
-  'name?': 'string',
-});
-
-const UniqueConstraintSchema = type.declare<UniqueConstraintInput>().type({
-  columns: type.string.array().readonly(),
-  'name?': 'string',
-});
-
-export const IndexSchema = type({
-  columns: type.string.array().readonly(),
-  'name?': 'string',
-  'type?': 'string',
-  'options?': 'Record<string, unknown>',
-});
-
-export const ForeignKeyReferenceSchema = type({
-  '+': 'reject',
-  namespaceId: 'string',
-  tableName: 'string',
-  columns: type.string.array().readonly(),
-  'spaceId?': 'string',
-}) satisfies Type<ForeignKeyReferenceInput>;
-
-export const ForeignKeySourceSchema = type({
-  '+': 'reject',
-  namespaceId: 'string',
-  tableName: 'string',
-  columns: type.string.array().readonly(),
-}) satisfies Type<ForeignKeyReferenceInput>;
-
-export const ReferentialActionSchema = type
-  .declare<ReferentialAction>()
-  .type("'noAction' | 'restrict' | 'cascade' | 'setNull' | 'setDefault'");
-
-export const ForeignKeySchema = type.declare<ForeignKeyInput>().type({
-  source: ForeignKeySourceSchema,
-  target: ForeignKeyReferenceSchema,
-  'name?': 'string',
-  'onDelete?': ReferentialActionSchema,
-  'onUpdate?': ReferentialActionSchema,
-  constraint: 'boolean',
-  index: 'boolean',
-});
-
-export const CheckConstraintSchema = type({
-  '+': 'reject',
-  name: 'string',
-  column: 'string',
-  valueSet: ValueSetRefSchema,
-});
-
-const StorageTableSchema = type({
-  '+': 'reject',
-  columns: type({ '[string]': StorageColumnSchema }),
-  'primaryKey?': PrimaryKeySchema,
-  uniques: UniqueConstraintSchema.array().readonly(),
-  indexes: IndexSchema.array().readonly(),
-  foreignKeys: ForeignKeySchema.array().readonly(),
-  'control?': ControlPolicySchema,
-  'checks?': CheckConstraintSchema.array().readonly(),
-});
-
 /**
- * Re-exported so target packs can register their `validatorSchema`
- * fragment without re-declaring the schema for the kinds the family
- * core already validates. Full extraction of enum-specific schemas
- * into the Postgres pack is a follow-up; today the symbol lives here.
+ * Derives a schema map from a descriptor map: maps each kind's key to its
+ * `schema` field. Used by validation functions to validate entries.
  */
-export { PostgresEnumTypeSchema };
+function schemaViewOf(
+  kinds: ReadonlyMap<string, AnyEntityKindDescriptor>,
+): ReadonlyMap<string, Type<unknown>> {
+  return new Map([...kinds].map(([k, d]) => [k, d.schema]));
+}
+
+const DEFAULT_SQL_KINDS = composeSqlEntityKinds();
 
 /**
- * Composes a hardcoded family `fallback` schema with optional
- * pack-contributed `fragments` keyed by the entry's `kind`
- * discriminator. The composition is **additive**, not substitutive:
+ * Builds the per-namespace entry schema for `storage.namespaces[id]`.
  *
- * - No fragments registered → entries are validated by `fallback`
- *   alone (the unchanged baseline).
- * - An entry's `kind` matches `fallbackKind` AND a fragment for that
- *   kind is registered → the entry must pass **both** `fallback` and
- *   the fragment. This preserves family-owned invariants (e.g. the
- *   built-in `PostgresEnumType` shape) even when a pack contributes
- *   its own schema for the same kind.
- * - An entry's `kind` matches a registered fragment for some
- *   non-fallback kind → the fragment alone validates the entry.
- *   `fallback` is family-specific (validates a single hardcoded kind)
- *   and would reject any other kind, so it does not apply here.
- * - An entry's `kind` matches no fragment → fall through to
- *   `fallback`.
+ * Validation is descriptor-driven: the `kinds` map carries both the schema
+ * (used here for structural validation) and the construct function (used at
+ * hydration time). An unregistered key fails validation naming the kind and
+ * the namespace id, so validation fails closed.
  */
-function namespaceSlotEntrySchema(
-  fallback: Type<unknown>,
-  fallbackKind: string,
-  fragments?: ReadonlyMap<string, Type<unknown>>,
+export function createNamespaceEntrySchema(
+  kinds: ReadonlyMap<string, AnyEntityKindDescriptor>,
 ): Type<unknown> {
-  if (fragments === undefined || fragments.size === 0) {
-    return fallback;
-  }
-  return type('unknown').narrow((entry, ctx) => {
-    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
-      return ctx.mustBe('an object');
+  const schemas = schemaViewOf(kinds);
+  const knownKinds = new Set(kinds.keys());
+  return type({
+    '+': 'reject',
+    id: 'string',
+    'kind?': 'string',
+    entries: 'object',
+  }).narrow((ns, ctx) => {
+    if (!isPlainRecord(ns.entries)) {
+      return ctx.mustBe('an entries object');
     }
-    const kind = (entry as { kind?: unknown }).kind;
-    if (typeof kind === 'string') {
-      const fragment = fragments.get(kind);
-      if (fragment !== undefined) {
-        if (kind === fallbackKind) {
-          const baseParsed = fallback(entry);
-          if (baseParsed instanceof type.errors) {
-            return ctx.reject({ expected: baseParsed.summary });
-          }
-        }
-        const parsed = fragment(entry);
+    for (const [key, innerMap] of Object.entries(ns.entries)) {
+      if (!knownKinds.has(key)) {
+        return ctx.reject({
+          expected: `entries key "${key}" in namespace "${ns.id}" is not a registered entity kind`,
+        });
+      }
+      if (!isPlainRecord(innerMap)) {
+        return ctx.reject({
+          expected: `entries["${key}"] in namespace "${ns.id}" must be an object`,
+        });
+      }
+      const entrySchema = blindCast<
+        Type<unknown>,
+        'knownKinds.has(key) guarantees schemas.get(key) is defined'
+      >(schemas.get(key));
+      for (const [, value] of Object.entries(innerMap)) {
+        const parsed = entrySchema(value);
         if (parsed instanceof type.errors) {
           return ctx.reject({ expected: parsed.summary });
         }
-        return true;
       }
     }
-    const parsed = fallback(entry);
-    if (parsed instanceof type.errors) {
-      return ctx.reject({ expected: parsed.summary });
-    }
     return true;
-  });
-}
-
-/**
- * Builds the per-namespace entry schema for `storage.namespaces[id]`.
- * Pack-contributed `validatorSchema` fragments — keyed by the
- * descriptor's `discriminator` — validate each entry by matching the
- * entry's `kind` field on the `'entries.type'` slot.
- */
-export function createNamespaceEntrySchema(
-  fragments?: ReadonlyMap<string, Type<unknown>>,
-): Type<unknown> {
-  return type({
-    '+': 'reject',
-    id: 'string',
-    'kind?': 'string',
-    entries: type({
-      '+': 'reject',
-      'table?': type({ '[string]': StorageTableSchema }),
-      'type?': type({
-        '[string]': namespaceSlotEntrySchema(PostgresEnumTypeSchema, 'postgres-enum', fragments),
-      }),
-      'valueSet?': type({ '[string]': StorageValueSetSchema }),
-    }),
   }) as Type<unknown>;
 }
 
 /**
  * Builds the storage schema. Pack contributions reach the per-namespace
  * entry shape through {@link createNamespaceEntrySchema}; the
- * document-scoped `storage.types` slot (codec triples only) and the
+ * document-scoped `storage.types` field (codec triples only) and the
  * storage hash stay family-shared.
  */
 export function createSqlStorageSchema(
-  fragments?: ReadonlyMap<string, Type<unknown>>,
+  kinds: ReadonlyMap<string, AnyEntityKindDescriptor>,
 ): Type<unknown> {
-  const namespaceEntry = createNamespaceEntrySchema(fragments);
+  const namespaceEntry = createNamespaceEntrySchema(kinds);
   return type({
     '+': 'reject',
     storageHash: 'string',
@@ -333,24 +200,20 @@ export function createSqlStorageSchema(
   }) as Type<unknown>;
 }
 
-const StorageSchema = createSqlStorageSchema();
+const StorageSchema = createSqlStorageSchema(DEFAULT_SQL_KINDS);
 
-// SQL-specific namespace walk shape (`entries.table` is the SQL family's
-// idiom). The wider `object` table value keeps this helper structurally
-// compatible with `SqlNamespace` and JSON envelope variants that lose class
-// identity.
 type NamespacedStorageWalk = {
   readonly namespaces: Readonly<
     Record<
       string,
-      Namespace & { readonly entries: { readonly table: Readonly<Record<string, object>> } }
+      Namespace & { readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>> }
     >
   >;
 };
 
 function eachStorageTable(storage: NamespacedStorageWalk) {
   return Object.entries(storage.namespaces).flatMap(([namespaceId, ns]) =>
-    Object.entries(ns.entries.table).map(([tableName, table]) => ({
+    Object.entries(ns.entries['table'] ?? {}).map(([tableName, table]) => ({
       namespaceId,
       tableName,
       table,
@@ -358,10 +221,6 @@ function eachStorageTable(storage: NamespacedStorageWalk) {
   );
 }
 
-function isPlainRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function findDuplicateValue(values: readonly string[]): string | undefined {
   const seen = new Set<string>();
   for (const value of values) {
@@ -403,7 +262,7 @@ const ModelFieldSchema = type({
   type: ContractFieldTypeSchema,
   'many?': 'true',
   'dict?': 'true',
-  'valueSet?': ValueSetRefSchema,
+  'valueSet?': DomainEnumRefSchema,
 });
 
 const ModelStorageFieldSchema = type({
@@ -480,9 +339,9 @@ const ContractMetaSchema = type({
  * of the contract envelope is family-shared.
  */
 export function createSqlContractSchema(
-  fragments?: ReadonlyMap<string, Type<unknown>>,
+  kinds: ReadonlyMap<string, AnyEntityKindDescriptor>,
 ): Type<unknown> {
-  const storage = createSqlStorageSchema(fragments);
+  const storage = createSqlStorageSchema(kinds);
   return type({
     '+': 'reject',
     target: 'string',
@@ -508,7 +367,7 @@ export function createSqlContractSchema(
   }) as Type<unknown>;
 }
 
-const SqlContractSchema = createSqlContractSchema();
+const SqlContractSchema = createSqlContractSchema(DEFAULT_SQL_KINDS);
 
 // NOTE: StorageColumnSchema, StorageTableSchema, and StorageSchema use bare type()
 // instead of type.declare<T>().type() because the ColumnDefault union's value field
@@ -792,7 +651,8 @@ export function validateModelStorageReferences(contract: Contract<SqlStorage>):
       }
 
       const storageTable = model.storage.table;
-      const rawTable = contract.storage.namespaces[storageNamespaceId]?.entries.table[storageTable];
+      const storageNs = contract.storage.namespaces[storageNamespaceId];
+      const rawTable = storageNs?.entries.table?.[storageTable];
       if (rawTable === undefined) {
         throw new ContractValidationError(
           `Model "${qualifiedName}" references non-existent table "${storageNamespaceId}.${storageTable}"`,
@@ -912,7 +772,7 @@ export function validateSqlStorageConsistency(contract: Contract<SqlStorage>): v
 
       if (fk.target.spaceId === undefined) {
         const targetNamespace = contract.storage.namespaces[fk.target.namespaceId];
-        const referencedRaw = targetNamespace?.entries.table[fk.target.tableName];
+        const referencedRaw = targetNamespace?.entries.table?.[fk.target.tableName];
         if (referencedRaw === undefined) {
           throw new ContractValidationError(
             `Namespace "${namespaceId}" table "${tableName}" foreignKey references non-existent table "${fk.target.namespaceId}.${fk.target.tableName}"`,
@@ -987,5 +847,208 @@ export function validateSqlContractFully<T extends Contract<SqlStorage>>(
     );
   }
   validateModelStorageReferences(validated);
+  validateRelationThroughConsistency(validated);
   return validated;
 }
+
+/** Storage column lookup for through-consistency validation. */
+function lookupStorageColumn(
+  contract: Contract<SqlStorage>,
+  namespaceId: string,
+  tableName: string,
+  columnName: string,
+): StorageColumn | undefined {
+  const rawTable = contract.storage.namespaces[namespaceId]?.entries.table?.[tableName];
+  if (rawTable === undefined) {
+    return undefined;
+  }
+  const table = blindCast<StorageTable, 'structurally validated storage table'>(rawTable);
+  return table.columns[columnName];
+}
+
+/**
+ * Two storage columns share a type when their `nativeType` and `typeParams`
+ * match. The contract is canonicalized, so `typeParams` key order is stable and
+ * a JSON comparison is exact. `codecId` and `nullable` are intentionally not
+ * compared: they do not change the database-level type that governs a join.
+ */
+function sameStorageType(a: StorageColumn, b: StorageColumn): boolean {
+  return (
+    a.nativeType === b.nativeType &&
+    JSON.stringify(a.typeParams ?? null) === JSON.stringify(b.typeParams ?? null)
+  );
+}
+
+function describeColumnType(column: StorageColumn): string {
+  return column.typeParams === undefined
+    ? column.nativeType
+    : `${column.nativeType} ${JSON.stringify(column.typeParams)}`;
+}
+
+/**
+ * Validates one side of an N:M join: the junction columns and the model
+ * columns they pair against positionally must be equal in number, exist in
+ * their tables, and share the same storage type (`nativeType` + `typeParams`).
+ * The junction's storage foreign keys already guarantee this for user-declared
+ * FK constraints, but `through` is a logical descriptor never tied to them by
+ * the rest of validation — and the TS builder accepts explicit join columns
+ * without requiring a junction FK at all — so this checks the columns directly
+ * against storage, one path regardless of how the junction was authored.
+ *
+ * Joined columns must be the *same* storage type, not merely compatible:
+ * relying on implicit conversion (e.g. `text`↔`character`) is unsafe on writes
+ * — `character(n)` space-padding makes such coercions non-associative — and no
+ * ADR sanctions heterogeneous junction columns. Equality is the conservative
+ * default; it can be relaxed deliberately if a real use case ever appears.
+ */
+function validateThroughJoinSide(input: {
+  readonly contract: Contract<SqlStorage>;
+  readonly qualifiedName: string;
+  readonly modelColumns: readonly string[];
+  readonly modelColumnsLabel: string;
+  /**
+   * The model side of the join, when resolvable. Absent for a cross-space
+   * target whose storage lives in another contract: the length and
+   * junction-column-existence checks still run, but the target-column
+   * existence and type checks are skipped because the target table is not
+   * available here. `fieldToColumn` is present when `modelColumns` are domain
+   * field names (the `on.*Fields` arrays), absent when they are already storage
+   * column names (the `through.*Columns` arrays).
+   */
+  readonly model?: {
+    readonly namespaceId: string;
+    readonly table: string;
+    readonly fieldToColumn?: Readonly<Record<string, { readonly column: string }>>;
+  };
+  readonly junctionColumns: readonly string[];
+  readonly junctionColumnsLabel: string;
+  readonly junctionNamespaceId: string;
+  readonly junctionTable: string;
+}): void {
+  const fail = (detail: string): ContractValidationError =>
+    new ContractValidationError(
+      `Many-to-many relation "${input.qualifiedName}" ${detail}`,
+      'storage',
+    );
+  if (input.junctionColumns.length !== input.modelColumns.length) {
+    throw fail(
+      `pairs ${input.junctionColumnsLabel} (${input.junctionColumns.length}) with ${input.modelColumnsLabel} (${input.modelColumns.length}) of differing length; they join positionally and must match.`,
+    );
+  }
+  for (const [index, junctionColumnName] of input.junctionColumns.entries()) {
+    const modelColumnRef = input.modelColumns[index];
+    if (modelColumnRef === undefined) {
+      continue;
+    }
+    const junctionColumn = lookupStorageColumn(
+      input.contract,
+      input.junctionNamespaceId,
+      input.junctionTable,
+      junctionColumnName,
+    );
+    if (junctionColumn === undefined) {
+      throw fail(
+        `${input.junctionColumnsLabel} references column "${junctionColumnName}" absent from junction table "${input.junctionNamespaceId}.${input.junctionTable}".`,
+      );
+    }
+    // Cross-space target: its storage lives in another contract, so the target
+    // column's existence and type cannot be checked here. Length and
+    // junction-column existence have already been validated above.
+    const model = input.model;
+    if (model === undefined) {
+      continue;
+    }
+    let modelColumnName = modelColumnRef;
+    if (model.fieldToColumn !== undefined) {
+      const mapped = model.fieldToColumn[modelColumnRef];
+      if (mapped === undefined) {
+        throw fail(
+          `${input.modelColumnsLabel} references field "${modelColumnRef}" absent from model on table "${model.namespaceId}.${model.table}".`,
+        );
+      }
+      modelColumnName = mapped.column;
+    }
+    const modelColumn = lookupStorageColumn(
+      input.contract,
+      model.namespaceId,
+      model.table,
+      modelColumnName,
+    );
+    if (modelColumn === undefined) {
+      throw fail(
+        `${input.modelColumnsLabel} references column "${modelColumnName}" absent from table "${model.namespaceId}.${model.table}".`,
+      );
+    }
+    if (!sameStorageType(junctionColumn, modelColumn)) {
+      throw fail(
+        `joins "${input.junctionTable}.${junctionColumnName}" (${describeColumnType(junctionColumn)}) with "${model.table}.${modelColumnName}" (${describeColumnType(modelColumn)}) of differing storage type; junction columns must match the type of the column they reference.`,
+      );
+    }
+  }
+}
+
+/**
+ * Validates that every N:M relation's `through` descriptor is consistent with
+ * the storage columns it joins: both join sides match in column count,
+ * reference columns that exist in their tables, and pair columns of the same
+ * storage type. Without this, a `through` that disagrees with storage surfaces
+ * as a silently wrong JOIN at query time rather than a validation error here.
+ */
+function validateRelationThroughConsistency(contract: Contract<SqlStorage>): void {
+  for (const [namespaceId, namespace] of Object.entries(contract.domain.namespaces)) {
+    for (const [modelName, model] of Object.entries(namespace.models)) {
+      for (const [relationName, relation] of Object.entries(model.relations)) {
+        if (relation.cardinality !== 'N:M') continue;
+        const qualifiedName = `${namespaceId}.${modelName}.${relationName}`;
+        const { on, through } = relation;
+        const modelStorage = blindCast<SqlModelStorage, 'SQL contract model storage'>(
+          model.storage,
+        );
+        // Parent side: the owning model's localFields (domain field names) join
+        // the junction's parentColumns (storage columns).
+        validateThroughJoinSide({
+          contract,
+          qualifiedName,
+          modelColumns: on.localFields,
+          modelColumnsLabel: 'on.localFields',
+          model: {
+            namespaceId,
+            table: modelStorage.table,
+            fieldToColumn: modelStorage.fields,
+          },
+          junctionColumns: through.parentColumns,
+          junctionColumnsLabel: 'through.parentColumns',
+          junctionNamespaceId: through.namespaceId,
+          junctionTable: through.table,
+        });
+        // Child side: the junction's childColumns join the target model's
+        // targetColumns. Length and junction-column existence are checked
+        // regardless; a cross-space target lives in another contract, so its
+        // column existence and type are checked only when it is resolvable here.
+        const targetModel =
+          relation.to.space === undefined
+            ? contract.domain.namespaces[relation.to.namespace]?.models[relation.to.model]
+            : undefined;
+        const targetModelSide =
+          targetModel === undefined
+            ? undefined
+            : {
+                namespaceId: relation.to.namespace,
+                table: blindCast<SqlModelStorage, 'SQL contract model storage'>(targetModel.storage)
+                  .table,
+              };
+        validateThroughJoinSide({
+          contract,
+          qualifiedName,
+          modelColumns: through.targetColumns,
+          modelColumnsLabel: 'through.targetColumns',
+          ...ifDefined('model', targetModelSide),
+          junctionColumns: through.childColumns,
+          junctionColumnsLabel: 'through.childColumns',
+          junctionNamespaceId: through.namespaceId,
+          junctionTable: through.table,
+        });
+      }
+    }
+  }
+}

package/dist/sql-storage-CXf9xjAL.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sql-storage-CXf9xjAL.d.mts","names":[],"sources":["../src/ir/check-constraint.ts","../src/ir/primary-key.ts","../src/ir/sql-index.ts","../src/ir/storage-column.ts","../src/ir/unique-constraint.ts","../src/ir/storage-table.ts","../src/ir/storage-type-instance.ts","../src/ir/storage-value-set.ts","../src/ir/sql-storage.ts"],"mappings":"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"}

package/dist/types-DEnWD3xB.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types-DEnWD3xB.d.mts","names":[],"sources":["../src/ir/build-sql-namespace.ts","../src/ir/postgres-enum-storage-entry.ts","../src/ir/sql-unbound-namespace.ts","../src/types.ts"],"mappings":"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"}