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

package/src/core/entity-kinds.ts

@@ -0,0 +1,41 @@
+import type { EntityKindDescriptor } from '@prisma-next/framework-components/ir';
+import { PostgresNativeEnum, type PostgresNativeEnumInput } from './postgres-native-enum';
+import { PostgresRlsEnablement, type PostgresRlsEnablementInput } from './postgres-rls-enablement';
+import { PostgresRlsPolicy, type PostgresRlsPolicyInput } from './postgres-rls-policy';
+import { PostgresRole, type PostgresRoleInput } from './postgres-role';
+import {
+  PostgresNativeEnumSchema,
+  PostgresRlsEnablementSchema,
+  PostgresRlsPolicySchema,
+  PostgresRoleSchema,
+} from './postgres-validators';
+
+export const policyEntityKind: EntityKindDescriptor<PostgresRlsPolicyInput, PostgresRlsPolicy> = {
+  kind: 'policy',
+  schema: PostgresRlsPolicySchema,
+  construct: (input) => new PostgresRlsPolicy(input),
+};
+
+export const roleEntityKind: EntityKindDescriptor<PostgresRoleInput, PostgresRole> = {
+  kind: 'role',
+  schema: PostgresRoleSchema,
+  construct: (input) => new PostgresRole(input),
+};
+
+export const rlsEnablementEntityKind: EntityKindDescriptor<
+  PostgresRlsEnablementInput,
+  PostgresRlsEnablement
+> = {
+  kind: 'rls',
+  schema: PostgresRlsEnablementSchema,
+  construct: (input) => new PostgresRlsEnablement(input),
+};
+
+export const nativeEnumEntityKind: EntityKindDescriptor<
+  PostgresNativeEnumInput,
+  PostgresNativeEnum
+> = {
+  kind: 'native_enum',
+  schema: PostgresNativeEnumSchema,
+  construct: (input) => new PostgresNativeEnum(input),
+};

package/src/core/errors.ts

@@ -1,14 +1,16 @@
 import { CliStructuredError } from '@prisma-next/errors/control';
 
 /**
- * A `PostgresMigration` instance method that needs the materialized control
- * adapter (currently only `this.dataTransform(...)`) was invoked, but the
- * migration was constructed without a `ControlStack`. Concrete authoring
- * usage always goes through the migration CLI entrypoint, which assembles
- * a stack from the loaded `prisma-next.config.ts`; reaching this error
- * means a test fixture or ad-hoc consumer instantiated `PostgresMigration`
- * with the no-arg form (legal for `operations` / `describe` introspection
- * only).
+ * A `PostgresMigration` operation that needs the materialized control adapter
+ * — named by `operation` (e.g. `createTable`, `dropColumn`, `dataTransform`) —
+ * was invoked, but the migration was constructed without a `ControlStack`.
+ * Concrete authoring usage always goes through the migration CLI entrypoint,
+ * which assembles a stack from the loaded `prisma-next.config.ts`; reaching this
+ * error means a test fixture or ad-hoc consumer instantiated `PostgresMigration`
+ * with the no-arg form (legal for `operations` / `describe` introspection only).
+ *
+ * The `operation` argument is required so every throw site names the operation
+ * that actually failed; a new operation cannot inherit a misattributed message.
  *
  * Distinct from `PN-MIG-2001` (placeholder not filled) and `PN-MIG-2005`
  * (data-transform query plan against wrong contract) because the missing
@@ -19,15 +21,15 @@ import { CliStructuredError } from '@prisma-next/errors/control';
  * the contract it talks about (`PostgresMigration`, the Postgres control
  * adapter, the Postgres-target stack) only exists in this package.
  */
-export function errorPostgresMigrationStackMissing(): CliStructuredError {
+export function errorPostgresMigrationStackMissing(operation: string): CliStructuredError {
   return new CliStructuredError(
     '2007',
-    'PostgresMigration.dataTransform requires a control adapter',
+    `PostgresMigration.${operation} requires a control adapter`,
     {
       domain: 'MIG',
-      why: 'PostgresMigration.dataTransform was invoked on an instance constructed without a ControlStack. The stored controlAdapter is undefined, so dataTransform cannot lower its query plan.',
+      why: `PostgresMigration.${operation} was invoked on an instance constructed without a ControlStack, so the stored controlAdapter is undefined and the operation cannot lower its plan.`,
       fix: 'Construct the migration via the migration CLI entrypoint (which assembles a ControlStack from the loaded prisma-next.config.ts), or pass a ControlStack containing a Postgres adapter to the migration constructor in test fixtures.',
-      meta: {},
+      meta: { operation },
     },
   );
 }

package/src/core/migrations/bound-schema.ts

@@ -0,0 +1,10 @@
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
+
+/**
+ * Maps a planner schema name to the contract-free DDL builder's optional
+ * `schema` field: the unbound sentinel becomes `undefined` (the builder omits
+ * the schema qualifier), every other name passes through.
+ */
+export function boundSchema(schemaName: string): string | undefined {
+  return schemaName === UNBOUND_NAMESPACE_ID ? undefined : schemaName;
+}

package/src/core/migrations/column-ddl-rendering.ts

@@ -0,0 +1,117 @@
+import type { CodecControlHooks } from '@prisma-next/family-sql/control';
+import type { StorageColumn } from '@prisma-next/sql-contract/types';
+import type { DdlColumn } from '@prisma-next/sql-relational-core/ast';
+import * as contractFree from '@prisma-next/sql-relational-core/contract-free';
+import type { SqlColumnDefaultIR, SqlColumnIR } from '@prisma-next/sql-schema-ir/types';
+import { blindCast } from '@prisma-next/utils/casts';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { postgresDefaultToDdlColumnDefault } from './op-factory-call';
+import { buildColumnDefaultSql, buildColumnTypeSql } from './planner-ddl-builders';
+import { resolveIdentityValue } from './planner-identity-values';
+import { buildExpectedFormatType } from './planner-sql-checks';
+
+/**
+ * Reconstructs the `StorageColumn`-shaped fields the DDL builder functions
+ * (`buildColumnTypeSql`, `buildExpectedFormatType`, `resolveIdentityValue`)
+ * expect, from a column node's own stamped codec identity (`codecRef` /
+ * `codecBaseNativeType` / `codecNamedType`, Decision 5) — never the
+ * contract. The builders were written against `StorageColumn` and are
+ * unchanged here; only the shape feeding them moves from the contract to
+ * the node. An empty `storageTypes` catalog is passed alongside: the
+ * node's fields are already resolved past any `typeRef` indirection, so no
+ * live lookup is needed, and passing a non-empty catalog would risk a
+ * false `typeRef` hit against an unrelated storage type.
+ */
+function columnLike(
+  column: SqlColumnIR,
+): Pick<
+  StorageColumn,
+  'nativeType' | 'codecId' | 'nullable' | 'many' | 'typeParams' | 'typeRef' | 'default'
+> {
+  if (column.codecRef === undefined || column.codecBaseNativeType === undefined) {
+    throw new Error(
+      `columnLike: expected column "${column.name}" carries no codec identity — the expected tree must be derived via contractToSchemaIR for planning`,
+    );
+  }
+  return {
+    nativeType: column.codecBaseNativeType,
+    codecId: column.codecRef.codecId,
+    nullable: column.nullable,
+    // `column.many` is unset on contract-derived columns (array-ness rides
+    // on the `nativeType` `[]` suffix there instead) — `codecRef.many`
+    // carries it. Hand-built/introspected columns set `column.many` directly.
+    ...ifDefined('many', column.many ?? column.codecRef.many),
+    ...ifDefined(
+      'typeParams',
+      column.codecRef.typeParams !== undefined
+        ? blindCast<
+            Record<string, unknown>,
+            'CodecRef.typeParams is JsonValue-shaped; the DDL builders only ever read it as the Record the contract column originally carried'
+          >(column.codecRef.typeParams)
+        : undefined,
+    ),
+    ...(column.codecNamedType ? { typeRef: '<resolved>' } : {}),
+    ...ifDefined('default', column.resolvedDefault),
+  };
+}
+
+/**
+ * Builds the `CREATE TABLE` / `ADD COLUMN` DDL column for an expected column
+ * node, resolving type rendering from the node's codec identity against the
+ * codec hooks the caller holds — the same builder the pre-`plan(start, end)`
+ * op-path called, so the output is byte-identical.
+ */
+export function renderColumnDdl(
+  name: string,
+  column: SqlColumnIR,
+  codecHooks: ReadonlyMap<string, CodecControlHooks>,
+): DdlColumn {
+  const like = columnLike(column);
+  const typeSql = buildColumnTypeSql(like, codecHooks, {});
+  const ddlDefault = postgresDefaultToDdlColumnDefault(like.default);
+  return contractFree.col(name, typeSql, {
+    ...(!column.nullable ? { notNull: true } : {}),
+    ...ifDefined('default', ddlDefault),
+    ...ifDefined('codecRef', column.codecRef),
+  });
+}
+
+/**
+ * Builds the `ALTER COLUMN … TYPE` operands for an expected column node.
+ */
+export function renderColumnAlterType(
+  column: SqlColumnIR,
+  codecHooks: ReadonlyMap<string, CodecControlHooks>,
+): { readonly qualifiedTargetType: string; readonly formatTypeExpected: string } {
+  const like = columnLike(column);
+  return {
+    qualifiedTargetType: buildColumnTypeSql(like, codecHooks, {}, false),
+    formatTypeExpected: buildExpectedFormatType(like, codecHooks, {}),
+  };
+}
+
+/**
+ * Resolves the identity value (monoid neutral element) SQL literal used as
+ * the temporary default when adding a NOT-NULL column with no contract
+ * default (`notNullAddColumnCallStrategy`'s shared-temp-default backfill).
+ * `null` when the column's type has no built-in/codec-provided identity
+ * value.
+ */
+export function resolveColumnTemporaryDefault(
+  column: SqlColumnIR,
+  codecHooks: ReadonlyMap<string, CodecControlHooks>,
+): string | null {
+  return resolveIdentityValue(columnLike(column), codecHooks, {});
+}
+
+/**
+ * The column's `SET DEFAULT` clause SQL, resolved from a column-default
+ * diff node. `''` when the node carries no resolved default.
+ */
+export function renderColumnDefaultSql(defaultNode: SqlColumnDefaultIR): string {
+  if (defaultNode.resolved === undefined) return '';
+  return buildColumnDefaultSql(defaultNode.resolved, {
+    nativeType: defaultNode.nativeTypeContext ?? '',
+    ...ifDefined('many', defaultNode.many),
+  });
+}

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

@@ -0,0 +1,160 @@
+import type { ContractToSchemaIROptions } from '@prisma-next/family-sql/control';
+import { contractNamespaceToSchemaIR } from '@prisma-next/family-sql/control';
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
+import { SqlForeignKeyIR } 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 { 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 { resolveDdlSchemaForNamespaceStorage } from './resolve-ddl-schema';
+
+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,
+  });
+}
+
+/**
+ * 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;
+    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) =>
+          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: resolveDdlSchemaForNamespaceStorage(
+              contract.storage,
+              fk.referencedSchema ?? UNBOUND_NAMESPACE_ID,
+            ),
+          }),
+      );
+      tables[tableName] = new PostgresTableSchemaNode({
+        name: sqlTable.name,
+        columns: sqlTable.columns,
+        foreignKeys,
+        uniques: sqlTable.uniques,
+        indexes: sqlTable.indexes,
+        ...ifDefined('primaryKey', sqlTable.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.`,
+        );
+      }
+    }
+
+    namespaces[ddlSchema] = new PostgresNamespaceSchemaNode({
+      schemaName: ddlSchema,
+      tables,
+      nativeEnumTypeNames: [],
+    });
+
+    for (const role of Object.values(ns.role)) {
+      roles.push(new PostgresRoleSchemaNode({ name: role.name, namespaceId: role.namespaceId }));
+    }
+  }
+
+  return new PostgresDatabaseSchemaNode({
+    namespaces,
+    roles,
+    existingSchemas: ownedSchemas,
+    pgVersion: '',
+  });
+}

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

@@ -1,10 +1,17 @@
 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 { 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 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';
 
 /**
@@ -21,6 +28,8 @@ import type { PostgresOpFactoryCall } from './op-factory-call';
 const OBJECT_CREATION_FACTORIES: ReadonlySet<string> = new Set<string>([
   'createTable',
   'createSchema',
+  'createRlsPolicy',
+  'enableRowLevelSecurity',
 ]);
 
 function createsNewTopLevelObject(call: PostgresOpFactoryCall): boolean {
@@ -54,7 +63,7 @@ function resolveNamespaceIdForTable(
   return UNBOUND_NAMESPACE_ID;
 }
 
-function resolveNamespaceIdForDdlSchema(
+export function resolveNamespaceIdForDdlSchema(
   contract: Contract<SqlStorage>,
   ddlSchemaName: string,
 ): string {
@@ -141,64 +150,137 @@ 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 that describe the absence of a whole, top-level Postgres
+ * object — the same objects `createsNewTopLevelObject` recognises for calls.
+ * 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',
 });
 
-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` —
+ * creation-class per `OBJECT_CREATION_FACTORIES` ('enableRowLevelSecurity'
+ * is a member): 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.
+ * Resolve the control-policy subject coordinate for a single node-typed
+ * {@link SchemaDiffIssue}. 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 node kind + reason: a `not-found` schema/table describes
+ * 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.
+ * A `not-expected` table carries no contract namespace coordinate (the live
+ * table isn't claimed by any contract namespace), so the subject's
+ * `namespaceId` falls back to {@link UNBOUND_NAMESPACE_ID} via
+ * `resolveNamespaceIdForTable`'s own fallback — the call-side resolver does
+ * the same for the `DropTableCall` it produces.
+ *
+ * A role node resolves against the `PostgresRole` contract entity at that
+ * role's name (roles are root-level diff subjects, so the name is the
+ * second path segment after the tree root). A `not-found` role is declared,
+ * so the entity is always found and its `control` read directly — which is
+ * always {@link ROLE_DEFAULT_CONTROL_POLICY} today, since no authoring
+ * surface sets it otherwise. A `not-expected` role has no contract entity
+ * (an undeclared live role, by definition), so the subject falls back to
+ * the same default — roles are referenced but never owned, so an
+ * undeclared role gets exactly the same governance as a declared one.
+ * Never creates a new object: role provisioning is a non-goal.
  */
-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 (issue.kind === 'missing_schema' && issue.namespaceId) {
-    return { namespaceId: issue.namespaceId, createsNewObject };
+  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 ('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, {
-      namespaceId,
-      entityKind: 'table',
-      entityName: issue.table,
-    });
+  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,
-      ...ifDefined('explicitNodeControlPolicy', table?.control),
-      table: issue.table,
-      ...ifDefined('column', 'column' in issue ? issue.column : undefined),
-      createsNewObject,
+      namespaceId: UNBOUND_NAMESPACE_ID,
+      explicitNodeControlPolicy: roleEntity?.control ?? ROLE_DEFAULT_CONTROL_POLICY,
+      createsNewObject: false,
     };
   }
 
-  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,
+  });
+  const createsNewObject =
+    (node.nodeKind === PostgresSchemaNodeKind.table && issue.reason === 'not-found') ||
+    isEnablementCreationIssue(issue);
+
+  return {
+    namespaceId,
+    ...ifDefined('explicitNodeControlPolicy', table?.control),
+    table: tableName,
+    ...ifDefined('column', issueColumnName(issue)),
+    createsNewObject,
+  };
 }