@prisma-next/target-postgres 0.14.0 → 0.15.0-dev.10

package/src/core/migrations/contract-to-postgres-database-schema-node.ts

@@ -0,0 +1,269 @@
+import type { ContractToSchemaIROptions } from '@prisma-next/family-sql/control';
+import { contractNamespaceToSchemaIR } from '@prisma-next/family-sql/control';
+import type { SchemaNodeRef } from '@prisma-next/framework-components/control';
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
+import {
+  PrimaryKey,
+  RelationalSchemaNodeKind,
+  SqlForeignKeyIR,
+  SqlIndexIR,
+  SqlUniqueIR,
+} from '@prisma-next/sql-schema-ir/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import type { PostgresRlsPolicy } from '../postgres-rls-policy';
+import type { PostgresContract } from '../postgres-schema';
+import { isPostgresSchema } from '../postgres-schema';
+import { PostgresDatabaseSchemaNode } from '../schema-ir/postgres-database-schema-node';
+import { PostgresNamespaceSchemaNode } from '../schema-ir/postgres-namespace-schema-node';
+import { PostgresNativeEnumSchemaNode } from '../schema-ir/postgres-native-enum-schema-node';
+import { PostgresPolicySchemaNode } from '../schema-ir/postgres-policy-schema-node';
+import { PostgresRoleSchemaNode } from '../schema-ir/postgres-role-schema-node';
+import { PostgresTableSchemaNode } from '../schema-ir/postgres-table-schema-node';
+import { PostgresSchemaNodeKind } from '../schema-ir/schema-node-kinds';
+import { resolveDdlSchemaForNamespaceStorage } from './resolve-ddl-schema';
+
+/** The database root's fixed sentinel id (`PostgresDatabaseSchemaNode#id`). */
+function databaseStep(): { readonly nodeKind: string; readonly id: string } {
+  return { nodeKind: PostgresSchemaNodeKind.database, id: 'database' };
+}
+
+function tableDependsOn(namespaceId: string, tableName: string): SchemaNodeRef {
+  return [
+    databaseStep(),
+    { nodeKind: PostgresSchemaNodeKind.namespace, id: namespaceId },
+    { nodeKind: PostgresSchemaNodeKind.table, id: tableName },
+  ];
+}
+
+function roleDependsOn(role: string): SchemaNodeRef {
+  return [databaseStep(), { nodeKind: PostgresSchemaNodeKind.role, id: role }];
+}
+
+/**
+ * The chains from a table-child object (foreign key, index, unique, primary
+ * key) to each of the own columns it is built on, in the Postgres tree.
+ * Dropping a covered column auto-drops the object, so the object's drop must
+ * precede the column's; the graph derives that direction from these edges.
+ */
+function columnDependsOn(
+  namespaceId: string,
+  tableName: string,
+  columns: readonly string[],
+): readonly SchemaNodeRef[] {
+  return columns.map((column) => [
+    ...tableDependsOn(namespaceId, tableName),
+    { nodeKind: RelationalSchemaNodeKind.column, id: `column:${column}` },
+  ]);
+}
+
+function toPolicyNode(policy: PostgresRlsPolicy, namespaceId: string): PostgresPolicySchemaNode {
+  return new PostgresPolicySchemaNode({
+    name: policy.name,
+    prefix: policy.prefix,
+    tableName: policy.tableName,
+    namespaceId,
+    operation: policy.operation,
+    roles: [...policy.roles],
+    ...ifDefined('using', policy.using),
+    ...ifDefined('withCheck', policy.withCheck),
+    permissive: policy.permissive,
+    dependsOn: [tableDependsOn(namespaceId, policy.tableName), ...policy.roles.map(roleDependsOn)],
+  });
+}
+
+/**
+ * Projects a Postgres contract into the expected schema-diff tree: a
+ * `PostgresDatabaseSchemaNode` root holding one `PostgresNamespaceSchemaNode`
+ * per Postgres namespace, each holding its `PostgresTableSchemaNode`s with
+ * their `PostgresPolicySchemaNode`s, plus the database roles on the root.
+ *
+ * Not a duplicate of the family's `contractToSchemaIR`: that builds a flat,
+ * single `{ tables }` map (and throws on cross-namespace name collisions, with
+ * no RLS/role concept) for SQLite's single-schema world. This is the
+ * Postgres-specific *tree* shape — multi-schema, RLS-policy-aware, role-aware.
+ * It reuses the family's per-namespace table conversion (`contractNamespaceToSchemaIR`)
+ * for column/FK/index building and only adds the Postgres tree/policy/role shape.
+ *
+ * Tables are grouped by their owning namespace (resolved DDL schema name) so
+ * the tree mirrors Postgres's object hierarchy. The DDL schema name is
+ * resolved once per namespace.
+ *
+ * A policy that references a table absent from its namespace is a malformed
+ * contract — the loop throws rather than fabricating a stub table.
+ */
+export function contractToPostgresDatabaseSchemaNode(
+  contract: PostgresContract | null,
+  options: ContractToSchemaIROptions,
+): PostgresDatabaseSchemaNode {
+  if (contract === null) {
+    return new PostgresDatabaseSchemaNode({
+      namespaces: {},
+      roles: [],
+      existingSchemas: [],
+      pgVersion: '',
+    });
+  }
+
+  const namespaces: Record<string, PostgresNamespaceSchemaNode> = {};
+  const roles: PostgresRoleSchemaNode[] = [];
+  const ownedSchemas: string[] = [];
+
+  for (const ns of Object.values(contract.storage.namespaces)) {
+    if (!isPostgresSchema(ns)) continue;
+
+    // Role entries are root-level diff subjects: they hoist to the database
+    // root from every slot and never count toward whether a namespace
+    // materializes a schema node.
+    for (const role of Object.values(ns.role)) {
+      roles.push(new PostgresRoleSchemaNode({ name: role.name, namespaceId: role.namespaceId }));
+    }
+
+    // The unbound slot resolves its DDL schema to 'public', so it
+    // materializes a schema node exactly when it has non-role content — a
+    // late-binding contract keeps today's behavior (the slot carries the
+    // tables), while a roles-only unbound slot alongside named namespaces
+    // contributes only root roles and no node (which would otherwise be a
+    // spurious empty 'public' node, clobbering a real bound 'public'
+    // namespace's node keyed by the same resolved schema name).
+    if (ns.id === UNBOUND_NAMESPACE_ID) {
+      const hasNonRoleContent = Object.entries(ns.entries).some(
+        ([entriesKey, slot]) => entriesKey !== 'role' && Object.keys(slot).length > 0,
+      );
+      if (!hasNonRoleContent) continue;
+    }
+
+    const ddlSchema = resolveDdlSchemaForNamespaceStorage(contract.storage, ns.id);
+    ownedSchemas.push(ddlSchema);
+
+    // Convert only THIS namespace's tables (passing the full storage for
+    // type/value-set/enum resolution that spans namespaces), so the same table
+    // name can exist in two schemas without colliding in a bare-keyed record.
+    const sqlTables = contractNamespaceToSchemaIR(contract.storage, ns.id, options).tables;
+
+    const policiesByTable = new Map<string, PostgresPolicySchemaNode[]>();
+    for (const policy of Object.values(ns.policy)) {
+      const list = policiesByTable.get(policy.tableName) ?? [];
+      list.push(toPolicyNode(policy, ddlSchema));
+      policiesByTable.set(policy.tableName, list);
+    }
+
+    const tables: Record<string, PostgresTableSchemaNode> = {};
+    for (const tableName of Object.keys(ns.table)) {
+      const sqlTable = sqlTables[tableName];
+      if (sqlTable === undefined) continue;
+      // The family conversion stamps `referencedSchema` only for bound FK
+      // targets; an absent value means the FK targets the unbound namespace.
+      // Postgres restores its own coordinate for that slot (the unbound
+      // singleton's id) so the raw coordinate keeps qualifying REFERENCES
+      // clauses, and resolves the real live DDL schema — introspected FKs
+      // already carry the live schema, so this is what lets an expected FK
+      // pair (by diff-node id) with its introspected counterpart.
+      const foreignKeys = sqlTable.foreignKeys.map((fk) => {
+        const resolvedReferencedNamespace = resolveDdlSchemaForNamespaceStorage(
+          contract.storage,
+          fk.referencedSchema ?? UNBOUND_NAMESPACE_ID,
+        );
+        return new SqlForeignKeyIR({
+          columns: fk.columns,
+          referencedTable: fk.referencedTable,
+          referencedColumns: fk.referencedColumns,
+          referencedSchema: fk.referencedSchema ?? UNBOUND_NAMESPACE_ID,
+          ...ifDefined('name', fk.name),
+          ...ifDefined('onDelete', fk.onDelete),
+          ...ifDefined('onUpdate', fk.onUpdate),
+          ...ifDefined('annotations', fk.annotations),
+          resolvedReferencedNamespace,
+          dependsOn: [
+            tableDependsOn(resolvedReferencedNamespace, fk.referencedTable),
+            ...columnDependsOn(ddlSchema, tableName, fk.columns),
+          ],
+        });
+      });
+      // The family stamped these children's own-column `dependsOn` with the
+      // flat (single-schema) chain; the Postgres tree nests them under a
+      // namespace, so re-stamp with the multi-schema chain that matches this
+      // tree's paths. Every other field is carried through unchanged.
+      const uniques = sqlTable.uniques.map(
+        (u) =>
+          new SqlUniqueIR({
+            columns: u.columns,
+            ...ifDefined('name', u.name),
+            ...ifDefined('annotations', u.annotations),
+            dependsOn: columnDependsOn(ddlSchema, tableName, u.columns),
+          }),
+      );
+      const indexes = sqlTable.indexes.map(
+        (i) =>
+          new SqlIndexIR({
+            columns: i.columns,
+            unique: i.unique,
+            ...ifDefined('name', i.name),
+            ...ifDefined('type', i.type),
+            ...ifDefined('options', i.options),
+            ...ifDefined('annotations', i.annotations),
+            dependsOn: columnDependsOn(ddlSchema, tableName, i.columns),
+          }),
+      );
+      const primaryKey =
+        sqlTable.primaryKey !== undefined
+          ? new PrimaryKey({
+              columns: sqlTable.primaryKey.columns,
+              ...ifDefined('name', sqlTable.primaryKey.name),
+              dependsOn: columnDependsOn(ddlSchema, tableName, sqlTable.primaryKey.columns),
+            })
+          : undefined;
+      tables[tableName] = new PostgresTableSchemaNode({
+        name: sqlTable.name,
+        columns: sqlTable.columns,
+        foreignKeys,
+        uniques,
+        indexes,
+        ...ifDefined('primaryKey', primaryKey),
+        ...ifDefined('annotations', sqlTable.annotations),
+        ...ifDefined('checks', sqlTable.checks),
+        policies: policiesByTable.get(tableName) ?? [],
+        // Marker-driven, never derived from the policy set: the `rls` entry
+        // is the single authored source of enablement.
+        rlsEnabled: Object.hasOwn(ns.rls, tableName),
+      });
+    }
+
+    for (const [tableName, tablePolicies] of policiesByTable) {
+      if (!(tableName in tables)) {
+        const policyName = tablePolicies[0]?.name ?? '(unknown)';
+        throw new Error(
+          `contract-to-postgres-database-schema-node: policy "${policyName}" references table "${tableName}" not present in namespace "${ddlSchema}"`,
+        );
+      }
+      if (!Object.hasOwn(ns.rls, tableName)) {
+        const policyPrefix = tablePolicies[0]?.prefix ?? '(unknown)';
+        throw new Error(
+          `contract-to-postgres-database-schema-node: policy "${policyPrefix}" targets table "${tableName}" in namespace "${ddlSchema}", which is not RLS-controlled. Mark the model with @@rls (entries.rls["${tableName}"]) or remove the policy.`,
+        );
+      }
+    }
+
+    const nativeEnums = Object.values(ns.entries.native_enum ?? {}).map(
+      (entity) =>
+        new PostgresNativeEnumSchemaNode({
+          typeName: entity.typeName,
+          namespaceId: ddlSchema,
+          members: entity.members,
+          ...ifDefined('control', entity.control),
+        }),
+    );
+
+    namespaces[ddlSchema] = new PostgresNamespaceSchemaNode({
+      schemaName: ddlSchema,
+      tables,
+      nativeEnums,
+    });
+  }
+
+  return new PostgresDatabaseSchemaNode({
+    namespaces,
+    roles,
+    existingSchemas: ownedSchemas,
+    pgVersion: '',
+  });
+}

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

@@ -1,10 +1,23 @@
-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 { issueOutcome } 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 +30,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 +50,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 +79,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 +121,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 +204,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 +223,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 (issueOutcome(issue) !== '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 (issueOutcome(issue) !== '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: issueOutcome(issue) === '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,
+  };
 }