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

package/src/core/migrations/planner.ts

@@ -28,24 +28,19 @@ import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { PostgresRlsPolicy } from '../postgres-rls-policy';
 import { parseRlsPolicyWireName } from '../rls/wire-name';
+import { postgresNodeStorageCoordinate } from '../schema-ir/node-storage-coordinate';
 import { PostgresDatabaseSchemaNode } from '../schema-ir/postgres-database-schema-node';
 import { PostgresPolicySchemaNode } from '../schema-ir/postgres-policy-schema-node';
-import { PostgresSchemaNodeKind, type SqlSchemaDiffNode } from '../schema-ir/schema-node-kinds';
+import type { SqlSchemaDiffNode } from '../schema-ir/schema-node-kinds';
 import {
-  formatPostgresControlPolicySubjectLabel,
+  renderPostgresSuppression,
   resolveNamespaceIdForDdlSchema,
   resolvePostgresCallControlPolicySubject,
   resolvePostgresNodeIssueControlPolicySubject,
   resolvePostgresNodeIssueCreationFactoryName,
 } from './control-policy';
 import { buildPostgresPlanDiff } from './diff-database-schema';
-import {
-  coalesceSubtreeIssues,
-  issueNode,
-  issueSchemaName,
-  issueTableName,
-  planIssues,
-} from './issue-planner';
+import { coalesceSubtreeIssues, issueNode, issueSchemaName, planIssues } from './issue-planner';
 import type { PostgresOpFactoryCall } from './op-factory-call';
 import {
   CreatePostgresRlsPolicyCall,
@@ -255,8 +250,6 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       resolveControlPolicySubject: (issue) =>
         resolvePostgresNodeIssueControlPolicySubject(issue, options.contract),
       resolveCreationFactoryName: resolvePostgresNodeIssueCreationFactoryName,
-      formatSubjectLabel: (factoryName, subject) =>
-        formatPostgresControlPolicySubjectLabel(factoryName, subject, options.contract),
     });
 
     const result = planIssues({
@@ -288,8 +281,6 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       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
@@ -314,15 +305,13 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       resolveControlPolicySubject: (call) =>
         resolvePostgresCallControlPolicySubject(call, options.contract),
       resolveFactoryName: (call) => call.factoryName,
-      formatSubjectLabel: (factoryName, subject) =>
-        formatPostgresControlPolicySubjectLabel(factoryName, subject, options.contract),
     });
     const calls = [...result.value.calls, ...schemaDiffPartition.kept, ...fieldEventPartition.kept];
     const warnings: SqlPlannerConflict[] = [
-      ...issuePartition.warnings,
-      ...schemaDiffPartition.warnings,
-      ...fieldEventPartition.warnings,
-    ];
+      ...issuePartition.suppressions,
+      ...schemaDiffPartition.suppressions,
+      ...fieldEventPartition.suppressions,
+    ].map((record) => renderPostgresSuppression(record, options.contract));
 
     return Object.freeze({
       kind: 'success' as const,
@@ -500,41 +489,14 @@ function isPolicyDiffIssue(issue: SchemaDiffIssue<SqlSchemaDiffNode>): boolean {
 }
 
 /**
- * Drops a `not-expected` issue when it is a whole extra TABLE that some
- * contract space owns, asking the ownership oracle per node.
- *
- * The consultation applies ONLY to table-level extras — a live table this
- * space's contract lacks — identified by asking the issue's own node
- * (`nodeKind === table`), never by counting path segments. `declaresEntity`
- * answers over the whole composition (self included), keyed on the schema-IR
- * entity coordinate so a genuine orphan in one namespace is never conflated
- * with a same-named table a sibling space declares in another, or with a
- * same-named non-table entity (an enum, an RLS policy) a sibling declares in
- * the SAME namespace: a positive answer means another space owns THIS table
- * in THIS namespace (a table this space owned would be in its expected tree,
- * never an extra) — leave it. A negative answer means no space owns it — a
- * genuine orphan to drop. `entityKind` is the literal `'table'` here: this
- * function only ever asks about a node already confirmed to be
- * `PostgresSchemaNodeKind.table` (checked just above), and the diff tree's
- * `nodeKind` vocabulary (`'postgres-table'`) is distinct from the storage
- * `entries` vocabulary `elementCoordinates` walks (`'table'`) — the literal
- * is that storage-entries spelling, not the node kind.
- *
- * The issue path carries the *resolved DDL schema* (e.g. `public`), but a
- * contract space's own declared namespace id can be the unbound sentinel
- * (`__unbound__`) that resolves to that schema — the two spellings would
- * never string-match. `resolveNamespaceIdForDdlSchema` recovers the raw
- * namespace id THIS space's own contract would use for that DDL schema, so
- * a table this space's own unbound namespace declares (and any sibling
- * whose own unbound namespace resolves the same way) is compared on the
- * same coordinate the aggregate's `elementCoordinates` walk yields.
- *
- * A DEEPER extra (an extra column/constraint on a table this space DOES own —
- * only the child drifted, so the table is in the expected tree) is this
- * space's own drift and is always kept for dropping; asking the oracle there
- * would wrongly suppress it, because the owned table answers `true`. Shallower
- * issues (namespace/root) are never ownership-scoped here. No oracle ⇒ every
- * extra is kept (single-space plan).
+ * Drops a `not-expected` issue when it is a whole extra storage entity (a table
+ * or a native enum) that some space in the composition owns. Each such node
+ * yields its own storage coordinate (see {@link postgresNodeStorageCoordinate}),
+ * so `declaresEntity` answers over the whole composition on one uniform
+ * coordinate: a positive answer means a sibling owns this entity here — leave
+ * it; a negative answer means a genuine orphan — drop it. A node with no storage
+ * coordinate (a namespace, or a deeper column/constraint drift on an owned
+ * table) is this space's own and is always kept. No oracle ⇒ keep everything.
  */
 function retainUnownedExtras(
   issues: readonly SchemaDiffIssue<SqlSchemaDiffNode>[],
@@ -545,12 +507,13 @@ function retainUnownedExtras(
   return issues.filter((issue) => {
     if (issue.reason !== 'not-expected') return true;
     const node = issueNode(issue);
-    if (node === undefined || node.nodeKind !== PostgresSchemaNodeKind.table) return true;
+    if (node === undefined) return true;
+    const coordinate = postgresNodeStorageCoordinate(node);
+    if (coordinate === undefined) return true;
     const ddlSchemaName = issueSchemaName(issue);
-    const tableName = issueTableName(issue);
-    if (ddlSchemaName === undefined || tableName === undefined) return true;
+    if (ddlSchemaName === undefined) return true;
     const namespaceId = resolveNamespaceIdForDdlSchema(contract, ddlSchemaName);
-    return !ownership.declaresEntity({ namespaceId, entityKind: 'table', entityName: tableName });
+    return !ownership.declaresEntity({ namespaceId, ...coordinate });
   });
 }
 
@@ -567,9 +530,9 @@ function retainUnownedExtras(
  * Returns the real `PostgresNamespaceSchemaNode` reference rather than a
  * projection: `storageTypePlanCallStrategy` hands this same value to codec
  * `planTypeOperations` hooks as `schema`, and hooks read the Postgres-specific
- * `nativeEnumTypeNames` field off it (via `PostgresNamespaceSchemaNode.is`) to
- * decide whether a native enum type already exists — a projection that only
- * copies `tables` would silently drop that signal. `StrategyContext.schema`'s
+ * `nativeEnums` field off it (via `PostgresNamespaceSchemaNode.is`) to decide
+ * whether a native enum type already exists — a projection that only copies
+ * `tables` would silently drop that signal. `StrategyContext.schema`'s
  * declared type (`SqlSchemaIR`, shared with SQLite's flat shape) doesn't
  * capture this, so the return is `blindCast` the same way `namespaceSchemaNodes`
  * in the family's relational walk already treats a namespace node as a
@@ -585,7 +548,7 @@ function relationalNamespaceNode(
   if (namespaceNode === undefined) return undefined;
   return blindCast<
     SqlSchemaIR,
-    'PostgresNamespaceSchemaNode carries tables (+ nativeEnumTypeNames, read by codec hooks via PostgresNamespaceSchemaNode.is) structurally compatible with the SqlSchemaIR shape the strategy layer declares'
+    'PostgresNamespaceSchemaNode carries tables (+ nativeEnums, read by codec hooks via PostgresNamespaceSchemaNode.is) structurally compatible with the SqlSchemaIR shape the strategy layer declares'
   >(namespaceNode);
 }
 

package/src/core/migrations/postgres-migration.ts

@@ -17,6 +17,7 @@ import {
   AlterColumnTypeCall,
   type AlterColumnTypeOptions,
   CreateIndexCall,
+  CreateNativeEnumTypeCall,
   CreateSchemaCall,
   CreateTableCall,
   DropCheckConstraintCall,
@@ -24,6 +25,7 @@ import {
   DropConstraintCall,
   DropDefaultCall,
   DropIndexCall,
+  DropNativeEnumTypeCall,
   DropNotNullCall,
   DropTableCall,
   SetDefaultCall,
@@ -171,6 +173,35 @@ export abstract class PostgresMigration<
     return new CreateSchemaCall(options.schema).toOp(this.controlAdapterFor('createSchema'));
   }
 
+  /**
+   * Emit a `CREATE TYPE ... AS ENUM (...)` migration operation for a managed
+   * native enum. Builds a typed DDL node and lowers it through the stored
+   * control adapter (members render in declaration order). Throws if no adapter
+   * is present.
+   */
+  protected createNativeEnumType(options: {
+    readonly schema: string;
+    readonly typeName: string;
+    readonly members: readonly string[];
+  }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
+    return new CreateNativeEnumTypeCall(options.schema, options.typeName, options.members).toOp(
+      this.controlAdapterFor('createNativeEnumType'),
+    );
+  }
+
+  /**
+   * Emit a `DROP TYPE` migration operation for a managed native enum, lowered
+   * through the stored control adapter. Throws if no adapter is present.
+   */
+  protected dropNativeEnumType(options: {
+    readonly schema: string;
+    readonly typeName: string;
+  }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
+    return new DropNativeEnumTypeCall(options.schema, options.typeName).toOp(
+      this.controlAdapterFor('dropNativeEnumType'),
+    );
+  }
+
   protected addColumn(options: {
     readonly schema: string;
     readonly table: string;

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

@@ -91,7 +91,6 @@ export function verifyPostgresNamespacePresence(input: {
     const namespace = new PostgresNamespaceSchemaNode({
       schemaName: ddlName,
       tables: {},
-      nativeEnumTypeNames: [],
     });
     issues.push({
       path: ['database', ddlName],

package/src/core/postgres-schema.ts

@@ -15,6 +15,7 @@ import {
 } from '@prisma-next/sql-contract/types';
 
 import { type CfExpr, cfExpr } from '@prisma-next/sql-relational-core/contract-free';
+import { invariant } from '@prisma-next/utils/assertions';
 import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { PostgresTableSource } from './ast/table-source';
@@ -25,7 +26,7 @@ import {
   rlsEnablementEntityKind,
   roleEntityKind,
 } from './entity-kinds';
-import type { PostgresNativeEnum } from './postgres-native-enum';
+import { PostgresNativeEnum } from './postgres-native-enum';
 import type { PostgresRlsEnablement } from './postgres-rls-enablement';
 import type { PostgresRlsPolicy } from './postgres-rls-policy';
 import type { PostgresRole } from './postgres-role';
@@ -88,6 +89,26 @@ export class PostgresSchema extends SqlNamespaceBase {
       'carry',
     );
 
+    // A native enum keys under its PHYSICAL type name in storage `entries`
+    // (ADR 221 coordinate `entityName`). The family/authoring layer keys every
+    // block by its author handle, so re-key the `native_enum` slot by each
+    // entity's `typeName` here — target-local Postgres code that already knows
+    // this entity kind. This runs at both authoring and hydration; a serialized
+    // contract's key already equals the `typeName`, so the re-key is idempotent.
+    const nativeEnumSlot = dispatched['native_enum'];
+    if (nativeEnumSlot !== undefined) {
+      const rekeyed: Record<string, unknown> = {};
+      for (const [handle, entity] of Object.entries(nativeEnumSlot)) {
+        const physicalName = PostgresNativeEnum.is(entity) ? entity.typeName : handle;
+        invariant(
+          !Object.hasOwn(rekeyed, physicalName),
+          `PostgresSchema "${input.id}": two native_enum entities resolve to the same physical type name "${physicalName}". Give them distinct @@map type names.`,
+        );
+        rekeyed[physicalName] = entity;
+      }
+      dispatched['native_enum'] = Object.freeze(rekeyed);
+    }
+
     // Drop an empty valueSet so presence signals non-emptiness.
     const valueSetRaw = dispatched['valueSet'];
     const withPresence =

package/src/core/psl-infer/infer-psl-contract.ts

@@ -300,10 +300,10 @@ export function inferPostgresPslContract(
   const owners = describedContractOwners(describedContracts ?? []);
   const enumOwners = describedNativeEnumOwnersByTypeName(describedContracts ?? []);
 
-  // Native enum adoption: each namespace's introspected `{ typeName, values }`
-  // entries become `native_enum` blocks + `pg.enum(<Name>)` columns, minus the
-  // types a described pack contract already declares (matched by TYPE NAME —
-  // see describedNativeEnumOwnersByTypeName). Transitional grade gap: an
+  // Native enum adoption: each namespace's introspected `enums` nodes become
+  // `native_enum` blocks + `pg.enum(<Name>)` columns, minus the types a
+  // described pack contract already declares (matched by TYPE NAME — see
+  // describedNativeEnumOwnersByTypeName). Transitional grade gap: an
   // inferred block carries no explicit `control` and inherits the contract's
   // `defaultControl`; under `defaultControl: 'managed'` the planner does not
   // yet enforce the native enum lifecycle (CREATE TYPE / DROP TYPE / ADD
@@ -313,17 +313,7 @@ export function inferPostgresPslContract(
   const packOwnedEnumTypesByNamespace = new Map<string, Map<string, string>>();
   const enumNamespaceNames = new Set<string>();
   for (const namespace of namespaces) {
-    const definitionsForNamespace = new Set(namespace.nativeEnums.map((e) => e.typeName));
-    for (const typeName of namespace.nativeEnumTypeNames) {
-      if (!definitionsForNamespace.has(typeName)) {
-        throw new Error(
-          `contract infer: introspection reported native enum type "${typeName}" in schema ` +
-            `"${namespace.schemaName}" without member values — the introspected tree's ` +
-            '`nativeEnumTypeNames` and `nativeEnums` are out of sync (internal invariant).',
-        );
-      }
-    }
-    for (const { typeName, values } of namespace.nativeEnums) {
+    for (const { typeName, members } of namespace.nativeEnums) {
       const owner = enumOwners.get(
         coordinateKey({
           namespaceId: namespace.schemaName,
@@ -341,7 +331,7 @@ export function inferPostgresPslContract(
         packOwnedEnumTypesByNamespace.set(namespace.schemaName, owned);
         continue;
       }
-      enumDefinitions.set(typeName, values);
+      enumDefinitions.set(typeName, members);
       enumNamespaceNames.add(namespace.schemaName);
     }
   }

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

@@ -1,20 +1,20 @@
 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';
 
-/** One introspected native Postgres enum type, in `pg_enum.enumsortorder` (declaration) order. */
-export interface PostgresNativeEnumIntrospection {
-  readonly typeName: string;
-  readonly values: readonly string[];
-}
-
 export interface PostgresNamespaceSchemaNodeInput {
   readonly schemaName: string;
   readonly tables: Readonly<Record<string, PostgresTableSchemaNode>>;
-  readonly nativeEnumTypeNames: readonly string[];
-  readonly nativeEnums?: readonly PostgresNativeEnumIntrospection[];
+  /**
+   * 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[];
 }
 
 /**
@@ -22,38 +22,29 @@ export interface PostgresNamespaceSchemaNodeInput {
  * 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` now carries this node's own literal
+ * 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 — two namespace nodes are
- * equal iff their ids (schema names) match. `children()` returns the table
- * nodes. Per-schema metadata is carried on the typed `nativeEnumTypeNames`
- * field, not an annotations bag.
+ * `id` is the schema name; `isEqualTo` is identity on it; `children()` returns
+ * the table nodes plus `nativeEnums`.
  *
- * `nativeEnums` carries the same enum types with their ordered member
- * values (`{ typeName, values }`), for consumers that need the values
- * (PSL inference, the printer). `nativeEnumTypeNames` stays a plain name
- * list read independently by existing consumers (codec `planTypeOperations`
- * hooks, the infer throw) so none of them need the values to keep working.
+ * `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 nativeEnumTypeNames: readonly string[];
-  readonly nativeEnums: readonly PostgresNativeEnumIntrospection[];
+  readonly nativeEnums: readonly PostgresNativeEnumSchemaNode[];
 
   constructor(input: PostgresNamespaceSchemaNodeInput) {
     super();
     this.schemaName = input.schemaName;
     this.tables = Object.freeze({ ...input.tables });
-    this.nativeEnumTypeNames = Object.freeze([...input.nativeEnumTypeNames]);
-    this.nativeEnums = Object.freeze(
-      (input.nativeEnums ?? []).map((entry) =>
-        Object.freeze({ typeName: entry.typeName, values: Object.freeze([...entry.values]) }),
-      ),
-    );
+    this.nativeEnums = Object.freeze([...(input.nativeEnums ?? [])]);
     freezeNode(this);
   }
 
@@ -66,7 +57,7 @@ export class PostgresNamespaceSchemaNode extends SqlSchemaIRNode implements Diff
   }
 
   children(): readonly DiffableNode[] {
-    return Object.values(this.tables);
+    return [...Object.values(this.tables), ...this.nativeEnums];
   }
 
   static is(node: SqlSchemaIRNode): node is PostgresNamespaceSchemaNode {

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/schema-node-kinds.ts

@@ -29,6 +29,7 @@ export const PostgresSchemaNodeKind = {
   table: 'postgres-table',
   policy: 'postgres-policy',
   role: 'postgres-role',
+  nativeEnum: 'postgres-native-enum',
 } as const;
 
 export type PostgresSchemaNodeKind =
@@ -54,6 +55,7 @@ const POSTGRES_NODE_GRANULARITY: Readonly<Record<PostgresSchemaNodeKind, DiffSub
     // not from the granularity.
     [PostgresSchemaNodeKind.policy]: 'structural',
     [PostgresSchemaNodeKind.role]: 'structural',
+    [PostgresSchemaNodeKind.nativeEnum]: 'entity',
   };
 
 function isPostgresSchemaNodeKind(nodeKind: string): nodeKind is PostgresSchemaNodeKind {
@@ -82,15 +84,22 @@ export function postgresDiffSubjectGranularity(nodeKind: string): DiffSubjectGra
 }
 
 /**
- * The one real map from a Postgres-specific `nodeKind` to its storage
- * `entityKind` — the same vocabulary the contract storage's `entries`
- * dictionary keys use. Only the whole-table kind has an entity of its own;
+ * The map from a Postgres-specific `nodeKind` to its storage `entityKind` — the
+ * same vocabulary the contract storage's `entries` dictionary keys use. The
+ * whole-table and native-enum kinds each have an entity of their own;
  * database/namespace/policy/role nodes map to nothing here (a namespace is
  * addressed by id, not by an `entries` kind; policies and roles are
  * structural, never a sibling space's unclaimed entity).
+ *
+ * The native enum keys under its PHYSICAL type name in `entries.native_enum`
+ * (ADR 221), so its diff node's `typeName` addresses the entity on the generic
+ * coordinate directly — no by-type-name walk needed. This lets the framework's
+ * unclaimed-elements sweep classify enum ownership the same coordinate way it
+ * classifies tables.
  */
 const POSTGRES_NODE_ENTITY_KIND: Partial<Readonly<Record<PostgresSchemaNodeKind, string>>> = {
   [PostgresSchemaNodeKind.table]: 'table',
+  [PostgresSchemaNodeKind.nativeEnum]: 'native_enum',
 };
 
 /** Looks up the storage entityKind for a Postgres-specific `nodeKind`. */

package/src/core/sql-utils.ts

@@ -81,6 +81,19 @@ export function qualifyName(schemaName: string, objectName: string): string {
   return `${quoteIdentifier(schemaName)}.${quoteIdentifier(objectName)}`;
 }
 
+/**
+ * Quotes a possibly dot-qualified name segment-by-segment:
+ * `order_status` -> `"order_status"`, `auth.aal_level` -> `"auth"."aal_level"`.
+ * A single-segment name round-trips to exactly {@link quoteIdentifier}; whole-
+ * string quoting (`"auth.aal_level"`) would be one wrong identifier.
+ */
+export function quoteQualifiedName(name: string): string {
+  return name
+    .split('.')
+    .map((segment) => quoteIdentifier(segment))
+    .join('.');
+}
+
 /**
  * Validates that an enum value doesn't exceed PostgreSQL's label length limit.
  *
@@ -93,10 +106,10 @@ export function qualifyName(schemaName: string, objectName: string): string {
  * @throws {SqlEscapeError} If the value exceeds the maximum length
  */
 export function validateEnumValueLength(value: string, enumTypeName: string): void {
-  if (value.length > MAX_IDENTIFIER_LENGTH) {
+  if (new TextEncoder().encode(value).length > MAX_IDENTIFIER_LENGTH) {
     throw new SqlEscapeError(
       `Enum value "${value.slice(0, 20)}..." for type "${enumTypeName}" exceeds PostgreSQL's ` +
-        `${MAX_IDENTIFIER_LENGTH}-character label limit`,
+        `${MAX_IDENTIFIER_LENGTH}-byte label limit`,
       value,
       'literal',
     );

package/src/exports/ddl.ts

@@ -9,9 +9,11 @@ export {
   PostgresCreatePolicy,
   PostgresCreateSchema,
   PostgresCreateTable,
+  PostgresCreateType,
   PostgresDdlNode,
   type PostgresDdlVisitor,
   PostgresDisableRowLevelSecurity,
   PostgresDropPolicy,
+  PostgresDropType,
   type RlsPolicyOperation,
 } from '../core/ddl/nodes';

package/src/exports/op-factory-call.ts

@@ -8,6 +8,7 @@ export {
   AlterColumnTypeCall,
   CreateExtensionCall,
   CreateIndexCall,
+  CreateNativeEnumTypeCall,
   CreateSchemaCall,
   CreateTableCall,
   DataTransformCall,
@@ -16,6 +17,7 @@ export {
   DropConstraintCall,
   DropDefaultCall,
   DropIndexCall,
+  DropNativeEnumTypeCall,
   DropNotNullCall,
   DropTableCall,
   RawSqlCall,

package/src/exports/sql-utils.ts

@@ -2,6 +2,7 @@ export {
   escapeLiteral,
   qualifyName,
   quoteIdentifier,
+  quoteQualifiedName,
   SqlEscapeError,
   validateEnumValueLength,
 } from '../core/sql-utils';

package/src/exports/types.ts

@@ -23,8 +23,11 @@ export {
 export {
   PostgresNamespaceSchemaNode,
   type PostgresNamespaceSchemaNodeInput,
-  type PostgresNativeEnumIntrospection,
 } from '../core/schema-ir/postgres-namespace-schema-node';
+export {
+  PostgresNativeEnumSchemaNode,
+  type PostgresNativeEnumSchemaNodeInput,
+} from '../core/schema-ir/postgres-native-enum-schema-node';
 export {
   PostgresPolicySchemaNode,
   type PostgresPolicySchemaNodeInput,