@prisma-next/target-postgres 0.14.0-dev.2 → 0.14.0-dev.21

package/src/core/migrations/planner.ts

@@ -25,6 +25,10 @@ import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import { blindCast } from '@prisma-next/utils/casts';
 import { parsePostgresDefault } from '../default-normalizer';
 import { normalizeSchemaNativeType } from '../native-type-normalizer';
+import { assertPostgresRlsPolicy } from '../postgres-rls-policy';
+import { isPostgresSchema } from '../postgres-schema';
+import { isPostgresSchemaIR } from '../postgres-schema-ir';
+import { resolveDdlSchemaForNamespaceStorage } from '../postgres-schema-ir-annotations';
 import {
   formatPostgresControlPolicySubjectLabel,
   resolvePostgresCallControlPolicySubject,
@@ -33,9 +37,15 @@ import {
 } from './control-policy';
 import { planIssues } from './issue-planner';
 import type { PostgresOpFactoryCall } from './op-factory-call';
+import {
+  CreatePostgresRlsPolicyCall,
+  DropPostgresRlsPolicyCall,
+  EnableRowLevelSecurityCall,
+} from './op-factory-call';
 import { TypeScriptRenderablePostgresMigration } from './planner-produced-postgres-migration';
 import { postgresPlannerStrategies } from './planner-strategies';
 import { verifyPostgresNamespacePresence } from './verify-postgres-namespaces';
+import { diffPostgresRlsPolicies } from './verify-postgres-rls-policies';
 
 type PlannerFrameworkComponents = SqlMigrationPlannerPlanOptions extends {
   readonly frameworkComponents: infer T;
@@ -194,6 +204,44 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       return plannerFailure(result.failure);
     }
 
+    // Translate RLS diff issues to DDL calls and run through control-policy
+    // partition. This runs AFTER the structural planIssues pass so the RLS
+    // calls can refer to tables that may have been created in this plan.
+    //
+    // Fail loud when the contract declares RLS policies but the schema is
+    // contract-derived (migration plan path). Without a live-introspected
+    // PostgresSchemaIR there is no baseline to reconcile against, so
+    // silently emitting no RLS DDL would be wrong. The user must run
+    // `db update` / `db init` against a live database to emit RLS.
+    if (!isPostgresSchemaIR(options.schema)) {
+      const policyNames: string[] = [];
+      for (const ns of Object.values(options.contract.storage.namespaces)) {
+        if (isPostgresSchema(ns)) {
+          for (const [policyName, policy] of Object.entries(ns.policy)) {
+            policyNames.push(`${policy.tableName}.${policyName}`);
+          }
+        }
+      }
+      if (policyNames.length > 0) {
+        return plannerFailure([
+          {
+            kind: 'unsupportedOperation',
+            summary: `migration plan does not yet emit RLS policies (the offline contract→schema derivation cannot carry them). Author RLS via 'db update' / 'db init' against a live database. Tracked for a follow-up slice (extension migration participation seam). Affected policies: ${policyNames.join(', ')}`,
+          },
+        ]);
+      }
+    }
+    const rlsCalls = this.planRlsDiff(options);
+    const rlsPartition = partitionCallsByControlPolicy({
+      calls: rlsCalls,
+      contract: options.contract,
+      resolveControlPolicySubject: (call) =>
+        resolvePostgresCallControlPolicySubject(call, options.contract),
+      resolveFactoryName: (call) => call.factoryName,
+      formatSubjectLabel: (factoryName, subject) =>
+        formatPostgresControlPolicySubjectLabel(factoryName, subject, options.contract),
+    });
+
     // Inline `onFieldEvent`-emitted ops after structural DDL. The fixed
     // ordering is `structural → added → dropped → altered`, with
     // within-group sorting by `(tableName, fieldName)` so re-emits are
@@ -219,9 +267,10 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       formatSubjectLabel: (factoryName, subject) =>
         formatPostgresControlPolicySubjectLabel(factoryName, subject, options.contract),
     });
-    const calls = [...result.value.calls, ...fieldEventPartition.kept];
+    const calls = [...result.value.calls, ...rlsPartition.kept, ...fieldEventPartition.kept];
     const warnings: SqlPlannerConflict[] = [
       ...issuePartition.warnings,
+      ...rlsPartition.warnings,
       ...fieldEventPartition.warnings,
     ];
 
@@ -240,6 +289,54 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
     });
   }
 
+  private planRlsDiff(options: PlannerOptionsWithComponents): readonly PostgresOpFactoryCall[] {
+    if (!isPostgresSchemaIR(options.schema)) {
+      // Non-PostgresSchemaIR (migration plan path) reaches here only when the
+      // contract declares NO policies — `planSql` already returned a failure
+      // for the has-policies case. This [] is the genuine no-RLS case.
+      return [];
+    }
+    const diffIssues = diffPostgresRlsPolicies({
+      contract: options.contract,
+      schema: options.schema,
+    });
+
+    const allowsDestructive = options.policy.allowedOperationClasses.includes('destructive');
+    const calls: PostgresOpFactoryCall[] = [];
+    const seenEnableTables = new Set<string>();
+
+    for (const issue of diffIssues) {
+      const { namespaceId, entityName: policyName } = issue.coordinate;
+      const schemaForTable = resolveDdlSchemaForNamespaceStorage(
+        options.contract.storage,
+        namespaceId,
+        options.schema,
+      );
+
+      // 'mismatch' is unreachable for content-addressed policies: the wire name
+      // encodes the body hash, so two policies sharing a coordinate (same name)
+      // are always equal and isEqualTo never returns false.
+      if (issue.outcome === 'missing') {
+        assertPostgresRlsPolicy(issue.expected);
+        const tableKey = `${schemaForTable}.${issue.expected.tableName}`;
+        if (!seenEnableTables.has(tableKey)) {
+          seenEnableTables.add(tableKey);
+          calls.push(new EnableRowLevelSecurityCall(schemaForTable, issue.expected.tableName));
+        }
+        calls.push(
+          new CreatePostgresRlsPolicyCall(schemaForTable, issue.expected.tableName, issue.expected),
+        );
+      } else if (issue.outcome === 'extra' && allowsDestructive) {
+        assertPostgresRlsPolicy(issue.actual);
+        calls.push(
+          new DropPostgresRlsPolicyCall(schemaForTable, issue.actual.tableName, policyName),
+        );
+      }
+    }
+
+    return calls;
+  }
+
   private ensureAdditivePolicy(policy: MigrationOperationPolicy) {
     if (!policy.allowedOperationClasses.includes('additive')) {
       return plannerFailure([
@@ -274,6 +371,7 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
     // rather than in the family verifier. Stitch it in here so a single
     // `SchemaIssue[]` flows through `planIssues` and the planner emits
     // CREATE SCHEMA in the dep bucket before any CreateTableCall.
+    // RLS policy drift is handled separately via diffPostgresRlsPolicies → planRlsDiff.
     const namespaceIssues = verifyPostgresNamespacePresence({
       contract: options.contract,
       schema: options.schema,

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

@@ -4,6 +4,7 @@ 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 { isPostgresSchema } from '../postgres-schema';
+import { isPostgresSchemaIR } from '../postgres-schema-ir';
 
 /**
  * Resolves the live-database schema name for a given namespace
@@ -23,25 +24,21 @@ 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 a `PostgresSchemaIR`.
+ * Defaults to the always-present `public` schema when the schema IR is not a
+ * `PostgresSchemaIR` — 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 `PostgresSchemaIR`. Tests that want to assert against a
+ * richer initial state construct a `PostgresSchemaIR` 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');
+  if (isPostgresSchemaIR(schema)) {
+    return schema.existingSchemas;
   }
   return ['public'];
 }

package/src/core/migrations/verify-postgres-rls-policies.ts

@@ -0,0 +1,62 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { SchemaDiffIssue } from '@prisma-next/framework-components/control';
+import { diffNodes } 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 { isPostgresSchema } from '../postgres-schema';
+import type { PostgresSchemaIR } from '../postgres-schema-ir';
+
+// Postgres binds the late-bound (`__unbound__`) namespace to the `public`
+// schema, so an unbound contract owns `public` in the live database. Both the
+// contract slot ids and the introspected policy coordinates can carry either
+// form depending on how the schema was lowered, so normalize both sides to the
+// same id before comparing ownership.
+const POSTGRES_DEFAULT_NAMESPACE_ID = 'public';
+
+function resolveNamespaceId(namespaceId: string): string {
+  return namespaceId === UNBOUND_NAMESPACE_ID ? POSTGRES_DEFAULT_NAMESPACE_ID : namespaceId;
+}
+
+/**
+ * Computes RLS policy drift between the contract and the live DB schema using
+ * the generic {@link diffNodes} differ. Returns `SchemaDiffIssue[]` keyed by
+ * the full `EntityCoordinate` (plane + namespaceId + entityKind + entityName).
+ *
+ * Both sides supply `PostgresRlsPolicy` nodes that implement `DiffableNode`
+ * with a concrete namespace coordinate — the contract carries explicit
+ * `namespaceId` set during lowering (e.g. `'public'`); the introspected schema
+ * carries the resolved DDL schema name. The differ matches purely on coordinate
+ * identity; no namespace interpretation happens here.
+ *
+ * The diff is scoped to the namespaces the verified contract owns. The live
+ * schema introspection returns every policy across all DB schemas, but a policy
+ * in a namespace this contract does not own belongs to another contract space
+ * (or is external) and must not be reported as extra. Without this scope a space
+ * that owns only `auth`/`storage` (e.g. the supabase extension space) would flag
+ * the application space's `public.*` policies as extra during verify.
+ *
+ * Ownership is the set of namespaces the contract declares (its
+ * `storage.namespaces` slot keys), with the late-bound `__unbound__` slot
+ * resolved to the Postgres default `public` so a single-namespace contract still
+ * owns — and diffs — its `public` policies.
+ */
+export function diffPostgresRlsPolicies(input: {
+  readonly contract: Contract<SqlStorage>;
+  readonly schema: PostgresSchemaIR;
+}): readonly SchemaDiffIssue[] {
+  const { contract, schema } = input;
+
+  const ownedNamespaceIds = new Set(
+    Object.keys(contract.storage.namespaces).map(resolveNamespaceId),
+  );
+
+  const expected = Object.values(contract.storage.namespaces).flatMap((ns) =>
+    isPostgresSchema(ns) ? Object.values(ns.policy) : [],
+  );
+
+  const actual = schema.rlsPolicies.filter((policy) =>
+    ownedNamespaceIds.has(resolveNamespaceId(policy.namespaceId)),
+  );
+
+  return diffNodes(expected, actual);
+}

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

@@ -10,15 +10,15 @@ import {
   isAuthoringEntityTypeDescriptor,
 } from '@prisma-next/framework-components/authoring';
 import {
+  type AnyEntityKindDescriptor,
   type Namespace,
-  NamespaceBase,
   UNBOUND_NAMESPACE_ID,
 } from '@prisma-next/framework-components/ir';
-import type { SqlNamespaceTablesInput, SqlStorage } from '@prisma-next/sql-contract/types';
+import type { SqlNamespaceInput, SqlStorage } from '@prisma-next/sql-contract/types';
 import { blindCast } from '@prisma-next/utils/casts';
-import type { JsonObject } from '@prisma-next/utils/json';
+import type { JsonObject, JsonValue } from '@prisma-next/utils/json';
 import { postgresAuthoringEntityTypes } from './authoring';
-import { postgresTargetDescriptorMeta } from './descriptor-meta';
+import { policyEntityKind, roleEntityKind } from './entity-kinds';
 import { isPostgresSchema, PostgresSchema } from './postgres-schema';
 
 const POSTGRES_AUTHORING_CTX: AuthoringEntityContext = {
@@ -32,7 +32,8 @@ function isAuthoringEntityTypeFactoryOutput(
   return (
     typeof output === 'object' &&
     output !== null &&
-    typeof (output as AuthoringEntityTypeFactoryOutput).factory === 'function'
+    'factory' in output &&
+    typeof output.factory === 'function'
   );
 }
 
@@ -65,34 +66,29 @@ function collectStorageTypesHydrators(
 }
 
 export class PostgresContractSerializer extends SqlContractSerializerBase<Contract<SqlStorage>> {
-  constructor() {
+  constructor(extraPackEntityKinds: readonly AnyEntityKindDescriptor[] = []) {
     const storageTypesHydrators = collectStorageTypesHydrators(postgresAuthoringEntityTypes);
-    super(storageTypesHydrators);
-  }
-
-  protected override get defaultNamespaceId(): string {
-    return postgresTargetDescriptorMeta.defaultNamespaceId;
+    super(storageTypesHydrators, [policyEntityKind, roleEntityKind, ...extraPackEntityKinds]);
   }
 
   protected override hydrateSqlNamespaceEntry(
     nsId: string,
-    raw: Namespace | Record<string, unknown>,
-  ): Namespace | SqlNamespaceTablesInput {
-    if (raw instanceof NamespaceBase) {
-      return raw;
-    }
+    raw: Record<string, unknown>,
+  ): Namespace | SqlNamespaceInput {
     const hydrated = blindCast<
-      SqlNamespaceTablesInput,
-      'super.hydrateSqlNamespaceEntry returns SqlNamespaceTablesInput when raw is not a NamespaceBase'
+      SqlNamespaceInput,
+      'raw is always plain JSON, so super.hydrateSqlNamespaceEntry returns SqlNamespaceInput'
     >(super.hydrateSqlNamespaceEntry(nsId, raw));
     const { id, entries } = hydrated;
 
-    const valueSetSlot = entries['valueSet'];
-    const hasValueSets = valueSetSlot !== undefined && Object.keys(valueSetSlot).length > 0;
-    const emptyTables = Object.keys(entries['table'] ?? {}).length === 0;
-    if (id === UNBOUND_NAMESPACE_ID && emptyTables && !hasValueSets) {
+    const allSlotsEmpty = Object.values(entries).every(
+      (slot) => slot === undefined || Object.keys(slot).length === 0,
+    );
+    if (id === UNBOUND_NAMESPACE_ID && allSlotsEmpty) {
       return PostgresSchema.unbound;
     }
+    const valueSetSlot = entries['valueSet'];
+    const hasValueSets = valueSetSlot !== undefined && Object.keys(valueSetSlot).length > 0;
     return new PostgresSchema({
       id,
       entries: {
@@ -118,7 +114,7 @@ export class PostgresContractSerializer extends SqlContractSerializerBase<Contra
             table: Object.fromEntries(
               Object.entries(ns.entries.table ?? {}).map(([tableName, table]) => [
                 tableName,
-                this.serializeJsonValue(table) as JsonObject,
+                this.serializeJsonObject(table),
               ]),
             ),
           },
@@ -132,42 +128,61 @@ export class PostgresContractSerializer extends SqlContractSerializerBase<Contra
     if (storage.types !== undefined) {
       const typesOut: Record<string, JsonObject> = {};
       for (const [name, entry] of Object.entries(storage.types)) {
-        typesOut[name] = this.serializeJsonValue(entry) as JsonObject;
+        typesOut[name] = this.serializeJsonObject(entry);
       }
       storageOut['types'] = typesOut;
     }
-    return {
+    return blindCast<
+      JsonObject,
+      'contract minus storage plus a JSON-shaped storageOut is a JsonObject'
+    >({
       ...rest,
       storage: storageOut,
-    } as unknown as JsonObject;
+    });
   }
 
   private serializePostgresNamespace(ns: PostgresSchema, isUnboundSlot: boolean): JsonObject {
     const tablesOut: Record<string, JsonObject> = {};
     for (const [tableName, table] of Object.entries(ns.table)) {
-      tablesOut[tableName] = this.serializeJsonValue(table) as JsonObject;
+      tablesOut[tableName] = this.serializeJsonObject(table);
     }
     const valueSetEntries = ns.valueSet;
     const valueSetOut: Record<string, JsonObject> = {};
     if (valueSetEntries !== undefined) {
       for (const [valueSetName, valueSet] of Object.entries(valueSetEntries)) {
-        valueSetOut[valueSetName] = blindCast<
-          JsonObject,
-          'serializeJsonValue round-trips the value-set node through JSON, yielding a JsonObject'
-        >(this.serializeJsonValue(valueSet));
+        valueSetOut[valueSetName] = this.serializeJsonObject(valueSet);
       }
     }
+    const roleOut: Record<string, JsonObject> = {};
+    for (const [roleName, role] of Object.entries(ns.role)) {
+      roleOut[roleName] = this.serializeJsonObject(role);
+    }
+    const policyOut: Record<string, JsonObject> = {};
+    for (const [policyName, policy] of Object.entries(ns.policy)) {
+      policyOut[policyName] = this.serializeJsonObject(policy);
+    }
     return {
       id: ns.id,
       kind: isUnboundSlot ? 'postgres-unbound-schema' : 'postgres-schema',
       entries: {
         table: tablesOut,
         ...(Object.keys(valueSetOut).length > 0 ? { valueSet: valueSetOut } : {}),
+        ...(Object.keys(roleOut).length > 0 ? { role: roleOut } : {}),
+        ...(Object.keys(policyOut).length > 0 ? { policy: policyOut } : {}),
       },
     };
   }
 
-  private serializeJsonValue(value: unknown): unknown {
-    return JSON.parse(JSON.stringify(value)) as unknown;
+  private serializeJsonObject(value: unknown): JsonObject {
+    return blindCast<
+      JsonObject,
+      'serializeJsonValue round-trips an IR node through JSON, yielding a JsonObject'
+    >(this.serializeJsonValue(value));
+  }
+
+  private serializeJsonValue(value: unknown): JsonValue {
+    return blindCast<JsonValue, 'JSON.parse(JSON.stringify(x)) yields a JsonValue'>(
+      JSON.parse(JSON.stringify(value)),
+    );
   }
 }

package/src/core/postgres-rls-policy.ts

@@ -0,0 +1,103 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+import type { EntityCoordinate } from '@prisma-next/framework-components/ir';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { SqlNode } from '@prisma-next/sql-contract/types';
+
+export type RlsPolicyOperation = 'select' | 'insert' | 'update' | 'delete' | 'all';
+
+export interface PostgresRlsPolicyInput {
+  /** Full wire name: `<prefix>_<8hex>`. Stored as-is; hashing is not this class's job. */
+  readonly name: string;
+  /** User-supplied prefix (the part before the `_<8hex>` suffix). */
+  readonly prefix: string;
+  /** Name of the table this policy attaches to, by name within the same schema. */
+  readonly tableName: string;
+  /** Namespace coordinate (schema name). Policies are schema-scoped. */
+  readonly namespaceId: string;
+  readonly operation: RlsPolicyOperation;
+  /** Sorted role names rendered in `TO <roles>`. Plain strings in this slice. */
+  readonly roles: readonly string[];
+  /** USING predicate SQL string, if present. */
+  readonly using?: string;
+  /** WITH CHECK predicate SQL string, if present. */
+  readonly withCheck?: string;
+  /** `true` = `AS PERMISSIVE`, `false` = `AS RESTRICTIVE`. */
+  readonly permissive: boolean;
+}
+
+/**
+ * Postgres IR class for a row-level security policy (`CREATE POLICY … ON …`).
+ *
+ * Target-only concept — no SQL-family abstract. Extends `SqlNode` directly.
+ * Frozen at construction via `freezeNode(this)`. The `kind: 'policy'`
+ * discriminant is enumerable (overrides SqlNode's non-enumerable `'sql'`) so it
+ * survives JSON serialization and enables dispatch. The literal matches the
+ * entries key (one-string rule: node.kind === entries key === entity kind).
+ */
+export class PostgresRlsPolicy extends SqlNode implements DiffableNode {
+  override readonly kind = 'policy' as const;
+  readonly name: string;
+  readonly prefix: string;
+  readonly tableName: string;
+  readonly namespaceId: string;
+  readonly operation: RlsPolicyOperation;
+  readonly roles: readonly string[];
+  declare readonly using?: string;
+  declare readonly withCheck?: string;
+  readonly permissive: boolean;
+
+  constructor(input: PostgresRlsPolicyInput) {
+    super();
+    this.name = input.name;
+    this.prefix = input.prefix;
+    this.tableName = input.tableName;
+    this.namespaceId = input.namespaceId;
+    this.operation = input.operation;
+    this.roles = Object.freeze([...input.roles]);
+    if (input.using !== undefined) this.using = input.using;
+    if (input.withCheck !== undefined) this.withCheck = input.withCheck;
+    this.permissive = input.permissive;
+    freezeNode(this);
+  }
+
+  identity(): EntityCoordinate {
+    return {
+      plane: 'storage',
+      namespaceId: this.namespaceId,
+      entityKind: 'policy',
+      entityName: this.name,
+    };
+  }
+
+  /**
+   * Equality by wire name only. The wire name is `<prefix>_<sha256(body)[0..8]>`,
+   * so name-equality IS body-equality — two policies with different bodies
+   * have different hashes and therefore different names. We deliberately
+   * skip comparing bodies directly because Postgres reprints predicate
+   * expressions (e.g. strips outer parentheses), so a byte-compare against
+   * the authored body would produce false mismatches on a clean re-verify.
+   */
+  isEqualTo(other: DiffableNode): boolean {
+    if (!isPostgresRlsPolicy(other)) {
+      throw new Error(
+        `PostgresRlsPolicy.isEqualTo: expected a PostgresRlsPolicy, got ${other.identity().entityKind}`,
+      );
+    }
+    return this.name === other.name;
+  }
+}
+
+export function isPostgresRlsPolicy(node: DiffableNode | undefined): node is PostgresRlsPolicy {
+  return node !== undefined && 'kind' in node && node.kind === 'policy';
+}
+
+export function assertPostgresRlsPolicy(
+  node: DiffableNode | undefined,
+): asserts node is PostgresRlsPolicy {
+  if (!isPostgresRlsPolicy(node)) {
+    const kind = node !== undefined && 'kind' in node ? String(node.kind) : typeof node;
+    throw new Error(
+      `planRlsDiff: expected a PostgresRlsPolicy on the policy-diff path but got ${kind}`,
+    );
+  }
+}

package/src/core/postgres-role.ts

@@ -0,0 +1,53 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+import type { EntityCoordinate } from '@prisma-next/framework-components/ir';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { SqlNode } from '@prisma-next/sql-contract/types';
+
+export interface PostgresRoleInput {
+  readonly name: string;
+  /**
+   * Namespace coordinate. Roles are cluster-scoped; pass `UNBOUND_NAMESPACE_ID`
+   * from `@prisma-next/framework-components/ir`.
+   */
+  readonly namespaceId: string;
+}
+
+/**
+ * Postgres IR class for a database role (`CREATE ROLE …`).
+ *
+ * Roles are cluster-scoped, so their namespace coordinate is always
+ * `UNBOUND_NAMESPACE_ID`. Target-only concept — no SQL-family abstract.
+ * Extends `SqlNode` directly, frozen at construction via `freezeNode(this)`.
+ * The `kind: 'role'` discriminant is enumerable so it survives JSON.
+ * Matches the entries key (one-string rule).
+ */
+export class PostgresRole extends SqlNode implements DiffableNode {
+  override readonly kind = 'role' as const;
+  readonly name: string;
+  readonly namespaceId: string;
+
+  constructor(input: PostgresRoleInput) {
+    super();
+    this.name = input.name;
+    this.namespaceId = input.namespaceId;
+    freezeNode(this);
+  }
+
+  identity(): EntityCoordinate {
+    return {
+      plane: 'storage',
+      namespaceId: this.namespaceId,
+      entityKind: 'role',
+      entityName: this.name,
+    };
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    if (!(other instanceof PostgresRole)) {
+      throw new Error(
+        `PostgresRole.isEqualTo: expected a PostgresRole, got ${other.identity().entityKind}`,
+      );
+    }
+    return this.name === other.name;
+  }
+}

package/src/core/postgres-schema-ir-annotations.ts

@@ -0,0 +1,22 @@
+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 { isPostgresSchema } from './postgres-schema';
+import { isPostgresSchemaIR } from './postgres-schema-ir';
+
+export function resolveDdlSchemaForNamespaceStorage(
+  storage: SqlStorage,
+  namespaceId: string,
+  schemaIr?: SqlSchemaIR,
+): string {
+  if (namespaceId === UNBOUND_NAMESPACE_ID) {
+    return (
+      (schemaIr && isPostgresSchemaIR(schemaIr) ? schemaIr.pgSchemaName : undefined) ?? 'public'
+    );
+  }
+  const namespace = storage.namespaces[namespaceId];
+  if (namespace && isPostgresSchema(namespace)) {
+    return namespace.ddlSchemaName(storage);
+  }
+  return namespaceId;
+}