@prisma-next/sql-contract 0.14.0-dev.5 → 0.14.0-dev.50

package/src/ir/sql-storage.ts

@@ -1,5 +1,12 @@
 import type { StorageHashBase } from '@prisma-next/contract/types';
-import { freezeNode, type Namespace, type Storage } from '@prisma-next/framework-components/ir';
+import type { AuthoringContributions } from '@prisma-next/framework-components/authoring';
+import {
+  freezeNode,
+  isPlainRecord,
+  type Namespace,
+  NamespaceBase,
+  type Storage,
+} from '@prisma-next/framework-components/ir';
 import { SqlNode } from './sql-node';
 import type { StorageTable } from './storage-table';
 import {
@@ -19,15 +26,45 @@ import type { StorageValueSet } from './storage-value-set';
  */
 export type SqlStorageTypeEntry = StorageTypeInstance | StorageTypeInstanceInput;
 
-export interface SqlNamespaceTablesInput {
+export interface SqlNamespaceInput {
   readonly id: string;
   readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
 }
 
+/**
+ * Target-supplied factory that materializes a `Namespace` from a SQL
+ * `SqlNamespaceInput` (used to populate `SqlStorage.namespaces`).
+ */
+export type SqlNamespaceFactory = (input: SqlNamespaceInput) => Namespace;
+
+/**
+ * SQL-family extension of the framework `AuthoringContributions`. SQL target
+ * packs add a `createNamespace` factory so the PSL/TS authoring paths can
+ * materialize namespaces (and merge lowered extension-block entities) without
+ * each consumer re-specifying it. The factory is SQL-specific, so it lives here
+ * rather than on the framework `AuthoringContributions` base.
+ */
+export interface SqlAuthoringContributions extends AuthoringContributions {
+  readonly createNamespace?: SqlNamespaceFactory;
+}
+
+/**
+ * Narrows framework `AuthoringContributions` to the SQL-family shape by testing
+ * for the SQL-specific `createNamespace` capability.
+ */
+export function isSqlAuthoringContributions(
+  authoring: AuthoringContributions | undefined,
+): authoring is SqlAuthoringContributions {
+  if (authoring === undefined || !Object.hasOwn(authoring, 'createNamespace')) {
+    return false;
+  }
+  return typeof Reflect.get(authoring, 'createNamespace') === 'function';
+}
+
 export interface SqlStorageInput<THash extends string = string> {
   readonly storageHash: StorageHashBase<THash>;
   readonly types?: Record<string, SqlStorageTypeEntry>;
-  readonly namespaces: Readonly<Record<string, SqlNamespace>>;
+  readonly namespaces: Readonly<Record<string, SqlNamespaceBase>>;
 }
 
 /**
@@ -63,22 +100,48 @@ export type SqlNamespaceEntries = Readonly<Record<string, Readonly<Record<string
 };
 
 /**
- * SQL family namespace. `entries` is the open ADR 224 dictionary —
- * `entries[entityKind][entityName]` addresses any entity. Emitted
- * contract literals satisfy this structurally (no prototype getters
- * needed). For typed access to specific kinds, use the class getters
- * on the concretion or `ns.entries.table` / `ns.entries.valueSet` directly.
+ * Structural interface for SQL family namespaces. Generated `.d.ts` contract
+ * types satisfy this structurally (no prototype methods). The runtime
+ * abstract class `SqlNamespaceBase` extends this.
+ *
+ * `qualifyTable` is optional so JSON-shaped contract types (which carry no
+ * methods) are accepted where `SqlNamespace` is required. Hydrated
+ * `SqlNamespaceBase` instances always have it.
  */
-export type SqlNamespace = Namespace & {
+export interface SqlNamespace {
+  readonly kind: string;
+  readonly id: string;
   readonly entries: SqlNamespaceEntries;
-  /**
-   * Render a dialect-qualified table reference for runtime SQL emission.
-   * Present on materialised target concretions (`PostgresSchema`,
-   * `SqliteDatabase`, …) and family placeholders; omitted on emitted
-   * contract structural namespace literals (methods are not serialised).
-   */
   qualifyTable?(tableName: string): string;
-};
+}
+
+/**
+ * Abstract SQL family namespace base class. Target concretions (`PostgresSchema`,
+ * `SqliteDatabase`, …) extend this — it is never instantiated directly.
+ * `entries` is the open ADR 224 dictionary: `entries[entityKind][entityName]`
+ * addresses any entity.
+ */
+export abstract class SqlNamespaceBase extends NamespaceBase implements SqlNamespace {
+  abstract override readonly id: string;
+  abstract override readonly entries: SqlNamespaceEntries;
+
+  abstract qualifyTable(tableName: string): string;
+}
+
+/**
+ * Realm-safe guard for hydrated `SqlNamespaceBase` concretions. Checks
+ * `qualifyTable` structurally instead of `instanceof NamespaceBase`, so it
+ * survives duplicate-module boundaries (e.g. dist e2e where the target and
+ * the family carry separate copies of `@prisma-next/framework-components`).
+ *
+ * Every concrete `SqlNamespaceBase` subclass (`PostgresSchema`, `SqliteDatabase`,
+ * `TestSqlNamespace`, …) implements `qualifyTable`. Raw `SqlNamespaceInput`
+ * objects (`{ id, entries }`) do not.
+ */
+export function isMaterializedSqlNamespace(x: unknown): x is SqlNamespaceBase {
+  if (typeof x !== 'object' || x === null || !('qualifyTable' in x)) return false;
+  return typeof x.qualifyTable === 'function';
+}
 
 export class SqlStorage<THash extends string = string> extends SqlNode implements Storage {
   readonly storageHash: StorageHashBase<THash>;
@@ -128,7 +191,7 @@ function normaliseTypeEntry(name: string, entry: SqlStorageTypeEntry): StorageTy
     }
     return toStorageTypeInstance(entry);
   }
-  const rawKind = (entry as { kind?: unknown }).kind;
+  const rawKind = isPlainRecord(entry) ? entry['kind'] : undefined;
   const kindDescription =
     rawKind === undefined
       ? 'missing `kind` discriminator'

package/src/ir/storage-column.ts

@@ -16,6 +16,7 @@ export interface StorageColumnInput {
   readonly nativeType: string;
   readonly codecId: string;
   readonly nullable: boolean;
+  readonly many?: boolean;
   readonly typeParams?: Record<string, unknown>;
   readonly typeRef?: string;
   readonly default?: ColumnDefault;
@@ -40,6 +41,7 @@ export class StorageColumn extends SqlNode {
   readonly nativeType: string;
   readonly codecId: string;
   readonly nullable: boolean;
+  declare readonly many?: boolean;
   declare readonly typeParams?: Record<string, unknown>;
   declare readonly typeRef?: string;
   declare readonly default?: ColumnDefault;
@@ -51,6 +53,7 @@ export class StorageColumn extends SqlNode {
     this.nativeType = input.nativeType;
     this.codecId = input.codecId;
     this.nullable = input.nullable;
+    if (input.many !== undefined) this.many = input.many;
     if (input.typeParams !== undefined) this.typeParams = input.typeParams;
     if (input.typeRef !== undefined) this.typeRef = input.typeRef;
     if (input.default !== undefined) this.default = input.default;

package/src/ir/storage-entry-schemas.ts

@@ -39,6 +39,7 @@ const StorageColumnSchema = type({
   nativeType: 'string',
   codecId: 'string',
   nullable: 'boolean',
+  'many?': 'boolean',
   'typeParams?': 'Record<string, unknown>',
   'typeRef?': 'string',
   'default?': ColumnDefaultSchema,

package/src/ir/storage-table.ts

@@ -68,4 +68,25 @@ export class StorageTable extends SqlNode {
     }
     freezeNode(this);
   }
+
+  /**
+   * Runtime guard that a namespace `table` entry is really a `StorageTable`.
+   * The compiler already types the entry as `StorageTable`, but a
+   * freshly-deserialized contract may carry plain JSON at that slot until
+   * hydration; this duck-types the structural shape. Accepts `undefined` so
+   * optional-chained entry lookups pass straight through.
+   */
+  static is(value: StorageTable | undefined): value is StorageTable {
+    if (typeof value !== 'object' || value === null) return false;
+    return 'columns' in value && 'uniques' in value && 'indexes' in value && 'foreignKeys' in value;
+  }
+
+  static assert(
+    value: StorageTable | undefined,
+    coordinate: string,
+  ): asserts value is StorageTable {
+    if (!StorageTable.is(value)) {
+      throw new Error(`Expected a StorageTable at ${coordinate}`);
+    }
+  }
 }

package/src/ir/storage-value-set.ts

@@ -41,3 +41,8 @@ export class StorageValueSet extends SqlNode {
     freezeNode(this);
   }
 }
+
+export function isStorageValueSet(value: unknown): value is StorageValueSet {
+  if (typeof value !== 'object' || value === null) return false;
+  return 'kind' in value && value.kind === 'valueSet' && 'values' in value;
+}

package/src/types.ts

@@ -10,7 +10,6 @@ export interface SqlControlDriverInstance<T extends string = string>
   ): Promise<{ readonly rows: Row[] }>;
 }
 
-export { buildSqlNamespace, buildSqlNamespaceMap } from './ir/build-sql-namespace';
 export { CheckConstraint, type CheckConstraintInput } from './ir/check-constraint';
 export {
   ForeignKey,
@@ -25,14 +24,18 @@ export { PrimaryKey, type PrimaryKeyInput } from './ir/primary-key';
 export { Index, type IndexInput } from './ir/sql-index';
 export { SqlNode } from './ir/sql-node';
 export {
+  isMaterializedSqlNamespace,
+  isSqlAuthoringContributions,
+  type SqlAuthoringContributions,
   type SqlNamespace,
+  SqlNamespaceBase,
   type SqlNamespaceEntries,
-  type SqlNamespaceTablesInput,
+  type SqlNamespaceFactory,
+  type SqlNamespaceInput,
   SqlStorage,
   type SqlStorageInput,
   type SqlStorageTypeEntry,
 } from './ir/sql-storage';
-export { SqlUnboundNamespace } from './ir/sql-unbound-namespace';
 export { StorageColumn, type StorageColumnInput } from './ir/storage-column';
 export { StorageTable, type StorageTableInput } from './ir/storage-table';
 export {
@@ -42,7 +45,11 @@ export {
   type StorageTypeInstanceInput,
   toStorageTypeInstance,
 } from './ir/storage-type-instance';
-export { StorageValueSet, type StorageValueSetInput } from './ir/storage-value-set';
+export {
+  isStorageValueSet,
+  StorageValueSet,
+  type StorageValueSetInput,
+} from './ir/storage-value-set';
 export {
   UniqueConstraint,
   type UniqueConstraintInput,
@@ -83,16 +90,25 @@ export function applyFkDefaults(
 // Shared by the output and input field-type maps and their extractors.
 export type NamespacedFieldTypeMap = Record<string, Record<string, Record<string, unknown>>>;
 
+export type NamespacedStorageColumnTypeMap = Record<
+  string,
+  Record<string, Record<string, unknown>>
+>;
+
 export type TypeMaps<
   TCodecTypes extends Record<string, { output: unknown }> = Record<string, never>,
   TQueryOperationTypes extends Record<string, unknown> = Record<string, never>,
   TFieldOutputTypes extends NamespacedFieldTypeMap = Record<string, never>,
   TFieldInputTypes extends NamespacedFieldTypeMap = Record<string, never>,
+  TStorageColumnTypes extends NamespacedStorageColumnTypeMap = Record<string, never>,
+  TStorageColumnInputTypes extends NamespacedStorageColumnTypeMap = Record<string, never>,
 > = {
   readonly codecTypes: TCodecTypes;
   readonly queryOperationTypes: TQueryOperationTypes;
   readonly fieldOutputTypes: TFieldOutputTypes;
   readonly fieldInputTypes: TFieldInputTypes;
+  readonly storageColumnTypes: TStorageColumnTypes;
+  readonly storageColumnInputTypes: TStorageColumnInputTypes;
 };
 
 export type CodecTypesOf<T> = [T] extends [never]
@@ -107,12 +123,19 @@ export type CodecTypesOf<T> = [T] extends [never]
  * Dispatch hint identifying the first-argument target of an operation.
  *
  * Used by ORM column helpers to decide whether an operation is reachable on a
- * field. Either names a concrete codec identity or a set of capability traits
- * that the field's codec must carry.
+ * field. Names a concrete codec identity, a set of capability traits the
+ * field's codec must carry, or targets list-typed (`many`) fields. Element
+ * capability gating for list ops travels in `elementTraits`.
  */
 export type QueryOperationSelfSpec =
-  | { readonly codecId: string; readonly traits?: never }
-  | { readonly traits: readonly CodecTrait[]; readonly codecId?: never };
+  | { readonly codecId: string; readonly traits?: never; readonly many?: never }
+  | { readonly traits: readonly CodecTrait[]; readonly codecId?: never; readonly many?: never }
+  | {
+      readonly many: true;
+      readonly elementTraits?: readonly CodecTrait[];
+      readonly codecId?: never;
+      readonly traits?: never;
+    };
 
 /**
  * Structural shape an operation's impl must return: any value carrying a
@@ -172,10 +195,30 @@ export type FieldInputTypesOf<T> = [T] extends [never]
       : Record<string, never>
     : Record<string, never>;
 
+export type StorageColumnTypesOf<T> = [T] extends [never]
+  ? Record<string, never>
+  : T extends { readonly storageColumnTypes: infer F }
+    ? F extends NamespacedStorageColumnTypeMap
+      ? F
+      : Record<string, never>
+    : Record<string, never>;
+
+export type StorageColumnInputTypesOf<T> = [T] extends [never]
+  ? Record<string, never>
+  : T extends { readonly storageColumnInputTypes: infer F }
+    ? F extends NamespacedStorageColumnTypeMap
+      ? F
+      : Record<string, never>
+    : Record<string, never>;
+
 export type ExtractCodecTypes<T> = CodecTypesOf<ExtractTypeMapsFromContract<T>>;
 export type ExtractQueryOperationTypes<T> = QueryOperationTypesOf<ExtractTypeMapsFromContract<T>>;
 export type ExtractFieldOutputTypes<T> = FieldOutputTypesOf<ExtractTypeMapsFromContract<T>>;
 export type ExtractFieldInputTypes<T> = FieldInputTypesOf<ExtractTypeMapsFromContract<T>>;
+export type ExtractStorageColumnTypes<T> = StorageColumnTypesOf<ExtractTypeMapsFromContract<T>>;
+export type ExtractStorageColumnInputTypes<T> = StorageColumnInputTypesOf<
+  ExtractTypeMapsFromContract<T>
+>;
 
 export type ResolveCodecTypes<TContract, TTypeMaps> = [TTypeMaps] extends [never]
   ? ExtractCodecTypes<TContract>

package/src/validators.ts

@@ -10,13 +10,11 @@ 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,
@@ -32,13 +30,12 @@ export {
   StorageValueSetSchema,
 } from './ir/storage-entry-schemas';
 
-import { SqlUnboundNamespace } from './ir/sql-unbound-namespace';
-import {
-  type SqlModelStorage,
+import type {
+  SqlModelStorage,
   SqlStorage,
-  type SqlStorageInput,
-  type StorageTable,
-  type StorageTypeInstanceInput,
+  StorageColumn,
+  StorageTable,
+  StorageTypeInstanceInput,
 } from './types';
 
 const generatorKindSchema = type("'generator'");
@@ -192,9 +189,8 @@ export function createSqlStorageSchema(
     'types?': type({ '[string]': DocumentScopedStorageTypeSchema }),
     // `__unbound__` is NOT required here: cross-namespace contracts can
     // declare only named namespaces (see cross-namespace FK fixtures). The
-    // `__unbound__` brand on `SqlStorageInput['namespaces']` is kept sound at
-    // construction time by injecting the unbound singleton when absent
-    // (see `validateStorage` / `hydrateSqlStorage`), not by structural require.
+    // unbound slot is injected when absent by `ensureUnboundNamespaceSlot`
+    // in `build-contract.ts`, not enforced here structurally.
     'namespaces?': type({ '[string]': namespaceEntry }),
   }) as Type<unknown>;
 }
@@ -368,45 +364,21 @@ export function 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
-// includes bigint | Date (runtime-only types after decoding) which cannot be expressed
-// in Arktype's JSON validation DSL. The `as SqlStorage` cast in validateStorage() bridges
-// the gap between the JSON-safe Arktype output and the runtime TypeScript type.
-
 /**
- * Validates the structural shape of SqlStorage using Arktype.
+ * Validates the structural shape of SqlStorage using Arktype. Pure
+ * structural check: namespace IR is never materialized here (that needs
+ * a target concretion via the serializer hydration path), so this throws
+ * on invalid input and constructs nothing.
  *
  * @param value - The storage value to validate
- * @returns The validated storage if structure is valid
  * @throws Error if the storage structure is invalid
  */
-export function validateStorage(value: unknown): SqlStorage {
+export function validateStorage(value: unknown): void {
   const result = StorageSchema(value);
   if (result instanceof type.errors) {
     const messages = result.map((p: { message: string }) => p.message).join('; ');
     throw new Error(`Storage validation failed: ${messages}`);
   }
-  // Arktype validates the JSON-safe envelope, but the `ColumnDefault`
-  // union carries runtime-only `bigint | Date` that the validation DSL
-  // can't express (see NOTE above), so bridge the validated shape to the
-  // input type. Construction below re-materialises nested IR fields.
-  const validated = blindCast<
-    SqlStorageInput & { readonly namespaces?: SqlStorageInput['namespaces'] },
-    'arktype validated the JSON envelope but its output type is unknown (ColumnDefault carries runtime-only bigint|Date); bridge to the input shape'
-  >(result);
-  const namespaces = buildSqlNamespaceMap(validated.namespaces ?? {});
-  // Compatibility shim: inject the empty unbound singleton when absent so that
-  // production code paths which address __unbound__ for table metadata have a
-  // slot to read or write into. The `SqlStorageInput['namespaces']` type no
-  // longer requires __unbound__, so this is a runtime convenience, not a type
-  // invariant.
-  const unbound = namespaces[UNBOUND_NAMESPACE_ID] ?? SqlUnboundNamespace.instance;
-  return new SqlStorage({
-    storageHash: validated.storageHash,
-    ...ifDefined('types', validated.types),
-    namespaces: { ...namespaces, [UNBOUND_NAMESPACE_ID]: unbound },
-  });
 }
 
 export function validateModel(value: unknown): unknown {
@@ -846,5 +818,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/src/value-set-derivation-hook.ts

@@ -0,0 +1,47 @@
+import type { StorageValueSetInput } from './ir/storage-value-set';
+
+/**
+ * SQL-family extension to the framework entity-type authoring registry: a pack's entity-type
+ * `factory` output (framework `AuthoringEntityTypeFactoryOutput`) may derive a value-set from an
+ * entity it built (e.g. Postgres's `native_enum` deriving its ordered member values). The generic
+ * extension-block lowering pass (`contract-psl`'s interpreter) probes each entity-type descriptor's
+ * output for this hook after building the entity, and folds a non-undefined result into the same
+ * namespace's `valueSet` slot, keyed by the entity's block name.
+ *
+ * SQL-family concept — the returned shape ({@link StorageValueSetInput}) is SQL-specific, so this
+ * hook lives here instead of on the framework `AuthoringEntityTypeFactoryOutput` itself.
+ */
+export interface SqlValueSetDerivingEntityTypeOutput {
+  /**
+   * TypeScript treats method-syntax declarations bivariantly, so a pack's concretely-typed
+   * `deriveValueSet(entity: PostgresNativeEnum) => …` is structurally compatible with this
+   * interface's `unknown` parameter — no `never`-parameter contravariance bridge needed.
+   */
+  deriveValueSet(entity: unknown): StorageValueSetInput | undefined;
+}
+
+/** Structural check for {@link SqlValueSetDerivingEntityTypeOutput}: no casts. */
+export function providesValueSetDerivation(
+  output: unknown,
+): output is SqlValueSetDerivingEntityTypeOutput {
+  if (typeof output !== 'object' || output === null || !('deriveValueSet' in output)) {
+    return false;
+  }
+  const { deriveValueSet } = output;
+  return typeof deriveValueSet === 'function';
+}
+
+/**
+ * If `output` (an entity-type descriptor's factory output) provides
+ * {@link SqlValueSetDerivingEntityTypeOutput.deriveValueSet}, invoke it on `entity` and return the
+ * derived value-set; otherwise return `undefined`. `contract-psl`'s generic extension-block
+ * lowering pass calls this after building each entity so a value-set-carrying pack entity can
+ * contribute its value-set without the pass naming any target discriminator.
+ */
+export function deriveValueSetFromEntity(
+  output: unknown,
+  entity: unknown,
+): StorageValueSetInput | undefined {
+  if (!providesValueSetDerivation(output)) return undefined;
+  return output.deriveValueSet(entity);
+}