@prisma-next/target-postgres 0.3.0-pr.99.5 → 0.3.0

package/src/core/migrations/planner.ts

@@ -1,5 +1,11 @@
-import type { SchemaIssue } from '@prisma-next/core-control-plane/types';
+import {
+  normalizeSchemaNativeType,
+  parsePostgresDefault,
+  quoteIdentifier,
+} from '@prisma-next/adapter-postgres/control';
 import type {
+  CodecControlHooks,
+  ComponentDatabaseDependency,
   MigrationOperationPolicy,
   SqlMigrationPlanner,
   SqlMigrationPlannerPlanOptions,
@@ -7,26 +13,51 @@ import type {
   SqlPlannerConflict,
 } from '@prisma-next/family-sql/control';
 import {
+  collectInitDependencies,
   createMigrationPlan,
+  extractCodecControlHooks,
   plannerFailure,
   plannerSuccess,
 } from '@prisma-next/family-sql/control';
-import {
-  arraysEqual,
-  isIndexSatisfied,
-  isUniqueConstraintSatisfied,
-  verifySqlSchema,
-} from '@prisma-next/family-sql/schema-verify';
+import { verifySqlSchema } from '@prisma-next/family-sql/schema-verify';
+import type { SchemaIssue } from '@prisma-next/framework-components/control';
 import type {
-  ForeignKey,
-  SqlContract,
-  SqlStorage,
   StorageColumn,
   StorageTable,
+  StorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
+import { defaultIndexName } from '@prisma-next/sql-schema-ir/naming';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
-
-type OperationClass = 'extension' | 'table' | 'unique' | 'index' | 'foreignKey';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { buildAddColumnSql, buildCreateTableSql, buildForeignKeySql } from './planner-ddl-builders';
+import { resolveIdentityValue } from './planner-identity-values';
+import {
+  buildAddColumnOperationIdentity,
+  buildAddNotNullColumnWithTemporaryDefaultOperation,
+} from './planner-recipes';
+import { buildReconciliationPlan } from './planner-reconciliation';
+import {
+  buildSchemaLookupMap,
+  hasForeignKey,
+  hasIndex,
+  hasUniqueConstraint,
+  type SchemaTableLookup,
+} from './planner-schema-lookup';
+import {
+  columnExistsCheck,
+  columnNullabilityCheck,
+  constraintExistsCheck,
+  qualifyTableName,
+  tableHasPrimaryKeyCheck,
+  tableIsEmptyCheck,
+  toRegclassLiteral,
+} from './planner-sql-checks';
+import {
+  buildTargetDetails,
+  type OperationClass,
+  type PlanningMode,
+  type PostgresPlanTargetDetails,
+} from './planner-target-details';
 
 type PlannerFrameworkComponents = SqlMigrationPlannerPlanOptions extends {
   readonly frameworkComponents: infer T;
@@ -46,16 +77,8 @@ type PlannerDatabaseDependency = {
   readonly id: string;
   readonly label: string;
   readonly install: readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[];
-  readonly verifyDatabaseDependencyInstalled: (schema: SqlSchemaIR) => readonly SchemaIssue[];
 };
 
-export interface PostgresPlanTargetDetails {
-  readonly schema: string;
-  readonly objectType: OperationClass;
-  readonly name: string;
-  readonly table?: string;
-}
-
 interface PlannerConfig {
   readonly defaultSchema: string;
 }
@@ -83,38 +106,72 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
       return policyResult;
     }
 
-    const classification = this.classifySchema(options);
-    if (classification.kind === 'conflict') {
-      return plannerFailure(classification.conflicts);
-    }
+    const planningMode = this.resolvePlanningMode(options.policy);
+    const schemaIssues = this.collectSchemaIssues(options, planningMode.includeExtraObjects);
+
+    // Extract codec control hooks once at entry point for reuse across all operations.
+    // This avoids repeated iteration over frameworkComponents for each method that needs hooks.
+    const codecHooks = extractCodecControlHooks(options.frameworkComponents);
 
     const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
+    const storageTypes = options.contract.storage.types ?? {};
+
+    const reconciliationPlan = buildReconciliationPlan({
+      contract: options.contract,
+      issues: schemaIssues,
+      schemaName,
+      mode: planningMode,
+      policy: options.policy,
+      codecHooks,
+    });
+    if (reconciliationPlan.conflicts.length > 0) {
+      return plannerFailure(reconciliationPlan.conflicts);
+    }
+
+    const storageTypePlan = this.buildStorageTypeOperations(options, schemaName, codecHooks);
+    if (storageTypePlan.conflicts.length > 0) {
+      return plannerFailure(storageTypePlan.conflicts);
+    }
+
+    // Sort table entries once for reuse across all additive operation builders.
+    const sortedTables = sortedEntries(options.contract.storage.tables);
+
+    // Pre-compute constraint lookups once per schema table for O(1) checks across all builders.
+    const schemaLookups = buildSchemaLookupMap(options.schema);
 
     // Build extension operations from component-owned database dependencies
     operations.push(
       ...this.buildDatabaseDependencyOperations(options),
-      ...this.buildTableOperations(options.contract.storage.tables, options.schema, schemaName),
-      ...this.buildColumnOperations(options.contract.storage.tables, options.schema, schemaName),
-      ...this.buildPrimaryKeyOperations(
-        options.contract.storage.tables,
+      ...storageTypePlan.operations,
+      ...reconciliationPlan.operations,
+      ...this.buildTableOperations(
+        sortedTables,
         options.schema,
         schemaName,
+        codecHooks,
+        storageTypes,
       ),
-      ...this.buildUniqueOperations(options.contract.storage.tables, options.schema, schemaName),
-      ...this.buildIndexOperations(options.contract.storage.tables, options.schema, schemaName),
-      ...this.buildForeignKeyOperations(
-        options.contract.storage.tables,
+      ...this.buildColumnOperations(
+        sortedTables,
         options.schema,
+        schemaLookups,
         schemaName,
+        codecHooks,
+        storageTypes,
       ),
+      ...this.buildPrimaryKeyOperations(sortedTables, options.schema, schemaName),
+      ...this.buildUniqueOperations(sortedTables, schemaLookups, schemaName),
+      ...this.buildIndexOperations(sortedTables, schemaLookups, schemaName),
+      ...this.buildFkBackingIndexOperations(sortedTables, schemaLookups, schemaName),
+      ...this.buildForeignKeyOperations(sortedTables, schemaLookups, schemaName),
     );
 
     const plan = createMigrationPlan<PostgresPlanTargetDetails>({
       targetId: 'postgres',
       origin: null,
       destination: {
-        coreHash: options.contract.coreHash,
-        ...(options.contract.profileHash ? { profileHash: options.contract.profileHash } : {}),
+        storageHash: options.contract.storage.storageHash,
+        ...ifDefined('profileHash', options.contract.profileHash),
       },
       operations,
     });
@@ -127,8 +184,8 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
       return plannerFailure([
         {
           kind: 'unsupportedOperation',
-          summary: 'Init planner requires additive operations be allowed',
-          why: 'The init planner only emits additive operations. Update the policy to include "additive".',
+          summary: 'Migration planner requires additive operations be allowed',
+          why: 'The planner requires the "additive" operation class to be allowed in the policy.',
         },
       ]);
     }
@@ -147,14 +204,15 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
     const seenDependencyIds = new Set<string>();
     const seenOperationIds = new Set<string>();
 
+    const installedIds = new Set(options.schema.dependencies.map((d) => d.id));
+
     for (const dependency of dependencies) {
       if (seenDependencyIds.has(dependency.id)) {
         continue;
       }
       seenDependencyIds.add(dependency.id);
 
-      const issues = dependency.verifyDatabaseDependencyInstalled(options.schema);
-      if (issues.length === 0) {
+      if (installedIds.has(dependency.id)) {
         continue;
       }
 
@@ -163,41 +221,77 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
           continue;
         }
         seenOperationIds.add(installOp.id);
-        // SQL family components are expected to provide compatible target details. This would be better if
-        // the type system could enforce it but it's not likely to occur in practice.
         operations.push(installOp as SqlMigrationPlanOperation<PostgresPlanTargetDetails>);
       }
     }
 
     return operations;
   }
-  private collectDependencies(
+
+  private buildStorageTypeOperations(
     options: PlannerOptionsWithComponents,
-  ): ReadonlyArray<PlannerDatabaseDependency> {
-    const components = options.frameworkComponents;
-    if (components.length === 0) {
-      return [];
-    }
-    const deps: PlannerDatabaseDependency[] = [];
-    for (const component of components) {
-      if (!isSqlDependencyProvider(component)) {
+    schemaName: string,
+    codecHooks: Map<string, CodecControlHooks>,
+  ): {
+    readonly operations: readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[];
+    readonly conflicts: readonly SqlPlannerConflict[];
+  } {
+    const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
+    const conflicts: SqlPlannerConflict[] = [];
+    const storageTypes = options.contract.storage.types ?? {};
+
+    for (const [typeName, typeInstance] of sortedEntries(storageTypes)) {
+      const hook = codecHooks.get(typeInstance.codecId);
+      const planResult = hook?.planTypeOperations?.({
+        typeName,
+        typeInstance,
+        contract: options.contract,
+        schema: options.schema,
+        schemaName,
+        policy: options.policy,
+      });
+      if (!planResult) {
         continue;
       }
-      const initDeps = component.databaseDependencies?.init;
-      if (initDeps && initDeps.length > 0) {
-        deps.push(...initDeps);
+      for (const operation of planResult.operations) {
+        if (!options.policy.allowedOperationClasses.includes(operation.operationClass)) {
+          conflicts.push({
+            kind: 'missingButNonAdditive',
+            summary: `Storage type "${typeName}" requires "${operation.operationClass}" operation "${operation.id}"`,
+            location: {
+              type: typeName,
+            },
+          });
+          continue;
+        }
+        operations.push({
+          ...operation,
+          target: {
+            id: operation.target.id,
+            details: this.buildTargetDetails('type', typeName, schemaName),
+          },
+        });
       }
     }
-    return sortDependencies(deps);
+
+    return { operations, conflicts };
+  }
+  private collectDependencies(
+    options: PlannerOptionsWithComponents,
+  ): ReadonlyArray<PlannerDatabaseDependency> {
+    const dependencies = collectInitDependencies(options.frameworkComponents);
+    return sortDependencies(dependencies.filter(isPostgresPlannerDependency));
   }
 
   private buildTableOperations(
-    tables: SqlContract<SqlStorage>['storage']['tables'],
+    tables: ReadonlyArray<[string, StorageTable]>,
     schema: SqlSchemaIR,
     schemaName: string,
+    codecHooks: Map<string, CodecControlHooks>,
+    storageTypes: Record<string, StorageTypeInstance>,
   ): readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] {
     const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
-    for (const [tableName, table] of sortedEntries(tables)) {
+    for (const [tableName, table] of tables) {
       if (schema.tables[tableName]) {
         continue;
       }
@@ -220,7 +314,7 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
         execute: [
           {
             description: `create table "${tableName}"`,
-            sql: buildCreateTableSql(qualified, table),
+            sql: buildCreateTableSql(qualified, table, codecHooks, storageTypes),
           },
         ],
         postcheck: [
@@ -235,91 +329,155 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
   }
 
   private buildColumnOperations(
-    tables: SqlContract<SqlStorage>['storage']['tables'],
+    tables: ReadonlyArray<[string, StorageTable]>,
     schema: SqlSchemaIR,
+    schemaLookups: ReadonlyMap<string, SchemaTableLookup>,
     schemaName: string,
+    codecHooks: Map<string, CodecControlHooks>,
+    storageTypes: Record<string, StorageTypeInstance>,
   ): readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] {
     const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
-    for (const [tableName, table] of sortedEntries(tables)) {
+    for (const [tableName, table] of tables) {
       const schemaTable = schema.tables[tableName];
       if (!schemaTable) {
         continue;
       }
+      const schemaLookup = schemaLookups.get(tableName);
       for (const [columnName, column] of sortedEntries(table.columns)) {
         if (schemaTable.columns[columnName]) {
           continue;
         }
-        operations.push(this.buildAddColumnOperation(schemaName, tableName, columnName, column));
+        operations.push(
+          this.buildAddColumnOperation({
+            schema: schemaName,
+            tableName,
+            table,
+            schemaTable,
+            schemaLookup,
+            columnName,
+            column,
+            codecHooks,
+            storageTypes,
+          }),
+        );
       }
     }
     return operations;
   }
 
-  private buildAddColumnOperation(
-    schema: string,
-    tableName: string,
-    columnName: string,
-    column: StorageColumn,
-  ): SqlMigrationPlanOperation<PostgresPlanTargetDetails> {
-    const qualified = qualifyTableName(schema, tableName);
-    const notNull = column.nullable === false;
-    const precheck = [
-      {
-        description: `ensure column "${columnName}" is missing`,
-        sql: columnExistsCheck({ schema, table: tableName, column: columnName, exists: false }),
-      },
-      ...(notNull
-        ? [
-            {
-              description: `ensure table "${tableName}" is empty before adding NOT NULL column`,
-              sql: tableIsEmptyCheck(qualified),
-            },
-          ]
-        : []),
-    ];
-    const execute = [
-      {
-        description: `add column "${columnName}"`,
-        sql: buildAddColumnSql(qualified, columnName, column),
-      },
-    ];
-    const postcheck = [
-      {
-        description: `verify column "${columnName}" exists`,
-        sql: columnExistsCheck({ schema, table: tableName, column: columnName }),
-      },
-      ...(notNull
-        ? [
-            {
-              description: `verify column "${columnName}" is NOT NULL`,
-              sql: columnIsNotNullCheck({ schema, table: tableName, column: columnName }),
-            },
-          ]
-        : []),
-    ];
+  private buildAddColumnOperation(options: {
+    readonly schema: string;
+    readonly tableName: string;
+    readonly table: StorageTable;
+    readonly schemaTable: SqlSchemaIR['tables'][string];
+    readonly schemaLookup: SchemaTableLookup | undefined;
+    readonly columnName: string;
+    readonly column: StorageColumn;
+    readonly codecHooks: Map<string, CodecControlHooks>;
+    readonly storageTypes: Record<string, StorageTypeInstance>;
+  }): SqlMigrationPlanOperation<PostgresPlanTargetDetails> {
+    const {
+      schema,
+      tableName,
+      table,
+      schemaTable,
+      schemaLookup,
+      columnName,
+      column,
+      codecHooks,
+      storageTypes,
+    } = options;
+    const notNull = !column.nullable;
+    const hasDefault = column.default !== undefined;
+    // Planner logic decides whether this column needs the coordinated multi-step
+    // strategy. The strategy recipe itself is built by a dedicated helper.
+    const needsTemporaryDefault = notNull && !hasDefault;
+    const temporaryDefault = needsTemporaryDefault
+      ? resolveIdentityValue(column, codecHooks, storageTypes)
+      : null;
+    const canUseSharedTemporaryDefault =
+      needsTemporaryDefault &&
+      temporaryDefault !== null &&
+      canUseSharedTemporaryDefaultStrategy({
+        table,
+        schemaTable,
+        schemaLookup,
+        columnName,
+      });
 
+    if (canUseSharedTemporaryDefault) {
+      return buildAddNotNullColumnWithTemporaryDefaultOperation({
+        schema,
+        tableName,
+        columnName,
+        column,
+        codecHooks,
+        storageTypes,
+        temporaryDefault,
+      });
+    }
+
+    const qualified = qualifyTableName(schema, tableName);
+    const requiresEmptyTableCheck = needsTemporaryDefault && !canUseSharedTemporaryDefault;
     return {
-      id: `column.${tableName}.${columnName}`,
-      label: `Add column ${columnName} to ${tableName}`,
-      summary: `Adds column ${columnName} to table ${tableName}`,
+      ...buildAddColumnOperationIdentity(schema, tableName, columnName),
       operationClass: 'additive',
-      target: {
-        id: 'postgres',
-        details: this.buildTargetDetails('table', tableName, schema),
-      },
-      precheck,
-      execute,
-      postcheck,
+      precheck: [
+        {
+          description: `ensure column "${columnName}" is missing`,
+          sql: columnExistsCheck({ schema, table: tableName, column: columnName, exists: false }),
+        },
+        ...(requiresEmptyTableCheck
+          ? [
+              {
+                description: `ensure table "${tableName}" is empty before adding NOT NULL column without default`,
+                sql: tableIsEmptyCheck(qualified),
+              },
+            ]
+          : []),
+      ],
+      execute: [
+        {
+          description: `add column "${columnName}"`,
+          sql: buildAddColumnSql(
+            qualified,
+            columnName,
+            column,
+            codecHooks,
+            undefined,
+            storageTypes,
+          ),
+        },
+      ],
+      postcheck: [
+        {
+          description: `verify column "${columnName}" exists`,
+          sql: columnExistsCheck({ schema, table: tableName, column: columnName }),
+        },
+        ...(notNull
+          ? [
+              {
+                description: `verify column "${columnName}" is NOT NULL`,
+                sql: columnNullabilityCheck({
+                  schema,
+                  table: tableName,
+                  column: columnName,
+                  nullable: false,
+                }),
+              },
+            ]
+          : []),
+      ],
     };
   }
 
   private buildPrimaryKeyOperations(
-    tables: SqlContract<SqlStorage>['storage']['tables'],
+    tables: ReadonlyArray<[string, StorageTable]>,
     schema: SqlSchemaIR,
     schemaName: string,
   ): readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] {
     const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
-    for (const [tableName, table] of sortedEntries(tables)) {
+    for (const [tableName, table] of tables) {
       if (!table.primaryKey) {
         continue;
       }
@@ -363,15 +521,15 @@ PRIMARY KEY (${table.primaryKey.columns.map(quoteIdentifier).join(', ')})`,
   }
 
   private buildUniqueOperations(
-    tables: SqlContract<SqlStorage>['storage']['tables'],
-    schema: SqlSchemaIR,
+    tables: ReadonlyArray<[string, StorageTable]>,
+    schemaLookups: ReadonlyMap<string, SchemaTableLookup>,
     schemaName: string,
   ): readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] {
     const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
-    for (const [tableName, table] of sortedEntries(tables)) {
-      const schemaTable = schema.tables[tableName];
+    for (const [tableName, table] of tables) {
+      const lookup = schemaLookups.get(tableName);
       for (const unique of table.uniques) {
-        if (schemaTable && hasUniqueConstraint(schemaTable, unique.columns)) {
+        if (lookup && hasUniqueConstraint(lookup, unique.columns)) {
           continue;
         }
         const constraintName = unique.name ?? `${tableName}_${unique.columns.join('_')}_key`;
@@ -387,7 +545,12 @@ PRIMARY KEY (${table.primaryKey.columns.map(quoteIdentifier).join(', ')})`,
           precheck: [
             {
               description: `ensure unique constraint "${constraintName}" is missing`,
-              sql: constraintExistsCheck({ constraintName, schema: schemaName, exists: false }),
+              sql: constraintExistsCheck({
+                constraintName,
+                schema: schemaName,
+                table: tableName,
+                exists: false,
+              }),
             },
           ],
           execute: [
@@ -401,7 +564,7 @@ UNIQUE (${unique.columns.map(quoteIdentifier).join(', ')})`,
           postcheck: [
             {
               description: `verify unique constraint "${constraintName}" exists`,
-              sql: constraintExistsCheck({ constraintName, schema: schemaName }),
+              sql: constraintExistsCheck({ constraintName, schema: schemaName, table: tableName }),
             },
           ],
         });
@@ -411,18 +574,18 @@ UNIQUE (${unique.columns.map(quoteIdentifier).join(', ')})`,
   }
 
   private buildIndexOperations(
-    tables: SqlContract<SqlStorage>['storage']['tables'],
-    schema: SqlSchemaIR,
+    tables: ReadonlyArray<[string, StorageTable]>,
+    schemaLookups: ReadonlyMap<string, SchemaTableLookup>,
     schemaName: string,
   ): readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] {
     const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
-    for (const [tableName, table] of sortedEntries(tables)) {
-      const schemaTable = schema.tables[tableName];
+    for (const [tableName, table] of tables) {
+      const lookup = schemaLookups.get(tableName);
       for (const index of table.indexes) {
-        if (schemaTable && hasIndex(schemaTable, index.columns)) {
+        if (lookup && hasIndex(lookup, index.columns)) {
           continue;
         }
-        const indexName = index.name ?? `${tableName}_${index.columns.join('_')}_idx`;
+        const indexName = index.name ?? defaultIndexName(tableName, index.columns);
         operations.push({
           id: `index.${tableName}.${indexName}`,
           label: `Create index ${indexName} on ${tableName}`,
@@ -459,16 +622,76 @@ UNIQUE (${unique.columns.map(quoteIdentifier).join(', ')})`,
     return operations;
   }
 
+  /**
+   * Generates FK-backing index operations for FKs with `index: true`,
+   * but only when no matching user-declared index exists in `contractTable.indexes`.
+   */
+  private buildFkBackingIndexOperations(
+    tables: ReadonlyArray<[string, StorageTable]>,
+    schemaLookups: ReadonlyMap<string, SchemaTableLookup>,
+    schemaName: string,
+  ): readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] {
+    const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
+    for (const [tableName, table] of tables) {
+      const lookup = schemaLookups.get(tableName);
+      // Collect column sets of user-declared indexes to avoid duplicates
+      const declaredIndexColumns = new Set(table.indexes.map((idx) => idx.columns.join(',')));
+
+      for (const fk of table.foreignKeys) {
+        if (fk.index === false) continue;
+        // Skip if user already declared an index with these columns
+        if (declaredIndexColumns.has(fk.columns.join(','))) continue;
+        // Skip if the index already exists in the database
+        if (lookup && hasIndex(lookup, fk.columns)) continue;
+
+        const indexName = defaultIndexName(tableName, fk.columns);
+        operations.push({
+          id: `index.${tableName}.${indexName}`,
+          label: `Create FK-backing index ${indexName} on ${tableName}`,
+          summary: `Creates FK-backing index ${indexName} on ${tableName}`,
+          operationClass: 'additive',
+          target: {
+            id: 'postgres',
+            details: this.buildTargetDetails('index', indexName, schemaName, tableName),
+          },
+          precheck: [
+            {
+              description: `ensure index "${indexName}" is missing`,
+              sql: `SELECT to_regclass(${toRegclassLiteral(schemaName, indexName)}) IS NULL`,
+            },
+          ],
+          execute: [
+            {
+              description: `create FK-backing index "${indexName}"`,
+              sql: `CREATE INDEX ${quoteIdentifier(indexName)} ON ${qualifyTableName(
+                schemaName,
+                tableName,
+              )} (${fk.columns.map(quoteIdentifier).join(', ')})`,
+            },
+          ],
+          postcheck: [
+            {
+              description: `verify index "${indexName}" exists`,
+              sql: `SELECT to_regclass(${toRegclassLiteral(schemaName, indexName)}) IS NOT NULL`,
+            },
+          ],
+        });
+      }
+    }
+    return operations;
+  }
+
   private buildForeignKeyOperations(
-    tables: SqlContract<SqlStorage>['storage']['tables'],
-    schema: SqlSchemaIR,
+    tables: ReadonlyArray<[string, StorageTable]>,
+    schemaLookups: ReadonlyMap<string, SchemaTableLookup>,
     schemaName: string,
   ): readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] {
     const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
-    for (const [tableName, table] of sortedEntries(tables)) {
-      const schemaTable = schema.tables[tableName];
+    for (const [tableName, table] of tables) {
+      const lookup = schemaLookups.get(tableName);
       for (const foreignKey of table.foreignKeys) {
-        if (schemaTable && hasForeignKey(schemaTable, foreignKey)) {
+        if (foreignKey.constraint === false) continue;
+        if (lookup && hasForeignKey(lookup, foreignKey)) {
           continue;
         }
         const fkName = foreignKey.name ?? `${tableName}_${foreignKey.columns.join('_')}_fkey`;
@@ -487,6 +710,7 @@ UNIQUE (${unique.columns.map(quoteIdentifier).join(', ')})`,
               sql: constraintExistsCheck({
                 constraintName: fkName,
                 schema: schemaName,
+                table: tableName,
                 exists: false,
               }),
             },
@@ -494,18 +718,17 @@ UNIQUE (${unique.columns.map(quoteIdentifier).join(', ')})`,
           execute: [
             {
               description: `add foreign key "${fkName}"`,
-              sql: `ALTER TABLE ${qualifyTableName(schemaName, tableName)}
-ADD CONSTRAINT ${quoteIdentifier(fkName)}
-FOREIGN KEY (${foreignKey.columns.map(quoteIdentifier).join(', ')})
-REFERENCES ${qualifyTableName(schemaName, foreignKey.references.table)} (${foreignKey.references.columns
-                .map(quoteIdentifier)
-                .join(', ')})`,
+              sql: buildForeignKeySql(schemaName, tableName, fkName, foreignKey),
             },
           ],
           postcheck: [
             {
               description: `verify foreign key "${fkName}" exists`,
-              sql: constraintExistsCheck({ constraintName: fkName, schema: schemaName }),
+              sql: constraintExistsCheck({
+                constraintName: fkName,
+                schema: schemaName,
+                table: tableName,
+              }),
             },
           ],
         });
@@ -520,356 +743,83 @@ REFERENCES ${qualifyTableName(schemaName, foreignKey.references.table)} (${forei
     schema: string,
     table?: string,
   ): PostgresPlanTargetDetails {
-    return {
-      schema,
-      objectType,
-      name,
-      ...(table ? { table } : {}),
-    };
+    return buildTargetDetails(objectType, name, schema, table);
   }
 
-  private classifySchema(options: PlannerOptionsWithComponents):
-    | { kind: 'ok' }
-    | {
-        kind: 'conflict';
-        conflicts: SqlPlannerConflict[];
-      } {
+  private resolvePlanningMode(policy: MigrationOperationPolicy): PlanningMode {
+    const allowWidening = policy.allowedOperationClasses.includes('widening');
+    const allowDestructive = policy.allowedOperationClasses.includes('destructive');
+    // `db init` uses additive-only policy and intentionally ignores extras.
+    // Any reconciliation-capable policy should inspect extras to reconcile strict equality.
+    const includeExtraObjects = allowWidening || allowDestructive;
+    return { includeExtraObjects, allowWidening, allowDestructive };
+  }
+
+  private collectSchemaIssues(
+    options: PlannerOptionsWithComponents,
+    strict: boolean,
+  ): readonly SchemaIssue[] {
     const verifyOptions: VerifySqlSchemaOptionsWithComponents = {
       contract: options.contract,
       schema: options.schema,
-      strict: false,
+      strict,
       typeMetadataRegistry: new Map(),
       frameworkComponents: options.frameworkComponents,
+      normalizeDefault: parsePostgresDefault,
+      normalizeNativeType: normalizeSchemaNativeType,
     };
     const verifyResult = verifySqlSchema(verifyOptions);
-
-    const conflicts = this.extractConflicts(verifyResult.schema.issues);
-    if (conflicts.length > 0) {
-      return { kind: 'conflict', conflicts };
-    }
-    return { kind: 'ok' };
-  }
-
-  private extractConflicts(issues: readonly SchemaIssue[]): SqlPlannerConflict[] {
-    const conflicts: SqlPlannerConflict[] = [];
-    for (const issue of issues) {
-      if (isAdditiveIssue(issue)) {
-        continue;
-      }
-      const conflict = this.convertIssueToConflict(issue);
-      if (conflict) {
-        conflicts.push(conflict);
-      }
-    }
-    return conflicts.sort(conflictComparator);
-  }
-
-  private convertIssueToConflict(issue: SchemaIssue): SqlPlannerConflict | null {
-    switch (issue.kind) {
-      case 'type_mismatch':
-        return this.buildConflict('typeMismatch', issue);
-      case 'nullability_mismatch':
-        return this.buildConflict('nullabilityConflict', issue);
-      case 'primary_key_mismatch':
-        return this.buildConflict('indexIncompatible', issue);
-      case 'unique_constraint_mismatch':
-        return this.buildConflict('indexIncompatible', issue);
-      case 'index_mismatch':
-        return this.buildConflict('indexIncompatible', issue);
-      case 'foreign_key_mismatch':
-        return this.buildConflict('foreignKeyConflict', issue);
-      default:
-        return null;
-    }
-  }
-
-  private buildConflict(kind: SqlPlannerConflict['kind'], issue: SchemaIssue): SqlPlannerConflict {
-    const location = buildConflictLocation(issue);
-    const meta =
-      issue.expected || issue.actual
-        ? Object.freeze({
-            ...(issue.expected ? { expected: issue.expected } : {}),
-            ...(issue.actual ? { actual: issue.actual } : {}),
-          })
-        : undefined;
-
-    return {
-      kind,
-      summary: issue.message,
-      ...(location ? { location } : {}),
-      ...(meta ? { meta } : {}),
-    };
+    return verifyResult.schema.issues;
   }
 }
 
-function isSqlDependencyProvider(component: unknown): component is {
-  readonly databaseDependencies?: {
-    readonly init?: readonly PlannerDatabaseDependency[];
-  };
-} {
-  if (typeof component !== 'object' || component === null) {
+function canUseSharedTemporaryDefaultStrategy(options: {
+  readonly table: StorageTable;
+  readonly schemaTable: SqlSchemaIR['tables'][string];
+  readonly schemaLookup: SchemaTableLookup | undefined;
+  readonly columnName: string;
+}): boolean {
+  const { table, schemaTable, schemaLookup, columnName } = options;
+
+  // Shared placeholders are only safe when later plan steps do not require
+  // row-specific values for this newly added column.
+  if (table.primaryKey?.columns.includes(columnName) && !schemaTable.primaryKey) {
     return false;
   }
-  const record = component as Record<string, unknown>;
 
-  // If present, enforce familyId match to avoid mixing families at runtime.
-  if (Object.hasOwn(record, 'familyId') && record['familyId'] !== 'sql') {
-    return false;
+  for (const unique of table.uniques) {
+    if (!unique.columns.includes(columnName)) {
+      continue;
+    }
+    if (!schemaLookup || !hasUniqueConstraint(schemaLookup, unique.columns)) {
+      return false;
+    }
   }
 
-  if (!Object.hasOwn(record, 'databaseDependencies')) {
-    return false;
+  for (const foreignKey of table.foreignKeys) {
+    if (foreignKey.constraint === false || !foreignKey.columns.includes(columnName)) {
+      continue;
+    }
+    if (!schemaLookup || !hasForeignKey(schemaLookup, foreignKey)) {
+      return false;
+    }
   }
-  const deps = record['databaseDependencies'];
-  return deps === undefined || (typeof deps === 'object' && deps !== null);
+
+  return true;
 }
 
 function sortDependencies(
   dependencies: ReadonlyArray<PlannerDatabaseDependency>,
 ): ReadonlyArray<PlannerDatabaseDependency> {
-  if (dependencies.length <= 1) {
-    return dependencies;
-  }
   return [...dependencies].sort((a, b) => a.id.localeCompare(b.id));
 }
 
-function buildCreateTableSql(qualifiedTableName: string, table: StorageTable): string {
-  const columnDefinitions = Object.entries(table.columns).map(
-    ([columnName, column]: [string, StorageColumn]) => {
-      const parts = [
-        quoteIdentifier(columnName),
-        column.nativeType,
-        column.nullable ? '' : 'NOT NULL',
-      ].filter(Boolean);
-      return parts.join(' ');
-    },
-  );
-
-  const constraintDefinitions: string[] = [];
-  if (table.primaryKey) {
-    constraintDefinitions.push(
-      `PRIMARY KEY (${table.primaryKey.columns.map(quoteIdentifier).join(', ')})`,
-    );
-  }
-
-  const allDefinitions = [...columnDefinitions, ...constraintDefinitions];
-  return `CREATE TABLE ${qualifiedTableName} (\n  ${allDefinitions.join(',\n  ')}\n)`;
-}
-
-function qualifyTableName(schema: string, table: string): string {
-  return `${quoteIdentifier(schema)}.${quoteIdentifier(table)}`;
-}
-
-function toRegclassLiteral(schema: string, name: string): string {
-  const regclass = `${quoteIdentifier(schema)}.${quoteIdentifier(name)}`;
-  return `'${escapeLiteral(regclass)}'`;
-}
-
-/** Escapes and quotes a SQL identifier (table, column, schema name). */
-function quoteIdentifier(identifier: string): string {
-  // TypeScript enforces string type - no runtime check needed for internal callers
-  return `"${identifier.replace(/"/g, '""')}"`;
-}
-
-function escapeLiteral(value: string): string {
-  return value.replace(/'/g, "''");
+function isPostgresPlannerDependency(
+  dependency: ComponentDatabaseDependency<unknown>,
+): dependency is PlannerDatabaseDependency {
+  return dependency.install.every((operation) => operation.target.id === 'postgres');
 }
 
 function sortedEntries<V>(record: Readonly<Record<string, V>>): Array<[string, V]> {
   return Object.entries(record).sort(([a], [b]) => a.localeCompare(b)) as Array<[string, V]>;
 }
-
-function constraintExistsCheck({
-  constraintName,
-  schema,
-  exists = true,
-}: {
-  constraintName: string;
-  schema: string;
-  exists?: boolean;
-}): string {
-  const existsClause = exists ? 'EXISTS' : 'NOT EXISTS';
-  return `SELECT ${existsClause} (
-  SELECT 1 FROM pg_constraint c
-  JOIN pg_namespace n ON c.connamespace = n.oid
-  WHERE c.conname = '${escapeLiteral(constraintName)}'
-  AND n.nspname = '${escapeLiteral(schema)}'
-)`;
-}
-
-function columnExistsCheck({
-  schema,
-  table,
-  column,
-  exists = true,
-}: {
-  schema: string;
-  table: string;
-  column: string;
-  exists?: boolean;
-}): string {
-  const existsClause = exists ? '' : 'NOT ';
-  return `SELECT ${existsClause}EXISTS (
-  SELECT 1
-  FROM information_schema.columns
-  WHERE table_schema = '${escapeLiteral(schema)}'
-    AND table_name = '${escapeLiteral(table)}'
-    AND column_name = '${escapeLiteral(column)}'
-)`;
-}
-
-function columnIsNotNullCheck({
-  schema,
-  table,
-  column,
-}: {
-  schema: string;
-  table: string;
-  column: string;
-}): string {
-  return `SELECT EXISTS (
-  SELECT 1
-  FROM information_schema.columns
-  WHERE table_schema = '${escapeLiteral(schema)}'
-    AND table_name = '${escapeLiteral(table)}'
-    AND column_name = '${escapeLiteral(column)}'
-    AND is_nullable = 'NO'
-)`;
-}
-
-function tableIsEmptyCheck(qualifiedTableName: string): string {
-  return `SELECT NOT EXISTS (SELECT 1 FROM ${qualifiedTableName} LIMIT 1)`;
-}
-
-function buildAddColumnSql(
-  qualifiedTableName: string,
-  columnName: string,
-  column: StorageColumn,
-): string {
-  const parts = [
-    `ALTER TABLE ${qualifiedTableName}`,
-    `ADD COLUMN ${quoteIdentifier(columnName)} ${column.nativeType}`,
-    column.nullable ? '' : 'NOT NULL',
-  ].filter(Boolean);
-  return parts.join(' ');
-}
-
-function tableHasPrimaryKeyCheck(
-  schema: string,
-  table: string,
-  exists: boolean,
-  constraintName?: string,
-): string {
-  const comparison = exists ? '' : 'NOT ';
-  const constraintFilter = constraintName
-    ? `AND c2.relname = '${escapeLiteral(constraintName)}'`
-    : '';
-  return `SELECT ${comparison}EXISTS (
-  SELECT 1
-  FROM pg_index i
-  JOIN pg_class c ON c.oid = i.indrelid
-  JOIN pg_namespace n ON n.oid = c.relnamespace
-  LEFT JOIN pg_class c2 ON c2.oid = i.indexrelid
-  WHERE n.nspname = '${escapeLiteral(schema)}'
-    AND c.relname = '${escapeLiteral(table)}'
-    AND i.indisprimary
-    ${constraintFilter}
-)`;
-}
-
-/**
- * Checks if table has a unique constraint satisfied by the given columns.
- * Uses shared semantic satisfaction predicate from verify-helpers.
- */
-function hasUniqueConstraint(
-  table: SqlSchemaIR['tables'][string],
-  columns: readonly string[],
-): boolean {
-  return isUniqueConstraintSatisfied(table.uniques, table.indexes, columns);
-}
-
-/**
- * Checks if table has an index satisfied by the given columns.
- * Uses shared semantic satisfaction predicate from verify-helpers.
- */
-function hasIndex(table: SqlSchemaIR['tables'][string], columns: readonly string[]): boolean {
-  return isIndexSatisfied(table.indexes, table.uniques, columns);
-}
-
-function hasForeignKey(table: SqlSchemaIR['tables'][string], fk: ForeignKey): boolean {
-  return table.foreignKeys.some(
-    (candidate) =>
-      arraysEqual(candidate.columns, fk.columns) &&
-      candidate.referencedTable === fk.references.table &&
-      arraysEqual(candidate.referencedColumns, fk.references.columns),
-  );
-}
-
-function isAdditiveIssue(issue: SchemaIssue): boolean {
-  switch (issue.kind) {
-    case 'missing_table':
-    case 'missing_column':
-    case 'extension_missing':
-      return true;
-    case 'primary_key_mismatch':
-      return issue.actual === undefined;
-    case 'unique_constraint_mismatch':
-    case 'index_mismatch':
-    case 'foreign_key_mismatch':
-      return issue.indexOrConstraint === undefined;
-    default:
-      return false;
-  }
-}
-
-function buildConflictLocation(issue: SchemaIssue) {
-  const location: {
-    table?: string;
-    column?: string;
-    constraint?: string;
-  } = {};
-  if (issue.table) {
-    location.table = issue.table;
-  }
-  if (issue.column) {
-    location.column = issue.column;
-  }
-  if (issue.indexOrConstraint) {
-    location.constraint = issue.indexOrConstraint;
-  }
-  return Object.keys(location).length > 0 ? location : undefined;
-}
-
-function conflictComparator(a: SqlPlannerConflict, b: SqlPlannerConflict): number {
-  if (a.kind !== b.kind) {
-    return a.kind < b.kind ? -1 : 1;
-  }
-  const aLocation = a.location ?? {};
-  const bLocation = b.location ?? {};
-  const tableCompare = compareStrings(aLocation.table, bLocation.table);
-  if (tableCompare !== 0) {
-    return tableCompare;
-  }
-  const columnCompare = compareStrings(aLocation.column, bLocation.column);
-  if (columnCompare !== 0) {
-    return columnCompare;
-  }
-  const constraintCompare = compareStrings(aLocation.constraint, bLocation.constraint);
-  if (constraintCompare !== 0) {
-    return constraintCompare;
-  }
-  return compareStrings(a.summary, b.summary);
-}
-
-function compareStrings(a?: string, b?: string): number {
-  if (a === b) {
-    return 0;
-  }
-  if (a === undefined) {
-    return -1;
-  }
-  if (b === undefined) {
-    return 1;
-  }
-  return a < b ? -1 : 1;
-}