@prisma-next/target-postgres 0.4.0-dev.8 → 0.4.1

package/src/core/migrations/issue-planner.ts

@@ -0,0 +1,832 @@
+/**
+ * Postgres migration planner.
+ *
+ * Takes schema issues (from verifySqlSchema) and emits migration IR
+ * (`PostgresOpFactoryCall[]`). Strategies consume issues they recognize and
+ * produce specialized call sequences (e.g. NOT NULL backfill →
+ * addColumn(nullable) + dataTransform + setNotNull); remaining issues flow
+ * through `mapIssueToCall` for the default case.
+ */
+
+import type { Contract } from '@prisma-next/contract/types';
+import type {
+  CodecControlHooks,
+  MigrationOperationPolicy,
+  SqlPlannerConflict,
+  SqlPlannerConflictLocation,
+} from '@prisma-next/family-sql/control';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type { SchemaIssue } from '@prisma-next/framework-components/control';
+import type {
+  SqlStorage,
+  StorageColumn,
+  StorageTypeInstance,
+} from '@prisma-next/sql-contract/types';
+import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
+import type { Result } from '@prisma-next/utils/result';
+import { notOk, ok } from '@prisma-next/utils/result';
+import {
+  AddColumnCall,
+  AddForeignKeyCall,
+  AddPrimaryKeyCall,
+  AddUniqueCall,
+  AlterColumnTypeCall,
+  CreateEnumTypeCall,
+  CreateExtensionCall,
+  CreateIndexCall,
+  CreateSchemaCall,
+  CreateTableCall,
+  DropColumnCall,
+  DropConstraintCall,
+  DropDefaultCall,
+  DropIndexCall,
+  DropNotNullCall,
+  DropTableCall,
+  type PostgresOpFactoryCall,
+  SetDefaultCall,
+  SetNotNullCall,
+} from './op-factory-call';
+import type { ColumnSpec, ForeignKeySpec } from './operations/shared';
+import { buildColumnDefaultSql, buildColumnTypeSql } from './planner-ddl-builders';
+import { buildExpectedFormatType } from './planner-sql-checks';
+import {
+  type CallMigrationStrategy,
+  postgresPlannerStrategies,
+  type StrategyContext,
+} from './planner-strategies';
+
+export type { CallMigrationStrategy, StrategyContext };
+
+// ============================================================================
+// Issue kind ordering (dependency order)
+// ============================================================================
+
+const ISSUE_KIND_ORDER: Record<string, number> = {
+  // Dependencies and types first
+  dependency_missing: 1,
+  type_missing: 2,
+  type_values_mismatch: 3,
+  enum_values_changed: 3,
+
+  // Drops (reconciliation — clear the way for creates)
+  // FKs dropped first (they depend on other constraints)
+  extra_foreign_key: 10,
+  extra_unique_constraint: 11,
+  extra_primary_key: 12,
+  extra_index: 13,
+  extra_default: 14,
+  extra_column: 15,
+  extra_table: 16,
+
+  // Tables before columns
+  missing_table: 20,
+
+  // Columns before constraints
+  missing_column: 30,
+
+  // Reconciliation alters (on existing objects)
+  type_mismatch: 40,
+  nullability_mismatch: 41,
+  default_missing: 42,
+  default_mismatch: 43,
+
+  // Constraints after columns exist
+  primary_key_mismatch: 50,
+  unique_constraint_mismatch: 51,
+  index_mismatch: 52,
+  foreign_key_mismatch: 60,
+};
+
+function issueOrder(issue: SchemaIssue): number {
+  return ISSUE_KIND_ORDER[issue.kind] ?? 99;
+}
+
+// ============================================================================
+// Conflict helpers
+// ============================================================================
+
+function issueConflict(
+  kind: SqlPlannerConflict['kind'],
+  summary: string,
+  location?: SqlPlannerConflict['location'],
+): SqlPlannerConflict {
+  return {
+    kind,
+    summary,
+    why: 'Use `migration new` to author a custom migration for this change.',
+    ...(location ? { location } : {}),
+  };
+}
+
+function isMissing(issue: SchemaIssue): boolean {
+  if (issue.kind === 'enum_values_changed') return false;
+  return issue.actual === undefined;
+}
+
+// ============================================================================
+// Issue planner
+// ============================================================================
+
+export interface IssuePlannerOptions {
+  readonly issues: readonly SchemaIssue[];
+  readonly toContract: Contract<SqlStorage>;
+  readonly fromContract: Contract<SqlStorage> | null;
+  readonly schemaName: string;
+  readonly codecHooks: ReadonlyMap<string, CodecControlHooks>;
+  readonly storageTypes: Readonly<Record<string, StorageTypeInstance>>;
+  /**
+   * Current database schema IR. Strategies read this to detect whether a
+   * structure already exists (e.g. `buildSchemaLookupMap` for shared-temp-
+   * default safety, extension dependency checks). Defaults to an empty schema
+   * when omitted so the planner can still run over "fresh DB" contract
+   * snapshots.
+   */
+  readonly schema?: SqlSchemaIR;
+  /**
+   * Operation-class policy. `planIssues` filters calls whose `operationClass`
+   * is not in `policy.allowedOperationClasses` and surfaces them as conflicts
+   * instead of emitting disallowed DDL. Defaults to additive-only.
+   */
+  readonly policy?: MigrationOperationPolicy;
+  /**
+   * Framework components participating in this composition. Used by the
+   * dependency-install strategy to dispatch `databaseDependencies.init` at
+   * plan time.
+   */
+  readonly frameworkComponents?: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+  readonly strategies?: readonly CallMigrationStrategy[];
+}
+
+export interface IssuePlannerValue {
+  readonly calls: readonly PostgresOpFactoryCall[];
+}
+
+function toColumnSpec(
+  name: string,
+  column: StorageColumn,
+  codecHooks: ReadonlyMap<string, CodecControlHooks>,
+  storageTypes: Readonly<Record<string, StorageTypeInstance>>,
+): ColumnSpec {
+  return {
+    name,
+    typeSql: buildColumnTypeSql(
+      column,
+      codecHooks as Map<string, CodecControlHooks>,
+      storageTypes as Record<string, StorageTypeInstance>,
+    ),
+    defaultSql: buildColumnDefaultSql(column.default, column),
+    nullable: column.nullable,
+  };
+}
+
+function mapIssueToCall(
+  issue: SchemaIssue,
+  ctx: StrategyContext,
+): Result<readonly PostgresOpFactoryCall[], SqlPlannerConflict> {
+  const { schemaName, codecHooks, storageTypes } = ctx;
+
+  switch (issue.kind) {
+    case 'missing_table': {
+      if (!issue.table)
+        return notOk(
+          issueConflict('unsupportedOperation', 'Missing table issue has no table name'),
+        );
+      const contractTable = ctx.toContract.storage.tables[issue.table];
+      if (!contractTable) {
+        return notOk(
+          issueConflict(
+            'unsupportedOperation',
+            `Table "${issue.table}" reported missing but not found in destination contract`,
+          ),
+        );
+      }
+      const columns: ColumnSpec[] = Object.entries(contractTable.columns).map(([name, column]) =>
+        toColumnSpec(name, column, codecHooks, storageTypes),
+      );
+      const primaryKey = contractTable.primaryKey
+        ? { columns: contractTable.primaryKey.columns }
+        : undefined;
+      const calls: PostgresOpFactoryCall[] = [
+        new CreateTableCall(schemaName, issue.table, columns, primaryKey),
+      ];
+      for (const index of contractTable.indexes) {
+        const indexName = index.name ?? `${issue.table}_${index.columns.join('_')}_idx`;
+        calls.push(new CreateIndexCall(schemaName, issue.table, indexName, [...index.columns]));
+      }
+      const explicitIndexColumnSets = new Set(
+        contractTable.indexes.map((idx) => idx.columns.join(',')),
+      );
+      for (const fk of contractTable.foreignKeys) {
+        if (fk.constraint) {
+          const fkName = fk.name ?? `${issue.table}_${fk.columns.join('_')}_fkey`;
+          const fkSpec: ForeignKeySpec = {
+            name: fkName,
+            columns: fk.columns,
+            references: { table: fk.references.table, columns: fk.references.columns },
+            ...(fk.onDelete !== undefined && { onDelete: fk.onDelete }),
+            ...(fk.onUpdate !== undefined && { onUpdate: fk.onUpdate }),
+          };
+          calls.push(new AddForeignKeyCall(schemaName, issue.table, fkSpec));
+        }
+        if (fk.index && !explicitIndexColumnSets.has(fk.columns.join(','))) {
+          const indexName = `${issue.table}_${fk.columns.join('_')}_idx`;
+          calls.push(new CreateIndexCall(schemaName, issue.table, indexName, [...fk.columns]));
+        }
+      }
+      for (const unique of contractTable.uniques) {
+        const constraintName = unique.name ?? `${issue.table}_${unique.columns.join('_')}_key`;
+        calls.push(new AddUniqueCall(schemaName, issue.table, constraintName, [...unique.columns]));
+      }
+      return ok(calls);
+    }
+
+    case 'missing_column':
+      if (!issue.table || !issue.column)
+        return notOk(
+          issueConflict('unsupportedOperation', 'Missing column issue has no table/column name'),
+        );
+      {
+        const column = ctx.toContract.storage.tables[issue.table]?.columns[issue.column];
+        if (!column)
+          return notOk(
+            issueConflict(
+              'unsupportedOperation',
+              `Column "${issue.table}"."${issue.column}" not in destination contract`,
+            ),
+          );
+        return ok([
+          new AddColumnCall(
+            schemaName,
+            issue.table,
+            toColumnSpec(issue.column, column, codecHooks, storageTypes),
+          ),
+        ]);
+      }
+
+    case 'default_missing':
+      if (!issue.table || !issue.column)
+        return notOk(
+          issueConflict('unsupportedOperation', 'Default missing issue has no table/column name'),
+        );
+      {
+        const column = ctx.toContract.storage.tables[issue.table]?.columns[issue.column];
+        if (!column?.default) {
+          return notOk(
+            issueConflict(
+              'unsupportedOperation',
+              `Column "${issue.table}"."${issue.column}" has no default in contract`,
+            ),
+          );
+        }
+        const defaultSql = buildColumnDefaultSql(column.default, column);
+        if (!defaultSql) return ok([]);
+        return ok([new SetDefaultCall(schemaName, issue.table, issue.column, defaultSql)]);
+      }
+
+    case 'extra_table':
+      if (!issue.table)
+        return notOk(issueConflict('unsupportedOperation', 'Extra table issue has no table name'));
+      return ok([new DropTableCall(schemaName, issue.table)]);
+
+    case 'extra_column':
+      if (!issue.table || !issue.column)
+        return notOk(
+          issueConflict('unsupportedOperation', 'Extra column issue has no table/column name'),
+        );
+      return ok([new DropColumnCall(schemaName, issue.table, issue.column)]);
+
+    case 'extra_index':
+      if (!issue.table || !issue.indexOrConstraint)
+        return notOk(
+          issueConflict('unsupportedOperation', 'Extra index issue has no table/index name'),
+        );
+      return ok([new DropIndexCall(schemaName, issue.table, issue.indexOrConstraint)]);
+
+    case 'extra_unique_constraint':
+    case 'extra_foreign_key':
+    case 'extra_primary_key': {
+      if (!issue.table)
+        return notOk(
+          issueConflict(
+            'unsupportedOperation',
+            'Extra constraint issue has no table/constraint name',
+          ),
+        );
+      // `extra_primary_key` issues don't carry a constraint name — the
+      // verifier only has the table. Fall back to `<table>_pkey`, matching
+      // Postgres' default PK constraint naming and the old reconciliation
+      // planner's behavior.
+      const constraintName =
+        issue.indexOrConstraint ??
+        (issue.kind === 'extra_primary_key' ? `${issue.table}_pkey` : undefined);
+      if (!constraintName)
+        return notOk(
+          issueConflict(
+            'unsupportedOperation',
+            'Extra constraint issue has no table/constraint name',
+          ),
+        );
+      const kindMap = {
+        extra_unique_constraint: 'unique' as const,
+        extra_foreign_key: 'foreignKey' as const,
+        extra_primary_key: 'primaryKey' as const,
+      };
+      return ok([
+        new DropConstraintCall(schemaName, issue.table, constraintName, kindMap[issue.kind]),
+      ]);
+    }
+
+    case 'extra_default':
+      if (!issue.table || !issue.column)
+        return notOk(
+          issueConflict('unsupportedOperation', 'Extra default issue has no table/column name'),
+        );
+      return ok([new DropDefaultCall(schemaName, issue.table, issue.column)]);
+
+    case 'nullability_mismatch': {
+      if (!issue.table || !issue.column)
+        return notOk(
+          issueConflict('nullabilityConflict', 'Nullability mismatch has no table/column name'),
+        );
+      const column = ctx.toContract.storage.tables[issue.table]?.columns[issue.column];
+      if (!column)
+        return notOk(
+          issueConflict(
+            'nullabilityConflict',
+            `Column "${issue.table}"."${issue.column}" not found in destination contract`,
+          ),
+        );
+      return ok(
+        column.nullable
+          ? [new DropNotNullCall(schemaName, issue.table, issue.column)]
+          : [new SetNotNullCall(schemaName, issue.table, issue.column)],
+      );
+    }
+
+    case 'type_mismatch':
+      if (!issue.table || !issue.column)
+        return notOk(issueConflict('typeMismatch', 'Type mismatch has no table/column name'));
+      {
+        const column = ctx.toContract.storage.tables[issue.table]?.columns[issue.column];
+        if (!column)
+          return notOk(
+            issueConflict(
+              'typeMismatch',
+              `Column "${issue.table}"."${issue.column}" not in destination contract`,
+            ),
+          );
+        const hooksMap = codecHooks as Map<string, CodecControlHooks>;
+        const typesMap = storageTypes as Record<string, StorageTypeInstance>;
+        const qualifiedTargetType = buildColumnTypeSql(column, hooksMap, typesMap, false);
+        const formatTypeExpected = buildExpectedFormatType(column, hooksMap, typesMap);
+        return ok([
+          new AlterColumnTypeCall(schemaName, issue.table, issue.column, {
+            qualifiedTargetType,
+            formatTypeExpected,
+            rawTargetTypeForLabel: qualifiedTargetType,
+          }),
+        ]);
+      }
+
+    case 'default_mismatch':
+      if (!issue.table || !issue.column)
+        return notOk(
+          issueConflict('unsupportedOperation', 'Default mismatch has no table/column name'),
+        );
+      {
+        const column = ctx.toContract.storage.tables[issue.table]?.columns[issue.column];
+        if (!column?.default) return ok([]);
+        const defaultSql = buildColumnDefaultSql(column.default, column);
+        if (!defaultSql) return ok([]);
+        return ok([
+          new SetDefaultCall(schemaName, issue.table, issue.column, defaultSql, 'widening'),
+        ]);
+      }
+
+    case 'primary_key_mismatch':
+      if (!issue.table)
+        return notOk(issueConflict('indexIncompatible', 'Primary key issue has no table name'));
+      if (isMissing(issue)) {
+        const pk = ctx.toContract.storage.tables[issue.table]?.primaryKey;
+        if (!pk)
+          return notOk(
+            issueConflict('indexIncompatible', `No primary key in contract for "${issue.table}"`),
+          );
+        const constraintName = pk.name ?? `${issue.table}_pkey`;
+        return ok([new AddPrimaryKeyCall(schemaName, issue.table, constraintName, pk.columns)]);
+      }
+      return notOk(
+        issueConflict(
+          'indexIncompatible',
+          `Primary key on "${issue.table}" has different columns (expected: ${issue.expected}, actual: ${issue.actual})`,
+          { table: issue.table },
+        ),
+      );
+
+    case 'unique_constraint_mismatch':
+      if (!issue.table)
+        return notOk(
+          issueConflict('indexIncompatible', 'Unique constraint issue has no table name'),
+        );
+      if (isMissing(issue) && issue.expected) {
+        const columns = issue.expected.split(', ');
+        const constraintName = `${issue.table}_${columns.join('_')}_key`;
+        return ok([new AddUniqueCall(schemaName, issue.table, constraintName, columns)]);
+      }
+      return notOk(
+        issueConflict(
+          'indexIncompatible',
+          `Unique constraint on "${issue.table}" differs (expected: ${issue.expected}, actual: ${issue.actual})`,
+          { table: issue.table },
+        ),
+      );
+
+    case 'index_mismatch':
+      if (!issue.table)
+        return notOk(issueConflict('indexIncompatible', 'Index issue has no table name'));
+      if (isMissing(issue) && issue.expected) {
+        const columns = issue.expected.split(', ');
+        const indexName = `${issue.table}_${columns.join('_')}_idx`;
+        return ok([new CreateIndexCall(schemaName, issue.table, indexName, columns)]);
+      }
+      return notOk(
+        issueConflict(
+          'indexIncompatible',
+          `Index on "${issue.table}" differs (expected: ${issue.expected}, actual: ${issue.actual})`,
+          { table: issue.table },
+        ),
+      );
+
+    case 'foreign_key_mismatch':
+      if (!issue.table)
+        return notOk(issueConflict('foreignKeyConflict', 'Foreign key issue has no table name'));
+      if (isMissing(issue) && issue.expected) {
+        const arrowIdx = issue.expected.indexOf(' -> ');
+        if (arrowIdx >= 0) {
+          const columns = issue.expected.slice(0, arrowIdx).split(', ');
+          const fkName = `${issue.table}_${columns.join('_')}_fkey`;
+          const fk = ctx.toContract.storage.tables[issue.table]?.foreignKeys.find(
+            (k) => k.columns.join(', ') === columns.join(', '),
+          );
+          if (fk) {
+            const fkSpec: ForeignKeySpec = {
+              name: fkName,
+              columns: fk.columns,
+              references: { table: fk.references.table, columns: fk.references.columns },
+              ...(fk.onDelete !== undefined && { onDelete: fk.onDelete }),
+              ...(fk.onUpdate !== undefined && { onUpdate: fk.onUpdate }),
+            };
+            return ok([new AddForeignKeyCall(schemaName, issue.table, fkSpec)]);
+          }
+          return notOk(
+            issueConflict(
+              'foreignKeyConflict',
+              `Foreign key on "${issue.table}" (${columns.join(', ')}) not found in destination contract`,
+              { table: issue.table },
+            ),
+          );
+        }
+      }
+      return notOk(
+        issueConflict(
+          'foreignKeyConflict',
+          `Foreign key on "${issue.table}" differs (expected: ${issue.expected}, actual: ${issue.actual})`,
+          { table: issue.table },
+        ),
+      );
+
+    case 'type_missing': {
+      if (!issue.typeName)
+        return notOk(issueConflict('unsupportedOperation', 'Type missing issue has no typeName'));
+      const typeInstance = ctx.toContract.storage.types?.[issue.typeName];
+      if (!typeInstance) {
+        return notOk(
+          issueConflict(
+            'unsupportedOperation',
+            `Type "${issue.typeName}" reported missing but not found in destination contract`,
+          ),
+        );
+      }
+      if (typeInstance.codecId.startsWith('pg/enum')) {
+        const values = (typeInstance.typeParams['values'] ?? []) as readonly string[];
+        return ok([new CreateEnumTypeCall(schemaName, typeInstance.nativeType, values)]);
+      }
+      return notOk(
+        issueConflict(
+          'unsupportedOperation',
+          `Type "${issue.typeName}" uses codec "${typeInstance.codecId}" — only enum types are supported`,
+        ),
+      );
+    }
+
+    case 'type_values_mismatch':
+      return notOk(
+        issueConflict(
+          'unsupportedOperation',
+          `Type "${issue.typeName ?? 'unknown'}" values differ — type alteration not yet supported`,
+        ),
+      );
+
+    case 'dependency_missing':
+      if (!issue.dependencyId)
+        return notOk(
+          issueConflict('unsupportedOperation', 'Dependency missing issue has no dependencyId'),
+        );
+      if (issue.dependencyId.startsWith('ext:')) {
+        return ok([new CreateExtensionCall(issue.dependencyId.slice(4))]);
+      }
+      if (issue.dependencyId.startsWith('schema:')) {
+        return ok([new CreateSchemaCall(issue.dependencyId.slice(7))]);
+      }
+      return notOk(
+        issueConflict('unsupportedOperation', `Unknown dependency type: ${issue.dependencyId}`),
+      );
+
+    default:
+      return notOk(
+        issueConflict(
+          'unsupportedOperation',
+          `Unhandled issue kind: ${(issue as SchemaIssue).kind}`,
+        ),
+      );
+  }
+}
+
+/**
+ * Classifies calls into dependency order categories for correct DDL sequencing.
+ */
+type CallCategory =
+  | 'dep'
+  | 'drop'
+  | 'table'
+  | 'column'
+  | 'alter'
+  | 'primaryKey'
+  | 'unique'
+  | 'index'
+  | 'foreignKey';
+
+/**
+ * Classifies calls into DDL sequencing buckets. The order matches the
+ * legacy walk-schema planner's emission order so `db init` and `db update`
+ * produce byte-identical plans for the shared shape (deps → drops → tables
+ * → columns → alters → PKs → uniques → indexes → FKs).
+ */
+function classifyCall(call: PostgresOpFactoryCall): CallCategory {
+  switch (call.factoryName) {
+    case 'createExtension':
+    case 'createSchema':
+    case 'createEnumType':
+    case 'addEnumValues':
+    case 'dropEnumType':
+    case 'renameType':
+      return 'dep';
+    case 'dropTable':
+    case 'dropColumn':
+    case 'dropConstraint':
+    case 'dropIndex':
+    case 'dropDefault':
+      return 'drop';
+    case 'createTable':
+      return 'table';
+    case 'addColumn':
+      return 'column';
+    case 'alterColumnType':
+    case 'setNotNull':
+    case 'dropNotNull':
+    case 'setDefault':
+      return 'alter';
+    case 'addPrimaryKey':
+      return 'primaryKey';
+    case 'addUnique':
+      return 'unique';
+    case 'createIndex':
+      return 'index';
+    case 'addForeignKey':
+      return 'foreignKey';
+    case 'rawSql': {
+      // Install ops (`dependencyInstallCallStrategy`) and type ops
+      // (`storageTypePlanCallStrategy`) both lift raw `SqlMigrationPlanOperation`s
+      // through `RawSqlCall` to preserve the component-declared label and
+      // precheck/postcheck. Classification falls back to inspecting the
+      // underlying op's target details (`objectType: 'type'`) and id prefix
+      // (`extension.*` / `schema.*`).
+      const op = (
+        call as {
+          op?: {
+            id?: string;
+            target?: { details?: { objectType?: string } };
+          };
+        }
+      ).op;
+      const objectType = op?.target?.details?.objectType;
+      if (objectType === 'type') return 'dep';
+      const id = typeof op?.id === 'string' ? op.id : '';
+      if (id.startsWith('extension.') || id.startsWith('schema.')) return 'dep';
+      return 'alter';
+    }
+    default:
+      return 'alter';
+  }
+}
+
+/** Stable lexical key used to order issues within the same kind bucket. */
+function issueKey(issue: SchemaIssue): string {
+  const table = 'table' in issue && typeof issue.table === 'string' ? issue.table : '';
+  const column = 'column' in issue && typeof issue.column === 'string' ? issue.column : '';
+  const name =
+    'indexOrConstraint' in issue && typeof issue.indexOrConstraint === 'string'
+      ? issue.indexOrConstraint
+      : '';
+  return `${table}\u0000${column}\u0000${name}`;
+}
+
+// When no policy is explicitly supplied (test-only path; production callers
+// always pass one), allow every class so strategies that gate on
+// `'data'` (data-safe placeholders) still fire — the test is treated as
+// trusted. Filtering of actual emitted calls only runs when a policy was
+// explicitly provided (see `policyProvided` below).
+const DEFAULT_POLICY: MigrationOperationPolicy = {
+  allowedOperationClasses: ['additive', 'widening', 'destructive', 'data'],
+};
+
+function emptySchemaIR(): SqlSchemaIR {
+  return { tables: {}, dependencies: [] };
+}
+
+function conflictKindForCall(call: PostgresOpFactoryCall): SqlPlannerConflict['kind'] {
+  switch (call.factoryName) {
+    case 'alterColumnType':
+      return 'typeMismatch';
+    case 'setNotNull':
+    case 'dropNotNull':
+      return 'nullabilityConflict';
+    case 'addForeignKey':
+    case 'dropConstraint':
+      return 'foreignKeyConflict';
+    case 'createIndex':
+    case 'dropIndex':
+      return 'indexIncompatible';
+    default:
+      return 'missingButNonAdditive';
+  }
+}
+
+function locationForCall(call: PostgresOpFactoryCall): SqlPlannerConflict['location'] | undefined {
+  // Most Postgres call classes expose `tableName`/`columnName`/`indexName`/
+  // `constraintName` as readonly fields. We avoid `toOp()` here because a
+  // `DataTransformCall` intentionally throws from `toOp`.
+  const anyCall = call as unknown as {
+    tableName?: string;
+    columnName?: string;
+    indexName?: string;
+    constraintName?: string;
+    typeName?: string;
+  };
+  const location: {
+    table?: string;
+    column?: string;
+    index?: string;
+    constraint?: string;
+    type?: string;
+  } = {};
+  if (anyCall.tableName) location.table = anyCall.tableName;
+  if (anyCall.columnName) location.column = anyCall.columnName;
+  if (anyCall.indexName) location.index = anyCall.indexName;
+  if (anyCall.constraintName) location.constraint = anyCall.constraintName;
+  if (anyCall.typeName) location.type = anyCall.typeName;
+  return Object.keys(location).length > 0 ? (location as SqlPlannerConflictLocation) : undefined;
+}
+
+function conflictForDisallowedCall(
+  call: PostgresOpFactoryCall,
+  allowed: readonly string[],
+): SqlPlannerConflict {
+  const summary = `Operation "${call.label}" requires class "${call.operationClass}", but policy allows only: ${allowed.join(', ')}`;
+  const location = locationForCall(call);
+  return {
+    kind: conflictKindForCall(call),
+    summary,
+    why: 'Use `migration new` to author a custom migration for this change.',
+    ...(location ? { location } : {}),
+  };
+}
+
+export function planIssues(
+  options: IssuePlannerOptions,
+): Result<IssuePlannerValue, readonly SqlPlannerConflict[]> {
+  // When no policy is supplied, `planIssues` treats the call as trusted (the
+  // caller — typically a test — has already vetted the issues). Only explicit
+  // policies gate operation classes into conflicts.
+  // `PostgresMigrationPlanner` always passes an explicit policy.
+  const policyProvided = options.policy !== undefined;
+  const policy = options.policy ?? DEFAULT_POLICY;
+  const schema = options.schema ?? emptySchemaIR();
+  const frameworkComponents = options.frameworkComponents ?? [];
+
+  const context: StrategyContext = {
+    toContract: options.toContract,
+    fromContract: options.fromContract,
+    schemaName: options.schemaName,
+    codecHooks: options.codecHooks,
+    storageTypes: options.storageTypes,
+    schema,
+    policy,
+    frameworkComponents,
+  };
+
+  const strategies = options.strategies ?? postgresPlannerStrategies;
+
+  let remaining = options.issues;
+  const recipeCalls: PostgresOpFactoryCall[] = [];
+  const bucketablePatternCalls: PostgresOpFactoryCall[] = [];
+
+  for (const strategy of strategies) {
+    const result = strategy(remaining, context);
+    if (result.kind === 'match') {
+      remaining = result.issues;
+      if (result.recipe) {
+        recipeCalls.push(...result.calls);
+      } else {
+        bucketablePatternCalls.push(...result.calls);
+      }
+    }
+  }
+
+  const sorted = [...remaining].sort((a, b) => {
+    const kindDelta = issueOrder(a) - issueOrder(b);
+    if (kindDelta !== 0) return kindDelta;
+    const keyA = issueKey(a);
+    const keyB = issueKey(b);
+    return keyA < keyB ? -1 : keyA > keyB ? 1 : 0;
+  });
+
+  const defaultCalls: PostgresOpFactoryCall[] = [];
+  const conflicts: SqlPlannerConflict[] = [];
+
+  for (const issue of sorted) {
+    const result = mapIssueToCall(issue, context);
+    if (result.ok) {
+      defaultCalls.push(...result.value);
+    } else {
+      conflicts.push(result.failure);
+    }
+  }
+
+  // Policy gating: drop calls whose operation class is not allowed and
+  // surface a conflict describing the disallowed op. Applies to both strategy
+  // output and default-mapped output. Only active when the caller explicitly
+  // supplied a policy — direct unit-test invocations (which pass no policy)
+  // stay as pass-through and keep destructive recipe steps intact.
+  const allowed = policy.allowedOperationClasses;
+  let gatedDefault = defaultCalls;
+  let gatedRecipe = recipeCalls;
+  let gatedBucketable = bucketablePatternCalls;
+  if (policyProvided) {
+    const keepIfAllowed = (bucket: PostgresOpFactoryCall[]) => (call: PostgresOpFactoryCall) => {
+      if (allowed.includes(call.operationClass)) {
+        bucket.push(call);
+        return;
+      }
+      conflicts.push(conflictForDisallowedCall(call, allowed));
+    };
+    const gatedDefaultBucket: PostgresOpFactoryCall[] = [];
+    const gatedRecipeBucket: PostgresOpFactoryCall[] = [];
+    const gatedBucketableBucket: PostgresOpFactoryCall[] = [];
+    defaultCalls.forEach(keepIfAllowed(gatedDefaultBucket));
+    recipeCalls.forEach(keepIfAllowed(gatedRecipeBucket));
+    bucketablePatternCalls.forEach(keepIfAllowed(gatedBucketableBucket));
+    gatedDefault = gatedDefaultBucket;
+    gatedRecipe = gatedRecipeBucket;
+    gatedBucketable = gatedBucketableBucket;
+  }
+
+  if (conflicts.length > 0) {
+    return notOk(conflicts);
+  }
+
+  // Recipe strategies (`enumChangeCallStrategy`, `notNullBackfillCallStrategy`,
+  // etc.) emit a cohesive sequence that must stay contiguous. They are
+  // inserted at a single pattern slot. Non-recipe pattern strategies
+  // (`dependencyInstallCallStrategy`, `storageTypePlanCallStrategy`,
+  // `notNullAddColumnCallStrategy`) produce individually classifiable calls
+  // that slot into DDL buckets alongside default-mapped calls.
+  const combinedBucketable = [...gatedDefault, ...gatedBucketable];
+  const byCategory = (cat: CallCategory) =>
+    combinedBucketable.filter((c) => classifyCall(c) === cat);
+
+  const calls: PostgresOpFactoryCall[] = [
+    ...byCategory('dep'),
+    ...byCategory('drop'),
+    ...byCategory('table'),
+    ...byCategory('column'),
+    ...gatedRecipe,
+    ...byCategory('alter'),
+    ...byCategory('primaryKey'),
+    ...byCategory('unique'),
+    ...byCategory('index'),
+    ...byCategory('foreignKey'),
+  ];
+
+  return ok({ calls });
+}