@prisma-next/family-sql 0.14.0-dev.8 → 0.14.0-dev.81

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,26 +232,42 @@ 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 {
+/**
+ * The FK's referenced-namespace identity comes from the target's namespace
+ * node, not the raw namespace-id string. An unbound target namespace stamps
+ * no `referencedSchema` at all — the FK node's id renders the absence as the
+ * empty segment, which is what flat (single-schema) introspection produces,
+ * so both diff sides' FK ids meet by construction. A bound namespace (or a
+ * cross-space target whose namespace lives in another contract's storage)
+ * stamps its coordinate verbatim; namespaced targets (Postgres) resolve the
+ * real DDL schema downstream.
+ */
+function convertForeignKey(fk: ForeignKey, storage: SqlStorage): SqlForeignKeyIRInput {
+  const targetNamespace = storage.namespaces[fk.target.namespaceId];
+  const targetIsUnbound = targetNamespace?.isUnbound === true;
   return {
     columns: fk.source.columns,
     referencedTable: fk.target.tableName,
-    referencedSchema: fk.target.namespaceId,
+    ...(targetIsUnbound ? {} : { referencedSchema: fk.target.namespaceId }),
     referencedColumns: fk.target.columns,
     ...ifDefined('name', fk.name),
     ...ifDefined('onDelete', fk.onDelete),
@@ -227,7 +283,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 +299,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,15 +317,17 @@ function convertTable(
       ? table.checks.map((c) => convertCheck(c, storage))
       : undefined;
 
-  return {
+  return new SqlTableIR({
     name,
     columns,
     ...ifDefined('primaryKey', table.primaryKey),
-    foreignKeys: table.foreignKeys.filter((fk) => fk.constraint !== false).map(convertForeignKey),
+    foreignKeys: table.foreignKeys
+      .filter((fk) => fk.constraint !== false)
+      .map((fk) => convertForeignKey(fk, storage)),
     uniques: table.uniques.map(convertUnique),
     indexes: [...table.indexes.map(convertIndex), ...fkBackingIndexes],
     ...ifDefined('checks', checks),
-  };
+  });
 }
 
 /**
@@ -303,7 +361,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 +371,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 +416,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 +467,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 +499,10 @@ export function contractToSchemaIR(
     options.resolveEnumNamespaceSchema,
   );
 
-  return {
+  return new SqlSchemaIR({
     tables,
     ...ifDefined('annotations', annotations),
-  };
+  });
 }
 
 function deriveAnnotations(
@@ -418,7 +512,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/control-policy.ts

@@ -5,20 +5,25 @@ import {
 } from '@prisma-next/contract/types';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import { ifDefined } from '@prisma-next/utils/defined';
-import type { SqlPlannerConflict } from './types';
 
 /**
  * The target object a control policy governs for a single planner call,
  * resolved from the target's own IR. `undefined` means the call's target
  * object could not be positively established — a fail-closed signal: any
  * policy stricter than `managed` drops such a call rather than emitting it.
+ *
+ * The object identity is a generic storage coordinate — `(entityKind,
+ * entityName)`, absent for a whole-namespace subject — never a target-specific
+ * `table`/`typeName` field. The family reasons about the coordinate for policy
+ * and deduplication; the target owns any vocabulary (table vs enum) when it
+ * renders a suppression.
  */
 export interface ControlPolicySubject {
   readonly namespaceId: string;
-  readonly explicitNodeControlPolicy?: ControlPolicy;
-  readonly table?: string;
+  readonly entityKind?: string;
+  readonly entityName?: string;
   readonly column?: string;
-  readonly typeName?: string;
+  readonly explicitNodeControlPolicy?: ControlPolicy;
   /**
    * Whether the call creates a whole, previously-absent top-level storage
    * object (e.g. a table or an enum/type), as opposed to modifying an
@@ -29,6 +34,26 @@ export interface ControlPolicySubject {
   readonly createsNewObject: boolean;
 }
 
+/**
+ * The structured record a control-policy partition emits for one suppressed
+ * subject or call. It carries only raw data — no strings, no vocabulary — so
+ * the consumer (the target) renders the user-facing message itself:
+ *
+ * - `subject` — the suppressed subject (its coordinate + namespace), or
+ *   `undefined` when the subject could not be resolved (fail-closed).
+ * - `policy` — the effective control policy that caused the suppression.
+ * - `factoryName` — the resolved creation factory name if the suppressed thing
+ *   was a whole-object creation (e.g. `createTable`), else `undefined`. The
+ *   family never invents a verb for a modification that produced no call.
+ * - `createsNewObject` — whether the suppressed thing was object creation.
+ */
+export interface SuppressionRecord {
+  readonly subject: ControlPolicySubject | undefined;
+  readonly policy: ControlPolicy;
+  readonly factoryName: string | undefined;
+  readonly createsNewObject: boolean;
+}
+
 /**
  * The control policy that governs a single call. The `external` default is an
  * un-overridable namespace floor: when the contract default is `external`, no
@@ -71,67 +96,10 @@ function callAllowedUnderControlPolicy(
   }
 }
 
-function defaultSubjectLabel(
-  factoryName: string,
-  subject: ControlPolicySubject | undefined,
-): string {
-  if (subject?.table) {
-    return `${factoryName}(${subject.table})`;
-  }
-  if (subject?.typeName) {
-    return `${factoryName}(${subject.typeName})`;
-  }
-  return factoryName;
-}
-
-function suppressionSummary(
-  subjectLabel: string,
-  subject: ControlPolicySubject | undefined,
-  effectivePolicy: ControlPolicy,
-): string {
-  const namespace = subject?.namespaceId ?? 'unknown';
-  const declared = subject?.explicitNodeControlPolicy;
-  if (effectivePolicy === 'external' && declared === 'managed') {
-    return `control policy suppressed: ${subjectLabel} — namespace '${namespace}' has effective control 'external' but table declared 'managed'`;
-  }
-  const declaredSuffix = declared ? ` but table declared '${declared}'` : '';
-  return `control policy suppressed: ${subjectLabel} — namespace '${namespace}' has effective control '${effectivePolicy}'${declaredSuffix}`;
-}
-
-function buildSubjectSuppressionWarning(
-  subject: ControlPolicySubject | undefined,
-  effectivePolicy: ControlPolicy,
-  factoryName: string,
-  formatSubjectLabel: (factoryName: string, subject: ControlPolicySubject | undefined) => string,
-): SqlPlannerConflict {
-  const subjectLabel = formatSubjectLabel(factoryName, subject);
-  return {
-    kind: 'controlPolicySuppressedCall',
-    summary: suppressionSummary(subjectLabel, subject, effectivePolicy),
-    location: {
-      ...ifDefined('namespace', subject?.namespaceId),
-      ...ifDefined('table', subject?.table),
-      ...ifDefined('column', subject?.column),
-      ...ifDefined('type', subject?.typeName),
-    },
-    meta: {
-      controlPolicy: effectivePolicy,
-      factoryName,
-      ...ifDefined('declaredControlPolicy', subject?.explicitNodeControlPolicy),
-    },
-  };
-}
-
-function defaultModificationFactoryNameForSubject(subject: ControlPolicySubject): string {
-  if (subject.table) return 'alterTable';
-  if (subject.typeName) return 'alterType';
-  return 'alterSchema';
-}
-
 /**
  * Partition the calls produced for a single set of subjects into those the
  * effective control policy permits (`kept`) and a list of
- * {@link SqlPlannerConflict} warnings describing the suppressed calls.
+ * {@link SuppressionRecord}s describing the suppressed calls.
  *
  * **Prefer {@link partitionIssuesByControlPolicy}** for the schema-issue
  * pipeline: it filters subjects out of the planner's *input* so the planner
@@ -146,18 +114,13 @@ export function partitionCallsByControlPolicy<TCall>(options: {
   readonly contract: Contract<SqlStorage>;
   readonly resolveControlPolicySubject: (call: TCall) => ControlPolicySubject | undefined;
   readonly resolveFactoryName: (call: TCall) => string;
-  readonly formatSubjectLabel?: (
-    factoryName: string,
-    subject: ControlPolicySubject | undefined,
-  ) => string;
 }): {
   readonly kept: readonly TCall[];
-  readonly warnings: readonly SqlPlannerConflict[];
+  readonly suppressions: readonly SuppressionRecord[];
 } {
   const defaultControlPolicy = options.contract.defaultControlPolicy;
-  const formatSubjectLabel = options.formatSubjectLabel ?? defaultSubjectLabel;
   const kept: TCall[] = [];
-  const warnings: SqlPlannerConflict[] = [];
+  const suppressions: SuppressionRecord[] = [];
 
   for (const call of options.calls) {
     const subject = options.resolveControlPolicySubject(call);
@@ -165,16 +128,18 @@ export function partitionCallsByControlPolicy<TCall>(options: {
     if (callAllowedUnderControlPolicy(policy, subject)) {
       kept.push(call);
     } else {
-      const factoryName = options.resolveFactoryName(call);
-      warnings.push(
-        buildSubjectSuppressionWarning(subject, policy, factoryName, formatSubjectLabel),
-      );
+      suppressions.push({
+        subject,
+        policy,
+        factoryName: options.resolveFactoryName(call),
+        createsNewObject: subject?.createsNewObject ?? false,
+      });
     }
   }
 
   return Object.freeze({
     kept: Object.freeze(kept),
-    warnings: Object.freeze(warnings),
+    suppressions: Object.freeze(suppressions),
   });
 }
 
@@ -192,18 +157,15 @@ export function partitionCallsByControlPolicy<TCall>(options: {
  * cannot reason about the live shape of a subject the user marked as
  * out-of-scope (`external`).
  *
- * `warnings` is one {@link SqlPlannerConflict} per suppressed subject (not per
- * suppressed issue). `factoryName` is inferred from the subject's issue mix:
- * if any of the subject's issues is whole-object creation, the warning takes
- * the corresponding creation factoryName (e.g. `createTable`,
- * `createEnumType`, `createSchema`); otherwise it falls back to
- * `defaultModificationFactoryName(subject)` — a synthetic label that names
- * the *kind* of mutation that would have run, since no concrete DDL call was
- * generated.
+ * `suppressions` is one {@link SuppressionRecord} per suppressed subject (not
+ * per suppressed issue). Its `factoryName` is the creation factory name when any
+ * of the subject's issues is whole-object creation (e.g. `createTable`), else
+ * `undefined` — the family never invents a modification verb for an op that
+ * produced no call; the target renders the message.
  *
  * Unresolved-subject issues (`resolveControlPolicySubject` returns
- * `undefined`) emit one warning each; they cannot be deduplicated because
- * they carry no subject coordinate.
+ * `undefined`) emit one record each; they cannot be deduplicated because they
+ * carry no subject coordinate.
  */
 export function partitionIssuesByControlPolicy<TIssue>(options: {
   readonly issues: readonly TIssue[];
@@ -221,34 +183,19 @@ export function partitionIssuesByControlPolicy<TIssue>(options: {
    *
    * 1. Under `tolerated`, only issues whose `resolveCreationFactoryName`
    *    returns a value flow into the planner (create-if-absent).
-   * 2. Subjects that have at least one creation-flavoured issue use the
-   *    resolved creation factoryName for their suppression warning;
-   *    otherwise they fall back to `defaultModificationFactoryName`.
+   * 2. A suppressed subject's record carries the resolved creation factoryName
+   *    when it has at least one creation-flavoured issue, else `undefined`.
    */
   readonly resolveCreationFactoryName: (issue: TIssue) => string | undefined;
-  /**
-   * Default modification factoryName for a suppressed subject whose issues
-   * are all non-creation (the subject exists but has a different shape).
-   * Defaults to `'alterTable'` / `'alterType'` / `'alterSchema'` based on the
-   * subject's populated coordinates.
-   */
-  readonly defaultModificationFactoryName?: (subject: ControlPolicySubject) => string;
-  readonly formatSubjectLabel?: (
-    factoryName: string,
-    subject: ControlPolicySubject | undefined,
-  ) => string;
 }): {
   readonly plannable: readonly TIssue[];
-  readonly warnings: readonly SqlPlannerConflict[];
+  readonly suppressions: readonly SuppressionRecord[];
 } {
   const defaultControlPolicy = options.contract.defaultControlPolicy;
-  const formatSubjectLabel = options.formatSubjectLabel ?? defaultSubjectLabel;
-  const inferModificationFactoryName =
-    options.defaultModificationFactoryName ?? defaultModificationFactoryNameForSubject;
 
   const plannable: TIssue[] = [];
   // Resolved-subject suppressions are deduplicated by subject key so we emit
-  // one warning per suppressed subject, not one per suppressed issue.
+  // one record per suppressed subject, not one per suppressed issue.
   // `creationFactoryName` upgrades from `undefined` to a concrete creation
   // name the first time we see a creation-flavoured issue for the subject.
   const suppressedSubjects = new Map<
@@ -259,7 +206,7 @@ export function partitionIssuesByControlPolicy<TIssue>(options: {
       creationFactoryName?: string;
     }
   >();
-  const unresolvedSuppressions: SqlPlannerConflict[] = [];
+  const unresolvedSuppressions: SuppressionRecord[] = [];
 
   for (const issue of options.issues) {
     const subject = options.resolveControlPolicySubject(issue);
@@ -281,10 +228,12 @@ export function partitionIssuesByControlPolicy<TIssue>(options: {
     }
 
     if (subject === undefined) {
-      const factoryName = creationFactoryName ?? 'unknown';
-      unresolvedSuppressions.push(
-        buildSubjectSuppressionWarning(undefined, policy, factoryName, formatSubjectLabel),
-      );
+      unresolvedSuppressions.push({
+        subject: undefined,
+        policy,
+        factoryName: creationFactoryName,
+        createsNewObject: false,
+      });
       continue;
     }
 
@@ -303,20 +252,22 @@ export function partitionIssuesByControlPolicy<TIssue>(options: {
     }
   }
 
-  const warnings: SqlPlannerConflict[] = [...unresolvedSuppressions];
+  const suppressions: SuppressionRecord[] = [...unresolvedSuppressions];
   for (const entry of suppressedSubjects.values()) {
-    const factoryName = entry.creationFactoryName ?? inferModificationFactoryName(entry.subject);
-    warnings.push(
-      buildSubjectSuppressionWarning(entry.subject, entry.policy, factoryName, formatSubjectLabel),
-    );
+    suppressions.push({
+      subject: entry.subject,
+      policy: entry.policy,
+      factoryName: entry.creationFactoryName,
+      createsNewObject: entry.subject.createsNewObject,
+    });
   }
 
   return Object.freeze({
     plannable: Object.freeze(plannable),
-    warnings: Object.freeze(warnings),
+    suppressions: Object.freeze(suppressions),
   });
 }
 
 function subjectKey(subject: ControlPolicySubject): string {
-  return `${subject.namespaceId}\u0000${subject.table ?? ''}\u0000${subject.typeName ?? ''}`;
+  return `${subject.namespaceId}\u0000${subject.entityKind ?? ''}\u0000${subject.entityName ?? ''}`;
 }

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;