@prisma-next/family-sql 0.14.0-dev.5 → 0.14.0-dev.51

package/src/core/ir/sql-contract-serializer-base.ts

@@ -6,18 +6,15 @@ import {
   type AnyEntityKindDescriptor,
   hydrateNamespaceEntities,
   type Namespace,
-  NamespaceBase,
-  UNBOUND_NAMESPACE_ID,
 } from '@prisma-next/framework-components/ir';
 import { sqlContractCanonicalizationHooks } from '@prisma-next/sql-contract/canonicalization-hooks';
 import { composeSqlEntityKinds } from '@prisma-next/sql-contract/entity-kinds';
 import {
-  buildSqlNamespace,
-  type SqlNamespaceTablesInput,
+  isMaterializedSqlNamespace,
+  type SqlNamespaceInput,
   SqlStorage,
   type SqlStorageInput,
   type SqlStorageTypeEntry,
-  SqlUnboundNamespace,
 } from '@prisma-next/sql-contract/types';
 import {
   createSqlContractSchema,
@@ -25,7 +22,7 @@ import {
 } from '@prisma-next/sql-contract/validators';
 import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
-import type { JsonObject } from '@prisma-next/utils/json';
+import type { JsonObject, JsonValue } from '@prisma-next/utils/json';
 import { type Type, type } from 'arktype';
 
 const NamespaceRawSchema = type({
@@ -120,77 +117,48 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
         'structural',
       );
     }
-    const hydratedNamespaces = this.hydrateSqlNamespaceMap(rawNamespaces);
-    // Compatibility shim: production code that addresses `__unbound__` for table
-    // metadata lookups (collection-contract, query-plan-mutations, model-accessor,
-    // query-plan-meta, where-binding) uses optional chaining and tolerates absence,
-    // but runtime-qualification (TML-2605) has not yet landed cross-namespace table
-    // routing. Injecting the empty singleton here keeps helpers that augment the
-    // deserialized JSON (e.g. buildMixedPolyContract) working by providing a slot to
-    // write into. Once runtime-qualification routes table lookups by namespace, this
-    // shim should be removed.
-    //
-    // TML-2916: the shim only fires when the target's default namespace IS unbound
-    // (SQLite, Mongo). On Postgres (`defaultNamespaceId === 'public'`) injecting an
-    // empty `__unbound__` slot violates ADR 223 — un-namespaced PG models belong in
-    // `public`, not `__unbound__`.
-    const withInjectedUnbound =
-      this.defaultNamespaceId === UNBOUND_NAMESPACE_ID
-        ? {
-            ...hydratedNamespaces,
-            [UNBOUND_NAMESPACE_ID]:
-              hydratedNamespaces[UNBOUND_NAMESPACE_ID] ?? SqlUnboundNamespace.instance,
-          }
-        : hydratedNamespaces;
+    const hydratedNamespaces = this.hydrateSqlNamespaceMap(
+      blindCast<
+        Readonly<Record<string, Record<string, unknown>>>,
+        'parseSqlContractStructure validated raw JSON; namespace entries are plain objects, not SqlNamespace instances.'
+      >(rawNamespaces),
+    );
 
     return {
       ...validated,
       storage: new SqlStorage({
         storageHash: validated.storage.storageHash,
         ...ifDefined('types', hydratedTypes),
-        // Cast narrows the result of hydrateSqlNamespaceMap from the wider
-        // framework `Namespace` to the SQL-family `SqlNamespace`.
         namespaces: blindCast<
           SqlStorageInput['namespaces'],
-          'hydrateSqlNamespaceMap builds each namespace through the SQL family concretions (SqlBoundNamespace / target schema), so every value is a SqlNamespace; the framework return type only promises the base Namespace.'
-        >(withInjectedUnbound),
+          'hydrateSqlNamespaceMap builds each namespace through the target serializer override, so every value is a SqlNamespace; the framework return type only promises the base Namespace.'
+        >(hydratedNamespaces),
       }),
     };
   }
 
-  protected abstract get defaultNamespaceId(): string;
-
   protected hydrateSqlNamespaceMap(
-    namespaces: Readonly<Record<string, Namespace | Record<string, unknown>>>,
+    namespaces: Readonly<Record<string, Record<string, unknown>>>,
   ): Readonly<Record<string, Namespace>> {
     return Object.fromEntries(
       Object.entries(namespaces).map(([nsId, namespaceEntryRaw]) => {
-        // Raw entries passed structural validation; hydrate materialises family IR class instances.
         const namespaceHydrated = this.hydrateSqlNamespaceEntry(nsId, namespaceEntryRaw);
-        const namespaceMaterialised =
-          namespaceHydrated instanceof NamespaceBase
-            ? namespaceHydrated
-            : buildSqlNamespace(
-                blindCast<
-                  SqlNamespaceTablesInput,
-                  'hydrateSqlNamespaceEntry returns SqlNamespaceTablesInput when raw is not a NamespaceBase'
-                >(namespaceHydrated),
-              );
-        return [nsId, namespaceMaterialised];
+        if (!isMaterializedSqlNamespace(namespaceHydrated)) {
+          throw new Error(
+            `Target serializer bug: hydrateSqlNamespaceEntry for namespace "${nsId}" returned a non-NamespaceBase value. Override hydrateSqlNamespaceEntry to produce a target namespace concretion.`,
+          );
+        }
+        return [nsId, namespaceHydrated];
       }),
     );
   }
 
   protected hydrateSqlNamespaceEntry(
     nsId: string,
-    raw: Namespace | Record<string, unknown>,
-  ): Namespace | SqlNamespaceTablesInput {
-    if (raw instanceof NamespaceBase) {
-      return raw;
-    }
-    const rawRecord = isPlainRecord(raw) ? raw : {};
-    const id = typeof rawRecord['id'] === 'string' ? rawRecord['id'] : nsId;
-    const parsed = NamespaceRawSchema({ ...rawRecord, id });
+    raw: Record<string, unknown>,
+  ): Namespace | SqlNamespaceInput {
+    const id = typeof raw['id'] === 'string' ? raw['id'] : nsId;
+    const parsed = NamespaceRawSchema({ ...raw, id });
     if (parsed instanceof type.errors) {
       const messages = parsed.map((p: { message: string }) => p.message).join('; ');
       throw new ContractValidationError(`Namespace hydration failed: ${messages}`, 'structural');
@@ -211,8 +179,8 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
     }
 
     return blindCast<
-      SqlNamespaceTablesInput,
-      'entriesOutput holds the hydrated SQL entity-kind maps (table always present); this wraps them as the SqlNamespaceTablesInput the family createNamespace consumes.'
+      SqlNamespaceInput,
+      'entriesOutput holds the hydrated SQL entity-kind maps (table always present); this wraps them as the SqlNamespaceInput the target createNamespace consumes.'
     >({
       id,
       entries: entriesOutput,
@@ -240,4 +208,50 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
   protected constructTargetContract(hydrated: Contract<SqlStorage>): TContract {
     return hydrated as TContract;
   }
+
+  /**
+   * Serializes a namespace's `entries` dict by walking every enumerable
+   * kind — no kind is named here, mirroring the generic hydrate walk in
+   * `hydrateSqlNamespaceEntry` above. `table` is the SQL family's one
+   * universal base kind (every namespace carries it), so it is always
+   * emitted, even when empty; every other kind — target- or
+   * pack-contributed — is emitted only when it holds at least one entry.
+   * A kind carried non-enumerable on `entries` is excluded here for free,
+   * since `Object.entries` honors enumerability.
+   */
+  protected serializeNamespaceEntries(
+    entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>,
+  ): Record<string, Record<string, JsonObject>> {
+    const out: Record<string, Record<string, JsonObject>> = {
+      table: this.serializeEntries(entries['table'] ?? {}),
+    };
+    for (const [kind, record] of Object.entries(entries)) {
+      if (kind === 'table' || record == null || Object.keys(record).length === 0) {
+        continue;
+      }
+      out[kind] = this.serializeEntries(record);
+    }
+    return out;
+  }
+
+  private serializeEntries(entries: Readonly<Record<string, unknown>>): Record<string, JsonObject> {
+    const out: Record<string, JsonObject> = {};
+    for (const [name, entry] of Object.entries(entries)) {
+      out[name] = this.serializeJsonObject(entry);
+    }
+    return out;
+  }
+
+  protected serializeJsonObject(value: unknown): JsonObject {
+    return blindCast<
+      JsonObject,
+      'serializeJsonValue round-trips an IR node through JSON, yielding a JsonObject'
+    >(this.serializeJsonValue(value));
+  }
+
+  private serializeJsonValue(value: unknown): JsonValue {
+    return blindCast<JsonValue, 'JSON.parse(JSON.stringify(x)) yields a JsonValue'>(
+      JSON.parse(JSON.stringify(value)),
+    );
+  }
 }

package/src/core/ir/sql-contract-serializer.ts

@@ -1,5 +1,4 @@
 import type { Contract } from '@prisma-next/contract/types';
-import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import { SqlContractSerializerBase } from './sql-contract-serializer-base';
 
@@ -11,15 +10,14 @@ import { SqlContractSerializerBase } from './sql-contract-serializer-base';
  * codec-typed envelope wire a target-specific subclass with a populated
  * registry (see Postgres). Family-level call sites instantiate this
  * default directly when no target serializer is supplied.
+ *
+ * Because this serializer has no target concretion, deserialization of
+ * contracts that include namespace entries from JSON will throw unless
+ * the caller provides pre-hydrated `NamespaceBase` instances. Production
+ * paths always supply a target-specific serializer.
  */
 export class SqlContractSerializer extends SqlContractSerializerBase<Contract<SqlStorage>> {
   constructor() {
     super(new Map());
   }
-
-  // Family-level fallback when no target descriptor is wired in. Preserves the
-  // pre-TML-2916 compatibility-shim behaviour for the unbound slot.
-  protected override get defaultNamespaceId(): string {
-    return UNBOUND_NAMESPACE_ID;
-  }
 }

package/src/core/ir/sql-schema-verifier-base.ts

@@ -1,5 +1,5 @@
 import type {
-  SchemaIssue,
+  SchemaDiffIssue,
   SchemaVerifier,
   SchemaVerifyOptions,
   SchemaVerifyResult,
@@ -9,7 +9,7 @@ import type {
  * SQL family `SchemaVerifier` abstract base. Centralises the SQL-shared
  * walk (table-by-table + column-by-column matching keyed by
  * `(namespace.id, name)`, FK / unique / index comparisons via the
- * existing helpers in `verify-helpers.ts`) and exposes a protected hook
+ * shared satisfaction helpers in `sql-schema-diff.ts`) and exposes a protected hook
  * for target extensions (Postgres functions, RLS policies, future
  * target-only kinds).
  *
@@ -29,7 +29,7 @@ export abstract class SqlSchemaVerifierBase<TContract, TSchema>
   implements SchemaVerifier<TContract, TSchema>
 {
   verifySchema(options: SchemaVerifyOptions<TContract, TSchema>): SchemaVerifyResult {
-    const issues: SchemaIssue[] = [];
+    const issues: SchemaDiffIssue[] = [];
     issues.push(...this.verifyCommonSqlSchema(options));
     issues.push(...this.verifyTargetExtensions(options));
     return { ok: issues.length === 0, issues };
@@ -43,7 +43,7 @@ export abstract class SqlSchemaVerifierBase<TContract, TSchema>
    */
   protected abstract verifyCommonSqlSchema(
     options: SchemaVerifyOptions<TContract, TSchema>,
-  ): readonly SchemaIssue[];
+  ): readonly SchemaDiffIssue[];
 
   /**
    * Target-specific extensions — e.g. Postgres functions, future RLS
@@ -52,5 +52,5 @@ export abstract class SqlSchemaVerifierBase<TContract, TSchema>
    */
   protected abstract verifyTargetExtensions(
     options: SchemaVerifyOptions<TContract, TSchema>,
-  ): readonly SchemaIssue[];
+  ): readonly SchemaDiffIssue[];
 }

package/src/core/migrations/contract-to-schema-ir.ts

@@ -1,4 +1,5 @@
 import type { ColumnDefault, Contract, JsonValue } from '@prisma-next/contract/types';
+import type { CodecRef } from '@prisma-next/framework-components/codec';
 import type { MigrationPlannerConflict } from '@prisma-next/framework-components/control';
 import {
   type CheckConstraint,
@@ -12,16 +13,17 @@ import {
   type UniqueConstraint,
 } from '@prisma-next/sql-contract/types';
 import { defaultIndexName } from '@prisma-next/sql-schema-ir/naming';
-import type {
-  SqlAnnotations,
-  SqlCheckConstraintIRInput,
-  SqlColumnIR,
-  SqlForeignKeyIR,
-  SqlIndexIR,
+import {
+  type SqlAnnotations,
+  type SqlCheckConstraintIRInput,
+  type SqlColumnIRInput,
+  type SqlForeignKeyIRInput,
+  type SqlIndexIRInput,
   SqlSchemaIR,
   SqlTableIR,
-  SqlUniqueIR,
+  type SqlUniqueIRInput,
 } from '@prisma-next/sql-schema-ir/types';
+import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 
 /**
@@ -72,7 +74,7 @@ function convertColumn(
   storageTypes: ResolvedStorageTypes,
   expandNativeType: NativeTypeExpander | undefined,
   renderDefault: DefaultRenderer | undefined,
-): SqlColumnIR {
+): SqlColumnIRInput {
   // Resolve `typeRef` so columns that delegate their `nativeType`/`codecId`/
   // `typeParams` to a named `storage.types` entry expand the same way as
   // columns that inline those fields. Without this resolution, a
@@ -82,13 +84,14 @@ function convertColumn(
   // typeRef and produces `"vector(1536)"` — making diffs on the same
   // contract falsely report a `type_mismatch`.
   const resolved = resolveColumnTypeMetadata(column, storageTypes);
-  const nativeType = expandNativeType
+  const baseNativeType = expandNativeType
     ? expandNativeType({
         nativeType: resolved.nativeType,
         codecId: resolved.codecId,
         ...ifDefined('typeParams', resolved.typeParams),
       })
     : resolved.nativeType;
+  const nativeType = column.many ? `${baseNativeType}[]` : baseNativeType;
   return {
     name,
     nativeType,
@@ -97,6 +100,43 @@ function convertColumn(
       'default',
       column.default != null && renderDefault ? renderDefault(column.default, column) : undefined,
     ),
+    // Contract-derived columns are resolved by construction: the computed
+    // full native type doubles as the resolved value, and the contract's
+    // structured default is the resolved default (the introspected side
+    // stamps its normalizer's parse of the raw expression).
+    resolvedNativeType: nativeType,
+    ...ifDefined('resolvedDefault', column.default ?? undefined),
+    // The column's codec identity, carried the same way the query AST
+    // carries `CodecRef` (TML-2456) — the migration planner's op-builders
+    // resolve DDL rendering from this at plan time (Decision 5), instead of
+    // reading a derivation-precomputed render payload.
+    codecRef: buildColumnCodecRef(resolved, column.many),
+    codecBaseNativeType: resolved.nativeType,
+    ...(column.typeRef !== undefined ? { codecNamedType: true } : {}),
+  };
+}
+
+/**
+ * Builds the column's `CodecRef` from its resolved (post-`typeRef`) codec
+ * identity — the same construction the query AST and the migration DDL
+ * renderer already use (TML-2456, TML-2918).
+ */
+function buildColumnCodecRef(
+  resolved: Pick<StorageColumn, 'codecId' | 'nativeType' | 'typeParams'>,
+  many: boolean | undefined,
+): CodecRef {
+  return {
+    codecId: resolved.codecId,
+    ...ifDefined(
+      'typeParams',
+      resolved.typeParams !== undefined
+        ? blindCast<
+            JsonValue,
+            'resolved.typeParams is JsonValue-shaped storage metadata; the narrowed (non-undefined) value lands in CodecRef.typeParams which is JsonValue'
+          >(resolved.typeParams)
+        : undefined,
+    ),
+    ...ifDefined('many', many),
   };
 }
 
@@ -192,22 +232,26 @@ function convertCheck(check: CheckConstraint, storage: SqlStorage): SqlCheckCons
   };
 }
 
-function convertUnique(unique: UniqueConstraint): SqlUniqueIR {
+function convertUnique(unique: UniqueConstraint): SqlUniqueIRInput {
   return {
     columns: unique.columns,
     ...ifDefined('name', unique.name),
   };
 }
 
-function convertIndex(index: Index): SqlIndexIR {
+function convertIndex(index: Index): SqlIndexIRInput {
   return {
     columns: index.columns,
     unique: false,
     ...ifDefined('name', index.name),
+    // Carried so the derived index node compares type/options against the
+    // introspected side (the legacy walk read them from the contract).
+    ...ifDefined('type', index.type),
+    ...ifDefined('options', index.options),
   };
 }
 
-function convertForeignKey(fk: ForeignKey): SqlForeignKeyIR {
+function convertForeignKey(fk: ForeignKey): SqlForeignKeyIRInput {
   return {
     columns: fk.source.columns,
     referencedTable: fk.target.tableName,
@@ -227,7 +271,7 @@ function convertTable(
   renderDefault: DefaultRenderer | undefined,
   storage: SqlStorage,
 ): SqlTableIR {
-  const columns: Record<string, SqlColumnIR> = {};
+  const columns: Record<string, SqlColumnIRInput> = {};
   for (const [colName, colDef] of Object.entries(table.columns)) {
     columns[colName] = convertColumn(
       colName,
@@ -243,7 +287,7 @@ function convertTable(
     ...table.uniques.map((unique) => unique.columns.join(',')),
     ...(table.primaryKey ? [table.primaryKey.columns.join(',')] : []),
   ]);
-  const fkBackingIndexes: SqlIndexIR[] = [];
+  const fkBackingIndexes: SqlIndexIRInput[] = [];
   for (const fk of table.foreignKeys) {
     if (fk.index === false) continue;
     const key = fk.source.columns.join(',');
@@ -261,7 +305,7 @@ function convertTable(
       ? table.checks.map((c) => convertCheck(c, storage))
       : undefined;
 
-  return {
+  return new SqlTableIR({
     name,
     columns,
     ...ifDefined('primaryKey', table.primaryKey),
@@ -269,7 +313,7 @@ function convertTable(
     uniques: table.uniques.map(convertUnique),
     indexes: [...table.indexes.map(convertIndex), ...fkBackingIndexes],
     ...ifDefined('checks', checks),
-  };
+  });
 }
 
 /**
@@ -303,7 +347,7 @@ export function detectDestructiveChanges(
 
     for (const tableName of Object.keys(fromTables)) {
       const toTableRaw = toNs?.entries.table?.[tableName];
-      if (!(toTableRaw instanceof StorageTable)) {
+      if (!StorageTable.is(toTableRaw)) {
         conflicts.push({
           kind: 'tableRemoved',
           summary: `Table "${tableName}" was removed`,
@@ -313,7 +357,7 @@ export function detectDestructiveChanges(
       const toTable = toTableRaw;
 
       const fromTableRaw = fromTables[tableName];
-      if (!(fromTableRaw instanceof StorageTable)) continue;
+      if (!StorageTable.is(fromTableRaw)) continue;
       const fromTable = fromTableRaw;
 
       for (const columnName of Object.keys(fromTable.columns)) {
@@ -358,6 +402,48 @@ export interface ContractToSchemaIROptions {
  *
  * Returns an empty schema IR when `contract` is `null` (new project).
  */
+/**
+ * Converts the tables of a single namespace into a `SqlSchemaIR`, keyed by
+ * table name within that namespace. Unlike {@link contractToSchemaIR}, which
+ * flattens every namespace's tables into one bare-keyed record (and throws on a
+ * cross-namespace name collision), this scopes the table iteration to one
+ * namespace so the same table name can exist in two schemas.
+ *
+ * The full `storage` is still passed to `convertTable`, so value-set / enum /
+ * type resolution that legitimately spans namespaces is unaffected. Foreign
+ * keys are built purely from the FK descriptor (`fk.target`), so cross-namespace
+ * FKs survive per-namespace conversion. The `annotations` block (storage-type
+ * derived) is omitted here — the per-namespace tree consumer reads only the
+ * per-table fields.
+ */
+export function contractNamespaceToSchemaIR(
+  storage: SqlStorage,
+  namespaceId: string,
+  options: ContractToSchemaIROptions,
+): SqlSchemaIR {
+  if (options.annotationNamespace.length === 0) {
+    throw new Error('annotationNamespace must be a non-empty string');
+  }
+  const namespace = storage.namespaces[namespaceId];
+  if (!namespace) {
+    return new SqlSchemaIR({ tables: {} });
+  }
+  const storageTypes: ResolvedStorageTypes = { ...(storage.types ?? {}) };
+  const tables: Record<string, SqlTableIR> = {};
+  for (const [tableName, tableDefRaw] of Object.entries(namespace.entries.table ?? {})) {
+    StorageTable.assert(tableDefRaw, `namespaces.${namespaceId}.entries.table.${tableName}`);
+    tables[tableName] = convertTable(
+      tableName,
+      tableDefRaw,
+      storageTypes,
+      options.expandNativeType,
+      options.renderDefault,
+      storage,
+    );
+  }
+  return new SqlSchemaIR({ tables });
+}
+
 export function contractToSchemaIR(
   contract: Contract<SqlStorage> | null,
   options: ContractToSchemaIROptions,
@@ -367,21 +453,15 @@ export function contractToSchemaIR(
   }
 
   if (!contract) {
-    return { tables: {} };
+    return new SqlSchemaIR({ tables: {} });
   }
 
   const storage = contract.storage;
-  const storageTypes: ResolvedStorageTypes = {
-    ...((storage.types ?? {}) as ResolvedStorageTypes),
-  };
+  const storageTypes: ResolvedStorageTypes = { ...(storage.types ?? {}) };
   const tables: Record<string, SqlTableIR> = {};
   for (const ns of Object.values(storage.namespaces)) {
     for (const [tableName, tableDefRaw] of Object.entries(ns.entries.table ?? {})) {
-      if (!(tableDefRaw instanceof StorageTable)) {
-        throw new Error(
-          `contractToSchemaIR: expected StorageTable at namespaces.${ns.id}.entries.table.${tableName}`,
-        );
-      }
+      StorageTable.assert(tableDefRaw, `namespaces.${ns.id}.entries.table.${tableName}`);
       const tableDef = tableDefRaw;
       if (tables[tableName] !== undefined) {
         throw new Error(
@@ -405,10 +485,10 @@ export function contractToSchemaIR(
     options.resolveEnumNamespaceSchema,
   );
 
-  return {
+  return new SqlSchemaIR({
     tables,
     ...ifDefined('annotations', annotations),
-  };
+  });
 }
 
 function deriveAnnotations(
@@ -418,7 +498,7 @@ function deriveAnnotations(
 ): SqlAnnotations | undefined {
   const storageTypes: Record<string, StorageTypeInstance> = {};
 
-  for (const typeInstance of Object.values((storage.types ?? {}) as ResolvedStorageTypes)) {
+  for (const typeInstance of Object.values(storage.types ?? {})) {
     if (isStorageTypeInstance(typeInstance)) {
       storageTypes[typeInstance.nativeType] = typeInstance;
     }

package/src/core/migrations/field-event-planner.ts

@@ -88,8 +88,8 @@ export function planFieldEventOperations(
     for (const tableName of tableNames) {
       const priorTableRaw = priorTables?.[tableName];
       const newTableRaw = newTables?.[tableName];
-      const priorTable = priorTableRaw instanceof StorageTable ? priorTableRaw : undefined;
-      const newTable = newTableRaw instanceof StorageTable ? newTableRaw : undefined;
+      const priorTable = StorageTable.is(priorTableRaw) ? priorTableRaw : undefined;
+      const newTable = StorageTable.is(newTableRaw) ? newTableRaw : undefined;
       const fieldNames = unionSorted(
         priorTable ? Object.keys(priorTable.columns) : [],
         newTable ? Object.keys(newTable.columns) : [],

package/src/core/migrations/native-type-expander.ts

@@ -0,0 +1,28 @@
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import { extractCodecControlHooks } from '../assembly';
+
+/**
+ * Builds the codec-hook-composed `expandNativeType` callback the contract→IR
+ * derivation uses to expand parameterized native types (e.g. `character` +
+ * `{ length: 36 }` → `character(36)`). Returns `undefined` when no framework
+ * components are supplied, so callers can omit the option entirely.
+ */
+export function buildNativeTypeExpander(
+  frameworkComponents?: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>,
+) {
+  if (!frameworkComponents) {
+    return undefined;
+  }
+  const codecHooks = extractCodecControlHooks(frameworkComponents);
+  return (input: {
+    readonly nativeType: string;
+    readonly codecId?: string;
+    readonly typeParams?: Record<string, unknown>;
+  }) => {
+    if (!input.typeParams) return input.nativeType;
+    if (!input.codecId) return input.nativeType;
+    const hooks = codecHooks.get(input.codecId);
+    if (!hooks?.expandNativeType) return input.nativeType;
+    return hooks.expandNativeType(input);
+  };
+}

package/src/core/migrations/schema-differ.ts

@@ -0,0 +1,41 @@
+import type { Contract, ControlPolicy } from '@prisma-next/contract/types';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type { SchemaDiffIssue } from '@prisma-next/framework-components/control';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import type { SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+
+/**
+ * The full-tree node diff a SQL target produces for the family verify
+ * verdict: the target derives the expected tree from the contract, applies
+ * the pre-diff normalizations (semantic satisfaction, FK schema-segment
+ * resolution), runs the generic differ, and ownership-scopes the result.
+ * Strict gating, control-policy disposition, and the verdict itself are the
+ * family's post-diff filters over this output.
+ */
+export interface SqlSchemaDiffResult {
+  /** The full, ownership-scoped diff issue list. */
+  readonly issues: readonly SchemaDiffIssue[];
+  /**
+   * Resolves a diff issue's subject table's declared control policy directly
+   * from the contract (Decision 5's own-layer-per-concern discipline extends
+   * here too: control policy is a contract concern, resolved by the target
+   * at disposition time — never stamped on the diff node). `undefined`
+   * when the issue's path resolves to no contract table (a genuine orphan,
+   * or a non-table subject).
+   */
+  readonly resolveControlPolicy: (issue: SchemaDiffIssue) => ControlPolicy | undefined;
+  /**
+   * The expected/actual namespace-node pairs the codec `verifyType` hooks
+   * run over — one per contract namespace with tables, paired by DDL
+   * schema; a flat target repeats its sole actual root per such namespace.
+   */
+  readonly namespacePairs: ReadonlyArray<{ readonly actual: SqlSchemaIRNode | undefined }>;
+}
+
+export interface SqlSchemaDiffInput {
+  readonly contract: Contract<SqlStorage>;
+  readonly schema: SqlSchemaIRNode;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+}
+
+export type SqlSchemaDiffFn = (input: SqlSchemaDiffInput) => SqlSchemaDiffResult;