@prisma-next/family-sql 0.14.0-dev.6 → 0.14.0-dev.61

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/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;

package/src/core/migrations/types.ts

@@ -1,11 +1,9 @@
 import type { Contract } from '@prisma-next/contract/types';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
-  ContractSerializer,
   ContractSpace,
   ControlAdapterDescriptor,
   ControlExtensionDescriptor,
-  MigratableTargetDescriptor,
   MigrationOperationPolicy,
   MigrationPlan,
   MigrationPlannerConflict,
@@ -18,8 +16,8 @@ import type {
   MigrationRunnerResult,
   OperationContext,
   OpFactoryCall,
-  SchemaIssue,
-  SchemaVerifier,
+  SchemaDiffIssue,
+  SchemaOwnership,
 } from '@prisma-next/framework-components/control';
 import type { AggregateMigrationEdgeRef } from '@prisma-next/migration-tools/aggregate';
 import type {
@@ -30,10 +28,9 @@ import type {
   StorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
 import type { SqlOperationDescriptors } from '@prisma-next/sql-operations';
-import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
+import type { SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
 import type { Result } from '@prisma-next/utils/result';
 import type { SqlControlAdapter } from '../control-adapter';
-import type { SqlControlFamilyInstance } from '../control-instance';
 
 export type AnyRecord = Readonly<Record<string, unknown>>;
 
@@ -102,20 +99,29 @@ export interface FieldEventContext {
 }
 
 export interface CodecControlHooks<TTargetDetails = unknown> {
+  /**
+   * `schema` is typed as the family-level `SqlSchemaIRNode` (not the concrete
+   * `SqlSchemaIR` class) because the actual value handed in is whatever
+   * per-namespace node the calling target's tree shape produces — a flat
+   * `SqlSchemaIR` for SQLite, a `PostgresNamespaceSchemaNode` for Postgres —
+   * read structurally for its `tables`/`nativeEnumTypeNames` fields. Hooks
+   * that need the concrete Postgres shape narrow via
+   * `PostgresNamespaceSchemaNode.is(schema)`.
+   */
   planTypeOperations?: (options: {
     readonly typeName: string;
     readonly typeInstance: StorageTypeInstance;
     readonly contract: Contract<SqlStorage>;
-    readonly schema: SqlSchemaIR;
+    readonly schema: SqlSchemaIRNode;
     readonly schemaName?: string;
     readonly policy: MigrationOperationPolicy;
   }) => StorageTypePlanResult<TTargetDetails>;
   verifyType?: (options: {
     readonly typeName: string;
     readonly typeInstance: StorageTypeInstance;
-    readonly schema: SqlSchemaIR;
+    readonly schema: SqlSchemaIRNode;
     readonly schemaName?: string;
-  }) => readonly SchemaIssue[];
+  }) => readonly SchemaDiffIssue[];
   introspectTypes?: (options: {
     readonly driver: SqlControlDriverInstance<string>;
     readonly schemaName?: string;
@@ -308,7 +314,12 @@ export type SqlPlannerResult<TTargetDetails> =
 
 export interface SqlMigrationPlannerPlanOptions {
   readonly contract: Contract<SqlStorage>;
-  readonly schema: SqlSchemaIR;
+  /**
+   * The "from"/live schema as the target's introspected node (SQLite a flat
+   * `SqlSchemaIR`, Postgres a `PostgresDatabaseSchemaNode` root). Structure-aware
+   * consumers narrow the concrete shape before walking it.
+   */
+  readonly schema: SqlSchemaIRNode;
   readonly policy: MigrationOperationPolicy;
   readonly schemaName?: string;
   /**
@@ -343,6 +354,16 @@ export interface SqlMigrationPlannerPlanOptions {
    * All components must have matching familyId ('sql') and targetId.
    */
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+  /**
+   * Ownership oracle over the whole contract-space composition (the passive
+   * aggregate). The planner asks it, per live extra node, whether any space
+   * declares that entity: a sibling-owned node is left untouched, an unowned
+   * node is a genuine extra it may drop under a destructive policy. The
+   * planner holds no list of other spaces' names — ownership lives in the
+   * aggregate; it only asks. Absent for a single-space plan handed no
+   * aggregate. See {@link SchemaOwnership}.
+   */
+  readonly ownership?: SchemaOwnership;
 }
 
 export interface SqlMigrationPlanner<TTargetDetails> {
@@ -456,30 +477,6 @@ export interface SqlMigrationRunner<TTargetDetails> {
   ): Promise<SqlMigrationRunnerResult>;
 }
 
-export interface SqlControlTargetDescriptor<
-  TTargetId extends string,
-  TTargetDetails,
-  TContract extends Contract<SqlStorage> = Contract<SqlStorage>,
-> extends MigratableTargetDescriptor<'sql', TTargetId, SqlControlFamilyInstance> {
-  readonly queryOperations?: () => SqlOperationDescriptors;
-  /**
-   * JSON ⇄ class boundary for the SQL target's contract. The descriptor
-   * composes a concrete `SqlContractSerializerBase` subclass; the rest
-   * of the control stack reaches `descriptor.contractSerializer` rather
-   * than importing a per-target deserialization function.
-   */
-  readonly contractSerializer: ContractSerializer<TContract>;
-  /**
-   * Per-target schema verifier walking the contract against
-   * `SqlSchemaIR`. The descriptor composes a concrete
-   * `SqlSchemaVerifierBase` subclass; the family-shared walk lives on
-   * the base, the target-specific dispatch on the subclass.
-   */
-  readonly schemaVerifier: SchemaVerifier<TContract, SqlSchemaIR>;
-  createPlanner(adapter: SqlControlAdapter<TTargetId>): SqlMigrationPlanner<TTargetDetails>;
-  createRunner(family: SqlControlFamilyInstance): SqlMigrationRunner<TTargetDetails>;
-}
-
 export interface CreateSqlMigrationPlanOptions<TTargetDetails> {
   readonly targetId: string;
   /**

package/src/core/psl-contract-infer/name-transforms.ts

@@ -127,6 +127,21 @@ export function toEnumName(pgTypeName: string): NameResult {
   return { name };
 }
 
+const VALID_IDENTIFIER_PATTERN = /^[A-Za-z_]\w*$/;
+
+/**
+ * PSL member name for a native-enum value. The value itself always prints
+ * explicitly (`member = "value"`), so the returned name never needs a map:
+ * a value that already is a valid, non-reserved identifier is kept verbatim
+ * (case included); anything else is camelCased/escaped like a field name.
+ */
+export function toEnumMemberName(value: string): string {
+  if (VALID_IDENTIFIER_PATTERN.test(value) && !needsEscaping(value)) {
+    return value;
+  }
+  return escapeIfNeeded(snakeToCamelCase(value));
+}
+
 export function pluralize(word: string): string {
   if (
     word.endsWith('s') ||

package/src/core/psl-contract-infer/printer-config.ts

@@ -1,12 +1,6 @@
 import type { ColumnDefault } from '@prisma-next/contract/types';
 import type { DefaultMappingOptions } from './default-mapping';
 
-/**
- * Internal printer-shaped configuration, used by the SQL family's
- * `sqlSchemaIrToPslAst` helper (M2). The framework-level psl-printer no longer
- * exposes these — they're consumed only inside the SQL family.
- */
-
 export type PslNativeTypeAttribute = {
   readonly name: string;
   readonly args?: readonly string[];
@@ -43,6 +37,18 @@ export interface PslPrinterOptions {
 export type RelationField = {
   readonly fieldName: string;
   readonly typeName: string;
+  /**
+   * Namespace qualifier for a cross-space relation (e.g. `"auth"` for a
+   * relation into `supabase:auth.AuthUser`). Absent for a same-namespace
+   * relation.
+   */
+  readonly typeNamespaceId?: string | undefined;
+  /**
+   * Contract-space qualifier for a relation into another stack extension
+   * pack's contract space (e.g. `"supabase"`). Absent for a same-space
+   * relation.
+   */
+  readonly typeContractSpaceId?: string | undefined;
   readonly referencedTableName?: string | undefined;
   readonly optional: boolean;
   readonly list: boolean;

package/src/core/psl-contract-infer/relation-inference.ts

@@ -136,7 +136,15 @@ function deriveRelationName(
   return fk.columns.join('_');
 }
 
-function buildChildRelationField(
+/**
+ * Builds the child-side {@link RelationField} for a single foreign key:
+ * `typeName` is the parent model name, `fields`/`references` are the FK's raw
+ * columns, and `onDelete`/`onUpdate` are normalized to their PSL spelling.
+ * Exported so a caller resolving a foreign key against a model outside
+ * `tables` (e.g. a cross-space reference into another contract) can reuse the
+ * same normalization instead of duplicating it.
+ */
+export function buildChildRelationField(
   fieldName: string,
   parentModelName: string,
   fk: SqlForeignKeyIR,

package/src/core/sql-migration.ts

@@ -1,5 +1,7 @@
+import type { Contract } from '@prisma-next/contract/types';
 import { deriveProvidedInvariants } from '@prisma-next/migration-tools/invariants';
 import { Migration } from '@prisma-next/migration-tools/migration';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import { isThenable } from '@prisma-next/utils/promise';
 import type { SqlMigrationPlanOperation, SqlPlanTargetDetails } from './migrations/types';
 
@@ -14,13 +16,22 @@ import type { SqlMigrationPlanOperation, SqlPlanTargetDetails } from './migratio
  * fully concrete operation shape. Target-free code in SQL family / tooling
  * parameterises over `TDetails` (and usually `TTargetId = string`).
  *
+ * The `Start` / `End` contract generics are forwarded to the framework
+ * `Migration` base so the derived `describe()` and the per-target view getters
+ * (`PostgresMigration` / `SqliteMigration`) carry each migration's precise
+ * contract types. The view getters themselves live on the per-target bases
+ * because the SQL ContractView shapes differ per target (SQLite unwraps its
+ * sole namespace to the root; Postgres is schema-qualified).
+ *
  * Keeps target-free contract/runtime features in the family layer while
  * letting adapters own target shape.
  */
 export abstract class SqlMigration<
   TDetails extends SqlPlanTargetDetails,
   TTargetId extends string = string,
-> extends Migration<SqlMigrationPlanOperation<TDetails>, 'sql', TTargetId> {
+  Start extends Contract<SqlStorage> = Contract<SqlStorage>,
+  End extends Contract<SqlStorage> = Contract<SqlStorage>,
+> extends Migration<SqlMigrationPlanOperation<TDetails>, 'sql', TTargetId, Start, End> {
   /**
    * Sorted, deduplicated invariant ids declared by this migration's
    * data-transform ops. Derived from `this.operations` so the field remains

package/src/exports/control.ts

@@ -14,6 +14,10 @@ export type {
 export { assembleAuthoringContributions } from '@prisma-next/framework-components/control';
 export { extractCodecControlHooks } from '../core/assembly';
 export type { SqlControlFamilyInstance } from '../core/control-instance';
+export type {
+  SqlControlTargetDescriptor,
+  SqlDescribedContractSpace,
+} from '../core/control-target-descriptor';
 export type {
   ContractToSchemaIROptions,
   DefaultRenderer,
@@ -22,6 +26,7 @@ export type {
 } from '../core/migrations/contract-to-schema-ir';
 // Contract → SchemaIR conversion for offline migration planning
 export {
+  contractNamespaceToSchemaIR,
   contractToSchemaIR,
   detectDestructiveChanges,
   resolveValueSetValues,
@@ -34,6 +39,7 @@ export {
 } from '../core/migrations/control-policy';
 export type { PlanFieldEventOperationsOptions } from '../core/migrations/field-event-planner';
 export { planFieldEventOperations } from '../core/migrations/field-event-planner';
+export { buildNativeTypeExpander } from '../core/migrations/native-type-expander';
 export {
   createMigrationPlan,
   plannerFailure,
@@ -42,6 +48,11 @@ export {
   runnerSuccess,
 } from '../core/migrations/plan-helpers';
 export { INIT_ADDITIVE_POLICY } from '../core/migrations/policies';
+export type {
+  SqlSchemaDiffFn,
+  SqlSchemaDiffInput,
+  SqlSchemaDiffResult,
+} from '../core/migrations/schema-differ';
 export type {
   CodecControlHooks,
   CreateSqlMigrationPlanOptions,
@@ -51,7 +62,6 @@ export type {
   ResolveIdentityValueInput,
   SqlControlAdapterDescriptor,
   SqlControlExtensionDescriptor,
-  SqlControlTargetDescriptor,
   SqlMigrationPlan,
   SqlMigrationPlanContractInfo,
   SqlMigrationPlanner,