@prisma-next/target-postgres 0.14.0-dev.9 → 0.14.0-dev.90

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

@@ -1,9 +1,13 @@
 import type { Contract } from '@prisma-next/contract/types';
-import type { SchemaIssue } from '@prisma-next/framework-components/control';
+import type { SchemaDiffIssue } from '@prisma-next/framework-components/control';
 import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
-import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
+import type { SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import { DEFAULT_NAMESPACE_ID } from '../namespace-ids';
 import { isPostgresSchema } from '../postgres-schema';
+import { PostgresDatabaseSchemaNode } from '../schema-ir/postgres-database-schema-node';
+import { PostgresNamespaceSchemaNode } from '../schema-ir/postgres-namespace-schema-node';
+import type { SqlSchemaDiffNode } from '../schema-ir/schema-node-kinds';
 
 /**
  * Resolves the live-database schema name for a given namespace
@@ -23,32 +27,36 @@ 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 the database-root schema
+ * node. `existingSchemas` is database-level, so it lives on the
+ * `PostgresDatabaseSchemaNode` root — not on the per-schema namespace nodes.
+ *
+ * Defaults to the always-present `public` schema when the node is not the
+ * database root — 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 root. Tests that want to assert against a richer initial
+ * state construct a `PostgresDatabaseSchemaNode` 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');
+function existingSchemasFromSchema(schema: SqlSchemaIRNode): readonly string[] {
+  if (PostgresDatabaseSchemaNode.is(schema)) {
+    return schema.existingSchemas;
   }
-  return ['public'];
+  return [DEFAULT_NAMESPACE_ID];
 }
 
 /**
- * Emits a `missing_schema` issue for every contract-declared Postgres
- * namespace whose live container does not yet exist.
+ * Emits a `postgres-namespace` `not-found` diff issue for every
+ * contract-declared Postgres namespace whose live container does not yet
+ * exist. The planner prepends these (node-typed, synthesized) to the
+ * relational diff issues so a multi-schema plan emits `CREATE SCHEMA`
+ * before the tables that need it — a planner-only concern (verify already
+ * rejects via the `not-found` table issues a missing schema already
+ * produces), so this is not part of the shared diff.
  *
  * A namespace's live container is the schema returned by its
  * polymorphic `ddlSchemaName(storage)` method — named schemas resolve
@@ -59,28 +67,35 @@ function existingSchemasFromSchema(schema: SqlSchemaIR): readonly string[] {
  * introspected list. `public` is suppressed implicitly because the
  * introspection (or its sensible default) always carries it.
  *
- * Each emitted issue stamps `namespaceId` with the contract namespace
- * coordinate so the downstream `mapIssueToCall` re-resolves the DDL
- * schema name through the same polymorphic path — keeping the
- * coordinate, not the resolved name, as the issue's stable identity.
+ * Each emitted issue's path is `['database', ddlName]` — an ancestor of
+ * every table path under that schema, so it must never be run through
+ * `coalesceSubtreeIssues` alongside the table diff (it would swallow the
+ * table-level `not-found` issues that drive `CREATE TABLE`); the planner
+ * adds these AFTER coalescing the relational issues, and they are not
+ * subject to sibling-space ownership scoping (mirrors the retired
+ * coordinate walk, which prepended namespace issues after that filter).
  */
 export function verifyPostgresNamespacePresence(input: {
   readonly contract: Contract<SqlStorage>;
-  readonly schema: SqlSchemaIR;
-}): readonly SchemaIssue[] {
+  readonly schema: SqlSchemaIRNode;
+}): readonly SchemaDiffIssue<SqlSchemaDiffNode>[] {
   const { contract, schema } = input;
   const existing = new Set(existingSchemasFromSchema(schema));
-  const issues: SchemaIssue[] = [];
+  const issues: SchemaDiffIssue<SqlSchemaDiffNode>[] = [];
   const namespaceIds = Object.keys(contract.storage.namespaces).sort();
   for (const namespaceId of namespaceIds) {
     if (namespaceId === UNBOUND_NAMESPACE_ID) continue;
     const ddlName = resolveDdlSchemaName(contract.storage, namespaceId);
     if (ddlName === UNBOUND_NAMESPACE_ID) continue;
     if (existing.has(ddlName)) continue;
+    const namespace = new PostgresNamespaceSchemaNode({
+      schemaName: ddlName,
+      tables: {},
+    });
     issues.push({
-      kind: 'missing_schema',
-      namespaceId,
-      message: `Schema "${ddlName}" is missing from database`,
+      path: ['database', ddlName],
+      reason: 'not-found',
+      expected: namespace,
     });
   }
   return issues;

package/src/core/namespace-ids.ts

@@ -0,0 +1,3 @@
+// Leaf module: authoring.ts and descriptor-meta.ts both need this and import each other.
+/** Postgres's default schema; `postgresTargetDescriptorMeta.defaultNamespaceId` is this value. */
+export const DEFAULT_NAMESPACE_ID = 'public' as const;

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

@@ -10,20 +10,27 @@ 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 { postgresAuthoringEntityTypes } from './authoring';
-import { postgresTargetDescriptorMeta } from './descriptor-meta';
-import { isPostgresSchema, PostgresSchema } from './postgres-schema';
+import { PG_INT_CODEC_ID, PG_TEXT_CODEC_ID } from './codec-ids';
+import {
+  nativeEnumEntityKind,
+  policyEntityKind,
+  rlsEnablementEntityKind,
+  roleEntityKind,
+} from './entity-kinds';
+import { PostgresSchema } from './postgres-schema';
 
 const POSTGRES_AUTHORING_CTX: AuthoringEntityContext = {
   family: 'sql',
   target: 'postgres',
+  enumInferenceCodecs: { text: PG_TEXT_CODEC_ID, int: PG_INT_CODEC_ID },
 };
 
 function isAuthoringEntityTypeFactoryOutput(
@@ -32,7 +39,8 @@ function isAuthoringEntityTypeFactoryOutput(
   return (
     typeof output === 'object' &&
     output !== null &&
-    typeof (output as AuthoringEntityTypeFactoryOutput).factory === 'function'
+    'factory' in output &&
+    typeof output.factory === 'function'
   );
 }
 
@@ -65,34 +73,35 @@ 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,
+      rlsEnablementEntityKind,
+      nativeEnumEntityKind,
+      ...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: {
@@ -106,24 +115,16 @@ export class PostgresContractSerializer extends SqlContractSerializerBase<Contra
   override serializeContract(contract: Contract<SqlStorage>): JsonObject {
     const { storage, ...rest } = contract;
     const namespacesJson: Record<string, JsonObject> = {};
+    // Each namespace serializes to its id, its schema-kind tag, and the
+    // base's generic entries walk — every enumerable kind on
+    // `PostgresSchema.entries`, including `native_enum`.
     for (const [nsId, ns] of Object.entries(storage.namespaces)) {
-      if (isPostgresSchema(ns)) {
-        namespacesJson[nsId] = this.serializePostgresNamespace(ns, ns.id === UNBOUND_NAMESPACE_ID);
-      } else {
-        const isUnboundSlot = nsId === UNBOUND_NAMESPACE_ID;
-        namespacesJson[nsId] = {
-          id: nsId,
-          kind: isUnboundSlot ? 'postgres-unbound-schema' : 'postgres-schema',
-          entries: {
-            table: Object.fromEntries(
-              Object.entries(ns.entries.table ?? {}).map(([tableName, table]) => [
-                tableName,
-                this.serializeJsonValue(table) as JsonObject,
-              ]),
-            ),
-          },
-        };
-      }
+      const isUnboundSlot = ns.id === UNBOUND_NAMESPACE_ID;
+      namespacesJson[nsId] = {
+        id: ns.id,
+        kind: isUnboundSlot ? 'postgres-unbound-schema' : 'postgres-schema',
+        entries: this.serializeNamespaceEntries(ns.entries),
+      };
     }
     const storageOut: Record<string, unknown> = {
       storageHash: String(storage.storageHash),
@@ -132,42 +133,16 @@ 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;
-    }
-    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));
-      }
-    }
-    return {
-      id: ns.id,
-      kind: isUnboundSlot ? 'postgres-unbound-schema' : 'postgres-schema',
-      entries: {
-        table: tablesOut,
-        ...(Object.keys(valueSetOut).length > 0 ? { valueSet: valueSetOut } : {}),
-      },
-    };
-  }
-
-  private serializeJsonValue(value: unknown): unknown {
-    return JSON.parse(JSON.stringify(value)) as unknown;
+    });
   }
 }

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

@@ -0,0 +1,48 @@
+import type { Contract } from '@prisma-next/contract/types';
+import {
+  buildSqlSchemaQualifiedView,
+  type SqlSchemaQualifiedView,
+} from '@prisma-next/sql-contract/contract-view';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import { PostgresContractSerializer } from './postgres-contract-serializer';
+
+/**
+ * A schema-qualified Postgres contract view: the deserialized contract
+ * intersected with a single `namespace` member holding every schema by id. It is
+ * substitutable for `Contract` (carries `storage`, `domain`, …) and reaches each
+ * schema's entities through `view.namespace.<schema>`:
+ *
+ * ```ts
+ * const view = PostgresContractView.fromJson<Contract>(contractJson);
+ * view.namespace.public.table.users      // typed table leaf in the public schema
+ * view.namespace.auth.table.users        // the auth schema's own users table
+ * view.namespace.public.entries.policy.X // pack-contributed kind (RLS / #771 path)
+ * view.namespace.__unbound__.table.X     // default schema, keyed by its raw id
+ * view.storage                           // the full contract is still present
+ * ```
+ *
+ * This mirrors the runtime `db.enums.<ns>` keying exactly (the default schema
+ * keeps its literal `__unbound__` id). Schema names are NOT promoted to the
+ * contract root, so there is no collision with contract envelope fields — a
+ * schema named `storage` is `view.namespace.storage`, while `view.storage`
+ * stays the contract's `storage`.
+ */
+export type PostgresContractView<TContract extends Contract<SqlStorage> = Contract<SqlStorage>> =
+  SqlSchemaQualifiedView<TContract>;
+
+export const PostgresContractView = {
+  /** Wrap an already-deserialized Postgres contract in a schema-qualified view. */
+  from<TContract extends Contract<SqlStorage>>(
+    contract: TContract,
+  ): PostgresContractView<TContract> {
+    return buildSqlSchemaQualifiedView(contract);
+  },
+
+  /** Deserialize a Postgres contract JSON envelope and wrap it in a view. */
+  fromJson<TContract extends Contract<SqlStorage> = Contract<SqlStorage>>(
+    json: unknown,
+  ): PostgresContractView<TContract> {
+    const contract = new PostgresContractSerializer().deserializeContract<TContract>(json);
+    return buildSqlSchemaQualifiedView(contract);
+  },
+};

package/src/core/postgres-native-enum.ts

@@ -0,0 +1,61 @@
+import type { ControlPolicy } from '@prisma-next/contract/types';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { SqlNode } from '@prisma-next/sql-contract/types';
+import { blindCast } from '@prisma-next/utils/casts';
+
+export interface PostgresNativeEnumInput<Members extends readonly string[] = readonly string[]> {
+  /** The Postgres type name (`CREATE TYPE <typeName> AS ENUM (…)`). */
+  readonly typeName: string;
+  /** Member values in declaration order — this is the Postgres enum sort order. */
+  readonly members: Members;
+  readonly control?: ControlPolicy;
+}
+
+function freezeMembers<Members extends readonly string[]>(members: Members): Members {
+  return blindCast<
+    Members,
+    'Object.freeze clones+freezes the tuple for immutability; the clone widens to readonly string[], but it holds exactly the values of members (already typed Members)'
+  >(Object.freeze([...members]));
+}
+
+/**
+ * Postgres contract-IR class for a native enum type (`CREATE TYPE … AS ENUM (…)`).
+ *
+ * This is an authored, serialized Contract-IR entity — it is registered as an entity
+ * kind, extends `SqlNode`, and is stored in `contract.json`. It is NOT a DiffableNode;
+ * the schema-diff tree will use `PostgresNativeEnumSchemaNode` when the managed phase
+ * builds it.
+ *
+ * A member is a value, not a name→value pair — matching `CREATE TYPE … AS ENUM
+ * ('a', 'b')`, which has no separate member name.
+ *
+ * Target-only concept — no SQL-family abstract. Extends `SqlNode` directly,
+ * frozen at construction via `freezeNode(this)`. The `kind: 'postgres-enum'`
+ * discriminant is enumerable so it survives JSON. Lives at
+ * `storage.namespaces[ns].entries.native_enum[HandleName]`; the entries key
+ * (`native_enum`) is the entity-kind descriptor's `kind`, decoupled from this
+ * node's own `kind` literal — the same shape as `table`/`StorageTable` and
+ * `valueSet`/`StorageValueSet`.
+ */
+export class PostgresNativeEnum<
+  Members extends readonly string[] = readonly string[],
+> extends SqlNode {
+  static is(node: unknown): node is PostgresNativeEnum {
+    return (
+      typeof node === 'object' && node !== null && 'kind' in node && node.kind === 'postgres-enum'
+    );
+  }
+
+  override readonly kind = 'postgres-enum' as const;
+  readonly typeName: string;
+  readonly members: Members;
+  declare readonly control?: ControlPolicy;
+
+  constructor(input: PostgresNativeEnumInput<Members>) {
+    super();
+    this.typeName = input.typeName;
+    this.members = freezeMembers(input.members);
+    if (input.control !== undefined) this.control = input.control;
+    freezeNode(this);
+  }
+}

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

@@ -0,0 +1,34 @@
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { SqlNode } from '@prisma-next/sql-contract/types';
+
+export interface PostgresRlsEnablementInput {
+  /** Name of the table this marker declares RLS-controlled. */
+  readonly tableName: string;
+  /** Namespace coordinate (schema name). Markers are schema-scoped like policies. */
+  readonly namespaceId: string;
+}
+
+/**
+ * Postgres contract-IR marker for `@@rls` on a model: the table named here is
+ * RLS-controlled (`ENABLE ROW LEVEL SECURITY` is driven by this marker, never
+ * by the policy set).
+ *
+ * This is an authored, serialized Contract-IR entity — it is registered as an
+ * entity kind, extends `SqlNode`, and is stored in `contract.json` under
+ * `entries.rls[tableName]`. Target-only concept — no SQL-family abstract.
+ * Frozen at construction via `freezeNode(this)`. The `kind: 'rls'`
+ * discriminant is enumerable so it survives JSON serialization; the literal
+ * matches the entries key (one-string rule).
+ */
+export class PostgresRlsEnablement extends SqlNode {
+  override readonly kind = 'rls' as const;
+  readonly tableName: string;
+  readonly namespaceId: string;
+
+  constructor(input: PostgresRlsEnablementInput) {
+    super();
+    this.tableName = input.tableName;
+    this.namespaceId = input.namespaceId;
+    freezeNode(this);
+  }
+}

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

@@ -0,0 +1,64 @@
+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 contract-IR class for a row-level security policy (`CREATE POLICY … ON …`).
+ *
+ * This is an authored, serialized Contract-IR entity — it is registered as an entity
+ * kind, extends `SqlNode`, and is stored in `contract.json`. It is NOT a DiffableNode;
+ * the schema-diff tree uses `PostgresPolicySchemaNode` for that role.
+ *
+ * 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 {
+  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);
+  }
+}

package/src/core/postgres-role.ts

@@ -0,0 +1,59 @@
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { SqlNode } from '@prisma-next/sql-contract/types';
+
+/**
+ * Roles are referenced by the contract but never owned — the framework
+ * issues no `CREATE`/`DROP ROLE`, so a role's effective governance is always
+ * `external`: a missing declared role fails verify, an extra live role is
+ * tolerated, and the planner emits zero role DDL. `external` is the only
+ * value a role's control can ever carry.
+ */
+export const ROLE_DEFAULT_CONTROL_POLICY = 'external';
+
+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;
+  /**
+   * Defaults to {@link ROLE_DEFAULT_CONTROL_POLICY} when omitted. Roles are
+   * referenced but never owned, so `'external'` is the only allowed value.
+   */
+  readonly control?: 'external';
+}
+
+/**
+ * Postgres contract-IR class for a database role (`CREATE ROLE …`).
+ *
+ * This is an authored, serialized Contract-IR entity — it is registered as an entity
+ * kind, extends `SqlNode`, and is stored in `contract.json`. It is NOT a DiffableNode;
+ * the schema-diff tree uses `PostgresRoleSchemaNode` for that 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).
+ *
+ * `control` always carries a value (never omitted): it defaults to
+ * {@link ROLE_DEFAULT_CONTROL_POLICY} in the constructor, so both a
+ * freshly-authored role and one hydrated from an older `contract.json`
+ * lacking the field resolve the same way — the control-policy resolver
+ * reads it directly off the entity instead of special-casing role issues.
+ */
+export class PostgresRole extends SqlNode {
+  override readonly kind = 'role' as const;
+  readonly name: string;
+  readonly namespaceId: string;
+  readonly control: 'external';
+
+  constructor(input: PostgresRoleInput) {
+    super();
+    this.name = input.name;
+    this.namespaceId = input.namespaceId;
+    this.control = input.control ?? ROLE_DEFAULT_CONTROL_POLICY;
+    freezeNode(this);
+  }
+}

package/src/core/postgres-schema-verifier.ts

@@ -1,16 +1,19 @@
 import type { Contract } from '@prisma-next/contract/types';
 import { SqlSchemaVerifierBase } from '@prisma-next/family-sql/ir';
-import type { SchemaIssue, SchemaVerifyOptions } from '@prisma-next/framework-components/control';
+import type {
+  SchemaDiffIssue,
+  SchemaVerifyOptions,
+} from '@prisma-next/framework-components/control';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
 
 /**
  * Postgres target `SchemaVerifier` concretion. Plugs into the
  * SQL-shared verification surface; production verification today still
- * routes through the legacy `verifySqlSchema` entry point, which
- * carries options (codec hooks, normalizers, framework components)
- * that the framework-level `SchemaVerifyOptions` shape does not yet
- * surface.
+ * routes through the family verify verdict (`verifySqlSchemaByDiff` over
+ * `diffPostgresSchema`), which carries options (codec hooks,
+ * normalizers, framework components) that the framework-level
+ * `SchemaVerifyOptions` shape does not yet surface.
  *
  * The hooks return the empty list pending the call-site migration that
  * routes the existing verifier behaviour through the SPI — at that
@@ -25,13 +28,13 @@ export class PostgresSchemaVerifier extends SqlSchemaVerifierBase<
 > {
   protected verifyCommonSqlSchema(
     _options: SchemaVerifyOptions<Contract<SqlStorage>, SqlSchemaIR>,
-  ): readonly SchemaIssue[] {
+  ): readonly SchemaDiffIssue[] {
     return [];
   }
 
   protected verifyTargetExtensions(
     _options: SchemaVerifyOptions<Contract<SqlStorage>, SqlSchemaIR>,
-  ): readonly SchemaIssue[] {
+  ): readonly SchemaDiffIssue[] {
     return [];
   }
 }