@prisma-next/family-sql 0.8.0 → 0.9.0-dev.2

package/src/core/ir/sql-contract-serializer-base.ts

@@ -0,0 +1,136 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { ContractSerializer } from '@prisma-next/framework-components/control';
+import { SqlStorage, type SqlStorageTypeEntry } from '@prisma-next/sql-contract/types';
+import { validateSqlContractFully } from '@prisma-next/sql-contract/validators';
+import type { JsonObject } from '@prisma-next/utils/json';
+
+export type SqlEntityHydrationFactory = (entry: unknown) => SqlStorageTypeEntry;
+
+/**
+ * SQL family `ContractSerializer` abstract base. Carries the SQL-shared
+ * deserialization pipeline:
+ *
+ * 1. `parseSqlContractStructure` validates the on-disk JSON envelope
+ *    against the SQL contract arktype schema (`validateSqlContractFully`)
+ *    and returns the validated flat-data shape.
+ * 2. `hydrateSqlStorage` walks the validated `storage` subtree and
+ *    constructs the family-shared SQL Contract IR class hierarchy
+ *    (`SqlStorage` -> `StorageTable` -> `StorageColumn` / `PrimaryKey`
+ *    / …). The rest of the contract envelope is JSON-clean primitive
+ *    data and passes through unchanged.
+ * 3. `constructTargetContract` is the target-specific extension hook;
+ *    defaults to identity. Targets that need to attach target-only
+ *    fields (e.g. target-specific derived storage fields) override it.
+ *
+ * Default `serializeContract` is identity over the contract — concrete
+ * SQL targets ship JSON-clean class instances, so the contract value
+ * can be stringified directly. The non-enumerable family-level `kind`
+ * discriminator on `SqlNode` instances stays out of the persisted
+ * envelope automatically. Targets that need to canonicalize on the way
+ * out (key ordering, dropping computed-only fields) override
+ * `serializeContract` directly.
+ */
+export abstract class SqlContractSerializerBase<TContract extends Contract<SqlStorage>>
+  implements ContractSerializer<TContract>
+{
+  constructor(
+    private readonly entityTypeRegistry: ReadonlyMap<string, SqlEntityHydrationFactory>,
+  ) {}
+
+  deserializeContract(json: unknown): TContract {
+    const validated = this.parseSqlContractStructure(json);
+    const hydrated = this.hydrateSqlStorage(validated);
+    return this.constructTargetContract(hydrated);
+  }
+
+  serializeContract(contract: TContract): JsonObject {
+    // Targets that ship enumerable runtime-only fields must override
+    // this method (mirroring `MongoTargetContractSerializer.serializeContract`)
+    // to construct the persisted envelope explicitly; the default identity
+    // works only when every enumerable own property belongs in the JSON.
+    return contract as unknown as JsonObject;
+  }
+
+  /**
+   * Family-shared validation pipeline (delegates to
+   * `validateSqlContractFully` in `@prisma-next/sql-contract/validators`):
+   * structural arktype + framework-shared domain + SQL storage
+   * logical-consistency + SQL storage semantic + model ↔ storage
+   * reference checks. Subclasses override to add target-specific
+   * structural checks before hydration; the family default suffices
+   * for targets whose contract shape is the SQL-shared shape
+   * (Postgres, SQLite today).
+   */
+  protected parseSqlContractStructure(json: unknown): Contract<SqlStorage> {
+    return validateSqlContractFully<Contract<SqlStorage>>(json);
+  }
+
+  /**
+   * Family-shared hydration walker. Lifts the validated flat-data
+   * `storage` subtree into the SQL Contract IR class hierarchy by
+   * constructing a single `SqlStorage` instance — its constructor
+   * cascades nested instantiation of `StorageTable`, `StorageColumn`,
+   * `PrimaryKey`, `UniqueConstraint`, `Index`, `ForeignKey`,
+   * `ForeignKeyReferences`, and `StorageTypeInstance`. The rest of the
+   * contract envelope (target identity, hashes, capabilities, models,
+   * meta, …) is JSON-clean primitive data and passes through unchanged.
+   *
+   * Polymorphic `storage.types` entries are normalised before the
+   * `SqlStorage` constructor runs: when an entry carries an enumerable
+   * string `kind`, the serializer looks up a pack-registered hydration
+   * factory for that discriminator and delegates reconstruction. Entries
+   * with no registered factory pass through unchanged (codec-typed JSON
+   * stays codec-typed until `SqlStorage` normalises it).
+   */
+  protected hydrateSqlStorage(validated: Contract<SqlStorage>): Contract<SqlStorage> {
+    const types = validated.storage.types;
+    const hydratedTypes =
+      types !== undefined
+        ? Object.fromEntries(
+            Object.entries(types).map(([name, entry]) => [
+              name,
+              this.hydrateStorageTypeEntry(entry),
+            ]),
+          )
+        : undefined;
+
+    return {
+      ...validated,
+      storage: new SqlStorage({
+        ...validated.storage,
+        ...(hydratedTypes !== undefined ? { types: hydratedTypes } : {}),
+      }),
+    };
+  }
+
+  /**
+   * Per-entry hydration dispatcher for `storage.types`. When `kind` is a
+   * string and the constructor registry supplies a factory for that key,
+   * the factory returns the hydrated `SqlStorageTypeEntry`. Otherwise the
+   * entry passes through unchanged for `SqlStorage` to normalise.
+   */
+  protected hydrateStorageTypeEntry(entry: SqlStorageTypeEntry): SqlStorageTypeEntry {
+    if (typeof entry !== 'object' || entry === null) {
+      return entry;
+    }
+    const kind = (entry as { kind?: unknown }).kind;
+    if (typeof kind !== 'string') {
+      return entry;
+    }
+    const factory = this.entityTypeRegistry.get(kind);
+    if (factory === undefined) {
+      return entry;
+    }
+    return factory(entry);
+  }
+
+  /**
+   * Target-specific construction hook. Defaults to identity; targets
+   * that need to wrap the hydrated contract (e.g. attach target-only
+   * derived fields, narrow the contract type to a target-specific
+   * subtype) override.
+   */
+  protected constructTargetContract(hydrated: Contract<SqlStorage>): TContract {
+    return hydrated as TContract;
+  }
+}

package/src/core/ir/sql-contract-serializer.ts

@@ -0,0 +1,18 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import { SqlContractSerializerBase } from './sql-contract-serializer-base';
+
+/**
+ * Default SQL family `ContractSerializer` concretion. Inherits the
+ * full SQL-shared deserialization pipeline (structural validation +
+ * IR-class hydration) without pack-registered `storage.types`
+ * hydration factories — targets that emit polymorphic JSON outside the
+ * codec-typed envelope wire a target-specific subclass with a populated
+ * registry (see Postgres). Family-level call sites instantiate this
+ * default directly when no target serializer is supplied.
+ */
+export class SqlContractSerializer extends SqlContractSerializerBase<Contract<SqlStorage>> {
+  constructor() {
+    super(new Map());
+  }
+}

package/src/core/ir/sql-schema-verifier-base.ts

@@ -0,0 +1,56 @@
+import type {
+  SchemaIssue,
+  SchemaVerifier,
+  SchemaVerifyOptions,
+  SchemaVerifyResult,
+} from '@prisma-next/framework-components/control';
+
+/**
+ * SQL family `SchemaVerifier` abstract base. Centralises the SQL-shared
+ * walk (table-by-table + column-by-column matching keyed by
+ * `(namespace.id, name)`, FK / unique / index comparisons via the
+ * existing helpers in `verify-helpers.ts`) and exposes a protected hook
+ * for target extensions (Postgres functions, RLS policies, future
+ * target-only kinds).
+ *
+ * The base accumulates issues in a single buffer and returns the
+ * combined result; the per-SPI family abstract handles the result
+ * envelope shape so concrete subclasses focus on target-specific
+ * verification logic.
+ *
+ * The protected hooks (`verifyCommonSqlSchema`,
+ * `verifyTargetExtensions`) carry the stable base API that target
+ * subclasses (`PostgresSchemaVerifier`, `SqliteSchemaVerifier`)
+ * compile against; the SQL-shared walk implementation will be lifted
+ * into this base when the verifier behaviour migrates off the
+ * legacy adapter shells.
+ */
+export abstract class SqlSchemaVerifierBase<TContract, TSchema>
+  implements SchemaVerifier<TContract, TSchema>
+{
+  verifySchema(options: SchemaVerifyOptions<TContract, TSchema>): SchemaVerifyResult {
+    const issues: SchemaIssue[] = [];
+    issues.push(...this.verifyCommonSqlSchema(options));
+    issues.push(...this.verifyTargetExtensions(options));
+    return { ok: issues.length === 0, issues };
+  }
+
+  /**
+   * SQL-shared verification — table/column/FK/unique/index walks keyed
+   * by `(namespace.id, name)`. Concrete subclasses provide the
+   * family-shared implementation today; a future iteration will lift
+   * the shared walk into this base.
+   */
+  protected abstract verifyCommonSqlSchema(
+    options: SchemaVerifyOptions<TContract, TSchema>,
+  ): readonly SchemaIssue[];
+
+  /**
+   * Target-specific extensions — e.g. Postgres functions, future RLS
+   * policies, namespace-mismatch issues. Returns the empty list when the
+   * target ships no extensions over the SQL family alphabet.
+   */
+  protected abstract verifyTargetExtensions(
+    options: SchemaVerifyOptions<TContract, TSchema>,
+  ): readonly SchemaIssue[];
+}

package/src/core/migrations/contract-to-schema-ir.ts

@@ -1,13 +1,17 @@
 import type { ColumnDefault, Contract } from '@prisma-next/contract/types';
 import type { MigrationPlannerConflict } from '@prisma-next/framework-components/control';
-import type {
-  ForeignKey,
-  Index,
-  SqlStorage,
-  StorageColumn,
-  StorageTable,
-  StorageTypeInstance,
-  UniqueConstraint,
+import {
+  type ForeignKey,
+  type Index,
+  isPostgresEnumStorageEntry,
+  isStorageTypeInstance,
+  type PostgresEnumStorageEntry,
+  type SqlStorage,
+  type StorageColumn,
+  type StorageTable,
+  type StorageTypeInstance,
+  toStorageTypeInstance,
+  type UniqueConstraint,
 } from '@prisma-next/sql-contract/types';
 import { defaultIndexName } from '@prisma-next/sql-schema-ir/naming';
 import type {
@@ -51,7 +55,7 @@ export type DefaultRenderer = (def: ColumnDefault, column: StorageColumn) => str
 function convertColumn(
   name: string,
   column: StorageColumn,
-  storageTypes: Record<string, StorageTypeInstance>,
+  storageTypes: ResolvedStorageTypes,
   expandNativeType: NativeTypeExpander | undefined,
   renderDefault: DefaultRenderer | undefined,
 ): SqlColumnIR {
@@ -82,9 +86,21 @@ function convertColumn(
   };
 }
 
+/**
+ * `storageTypes` is polymorphic per Decision 18 (Option B) — codec-typed
+ * entries match `StorageTypeInstance`; enum entries match the structural
+ * `PostgresEnumStorageEntry` shape (Postgres-only; cross-domain layering
+ * keeps target IR classes out of the family layer). Both shapes resolve
+ * into the same `(codecId, nativeType, typeParams)` triplet at the
+ * column-resolution boundary so downstream walks stay uniform.
+ */
+type ResolvedStorageTypes = Readonly<
+  Record<string, StorageTypeInstance | PostgresEnumStorageEntry>
+>;
+
 function resolveColumnTypeMetadata(
   column: StorageColumn,
-  storageTypes: Record<string, StorageTypeInstance>,
+  storageTypes: ResolvedStorageTypes,
 ): Pick<StorageColumn, 'codecId' | 'nativeType' | 'typeParams'> {
   if (!column.typeRef) {
     return column;
@@ -95,11 +111,23 @@ function resolveColumnTypeMetadata(
       `Column references storage type "${column.typeRef}" but it is not defined in storage.types.`,
     );
   }
-  return {
-    codecId: referenced.codecId,
-    nativeType: referenced.nativeType,
-    typeParams: referenced.typeParams,
-  };
+  if (isPostgresEnumStorageEntry(referenced)) {
+    return {
+      codecId: referenced.codecId,
+      nativeType: referenced.nativeType,
+      typeParams: { values: referenced.values } as Record<string, unknown>,
+    };
+  }
+  if (isStorageTypeInstance(referenced)) {
+    return {
+      codecId: referenced.codecId,
+      nativeType: referenced.nativeType,
+      typeParams: referenced.typeParams,
+    };
+  }
+  throw new Error(
+    `Storage type "${column.typeRef}" has an unknown polymorphic kind; expected codec-instance or postgres-enum.`,
+  );
 }
 
 function convertUnique(unique: UniqueConstraint): SqlUniqueIR {
@@ -129,7 +157,7 @@ function convertForeignKey(fk: ForeignKey): SqlForeignKeyIR {
 function convertTable(
   name: string,
   table: StorageTable,
-  storageTypes: Record<string, StorageTypeInstance>,
+  storageTypes: ResolvedStorageTypes,
   expandNativeType: NativeTypeExpander | undefined,
   renderDefault: DefaultRenderer | undefined,
 ): SqlTableIR {
@@ -250,7 +278,7 @@ export function contractToSchemaIR(
   }
 
   const storage = contract.storage;
-  const storageTypes = storage.types ?? {};
+  const storageTypes = (storage.types ?? {}) as ResolvedStorageTypes;
   const tables: Record<string, SqlTableIR> = {};
   for (const [tableName, tableDef] of Object.entries(storage.tables)) {
     tables[tableName] = convertTable(
@@ -274,11 +302,32 @@ function deriveAnnotations(
   storage: SqlStorage,
   annotationNamespace: string,
 ): SqlAnnotations | undefined {
-  if (!storage.types || Object.keys(storage.types).length === 0) return undefined;
-  // Re-key by nativeType to match the structure produced by introspection
-  const byNativeType: Record<string, (typeof storage.types)[string]> = {};
-  for (const typeInstance of Object.values(storage.types)) {
-    byNativeType[typeInstance.nativeType] = typeInstance;
+  const types = storage.types as ResolvedStorageTypes | undefined;
+  if (!types || Object.keys(types).length === 0) return undefined;
+  // Re-key by nativeType, normalising every variant to the codec-typed
+  // annotation shape `{codecId, nativeType, typeParams}` produced by the
+  // adapter introspector (`introspectPostgresEnumTypes` writes that shape;
+  // see also `enum-planning.ts § readExistingEnumValues`, which reads
+  // `existing.codecId` + `existing.typeParams.values`). Without this
+  // normalisation, the projector would emit the raw
+  // `PostgresEnumStorageEntry` shape (top-level `values`, no `typeParams`)
+  // and downstream Schema IR consumers that walk the codec-typed shape
+  // would see enum entries as new (e.g. the planner emits a fresh
+  // `CreateEnumTypeCall` instead of the rebuild recipe). Unknown future
+  // kinds without `nativeType` are skipped rather than crashing.
+  const byNativeType: Record<string, StorageTypeInstance> = {};
+  for (const typeInstance of Object.values(types)) {
+    if (isPostgresEnumStorageEntry(typeInstance)) {
+      byNativeType[typeInstance.nativeType] = toStorageTypeInstance({
+        codecId: typeInstance.codecId,
+        nativeType: typeInstance.nativeType,
+        typeParams: { values: typeInstance.values },
+      });
+      continue;
+    }
+    if (isStorageTypeInstance(typeInstance)) {
+      byNativeType[typeInstance.nativeType] = typeInstance;
+    }
   }
   return { [annotationNamespace]: { storageTypes: byNativeType } };
 }

package/src/core/migrations/types.ts

@@ -1,6 +1,7 @@
 import type { Contract } from '@prisma-next/contract/types';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
+  ContractSerializer,
   ContractSpace,
   ControlAdapterDescriptor,
   ControlDriverInstance,
@@ -18,6 +19,7 @@ import type {
   OperationContext,
   OpFactoryCall,
   SchemaIssue,
+  SchemaVerifier,
 } from '@prisma-next/framework-components/control';
 import type {
   SqlStorage,
@@ -313,9 +315,10 @@ export interface SqlMigrationPlannerPlanOptions {
    * or `null` for reconciliation flows that have no prior contract.
    *
    * Required at every call site so the structural fact "I have a prior
-   * contract / I don't" is visible in the type. `migration plan` supplies
-   * the previous bundle's `metadata.toContract`; `db update` / `db init`
-   * reconcile against the live schema and pass `null`. Strategies that
+   * contract / I don't" is visible in the type. `migration plan` reads
+   * the predecessor bundle's `end-contract.json` from disk and passes
+   * the parsed value; `db update` / `db init` reconcile against the
+   * live schema and pass `null`. Strategies that
    * need from/to column-shape comparisons (unsafe type change, nullability
    * tightening) use this to decide whether to emit `dataTransform`
    * placeholders; they short-circuit when it is `null`.
@@ -463,9 +466,26 @@ export interface MultiSpaceRunnerFailure extends SqlMigrationRunnerFailure {
 
 export type MultiSpaceRunnerResult = Result<MultiSpaceRunnerSuccessValue, MultiSpaceRunnerFailure>;
 
-export interface SqlControlTargetDescriptor<TTargetId extends string, TTargetDetails>
-  extends MigratableTargetDescriptor<'sql', TTargetId, SqlControlFamilyInstance> {
+export interface SqlControlTargetDescriptor<
+  TTargetId extends string,
+  TTargetDetails,
+  TContract extends Contract<SqlStorage> = Contract<SqlStorage>,
+> extends MigratableTargetDescriptor<'sql', TTargetId, SqlControlFamilyInstance> {
   readonly queryOperations?: () => SqlOperationDescriptors;
+  /**
+   * JSON ⇄ class boundary for the SQL target's contract. The descriptor
+   * composes a concrete `SqlContractSerializerBase` subclass; the rest
+   * of the control stack reaches `descriptor.contractSerializer` rather
+   * than importing a per-target deserialization function.
+   */
+  readonly contractSerializer: ContractSerializer<TContract>;
+  /**
+   * Per-target schema verifier walking the contract against
+   * `SqlSchemaIR`. The descriptor composes a concrete
+   * `SqlSchemaVerifierBase` subclass; the family-shared walk lives on
+   * the base, the target-specific dispatch on the subclass.
+   */
+  readonly schemaVerifier: SchemaVerifier<TContract, SqlSchemaIR>;
   createPlanner(family: SqlControlFamilyInstance): SqlMigrationPlanner<TTargetDetails>;
   createRunner(family: SqlControlFamilyInstance): SqlMigrationRunner<TTargetDetails>;
 }

package/src/core/schema-verify/verify-sql-schema.ts

@@ -14,10 +14,13 @@ import type {
   SchemaVerificationNode,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
-import type {
-  SqlStorage,
-  StorageColumn,
-  StorageTypeInstance,
+import {
+  isPostgresEnumStorageEntry,
+  isStorageTypeInstance,
+  type PostgresEnumStorageEntry,
+  type SqlStorage,
+  type StorageColumn,
+  type StorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
 import { canonicalStringify } from '@prisma-next/utils/canonical-stringify';
@@ -80,6 +83,21 @@ export interface VerifySqlSchemaOptions {
    * with contract native types (e.g., Postgres 'varchar' → 'character varying').
    */
   readonly normalizeNativeType?: NativeTypeNormalizer;
+  /**
+   * Bridging adapter that resolves the existing values for a `PostgresEnumStorageEntry`
+   * (looked up by its native type) from the introspected schema IR. Targets
+   * supply this so the family-level verifier can walk `PostgresEnumStorageEntry` instances
+   * natively without reaching into target-specific `schema.annotations`
+   * shapes itself.
+   *
+   * Returning `null` indicates the type is missing from the database; the
+   * verifier emits a `type_missing` issue. A non-null array triggers a
+   * value-set comparison against the contract's `PostgresEnumStorageEntry.values`.
+   */
+  readonly resolveExistingEnumValues?: (
+    schema: SqlSchemaIR,
+    enumType: PostgresEnumStorageEntry,
+  ) => readonly string[] | null;
 }
 
 /**
@@ -101,6 +119,7 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
     typeMetadataRegistry,
     normalizeDefault,
     normalizeNativeType,
+    resolveExistingEnumValues,
   } = options;
   const startTime = Date.now();
 
@@ -109,7 +128,9 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
 
   const { contractStorageHash, contractProfileHash, contractTarget } =
     extractContractMetadata(contract);
-  const storageTypes = contract.storage.types ?? {};
+  const storageTypes = (contract.storage.types ?? {}) as Readonly<
+    Record<string, PostgresEnumStorageEntry | StorageTypeInstance>
+  >;
   const { issues, rootChildren } = verifySchemaTables({
     contract,
     schema,
@@ -123,15 +144,28 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
 
   validateFrameworkComponentsForExtensions(contract, options.frameworkComponents);
 
-  // Verify storage type instances via codec control hooks (pure, deterministic)
+  // Verify storage type instances. PostgresEnumStorageEntry entries are walked
+  // natively (using the bridging adapter `resolveExistingEnumValues`);
+  // remaining codec-typed entries continue to dispatch through the
+  // generic codec-hook `verifyType` path.
   const storageTypeEntries = Object.entries(storageTypes);
   if (storageTypeEntries.length > 0) {
     const typeNodes: SchemaVerificationNode[] = [];
     for (const [typeName, typeInstance] of storageTypeEntries) {
-      const hook = codecHooks.get(typeInstance.codecId);
-      const typeIssues = hook?.verifyType
-        ? hook.verifyType({ typeName, typeInstance, schema })
-        : [];
+      let typeIssues: readonly SchemaIssue[];
+      if (isPostgresEnumStorageEntry(typeInstance)) {
+        typeIssues = verifyEnumType({
+          typeName,
+          typeInstance,
+          schema,
+          resolveExistingEnumValues,
+        });
+      } else if (isStorageTypeInstance(typeInstance)) {
+        const hook = codecHooks.get(typeInstance.codecId);
+        typeIssues = hook?.verifyType ? hook.verifyType({ typeName, typeInstance, schema }) : [];
+      } else {
+        typeIssues = [];
+      }
       if (typeIssues.length > 0) {
         issues.push(...typeIssues);
       }
@@ -214,6 +248,56 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
 
 type VerificationStatus = 'pass' | 'warn' | 'fail';
 
+/**
+ * Native verification walk for `PostgresEnumStorageEntry` instances (no codec hook).
+ *
+ * Bridges the native `PostgresEnumStorageEntry.values` against the introspected schema
+ * IR via the target-supplied `resolveExistingEnumValues` adapter. Without an
+ * adapter, the verifier conservatively reports the enum as missing — there
+ * is no other way for the family layer to learn about live enum types.
+ */
+function verifyEnumType(options: {
+  readonly typeName: string;
+  readonly typeInstance: PostgresEnumStorageEntry;
+  readonly schema: SqlSchemaIR;
+  readonly resolveExistingEnumValues?:
+    | ((schema: SqlSchemaIR, enumType: PostgresEnumStorageEntry) => readonly string[] | null)
+    | undefined;
+}): readonly SchemaIssue[] {
+  const { typeName, typeInstance, schema, resolveExistingEnumValues } = options;
+  const desired = typeInstance.values;
+  const existing = resolveExistingEnumValues?.(schema, typeInstance) ?? null;
+  if (!existing) {
+    return [
+      {
+        kind: 'type_missing',
+        typeName,
+        message: `Type "${typeName}" is missing from database`,
+      },
+    ];
+  }
+  if (arraysEqual(existing, desired)) {
+    return [];
+  }
+  const existingSet = new Set(existing);
+  const desiredSet = new Set(desired);
+  const addedValues = desired.filter((v) => !existingSet.has(v));
+  const removedValues = existing.filter((v) => !desiredSet.has(v));
+  const message =
+    removedValues.length === 0
+      ? `Enum type "${typeName}" needs new values: ${addedValues.join(', ')}`
+      : `Enum type "${typeName}" values changed (requires rebuild): +[${addedValues.join(', ')}] -[${removedValues.join(', ')}]`;
+  return [
+    {
+      kind: 'enum_values_changed' as const,
+      typeName,
+      addedValues,
+      removedValues,
+      message,
+    },
+  ];
+}
+
 function extractContractMetadata(contract: Contract<SqlStorage>): {
   contractStorageHash: SqlStorage['storageHash'];
   contractProfileHash?: Contract<SqlStorage>['profileHash'] | undefined;
@@ -235,7 +319,7 @@ function verifySchemaTables(options: {
   strict: boolean;
   typeMetadataRegistry: ReadonlyMap<string, { nativeType?: string }>;
   codecHooks: Map<string, CodecControlHooks>;
-  storageTypes: Record<string, StorageTypeInstance>;
+  storageTypes: Readonly<Record<string, StorageTypeInstance | PostgresEnumStorageEntry>>;
   normalizeDefault?: DefaultNormalizer;
   normalizeNativeType?: NativeTypeNormalizer;
 }): { issues: SchemaIssue[]; rootChildren: SchemaVerificationNode[] } {
@@ -329,7 +413,7 @@ function verifyTableChildren(options: {
   strict: boolean;
   typeMetadataRegistry: ReadonlyMap<string, { nativeType?: string }>;
   codecHooks: Map<string, CodecControlHooks>;
-  storageTypes: Record<string, StorageTypeInstance>;
+  storageTypes: Readonly<Record<string, StorageTypeInstance | PostgresEnumStorageEntry>>;
   normalizeDefault?: DefaultNormalizer;
   normalizeNativeType?: NativeTypeNormalizer;
 }): SchemaVerificationNode[] {
@@ -487,7 +571,7 @@ function collectContractColumnNodes(options: {
   strict: boolean;
   typeMetadataRegistry: ReadonlyMap<string, { nativeType?: string }>;
   codecHooks: Map<string, CodecControlHooks>;
-  storageTypes: Record<string, StorageTypeInstance>;
+  storageTypes: Readonly<Record<string, StorageTypeInstance | PostgresEnumStorageEntry>>;
   normalizeDefault?: DefaultNormalizer;
   normalizeNativeType?: NativeTypeNormalizer;
 }): SchemaVerificationNode[] {
@@ -594,7 +678,7 @@ function verifyColumn(options: {
   strict: boolean;
   typeMetadataRegistry: ReadonlyMap<string, { nativeType?: string }>;
   codecHooks: Map<string, CodecControlHooks>;
-  storageTypes: Record<string, StorageTypeInstance>;
+  storageTypes: Readonly<Record<string, StorageTypeInstance | PostgresEnumStorageEntry>>;
   normalizeDefault?: DefaultNormalizer;
   normalizeNativeType?: NativeTypeNormalizer;
 }): SchemaVerificationNode {
@@ -937,7 +1021,7 @@ function validateFrameworkComponentsForExtensions(
  */
 function renderExpectedNativeType(
   contractColumn: Contract<SqlStorage>['storage']['tables'][string]['columns'][string],
-  storageTypes: Record<string, StorageTypeInstance>,
+  storageTypes: Readonly<Record<string, StorageTypeInstance | PostgresEnumStorageEntry>>,
   codecHooks: Map<string, CodecControlHooks>,
   context?: {
     readonly tableName: string;
@@ -967,7 +1051,7 @@ function renderExpectedNativeType(
 
 function resolveContractColumnTypeMetadata(
   contractColumn: StorageColumn,
-  storageTypes: Record<string, StorageTypeInstance>,
+  storageTypes: Readonly<Record<string, StorageTypeInstance | PostgresEnumStorageEntry>>,
   context?: {
     readonly tableName: string;
     readonly columnName: string;
@@ -987,11 +1071,23 @@ function resolveContractColumnTypeMetadata(
     );
   }
 
-  return {
-    codecId: referencedType.codecId,
-    nativeType: referencedType.nativeType,
-    typeParams: referencedType.typeParams,
-  };
+  if (isPostgresEnumStorageEntry(referencedType)) {
+    return {
+      codecId: referencedType.codecId,
+      nativeType: referencedType.nativeType,
+      typeParams: { values: referencedType.values } as Record<string, unknown>,
+    };
+  }
+  if (isStorageTypeInstance(referencedType)) {
+    return {
+      codecId: referencedType.codecId,
+      nativeType: referencedType.nativeType,
+      typeParams: referencedType.typeParams,
+    };
+  }
+  throw new Error(
+    `Storage type "${contractColumn.typeRef}" has an unknown polymorphic kind; expected codec-instance or postgres-enum.`,
+  );
 }
 
 /**

package/src/exports/control.ts

@@ -13,7 +13,7 @@ export type {
 } from '@prisma-next/framework-components/control';
 export { assembleAuthoringContributions } from '@prisma-next/framework-components/control';
 export { extractCodecControlHooks } from '../core/assembly';
-export type { SchemaVerifyOptions, SqlControlFamilyInstance } from '../core/control-instance';
+export type { SqlControlFamilyInstance } from '../core/control-instance';
 export type {
   ContractToSchemaIROptions,
   DefaultRenderer,

package/src/exports/ir.ts

@@ -0,0 +1,6 @@
+export { SqlContractSerializer } from '../core/ir/sql-contract-serializer';
+export {
+  SqlContractSerializerBase,
+  type SqlEntityHydrationFactory,
+} from '../core/ir/sql-contract-serializer-base';
+export { SqlSchemaVerifierBase } from '../core/ir/sql-schema-verifier-base';