@prisma-next/target-postgres 0.14.0-dev.3 → 0.14.0-dev.31

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-schema.ts

@@ -1,24 +1,36 @@
+import type { Contract } from '@prisma-next/contract/types';
 import {
   freezeNode,
   hydrateNamespaceEntities,
-  NamespaceBase,
   UNBOUND_NAMESPACE_ID,
 } from '@prisma-next/framework-components/ir';
 import { composeSqlEntityKinds } from '@prisma-next/sql-contract/entity-kinds';
-import type {
-  SqlNamespaceEntries,
-  SqlNamespaceTablesInput,
-  SqlStorage,
-  StorageTable,
-  StorageValueSet,
+import {
+  SqlNamespaceBase,
+  type SqlNamespaceEntries,
+  type SqlNamespaceInput,
+  type SqlStorage,
+  type StorageTable,
+  type StorageValueSet,
 } from '@prisma-next/sql-contract/types';
+
 import { type CfExpr, cfExpr } from '@prisma-next/sql-relational-core/contract-free';
 import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { PostgresTableSource } from './ast/table-source';
 import { PG_TEXT_CODEC_ID } from './codec-ids';
+import { policyEntityKind, roleEntityKind } from './entity-kinds';
+import type { PostgresRlsPolicy } from './schema-ir/postgres-rls-policy';
+import type { PostgresRole } from './schema-ir/postgres-role';
 import { escapeLiteral } from './sql-utils';
 
+export type PostgresContract = Contract<SqlStorage> & { readonly target: 'postgres' };
+
+export type PostgresNamespaceEntries = SqlNamespaceEntries & {
+  readonly policy?: Readonly<Record<string, PostgresRlsPolicy>>;
+  readonly role?: Readonly<Record<string, PostgresRole>>;
+};
+
 export interface PostgresSchemaInput {
   readonly id: string;
   readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
@@ -38,7 +50,7 @@ export interface PostgresSchemaInput {
  * prefix entirely — call sites stay polymorphic and never branch on
  * `id === UNBOUND_NAMESPACE_ID`.
  */
-export class PostgresSchema extends NamespaceBase {
+export class PostgresSchema extends SqlNamespaceBase {
   /**
    * Stable singleton reference for the late-bound slot. Materialised
    * lazily below the singleton subclass declaration so the static
@@ -50,13 +62,17 @@ export class PostgresSchema extends NamespaceBase {
 
   declare readonly kind: 'schema';
   readonly id: string;
-  readonly entries: SqlNamespaceEntries;
+  readonly entries: PostgresNamespaceEntries;
 
   constructor(input: PostgresSchemaInput) {
     super();
     this.id = input.id;
 
-    const dispatched = hydrateNamespaceEntities(input.entries, composeSqlEntityKinds(), 'carry');
+    const dispatched = hydrateNamespaceEntities(
+      input.entries,
+      composeSqlEntityKinds([policyEntityKind, roleEntityKind]),
+      'carry',
+    );
 
     // Drop an empty valueSet so presence signals non-emptiness.
     const valueSetRaw = dispatched['valueSet'];
@@ -67,8 +83,8 @@ export class PostgresSchema extends NamespaceBase {
 
     this.entries = Object.freeze(
       blindCast<
-        SqlNamespaceEntries,
-        'composeSqlEntityKinds() supplies table→StorageTable and valueSet→StorageValueSet descriptors, so this open-dict result holds exactly the typed members SqlNamespaceEntries declares; the descriptor Map erases those per-kind Node types from the return.'
+        PostgresNamespaceEntries,
+        'composeSqlEntityKinds([policyEntityKind, roleEntityKind]) supplies table→StorageTable, valueSet→StorageValueSet, policy→PostgresRlsPolicy, role→PostgresRole descriptors'
       >(withPresence),
     );
     Object.defineProperty(this, 'kind', {
@@ -88,6 +104,14 @@ export class PostgresSchema extends NamespaceBase {
     return this.entries.valueSet;
   }
 
+  get policy(): Readonly<Record<string, PostgresRlsPolicy>> {
+    return this.entries.policy ?? Object.freeze({});
+  }
+
+  get role(): Readonly<Record<string, PostgresRole>> {
+    return this.entries.role ?? Object.freeze({});
+  }
+
   /**
    * The bare schema qualifier as it would appear in a rendered SQL
    * fragment (already quoted). The unbound-schema singleton overrides
@@ -247,7 +271,7 @@ export function isPostgresSchema(ns: unknown): ns is PostgresSchema {
  * by reference and trust the resulting `SqlStorage.namespaces` map to
  * be value-stable for a given input set.
  */
-export function postgresCreateNamespace(input: SqlNamespaceTablesInput): PostgresSchema {
+export function postgresCreateNamespace(input: SqlNamespaceInput): PostgresSchema {
   const schemaInput: PostgresSchemaInput = {
     id: input.id,
     entries: {

package/src/core/postgres-validators.ts

@@ -0,0 +1,20 @@
+import { type } from 'arktype';
+
+export const PostgresRoleSchema = type({
+  kind: "'role'",
+  name: 'string',
+  namespaceId: 'string',
+});
+
+export const PostgresRlsPolicySchema = type({
+  kind: "'policy'",
+  name: 'string',
+  prefix: 'string',
+  tableName: 'string',
+  namespaceId: 'string',
+  operation: "'select' | 'insert' | 'update' | 'delete' | 'all'",
+  roles: type.string.array().readonly(),
+  'using?': 'string',
+  'withCheck?': 'string',
+  permissive: 'boolean',
+});

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/schema-ir/postgres-rls-policy.ts

@@ -0,0 +1,101 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+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);
+  }
+
+  get id(): string {
+    return this.name;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [];
+  }
+
+  /**
+   * 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.constructor?.name ?? typeof other}`,
+      );
+    }
+    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(
+      `planPostgresSchemaDiff: expected a PostgresRlsPolicy on the policy-diff path but got ${kind}`,
+    );
+  }
+}

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

@@ -0,0 +1,52 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+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);
+  }
+
+  /** Roles are cluster-unique; the name alone is sufficient as the id. */
+  get id(): string {
+    return this.name;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [];
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    if (!(other instanceof PostgresRole)) {
+      throw new Error(
+        `PostgresRole.isEqualTo: expected a PostgresRole, got ${other.constructor?.name ?? typeof other}`,
+      );
+    }
+    return this.name === other.name;
+  }
+}

package/src/core/schema-ir/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;
+}

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

@@ -0,0 +1,138 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import {
+  type SqlAnnotations,
+  type SqlSchemaIR,
+  SqlSchemaIRNode,
+  type SqlSchemaTarget,
+  type SqlTableIRInput,
+} from '@prisma-next/sql-schema-ir/types';
+import { blindCast } from '@prisma-next/utils/casts';
+import type { PostgresRlsPolicy } from './postgres-rls-policy';
+import type { PostgresRole } from './postgres-role';
+import { PostgresTableIR } from './postgres-table-ir';
+
+export interface PostgresSchemaIRInput {
+  readonly tables: Record<
+    string,
+    PostgresTableIR | (SqlTableIRInput & { rlsPolicies?: readonly PostgresRlsPolicy[] })
+  >;
+  readonly pgSchemaName: string;
+  readonly pgVersion: string;
+  readonly roles: readonly PostgresRole[];
+  readonly existingSchemas: readonly string[];
+  readonly nativeEnumTypeNames: readonly string[];
+}
+
+/**
+ * Postgres-specific schema IR. Mirrors the structure of `SqlSchemaIR`
+ * (same `tables` + optional `annotations` fields) and adds typed fields for
+ * data the postgres adapter collects during introspection.
+ *
+ * Extends `SqlSchemaIRNode` directly rather than `SqlSchemaIR` because
+ * `SqlSchemaIR` calls `freezeNode` in its constructor, which prevents
+ * subclass field initialisation. `PostgresSchemaIR` replicates the minimal
+ * `SqlSchemaIR` structure and freezes itself at the end of its own
+ * constructor.
+ *
+ * `tables` holds `PostgresTableIR` instances which carry their own RLS
+ * policies. `children()` returns the tables directly — the table instances
+ * ARE the diff-tree nodes.
+ *
+ * Nothing RLS-specific leaks into the sql-family layer.
+ */
+export class PostgresSchemaIR extends SqlSchemaIRNode implements DiffableNode {
+  readonly nodeTarget: SqlSchemaTarget = 'postgres';
+  readonly tables: Readonly<Record<string, PostgresTableIR>>;
+  declare readonly annotations?: SqlAnnotations;
+  readonly pgSchemaName: string;
+  readonly pgVersion: string;
+  readonly roles: readonly PostgresRole[];
+  readonly existingSchemas: readonly string[];
+  readonly nativeEnumTypeNames: readonly string[];
+
+  constructor(input: PostgresSchemaIRInput) {
+    super();
+    this.tables = Object.freeze(
+      Object.fromEntries(
+        Object.entries(input.tables).map(([key, t]) => [
+          key,
+          t instanceof PostgresTableIR ? t : new PostgresTableIR(t),
+        ]),
+      ),
+    );
+    this.pgSchemaName = input.pgSchemaName;
+    this.pgVersion = input.pgVersion;
+    this.roles = Object.freeze([...input.roles]);
+    this.existingSchemas = Object.freeze([...input.existingSchemas]);
+    this.nativeEnumTypeNames = Object.freeze([...input.nativeEnumTypeNames]);
+    // Populate the annotations.pg bag with only the subset the family layer
+    // reads (nativeEnumTypeNames for PSL inference, existingSchemas for
+    // namespace presence checks).
+    this.annotations = {
+      pg: {
+        schema: input.pgSchemaName,
+        ...(input.nativeEnumTypeNames.length > 0 && {
+          nativeEnumTypeNames: input.nativeEnumTypeNames,
+        }),
+        ...(input.existingSchemas.length > 0 && {
+          existingSchemas: input.existingSchemas,
+        }),
+      },
+    };
+    freezeNode(this);
+  }
+
+  get id(): string {
+    return this.pgSchemaName;
+  }
+
+  get rlsPolicies(): readonly PostgresRlsPolicy[] {
+    return Object.values(this.tables).flatMap((t) => t.rlsPolicies);
+  }
+
+  isEqualTo(_other: DiffableNode): boolean {
+    return true;
+  }
+
+  children(): readonly DiffableNode[] {
+    return Object.values(this.tables);
+  }
+}
+
+/**
+ * Structural guard for `PostgresSchemaIR`, narrowing on the `nodeTarget`
+ * discriminant rather than `instanceof`. `nodeTarget` is an enumerable own field
+ * (a plain class-field initializer), so it survives the `{ ...schema, tables }`
+ * spread the multi-space verify path (`projectSchemaToSpace`) produces — that
+ * projected object is not a class instance but retains every enumerable own
+ * property. The family-level `kind = 'sql-schema-ir'` discriminator is unusable
+ * here: it is shared by every SQL schema-IR node and is non-enumerable (dropped
+ * by the spread).
+ */
+export function isPostgresSchemaIR(schema: SqlSchemaIR): schema is PostgresSchemaIR {
+  return schema.nodeTarget === 'postgres';
+}
+
+export function assertPostgresSchemaIR(schema: SqlSchemaIR): asserts schema is PostgresSchemaIR {
+  if (!isPostgresSchemaIR(schema)) {
+    throw new Error(
+      `planPostgresSchemaDiff: expected a PostgresSchemaIR but got nodeTarget=${String(schema.nodeTarget ?? typeof schema)}`,
+    );
+  }
+}
+
+/**
+ * Returns `schema` as-is when it is a real `PostgresSchemaIR` instance, or
+ * reconstructs one when `projectSchemaToSpace` has spread the class into a
+ * plain object (losing prototype methods).
+ */
+export function ensurePostgresSchemaIR(schema: PostgresSchemaIR): PostgresSchemaIR {
+  if (schema instanceof PostgresSchemaIR) return schema;
+  return new PostgresSchemaIR(
+    blindCast<
+      PostgresSchemaIRInput,
+      'spread objects from projectSchemaToSpace preserve all own-enumerable fields'
+    >(schema),
+  );
+}