@prisma-next/target-postgres 0.14.0-dev.8 → 0.14.0-dev.80

package/src/core/migrations/control-policy.ts

@@ -1,10 +1,22 @@
-import type { Contract } from '@prisma-next/contract/types';
-import type { ControlPolicySubject } from '@prisma-next/family-sql/control';
-import type { SchemaIssue } from '@prisma-next/framework-components/control';
+import type { Contract, ControlPolicy } from '@prisma-next/contract/types';
+import type {
+  ControlPolicySubject,
+  SqlPlannerConflict,
+  SuppressionRecord,
+} from '@prisma-next/family-sql/control';
+import type { SchemaDiffIssue } from '@prisma-next/framework-components/control';
 import { entityAt, UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import type { SqlStorage, StorageTable } from '@prisma-next/sql-contract/types';
+import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { type PostgresRole, ROLE_DEFAULT_CONTROL_POLICY } from '../postgres-role';
 import { isPostgresSchema } from '../postgres-schema';
+import { postgresNodeStorageCoordinate } from '../schema-ir/node-storage-coordinate';
+import type { PostgresNamespaceSchemaNode } from '../schema-ir/postgres-namespace-schema-node';
+import { PostgresTableSchemaNode } from '../schema-ir/postgres-table-schema-node';
+import type { SqlSchemaDiffNode } from '../schema-ir/schema-node-kinds';
+import { PostgresSchemaNodeKind } from '../schema-ir/schema-node-kinds';
+import { issueColumnName } from './issue-planner';
 import type { PostgresOpFactoryCall } from './op-factory-call';
 
 /**
@@ -17,11 +29,16 @@ import type { PostgresOpFactoryCall } from './op-factory-call';
  * and is fail-closed. Any call not listed here — including future or
  * extension-contributed factories — is treated as NOT object-creation, so it
  * is suppressed under `tolerated` rather than permissively emitted.
+ *
+ * Lists the creation factories that actually reach the call-side resolver
+ * (`resolvePostgresCallControlPolicySubject`) — today only RLS policy
+ * creation, from `planPostgresSchemaDiff`. Every other whole-object create
+ * (table, schema, native enum, and RLS enablement) is constructed inside
+ * `planIssues` and graded on the node side by
+ * `resolvePostgresNodeIssueCreationFactoryName`, so none of them are listed
+ * here.
  */
-const OBJECT_CREATION_FACTORIES: ReadonlySet<string> = new Set<string>([
-  'createTable',
-  'createSchema',
-]);
+const OBJECT_CREATION_FACTORIES: ReadonlySet<string> = new Set<string>(['createRlsPolicy']);
 
 function createsNewTopLevelObject(call: PostgresOpFactoryCall): boolean {
   return OBJECT_CREATION_FACTORIES.has(call.factoryName);
@@ -32,18 +49,25 @@ function ddlSchemaNameForNamespace(contract: Contract<SqlStorage>, namespaceId:
   return isPostgresSchema(namespace) ? namespace.ddlSchemaName(contract.storage) : namespaceId;
 }
 
-function resolveNamespaceIdForTable(
+/**
+ * Resolve the namespace a declared storage entity lives in by walking every
+ * namespace for one whose `entries` map actually contains the coordinate —
+ * a table by its name, a native enum by its physical type name (see
+ * {@link postgresNodeStorageCoordinate}). When `ddlSchemaName` is given, the
+ * match must also land in that DDL schema (disambiguates same-named entities
+ * declared under different namespaces); when omitted, the first namespace
+ * that declares the entity wins. Falls back to {@link UNBOUND_NAMESPACE_ID}
+ * when no namespace declares it — e.g. an extra/dropped entity the contract
+ * doesn't claim at all.
+ */
+function resolveNamespaceIdForEntity(
   contract: Contract<SqlStorage>,
-  tableName: string,
+  coordinate: { readonly entityKind: string; readonly entityName: string },
   ddlSchemaName: string | undefined,
 ): string {
   for (const namespaceId of Object.keys(contract.storage.namespaces)) {
-    const table = entityAt<StorageTable>(contract.storage, {
-      namespaceId,
-      entityKind: 'table',
-      entityName: tableName,
-    });
-    if (!table) continue;
+    const entity = entityAt(contract.storage, { namespaceId, ...coordinate });
+    if (!entity) continue;
     if (
       ddlSchemaName === undefined ||
       ddlSchemaNameForNamespace(contract, namespaceId) === ddlSchemaName
@@ -54,7 +78,19 @@ function resolveNamespaceIdForTable(
   return UNBOUND_NAMESPACE_ID;
 }
 
-function resolveNamespaceIdForDdlSchema(
+function resolveNamespaceIdForTable(
+  contract: Contract<SqlStorage>,
+  tableName: string,
+  ddlSchemaName: string | undefined,
+): string {
+  return resolveNamespaceIdForEntity(
+    contract,
+    { entityKind: 'table', entityName: tableName },
+    ddlSchemaName,
+  );
+}
+
+export function resolveNamespaceIdForDdlSchema(
   contract: Contract<SqlStorage>,
   ddlSchemaName: string,
 ): string {
@@ -84,16 +120,60 @@ function postgresCallFields(call: PostgresOpFactoryCall): PostgresCallFields {
   };
 }
 
-export function formatPostgresControlPolicySubjectLabel(
-  factoryName: string,
+function formatSuppressionSubjectLabel(
   subject: ControlPolicySubject | undefined,
   contract: Contract<SqlStorage>,
 ): string {
-  if (subject?.table) {
-    const ddlSchema = ddlSchemaNameForNamespace(contract, subject.namespaceId);
-    return `${factoryName}(${ddlSchema}.${subject.table})`;
+  if (subject === undefined) return 'unknown';
+  const ddlSchema = ddlSchemaNameForNamespace(contract, subject.namespaceId);
+  if (subject.entityKind !== undefined && subject.entityName !== undefined) {
+    return `${subject.entityKind} "${ddlSchema}.${subject.entityName}"`;
+  }
+  return `namespace "${ddlSchema}"`;
+}
+
+function postgresSuppressionSummary(
+  subjectLabel: string,
+  subject: ControlPolicySubject | undefined,
+  policy: string,
+): string {
+  const namespace = subject?.namespaceId ?? 'unknown';
+  const declared = subject?.explicitNodeControlPolicy;
+  if (policy === 'external' && declared === 'managed') {
+    return `control policy suppressed: ${subjectLabel} — namespace '${namespace}' has effective control 'external' but declared 'managed'`;
   }
-  return factoryName;
+  const declaredSuffix = declared ? ` but declared '${declared}'` : '';
+  return `control policy suppressed: ${subjectLabel} — namespace '${namespace}' has effective control '${policy}'${declaredSuffix}`;
+}
+
+/**
+ * Render one family {@link SuppressionRecord} into a target `SqlPlannerConflict`.
+ * The family decides *that* a subject is suppressed and hands over the raw
+ * coordinate + policy; the label, message, and location are rendered here,
+ * driven entirely by the subject's own `(entityKind, entityName)` coordinate
+ * — no target-owned table-vs-enum vocabulary.
+ */
+export function renderPostgresSuppression(
+  record: SuppressionRecord,
+  contract: Contract<SqlStorage>,
+): SqlPlannerConflict {
+  const subject = record.subject;
+  const subjectLabel = formatSuppressionSubjectLabel(subject, contract);
+  return {
+    kind: 'controlPolicySuppressedCall',
+    summary: postgresSuppressionSummary(subjectLabel, subject, record.policy),
+    location: {
+      ...ifDefined('namespaceId', subject?.namespaceId),
+      ...ifDefined('entityKind', subject?.entityKind),
+      ...ifDefined('entityName', subject?.entityName),
+      ...ifDefined('column', subject?.column),
+    },
+    meta: {
+      controlPolicy: record.policy,
+      ...ifDefined('factoryName', record.factoryName),
+      ...ifDefined('declaredControlPolicy', subject?.explicitNodeControlPolicy),
+    },
+  };
 }
 
 export function resolvePostgresCallControlPolicySubject(
@@ -123,9 +203,10 @@ export function resolvePostgresCallControlPolicySubject(
     })?.control;
     return {
       namespaceId,
-      ...ifDefined('explicitNodeControlPolicy', tableControlPolicy),
-      table: callFields.tableName,
+      entityKind: 'table',
+      entityName: callFields.tableName,
       ...ifDefined('column', callFields.columnName),
+      ...ifDefined('explicitNodeControlPolicy', tableControlPolicy),
       createsNewObject,
     };
   }
@@ -141,64 +222,135 @@ export function resolvePostgresCallControlPolicySubject(
 }
 
 /**
- * Issue kinds that describe the absence of a whole, top-level Postgres
- * object — the same kinds `createsNewTopLevelObject` recognises for calls.
- * Used by {@link resolvePostgresIssueCreationFactoryName} to decide whether
- * a `tolerated` subject permits the issue to flow into the planner
+ * Node kinds whose *absence* is the creation of a whole, top-level Postgres
+ * object: a namespace, a table, or a native enum. Used by
+ * {@link resolvePostgresNodeIssueCreationFactoryName} to decide whether a
+ * `tolerated` subject permits the issue to flow into the planner
  * (create-if-absent) and to seed the suppressed-subject warning's
- * `factoryName` when the planner is skipped.
+ * `factoryName` when the planner is skipped. RLS policy creation is not
+ * listed here — policy issues never reach this issue-based partition (they
+ * are routed to `planPostgresSchemaDiff` and gated via the call-based
+ * {@link resolvePostgresCallControlPolicySubject} instead).
  */
-const POSTGRES_ISSUE_CREATION_FACTORY: Readonly<Record<string, string>> = Object.freeze({
-  missing_schema: 'createSchema',
-  missing_table: 'createTable',
+const POSTGRES_NODE_CREATION_FACTORY: Readonly<Record<string, string>> = Object.freeze({
+  [PostgresSchemaNodeKind.namespace]: 'createSchema',
+  [PostgresSchemaNodeKind.table]: 'createTable',
+  [PostgresSchemaNodeKind.nativeEnum]: 'createNativeEnumType',
 });
 
-export function resolvePostgresIssueCreationFactoryName(issue: SchemaIssue): string | undefined {
-  return POSTGRES_ISSUE_CREATION_FACTORY[issue.kind];
+/**
+ * A table `not-equal` issue whose `rlsEnabled` flips OFF→ON (expected on,
+ * actual off) is enablement toward `ENABLE ROW LEVEL SECURITY`. It is
+ * creation-class on the node side because `isEnablementCreationIssue` and
+ * {@link resolvePostgresNodeIssueCreationFactoryName} treat this OFF→ON delta
+ * as a creation: enabling RLS establishes the fail-closed guard the declared
+ * policy set attaches to, the same grant `tolerated` extends to creating the
+ * policies themselves. The opposite direction (`DISABLE`) is a modification
+ * and stays managed-only. Keying on the actual delta (not just the expected
+ * bit) keeps this correct if a second table attribute ever joins
+ * `isEqualTo`: a not-equal with no `rlsEnabled` delta is not enablement, so
+ * it is not admitted as creation-class here.
+ */
+function isEnablementCreationIssue(issue: SchemaDiffIssue<SqlSchemaDiffNode>): boolean {
+  if (issue.reason !== 'not-equal') return false;
+  const { expected, actual } = issue;
+  return (
+    expected !== undefined &&
+    actual !== undefined &&
+    PostgresTableSchemaNode.is(expected) &&
+    PostgresTableSchemaNode.is(actual) &&
+    expected.rlsEnabled === true &&
+    actual.rlsEnabled === false
+  );
+}
+
+export function resolvePostgresNodeIssueCreationFactoryName(
+  issue: SchemaDiffIssue<SqlSchemaDiffNode>,
+): string | undefined {
+  if (isEnablementCreationIssue(issue)) {
+    return 'enableRowLevelSecurity';
+  }
+  if (issue.reason !== 'not-found') return undefined;
+  const node = issue.expected ?? issue.actual;
+  if (node === undefined) return undefined;
+  return POSTGRES_NODE_CREATION_FACTORY[node.nodeKind];
 }
 
 /**
- * Resolve the control-policy subject coordinate for a single
- * {@link SchemaIssue}. Mirrors the resolution `resolvePostgresCallControlPolicySubject`
- * performs for a generated DDL call, but works *off the issue* — so the
- * planner can partition issues by effective policy before the diff engine
- * runs. `createsNewObject` is derived from the issue's kind: schema/table/
- * type-missing issues describe a brand-new top-level object; everything else
- * touches an existing object.
- *
- * An `extra_table` issue carries no contract namespace coordinate (the table
- * isn't in any contract namespace), so the subject's `namespaceId` falls
- * back to {@link UNBOUND_NAMESPACE_ID}; the call-side resolver does the same
- * for the `DropTableCall` it produces.
+ * Resolves the control-policy subject for a node-typed {@link SchemaDiffIssue}
+ * (the issue-side mirror of `resolvePostgresCallControlPolicySubject`).
+ * Storage entities resolve off their node coordinate; a sub-entity issue
+ * resolves off the enclosing table read from the issue path; an unclaimed
+ * extra falls back to the unbound coordinate. A role always resolves
+ * `'external'` — roles are referenced, never owned.
  */
-export function resolvePostgresIssueControlPolicySubject(
-  issue: SchemaIssue,
+export function resolvePostgresNodeIssueControlPolicySubject(
+  issue: SchemaDiffIssue<SqlSchemaDiffNode>,
   contract: Contract<SqlStorage>,
 ): ControlPolicySubject | undefined {
-  const createsNewObject = POSTGRES_ISSUE_CREATION_FACTORY[issue.kind] !== undefined;
+  const node = issue.expected ?? issue.actual;
+  if (node === undefined) return undefined;
+
+  if (node.nodeKind === PostgresSchemaNodeKind.namespace) {
+    const namespaceNode = blindCast<
+      PostgresNamespaceSchemaNode,
+      'a postgres-namespace diff node is always a PostgresNamespaceSchemaNode'
+    >(node);
+    return {
+      namespaceId: resolveNamespaceIdForDdlSchema(contract, namespaceNode.schemaName),
+      createsNewObject: issue.reason === 'not-found',
+    };
+  }
 
-  if (issue.kind === 'missing_schema' && issue.namespaceId) {
-    return { namespaceId: issue.namespaceId, createsNewObject };
+  if (node.nodeKind === PostgresSchemaNodeKind.role) {
+    const roleName = issue.path[1];
+    const roleEntity =
+      roleName === undefined
+        ? undefined
+        : entityAt<PostgresRole>(contract.storage, {
+            namespaceId: UNBOUND_NAMESPACE_ID,
+            entityKind: 'role',
+            entityName: roleName,
+          });
+    return {
+      namespaceId: UNBOUND_NAMESPACE_ID,
+      explicitNodeControlPolicy: roleEntity?.control ?? ROLE_DEFAULT_CONTROL_POLICY,
+      createsNewObject: false,
+    };
   }
 
-  if ('table' in issue && issue.table) {
-    const namespaceId =
-      'namespaceId' in issue && issue.namespaceId
-        ? issue.namespaceId
-        : resolveNamespaceIdForTable(contract, issue.table, undefined);
-    const table = entityAt<StorageTable>(contract.storage, {
+  const coordinate = postgresNodeStorageCoordinate(node);
+  if (coordinate !== undefined) {
+    const namespaceId = resolveNamespaceIdForEntity(contract, coordinate, issue.path[1]);
+    const entityControl = entityAt<{ readonly control?: ControlPolicy }>(contract.storage, {
       namespaceId,
-      entityKind: 'table',
-      entityName: issue.table,
-    });
+      ...coordinate,
+    })?.control;
     return {
       namespaceId,
-      ...ifDefined('explicitNodeControlPolicy', table?.control),
-      table: issue.table,
-      ...ifDefined('column', 'column' in issue ? issue.column : undefined),
-      createsNewObject,
+      ...coordinate,
+      ...ifDefined('column', issueColumnName(issue)),
+      ...ifDefined('explicitNodeControlPolicy', entityControl),
+      createsNewObject: resolvePostgresNodeIssueCreationFactoryName(issue) !== undefined,
     };
   }
 
-  return undefined;
+  const tableName = issue.path[2];
+  if (tableName === undefined) return undefined;
+  const ddlSchemaName = issue.path[1];
+  const namespaceId = resolveNamespaceIdForTable(contract, tableName, ddlSchemaName);
+  const table = entityAt<StorageTable>(contract.storage, {
+    namespaceId,
+    entityKind: 'table',
+    entityName: tableName,
+  });
+
+  return {
+    namespaceId,
+    entityKind: 'table',
+    entityName: tableName,
+    ...ifDefined('column', issueColumnName(issue)),
+    ...ifDefined('explicitNodeControlPolicy', table?.control),
+    createsNewObject: resolvePostgresNodeIssueCreationFactoryName(issue) !== undefined,
+  };
 }

package/src/core/migrations/diff-database-schema.ts

@@ -0,0 +1,252 @@
+import type { Contract, ControlPolicy } from '@prisma-next/contract/types';
+import type { SqlSchemaDiffResult } from '@prisma-next/family-sql/control';
+import { buildNativeTypeExpander } from '@prisma-next/family-sql/control';
+import { classifyDiffSubjectGranularity } from '@prisma-next/family-sql/diff';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type { DiffableNode, SchemaDiffIssue } from '@prisma-next/framework-components/control';
+import { diffSchemas } 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 { SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import { blindCast } from '@prisma-next/utils/casts';
+import { ifDefined } from '@prisma-next/utils/defined';
+import type { PostgresContract } from '../postgres-schema';
+import { PostgresDatabaseSchemaNode } from '../schema-ir/postgres-database-schema-node';
+import { PostgresNamespaceSchemaNode } from '../schema-ir/postgres-namespace-schema-node';
+import {
+  postgresDiffSubjectGranularity,
+  type SqlSchemaDiffNode,
+} from '../schema-ir/schema-node-kinds';
+import { contractToPostgresDatabaseSchemaNode } from './contract-to-postgres-database-schema-node';
+import { resolvePostgresNodeIssueControlPolicySubject } from './control-policy';
+
+/**
+ * Whether a diff issue's subject node is cluster-scoped — it carries its own
+ * `namespaceId` field (only role and policy diff nodes do) and that
+ * coordinate is the unbound sentinel, meaning the node is not owned by any
+ * schema/namespace. A role node is always cluster-scoped (roles are
+ * cluster-level objects); a policy node's `namespaceId` is always its
+ * table's resolved DDL schema, never the sentinel. Namespace-ownership
+ * scoping (which compares `issue.path[1]` against the set of DDL schemas
+ * the contract owns) makes no sense for a cluster-scoped subject — its path
+ * segment at that index is the object's own name, not a schema name — so
+ * such an issue bypasses that scoping entirely.
+ */
+function isClusterScopedIssue(issue: SchemaDiffIssue): boolean {
+  const node = issue.expected ?? issue.actual;
+  return node !== undefined && nodeNamespaceId(node) === UNBOUND_NAMESPACE_ID;
+}
+
+function nodeNamespaceId(node: DiffableNode): string | undefined {
+  if (!Object.hasOwn(node, 'namespaceId')) return undefined;
+  return blindCast<
+    { namespaceId: string },
+    'presence of an own namespaceId field was just checked via Object.hasOwn'
+  >(node).namespaceId;
+}
+
+function ownedSchemaNames(expected: PostgresDatabaseSchemaNode): ReadonlySet<string> {
+  const policyNamespaces = Object.values(expected.namespaces).flatMap((ns) =>
+    Object.values(ns.tables).flatMap((t) => t.policies.map((p) => p.namespaceId)),
+  );
+  return new Set([...policyNamespaces, ...expected.existingSchemas]);
+}
+
+/**
+ * Drops contract namespaces that declare no tables from the verdict-diff
+ * expected tree and the relational owned-schema set. The legacy relational
+ * walk skipped a table-less namespace (e.g. an enums-only schema) before
+ * pairing, so neither its DDL schema's absence nor that schema's live
+ * relational contents ever reached the verdict — the pruned tree
+ * reproduces that. The prune loses no expected policies: policies attach
+ * to tables, so a table-less namespace carries none (the projection
+ * throws on a policy referencing an absent table). Live policies in a
+ * pruned schema remain governed via the full owned set (see
+ * {@link diffPostgresSchema}).
+ */
+function pruneTableLessNamespaces(
+  expected: PostgresDatabaseSchemaNode,
+): PostgresDatabaseSchemaNode {
+  const namespaces = Object.fromEntries(
+    Object.entries(expected.namespaces).filter(([, ns]) => Object.keys(ns.tables).length > 0),
+  );
+  return new PostgresDatabaseSchemaNode({
+    namespaces,
+    roles: [...expected.roles],
+    existingSchemas: expected.existingSchemas.filter((s) => namespaces[s] !== undefined),
+    pgVersion: expected.pgVersion,
+  });
+}
+
+/**
+ * Resolves a verdict-diff issue's subject's declared control policy directly
+ * from the contract, by delegating to the same node-typed resolver
+ * ({@link resolvePostgresNodeIssueControlPolicySubject}) the planner uses to
+ * gate DDL calls. `undefined` when the issue resolves to no contract subject.
+ *
+ * A role issue resolves through that same resolver to `external`
+ * unconditionally (see its role branch), regardless of the contract's own
+ * default policy: a role is referenced by the contract but not owned, and
+ * `external`'s existing semantics — a missing declared subject still fails,
+ * every extra is suppressed — are exactly the wanted asymmetric grading for
+ * a cluster object the framework does not own.
+ */
+function resolveControlPolicy(
+  issue: SchemaDiffIssue,
+  contract: Contract<SqlStorage>,
+): ControlPolicy | undefined {
+  const nodeIssue = blindCast<
+    SchemaDiffIssue<SqlSchemaDiffNode>,
+    'every node in a Postgres schema diff tree is a SqlSchemaDiffNode'
+  >(issue);
+  return resolvePostgresNodeIssueControlPolicySubject(nodeIssue, contract)
+    ?.explicitNodeControlPolicy;
+}
+
+/**
+ * The Postgres full-tree node diff for the family verify verdict: derive
+ * the expected tree (resolved leaf values, expander threaded, FK schemas
+ * resolved, table-less namespaces pruned), run the generic
+ * differ over the trees as derived, and scope out `not-expected` findings under namespaces the
+ * contract does not own. Ownership scoping bypasses cluster-scoped subjects
+ * (roles today), mirroring the legacy decomposition: relational extras check
+ * the PRUNED owned set (the legacy
+ * per-namespace walk never visited a table-less namespace, so its live
+ * relational contents are invisible), while `structural` extras (RLS
+ * policies) check the FULL owned set (the legacy policy diff governed
+ * every contract schema regardless of tables — RLS governance does not
+ * shrink because a namespace declares no tables). The codec `verifyType`
+ * hooks run once per contract namespace with tables against that
+ * namespace's paired actual node (the hooks read namespace-scoped state
+ * such as `nativeEnums`).
+ */
+export function diffPostgresSchema(input: {
+  readonly contract: Contract<SqlStorage>;
+  readonly schema: SqlSchemaIRNode;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+}): SqlSchemaDiffResult {
+  const postgresContract = blindCast<
+    PostgresContract,
+    'diffPostgresSchema is only called with a postgres contract'
+  >(input.contract);
+  PostgresDatabaseSchemaNode.assert(input.schema);
+  const actual = input.schema;
+  const expandNativeType = buildNativeTypeExpander(input.frameworkComponents);
+  const fullExpected = contractToPostgresDatabaseSchemaNode(postgresContract, {
+    annotationNamespace: 'pg',
+    ...ifDefined('expandNativeType', expandNativeType),
+  });
+  const expected = pruneTableLessNamespaces(fullExpected);
+  const relationalOwned = ownedSchemaNames(expected);
+  const structuralOwned = ownedSchemaNames(fullExpected);
+  const issues = diffSchemas(expected, actual).filter((issue) => {
+    if (issue.reason !== 'not-expected') return true;
+    if (isClusterScopedIssue(issue)) return true;
+    const granularity = classifyDiffSubjectGranularity(issue, postgresDiffSubjectGranularity);
+    const namespaceSegment = issue.path[1];
+    if (namespaceSegment === undefined) return true;
+    const owned = granularity === 'structural' ? structuralOwned : relationalOwned;
+    return owned.has(namespaceSegment);
+  });
+  const namespacePairs = Object.values(expected.namespaces).map((ns) => ({
+    actual: actual.namespaces[ns.schemaName],
+  }));
+  return {
+    issues,
+    resolveControlPolicy: (issue) => resolveControlPolicy(issue, postgresContract),
+    namespacePairs,
+  };
+}
+
+/**
+ * Adds an empty namespace node to the actual tree for every expected namespace
+ * absent from it. The relational plan diff pairs on namespace: a contract
+ * namespace whose live schema does not exist yet must surface each of its
+ * tables as `not-found` (→ `CREATE TABLE`), NOT as a single namespace
+ * `not-found` that subtree-coalescing would collapse (leaving `CREATE SCHEMA`
+ * with no tables). Padding makes the namespaces pair, so only table/column/
+ * policy drift surfaces; `CREATE SCHEMA` comes separately from the synthesized
+ * namespace-presence stitch (`verifyPostgresNamespacePresence`), never from the
+ * tree diff — matching the retired per-namespace-paired relational walk, which
+ * paired a missing schema against an empty namespace node.
+ */
+function padActualNamespaces(
+  expected: PostgresDatabaseSchemaNode,
+  actual: PostgresDatabaseSchemaNode,
+): PostgresDatabaseSchemaNode {
+  const namespaces: Record<string, PostgresNamespaceSchemaNode> = { ...actual.namespaces };
+  let padded = false;
+  for (const schemaName of Object.keys(expected.namespaces)) {
+    if (namespaces[schemaName] === undefined) {
+      namespaces[schemaName] = new PostgresNamespaceSchemaNode({
+        schemaName,
+        tables: {},
+      });
+      padded = true;
+    }
+  }
+  if (!padded) return actual;
+  return new PostgresDatabaseSchemaNode({
+    namespaces,
+    roles: [...actual.roles],
+    existingSchemas: [...actual.existingSchemas],
+    pgVersion: actual.pgVersion,
+  });
+}
+
+export interface PostgresPlanDiff {
+  /** The desired ("end") tree — resolved leaf values (incl. `codecRef`) on every column, table-less namespaces pruned. */
+  readonly expected: PostgresDatabaseSchemaNode;
+  /** The live ("start") tree, padded with empty namespaces so a missing schema's tables pair. */
+  readonly actual: PostgresDatabaseSchemaNode;
+  /** The one node diff over the two trees: relational + policy drift, cluster-scope-aware ownership filtered. */
+  readonly issues: readonly SchemaDiffIssue<SqlSchemaDiffNode>[];
+}
+
+/**
+ * The Postgres planner's diff input: the SAME tree-building
+ * `diffPostgresSchema` uses (expander threaded, FK schemas resolved,
+ * table-less namespaces pruned, cluster-scope-aware ownership filter) plus
+ * actual namespace padding (so a missing
+ * schema's tables surface as `not-found` instead of a swallowed namespace
+ * `not-found`). One differ drives both verify and plan; this is the
+ * plan-side derivation. The single issue list covers tables / columns /
+ * constraints / indexes / defaults AND policies — the caller splits it
+ * (relational → `mapNodeIssueToCall`; policy → RLS ops) and stitches in
+ * `CREATE SCHEMA` separately.
+ */
+export function buildPostgresPlanDiff(input: {
+  readonly contract: Contract<SqlStorage>;
+  readonly actualSchema: SqlSchemaIRNode;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+}): PostgresPlanDiff {
+  const postgresContract = blindCast<
+    PostgresContract,
+    'buildPostgresPlanDiff is only called with a postgres contract'
+  >(input.contract);
+  PostgresDatabaseSchemaNode.assert(input.actualSchema);
+  const actual = input.actualSchema;
+  const expandNativeType = buildNativeTypeExpander(input.frameworkComponents);
+  const projectionOptions = {
+    annotationNamespace: 'pg',
+    ...ifDefined('expandNativeType', expandNativeType),
+  };
+  const fullExpected = contractToPostgresDatabaseSchemaNode(postgresContract, projectionOptions);
+  const expected = pruneTableLessNamespaces(fullExpected);
+  const paddedActual = padActualNamespaces(expected, actual);
+  const relationalOwned = ownedSchemaNames(expected);
+  const structuralOwned = ownedSchemaNames(fullExpected);
+  const issues = blindCast<
+    readonly SchemaDiffIssue<SqlSchemaDiffNode>[],
+    'both trees are PostgresDatabaseSchemaNodes, so every diff-issue node is a SqlSchemaDiffNode'
+  >(diffSchemas(expected, paddedActual)).filter((issue) => {
+    if (issue.reason !== 'not-expected') return true;
+    if (isClusterScopedIssue(issue)) return true;
+    const granularity = classifyDiffSubjectGranularity(issue, postgresDiffSubjectGranularity);
+    const namespaceSegment = issue.path[1];
+    if (namespaceSegment === undefined) return true;
+    const owned = granularity === 'structural' ? structuralOwned : relationalOwned;
+    return owned.has(namespaceSegment);
+  });
+  return { expected, actual: paddedActual, issues };
+}