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

package/src/core/psl-infer/postgres-default-mapping.ts

@@ -0,0 +1,16 @@
+import type { DefaultMappingOptions } from '@prisma-next/family-sql/psl-infer';
+
+const POSTGRES_FUNCTION_ATTRIBUTES: Readonly<Record<string, string>> = {
+  'gen_random_uuid()': '@default(dbgenerated("gen_random_uuid()"))',
+};
+
+function formatDbGeneratedAttribute(expression: string): string {
+  return `@default(dbgenerated(${JSON.stringify(expression)}))`;
+}
+
+export function createPostgresDefaultMapping(): DefaultMappingOptions {
+  return {
+    functionAttributes: POSTGRES_FUNCTION_ATTRIBUTES,
+    fallbackFunctionAttribute: formatDbGeneratedAttribute,
+  };
+}

package/src/core/psl-infer/postgres-type-map.ts

@@ -0,0 +1,128 @@
+import type {
+  PslNativeTypeAttribute,
+  PslTypeMap,
+  PslTypeResolution,
+} from '@prisma-next/family-sql/psl-infer';
+
+const POSTGRES_TO_PSL: Record<string, string> = {
+  text: 'String',
+  bool: 'Boolean',
+  boolean: 'Boolean',
+  int4: 'Int',
+  integer: 'Int',
+  int8: 'BigInt',
+  bigint: 'BigInt',
+  float8: 'Float',
+  'double precision': 'Float',
+  numeric: 'Decimal',
+  decimal: 'Decimal',
+  timestamptz: 'DateTime',
+  'timestamp with time zone': 'DateTime',
+  jsonb: 'Json',
+  bytea: 'Bytes',
+};
+
+const PRESERVED_NATIVE_TYPES: Record<
+  string,
+  { readonly pslType: string; readonly attributeName: string }
+> = {
+  'character varying': { pslType: 'String', attributeName: 'db.VarChar' },
+  character: { pslType: 'String', attributeName: 'db.Char' },
+  char: { pslType: 'String', attributeName: 'db.Char' },
+  varchar: { pslType: 'String', attributeName: 'db.VarChar' },
+  uuid: { pslType: 'String', attributeName: 'db.Uuid' },
+  int2: { pslType: 'Int', attributeName: 'db.SmallInt' },
+  smallint: { pslType: 'Int', attributeName: 'db.SmallInt' },
+  float4: { pslType: 'Float', attributeName: 'db.Real' },
+  real: { pslType: 'Float', attributeName: 'db.Real' },
+  timestamp: { pslType: 'DateTime', attributeName: 'db.Timestamp' },
+  'timestamp without time zone': { pslType: 'DateTime', attributeName: 'db.Timestamp' },
+  date: { pslType: 'DateTime', attributeName: 'db.Date' },
+  time: { pslType: 'DateTime', attributeName: 'db.Time' },
+  'time without time zone': { pslType: 'DateTime', attributeName: 'db.Time' },
+  timetz: { pslType: 'DateTime', attributeName: 'db.Timetz' },
+  'time with time zone': { pslType: 'DateTime', attributeName: 'db.Timetz' },
+  json: { pslType: 'Json', attributeName: 'db.Json' },
+};
+
+const PARAMETERIZED_NATIVE_TYPES: Record<
+  string,
+  { readonly pslType: string; readonly attributeName: string }
+> = {
+  'character varying': { pslType: 'String', attributeName: 'db.VarChar' },
+  character: { pslType: 'String', attributeName: 'db.Char' },
+  char: { pslType: 'String', attributeName: 'db.Char' },
+  varchar: { pslType: 'String', attributeName: 'db.VarChar' },
+  numeric: { pslType: 'Decimal', attributeName: 'db.Numeric' },
+  timestamp: { pslType: 'DateTime', attributeName: 'db.Timestamp' },
+  timestamptz: { pslType: 'DateTime', attributeName: 'db.Timestamptz' },
+  time: { pslType: 'DateTime', attributeName: 'db.Time' },
+  timetz: { pslType: 'DateTime', attributeName: 'db.Timetz' },
+};
+
+const PARAMETERIZED_TYPE_PATTERN = /^(.+?)\((.+)\)$/;
+
+function getOwnMappingValue(map: Record<string, string>, key: string): string | undefined {
+  return Object.hasOwn(map, key) ? map[key] : undefined;
+}
+
+function getOwnRecordValue<T>(map: Record<string, T>, key: string): T | undefined {
+  return Object.hasOwn(map, key) ? map[key] : undefined;
+}
+
+function createNativeTypeAttribute(name: string, args?: readonly string[]): PslNativeTypeAttribute {
+  return args && args.length > 0 ? { name, args } : { name };
+}
+
+function splitTypeParameterList(params: string): readonly string[] {
+  return params
+    .split(',')
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}
+
+export function createPostgresTypeMap(enumTypeNames?: ReadonlySet<string>): PslTypeMap {
+  return {
+    resolve(nativeType: string): PslTypeResolution {
+      if (enumTypeNames?.has(nativeType)) {
+        return { pslType: nativeType, nativeType };
+      }
+
+      const paramMatch = nativeType.match(PARAMETERIZED_TYPE_PATTERN);
+      if (paramMatch) {
+        const [, baseType = nativeType, params = ''] = paramMatch;
+        const template = getOwnRecordValue(PARAMETERIZED_NATIVE_TYPES, baseType);
+        if (template) {
+          return {
+            pslType: template.pslType,
+            nativeType,
+            typeParams: { baseType, params },
+            nativeTypeAttribute: createNativeTypeAttribute(
+              template.attributeName,
+              splitTypeParameterList(params),
+            ),
+          };
+        }
+      }
+
+      const preservedType = getOwnRecordValue(PRESERVED_NATIVE_TYPES, nativeType);
+      if (preservedType) {
+        return {
+          pslType: preservedType.pslType,
+          nativeType,
+          nativeTypeAttribute: createNativeTypeAttribute(preservedType.attributeName),
+        };
+      }
+
+      const pslType = getOwnMappingValue(POSTGRES_TO_PSL, nativeType);
+      if (pslType) {
+        return {
+          pslType,
+          nativeType,
+        };
+      }
+
+      return { unsupported: true, nativeType };
+    },
+  };
+}

package/src/core/rls/canonicalize.ts

@@ -0,0 +1,48 @@
+import { createHash } from 'node:crypto';
+
+export type RlsPolicyOperation = 'select' | 'insert' | 'update' | 'delete' | 'all';
+
+export interface ContentHashParts {
+  readonly using?: string;
+  readonly withCheck?: string;
+  readonly roles: readonly string[];
+  readonly operation: RlsPolicyOperation;
+  readonly permissive: boolean;
+}
+
+/**
+ * Stabilizes an authored predicate for hashing: trim, and collapse runs of
+ * internal whitespace to a single space.
+ *
+ * This is deliberately minimal. The content hash is the equivalence relation
+ * for a policy, and the wire name (prefix + hash) is the only thing ever
+ * compared — we never recompute the hash from an introspected policy body, so
+ * there is no need to match Postgres's reprinted form. Minimal normalization
+ * also protects the no-collision property: aggressive rewriting (lowercasing,
+ * paren-stripping, cast-alias folding) risks collapsing two distinct predicates
+ * onto one hash. Out-of-band alteration of a hashed policy is unsupported.
+ *
+ * The normalizer is a stability commitment: any change re-suffixes all wire names.
+ */
+export function normalizePredicate(sql: string): string {
+  return sql.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Returns the first 8 lowercase hex characters of the SHA-256 digest over the
+ * canonical content tuple for an RLS policy:
+ *
+ *   [normalize(using), normalize(withCheck), sortedRoles, operation, permissive]
+ *
+ * Schema and table are excluded (they are orthogonal to policy equivalence).
+ * Uses `JSON.stringify` for a deterministic encoding.
+ */
+export function computeContentHash(parts: ContentHashParts): string {
+  const using = normalizePredicate(parts.using ?? '');
+  const withCheck = normalizePredicate(parts.withCheck ?? '');
+  const roles = [...new Set(parts.roles)].sort();
+  const permissive = parts.permissive ? 'permissive' : 'restrictive';
+
+  const tuple = JSON.stringify([using, withCheck, roles, parts.operation, permissive]);
+  return createHash('sha256').update(tuple).digest('hex').slice(0, 8);
+}

package/src/core/rls/wire-name.ts

@@ -0,0 +1,33 @@
+export interface RlsPolicyWireName {
+  /** The user-supplied part before the `_<8hex>` suffix. */
+  readonly prefix: string;
+  /** The 8-lowercase-hex content-hash suffix. */
+  readonly hash: string;
+}
+
+const WIRE_NAME_PATTERN = /^(.+)_([0-9a-f]{8})$/;
+
+/**
+ * Assembles an RLS policy wire name from its user-supplied prefix and its
+ * 8-hex content-hash suffix. This module owns the `<prefix>_<hash>` format
+ * on both sides — construction here and parsing in
+ * {@link parseRlsPolicyWireName} — so the two never drift.
+ */
+export function formatRlsPolicyWireName(prefix: string, hash: string): string {
+  return `${prefix}_${hash}`;
+}
+
+/**
+ * Splits an RLS policy wire name (`<prefix>_<8hex>`) into its prefix and
+ * content-hash suffix. Returns `undefined` when the name does not follow the
+ * wire-name shape (e.g. a policy created outside the toolchain) — callers
+ * treat such names as all-prefix. Consumed by introspection (prefix
+ * extraction) and by rename pairing (same hash, different prefix).
+ */
+export function parseRlsPolicyWireName(name: string): RlsPolicyWireName | undefined {
+  const match = WIRE_NAME_PATTERN.exec(name);
+  const prefix = match?.[1];
+  const hash = match?.[2];
+  if (prefix === undefined || hash === undefined) return undefined;
+  return { prefix, hash };
+}

package/src/core/schema-ir/node-storage-coordinate.ts

@@ -0,0 +1,26 @@
+import type { EntityCoordinate } from '@prisma-next/framework-components/ir';
+import type { SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import { PostgresNativeEnumSchemaNode } from './postgres-native-enum-schema-node';
+import { PostgresTableSchemaNode } from './postgres-table-schema-node';
+import { postgresNodeEntityKind } from './schema-node-kinds';
+
+/**
+ * The storage-`entries` coordinate `(entityKind, entityName)` a Postgres diff
+ * node addresses — a table by its name, a native enum by its physical type
+ * name. `undefined` for a node that is not a whole storage entity (a namespace,
+ * a column, a policy). Lets ownership/subject resolution treat every entity kind
+ * uniformly, the node self-describing its storage identity.
+ */
+export function postgresNodeStorageCoordinate(
+  node: SqlSchemaIRNode,
+): Pick<EntityCoordinate, 'entityKind' | 'entityName'> | undefined {
+  if (PostgresTableSchemaNode.is(node)) {
+    const entityKind = postgresNodeEntityKind(node.nodeKind);
+    return entityKind === undefined ? undefined : { entityKind, entityName: node.name };
+  }
+  if (PostgresNativeEnumSchemaNode.is(node)) {
+    const entityKind = postgresNodeEntityKind(node.nodeKind);
+    return entityKind === undefined ? undefined : { entityKind, entityName: node.typeName };
+  }
+  return undefined;
+}

package/src/core/schema-ir/postgres-database-schema-node.ts

@@ -0,0 +1,61 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { assertNode, SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import type { PostgresNamespaceSchemaNode } from './postgres-namespace-schema-node';
+import type { PostgresRoleSchemaNode } from './postgres-role-schema-node';
+import { PostgresSchemaNodeKind } from './schema-node-kinds';
+
+export interface PostgresDatabaseSchemaNodeInput {
+  readonly namespaces: Readonly<Record<string, PostgresNamespaceSchemaNode>>;
+  readonly roles: readonly PostgresRoleSchemaNode[];
+  readonly existingSchemas: readonly string[];
+  readonly pgVersion: string;
+}
+
+/**
+ * The root of the Postgres schema-diff tree: one node per database.
+ *
+ * `id` is the fixed sentinel `'database'` — the root has no siblings and
+ * the value is never emitted into migration paths. `isEqualTo` is identity
+ * (roots always share the `'database'` id). `children()` yields the namespace
+ * nodes followed by the role nodes — both are root-level diff subjects. The
+ * differ pairs siblings by `(nodeKind, id)`, so a role and a namespace may
+ * share a name without colliding.
+ */
+export class PostgresDatabaseSchemaNode extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = PostgresSchemaNodeKind.database;
+
+  readonly namespaces: Readonly<Record<string, PostgresNamespaceSchemaNode>>;
+  readonly roles: readonly PostgresRoleSchemaNode[];
+  readonly existingSchemas: readonly string[];
+  readonly pgVersion: string;
+
+  constructor(input: PostgresDatabaseSchemaNodeInput) {
+    super();
+    this.namespaces = Object.freeze({ ...input.namespaces });
+    this.roles = Object.freeze([...input.roles]);
+    this.existingSchemas = Object.freeze([...input.existingSchemas]);
+    this.pgVersion = input.pgVersion;
+    freezeNode(this);
+  }
+
+  get id(): string {
+    return 'database';
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    return this.id === other.id;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [...Object.values(this.namespaces), ...this.roles];
+  }
+
+  static is(node: SqlSchemaIRNode): node is PostgresDatabaseSchemaNode {
+    return node.nodeKind === PostgresSchemaNodeKind.database;
+  }
+
+  static assert(node: SqlSchemaIRNode): asserts node is PostgresDatabaseSchemaNode {
+    assertNode(node, 'PostgresDatabaseSchemaNode', PostgresDatabaseSchemaNode.is);
+  }
+}

package/src/core/schema-ir/postgres-namespace-schema-node.ts

@@ -0,0 +1,70 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { assertNode, SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import type { PostgresNativeEnumSchemaNode } from './postgres-native-enum-schema-node';
+import type { PostgresTableSchemaNode } from './postgres-table-schema-node';
+import { PostgresSchemaNodeKind } from './schema-node-kinds';
+
+export interface PostgresNamespaceSchemaNodeInput {
+  readonly schemaName: string;
+  readonly tables: Readonly<Record<string, PostgresTableSchemaNode>>;
+  /**
+   * The native-enum diff nodes belonging to this namespace, member values in
+   * `pg_enum.enumsortorder` (declaration) order. The expected
+   * (contract-projected) side attaches each node's `control` (the contract
+   * entity's grade); introspection builds nodes with no `control`.
+   */
+  readonly nativeEnums?: readonly PostgresNativeEnumSchemaNode[];
+}
+
+/**
+ * One-per-Postgres-schema diff-tree node. Groups the tables belonging to a
+ * single namespace. Per-schema consumers (the relational planner,
+ * toSchemaView) read this node's `tables` field structurally via
+ * `blindCast`/`SqlSchemaIRNode` — not through a static `SqlSchemaIR`
+ * assignment — because `nodeKind` carries this node's own literal
+ * (`postgres-namespace`), distinct from `SqlSchemaIR`'s own (`sql-schema`).
+ *
+ * `id` is the schema name; `isEqualTo` is identity on it; `children()` returns
+ * the table nodes plus `nativeEnums`.
+ *
+ * `nativeEnums` is the diff-tree representation of native enum types the
+ * differ pairs — the sole enum carrier, built directly by both sides: the
+ * expected (contract-projected) side and introspection alike hand in
+ * `PostgresNativeEnumSchemaNode`s.
+ */
+export class PostgresNamespaceSchemaNode extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = PostgresSchemaNodeKind.namespace;
+
+  readonly schemaName: string;
+  readonly tables: Readonly<Record<string, PostgresTableSchemaNode>>;
+  readonly nativeEnums: readonly PostgresNativeEnumSchemaNode[];
+
+  constructor(input: PostgresNamespaceSchemaNodeInput) {
+    super();
+    this.schemaName = input.schemaName;
+    this.tables = Object.freeze({ ...input.tables });
+    this.nativeEnums = Object.freeze([...(input.nativeEnums ?? [])]);
+    freezeNode(this);
+  }
+
+  get id(): string {
+    return this.schemaName;
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    return this.id === other.id;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [...Object.values(this.tables), ...this.nativeEnums];
+  }
+
+  static is(node: SqlSchemaIRNode): node is PostgresNamespaceSchemaNode {
+    return node.nodeKind === PostgresSchemaNodeKind.namespace;
+  }
+
+  static assert(node: SqlSchemaIRNode): asserts node is PostgresNamespaceSchemaNode {
+    assertNode(node, 'PostgresNamespaceSchemaNode', PostgresNamespaceSchemaNode.is);
+  }
+}

package/src/core/schema-ir/postgres-native-enum-schema-node.ts

@@ -0,0 +1,83 @@
+import type { ControlPolicy } from '@prisma-next/contract/types';
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { assertNode, SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import { blindCast } from '@prisma-next/utils/casts';
+import { PostgresSchemaNodeKind } from './schema-node-kinds';
+
+export interface PostgresNativeEnumSchemaNodeInput {
+  /** The Postgres type name (`CREATE TYPE <typeName> AS ENUM (…)`). */
+  readonly typeName: string;
+  /** The owning DDL schema name — enum types are schema-scoped. */
+  readonly namespaceId: string;
+  /** Member values in declaration (`pg_enum.enumsortorder`) order. */
+  readonly members: readonly string[];
+  /** The contract entity's control grade — expected-side nodes only. */
+  readonly control?: ControlPolicy;
+}
+
+/**
+ * Schema-diff leaf node for a native Postgres enum type.
+ *
+ * This is a derived, transient node walked by the differ — it is NEVER
+ * serialized. Both sides derive it on the namespace node: the expected side
+ * from the contract's hydrated `entries.native_enum` entities, the actual
+ * side from the adapter's introspected `nativeEnums`.
+ *
+ * Enum types are schema-scoped, so identity is (namespace, type name): the
+ * namespace coordinate comes from tree position (the differ pairs enum nodes
+ * only inside an already-paired namespace) and `id` carries the type name,
+ * prefixed with the entries-kind vocabulary (`native_enum:<typeName>`) so it
+ * cannot collide with a sibling table of the same name — the same
+ * sibling-prefix convention relational column nodes use (`column:<name>`).
+ *
+ * `isEqualTo` compares members POSITIONALLY — `['a','b'] ≠ ['b','a']` —
+ * because Postgres enum sort order is semantic. `control` is contract
+ * metadata, not database state, and does not participate in equality.
+ */
+export class PostgresNativeEnumSchemaNode extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = PostgresSchemaNodeKind.nativeEnum;
+
+  readonly typeName: string;
+  readonly namespaceId: string;
+  readonly members: readonly string[];
+  declare readonly control?: ControlPolicy;
+
+  constructor(input: PostgresNativeEnumSchemaNodeInput) {
+    super();
+    this.typeName = input.typeName;
+    this.namespaceId = input.namespaceId;
+    this.members = Object.freeze([...input.members]);
+    if (input.control !== undefined) this.control = input.control;
+    freezeNode(this);
+  }
+
+  get id(): string {
+    return `native_enum:${this.typeName}`;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [];
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    const node = blindCast<
+      SqlSchemaIRNode,
+      'every diff-tree node the differ pairs is a SqlSchemaIRNode; the guard rejects non-enum kinds'
+    >(other);
+    PostgresNativeEnumSchemaNode.assert(node);
+    return (
+      this.typeName === node.typeName &&
+      this.members.length === node.members.length &&
+      this.members.every((member, index) => member === node.members[index])
+    );
+  }
+
+  static is(node: SqlSchemaIRNode): node is PostgresNativeEnumSchemaNode {
+    return node.nodeKind === PostgresSchemaNodeKind.nativeEnum;
+  }
+
+  static assert(node: SqlSchemaIRNode): asserts node is PostgresNativeEnumSchemaNode {
+    assertNode(node, 'PostgresNativeEnumSchemaNode', PostgresNativeEnumSchemaNode.is);
+  }
+}

package/src/core/schema-ir/postgres-policy-schema-node.ts

@@ -0,0 +1,90 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { assertNode, SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import { blindCast } from '@prisma-next/utils/casts';
+import type { RlsPolicyOperation } from '../postgres-rls-policy';
+import { PostgresSchemaNodeKind } from './schema-node-kinds';
+
+export interface PostgresPolicySchemaNodeInput {
+  /** Full wire name: `<prefix>_<8hex>`. */
+  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). */
+  readonly namespaceId: string;
+  readonly operation: RlsPolicyOperation;
+  /** Sorted role names rendered in `TO <roles>`. */
+  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;
+}
+
+/**
+ * Schema-diff leaf node for a Postgres row-level security policy.
+ *
+ * This is a derived, transient node walked by the differ — it is NEVER serialized.
+ * Built by project-from-contract and project-from-database from their respective
+ * `PostgresRlsPolicy` contract entities / introspected rows.
+ *
+ * `id` is the wire name (`<prefix>_<sha256(body)[0..8]>`), so name-equality is
+ * body-equality. `isEqualTo` compares names only — never byte-compare predicate
+ * bodies, because Postgres reprints them.
+ */
+export class PostgresPolicySchemaNode extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = PostgresSchemaNodeKind.policy;
+
+  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: PostgresPolicySchemaNodeInput) {
+    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);
+  }
+
+  get id(): string {
+    return this.name;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [];
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    const node = blindCast<
+      SqlSchemaIRNode,
+      'every diff-tree node the differ pairs is a SqlSchemaIRNode; the guard rejects non-policy kinds'
+    >(other);
+    PostgresPolicySchemaNode.assert(node);
+    return this.id === node.id;
+  }
+
+  static is(node: SqlSchemaIRNode): node is PostgresPolicySchemaNode {
+    return node.nodeKind === PostgresSchemaNodeKind.policy;
+  }
+
+  static assert(node: SqlSchemaIRNode | undefined): asserts node is PostgresPolicySchemaNode {
+    assertNode(node, 'PostgresPolicySchemaNode', PostgresPolicySchemaNode.is);
+  }
+}

package/src/core/schema-ir/postgres-role-schema-node.ts

@@ -0,0 +1,65 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { assertNode, SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import { blindCast } from '@prisma-next/utils/casts';
+import { PostgresSchemaNodeKind } from './schema-node-kinds';
+
+export interface PostgresRoleSchemaNodeInput {
+  readonly name: string;
+  /**
+   * Namespace coordinate. Roles are cluster-scoped; callers pass
+   * `UNBOUND_NAMESPACE_ID` from `@prisma-next/framework-components/ir`.
+   */
+  readonly namespaceId: string;
+}
+
+/**
+ * Schema-diff leaf node for a Postgres database role.
+ *
+ * This is a derived, transient node walked by the differ — it is NEVER serialized.
+ * Built by project-from-contract and project-from-database from their respective
+ * `PostgresRole` contract entities / introspected rows.
+ *
+ * Roles are cluster-scoped, so `id` is the bare role name. The differ pairs
+ * siblings by `(nodeKind, id)`, so a role and a namespace may share a name
+ * (role `public`, schema `public`) without colliding. `isEqualTo` compares
+ * ids — name-equality is role-equality for cluster-scoped objects.
+ */
+export class PostgresRoleSchemaNode extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = PostgresSchemaNodeKind.role;
+
+  readonly name: string;
+  readonly namespaceId: string;
+
+  constructor(input: PostgresRoleSchemaNodeInput) {
+    super();
+    this.name = input.name;
+    this.namespaceId = input.namespaceId;
+    freezeNode(this);
+  }
+
+  get id(): string {
+    return this.name;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [];
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    const node = blindCast<
+      SqlSchemaIRNode,
+      'every diff-tree node the differ pairs is a SqlSchemaIRNode; the guard rejects non-role kinds'
+    >(other);
+    PostgresRoleSchemaNode.assert(node);
+    return this.id === node.id;
+  }
+
+  static is(node: SqlSchemaIRNode): node is PostgresRoleSchemaNode {
+    return node.nodeKind === PostgresSchemaNodeKind.role;
+  }
+
+  static assert(node: SqlSchemaIRNode): asserts node is PostgresRoleSchemaNode {
+    assertNode(node, 'PostgresRoleSchemaNode', PostgresRoleSchemaNode.is);
+  }
+}