@prisma-next/target-postgres 0.14.0-dev.6 → 0.14.0-dev.61

package/src/core/migrations/postgres-migration.ts

@@ -3,9 +3,11 @@ import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control'
 import type { SqlControlAdapter } from '@prisma-next/family-sql/control-adapter';
 import { Migration as SqlMigration } from '@prisma-next/family-sql/migration';
 import type { ControlStack } from '@prisma-next/framework-components/control';
+import { MigrationContractViews } from '@prisma-next/migration-tools/migration';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { DdlColumn, DdlTableConstraint } from '@prisma-next/sql-relational-core/ast';
 import { errorPostgresMigrationStackMissing } from '../errors';
+import { PostgresContractView } from '../postgres-contract-view';
 import {
   AddCheckConstraintCall,
   AddColumnCall,
@@ -60,20 +62,31 @@ import type { PostgresPlanTargetDetails } from './planner-target-details';
  * is an antipattern in a migration. (The unbound/unspecified namespace concept
  * remains for SQLite, which has no schemas, and for Mongo's connection `db`.)
  */
-export abstract class PostgresMigration extends SqlMigration<
-  PostgresPlanTargetDetails,
-  'postgres'
-> {
+export abstract class PostgresMigration<
+  Start extends Contract<SqlStorage> = Contract<SqlStorage>,
+  End extends Contract<SqlStorage> = Contract<SqlStorage>,
+> extends SqlMigration<PostgresPlanTargetDetails, 'postgres', Start, End> {
   readonly targetId = 'postgres' as const;
 
   /**
    * Materialized Postgres control adapter, created once per migration
    * instance from the injected stack. `undefined` only when the migration
-   * was instantiated without a stack (test fixtures); `dataTransform`
-   * throws in that case to surface the misuse.
+   * was instantiated without a stack (test fixtures); `controlAdapterFor`
+   * throws a PN-MIG-2007 in that case to surface the misuse.
    */
   protected readonly controlAdapter: SqlControlAdapter<'postgres'> | undefined;
 
+  #endView = new MigrationContractViews<PostgresContractView<End>>(
+    this,
+    'PostgresMigration',
+    (json) => PostgresContractView.fromJson<End>(json),
+  );
+  #startView = new MigrationContractViews<PostgresContractView<Start>>(
+    this,
+    'PostgresMigration',
+    (json) => PostgresContractView.fromJson<Start>(json),
+  );
+
   constructor(stack?: ControlStack<'sql', 'postgres'>) {
     super(stack);
     // The descriptor `create()` is typed as the wider `ControlAdapterInstance`;
@@ -84,6 +97,35 @@ export abstract class PostgresMigration extends SqlMigration<
       : undefined;
   }
 
+  /**
+   * Returns the materialized control adapter, or throws a PN-MIG-2007 naming
+   * `operation` when the migration was constructed without a `ControlStack`.
+   * Single home for the null-check that every DDL/DML method shares.
+   */
+  private controlAdapterFor(operation: string): SqlControlAdapter<'postgres'> {
+    if (!this.controlAdapter) {
+      throw errorPostgresMigrationStackMissing(operation);
+    }
+    return this.controlAdapter;
+  }
+
+  /**
+   * The typed, schema-qualified Postgres view over this migration's end-state
+   * contract — `this.endContract.namespace.<schema>.table.<name>`, etc. Throws
+   * if no `endContractJson` was provided.
+   */
+  get endContract(): PostgresContractView<End> {
+    return this.#endView.endContract;
+  }
+
+  /**
+   * The typed Postgres view over this migration's start-state contract, or
+   * `null` for a baseline migration (no `startContractJson`).
+   */
+  get startContract(): PostgresContractView<Start> | null {
+    return this.#startView.startContract;
+  }
+
   /**
    * Instance-method wrapper around the free `dataTransform` factory that
    * supplies the stored control adapter. Authors call this from inside
@@ -94,10 +136,7 @@ export abstract class PostgresMigration extends SqlMigration<
     name: string,
     options: DataTransformOptions,
   ): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
-    return dataTransform(contract, name, options, this.controlAdapter);
+    return dataTransform(contract, name, options, this.controlAdapterFor('dataTransform'));
   }
 
   /**
@@ -112,15 +151,12 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly columns: readonly DdlColumn[];
     readonly constraints?: readonly DdlTableConstraint[];
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new CreateTableCall(
       options.schema,
       options.table,
       options.columns,
       options.constraints,
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('createTable'));
   }
 
   /**
@@ -132,10 +168,7 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly schema: string;
     readonly ifNotExists?: boolean;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
-    return new CreateSchemaCall(options.schema).toOp(this.controlAdapter);
+    return new CreateSchemaCall(options.schema).toOp(this.controlAdapterFor('createSchema'));
   }
 
   protected addColumn(options: {
@@ -143,11 +176,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly column: DdlColumn;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new AddColumnCall(options.schema, options.table, options.column).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('addColumn'),
     );
   }
 
@@ -157,15 +187,12 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly constraint: string;
     readonly columns: readonly string[];
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new AddPrimaryKeyCall(
       options.schema,
       options.table,
       options.constraint,
       options.columns,
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('addPrimaryKey'));
   }
 
   protected addUnique(options: {
@@ -174,15 +201,12 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly constraint: string;
     readonly columns: readonly string[];
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new AddUniqueCall(
       options.schema,
       options.table,
       options.constraint,
       options.columns,
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('addUnique'));
   }
 
   protected addForeignKey(options: {
@@ -190,11 +214,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly foreignKey: ForeignKeySpec;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new AddForeignKeyCall(options.schema, options.table, options.foreignKey).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('addForeignKey'),
     );
   }
 
@@ -205,16 +226,13 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly column: string;
     readonly values: readonly string[];
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new AddCheckConstraintCall(
       options.schema,
       options.table,
       options.constraint,
       options.column,
       options.values,
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('addCheckConstraint'));
   }
 
   protected dropCheckConstraint(options: {
@@ -222,11 +240,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly constraint: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new DropCheckConstraintCall(options.schema, options.table, options.constraint).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('dropCheckConstraint'),
     );
   }
 
@@ -236,25 +251,21 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly constraint: string;
     readonly kind?: 'foreignKey' | 'unique' | 'primaryKey';
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new DropConstraintCall(
       options.schema,
       options.table,
       options.constraint,
       options.kind ?? 'unique',
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('dropConstraint'));
   }
 
   protected dropTable(options: {
     readonly schema: string;
     readonly table: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
-    return new DropTableCall(options.schema, options.table).toOp(this.controlAdapter);
+    return new DropTableCall(options.schema, options.table).toOp(
+      this.controlAdapterFor('dropTable'),
+    );
   }
 
   protected dropColumn(options: {
@@ -262,11 +273,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly column: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new DropColumnCall(options.schema, options.table, options.column).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('dropColumn'),
     );
   }
 
@@ -276,15 +284,12 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly column: string;
     readonly options: AlterColumnTypeOptions;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new AlterColumnTypeCall(
       options.schema,
       options.table,
       options.column,
       options.options,
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('alterColumnType'));
   }
 
   protected setNotNull(options: {
@@ -292,11 +297,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly column: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new SetNotNullCall(options.schema, options.table, options.column).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('setNotNull'),
     );
   }
 
@@ -305,11 +307,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly column: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new DropNotNullCall(options.schema, options.table, options.column).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('dropNotNull'),
     );
   }
 
@@ -320,16 +319,13 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly defaultSql: string;
     readonly operationClass?: 'additive' | 'widening';
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new SetDefaultCall(
       options.schema,
       options.table,
       options.column,
       options.defaultSql,
       options.operationClass,
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('setDefault'));
   }
 
   protected dropDefault(options: {
@@ -337,11 +333,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly column: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new DropDefaultCall(options.schema, options.table, options.column).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('dropDefault'),
     );
   }
 
@@ -352,16 +345,13 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly columns: readonly string[];
     readonly extras?: CreateIndexExtras;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new CreateIndexCall(
       options.schema,
       options.table,
       options.index,
       options.columns,
       options.extras,
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('createIndex'));
   }
 
   protected dropIndex(options: {
@@ -369,11 +359,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly index: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new DropIndexCall(options.schema, options.table, options.index).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('dropIndex'),
     );
   }
 
@@ -383,9 +370,6 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly id: string;
     readonly label?: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
-    return installExtension(options, this.controlAdapter);
+    return installExtension(options, this.controlAdapterFor('installExtension'));
   }
 }

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

@@ -45,15 +45,19 @@ export function renderCallsToTypeScript(
   calls: ReadonlyArray<OpFactoryCall>,
   meta: RenderMigrationMeta,
 ): string {
-  const imports = buildImports(calls);
+  const imports = buildImports(calls, meta);
   const operationsBody = calls.map((c) => renderCall(c)).join(',\n');
+  const hasStart = meta.from !== null;
+  const startField = hasStart ? ['  override readonly startContractJson = startContract;'] : [];
 
   return [
     shebangLineFor(detectScaffoldRuntime()),
     imports,
     '',
-    'export default class M extends Migration {',
-    buildDescribeMethod(meta),
+    `export default class M extends Migration<${hasStart ? 'Start' : 'never'}, End> {`,
+    ...startField,
+    '  override readonly endContractJson = endContract;',
+    '',
     '  override get operations() {',
     '    return [',
     indent(operationsBody, 6),
@@ -70,8 +74,8 @@ function renderCall(call: OpFactoryCall): string {
   return call.renderTypeScript();
 }
 
-function buildImports(calls: ReadonlyArray<OpFactoryCall>): string {
-  const requirements: ImportRequirement[] = [...BASE_IMPORTS];
+function buildImports(calls: ReadonlyArray<OpFactoryCall>, meta: RenderMigrationMeta): string {
+  const requirements: ImportRequirement[] = [...BASE_IMPORTS, ...contractImports(meta)];
   for (const call of calls) {
     for (const req of call.importRequirements()) {
       requirements.push(req);
@@ -80,16 +84,39 @@ function buildImports(calls: ReadonlyArray<OpFactoryCall>): string {
   return renderImports(requirements);
 }
 
-function buildDescribeMethod(meta: RenderMigrationMeta): string {
-  const lines: string[] = [];
-  lines.push('  override describe() {');
-  lines.push('    return {');
-  lines.push(`      from: ${JSON.stringify(meta.from)},`);
-  lines.push(`      to: ${JSON.stringify(meta.to)},`);
-  lines.push('    };');
-  lines.push('  }');
-  lines.push('');
-  return lines.join('\n');
+/**
+ * The committed contract-JSON imports the scaffold reads its from/to identity
+ * from. `end-contract.json` is always present; `start-contract.json` is added
+ * only for a non-baseline migration (`meta.from !== null`). The matching
+ * `Contract` type imports (aliased `Start`/`End`) feed the
+ * `Migration<Start, End>` generics. Baseline emits `Migration<never, End>` with
+ * no start imports — `never` is the honest "no prior contract" Start.
+ */
+function contractImports(meta: RenderMigrationMeta): readonly ImportRequirement[] {
+  const reqs: ImportRequirement[] = [
+    {
+      moduleSpecifier: './end-contract.json',
+      symbol: 'endContract',
+      kind: 'default',
+      attributes: { type: 'json' },
+    },
+    { moduleSpecifier: './end-contract', symbol: 'Contract', alias: 'End', typeOnly: true },
+  ];
+  if (meta.from !== null) {
+    reqs.push({
+      moduleSpecifier: './start-contract.json',
+      symbol: 'startContract',
+      kind: 'default',
+      attributes: { type: 'json' },
+    });
+    reqs.push({
+      moduleSpecifier: './start-contract',
+      symbol: 'Contract',
+      alias: 'Start',
+      typeOnly: true,
+    });
+  }
+  return reqs;
 }
 
 function indent(text: string, spaces: number): string {

package/src/core/migrations/resolve-ddl-schema.ts

@@ -0,0 +1,26 @@
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import { DEFAULT_NAMESPACE_ID } from '../namespace-ids';
+import { isPostgresSchema } from '../postgres-schema';
+
+/**
+ * Given the contract's storage and a namespace id, returns the live Postgres
+ * DDL schema name that namespace maps to. A named Postgres namespace dispatches
+ * to its `ddlSchemaName(storage)`; the unbound sentinel resolves to
+ * `DEFAULT_NAMESPACE_ID` (the search-path default for offline planning); a
+ * bare object payload (used by some tests) falls back to the namespace id
+ * itself.
+ */
+export function resolveDdlSchemaForNamespaceStorage(
+  storage: SqlStorage,
+  namespaceId: string,
+): string {
+  if (namespaceId === UNBOUND_NAMESPACE_ID) {
+    return DEFAULT_NAMESPACE_ID;
+  }
+  const namespace = storage.namespaces[namespaceId];
+  if (namespace && isPostgresSchema(namespace)) {
+    return namespace.ddlSchemaName(storage);
+  }
+  return namespaceId;
+}

package/src/core/migrations/runner.ts

@@ -12,7 +12,6 @@ import type {
   SqlMigrationRunnerSuccessValue,
 } 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 { 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';
@@ -23,8 +22,6 @@ import { blindCast } from '@prisma-next/utils/casts';
 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 type { PostgresPlanTargetDetails } from './planner-target-details';
 
 interface ApplyPlanSuccessValue {
@@ -124,30 +121,27 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
       applyValue = applyResult.value;
     }
 
-    // Schema verification on app-space only — extension spaces don't
-    // own user-facing tables in the live schema, and `verifySqlSchema`
-    // matches the destination contract against the database, which
-    // would flag every app-space table as "extra" when called against
-    // an extension contract.
+    // Verify the schema on app-space only: extension spaces don't own
+    // user-facing tables, so verifying the destination contract against the
+    // database would flag every app-space table as "extra". Delegates to the
+    // family `verifySchema` — the same comparison the CLI verify runs.
     if (space === APP_SPACE_ID) {
-      const schemaIR = await this.family.introspect({
+      const schemaNode = await this.family.introspect({
         driver,
         contract: options.destinationContract,
       });
-      const schemaVerifyResult = verifySqlSchema({
+      const schemaVerifyResult = this.family.verifySchema({
         contract: options.destinationContract,
-        schema: schemaIR,
+        schema: schemaNode,
         strict: options.strictVerification ?? true,
-        context: options.context ?? {},
-        typeMetadataRegistry: this.family.typeMetadataRegistry,
         frameworkComponents: options.frameworkComponents,
-        normalizeDefault: parsePostgresDefault,
-        normalizeNativeType: normalizeSchemaNativeType,
       });
       if (!schemaVerifyResult.ok) {
         return runnerFailure('SCHEMA_VERIFY_FAILED', schemaVerifyResult.summary, {
           why: 'The resulting database schema does not satisfy the destination contract.',
-          meta: { issues: schemaVerifyResult.schema.issues },
+          meta: {
+            issues: schemaVerifyResult.schema.issues,
+          },
         });
       }
     }

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

@@ -1,9 +1,13 @@
 import type { Contract } from '@prisma-next/contract/types';
-import type { SchemaIssue } from '@prisma-next/framework-components/control';
+import type { SchemaDiffIssue } from '@prisma-next/framework-components/control';
 import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
-import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
+import type { SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import { DEFAULT_NAMESPACE_ID } from '../namespace-ids';
 import { isPostgresSchema } from '../postgres-schema';
+import { PostgresDatabaseSchemaNode } from '../schema-ir/postgres-database-schema-node';
+import { PostgresNamespaceSchemaNode } from '../schema-ir/postgres-namespace-schema-node';
+import type { SqlSchemaDiffNode } from '../schema-ir/schema-node-kinds';
 
 /**
  * Resolves the live-database schema name for a given namespace
@@ -23,32 +27,36 @@ function resolveDdlSchemaName(storage: SqlStorage, namespaceId: string): string
 }
 
 /**
- * Reads the introspected list of schema names from the Postgres-flavoured
- * annotations slot on the schema IR. Defaults to the always-present
- * `public` schema when introspection did not populate the slot — a fresh
- * Postgres database always carries `public` (unless an operator dropped
- * it manually), so any verifier path that runs without an enriched
- * introspection still suppresses the redundant `CREATE SCHEMA "public"`.
+ * Reads the introspected list of schema names from the database-root schema
+ * node. `existingSchemas` is database-level, so it lives on the
+ * `PostgresDatabaseSchemaNode` root — not on the per-schema namespace nodes.
+ *
+ * Defaults to the always-present `public` schema when the node is not the
+ * database root — a fresh Postgres database always carries `public` (unless an
+ * operator dropped it manually), so any verifier path that runs without an
+ * enriched introspection still suppresses the redundant `CREATE SCHEMA
+ * "public"`.
  *
  * Production introspection (`PostgresControlAdapter.introspect`) is the
- * authoritative source: it queries `pg_namespace` and writes every
- * non-system schema into `annotations.pg.existingSchemas`. Tests that
- * want to assert against a richer initial state pass the slot
- * explicitly via the schema IR.
+ * authoritative source: it queries `pg_namespace` and sets `existingSchemas`
+ * on the returned root. Tests that want to assert against a richer initial
+ * state construct a `PostgresDatabaseSchemaNode` explicitly.
  */
-function existingSchemasFromSchema(schema: SqlSchemaIR): readonly string[] {
-  const annotations = (schema as { annotations?: { pg?: { existingSchemas?: unknown } } })
-    .annotations;
-  const slot = annotations?.pg?.existingSchemas;
-  if (Array.isArray(slot)) {
-    return slot.filter((s): s is string => typeof s === 'string');
+function existingSchemasFromSchema(schema: SqlSchemaIRNode): readonly string[] {
+  if (PostgresDatabaseSchemaNode.is(schema)) {
+    return schema.existingSchemas;
   }
-  return ['public'];
+  return [DEFAULT_NAMESPACE_ID];
 }
 
 /**
- * Emits a `missing_schema` issue for every contract-declared Postgres
- * namespace whose live container does not yet exist.
+ * Emits a `postgres-namespace` `not-found` diff issue for every
+ * contract-declared Postgres namespace whose live container does not yet
+ * exist. The planner prepends these (node-typed, synthesized) to the
+ * relational diff issues so a multi-schema plan emits `CREATE SCHEMA`
+ * before the tables that need it — a planner-only concern (verify already
+ * rejects via the `not-found` table issues a missing schema already
+ * produces), so this is not part of the shared diff.
  *
  * A namespace's live container is the schema returned by its
  * polymorphic `ddlSchemaName(storage)` method — named schemas resolve
@@ -59,28 +67,36 @@ function existingSchemasFromSchema(schema: SqlSchemaIR): readonly string[] {
  * 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
- * schema name through the same polymorphic path — keeping the
- * coordinate, not the resolved name, as the issue's stable identity.
+ * Each emitted issue's path is `['database', ddlName]` — an ancestor of
+ * every table path under that schema, so it must never be run through
+ * `coalesceSubtreeIssues` alongside the table diff (it would swallow the
+ * table-level `not-found` issues that drive `CREATE TABLE`); the planner
+ * adds these AFTER coalescing the relational issues, and they are not
+ * subject to sibling-space ownership scoping (mirrors the retired
+ * coordinate walk, which prepended namespace issues after that filter).
  */
 export function verifyPostgresNamespacePresence(input: {
   readonly contract: Contract<SqlStorage>;
-  readonly schema: SqlSchemaIR;
-}): readonly SchemaIssue[] {
+  readonly schema: SqlSchemaIRNode;
+}): readonly SchemaDiffIssue<SqlSchemaDiffNode>[] {
   const { contract, schema } = input;
   const existing = new Set(existingSchemasFromSchema(schema));
-  const issues: SchemaIssue[] = [];
+  const issues: SchemaDiffIssue<SqlSchemaDiffNode>[] = [];
   const namespaceIds = Object.keys(contract.storage.namespaces).sort();
   for (const namespaceId of namespaceIds) {
     if (namespaceId === UNBOUND_NAMESPACE_ID) continue;
     const ddlName = resolveDdlSchemaName(contract.storage, namespaceId);
     if (ddlName === UNBOUND_NAMESPACE_ID) continue;
     if (existing.has(ddlName)) continue;
+    const namespace = new PostgresNamespaceSchemaNode({
+      schemaName: ddlName,
+      tables: {},
+      nativeEnumTypeNames: [],
+    });
     issues.push({
-      kind: 'missing_schema',
-      namespaceId,
-      message: `Schema "${ddlName}" is missing from database`,
+      path: ['database', ddlName],
+      reason: 'not-found',
+      expected: namespace,
     });
   }
   return issues;

package/src/core/namespace-ids.ts

@@ -0,0 +1,3 @@
+// Leaf module: authoring.ts and descriptor-meta.ts both need this and import each other.
+/** Postgres's default schema; `postgresTargetDescriptorMeta.defaultNamespaceId` is this value. */
+export const DEFAULT_NAMESPACE_ID = 'public' as const;