@prisma-next/sql-contract 0.14.0 → 0.15.0-dev.1

package/dist/types.mjs

@@ -1,3 +1,115 @@
-import { a as StorageTable, c as Index, d as ForeignKeyReference, f as CheckConstraint, i as StorageValueSet, l as PrimaryKey, o as UniqueConstraint, p as SqlNode, s as StorageColumn, u as ForeignKey } from "./entity-kinds-Cl36zL5j.mjs";
-import { a as CODEC_INSTANCE_KIND, c as buildSqlNamespace, i as SqlStorage, l as buildSqlNamespaceMap, n as DEFAULT_FK_INDEX, o as isStorageTypeInstance, r as applyFkDefaults, s as toStorageTypeInstance, t as DEFAULT_FK_CONSTRAINT, u as SqlUnboundNamespace } from "./types-B-eiQXff.mjs";
-export { CODEC_INSTANCE_KIND, CheckConstraint, DEFAULT_FK_CONSTRAINT, DEFAULT_FK_INDEX, ForeignKey, ForeignKeyReference, Index, PrimaryKey, SqlNode, SqlStorage, SqlUnboundNamespace, StorageColumn, StorageTable, StorageValueSet, UniqueConstraint, applyFkDefaults, buildSqlNamespace, buildSqlNamespaceMap, isStorageTypeInstance, toStorageTypeInstance };
+import { a as PrimaryKey, c as CheckConstraint, i as Index, l as SqlNode, n as UniqueConstraint, o as ForeignKey, r as StorageColumn, s as ForeignKeyReference, t as StorageTable } from "./storage-table-DBpYBmty.mjs";
+import { n as isStorageValueSet, t as StorageValueSet } from "./storage-value-set-3BKuha5q.mjs";
+import { NamespaceBase, freezeNode, isPlainRecord } from "@prisma-next/framework-components/ir";
+//#region src/ir/storage-type-instance.ts
+/**
+* Sentinel kind for the legacy codec-triple shape persisted under
+* `SqlStorage.types`. Plain JSON-clean object literals carry this
+* discriminator so the polymorphic slot dispatch can route them down
+* the codec path while target-specific IR class instances (e.g. the
+* Postgres enum class) keep their own narrower `kind` literal.
+*/
+const CODEC_INSTANCE_KIND = "codec-instance";
+/**
+* Stamp the codec-instance `kind` discriminator on a caller-supplied
+* codec triple. Idempotent: input that already carries the discriminator
+* passes through unchanged. Missing `typeParams` is normalised to `{}`.
+*/
+function toStorageTypeInstance(input) {
+	return {
+		kind: CODEC_INSTANCE_KIND,
+		codecId: input.codecId,
+		nativeType: input.nativeType,
+		typeParams: input.typeParams ?? {}
+	};
+}
+/**
+* Type-guard for codec-typed entries on the polymorphic
+* `SqlStorage.types` slot. Distinguishes `StorageTypeInstance` from
+* any class-instance kinds a target pack contributes.
+*/
+function isStorageTypeInstance(value) {
+	if (typeof value !== "object" || value === null) return false;
+	return value.kind === CODEC_INSTANCE_KIND;
+}
+//#endregion
+//#region src/ir/sql-storage.ts
+/**
+* Narrows framework `AuthoringContributions` to the SQL-family shape by testing
+* for the SQL-specific `createNamespace` capability.
+*/
+function isSqlAuthoringContributions(authoring) {
+	if (authoring === void 0 || !Object.hasOwn(authoring, "createNamespace")) return false;
+	return typeof Reflect.get(authoring, "createNamespace") === "function";
+}
+/**
+* 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.
+*/
+var SqlNamespaceBase = class extends NamespaceBase {};
+/**
+* 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.
+*/
+function isMaterializedSqlNamespace(x) {
+	if (typeof x !== "object" || x === null || !("qualifyTable" in x)) return false;
+	return typeof x.qualifyTable === "function";
+}
+var SqlStorage = class extends SqlNode {
+	storageHash;
+	namespaces;
+	constructor(input) {
+		super();
+		this.storageHash = input.storageHash;
+		this.namespaces = Object.freeze(input.namespaces);
+		if (input.types !== void 0) this.types = Object.freeze(Object.fromEntries(Object.entries(input.types).map(([name, ti]) => [name, normaliseTypeEntry(name, ti)])));
+		freezeNode(this);
+	}
+};
+/**
+* Strict polymorphic-slot dispatch for `SqlStorage.types` entries.
+* Every entry must carry a `kind: 'codec-instance'` discriminator or
+* be an already-constructed `StorageTypeInstance`. Untagged or
+* unrecognised inputs throw a diagnostic naming the entry and its
+* `kind`, so format drift surfaces loudly at the deserializer
+* boundary instead of slipping past the seam and corrupting
+* downstream IR walks.
+*
+* Codec-triple authors that have an untagged shape on hand can call
+* `toStorageTypeInstance(...)` (which stamps the `'codec-instance'`
+* discriminator) before constructing `SqlStorage`. On-disk reads
+* cross `familyInstance.deserializeContract` first; the structural
+* arktype schema rejects untagged entries earlier, so this throw
+* only fires for in-memory authoring bugs.
+*/
+function normaliseTypeEntry(name, entry) {
+	if (isStorageTypeInstance(entry)) {
+		if ("typeParams" in entry) return entry;
+		return toStorageTypeInstance(entry);
+	}
+	const rawKind = isPlainRecord(entry) ? entry["kind"] : void 0;
+	const kindDescription = rawKind === void 0 ? "missing `kind` discriminator" : `unrecognised \`kind\` discriminator ${JSON.stringify(rawKind)}`;
+	throw new Error(`storage.types[${JSON.stringify(name)}] has ${kindDescription}; expected ${JSON.stringify("codec-instance")}. Untagged codec triples should be wrapped with toStorageTypeInstance(...) before construction.`);
+}
+//#endregion
+//#region src/types.ts
+const DEFAULT_FK_CONSTRAINT = true;
+const DEFAULT_FK_INDEX = true;
+function applyFkDefaults(fk, overrideDefaults) {
+	return {
+		constraint: fk.constraint ?? overrideDefaults?.constraint ?? true,
+		index: fk.index ?? overrideDefaults?.index ?? true
+	};
+}
+//#endregion
+export { CODEC_INSTANCE_KIND, CheckConstraint, DEFAULT_FK_CONSTRAINT, DEFAULT_FK_INDEX, ForeignKey, ForeignKeyReference, Index, PrimaryKey, SqlNamespaceBase, SqlNode, SqlStorage, StorageColumn, StorageTable, StorageValueSet, UniqueConstraint, applyFkDefaults, isMaterializedSqlNamespace, isSqlAuthoringContributions, isStorageTypeInstance, isStorageValueSet, toStorageTypeInstance };
+
+//# sourceMappingURL=types.mjs.map

package/dist/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","names":[],"sources":["../src/ir/storage-type-instance.ts","../src/ir/sql-storage.ts","../src/types.ts"],"sourcesContent":["import type { StorageType } from '@prisma-next/framework-components/ir';\n\n/**\n * Sentinel kind for the legacy codec-triple shape persisted under\n * `SqlStorage.types`. Plain JSON-clean object literals carry this\n * discriminator so the polymorphic slot dispatch can route them down\n * the codec path while target-specific IR class instances (e.g. the\n * Postgres enum class) keep their own narrower `kind` literal.\n */\nexport const CODEC_INSTANCE_KIND = 'codec-instance' as const;\n\n/**\n * Structural sub-interface of {@link StorageType} for codec-typed entries\n * in `SqlStorage.types`. These are plain object literals — there is no\n * runtime IR class, the JSON envelope round-trips through the slot\n * unchanged. The `kind: 'codec-instance'` discriminator is the dispatch\n * key that distinguishes codec-typed entries from any class-instance\n * kinds a target pack contributes to the polymorphic slot.\n */\nexport interface StorageTypeInstance extends StorageType {\n  readonly kind: typeof CODEC_INSTANCE_KIND;\n  readonly codecId: string;\n  readonly nativeType: string;\n  readonly typeParams: Record<string, unknown>;\n}\n\n/**\n * Construction-time input for a codec-triple entry. Symmetric with the\n * structural runtime shape minus the `kind` discriminator — callers may\n * omit `kind`; the helper {@link toStorageTypeInstance} stamps it on.\n * `typeParams` may be omitted on input; the constructor normalises a\n * missing value to `{}` so the in-memory shape is always present.\n */\nexport interface StorageTypeInstanceInput {\n  readonly codecId: string;\n  readonly nativeType: string;\n  readonly typeParams?: Record<string, unknown>;\n}\n\n/**\n * Stamp the codec-instance `kind` discriminator on a caller-supplied\n * codec triple. Idempotent: input that already carries the discriminator\n * passes through unchanged. Missing `typeParams` is normalised to `{}`.\n */\nexport function toStorageTypeInstance(input: StorageTypeInstanceInput): StorageTypeInstance {\n  return {\n    kind: CODEC_INSTANCE_KIND,\n    codecId: input.codecId,\n    nativeType: input.nativeType,\n    typeParams: input.typeParams ?? {},\n  };\n}\n\n/**\n * Type-guard for codec-typed entries on the polymorphic\n * `SqlStorage.types` slot. Distinguishes `StorageTypeInstance` from\n * any class-instance kinds a target pack contributes.\n */\nexport function isStorageTypeInstance(value: unknown): value is StorageTypeInstance {\n  if (typeof value !== 'object' || value === null) return false;\n  return (value as { kind?: unknown }).kind === CODEC_INSTANCE_KIND;\n}\n","import type { StorageHashBase } from '@prisma-next/contract/types';\nimport type { AuthoringContributions } from '@prisma-next/framework-components/authoring';\nimport {\n  freezeNode,\n  isPlainRecord,\n  type Namespace,\n  NamespaceBase,\n  type Storage,\n} from '@prisma-next/framework-components/ir';\nimport { SqlNode } from './sql-node';\nimport type { StorageTable } from './storage-table';\nimport {\n  isStorageTypeInstance,\n  type StorageTypeInstance,\n  type StorageTypeInstanceInput,\n  toStorageTypeInstance,\n} from './storage-type-instance';\nimport type { StorageValueSet } from './storage-value-set';\n\n/**\n * Polymorphic value type for document-scoped `SqlStorage.types` entries\n * (codec aliases / parameterised native type registrations).\n *\n * Postgres native enum registrations live under the postgres-specific\n * `entries.type` slot on `PostgresSchema` (target layer), not here.\n */\nexport type SqlStorageTypeEntry = StorageTypeInstance | StorageTypeInstanceInput;\n\nexport interface SqlNamespaceInput {\n  readonly id: string;\n  readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;\n}\n\n/**\n * Target-supplied factory that materializes a `Namespace` from a SQL\n * `SqlNamespaceInput` (used to populate `SqlStorage.namespaces`).\n */\nexport type SqlNamespaceFactory = (input: SqlNamespaceInput) => Namespace;\n\n/**\n * SQL-family extension of the framework `AuthoringContributions`. SQL target\n * packs add a `createNamespace` factory so the PSL/TS authoring paths can\n * materialize namespaces (and merge lowered extension-block entities) without\n * each consumer re-specifying it. The factory is SQL-specific, so it lives here\n * rather than on the framework `AuthoringContributions` base.\n */\nexport interface SqlAuthoringContributions extends AuthoringContributions {\n  readonly createNamespace?: SqlNamespaceFactory;\n}\n\n/**\n * Narrows framework `AuthoringContributions` to the SQL-family shape by testing\n * for the SQL-specific `createNamespace` capability.\n */\nexport function isSqlAuthoringContributions(\n  authoring: AuthoringContributions | undefined,\n): authoring is SqlAuthoringContributions {\n  if (authoring === undefined || !Object.hasOwn(authoring, 'createNamespace')) {\n    return false;\n  }\n  return typeof Reflect.get(authoring, 'createNamespace') === 'function';\n}\n\nexport interface SqlStorageInput<THash extends string = string> {\n  readonly storageHash: StorageHashBase<THash>;\n  readonly types?: Record<string, SqlStorageTypeEntry>;\n  readonly namespaces: Readonly<Record<string, SqlNamespaceBase>>;\n}\n\n/**\n * SQL Contract IR root node for the `storage` field.\n *\n * Single concrete family-shared class — both Postgres and SQLite\n * consume this class today. Per-target storage subclasses are\n * introduced when each target's namespace shape earns its\n * target-specific concretion (target-specific derived fields,\n * target-specific storage extensions).\n *\n * Honours the framework `Storage` interface: every SQL IR carries a\n * `namespaces` map keyed by namespace id. Callers must supply fully\n * constructed `Namespace` instances — construction discipline lives\n * in the authoring builders and deserializer hydration paths.\n *\n * The constructor normalises optional `types` into class instances.\n * `types` is polymorphic per Decision 18 Option B: codec-triple inputs\n * are stamped with `kind: 'codec-instance'`; hydration of raw JSON\n * class-instance entries (carrying their narrower `kind` literal) is\n * the per-target serializer's responsibility (so the family base does\n * not import target-specific subclasses).\n */\n/**\n * The typed `entries` shape for SQL family namespaces. The open dictionary\n * is intersected with optional known-kind maps so that `ns.entries.table`\n * and `ns.entries.valueSet` resolve without a cast, while unknown pack-\n * contributed kinds remain valid (the `Record` part allows any string key).\n */\nexport type SqlNamespaceEntries = Readonly<Record<string, Readonly<Record<string, unknown>>>> & {\n  readonly table?: Readonly<Record<string, StorageTable>>;\n  readonly valueSet?: Readonly<Record<string, StorageValueSet>>;\n};\n\n/**\n * Structural interface for SQL family namespaces. Generated `.d.ts` contract\n * types satisfy this structurally (no prototype methods). The runtime\n * abstract class `SqlNamespaceBase` extends this.\n *\n * `qualifyTable` and `isUnbound` are optional so JSON-shaped contract types\n * (which carry no methods) are accepted where `SqlNamespace` is required.\n * Hydrated `SqlNamespaceBase` instances always have both.\n */\nexport interface SqlNamespace {\n  readonly kind: string;\n  readonly id: string;\n  readonly entries: SqlNamespaceEntries;\n  readonly isUnbound?: boolean;\n  qualifyTable?(tableName: string): string;\n}\n\n/**\n * Abstract SQL family namespace base class. Target concretions (`PostgresSchema`,\n * `SqliteDatabase`, …) extend this — it is never instantiated directly.\n * `entries` is the open ADR 224 dictionary: `entries[entityKind][entityName]`\n * addresses any entity.\n */\nexport abstract class SqlNamespaceBase extends NamespaceBase implements SqlNamespace {\n  abstract override readonly id: string;\n  abstract override readonly entries: SqlNamespaceEntries;\n\n  abstract qualifyTable(tableName: string): string;\n}\n\n/**\n * Realm-safe guard for hydrated `SqlNamespaceBase` concretions. Checks\n * `qualifyTable` structurally instead of `instanceof NamespaceBase`, so it\n * survives duplicate-module boundaries (e.g. dist e2e where the target and\n * the family carry separate copies of `@prisma-next/framework-components`).\n *\n * Every concrete `SqlNamespaceBase` subclass (`PostgresSchema`, `SqliteDatabase`,\n * `TestSqlNamespace`, …) implements `qualifyTable`. Raw `SqlNamespaceInput`\n * objects (`{ id, entries }`) do not.\n */\nexport function isMaterializedSqlNamespace(x: unknown): x is SqlNamespaceBase {\n  if (typeof x !== 'object' || x === null || !('qualifyTable' in x)) return false;\n  return typeof x.qualifyTable === 'function';\n}\n\nexport class SqlStorage<THash extends string = string> extends SqlNode implements Storage {\n  readonly storageHash: StorageHashBase<THash>;\n  readonly namespaces: Readonly<Record<string, SqlNamespace>>;\n  declare readonly types?: Readonly<Record<string, StorageTypeInstance>>;\n\n  constructor(input: SqlStorageInput<THash>) {\n    super();\n    this.storageHash = input.storageHash;\n    this.namespaces = Object.freeze(input.namespaces);\n    if (input.types !== undefined) {\n      this.types = Object.freeze(\n        Object.fromEntries(\n          Object.entries(input.types).map(([name, ti]) => [name, normaliseTypeEntry(name, ti)]),\n        ),\n      );\n    }\n    freezeNode(this);\n  }\n}\n\n/**\n * Strict polymorphic-slot dispatch for `SqlStorage.types` entries.\n * Every entry must carry a `kind: 'codec-instance'` discriminator or\n * be an already-constructed `StorageTypeInstance`. Untagged or\n * unrecognised inputs throw a diagnostic naming the entry and its\n * `kind`, so format drift surfaces loudly at the deserializer\n * boundary instead of slipping past the seam and corrupting\n * downstream IR walks.\n *\n * Codec-triple authors that have an untagged shape on hand can call\n * `toStorageTypeInstance(...)` (which stamps the `'codec-instance'`\n * discriminator) before constructing `SqlStorage`. On-disk reads\n * cross `familyInstance.deserializeContract` first; the structural\n * arktype schema rejects untagged entries earlier, so this throw\n * only fires for in-memory authoring bugs.\n */\nfunction normaliseTypeEntry(name: string, entry: SqlStorageTypeEntry): StorageTypeInstance {\n  if (isStorageTypeInstance(entry)) {\n    // Normalise on-disk objects that omit `typeParams` (the canonical on-disk\n    // form strips empty typeParams to keep JSON compact). The in-memory invariant\n    // is always `typeParams: {}` when empty — never `undefined`. Only create a\n    // new object when necessary to preserve identity-equality for callers that\n    // hold a reference to an already-correct in-memory entry.\n    if ('typeParams' in entry) {\n      return entry;\n    }\n    return toStorageTypeInstance(entry);\n  }\n  const rawKind = isPlainRecord(entry) ? entry['kind'] : undefined;\n  const kindDescription =\n    rawKind === undefined\n      ? 'missing `kind` discriminator'\n      : `unrecognised \\`kind\\` discriminator ${JSON.stringify(rawKind)}`;\n  throw new Error(\n    `storage.types[${JSON.stringify(name)}] has ${kindDescription}; expected ${JSON.stringify('codec-instance')}. Untagged codec triples should be wrapped with toStorageTypeInstance(...) before construction.`,\n  );\n}\n","import type { CodecTrait } from '@prisma-next/framework-components/codec';\nimport type { ControlDriverInstance } from '@prisma-next/framework-components/control';\nimport type { ReferentialAction } from './ir/foreign-key';\n\nexport interface SqlControlDriverInstance<T extends string = string>\n  extends ControlDriverInstance<'sql', T> {\n  query<Row = Record<string, unknown>>(\n    sql: string,\n    params?: readonly unknown[],\n  ): Promise<{ readonly rows: Row[] }>;\n}\n\nexport { CheckConstraint, type CheckConstraintInput } from './ir/check-constraint';\nexport {\n  ForeignKey,\n  type ForeignKeyInput,\n  type ReferentialAction,\n} from './ir/foreign-key';\nexport {\n  ForeignKeyReference,\n  type ForeignKeyReferenceInput,\n} from './ir/foreign-key-reference';\nexport { PrimaryKey, type PrimaryKeyInput } from './ir/primary-key';\nexport { Index, type IndexInput } from './ir/sql-index';\nexport { SqlNode } from './ir/sql-node';\nexport {\n  isMaterializedSqlNamespace,\n  isSqlAuthoringContributions,\n  type SqlAuthoringContributions,\n  type SqlNamespace,\n  SqlNamespaceBase,\n  type SqlNamespaceEntries,\n  type SqlNamespaceFactory,\n  type SqlNamespaceInput,\n  SqlStorage,\n  type SqlStorageInput,\n  type SqlStorageTypeEntry,\n} from './ir/sql-storage';\nexport { StorageColumn, type StorageColumnInput } from './ir/storage-column';\nexport { StorageTable, type StorageTableInput } from './ir/storage-table';\nexport {\n  CODEC_INSTANCE_KIND,\n  isStorageTypeInstance,\n  type StorageTypeInstance,\n  type StorageTypeInstanceInput,\n  toStorageTypeInstance,\n} from './ir/storage-type-instance';\nexport {\n  isStorageValueSet,\n  StorageValueSet,\n  type StorageValueSetInput,\n} from './ir/storage-value-set';\nexport {\n  UniqueConstraint,\n  type UniqueConstraintInput,\n} from './ir/unique-constraint';\n\nexport type ForeignKeyOptions = {\n  readonly name?: string;\n  readonly onDelete?: ReferentialAction;\n  readonly onUpdate?: ReferentialAction;\n};\n\nexport type SqlModelFieldStorage = {\n  readonly column: string;\n  readonly codecId?: string;\n  readonly nullable?: boolean;\n};\n\nexport type SqlModelStorage = {\n  readonly table: string;\n  readonly namespaceId: string;\n  readonly fields: Record<string, SqlModelFieldStorage>;\n};\n\nexport const DEFAULT_FK_CONSTRAINT = true;\nexport const DEFAULT_FK_INDEX = true;\n\nexport function applyFkDefaults(\n  fk: { constraint?: boolean | undefined; index?: boolean | undefined },\n  overrideDefaults?: { constraint?: boolean | undefined; index?: boolean | undefined },\n): { constraint: boolean; index: boolean } {\n  return {\n    constraint: fk.constraint ?? overrideDefaults?.constraint ?? DEFAULT_FK_CONSTRAINT,\n    index: fk.index ?? overrideDefaults?.index ?? DEFAULT_FK_INDEX,\n  };\n}\n\n// Field-type maps nested by namespace coordinate: `[namespaceId][model][field]`.\n// Shared by the output and input field-type maps and their extractors.\nexport type NamespacedFieldTypeMap = Record<string, Record<string, Record<string, unknown>>>;\n\nexport type NamespacedStorageColumnTypeMap = Record<\n  string,\n  Record<string, Record<string, unknown>>\n>;\n\nexport type TypeMaps<\n  TCodecTypes extends Record<string, { output: unknown }> = Record<string, never>,\n  TQueryOperationTypes extends Record<string, unknown> = Record<string, never>,\n  TFieldOutputTypes extends NamespacedFieldTypeMap = Record<string, never>,\n  TFieldInputTypes extends NamespacedFieldTypeMap = Record<string, never>,\n  TStorageColumnTypes extends NamespacedStorageColumnTypeMap = Record<string, never>,\n  TStorageColumnInputTypes extends NamespacedStorageColumnTypeMap = Record<string, never>,\n> = {\n  readonly codecTypes: TCodecTypes;\n  readonly queryOperationTypes: TQueryOperationTypes;\n  readonly fieldOutputTypes: TFieldOutputTypes;\n  readonly fieldInputTypes: TFieldInputTypes;\n  readonly storageColumnTypes: TStorageColumnTypes;\n  readonly storageColumnInputTypes: TStorageColumnInputTypes;\n};\n\nexport type CodecTypesOf<T> = [T] extends [never]\n  ? Record<string, never>\n  : T extends { readonly codecTypes: infer C }\n    ? C extends Record<string, { output: unknown }>\n      ? C\n      : Record<string, never>\n    : Record<string, never>;\n\n/**\n * Dispatch hint identifying the first-argument target of an operation.\n *\n * Used by ORM column helpers to decide whether an operation is reachable on a\n * field. Names a concrete codec identity, a set of capability traits the\n * field's codec must carry, or targets list-typed (`many`) fields. Element\n * capability gating for list ops travels in `elementTraits`.\n */\nexport type QueryOperationSelfSpec =\n  | { readonly codecId: string; readonly traits?: never; readonly many?: never }\n  | { readonly traits: readonly CodecTrait[]; readonly codecId?: never; readonly many?: never }\n  | {\n      readonly many: true;\n      readonly elementTraits?: readonly CodecTrait[];\n      readonly codecId?: never;\n      readonly traits?: never;\n    };\n\n/**\n * Structural shape an operation's impl must return: any value carrying a\n * codec-exact `returnType` descriptor. `Expression<T>` (from\n * `@prisma-next/sql-relational-core/expression`, with `T extends ScopeField`)\n * extends this. Trait-targeted returns are deliberately excluded — predicate\n * detection and result decoding both depend on knowing the concrete return\n * codec.\n */\nexport type QueryOperationReturn = {\n  readonly returnType: { readonly codecId: string; readonly nullable: boolean };\n};\n\nexport type QueryOperationTypeEntry = {\n  readonly self?: QueryOperationSelfSpec;\n  readonly impl: (...args: never[]) => QueryOperationReturn;\n};\n\nexport type SqlQueryOperationTypes<\n  _CT extends Record<string, { readonly input: unknown; readonly output: unknown }>,\n  T extends Record<string, QueryOperationTypeEntry>,\n> = T;\n\nexport type QueryOperationTypesBase = Record<string, QueryOperationTypeEntry>;\n\nexport type QueryOperationTypesOf<T> = [T] extends [never]\n  ? Record<string, never>\n  : T extends { readonly queryOperationTypes: infer Q }\n    ? Q extends Record<string, unknown>\n      ? Q\n      : Record<string, never>\n    : Record<string, never>;\n\nexport type TypeMapsPhantomKey = '__@prisma-next/sql-contract/typeMaps@__';\n\nexport type ContractWithTypeMaps<TContract, TTypeMaps> = TContract & {\n  readonly [K in TypeMapsPhantomKey]?: TTypeMaps;\n};\n\nexport type ExtractTypeMapsFromContract<T> = TypeMapsPhantomKey extends keyof T\n  ? NonNullable<T[TypeMapsPhantomKey & keyof T]>\n  : never;\n\nexport type FieldOutputTypesOf<T> = [T] extends [never]\n  ? Record<string, never>\n  : T extends { readonly fieldOutputTypes: infer F }\n    ? F extends NamespacedFieldTypeMap\n      ? F\n      : Record<string, never>\n    : Record<string, never>;\n\nexport type FieldInputTypesOf<T> = [T] extends [never]\n  ? Record<string, never>\n  : T extends { readonly fieldInputTypes: infer F }\n    ? F extends NamespacedFieldTypeMap\n      ? F\n      : Record<string, never>\n    : Record<string, never>;\n\nexport type StorageColumnTypesOf<T> = [T] extends [never]\n  ? Record<string, never>\n  : T extends { readonly storageColumnTypes: infer F }\n    ? F extends NamespacedStorageColumnTypeMap\n      ? F\n      : Record<string, never>\n    : Record<string, never>;\n\nexport type StorageColumnInputTypesOf<T> = [T] extends [never]\n  ? Record<string, never>\n  : T extends { readonly storageColumnInputTypes: infer F }\n    ? F extends NamespacedStorageColumnTypeMap\n      ? F\n      : Record<string, never>\n    : Record<string, never>;\n\nexport type ExtractCodecTypes<T> = CodecTypesOf<ExtractTypeMapsFromContract<T>>;\nexport type ExtractQueryOperationTypes<T> = QueryOperationTypesOf<ExtractTypeMapsFromContract<T>>;\nexport type ExtractFieldOutputTypes<T> = FieldOutputTypesOf<ExtractTypeMapsFromContract<T>>;\nexport type ExtractFieldInputTypes<T> = FieldInputTypesOf<ExtractTypeMapsFromContract<T>>;\nexport type ExtractStorageColumnTypes<T> = StorageColumnTypesOf<ExtractTypeMapsFromContract<T>>;\nexport type ExtractStorageColumnInputTypes<T> = StorageColumnInputTypesOf<\n  ExtractTypeMapsFromContract<T>\n>;\n\nexport type ResolveCodecTypes<TContract, TTypeMaps> = [TTypeMaps] extends [never]\n  ? ExtractCodecTypes<TContract>\n  : CodecTypesOf<TTypeMaps>;\n"],"mappings":";;;;;;;;;;;AASA,MAAa,sBAAsB;;;;;;AAmCnC,SAAgB,sBAAsB,OAAsD;CAC1F,OAAO;EACL,MAAM;EACN,SAAS,MAAM;EACf,YAAY,MAAM;EAClB,YAAY,MAAM,cAAc,CAAC;CACnC;AACF;;;;;;AAOA,SAAgB,sBAAsB,OAA8C;CAClF,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,OAAQ,MAA6B,SAAS;AAChD;;;;;;;ACPA,SAAgB,4BACd,WACwC;CACxC,IAAI,cAAc,KAAA,KAAa,CAAC,OAAO,OAAO,WAAW,iBAAiB,GACxE,OAAO;CAET,OAAO,OAAO,QAAQ,IAAI,WAAW,iBAAiB,MAAM;AAC9D;;;;;;;AA+DA,IAAsB,mBAAtB,cAA+C,cAAsC,CAKrF;;;;;;;;;;;AAYA,SAAgB,2BAA2B,GAAmC;CAC5E,IAAI,OAAO,MAAM,YAAY,MAAM,QAAQ,EAAE,kBAAkB,IAAI,OAAO;CAC1E,OAAO,OAAO,EAAE,iBAAiB;AACnC;AAEA,IAAa,aAAb,cAA+D,QAA2B;CACxF;CACA;CAGA,YAAY,OAA+B;EACzC,MAAM;EACN,KAAK,cAAc,MAAM;EACzB,KAAK,aAAa,OAAO,OAAO,MAAM,UAAU;EAChD,IAAI,MAAM,UAAU,KAAA,GAClB,KAAK,QAAQ,OAAO,OAClB,OAAO,YACL,OAAO,QAAQ,MAAM,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,MAAM,mBAAmB,MAAM,EAAE,CAAC,CAAC,CACtF,CACF;EAEF,WAAW,IAAI;CACjB;AACF;;;;;;;;;;;;;;;;;AAkBA,SAAS,mBAAmB,MAAc,OAAiD;CACzF,IAAI,sBAAsB,KAAK,GAAG;EAMhC,IAAI,gBAAgB,OAClB,OAAO;EAET,OAAO,sBAAsB,KAAK;CACpC;CACA,MAAM,UAAU,cAAc,KAAK,IAAI,MAAM,UAAU,KAAA;CACvD,MAAM,kBACJ,YAAY,KAAA,IACR,iCACA,uCAAuC,KAAK,UAAU,OAAO;CACnE,MAAM,IAAI,MACR,iBAAiB,KAAK,UAAU,IAAI,EAAE,QAAQ,gBAAgB,aAAa,KAAK,UAAU,gBAAgB,EAAE,gGAC9G;AACF;;;AC/HA,MAAa,wBAAwB;AACrC,MAAa,mBAAmB;AAEhC,SAAgB,gBACd,IACA,kBACyC;CACzC,OAAO;EACL,YAAY,GAAG,cAAc,kBAAkB,cAAA;EAC/C,OAAO,GAAG,SAAS,kBAAkB,SAAA;CACvC;AACF"}

package/dist/unique-constraint-C0De4sLU.d.mts

@@ -0,0 +1,55 @@
+import { t as SqlNode } from "./sql-node-V214WXQD.mjs";
+
+//#region src/ir/primary-key.d.ts
+interface PrimaryKeyInput {
+  readonly columns: readonly string[];
+  readonly name?: string;
+}
+/**
+ * SQL Contract IR node for a table's primary-key constraint.
+ */
+declare class PrimaryKey extends SqlNode {
+  readonly columns: readonly string[];
+  readonly name?: string;
+  constructor(input: PrimaryKeyInput);
+}
+//#endregion
+//#region src/ir/sql-index.d.ts
+interface IndexInput {
+  readonly columns: readonly string[];
+  readonly name?: string;
+  readonly type?: string;
+  readonly options?: Record<string, unknown>;
+}
+/**
+ * SQL Contract IR node for a table-level secondary index.
+ *
+ * Note that this class shadows the global TypeScript `Index` lib type
+ * at the family-shared name; consumer files that need both should
+ * alias one (e.g.
+ * `import { Index as SqlIndexNode } from '@prisma-next/sql-contract/types'`).
+ */
+declare class Index extends SqlNode {
+  readonly columns: readonly string[];
+  readonly name?: string;
+  readonly type?: string;
+  readonly options?: Record<string, unknown>;
+  constructor(input: IndexInput);
+}
+//#endregion
+//#region src/ir/unique-constraint.d.ts
+interface UniqueConstraintInput {
+  readonly columns: readonly string[];
+  readonly name?: string;
+}
+/**
+ * SQL Contract IR node for a table-level unique constraint.
+ */
+declare class UniqueConstraint extends SqlNode {
+  readonly columns: readonly string[];
+  readonly name?: string;
+  constructor(input: UniqueConstraintInput);
+}
+//#endregion
+export { PrimaryKey as a, IndexInput as i, UniqueConstraintInput as n, PrimaryKeyInput as o, Index as r, UniqueConstraint as t };
+//# sourceMappingURL=unique-constraint-C0De4sLU.d.mts.map

package/dist/unique-constraint-C0De4sLU.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unique-constraint-C0De4sLU.d.mts","names":[],"sources":["../src/ir/primary-key.ts","../src/ir/sql-index.ts","../src/ir/unique-constraint.ts"],"mappings":";;;UAGiB,eAAA;EAAA,SACN,OAAA;EAAA,SACA,IAAI;AAAA;;;AAAA;cAMF,UAAA,SAAmB,OAAO;EAAA,SAC5B,OAAA;EAAA,SACQ,IAAA;cAEL,KAAA,EAAO,eAAA;AAAA;;;UCZJ,UAAA;EAAA,SACN,OAAA;EAAA,SACA,IAAA;EAAA,SACA,IAAA;EAAA,SACA,OAAA,GAAU,MAAM;AAAA;ADFZ;AAMf;;;;;;;AANe,cCaF,KAAA,SAAc,OAAA;EAAA,SAChB,OAAA;EAAA,SACQ,IAAA;EAAA,SACA,IAAA;EAAA,SACA,OAAA,GAAU,MAAA;cAEf,KAAA,EAAO,UAAA;AAAA;;;UCrBJ,qBAAA;EAAA,SACN,OAAA;EAAA,SACA,IAAI;AAAA;;;AFAA;cEMF,gBAAA,SAAyB,OAAO;EAAA,SAClC,OAAA;EAAA,SACQ,IAAA;cAEL,KAAA,EAAO,qBAAA;AAAA"}

package/dist/validators.d.mts

@@ -1,8 +1,8 @@
-import { n as ForeignKeyInput, r as ReferentialAction } from "./foreign-key-BATxB95l.mjs";
-import { f as PrimaryKeyInput, o as UniqueConstraintInput } from "./storage-value-set-WnYsIFM8.mjs";
-import { i as SqlStorage } from "./sql-storage-Dga0jwP2.mjs";
-import { Type } from "arktype";
+import { n as ForeignKeyInput, r as ReferentialAction } from "./foreign-key-DuCoGJCf.mjs";
+import { n as UniqueConstraintInput, o as PrimaryKeyInput } from "./unique-constraint-C0De4sLU.mjs";
+import { s as SqlStorage } from "./sql-storage-p-Wzt_MO.mjs";
 import { AnyEntityKindDescriptor } from "@prisma-next/framework-components/ir";
+import { Type } from "arktype";
 import { Contract } from "@prisma-next/contract/types";
 
 //#region src/ir/storage-entry-schemas.d.ts
@@ -62,6 +62,7 @@ declare const StorageTableSchema: import("arktype/internal/variants/object.ts").
       nativeType: string;
       codecId: string;
       nullable: boolean;
+      many?: boolean;
       typeParams?: Record<string, unknown>;
       typeRef?: string;
       default?: ColumnDefaultLiteral | ColumnDefaultFunction;
@@ -133,13 +134,15 @@ declare function createSqlStorageSchema(kinds: ReadonlyMap<string, AnyEntityKind
  */
 declare function createSqlContractSchema(kinds: ReadonlyMap<string, AnyEntityKindDescriptor>): Type<unknown>;
 /**
- * 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
  */
-declare function validateStorage(value: unknown): SqlStorage;
+declare function validateStorage(value: unknown): void;
 declare function validateModel(value: unknown): unknown;
 /**
  * Validates semantic constraints on SqlStorage that cannot be expressed in Arktype schemas.

package/dist/validators.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"validators.d.mts","names":[],"sources":["../src/ir/storage-entry-schemas.ts","../src/validators.ts"],"mappings":";;;;;;;;KAMK,oBAAA;EAAA,SACM,IAAA;EAAA,SACA,KAAA,8BAAmC,MAAM;AAAA;AAAA,KAE/C,qBAAA;EAAA,SAAmC,IAAA;EAAA,SAA2B,UAAU;AAAA;AAAA,cAMhE,0BAAA,gDAA0B,UAAA,CAAA,oBAAA;AAAA,cAK1B,2BAAA,gDAA2B,UAAA,CAAA,qBAAA;AAAA,cAK3B,mBAAA,gDAAmB,UAAA,CAAA,oBAAA,GAAA,qBAAA;;;;AAlBoB;AAAA;cAkDvC,qBAAA,gDAAqB,UAAA;;gDAKhC,MAAA;AAAA;AAAA,cAYW,WAAA,gDAAW,UAAA;;;;YAKtB,MAAA;AAAA;AAAA,cAEW,yBAAA,gDAAyB,UAAA;;;;;;cAQzB,sBAAA,gDAAsB,UAAA;;;;;cAOtB,uBAAA,gDAAuB,UAAA,CAAA,iBAAA;AAAA,cAIvB,gBAAA,gDAAgB,UAAA,CAAA,eAAA;AAAA,cAUhB,qBAAA,gDAAqB,UAAA;;;;;;;;;;;cAOrB,kBAAA,gDAAkB,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cCXlB,kBAAA,gDAAkB,UAAA;;;;mDAS7B,MAAA;EAAA;AAAA;;AD5GkD;AAAA;;;;AAEyB;AAM7E;iBC0HgB,0BAAA,CACd,KAAA,EAAO,WAAA,SAAoB,uBAAA,IAC1B,IAAA;;;AD5HoC;AAKvC;;;iBCmKgB,sBAAA,CACd,KAAA,EAAO,WAAA,SAAoB,uBAAA,IAC1B,IAAA;ADrKqC;AAKxC;;;;AALwC,iBC8TxB,uBAAA,CACd,KAAA,EAAO,WAAA,SAAoB,uBAAA,IAC1B,IAAA;;;;AD3T6B;AAgChC;;;iBCqUgB,eAAA,CAAgB,KAAA,YAAiB,UAAU;AAAA,iBA4B3C,aAAA,CAAc,KAAc;;;;;;ADhV5C;;;;;;;;iBC8YgB,wBAAA,CAAyB,OAAmB,EAAV,UAAU;;;;ADvY5D;;;iBC4iBgB,8BAAA,CAA+B,QAAA,EAAU,QAAQ,CAAC,UAAA;;;;;;;iBA4DlD,6BAAA,CAA8B,QAAA,EAAU,QAAQ,CAAC,UAAA;AAAA,UAwGhD,+BAAA;EDnsB0B;;;;;;;;EAAA,SC4sBhC,cAAA,GAAiB,IAAI;AAAA;;;;AD1sBI;AAIpC;;;;iBCitBgB,wBAAA,WAAmC,QAAA,CAAS,UAAA,GAC1D,KAAA,WACA,OAAA,GAAU,+BAAA,GACT,CAAA"}
+{"version":3,"file":"validators.d.mts","names":[],"sources":["../src/ir/storage-entry-schemas.ts","../src/validators.ts"],"mappings":";;;;;;;;KAMK,oBAAA;EAAA,SACM,IAAA;EAAA,SACA,KAAA,8BAAmC,MAAM;AAAA;AAAA,KAE/C,qBAAA;EAAA,SAAmC,IAAA;EAAA,SAA2B,UAAU;AAAA;AAAA,cAMhE,0BAAA,gDAA0B,UAAA,CAAA,oBAAA;AAAA,cAK1B,2BAAA,gDAA2B,UAAA,CAAA,qBAAA;AAAA,cAK3B,mBAAA,gDAAmB,UAAA,CAAA,oBAAA,GAAA,qBAAA;;;;AAlBoB;AAAA;cAmDvC,qBAAA,gDAAqB,UAAA;;gDAKhC,MAAA;AAAA;AAAA,cAYW,WAAA,gDAAW,UAAA;;;;YAKtB,MAAA;AAAA;AAAA,cAEW,yBAAA,gDAAyB,UAAA;;;;;;cAQzB,sBAAA,gDAAsB,UAAA;;;;;cAOtB,uBAAA,gDAAuB,UAAA,CAAA,iBAAA;AAAA,cAIvB,gBAAA,gDAAgB,UAAA,CAAA,eAAA;AAAA,cAQhB,qBAAA,gDAAqB,UAAA;;;;;;;;;;;cAOrB,kBAAA,gDAAkB,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cCblB,kBAAA,gDAAkB,UAAA;;;;mDAS7B,MAAA;EAAA;AAAA;;ADzGkD;AAAA;;;;AAEyB;AAM7E;iBCuHgB,0BAAA,CACd,KAAA,EAAO,WAAA,SAAoB,uBAAA,IAC1B,IAAA;;;ADzHoC;AAKvC;;;iBCgKgB,sBAAA,CACd,KAAA,EAAO,WAAA,SAAoB,uBAAA,IAC1B,IAAA;ADlKqC;AAKxC;;;;AALwC,iBC0TxB,uBAAA,CACd,KAAA,EAAO,WAAA,SAAoB,uBAAA,IAC1B,IAAA;;;;ADvT6B;AAiChC;;;;;iBC4TgB,eAAA,CAAgB,KAAc;AAAA,iBAQ9B,aAAA,CAAc,KAAc;;;;ADnT5C;;;;;;;;;;iBCiXgB,wBAAA,CAAyB,OAAmB,EAAV,UAAU;;AD1W5D;;;;;iBC6gBgB,8BAAA,CAA+B,QAAA,EAAU,QAAQ,CAAC,UAAA;;;;;;ADrgBlE;iBCikBgB,6BAAA,CAA8B,QAAA,EAAU,QAAQ,CAAC,UAAA;AAAA,UAwGhD,+BAAA;EDpqB0B;;;;;;;AAE3C;EAF2C,SC6qBhC,cAAA,GAAiB,IAAI;AAAA;;AD3qBI;AAIpC;;;;AAA6B;AAQ7B;iBC0qBgB,wBAAA,WAAmC,QAAA,CAAS,UAAA,GAC1D,KAAA,WACA,OAAA,GAAU,+BAAA,GACT,CAAA"}

package/dist/validators.mjs

@@ -1,11 +1,10 @@
-import { C as StorageTableSchema, S as ReferentialActionSchema, _ as ColumnDefaultSchema, b as ForeignKeySourceSchema, g as ColumnDefaultLiteralSchema, h as ColumnDefaultFunctionSchema, m as CheckConstraintSchema, t as composeSqlEntityKinds, v as ForeignKeyReferenceSchema, w as StorageValueSetSchema, x as IndexSchema, y as ForeignKeySchema } from "./entity-kinds-Cl36zL5j.mjs";
-import { i as SqlStorage, l as buildSqlNamespaceMap, u as SqlUnboundNamespace } from "./types-B-eiQXff.mjs";
+import { a as ColumnDefaultFunctionSchema, c as ForeignKeyReferenceSchema, d as IndexSchema, f as ReferentialActionSchema, i as CheckConstraintSchema, l as ForeignKeySchema, m as StorageValueSetSchema, o as ColumnDefaultLiteralSchema, p as StorageTableSchema, s as ColumnDefaultSchema, t as composeSqlEntityKinds, u as ForeignKeySourceSchema } from "./entity-kinds-CVg6HzG2.mjs";
+import { isPlainRecord } from "@prisma-next/framework-components/ir";
 import { type } from "arktype";
-import { UNBOUND_NAMESPACE_ID, isPlainRecord } from "@prisma-next/framework-components/ir";
 import { CrossReferenceSchema } from "@prisma-next/contract/types";
-import { blindCast } from "@prisma-next/utils/casts";
 import { ContractValidationError } from "@prisma-next/contract/contract-validation-error";
 import { validateContractDomain } from "@prisma-next/contract/validate-domain";
+import { blindCast } from "@prisma-next/utils/casts";
 import { ifDefined } from "@prisma-next/utils/defined";
 //#region src/validators.ts
 const generatorKindSchema = type("'generator'");
@@ -236,10 +235,12 @@ function createSqlContractSchema(kinds) {
 }
 const SqlContractSchema = createSqlContractSchema(DEFAULT_SQL_KINDS);
 /**
-* 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
 */
 function validateStorage(value) {
@@ -248,17 +249,6 @@ function validateStorage(value) {
 		const messages = result.map((p) => p.message).join("; ");
 		throw new Error(`Storage validation failed: ${messages}`);
 	}
-	const validated = blindCast(result);
-	const namespaces = buildSqlNamespaceMap(validated.namespaces ?? {});
-	const unbound = namespaces[UNBOUND_NAMESPACE_ID] ?? SqlUnboundNamespace.instance;
-	return new SqlStorage({
-		storageHash: validated.storageHash,
-		...ifDefined("types", validated.types),
-		namespaces: {
-			...namespaces,
-			[UNBOUND_NAMESPACE_ID]: unbound
-		}
-	});
 }
 function validateModel(value) {
 	const result = ModelSchema(value);
@@ -348,9 +338,7 @@ function validateStorageSemantics(storage) {
 				source: fk.source,
 				target: fk.target,
 				onDelete: fk.onDelete ?? null,
-				onUpdate: fk.onUpdate ?? null,
-				constraint: fk.constraint,
-				index: fk.index
+				onUpdate: fk.onUpdate ?? null
 			});
 			if (seenForeignKeyDefinitions.has(signature)) {
 				errors.push(`Namespace "${namespaceId}" table "${tableName}": duplicate foreign key definition on columns [${fk.source.columns.join(", ")}]`);
@@ -400,7 +388,7 @@ function validateModelStorageReferences(contract) {
 			const table = rawTable;
 			const columnNames = new Set(Object.keys(table.columns));
 			for (const [fieldName, field] of Object.entries(model.storage.fields)) if (!columnNames.has(field.column)) throw new ContractValidationError(`Model "${qualifiedName}" field "${fieldName}" references non-existent column "${field.column}" in table "${storageTable}"`, "storage");
-			const JSON_NATIVE_TYPES = new Set(["json", "jsonb"]);
+			const JSON_NATIVE_TYPES = /* @__PURE__ */ new Set(["json", "jsonb"]);
 			for (const [fieldName, domainField] of Object.entries(model.fields ?? {})) {
 				if (domainField.type?.kind !== "valueObject") continue;
 				const storageField = model.storage.fields[fieldName];
@@ -463,8 +451,110 @@ function validateSqlContractFully(value, options) {
 	const semanticErrors = validateStorageSemantics(validated.storage);
 	if (semanticErrors.length > 0) throw new ContractValidationError(`Contract semantic validation failed: ${semanticErrors.join("; ")}`, "storage");
 	validateModelStorageReferences(validated);
+	validateRelationThroughConsistency(validated);
 	return validated;
 }
+/** Storage column lookup for through-consistency validation. */
+function lookupStorageColumn(contract, namespaceId, tableName, columnName) {
+	const rawTable = contract.storage.namespaces[namespaceId]?.entries.table?.[tableName];
+	if (rawTable === void 0) return;
+	return blindCast(rawTable).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, b) {
+	return a.nativeType === b.nativeType && JSON.stringify(a.typeParams ?? null) === JSON.stringify(b.typeParams ?? null);
+}
+function describeColumnType(column) {
+	return column.typeParams === void 0 ? 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) {
+	const fail = (detail) => 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 === void 0) continue;
+		const junctionColumn = lookupStorageColumn(input.contract, input.junctionNamespaceId, input.junctionTable, junctionColumnName);
+		if (junctionColumn === void 0) throw fail(`${input.junctionColumnsLabel} references column "${junctionColumnName}" absent from junction table "${input.junctionNamespaceId}.${input.junctionTable}".`);
+		const model = input.model;
+		if (model === void 0) continue;
+		let modelColumnName = modelColumnRef;
+		if (model.fieldToColumn !== void 0) {
+			const mapped = model.fieldToColumn[modelColumnRef];
+			if (mapped === void 0) 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 === void 0) 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) {
+	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(model.storage);
+		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
+		});
+		const targetModel = relation.to.space === void 0 ? contract.domain.namespaces[relation.to.namespace]?.models[relation.to.model] : void 0;
+		const targetModelSide = targetModel === void 0 ? void 0 : {
+			namespaceId: relation.to.namespace,
+			table: blindCast(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
+		});
+	}
+}
 //#endregion
 export { CheckConstraintSchema, ColumnDefaultFunctionSchema, ColumnDefaultLiteralSchema, ColumnDefaultSchema, ContractEnumSchema, ForeignKeyReferenceSchema, ForeignKeySchema, ForeignKeySourceSchema, IndexSchema, ReferentialActionSchema, StorageTableSchema, StorageValueSetSchema, createNamespaceEntrySchema, createSqlContractSchema, createSqlStorageSchema, validateModel, validateModelStorageReferences, validateSqlContractFully, validateSqlStorageConsistency, validateStorage, validateStorageSemantics };