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

package/src/core/migrations/planner.ts

@@ -2,13 +2,17 @@ import type { Contract } from '@prisma-next/contract/types';
 import type {
   MigrationOperationPolicy,
   SqlMigrationPlannerPlanOptions,
+  SqlPlannerConflict,
   SqlPlannerFailureResult,
 } from '@prisma-next/family-sql/control';
 import {
   extractCodecControlHooks,
+  partitionCallsByControlPolicy,
+  partitionIssuesByControlPolicy,
   planFieldEventOperations,
   plannerFailure,
 } from '@prisma-next/family-sql/control';
+import type { Lowerer } from '@prisma-next/family-sql/control-adapter';
 import { verifySqlSchema } from '@prisma-next/family-sql/schema-verify';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
@@ -18,10 +22,18 @@ import type {
   SchemaIssue,
 } from '@prisma-next/framework-components/control';
 import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
+import { blindCast } from '@prisma-next/utils/casts';
 import { parsePostgresDefault } from '../default-normalizer';
 import { normalizeSchemaNativeType } from '../native-type-normalizer';
+import {
+  formatPostgresControlPolicySubjectLabel,
+  resolvePostgresCallControlPolicySubject,
+  resolvePostgresIssueControlPolicySubject,
+  resolvePostgresIssueCreationFactoryName,
+} from './control-policy';
 import { createResolveExistingEnumValues } from './enum-planning';
 import { planIssues } from './issue-planner';
+import type { PostgresOpFactoryCall } from './op-factory-call';
 import { TypeScriptRenderablePostgresMigration } from './planner-produced-postgres-migration';
 import { postgresPlannerStrategies } from './planner-strategies';
 import { verifyPostgresNamespacePresence } from './verify-postgres-namespaces';
@@ -40,8 +52,8 @@ type VerifySqlSchemaOptionsWithComponents = Parameters<typeof verifySqlSchema>[0
   readonly frameworkComponents: PlannerFrameworkComponents;
 };
 
-export function createPostgresMigrationPlanner(): PostgresMigrationPlanner {
-  return new PostgresMigrationPlanner();
+export function createPostgresMigrationPlanner(lowerer: Lowerer): PostgresMigrationPlanner {
+  return new PostgresMigrationPlanner(lowerer);
 }
 
 /**
@@ -52,7 +64,11 @@ export function createPostgresMigrationPlanner(): PostgresMigrationPlanner {
  * uniformly.
  */
 export type PostgresPlanResult =
-  | { readonly kind: 'success'; readonly plan: TypeScriptRenderablePostgresMigration }
+  | {
+      readonly kind: 'success';
+      readonly plan: TypeScriptRenderablePostgresMigration;
+      readonly warnings?: readonly SqlPlannerConflict[];
+    }
   | SqlPlannerFailureResult;
 
 /**
@@ -72,6 +88,12 @@ export type PostgresPlanResult =
  * authoring surface.
  */
 export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgres'> {
+  readonly #lowerer: Lowerer | undefined;
+
+  constructor(lowerer?: Lowerer) {
+    this.#lowerer = lowerer;
+  }
+
   plan(options: {
     readonly contract: unknown;
     readonly schema: unknown;
@@ -114,6 +136,7 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
         to: context.toHash,
       },
       spaceId,
+      this.#lowerer,
     );
   }
 
@@ -131,8 +154,25 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
     const codecHooks = extractCodecControlHooks(options.frameworkComponents);
     const storageTypes = options.contract.storage.types ?? {};
 
-    const result = planIssues({
+    // Input-side control-policy partition. `external` / `observed` subjects
+    // — and non-creation issues for `tolerated` subjects — are dropped from
+    // the planner's input entirely; the planner never observes them, never
+    // diffs them, never generates DDL for them. Suppression warnings are
+    // built directly from the suppressed partition (one per subject), so the
+    // user-visible message survives even when the planner would have failed
+    // to model the subject's live shape.
+    const issuePartition = partitionIssuesByControlPolicy({
       issues: schemaIssues,
+      contract: options.contract,
+      resolveControlPolicySubject: (issue) =>
+        resolvePostgresIssueControlPolicySubject(issue, options.contract),
+      resolveCreationFactoryName: resolvePostgresIssueCreationFactoryName,
+      formatSubjectLabel: (factoryName, subject) =>
+        formatPostgresControlPolicySubjectLabel(factoryName, subject, options.contract),
+    });
+
+    const result = planIssues({
+      issues: issuePartition.plannable,
       toContract: options.contract,
       // `fromContract` is only supplied by `migration plan`. It is `null` for
       // `db update` / `db init`, which means data-safety strategies needing
@@ -163,10 +203,26 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       newContract: options.contract,
       codecHooks,
     });
-    // Codec-emitted calls already conform to `OpFactoryCall` — render +
-    // toOp + importRequirements ride directly through the same emit path
-    // as structural ops, no `RawSqlCall` wrap.
-    const calls = [...result.value.calls, ...fieldEventOps];
+    // Codec hook ops are target-agnostic `OpFactoryCall`; Postgres planning
+    // lifts them at this integration boundary (see field-event-planner JSDoc).
+    const fieldEventPostgresCalls = blindCast<
+      readonly PostgresOpFactoryCall[],
+      'Codec hook ops conform to PostgresOpFactoryCall at the app emitter boundary'
+    >(fieldEventOps);
+    const fieldEventPartition = partitionCallsByControlPolicy({
+      calls: fieldEventPostgresCalls,
+      contract: options.contract,
+      resolveControlPolicySubject: (call) =>
+        resolvePostgresCallControlPolicySubject(call, options.contract),
+      resolveFactoryName: (call) => call.factoryName,
+      formatSubjectLabel: (factoryName, subject) =>
+        formatPostgresControlPolicySubjectLabel(factoryName, subject, options.contract),
+    });
+    const calls = [...result.value.calls, ...fieldEventPartition.kept];
+    const warnings: SqlPlannerConflict[] = [
+      ...issuePartition.warnings,
+      ...fieldEventPartition.warnings,
+    ];
 
     return Object.freeze({
       kind: 'success' as const,
@@ -177,7 +233,9 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
           to: options.contract.storage.storageHash,
         },
         options.spaceId,
+        this.#lowerer,
       ),
+      ...(warnings.length > 0 ? { warnings: Object.freeze(warnings) } : {}),
     });
   }
 

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

@@ -3,8 +3,11 @@ import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control'
 import type { SqlControlAdapter } from '@prisma-next/family-sql/control-adapter';
 import { Migration as SqlMigration } from '@prisma-next/family-sql/migration';
 import type { ControlStack } from '@prisma-next/framework-components/control';
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import type { DdlColumn, DdlTableConstraint } from '@prisma-next/sql-relational-core/ast';
 import { errorPostgresMigrationStackMissing } from '../errors';
+import { CreateSchemaCall, CreateTableCall } from './op-factory-call';
 import { type DataTransformOptions, dataTransform } from './operations/data-transform';
 import type { PostgresPlanTargetDetails } from './planner-target-details';
 
@@ -67,4 +70,42 @@ export abstract class PostgresMigration extends SqlMigration<
     }
     return dataTransform(contract, name, options, this.controlAdapter);
   }
+
+  /**
+   * Emit a `CREATE TABLE` migration operation. Builds a typed DDL node from
+   * the supplied options and lowers it through the stored control adapter.
+   * Throws if no adapter is present (i.e. migration instantiated without a stack).
+   */
+  protected createTable(options: {
+    readonly schema?: string;
+    readonly table: string;
+    readonly ifNotExists?: boolean;
+    readonly columns: readonly DdlColumn[];
+    readonly constraints?: readonly DdlTableConstraint[];
+  }): SqlMigrationPlanOperation<PostgresPlanTargetDetails> {
+    if (!this.controlAdapter) {
+      throw errorPostgresMigrationStackMissing();
+    }
+    return new CreateTableCall(
+      options.schema ?? UNBOUND_NAMESPACE_ID,
+      options.table,
+      options.columns,
+      options.constraints,
+    ).toOp(this.controlAdapter);
+  }
+
+  /**
+   * Emit a `CREATE SCHEMA` migration operation. Builds a typed DDL node from
+   * the supplied options and lowers it through the stored control adapter.
+   * Throws if no adapter is present (i.e. migration instantiated without a stack).
+   */
+  protected createSchema(options: {
+    readonly schema: string;
+    readonly ifNotExists?: boolean;
+  }): SqlMigrationPlanOperation<PostgresPlanTargetDetails> {
+    if (!this.controlAdapter) {
+      throw errorPostgresMigrationStackMissing();
+    }
+    return new CreateSchemaCall(options.schema).toOp(this.controlAdapter);
+  }
 }

package/src/core/migrations/render-ops.ts

@@ -1,5 +1,7 @@
 import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control';
+import type { Lowerer } from '@prisma-next/family-sql/control-adapter';
 import type { OpFactoryCall } from '@prisma-next/framework-components/control';
+import { blindCast } from '@prisma-next/utils/casts';
 import type { PostgresPlanTargetDetails } from './planner-target-details';
 
 type Op = SqlMigrationPlanOperation<PostgresPlanTargetDetails>;
@@ -23,9 +25,12 @@ function assertPostgresOp(
   }
 }
 
-export function renderOps(calls: readonly OpFactoryCall[]): Op[] {
+export function renderOps(calls: readonly OpFactoryCall[], lowerer?: Lowerer): Op[] {
   return calls.map((c) => {
-    const op = c.toOp();
+    const op = blindCast<
+      { toOp(lowerer?: Lowerer): ReturnType<OpFactoryCall['toOp']> },
+      'PG OpFactoryCall.toOp accepts an optional Lowerer; the framework interface omits it because not all targets need a lowerer — the PG target overrides with this extended signature'
+    >(c).toOp(lowerer);
     assertPostgresOp(op, c.factoryName);
     return op;
   });

package/src/core/migrations/render-typescript.ts

@@ -46,7 +46,7 @@ export function renderCallsToTypeScript(
   meta: RenderMigrationMeta,
 ): string {
   const imports = buildImports(calls);
-  const operationsBody = calls.map((c) => c.renderTypeScript()).join(',\n');
+  const operationsBody = calls.map((c) => renderCall(c)).join(',\n');
 
   return [
     shebangLineFor(detectScaffoldRuntime()),
@@ -66,6 +66,10 @@ export function renderCallsToTypeScript(
   ].join('\n');
 }
 
+function renderCall(call: OpFactoryCall): string {
+  return call.renderTypeScript();
+}
+
 function buildImports(calls: ReadonlyArray<OpFactoryCall>): string {
   const requirements: ImportRequirement[] = [...BASE_IMPORTS];
   for (const call of calls) {

package/src/core/migrations/runner.ts

@@ -1,4 +1,4 @@
-import type { ContractMarkerRecord } from '@prisma-next/contract/types';
+import type { Contract, ContractMarkerRecord } from '@prisma-next/contract/types';
 import type {
   MigrationOperationPolicy,
   SqlControlFamilyInstance,
@@ -13,13 +13,12 @@ import type {
 } from '@prisma-next/family-sql/control';
 import { runnerFailure, runnerSuccess } from '@prisma-next/family-sql/control';
 import { verifySqlSchema } from '@prisma-next/family-sql/schema-verify';
-import type {
-  ControlDriverInstance,
-  MigrationRunnerResult,
-} from '@prisma-next/framework-components/control';
+import type { MigrationRunnerResult } from '@prisma-next/framework-components/control';
 import { APP_SPACE_ID } from '@prisma-next/framework-components/control';
 import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
+import type { SqlControlDriverInstance, SqlStorage } from '@prisma-next/sql-contract/types';
 import { SqlQueryError } from '@prisma-next/sql-errors';
+import type { LoweredStatement } from '@prisma-next/sql-relational-core/ast';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { Result } from '@prisma-next/utils/result';
 import { notOk, ok, okVoid } from '@prisma-next/utils/result';
@@ -27,14 +26,6 @@ import { parsePostgresDefault } from '../default-normalizer';
 import { normalizeSchemaNativeType } from '../native-type-normalizer';
 import { createResolveExistingEnumValues } from './enum-planning';
 import type { PostgresPlanTargetDetails } from './planner-target-details';
-import {
-  buildLedgerInsertStatement,
-  buildMergeMarkerStatements,
-  ensureLedgerTableStatement,
-  ensureMarkerTableStatement,
-  ensurePrismaContractSchemaStatement,
-  type SqlStatement,
-} from './statement-builders';
 
 interface ApplyPlanSuccessValue {
   readonly operationsExecuted: number;
@@ -107,7 +98,7 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
     if (!policyCheck.ok) return policyCheck;
 
     await this.acquireLock(driver, lockKey);
-    const ensureResult = await this.ensureControlTables(driver);
+    const ensureResult = await this.ensureControlTables(driver, options.destinationContract);
     if (!ensureResult.ok) return ensureResult;
     const existingMarker = await this.family.readMarker({ driver, space });
 
@@ -165,8 +156,9 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
       isSelfEdge && applyValue.operationsExecuted === 0 && incomingIsSubsetOfExisting;
 
     if (!isSelfEdgeNoOp) {
-      await this.upsertMarker(driver, options, existingMarker, space);
-      await this.recordLedgerEntry(driver, options, existingMarker, applyValue.executedOperations);
+      const markerResult = await this.upsertMarker(driver, options, existingMarker, space);
+      if (!markerResult.ok) return markerResult;
+      await this.recordLedgerEntries(driver, options, applyValue.executedOperations);
     }
 
     return runnerSuccess({
@@ -176,7 +168,7 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
   }
 
   async execute(options: {
-    readonly driver: ControlDriverInstance<'sql', string>;
+    readonly driver: SqlControlDriverInstance<string>;
     readonly perSpaceOptions: ReadonlyArray<
       SqlMigrationRunnerExecuteOptions<PostgresPlanTargetDetails>
     >;
@@ -282,18 +274,22 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
 
   private async ensureControlTables(
     driver: SqlMigrationRunnerExecuteOptions<PostgresPlanTargetDetails>['driver'],
+    contract: Contract<SqlStorage>,
   ): Promise<Result<void, SqlMigrationRunnerFailure>> {
-    await this.executeStatement(driver, ensurePrismaContractSchemaStatement);
-    // Pre-1.0 zero-range guardrail: detect a pre-cleanup single-row
-    // marker table (no `space` column) and surface a structured failure
-    // rather than silently auto-migrating it to the per-space shape.
-    // See `specs/framework-mechanism.spec.md § 2`.
+    const lowererContext = { contract };
+    const bootstrapQueries = this.family.bootstrapControlTableQueries();
+    const [schemaQuery, ...tableQueries] = bootstrapQueries;
+    if (schemaQuery === undefined) {
+      throw new Error('Postgres control-table bootstrap must include CREATE SCHEMA');
+    }
+    await this.executeStatement(driver, this.family.lowerAst(schemaQuery, lowererContext));
     const legacyDetection = await this.detectLegacyMarkerShape(driver);
     if (!legacyDetection.ok) {
       return legacyDetection;
     }
-    await this.executeStatement(driver, ensureMarkerTableStatement);
-    await this.executeStatement(driver, ensureLedgerTableStatement);
+    for (const query of tableQueries) {
+      await this.executeStatement(driver, this.family.lowerAst(query, lowererContext));
+    }
     return okVoid();
   }
 
@@ -594,43 +590,75 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
     options: SqlMigrationRunnerExecuteOptions<PostgresPlanTargetDetails>,
     existingMarker: ContractMarkerRecord | null,
     space: string,
-  ): Promise<void> {
-    const incomingInvariants = options.plan.providedInvariants ?? [];
-    const writeStatements = buildMergeMarkerStatements({
-      space,
+  ): Promise<Result<void, SqlMigrationRunnerFailure>> {
+    const destination = {
       storageHash: options.plan.destination.storageHash,
       profileHash:
         options.plan.destination.profileHash ??
         options.destinationContract.profileHash ??
         options.plan.destination.storageHash,
-      contractJson: options.destinationContract,
-      canonicalVersion: null,
-      meta: {},
-      invariants: incomingInvariants,
+      invariants: options.plan.providedInvariants ?? [],
+    };
+    if (!existingMarker) {
+      await this.family.initMarker({ driver, space, destination });
+      return okVoid();
+    }
+    const updated = await this.family.updateMarker({
+      driver,
+      space,
+      expectedFrom: existingMarker.storageHash,
+      destination,
     });
-    const statement = existingMarker ? writeStatements.update : writeStatements.insert;
-    await this.executeStatement(driver, statement);
+    if (!updated) {
+      return runnerFailure(
+        'MARKER_CAS_FAILURE',
+        'Marker was modified by another process during migration execution.',
+        {
+          meta: {
+            space,
+            expectedStorageHash: existingMarker.storageHash,
+            destinationStorageHash: options.plan.destination.storageHash,
+          },
+        },
+      );
+    }
+    return okVoid();
   }
 
-  private async recordLedgerEntry(
+  private async recordLedgerEntries(
     driver: SqlMigrationRunnerExecuteOptions<PostgresPlanTargetDetails>['driver'],
     options: SqlMigrationRunnerExecuteOptions<PostgresPlanTargetDetails>,
-    existingMarker: ContractMarkerRecord | null,
     executedOperations: readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[],
   ): Promise<void> {
-    const ledgerStatement = buildLedgerInsertStatement({
-      originStorageHash: existingMarker?.storageHash ?? null,
-      originProfileHash: existingMarker?.profileHash ?? null,
-      destinationStorageHash: options.plan.destination.storageHash,
-      destinationProfileHash:
-        options.plan.destination.profileHash ??
-        options.destinationContract.profileHash ??
-        options.plan.destination.storageHash,
-      contractJsonBefore: existingMarker?.contractJson ?? null,
-      contractJsonAfter: options.destinationContract,
-      operations: executedOperations,
-    });
-    await this.executeStatement(driver, ledgerStatement);
+    const plan = options.plan;
+    const space = plan.spaceId;
+    const edges = options.migrationEdges;
+    const totalEdgeOps = edges.reduce((sum, edge) => sum + edge.operationCount, 0);
+    if (totalEdgeOps !== plan.operations.length) {
+      throw new Error(
+        `Ledger write: plan.operations length (${plan.operations.length}) does not match sum of migrationEdges operationCount (${totalEdgeOps})`,
+      );
+    }
+    // The ledger records the operations as executed — idempotency-skipped ops
+    // are substituted with skip records (empty `execute`) by `applyPlan`, so the
+    // journal reflects what actually ran rather than the raw plan.
+    let offset = 0;
+    for (const edge of edges) {
+      const edgeOps = executedOperations.slice(offset, offset + edge.operationCount);
+      offset += edge.operationCount;
+      await this.family.writeLedgerEntry({
+        driver,
+        space,
+        entry: {
+          edgeId: `${edge.from}->${edge.to}`,
+          from: edge.from,
+          to: edge.to,
+          migrationName: edge.dirName,
+          migrationHash: edge.migrationHash,
+          operations: edgeOps,
+        },
+      });
+    }
   }
 
   private async acquireLock(
@@ -660,7 +688,7 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
 
   private async executeStatement(
     driver: SqlMigrationRunnerExecuteOptions<PostgresPlanTargetDetails>['driver'],
-    statement: SqlStatement,
+    statement: LoweredStatement,
   ): Promise<void> {
     if (statement.params.length > 0) {
       await driver.query(statement.sql, statement.params);

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

@@ -14,12 +14,8 @@ import {
   NamespaceBase,
   UNBOUND_NAMESPACE_ID,
 } from '@prisma-next/framework-components/ir';
-import type {
-  SqlNamespaceTablesInput,
-  SqlStorage,
-  SqlStorageTypeEntry,
-  StorageTable,
-} from '@prisma-next/sql-contract/types';
+import type { SqlNamespaceTablesInput, SqlStorage } from '@prisma-next/sql-contract/types';
+import { blindCast } from '@prisma-next/utils/casts';
 import type { JsonObject } from '@prisma-next/utils/json';
 import type { Type } from 'arktype';
 import { postgresAuthoringEntityTypes } from './authoring';
@@ -57,9 +53,8 @@ function collectEntityRegistryContributions(namespace: AuthoringEntityTypeNamesp
       if (isAuthoringEntityTypeDescriptor(value)) {
         if (isAuthoringEntityTypeFactoryOutput(value.output)) {
           const { factory } = value.output;
-          entityTypeRegistry.set(
-            value.discriminator,
-            (raw) => factory(raw, POSTGRES_AUTHORING_CTX) as SqlStorageTypeEntry,
+          entityTypeRegistry.set(value.discriminator, (raw) =>
+            factory(raw, POSTGRES_AUTHORING_CTX),
           );
         }
         if (value.validatorSchema !== undefined) {
@@ -91,22 +86,46 @@ export class PostgresContractSerializer extends SqlContractSerializerBase<Contra
     if (raw instanceof NamespaceBase) {
       return raw;
     }
-    const hydrated = super.hydrateSqlNamespaceEntry(nsId, raw) as {
-      id: string;
-      tables: Readonly<Record<string, StorageTable>>;
-      enum?: Readonly<Record<string, PostgresEnumType>>;
-    };
-    const { id, tables, enum: hydratedNsEnums } = hydrated;
+    const hydrated = blindCast<
+      SqlNamespaceTablesInput,
+      'super.hydrateSqlNamespaceEntry returns the tables form when raw is not a NamespaceBase'
+    >(super.hydrateSqlNamespaceEntry(nsId, raw));
+    const { id, entries } = hydrated;
+
+    // Extract the postgres-specific `type` slot directly from raw input.
+    // The family base handles the `table` slot; the postgres target owns `type`.
+    const rawRecord = raw as Record<string, unknown>;
+    const rawEntries = rawRecord['entries'];
+    let typeSlot: Record<string, PostgresEnumType> | undefined;
+    if (rawEntries !== null && typeof rawEntries === 'object' && !Array.isArray(rawEntries)) {
+      const rawTypeSlot = (rawEntries as Record<string, unknown>)['type'];
+      if (rawTypeSlot !== null && typeof rawTypeSlot === 'object' && !Array.isArray(rawTypeSlot)) {
+        const enumFactory = this.entityTypeRegistry.get('postgres-enum');
+        typeSlot = Object.fromEntries(
+          Object.entries(rawTypeSlot as Record<string, unknown>).map(([name, entry]) => [
+            name,
+            blindCast<PostgresEnumType, 'postgres-enum factory returns PostgresEnumType'>(
+              enumFactory !== undefined ? enumFactory(entry) : entry,
+            ),
+          ]),
+        );
+      }
+    }
 
-    const emptyTables = Object.keys(tables).length === 0;
-    const emptyEnums = !hydratedNsEnums || Object.keys(hydratedNsEnums).length === 0;
-    if (id === UNBOUND_NAMESPACE_ID && emptyTables && emptyEnums) {
+    const valueSetSlot = entries.valueSet;
+    const hasValueSets = valueSetSlot !== undefined && Object.keys(valueSetSlot).length > 0;
+    const emptyTables = Object.keys(entries.table).length === 0;
+    const emptyTypes = !typeSlot || Object.keys(typeSlot).length === 0;
+    if (id === UNBOUND_NAMESPACE_ID && emptyTables && emptyTypes && !hasValueSets) {
       return PostgresSchema.unbound;
     }
     return new PostgresSchema({
       id,
-      tables,
-      ...(hydratedNsEnums !== undefined ? { enum: hydratedNsEnums } : {}),
+      entries: {
+        table: entries.table,
+        type: typeSlot ?? {},
+        ...(hasValueSets ? { valueSet: valueSetSlot } : {}),
+      },
     });
   }
 
@@ -117,30 +136,18 @@ export class PostgresContractSerializer extends SqlContractSerializerBase<Contra
       if (isPostgresSchema(ns)) {
         namespacesJson[nsId] = this.serializePostgresNamespace(ns, ns.id === UNBOUND_NAMESPACE_ID);
       } else {
-        // Family-level SqlUnboundNamespace or other family-built SQL
-        // namespaces haven't been promoted to a PostgresSchema instance
-        // yet (e.g. they came straight from the TS builder before a target
-        // `createNamespace` factory ran). Serialise them as postgres-schema /
-        // postgres-unbound-schema so the round-trip through
-        // deserializeContract hydrates them back into PostgresSchema
-        // instances.
         const isUnboundSlot = nsId === UNBOUND_NAMESPACE_ID;
-        const nsEnums = (ns as { readonly enum?: Readonly<Record<string, unknown>> }).enum ?? {};
         namespacesJson[nsId] = {
           id: nsId,
           kind: isUnboundSlot ? 'postgres-unbound-schema' : 'postgres-schema',
-          tables: Object.fromEntries(
-            Object.entries(ns.tables).map(([tableName, table]) => [
-              tableName,
-              this.serializeJsonValue(table) as JsonObject,
-            ]),
-          ),
-          enum: Object.fromEntries(
-            Object.entries(nsEnums).map(([typeName, entry]) => [
-              typeName,
-              this.serializeJsonValue(entry) as JsonObject,
-            ]),
-          ),
+          entries: {
+            table: Object.fromEntries(
+              Object.entries(ns.entries.table).map(([tableName, table]) => [
+                tableName,
+                this.serializeJsonValue(table) as JsonObject,
+              ]),
+            ),
+          },
         };
       }
     }
@@ -163,18 +170,31 @@ export class PostgresContractSerializer extends SqlContractSerializerBase<Contra
 
   private serializePostgresNamespace(ns: PostgresSchema, isUnboundSlot: boolean): JsonObject {
     const tablesOut: Record<string, JsonObject> = {};
-    for (const [tableName, table] of Object.entries(ns.tables)) {
+    for (const [tableName, table] of Object.entries(ns.entries.table)) {
       tablesOut[tableName] = this.serializeJsonValue(table) as JsonObject;
     }
-    const enumOut: Record<string, JsonObject> = {};
-    for (const [typeName, ty] of Object.entries(ns.enum)) {
-      enumOut[typeName] = this.serializeJsonValue(ty) as JsonObject;
+    const typeOut: Record<string, JsonObject> = {};
+    for (const [typeName, ty] of Object.entries(ns.entries.type)) {
+      typeOut[typeName] = this.serializeJsonValue(ty) as JsonObject;
+    }
+    const valueSetEntries = ns.entries.valueSet;
+    const valueSetOut: Record<string, JsonObject> = {};
+    if (valueSetEntries !== undefined) {
+      for (const [valueSetName, valueSet] of Object.entries(valueSetEntries)) {
+        valueSetOut[valueSetName] = blindCast<
+          JsonObject,
+          'serializeJsonValue round-trips the value-set node through JSON, yielding a JsonObject'
+        >(this.serializeJsonValue(valueSet));
+      }
     }
     return {
       id: ns.id,
       kind: isUnboundSlot ? 'postgres-unbound-schema' : 'postgres-schema',
-      tables: tablesOut,
-      enum: enumOut,
+      entries: {
+        table: tablesOut,
+        type: typeOut,
+        ...(Object.keys(valueSetOut).length > 0 ? { valueSet: valueSetOut } : {}),
+      },
     };
   }
 

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

@@ -1,3 +1,4 @@
+import type { ControlPolicy } from '@prisma-next/contract/types';
 import { freezeNode } from '@prisma-next/framework-components/ir';
 import { SqlNode } from '@prisma-next/sql-contract/types';
 
@@ -18,6 +19,7 @@ export interface PostgresEnumTypeInput<
    */
   readonly nativeType?: string;
   readonly values: TValues;
+  readonly control?: ControlPolicy;
 }
 
 /** Codec id used by Postgres enum-typed columns (text wire format). */
@@ -64,6 +66,7 @@ export class PostgresEnumType<
    * dispatching through the prototype-only `codecBinding` accessor.
    */
   readonly codecId: typeof PG_ENUM_CODEC_ID = PG_ENUM_CODEC_ID;
+  declare readonly control?: ControlPolicy;
 
   constructor(input: PostgresEnumTypeInput<TName, TValues>) {
     super();
@@ -73,6 +76,7 @@ export class PostgresEnumType<
     // `TValues` literal tuple. Cast preserves the caller-supplied
     // tuple shape so inferred contract types retain literal narrowing.
     this.values = Object.freeze([...input.values] as unknown as TValues);
+    if (input.control !== undefined) this.control = input.control;
     freezeNode(this);
   }