@prisma-next/target-postgres 0.11.0-dev.9 → 0.12.0

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

@@ -37,7 +37,11 @@ import {
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
 import { PostgresEnumType } from '../postgres-enum-type';
 import { isPostgresSchema } from '../postgres-schema';
-import { determineEnumDiff, readExistingEnumValues } from './enum-planning';
+import {
+  determineEnumDiff,
+  readExistingEnumValues,
+  resolveDdlSchemaForNamespaceStorage,
+} from './enum-planning';
 import {
   AddColumnCall,
   AddEnumValuesCall,
@@ -108,12 +112,12 @@ export function resolveNamespaceIdForIssue(issue: { readonly namespaceId?: strin
 /**
  * Resolve the DDL schema name for a namespace coordinate. Postgres-aware
  * namespaces dispatch to their polymorphic `ddlSchemaName` override —
- * named schemas return their own id and the unbound singleton projects
- * to `'public'` (sibling-present) or the framework sentinel
- * (sibling-absent). Legacy single-namespace contracts whose `__unbound__`
- * slot is the framework-default `SqlUnboundNamespace` (rather than the
- * Postgres-aware `PostgresUnboundSchema`) flow the coordinate through
- * unchanged so downstream `qualifyTableName` resolves polymorphically.
+ * named schemas return their own id; the unbound singleton returns
+ * `UNBOUND_NAMESPACE_ID`. Legacy single-namespace contracts whose
+ * `__unbound__` slot is the framework-default `SqlUnboundNamespace`
+ * (rather than the Postgres-aware `PostgresUnboundSchema`) flow the
+ * coordinate through unchanged so downstream `qualifyTableName`
+ * resolves polymorphically.
  */
 export function resolveDdlSchemaForNamespace(ctx: StrategyContext, namespaceId: string): string {
   const namespace = ctx.toContract.storage.namespaces[namespaceId];
@@ -123,21 +127,57 @@ export function resolveDdlSchemaForNamespace(ctx: StrategyContext, namespaceId:
   return namespaceId;
 }
 
+/** Default Postgres enum landing namespace — where contract-level (`types:`)
+ * enums are placed by the authoring builder when no explicit namespace is
+ * given. Mirrors `POSTGRES_ENUM_NAMESPACE_ID` in the contract-ts builder. */
+const DEFAULT_ENUM_NAMESPACE_ID = 'public';
+
+function namespaceHasEnum(storage: SqlStorage, namespaceId: string, typeName: string): boolean {
+  const ns = storage.namespaces[namespaceId];
+  if (!ns || !('enum' in ns) || ns.enum == null) return false;
+  return (ns.enum as Record<string, PostgresEnumStorageEntry>)[typeName] !== undefined;
+}
+
 /**
- * Finds a type entry by name across all namespace type registries.
- * Namespace types (e.g. Postgres enums) live under
- * `storage.namespaces[nsId].enum`, not under `storage.types`.
+ * Resolves which namespace's enum a column's bare `typeRef` binds to.
+ *
+ * Columns carry a bare (non-namespace-qualified) `typeRef`; the enum it names
+ * may live in a different namespace than the column's own (the authoring
+ * builder places contract-level `types:` enums in the default `public`
+ * namespace while a model's table may sit in the unbound namespace). The
+ * binding rule: an enum declared in the column's *own* namespace shadows
+ * everything; otherwise the column references the ambient enum — the sole
+ * namespace that defines `typeName`, preferring the default `public`
+ * namespace when several do. Returns `undefined` when no namespace defines it.
+ */
+function resolveColumnEnumNamespace(
+  storage: SqlStorage,
+  columnNamespaceId: string,
+  typeName: string,
+): string | undefined {
+  if (namespaceHasEnum(storage, columnNamespaceId, typeName)) return columnNamespaceId;
+  const owners = Object.keys(storage.namespaces).filter((nsId) =>
+    namespaceHasEnum(storage, nsId, typeName),
+  );
+  if (owners.length === 1) return owners[0];
+  if (owners.includes(DEFAULT_ENUM_NAMESPACE_ID)) return DEFAULT_ENUM_NAMESPACE_ID;
+  return owners[0];
+}
+
+/**
+ * Finds a type entry by explicit namespace coordinate. Namespace types (e.g.
+ * Postgres enums) live under `storage.namespaces[nsId].enum`. Returns the
+ * entry from the named namespace only — never scans other namespaces, so two
+ * namespaces that hold an enum with the same name resolve independently.
  */
 function locateNamespaceType(
   storage: SqlStorage,
+  namespaceId: string,
   typeName: string,
 ): PostgresEnumStorageEntry | undefined {
-  for (const ns of Object.values(storage.namespaces)) {
-    if (!('enum' in ns) || ns.enum == null) continue;
-    const entry = (ns.enum as Record<string, PostgresEnumStorageEntry>)[typeName];
-    if (entry !== undefined) return entry;
-  }
-  return undefined;
+  const ns = storage.namespaces[namespaceId];
+  if (!ns || !('enum' in ns) || ns.enum == null) return undefined;
+  return (ns.enum as Record<string, PostgresEnumStorageEntry>)[typeName];
 }
 
 // ============================================================================
@@ -369,10 +409,11 @@ export const nullableTighteningCallStrategy: CallMigrationStrategy = (issues, ct
 };
 
 function enumRebuildCallRecipe(
+  namespaceId: string,
   typeName: string,
   ctx: StrategyContext,
 ): readonly PostgresOpFactoryCall[] {
-  const toType = locateNamespaceType(ctx.toContract.storage, typeName);
+  const toType = locateNamespaceType(ctx.toContract.storage, namespaceId, typeName);
   if (!toType) return [];
   const isEnum = isPostgresEnumStorageEntry(toType);
   const nativeType = toType.nativeType;
@@ -380,13 +421,28 @@ function enumRebuildCallRecipe(
     ? toType.values
     : (((toType as StorageTypeInstance).typeParams['values'] ?? []) as readonly string[]);
   const tempName = `${nativeType}${REBUILD_SUFFIX}`;
+  // Type DDL targets the enum's real schema — the unbound coordinate resolves
+  // to the introspected `current_schema()`, never the `__unbound__` sentinel.
+  const ddlSchema = resolveDdlSchemaForNamespaceStorage(
+    ctx.toContract.storage,
+    namespaceId,
+    ctx.schema,
+  );
 
+  // Migrate every column whose `typeRef` binds to *this* enum. The column's
+  // bare `typeRef` resolves to an enum namespace (own-namespace shadows;
+  // otherwise the ambient/default `public` enum), so a column in the unbound
+  // namespace correctly binds to a `public`-namespace enum, while two
+  // same-named enums in distinct namespaces keep their columns disjoint.
   const columnRefs: { namespaceId: string; table: string; column: string }[] = [];
   for (const [nsId, ns] of Object.entries(ctx.toContract.storage.namespaces)) {
     for (const [tableName, tableNode] of Object.entries(ns.tables)) {
       const table = tableNode as StorageTable;
       for (const [columnName, column] of Object.entries(table.columns)) {
-        if (column.typeRef === typeName) {
+        if (
+          column.typeRef === typeName &&
+          resolveColumnEnumNamespace(ctx.toContract.storage, nsId, typeName) === namespaceId
+        ) {
           columnRefs.push({ namespaceId: nsId, table: tableName, column: columnName });
         }
       }
@@ -394,7 +450,7 @@ function enumRebuildCallRecipe(
   }
 
   return [
-    new CreateEnumTypeCall(ctx.schemaName, tempName, desiredValues),
+    new CreateEnumTypeCall(ddlSchema, tempName, desiredValues),
     ...columnRefs.map((ref) => {
       const using = `${ref.column}::text::${tempName}`;
       return new AlterColumnTypeCall(
@@ -409,8 +465,8 @@ function enumRebuildCallRecipe(
         },
       );
     }),
-    new DropEnumTypeCall(ctx.schemaName, nativeType),
-    new RenameTypeCall(ctx.schemaName, tempName, nativeType),
+    new DropEnumTypeCall(ddlSchema, nativeType),
+    new RenameTypeCall(ddlSchema, tempName, nativeType),
   ];
 }
 
@@ -450,6 +506,18 @@ function enumRebuildCallRecipe(
  * into the `dep` bucket — i.e. `CREATE TYPE` runs before any
  * `CreateTableCall` that references the new enum.
  */
+/**
+ * Separator character for compound enum map keys (`namespaceId\u0000typeName`).
+ * NUL (`\u0000`) is invalid in both Postgres identifiers and TypeScript symbol
+ * names so it cannot appear in either component — unambiguous separator.
+ */
+const COMPOUND_KEY_SEP = '\u0000';
+
+/** Builds the compound map key for a namespace-qualified enum entry. */
+function enumCompoundKey(namespaceId: string, typeName: string): string {
+  return `${namespaceId}${COMPOUND_KEY_SEP}${typeName}`;
+}
+
 export const nativeEnumPlanCallStrategy: CallMigrationStrategy = (issues, ctx) => {
   const enumTypes = collectPostgresEnumTypes(ctx.toContract.storage);
   if (enumTypes.size === 0) return { kind: 'no_match' };
@@ -457,28 +525,42 @@ export const nativeEnumPlanCallStrategy: CallMigrationStrategy = (issues, ctx) =
   const dataAllowed = ctx.policy.allowedOperationClasses.includes('data');
 
   const calls: PostgresOpFactoryCall[] = [];
-  const handledTypeNames = new Set<string>();
-  const introducedTypeNames = new Set<string>();
-  const rebuiltTypeNames = new Set<string>();
+  const handledKeys = new Set<string>();
+  const introducedKeys = new Set<string>();
+  const rebuiltKeys = new Set<string>();
   let emittedRebuildRecipe = false;
 
-  for (const [typeName, enumType] of enumTypes) {
+  for (const [key, enumType] of enumTypes) {
+    const sepIdx = key.indexOf(COMPOUND_KEY_SEP);
+    const enumNamespaceId = key.slice(0, sepIdx);
+    const typeName = key.slice(sepIdx + 1);
+
     const desired = enumType.values;
-    const existing = readExistingEnumValues(ctx.schema, enumType.nativeType);
+    // The enum's live schema: for the unbound coordinate this resolves to the
+    // introspected `current_schema()` (e.g. `public`), never the `__unbound__`
+    // DDL-emit sentinel — so both the existing-values lookup key and the
+    // emitted `CREATE TYPE` / `ALTER TYPE` target the real schema the type
+    // lives in. Named namespaces resolve to their own DDL schema.
+    const ddlSchema = resolveDdlSchemaForNamespaceStorage(
+      ctx.toContract.storage,
+      enumNamespaceId,
+      ctx.schema,
+    );
+    const existing = readExistingEnumValues(ctx.schema, ddlSchema, enumType.nativeType);
     if (!existing) {
-      calls.push(new CreateEnumTypeCall(ctx.schemaName, typeName, desired, enumType.nativeType));
-      handledTypeNames.add(typeName);
-      introducedTypeNames.add(typeName);
+      calls.push(new CreateEnumTypeCall(ddlSchema, typeName, desired, enumType.nativeType));
+      handledKeys.add(key);
+      introducedKeys.add(key);
       continue;
     }
     const diff = determineEnumDiff(existing, desired);
     if (diff.kind === 'unchanged') {
-      handledTypeNames.add(typeName);
+      handledKeys.add(key);
       continue;
     }
     if (diff.kind === 'add_values') {
-      calls.push(new AddEnumValuesCall(ctx.schemaName, typeName, enumType.nativeType, diff.values));
-      handledTypeNames.add(typeName);
+      calls.push(new AddEnumValuesCall(ddlSchema, typeName, enumType.nativeType, diff.values));
+      handledKeys.add(key);
       continue;
     }
     if (dataAllowed && diff.removedValues.length > 0) {
@@ -490,10 +572,10 @@ export const nativeEnumPlanCallStrategy: CallMigrationStrategy = (issues, ctx) =
         ),
       );
     }
-    calls.push(...enumRebuildCallRecipe(typeName, ctx));
+    calls.push(...enumRebuildCallRecipe(enumNamespaceId, typeName, ctx));
     emittedRebuildRecipe = true;
-    handledTypeNames.add(typeName);
-    rebuiltTypeNames.add(typeName);
+    handledKeys.add(key);
+    rebuiltKeys.add(key);
   }
 
   // The strategy emits a single `recipe` flag for the entire pass,
@@ -505,9 +587,17 @@ export const nativeEnumPlanCallStrategy: CallMigrationStrategy = (issues, ctx) =
   // enum would fail at runtime with a confusing `type "X" does not
   // exist` error. Surface the unrepresentable case here as a
   // planner-time error so the failure mode is loud, not silent.
-  if (introducedTypeNames.size > 0 && rebuiltTypeNames.size > 0) {
+  if (introducedKeys.size > 0 && rebuiltKeys.size > 0) {
+    const introducedDisplay = [...introducedKeys]
+      .sort()
+      .map((k) => k.replace(COMPOUND_KEY_SEP, '.'))
+      .join(', ');
+    const rebuiltDisplay = [...rebuiltKeys]
+      .sort()
+      .map((k) => k.replace(COMPOUND_KEY_SEP, '.'))
+      .join(', ');
     throw new Error(
-      `nativeEnumPlanCallStrategy: cannot emit both a brand-new enum and a rebuild on a different enum in the same plan; the single recipe flag cannot route them to different buckets. Introduced: [${[...introducedTypeNames].sort().join(', ')}]; rebuilt: [${[...rebuiltTypeNames].sort().join(', ')}]. Split the strategy or grow the \`match\` return type before this case lands.`,
+      `nativeEnumPlanCallStrategy: cannot emit both a brand-new enum and a rebuild on a different enum in the same plan; the single recipe flag cannot route them to different buckets. Introduced: [${introducedDisplay}]; rebuilt: [${rebuiltDisplay}]. Split the strategy or grow the \`match\` return type before this case lands.`,
     );
   }
 
@@ -516,7 +606,7 @@ export const nativeEnumPlanCallStrategy: CallMigrationStrategy = (issues, ctx) =
       !(
         (issue.kind === 'type_missing' || issue.kind === 'enum_values_changed') &&
         issue.typeName &&
-        handledTypeNames.has(issue.typeName)
+        handledKeys.has(enumCompoundKey(resolveNamespaceIdForIssue(issue), issue.typeName))
       ),
   );
 
@@ -538,14 +628,22 @@ export const nativeEnumPlanCallStrategy: CallMigrationStrategy = (issues, ctx) =
   return { kind: 'match', issues: remaining, calls, recipe: emittedRebuildRecipe };
 };
 
+/**
+ * Collects every `PostgresEnumType` instance across all declared namespaces,
+ * returning a compound-keyed map (`${namespaceId}\u0000${typeName}`). Two
+ * namespaces that declare an enum with the same name produce two distinct
+ * entries — no name collision, no last-write-wins.
+ *
+ * Entries within each namespace are sorted by name for deterministic ordering.
+ */
 function collectPostgresEnumTypes(storage: SqlStorage): ReadonlyMap<string, PostgresEnumType> {
   const result = new Map<string, PostgresEnumType>();
-  for (const ns of Object.values(storage.namespaces)) {
+  for (const [nsId, ns] of Object.entries(storage.namespaces)) {
     if (!('enum' in ns) || ns.enum == null) continue;
     const nsEnums = ns.enum as Record<string, unknown>;
     for (const [name, instance] of Object.entries(nsEnums).sort(([a], [b]) => a.localeCompare(b))) {
       if (instance instanceof PostgresEnumType) {
-        result.set(name, instance);
+        result.set(enumCompoundKey(nsId, name), instance);
       }
     }
   }

package/src/core/migrations/planner.ts

@@ -17,9 +17,10 @@ import type {
   MigrationScaffoldContext,
   SchemaIssue,
 } from '@prisma-next/framework-components/control';
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import { parsePostgresDefault } from '../default-normalizer';
 import { normalizeSchemaNativeType } from '../native-type-normalizer';
-import { readExistingEnumValues } from './enum-planning';
+import { createResolveExistingEnumValues } from './enum-planning';
 import { planIssues } from './issue-planner';
 import { TypeScriptRenderablePostgresMigration } from './planner-produced-postgres-migration';
 import { postgresPlannerStrategies } from './planner-strategies';
@@ -39,21 +40,8 @@ type VerifySqlSchemaOptionsWithComponents = Parameters<typeof verifySqlSchema>[0
   readonly frameworkComponents: PlannerFrameworkComponents;
 };
 
-interface PlannerConfig {
-  readonly defaultSchema: string;
-}
-
-const DEFAULT_PLANNER_CONFIG: PlannerConfig = {
-  defaultSchema: 'public',
-};
-
-export function createPostgresMigrationPlanner(
-  config: Partial<PlannerConfig> = {},
-): PostgresMigrationPlanner {
-  return new PostgresMigrationPlanner({
-    ...DEFAULT_PLANNER_CONFIG,
-    ...config,
-  });
+export function createPostgresMigrationPlanner(): PostgresMigrationPlanner {
+  return new PostgresMigrationPlanner();
 }
 
 /**
@@ -84,8 +72,6 @@ export type PostgresPlanResult =
  * authoring surface.
  */
 export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgres'> {
-  constructor(private readonly config: PlannerConfig) {}
-
   plan(options: {
     readonly contract: unknown;
     readonly schema: unknown;
@@ -132,7 +118,10 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
   }
 
   private planSql(options: SqlMigrationPlannerPlanOptions): PostgresPlanResult {
-    const schemaName = options.schemaName ?? this.config.defaultSchema;
+    const schemaName =
+      options.schemaName ??
+      Object.keys(options.contract.storage.namespaces).find((id) => id !== UNBOUND_NAMESPACE_ID) ??
+      UNBOUND_NAMESPACE_ID;
     const policyResult = this.ensureAdditivePolicy(options.policy);
     if (policyResult) {
       return policyResult;
@@ -219,8 +208,7 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       frameworkComponents: options.frameworkComponents,
       normalizeDefault: parsePostgresDefault,
       normalizeNativeType: normalizeSchemaNativeType,
-      resolveExistingEnumValues: (schema, enumType) =>
-        readExistingEnumValues(schema, enumType.nativeType),
+      resolveExistingEnumValues: createResolveExistingEnumValues(options.contract.storage),
     };
     const verifyResult = verifySqlSchema(verifyOptions);
     // Schema presence is a Postgres-specific concern (no equivalent in

package/src/core/migrations/render-typescript.ts

@@ -11,12 +11,11 @@
 
 import type { OpFactoryCall } from '@prisma-next/framework-components/control';
 import { detectScaffoldRuntime, shebangLineFor } from '@prisma-next/migration-tools/migration-ts';
-import { type ImportRequirement, jsonToTsSource, renderImports } from '@prisma-next/ts-render';
+import { type ImportRequirement, renderImports } from '@prisma-next/ts-render';
 
 export interface RenderMigrationMeta {
   readonly from: string | null;
   readonly to: string;
-  readonly labels?: readonly string[];
 }
 
 /**
@@ -83,9 +82,6 @@ function buildDescribeMethod(meta: RenderMigrationMeta): string {
   lines.push('    return {');
   lines.push(`      from: ${JSON.stringify(meta.from)},`);
   lines.push(`      to: ${JSON.stringify(meta.to)},`);
-  if (meta.labels && meta.labels.length > 0) {
-    lines.push(`      labels: ${jsonToTsSource(meta.labels)},`);
-  }
   lines.push('    };');
   lines.push('  }');
   lines.push('');

package/src/core/migrations/runner.ts

@@ -1,7 +1,6 @@
 import type { ContractMarkerRecord } from '@prisma-next/contract/types';
 import type {
   MigrationOperationPolicy,
-  MultiSpaceRunnerResult,
   SqlControlFamilyInstance,
   SqlMigrationPlanContractInfo,
   SqlMigrationPlanOperation,
@@ -14,15 +13,19 @@ import type {
 } from '@prisma-next/family-sql/control';
 import { runnerFailure, runnerSuccess } from '@prisma-next/family-sql/control';
 import { verifySqlSchema } from '@prisma-next/family-sql/schema-verify';
-import type { ControlDriverInstance } from '@prisma-next/framework-components/control';
+import type {
+  ControlDriverInstance,
+  MigrationRunnerResult,
+} from '@prisma-next/framework-components/control';
 import { APP_SPACE_ID } from '@prisma-next/framework-components/control';
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import { SqlQueryError } from '@prisma-next/sql-errors';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { Result } from '@prisma-next/utils/result';
 import { notOk, ok, okVoid } from '@prisma-next/utils/result';
 import { parsePostgresDefault } from '../default-normalizer';
 import { normalizeSchemaNativeType } from '../native-type-normalizer';
-import { readExistingEnumValues } from './enum-planning';
+import { createResolveExistingEnumValues } from './enum-planning';
 import type { PostgresPlanTargetDetails } from './planner-target-details';
 import {
   buildLedgerInsertStatement,
@@ -33,19 +36,11 @@ import {
   type SqlStatement,
 } from './statement-builders';
 
-interface RunnerConfig {
-  readonly defaultSchema: string;
-}
-
 interface ApplyPlanSuccessValue {
   readonly operationsExecuted: number;
   readonly executedOperations: readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[];
 }
 
-const DEFAULT_CONFIG: RunnerConfig = {
-  defaultSchema: 'public',
-};
-
 const LOCK_DOMAIN = 'prisma_next.contract.marker';
 
 /**
@@ -58,13 +53,10 @@ function cloneAndFreezeRecord<T extends Record<string, unknown>>(value: T): T {
     if (val === null || val === undefined) {
       cloned[key] = val;
     } else if (Array.isArray(val)) {
-      // Clone array (shallow clone of array elements)
       cloned[key] = Object.freeze([...val]);
     } else if (typeof val === 'object') {
-      // Recursively clone nested objects
       cloned[key] = cloneAndFreezeRecord(val as Record<string, unknown>);
     } else {
-      // Primitives are copied as-is
       cloned[key] = val;
     }
   }
@@ -73,61 +65,27 @@ function cloneAndFreezeRecord<T extends Record<string, unknown>>(value: T): T {
 
 export function createPostgresMigrationRunner(
   family: SqlControlFamilyInstance,
-  config: Partial<RunnerConfig> = {},
 ): SqlMigrationRunner<PostgresPlanTargetDetails> {
-  return new PostgresMigrationRunner(family, { ...DEFAULT_CONFIG, ...config });
+  return new PostgresMigrationRunner(family);
 }
 
 class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDetails> {
-  constructor(
-    private readonly family: SqlControlFamilyInstance,
-    private readonly config: RunnerConfig,
-  ) {}
-
-  async execute(
-    options: SqlMigrationRunnerExecuteOptions<PostgresPlanTargetDetails>,
-  ): Promise<SqlMigrationRunnerResult> {
-    const driver = options.driver;
-
-    // Static checks fail fast before any transaction work — no point
-    // burning a BEGIN/ROLLBACK round-trip on a destination-contract
-    // mismatch the caller can fix locally.
-    const destinationCheck = this.ensurePlanMatchesDestinationContract(
-      options.plan.destination,
-      options.destinationContract,
-    );
-    if (!destinationCheck.ok) return destinationCheck;
-
-    const policyCheck = this.enforcePolicyCompatibility(options.policy, options.plan.operations);
-    if (!policyCheck.ok) return policyCheck;
-
-    await this.beginTransaction(driver);
-    let committed = false;
-    try {
-      const result = await this.executeOnConnection(options);
-      if (!result.ok) {
-        return result;
-      }
-      await this.commitTransaction(driver);
-      committed = true;
-      return result;
-    } finally {
-      if (!committed) {
-        await this.rollbackTransaction(driver);
-      }
-    }
-  }
+  constructor(private readonly family: SqlControlFamilyInstance) {}
 
   /**
    * Body of the migration runner without transaction management. The
-   * caller (single-space `execute(...)` above, or the multi-space
-   * outer-tx orchestrator at the SQL family level) owns the
+   * caller ({@link PostgresMigrationRunner.execute}) owns the
    * `BEGIN`/`COMMIT`/`ROLLBACK` lifecycle.
    */
   async executeOnConnection(
     options: SqlMigrationRunnerExecuteOptions<PostgresPlanTargetDetails>,
   ): Promise<SqlMigrationRunnerResult> {
-    const schema = options.schemaName ?? this.config.defaultSchema;
+    const schema =
+      options.schemaName ??
+      Object.keys(options.destinationContract.storage.namespaces).find(
+        (id) => id !== UNBOUND_NAMESPACE_ID,
+      ) ??
+      UNBOUND_NAMESPACE_ID;
     const driver = options.driver;
     if (options.space !== undefined && options.space !== options.plan.spaceId) {
       throw new Error(
@@ -188,8 +146,9 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
         frameworkComponents: options.frameworkComponents,
         normalizeDefault: parsePostgresDefault,
         normalizeNativeType: normalizeSchemaNativeType,
-        resolveExistingEnumValues: (schema, enumType) =>
-          readExistingEnumValues(schema, enumType.nativeType),
+        resolveExistingEnumValues: createResolveExistingEnumValues(
+          options.destinationContract.storage,
+        ),
       });
       if (!schemaVerifyResult.ok) {
         return runnerFailure('SCHEMA_VERIFY_FAILED', schemaVerifyResult.summary, {
@@ -216,12 +175,12 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
     });
   }
 
-  async executeAcrossSpaces(options: {
+  async execute(options: {
     readonly driver: ControlDriverInstance<'sql', string>;
     readonly perSpaceOptions: ReadonlyArray<
       SqlMigrationRunnerExecuteOptions<PostgresPlanTargetDetails>
     >;
-  }): Promise<MultiSpaceRunnerResult> {
+  }): Promise<MigrationRunnerResult> {
     const driver = options.driver;
     const perSpaceOptions = options.perSpaceOptions;
 

package/src/core/migrations/statement-builders.ts

@@ -56,7 +56,7 @@ export interface MergeMarkerInput {
    * Logical space identifier for this marker row. Required at every
    * call site so the type system surfaces every place that needs to
    * thread the value (rather than letting an `?? APP_SPACE_ID`
-   * fall-through silently collapse multi-space markers onto the
+   * fall-through silently collapse per-space markers onto the
    * `'app'` row). App-plan callers pass {@link APP_SPACE_ID}
    * (`'app'`); per-extension callers (planner / runner / verifier
    * extensions over contract spaces) pass the extension's space id.

package/src/core/migrations/verify-postgres-namespaces.ts

@@ -52,12 +52,12 @@ function existingSchemasFromSchema(schema: SqlSchemaIR): readonly string[] {
  *
  * A namespace's live container is the schema returned by its
  * polymorphic `ddlSchemaName(storage)` method — named schemas resolve
- * to their own id, the unbound singleton projects to `public` (sibling
- * present) or the framework sentinel (sibling absent). Issues are
- * emitted only when the resolved name is a real, creatable schema
- * (not the unbound sentinel) and is missing from the introspected
- * list. `public` is suppressed implicitly because the introspection
- * (or its sensible default) always carries it.
+ * to their own id; the unbound singleton returns `UNBOUND_NAMESPACE_ID`
+ * and is skipped explicitly (late-bound namespaces have no fixed DDL
+ * schema). Issues are emitted only when the resolved name is a real,
+ * creatable schema (not the unbound sentinel) and is missing from the
+ * introspected list. `public` is suppressed implicitly because the
+ * introspection (or its sensible default) always carries it.
  *
  * Each emitted issue stamps `namespaceId` with the contract namespace
  * coordinate so the downstream `mapIssueToCall` re-resolves the DDL

package/src/core/postgres-contract-serializer.ts

@@ -117,10 +117,10 @@ export class PostgresContractSerializer extends SqlContractSerializerBase<Contra
       if (isPostgresSchema(ns)) {
         namespacesJson[nsId] = this.serializePostgresNamespace(ns, ns.id === UNBOUND_NAMESPACE_ID);
       } else {
-        // Family-level SqlNamespacePayload / SqlUnboundNamespace haven't
-        // been promoted to a PostgresSchema instance yet (e.g. they came
-        // straight from the TS builder, which uses the family-shared
-        // SqlStorage constructor). Serialise them as postgres-schema /
+        // Family-level SqlUnboundNamespace or other family-built SQL
+        // namespaces haven't been promoted to a PostgresSchema instance
+        // yet (e.g. they came straight from the TS builder before a target
+        // `createNamespace` factory ran). Serialise them as postgres-schema /
         // postgres-unbound-schema so the round-trip through
         // deserializeContract hydrates them back into PostgresSchema
         // instances.

package/src/core/postgres-schema.ts

@@ -120,10 +120,11 @@ export class PostgresSchema extends NamespaceBase {
    * statements that need to identify this namespace in the live
    * database (e.g. `CREATE TABLE "<ddlSchemaName>"."<table>" …`,
    * catalog filters, planner conflict lookups). Named schemas resolve
-   * to their own id; the unbound singleton overrides this to project
-   * to `'public'` when a sibling public namespace exists in the same
-   * contract — and falls back to the framework sentinel otherwise so
-   * the planner can detect the missing-projection case explicitly.
+   * to their own id. The `PostgresUnboundSchema` singleton inherits
+   * this and returns `UNBOUND_NAMESPACE_ID` — callers that dispatch
+   * through `qualifyTableName` / `toRegclassLiteral` route through the
+   * polymorphic `PostgresUnboundSchema` overrides and produce
+   * unqualified (search-path-resolved) output automatically.
    */
   ddlSchemaName(_storage: SqlStorage): string {
     return this.id;
@@ -143,6 +144,11 @@ export class PostgresSchema extends NamespaceBase {
  * sentinel; Postgres decides what late-bound means here (the table
  * name, naked — the schema is supplied by the live connection's
  * `search_path`).
+ *
+ * `ddlSchemaName` is inherited from `PostgresSchema` and returns
+ * `UNBOUND_NAMESPACE_ID`. Downstream helpers (`qualifyTableName`,
+ * `toRegclassLiteral`) route through the polymorphic factory and
+ * produce unqualified output automatically.
  */
 export class PostgresUnboundSchema extends PostgresSchema {
   static readonly instance: PostgresUnboundSchema = new PostgresUnboundSchema();
@@ -162,22 +168,6 @@ export class PostgresUnboundSchema extends PostgresSchema {
   override schemaSqlExpression(): string {
     return 'current_schema()';
   }
-
-  /**
-   * The unbound slot has no schema name of its own, so DDL emission
-   * projects it onto a sibling when one is available: if the contract
-   * carries a `public` namespace, the late-bound slot resolves to
-   * `'public'` (the default Postgres landing schema); otherwise it
-   * resolves to the framework sentinel `UNBOUND_NAMESPACE_ID` so the
-   * planner can recognise the unprojected case and route accordingly
-   * (e.g. emit a conflict instead of silently picking a schema).
-   */
-  override ddlSchemaName(storage: SqlStorage): string {
-    if (storage.namespaces['public'] !== undefined) {
-      return 'public';
-    }
-    return UNBOUND_NAMESPACE_ID;
-  }
 }
 
 PostgresSchema.unbound = PostgresUnboundSchema.instance;