@prisma-next/target-postgres 0.12.0 → 0.13.0-dev.10

package/src/contract-free/control-bootstrap.ts

@@ -0,0 +1,55 @@
+import { APP_SPACE_ID } from '@prisma-next/framework-components/control';
+import type { DdlNode } from '@prisma-next/sql-relational-core/ast';
+import { col, fn, lit } from '@prisma-next/sql-relational-core/contract-free';
+import { createSchema, createTable } from './ddl';
+
+const markerColumns = [
+  col('space', 'text', { notNull: true, primaryKey: true, default: lit(APP_SPACE_ID) }),
+  col('core_hash', 'text', { notNull: true }),
+  col('profile_hash', 'text', { notNull: true }),
+  col('contract_json', 'jsonb'),
+  col('canonical_version', 'int'),
+  col('updated_at', 'timestamptz', { notNull: true, default: fn('now()') }),
+  col('app_tag', 'text'),
+  col('meta', 'jsonb', { notNull: true, default: lit('{}') }),
+  col('invariants', 'text[]', { notNull: true, default: lit('{}') }),
+] as const;
+
+const ledgerColumns = [
+  col('id', 'bigserial', { primaryKey: true }),
+  col('created_at', 'timestamptz', { notNull: true, default: fn('now()') }),
+  col('space', 'text', { notNull: true }),
+  col('migration_name', 'text', { notNull: true }),
+  col('migration_hash', 'text', { notNull: true }),
+  col('origin_core_hash', 'text'),
+  col('origin_profile_hash', 'text'),
+  col('destination_core_hash', 'text', { notNull: true }),
+  col('destination_profile_hash', 'text'),
+  col('contract_json_before', 'jsonb'),
+  col('contract_json_after', 'jsonb'),
+  col('operations', 'jsonb', { notNull: true }),
+] as const;
+
+const markerTable = createTable({
+  schema: 'prisma_contract',
+  table: 'marker',
+  ifNotExists: true,
+  columns: markerColumns,
+});
+
+const ledgerTable = createTable({
+  schema: 'prisma_contract',
+  table: 'ledger',
+  ifNotExists: true,
+  columns: ledgerColumns,
+});
+
+const controlSchema = createSchema({ schema: 'prisma_contract', ifNotExists: true });
+
+export function buildSignMarkerBootstrapQueries(): readonly DdlNode[] {
+  return [controlSchema, markerTable];
+}
+
+export function buildControlTableBootstrapQueries(): readonly DdlNode[] {
+  return [controlSchema, markerTable, ledgerTable];
+}

package/src/contract-free/ddl.ts

@@ -0,0 +1,37 @@
+import type { DdlColumn, DdlTableConstraint } from '@prisma-next/sql-relational-core/ast';
+import { PostgresCreateSchema, PostgresCreateTable } from '../core/ddl/nodes';
+
+/**
+ * Build a Postgres `CREATE TABLE` query node.
+ *
+ * Pass `constraints` for table-level composite primary keys, foreign keys, and
+ * unique constraints — use the {@link PrimaryKeyConstraint}, {@link ForeignKeyConstraint},
+ * and {@link UniqueConstraint} classes from `@prisma-next/sql-relational-core/ast`.
+ *
+ * Precondition: identifiers (`table`, `schema`, column names/types) are
+ * emitted to SQL verbatim — they are not quoted or escaped, so callers must
+ * pass pre-trusted values (e.g. fixed control-plane identifiers). String-literal
+ * default values, by contrast, are single-quote-escaped (embedded `'` doubled)
+ * by the renderer. Identifier quoting for untrusted identifiers is added when
+ * the migration planner adopts this lowering path.
+ */
+export function createTable(options: {
+  readonly table: string;
+  readonly schema?: string;
+  readonly ifNotExists?: boolean;
+  readonly columns: readonly DdlColumn[];
+  readonly constraints?: readonly DdlTableConstraint[];
+}): PostgresCreateTable {
+  return new PostgresCreateTable(options);
+}
+
+/**
+ * Build a Postgres `CREATE SCHEMA` query node. See {@link createTable} for the
+ * pre-trusted-identifier precondition.
+ */
+export function createSchema(options: {
+  readonly schema: string;
+  readonly ifNotExists?: boolean;
+}): PostgresCreateSchema {
+  return new PostgresCreateSchema(options);
+}

package/src/core/ast/table-source.ts

@@ -0,0 +1,23 @@
+import {
+  type AnyFromSource,
+  type AstRewriter,
+  TableSource,
+} from '@prisma-next/sql-relational-core/ast';
+
+export class PostgresTableSource extends TableSource {
+  readonly schema: string | undefined;
+
+  constructor(options: {
+    readonly name: string;
+    readonly schema?: string;
+    readonly alias?: string;
+  }) {
+    super(options.name, options.alias);
+    this.schema = options.schema;
+    this.freeze();
+  }
+
+  override rewrite(rewriter: AstRewriter): AnyFromSource {
+    return rewriter.tableSource ? rewriter.tableSource(this) : this;
+  }
+}

package/src/core/authoring.ts

@@ -124,7 +124,7 @@ export const postgresAuthoringFieldPresets = {
       nativeType: 'timestamptz',
     },
   },
-  temporal: temporalAuthoringPresets({
+  temporal: /* @__PURE__ */ temporalAuthoringPresets({
     codecId: 'pg/timestamptz@1',
     nativeType: 'timestamptz',
   }),

package/src/core/codec-ids.ts

@@ -7,6 +7,7 @@ export {
   SQL_VARCHAR_CODEC_ID,
 } from '@prisma-next/sql-relational-core/ast';
 export const PG_TEXT_CODEC_ID = 'pg/text@1' as const;
+export const PG_TEXT_ARRAY_CODEC_ID = 'pg/text-array@1' as const;
 export const PG_ENUM_CODEC_ID = 'pg/enum@1' as const;
 export const PG_CHAR_CODEC_ID = 'pg/char@1' as const;
 export const PG_VARCHAR_CODEC_ID = 'pg/varchar@1' as const;

package/src/core/codecs.ts

@@ -71,6 +71,7 @@ import {
   PG_JSON_CODEC_ID,
   PG_JSONB_CODEC_ID,
   PG_NUMERIC_CODEC_ID,
+  PG_TEXT_ARRAY_CODEC_ID,
   PG_TEXT_CODEC_ID,
   PG_TIME_CODEC_ID,
   PG_TIMESTAMP_CODEC_ID,
@@ -99,6 +100,7 @@ const precisionParamsSchema = arktype({
 }) satisfies StandardSchemaV1<PrecisionParams>;
 
 const PG_TEXT_META = { db: { sql: { postgres: { nativeType: 'text' } } } } as const;
+const PG_TEXT_ARRAY_META = { db: { sql: { postgres: { nativeType: 'text[]' } } } } as const;
 const PG_INT4_META = { db: { sql: { postgres: { nativeType: 'integer' } } } } as const;
 const PG_INT2_META = { db: { sql: { postgres: { nativeType: 'smallint' } } } } as const;
 const PG_INT8_META = { db: { sql: { postgres: { nativeType: 'bigint' } } } } as const;
@@ -160,6 +162,47 @@ export const pgTextColumn = () =>
 pgTextColumn satisfies ColumnHelperFor<PgTextDescriptor>;
 pgTextColumn satisfies ColumnHelperForStrict<PgTextDescriptor>;
 
+/**
+ * Postgres `text[]` codec. Encode is an identity pass-through: the pg wire
+ * driver serialises a JS `string[]` to a Postgres array literal under the
+ * `$N::text[]` cast the renderer emits from this codec's `text[]` native type,
+ * and decode reads it back as a JS array. Used by the control plane to write
+ * the marker's `invariants` column. Not a user-facing scalar — it is not part
+ * of the authorable `CodecTypes` surface, only the runtime codec registry.
+ */
+export class PgTextArrayCodec extends CodecImpl<
+  typeof PG_TEXT_ARRAY_CODEC_ID,
+  readonly ['equality'],
+  readonly string[],
+  readonly string[]
+> {
+  async encode(value: readonly string[], _ctx: CodecCallContext): Promise<readonly string[]> {
+    return value;
+  }
+  async decode(wire: readonly string[], _ctx: CodecCallContext): Promise<readonly string[]> {
+    return wire;
+  }
+  encodeJson(value: readonly string[]): JsonValue {
+    return [...value];
+  }
+  decodeJson(json: JsonValue): readonly string[] {
+    return Array.isArray(json) ? json.map((entry) => String(entry)) : [];
+  }
+}
+
+export class PgTextArrayDescriptor extends CodecDescriptorImpl<void> {
+  override readonly codecId = PG_TEXT_ARRAY_CODEC_ID;
+  override readonly traits = ['equality'] as const;
+  override readonly targetTypes = ['text[]'] as const;
+  override readonly meta = PG_TEXT_ARRAY_META;
+  override readonly paramsSchema: StandardSchemaV1<void> = voidParamsSchema;
+  override factory(): (ctx: CodecInstanceContext) => PgTextArrayCodec {
+    return () => new PgTextArrayCodec(this);
+  }
+}
+
+export const pgTextArrayDescriptor = new PgTextArrayDescriptor();
+
 export class PgInt4Codec extends CodecImpl<
   typeof PG_INT4_CODEC_ID,
   readonly ['equality', 'order', 'numeric'],
@@ -1036,4 +1079,5 @@ export const codecDescriptors: readonly AnyCodecDescriptor[] = [
   pgEnumDescriptor,
   pgJsonDescriptor,
   pgJsonbDescriptor,
+  pgTextArrayDescriptor,
 ];

package/src/core/ddl/nodes.ts

@@ -0,0 +1,72 @@
+import {
+  type DdlColumn,
+  DdlNode,
+  type DdlTableConstraint,
+} from '@prisma-next/sql-relational-core/ast';
+
+export interface PostgresDdlVisitor<R> {
+  createTable(node: PostgresCreateTable): R;
+  createSchema(node: PostgresCreateSchema): R;
+}
+
+export abstract class PostgresDdlNode extends DdlNode {
+  abstract accept<R>(visitor: PostgresDdlVisitor<R>): R;
+}
+
+function freezeDdlColumns(columns: readonly DdlColumn[]): ReadonlyArray<DdlColumn> {
+  return Object.freeze([...columns]);
+}
+
+function freezeConstraints(
+  constraints: readonly DdlTableConstraint[] | undefined,
+): ReadonlyArray<DdlTableConstraint> | undefined {
+  return constraints ? Object.freeze([...constraints]) : undefined;
+}
+
+export class PostgresCreateTable extends PostgresDdlNode {
+  readonly kind = 'create-table' as const;
+  readonly table: string;
+  readonly schema: string | undefined;
+  readonly ifNotExists: boolean | undefined;
+  readonly columns: ReadonlyArray<DdlColumn>;
+  readonly constraints: ReadonlyArray<DdlTableConstraint> | undefined;
+
+  constructor(options: {
+    readonly table: string;
+    readonly schema?: string;
+    readonly ifNotExists?: boolean;
+    readonly columns: readonly DdlColumn[];
+    readonly constraints?: readonly DdlTableConstraint[];
+  }) {
+    super();
+    this.table = options.table;
+    this.schema = options.schema;
+    this.ifNotExists = options.ifNotExists;
+    this.columns = freezeDdlColumns(options.columns);
+    this.constraints = freezeConstraints(options.constraints);
+    this.freeze();
+  }
+
+  override accept<R>(visitor: PostgresDdlVisitor<R>): R {
+    return visitor.createTable(this);
+  }
+}
+
+export class PostgresCreateSchema extends PostgresDdlNode {
+  readonly kind = 'create-schema' as const;
+  readonly schema: string;
+  readonly ifNotExists: boolean | undefined;
+
+  constructor(options: { readonly schema: string; readonly ifNotExists?: boolean }) {
+    super();
+    this.schema = options.schema;
+    this.ifNotExists = options.ifNotExists;
+    this.freeze();
+  }
+
+  override accept<R>(visitor: PostgresDdlVisitor<R>): R {
+    return visitor.createSchema(this);
+  }
+}
+
+export type AnyPostgresDdlNode = PostgresCreateTable | PostgresCreateSchema;

package/src/core/descriptor-meta-runtime.ts

@@ -0,0 +1,28 @@
+// Runtime-safe slice of the postgres target descriptor metadata.
+//
+// This file exists separately from ./descriptor-meta on purpose: the runtime
+// plane reads only `kind/familyId/targetId/id/version/capabilities` (plus the
+// `__codecTypes` phantom). The `authoring` slot lives on the pack/control
+// descriptor only, because authoring contributions are consumed at
+// contract-construction time by `assembleAuthoringContributions` (control
+// plane) and the PSL interpreter — never at runtime.
+//
+// Keeping the runtime closure free of the `./authoring` import is what lets
+// the bundler tree-shake `@prisma-next/family-sql/control` (and its
+// transitive `verify-sql-schema` chunk) out of the runtime entry. Do not
+// add an `authoring` field here — if you need to, the pack/control meta in
+// `./descriptor-meta` is the right place. See TML-2766 for context.
+import type { CodecTypes } from '../exports/codec-types';
+
+const postgresTargetDescriptorMetaRuntimeBase = {
+  kind: 'target',
+  familyId: 'sql',
+  targetId: 'postgres',
+  id: 'postgres',
+  version: '0.0.1',
+  capabilities: {},
+} as const;
+
+export const postgresTargetDescriptorMetaRuntime: typeof postgresTargetDescriptorMetaRuntimeBase & {
+  readonly __codecTypes?: CodecTypes;
+} = postgresTargetDescriptorMetaRuntimeBase;

package/src/core/descriptor-meta.ts

@@ -4,14 +4,11 @@ import {
   postgresAuthoringFieldPresets,
   postgresAuthoringTypes,
 } from './authoring';
+import { postgresTargetDescriptorMetaRuntime } from './descriptor-meta-runtime';
 
 const postgresTargetDescriptorMetaBase = {
-  kind: 'target',
-  familyId: 'sql',
-  targetId: 'postgres',
-  id: 'postgres',
-  version: '0.0.1',
-  capabilities: {},
+  ...postgresTargetDescriptorMetaRuntime,
+  defaultNamespaceId: 'public',
   authoring: {
     type: postgresAuthoringTypes,
     field: postgresAuthoringFieldPresets,

package/src/core/migrations/control-policy.ts

@@ -0,0 +1,234 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { ControlPolicySubject } from '@prisma-next/family-sql/control';
+import type { SchemaIssue } from '@prisma-next/framework-components/control';
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
+import {
+  isPostgresEnumStorageEntry,
+  type SqlStorage,
+  storageTableAt,
+} from '@prisma-next/sql-contract/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { isPostgresSchema } from '../postgres-schema';
+import type { PostgresOpFactoryCall } from './op-factory-call';
+
+/**
+ * Factory calls that create a whole, previously-absent top-level storage
+ * object. Used to decide whether `tolerated` permits a call (it only allows
+ * creating absent objects, never modifying existing ones).
+ *
+ * Deliberately an explicit, closed set rather than a `factoryName`
+ * create/alter/drop classification: it answers exactly one yes/no question
+ * and is fail-closed. Any call not listed here — including future or
+ * extension-contributed factories — is treated as NOT object-creation, so it
+ * is suppressed under `tolerated` rather than permissively emitted.
+ */
+const OBJECT_CREATION_FACTORIES: ReadonlySet<string> = new Set<string>([
+  'createTable',
+  'createEnumType',
+  'createSchema',
+]);
+
+function createsNewTopLevelObject(call: PostgresOpFactoryCall): boolean {
+  return OBJECT_CREATION_FACTORIES.has(call.factoryName);
+}
+
+function ddlSchemaNameForNamespace(contract: Contract<SqlStorage>, namespaceId: string): string {
+  const namespace = contract.storage.namespaces[namespaceId];
+  return isPostgresSchema(namespace) ? namespace.ddlSchemaName(contract.storage) : namespaceId;
+}
+
+function resolveNamespaceIdForTable(
+  contract: Contract<SqlStorage>,
+  tableName: string,
+  ddlSchemaName: string | undefined,
+): string {
+  for (const namespaceId of Object.keys(contract.storage.namespaces)) {
+    const table = storageTableAt(contract.storage, namespaceId, tableName);
+    if (!table) continue;
+    if (
+      ddlSchemaName === undefined ||
+      ddlSchemaNameForNamespace(contract, namespaceId) === ddlSchemaName
+    ) {
+      return namespaceId;
+    }
+  }
+  return UNBOUND_NAMESPACE_ID;
+}
+
+function resolveNamespaceIdForDdlSchema(
+  contract: Contract<SqlStorage>,
+  ddlSchemaName: string,
+): string {
+  for (const namespaceId of Object.keys(contract.storage.namespaces)) {
+    const ns = contract.storage.namespaces[namespaceId];
+    if (isPostgresSchema(ns) && ns.ddlSchemaName(contract.storage) === ddlSchemaName) {
+      return namespaceId;
+    }
+    if (namespaceId === ddlSchemaName) {
+      return namespaceId;
+    }
+  }
+  return UNBOUND_NAMESPACE_ID;
+}
+
+interface PostgresCallFields {
+  readonly schemaName?: string;
+  readonly tableName?: string;
+  readonly columnName?: string;
+  readonly typeName?: string;
+}
+
+function postgresCallFields(call: PostgresOpFactoryCall): PostgresCallFields {
+  return {
+    ...ifDefined('schemaName', 'schemaName' in call ? call.schemaName : undefined),
+    ...ifDefined('tableName', 'tableName' in call ? call.tableName : undefined),
+    ...ifDefined('columnName', 'columnName' in call ? call.columnName : undefined),
+    ...ifDefined('typeName', 'typeName' in call ? call.typeName : undefined),
+  };
+}
+
+export function formatPostgresControlPolicySubjectLabel(
+  factoryName: string,
+  subject: ControlPolicySubject | undefined,
+  contract: Contract<SqlStorage>,
+): string {
+  if (subject?.table) {
+    const ddlSchema = ddlSchemaNameForNamespace(contract, subject.namespaceId);
+    return `${factoryName}(${ddlSchema}.${subject.table})`;
+  }
+  if (subject?.typeName) {
+    const ddlSchema = ddlSchemaNameForNamespace(contract, subject.namespaceId);
+    return `${factoryName}(${ddlSchema}.${subject.typeName})`;
+  }
+  return factoryName;
+}
+
+export function resolvePostgresCallControlPolicySubject(
+  call: PostgresOpFactoryCall,
+  contract: Contract<SqlStorage>,
+): ControlPolicySubject | undefined {
+  const callFields = postgresCallFields(call);
+  const createsNewObject = createsNewTopLevelObject(call);
+
+  if (call.factoryName === 'createSchema' && callFields.schemaName) {
+    return {
+      namespaceId: resolveNamespaceIdForDdlSchema(contract, callFields.schemaName),
+      createsNewObject,
+    };
+  }
+
+  if (callFields.typeName && call.factoryName !== 'addColumn') {
+    const namespaceId = callFields.schemaName
+      ? resolveNamespaceIdForDdlSchema(contract, callFields.schemaName)
+      : UNBOUND_NAMESPACE_ID;
+    const ns = contract.storage.namespaces[namespaceId];
+    const rawEnum = isPostgresSchema(ns) ? ns.entries.type[callFields.typeName] : undefined;
+    const controlPolicy = isPostgresEnumStorageEntry(rawEnum) ? rawEnum.control : undefined;
+    return {
+      namespaceId,
+      ...ifDefined('explicitNodeControlPolicy', controlPolicy),
+      typeName: callFields.typeName,
+      createsNewObject,
+    };
+  }
+
+  if (callFields.tableName) {
+    const namespaceId = resolveNamespaceIdForTable(
+      contract,
+      callFields.tableName,
+      callFields.schemaName,
+    );
+    const table = storageTableAt(contract.storage, namespaceId, callFields.tableName);
+    const tableControlPolicy = table?.control;
+    return {
+      namespaceId,
+      ...ifDefined('explicitNodeControlPolicy', tableControlPolicy),
+      table: callFields.tableName,
+      ...ifDefined('column', callFields.columnName),
+      createsNewObject,
+    };
+  }
+
+  if (callFields.schemaName) {
+    return {
+      namespaceId: resolveNamespaceIdForDdlSchema(contract, callFields.schemaName),
+      createsNewObject,
+    };
+  }
+
+  return undefined;
+}
+
+/**
+ * Issue kinds that describe the absence of a whole, top-level Postgres
+ * object — the same kinds `createsNewTopLevelObject` recognises for calls.
+ * Used by {@link resolvePostgresIssueCreationFactoryName} to decide whether
+ * a `tolerated` subject permits the issue to flow into the planner
+ * (create-if-absent) and to seed the suppressed-subject warning's
+ * `factoryName` when the planner is skipped.
+ */
+const POSTGRES_ISSUE_CREATION_FACTORY: Readonly<Record<string, string>> = Object.freeze({
+  missing_schema: 'createSchema',
+  missing_table: 'createTable',
+  type_missing: 'createEnumType',
+});
+
+export function resolvePostgresIssueCreationFactoryName(issue: SchemaIssue): string | undefined {
+  return POSTGRES_ISSUE_CREATION_FACTORY[issue.kind];
+}
+
+/**
+ * Resolve the control-policy subject coordinate for a single
+ * {@link SchemaIssue}. Mirrors the resolution `resolvePostgresCallControlPolicySubject`
+ * performs for a generated DDL call, but works *off the issue* — so the
+ * planner can partition issues by effective policy before the diff engine
+ * runs. `createsNewObject` is derived from the issue's kind: schema/table/
+ * type-missing issues describe a brand-new top-level object; everything else
+ * touches an existing object.
+ *
+ * An `extra_table` issue carries no contract namespace coordinate (the table
+ * isn't in any contract namespace), so the subject's `namespaceId` falls
+ * back to {@link UNBOUND_NAMESPACE_ID}; the call-side resolver does the same
+ * for the `DropTableCall` it produces.
+ */
+export function resolvePostgresIssueControlPolicySubject(
+  issue: SchemaIssue,
+  contract: Contract<SqlStorage>,
+): ControlPolicySubject | undefined {
+  const createsNewObject = POSTGRES_ISSUE_CREATION_FACTORY[issue.kind] !== undefined;
+
+  if (issue.kind === 'missing_schema' && issue.namespaceId) {
+    return { namespaceId: issue.namespaceId, createsNewObject };
+  }
+
+  if ('typeName' in issue && issue.typeName) {
+    const namespaceId =
+      'namespaceId' in issue && issue.namespaceId ? issue.namespaceId : UNBOUND_NAMESPACE_ID;
+    const ns = contract.storage.namespaces[namespaceId];
+    const rawEnum = isPostgresSchema(ns) ? ns.entries.type[issue.typeName] : undefined;
+    const controlPolicy = isPostgresEnumStorageEntry(rawEnum) ? rawEnum.control : undefined;
+    return {
+      namespaceId,
+      ...ifDefined('explicitNodeControlPolicy', controlPolicy),
+      typeName: issue.typeName,
+      createsNewObject,
+    };
+  }
+
+  if ('table' in issue && issue.table) {
+    const namespaceId =
+      'namespaceId' in issue && issue.namespaceId
+        ? issue.namespaceId
+        : resolveNamespaceIdForTable(contract, issue.table, undefined);
+    const table = storageTableAt(contract.storage, namespaceId, issue.table);
+    return {
+      namespaceId,
+      ...ifDefined('explicitNodeControlPolicy', table?.control),
+      table: issue.table,
+      ...ifDefined('column', 'column' in issue ? issue.column : undefined),
+      createsNewObject,
+    };
+  }
+
+  return undefined;
+}

package/src/core/migrations/enum-planning.ts

@@ -14,17 +14,25 @@ import { isPostgresSchema } from '../postgres-schema';
 
 /**
  * Codec-typed enum entry shape stored under
- * `schema.annotations.pg.storageTypes[(schemaName, nativeType)]`.
+ * `schema.annotations.pg.enumTypes[schemaName][nativeType]`.
  */
 interface PgStorageTypeEntry {
   readonly codecId?: string;
   readonly typeParams?: { readonly values?: unknown };
 }
 
+/**
+ * Live enum types keyed by `(schemaName, nativeType)` as a nested map, so two
+ * schemas sharing a native enum name stay distinct without packing the pair
+ * into a string. This is the same `(namespace, entityName)` coordinate the
+ * contract side addresses entities by.
+ */
+type PgEnumTypesMap = Readonly<Record<string, Readonly<Record<string, PgStorageTypeEntry>>>>;
+
 /** Postgres-specific subtree on family `SqlSchemaIR.annotations`. */
 export interface PostgresSchemaIrAnnotations {
   readonly schema?: string;
-  readonly storageTypes?: Readonly<Record<string, PgStorageTypeEntry>>;
+  readonly enumTypes?: PgEnumTypesMap;
 }
 
 function readOptionalString(value: unknown): string | undefined {
@@ -50,20 +58,27 @@ function readPgStorageTypeEntry(value: unknown): PgStorageTypeEntry | undefined
   };
 }
 
-function readPgStorageTypesMap(
-  value: unknown,
-): Readonly<Record<string, PgStorageTypeEntry>> | undefined {
+function readPgEnumTypesMap(value: unknown): PgEnumTypesMap | undefined {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
     return undefined;
   }
-  const entries: Record<string, PgStorageTypeEntry> = {};
-  for (const [key, entryValue] of Object.entries(value)) {
-    const entry = readPgStorageTypeEntry(entryValue);
-    if (entry !== undefined) {
-      entries[key] = entry;
+  const bySchema: Record<string, Record<string, PgStorageTypeEntry>> = {};
+  for (const [schemaName, byTypeRaw] of Object.entries(value)) {
+    if (byTypeRaw === null || typeof byTypeRaw !== 'object' || Array.isArray(byTypeRaw)) {
+      continue;
+    }
+    const byType: Record<string, PgStorageTypeEntry> = {};
+    for (const [nativeType, entryValue] of Object.entries(byTypeRaw)) {
+      const entry = readPgStorageTypeEntry(entryValue);
+      if (entry !== undefined) {
+        byType[nativeType] = entry;
+      }
+    }
+    if (Object.keys(byType).length > 0) {
+      bySchema[schemaName] = byType;
     }
   }
-  return Object.keys(entries).length > 0 ? entries : undefined;
+  return Object.keys(bySchema).length > 0 ? bySchema : undefined;
 }
 
 /**
@@ -78,25 +93,13 @@ export function readPostgresSchemaIrAnnotations(schema: SqlSchemaIR): PostgresSc
     return {};
   }
   const schemaField = readOptionalString(Reflect.get(raw, 'schema'));
-  const storageTypes = readPgStorageTypesMap(Reflect.get(raw, 'storageTypes'));
+  const enumTypes = readPgEnumTypesMap(Reflect.get(raw, 'enumTypes'));
   return {
     ...(schemaField !== undefined ? { schema: schemaField } : {}),
-    ...(storageTypes !== undefined ? { storageTypes } : {}),
+    ...(enumTypes !== undefined ? { enumTypes } : {}),
   };
 }
 
-/**
- * Separator for `(schemaName, nativeType)` keys in introspected
- * `schema.annotations.pg.storageTypes`. NUL cannot appear in Postgres
- * identifiers, so the pair is unambiguous.
- */
-export const ENUM_STORAGE_KEY_SEP = '\u0000';
-
-/** Builds the schema-qualified storageTypes map key for a live Postgres enum. */
-export function enumStorageCompoundKey(schemaName: string, nativeType: string): string {
-  return `${schemaName}${ENUM_STORAGE_KEY_SEP}${nativeType}`;
-}
-
 /**
  * Resolves the live-schema name a namespace's enums are introspected under,
  * for keying `readExistingEnumValues` lookups. The unbound namespace's
@@ -149,9 +152,10 @@ export type EnumDiff =
 
 /**
  * Reads existing enum values for `(schemaName, nativeType)` from the
- * Postgres-introspected `schema.annotations.pg.storageTypes` map.
+ * Postgres-introspected `schema.annotations.pg.enumTypes` map, addressed by
+ * the `(schema, nativeType)` coordinate.
  *
- * Schema IR's `storageTypes` slots are always codec-typed
+ * Schema IR's enum entries are always codec-typed
  * (`{codecId: PG_ENUM_CODEC_ID, typeParams.values}`): the introspector
  * writes that shape, and the Contract→Schema IR projector resolves
  * `PostgresEnumType` instances down to the same codec-typed triple before
@@ -165,8 +169,8 @@ export function readExistingEnumValues(
   schemaName: string,
   nativeType: string,
 ): readonly string[] | null {
-  const storageTypes = readPostgresSchemaIrAnnotations(schema).storageTypes;
-  const existing = storageTypes?.[enumStorageCompoundKey(schemaName, nativeType)];
+  const enumTypes = readPostgresSchemaIrAnnotations(schema).enumTypes;
+  const existing = enumTypes?.[schemaName]?.[nativeType];
   if (!existing || existing.codecId !== PG_ENUM_CODEC_ID) {
     return null;
   }