@prisma-next/target-postgres 0.14.0-dev.5 → 0.14.0-dev.51

package/src/core/migrations/planner-target-details.ts

@@ -9,7 +9,9 @@ export type OperationClass =
   | 'unique'
   | 'index'
   | 'foreignKey'
-  | 'checkConstraint';
+  | 'checkConstraint'
+  | 'rlsPolicy'
+  | 'rowLevelSecurity';
 
 export interface PostgresPlanTargetDetails {
   readonly schema: string;

package/src/core/migrations/planner.ts

@@ -13,28 +13,47 @@ import {
   plannerFailure,
 } from '@prisma-next/family-sql/control';
 import type { ExecuteRequestLowerer } 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 {
   MigrationPlanner,
   MigrationPlanWithAuthoringSurface,
   MigrationScaffoldContext,
-  SchemaIssue,
+  SchemaDiffIssue,
+  SchemaOwnership,
 } 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 { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
 import { blindCast } from '@prisma-next/utils/casts';
-import { parsePostgresDefault } from '../default-normalizer';
-import { normalizeSchemaNativeType } from '../native-type-normalizer';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { PostgresRlsPolicy } from '../postgres-rls-policy';
+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 {
   formatPostgresControlPolicySubjectLabel,
+  resolveNamespaceIdForDdlSchema,
   resolvePostgresCallControlPolicySubject,
-  resolvePostgresIssueControlPolicySubject,
-  resolvePostgresIssueCreationFactoryName,
+  resolvePostgresNodeIssueControlPolicySubject,
+  resolvePostgresNodeIssueCreationFactoryName,
 } from './control-policy';
-import { planIssues } from './issue-planner';
+import { buildPostgresPlanDiff } from './diff-database-schema';
+import {
+  coalesceSubtreeIssues,
+  issueNode,
+  issueSchemaName,
+  issueTableName,
+  planIssues,
+} from './issue-planner';
 import type { PostgresOpFactoryCall } from './op-factory-call';
+import {
+  CreatePostgresRlsPolicyCall,
+  DropPostgresRlsPolicyCall,
+  EnableRowLevelSecurityCall,
+} from './op-factory-call';
 import { TypeScriptRenderablePostgresMigration } from './planner-produced-postgres-migration';
 import { postgresPlannerStrategies } from './planner-strategies';
+import { resolveDdlSchemaForNamespaceStorage } from './resolve-ddl-schema';
 import { verifyPostgresNamespacePresence } from './verify-postgres-namespaces';
 
 type PlannerFrameworkComponents = SqlMigrationPlannerPlanOptions extends {
@@ -47,10 +66,6 @@ type PlannerOptionsWithComponents = SqlMigrationPlannerPlanOptions & {
   readonly frameworkComponents: PlannerFrameworkComponents;
 };
 
-type VerifySqlSchemaOptionsWithComponents = Parameters<typeof verifySqlSchema>[0] & {
-  readonly frameworkComponents: PlannerFrameworkComponents;
-};
-
 export function createPostgresMigrationPlanner(
   lowerer: ExecuteRequestLowerer,
 ): PostgresMigrationPlanner {
@@ -75,18 +90,20 @@ export type PostgresPlanResult =
 /**
  * Postgres migration planner — a thin wrapper over `planIssues`.
  *
- * `plan()` verifies the live schema against the target contract (producing
- * `SchemaIssue[]`) and delegates to `planIssues` with the unified
- * `postgresPlannerStrategies` list: enum-change, NOT-NULL backfill,
- * type-change, nullable-tightening, codec-hook storage types,
- * component-declared dependency installs, and shared-temp-default /
- * empty-table-guarded NOT-NULL add-column. The same strategy list runs for
- * `migration plan`, `db update`, and `db init`; behavior diverges purely on
- * `policy.allowedOperationClasses` (the data-safe strategies short-circuit
- * when `'data'` is excluded). The issue planner applies operation-class
- * policy gates and emits a single `PostgresOpFactoryCall[]` that drives both
- * the runtime-ops view (via `renderOps`) and the `renderTypeScript()`
- * authoring surface.
+ * `plan()` diffs the target contract against the live schema via the one
+ * differ (`buildPostgresPlanDiff`, producing node-typed `SchemaDiffIssue[]`)
+ * and delegates to `planIssues` with the unified `postgresPlannerStrategies`
+ * list: NOT-NULL backfill, type-change, nullable-tightening, codec-hook
+ * storage types, component-declared dependency installs, and
+ * shared-temp-default / empty-table-guarded NOT-NULL add-column. The same
+ * strategy list runs for `migration plan`, `db update`, and `db init`;
+ * behavior diverges purely on `policy.allowedOperationClasses` (the
+ * data-safe strategies short-circuit when `'data'` is excluded). The issue
+ * planner applies operation-class policy gates and emits a single
+ * `PostgresOpFactoryCall[]` that drives both the runtime-ops view (via
+ * `renderOps`) and the `renderTypeScript()` authoring surface. RLS policy
+ * drift (the structural half of the same one-differ tree) is handled
+ * separately via `planPostgresSchemaDiff`.
  */
 export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgres'> {
   readonly #lowerer: ExecuteRequestLowerer | undefined;
@@ -122,6 +139,11 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
      * the marker row by the right space.
      */
     readonly spaceId: string;
+    /**
+     * Ownership oracle over the contract-space composition — see
+     * {@link SqlMigrationPlannerPlanOptions.ownership}.
+     */
+    readonly ownership?: SchemaOwnership;
   }): PostgresPlanResult {
     return this.planSql(options as SqlMigrationPlannerPlanOptions);
   }
@@ -151,9 +173,68 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       return policyResult;
     }
 
-    const schemaIssues = this.collectSchemaIssues(options);
+    // The one combined tree diff drives the whole plan: relational findings
+    // become structural DDL via `planIssues`, policy findings become RLS ops
+    // via `planPostgresSchemaDiff`. Verify runs its own full-tree node diff
+    // (`diffSchema`) over the same schema and rejects on a
+    // surviving failure.
+    PostgresDatabaseSchemaNode.assert(options.schema);
+    const { issues: rawIssues } = buildPostgresPlanDiff({
+      contract: options.contract,
+      actualSchema: options.schema,
+      frameworkComponents: options.frameworkComponents,
+    });
+    const policyDiffIssues = rawIssues.filter((issue) => isPolicyDiffIssue(issue));
+    const relationalDiffIssues = rawIssues.filter((issue) => !isPolicyDiffIssue(issue));
+
+    // The generic differ is total and un-gated: strict-mode extras filtering
+    // (dropping `not-expected` findings outside strict mode, mirroring the
+    // retired coordinate walk's `if (strict) { ...extra_* } }` guards),
+    // subtree coalescing (a missing/extra table also emits an issue for
+    // every child under it — redundant once the table-level Create/Drop call
+    // already accounts for the whole subtree), and ownership are all post-diff
+    // planner steps.
+    //
+    // Ownership: a live extra is only this plan's to drop when no contract
+    // space owns it. The differ ran against THIS space's contract, so a table
+    // a sibling space owns surfaces here as `not-expected`; the planner asks
+    // the ownership oracle (the passive aggregate) whether any space declares
+    // it and, if so, leaves it alone — it is a sibling's table, not an orphan.
+    // A table no space owns stays a genuine extra to drop under a destructive
+    // policy. Ownership lives in the aggregate; the planner only asks. Absent
+    // oracle (single-space, none handed) keeps every extra. Coalescing MUST
+    // run before this so a sibling-owned table's child issues have already
+    // collapsed into the one table-level issue that carries the table name.
+    const strict =
+      options.policy.allowedOperationClasses.includes('widening') ||
+      options.policy.allowedOperationClasses.includes('destructive');
+    const coalesced = coalesceSubtreeIssues(relationalDiffIssues);
+    const owned = retainUnownedExtras(coalesced, options.ownership, options.contract);
+    const gated = strict ? owned : owned.filter((issue) => issue.reason !== 'not-expected');
+
+    // Namespace presence (`CREATE SCHEMA`) is a planner-only op-generation
+    // concern stitched in here rather than inside the shared diff — verify
+    // never needs it (a missing schema already surfaces as a `not-found`
+    // table in the relational findings). These synthesized issues are added
+    // AFTER coalescing/scoping (never coalesced against the table diff —
+    // their path is an ancestor of every table path under that schema, so
+    // running them through the same coalesce would swallow the table-level
+    // `not-found` issues that drive `CREATE TABLE`) and are NOT subject to
+    // sibling-space scoping, matching the retired coordinate walk exactly.
+    const namespaceIssues = verifyPostgresNamespacePresence({
+      contract: options.contract,
+      schema: options.schema,
+    });
+    const schemaIssues = [...namespaceIssues, ...gated];
+
     const codecHooks = extractCodecControlHooks(options.frameworkComponents);
     const storageTypes = options.contract.storage.types ?? {};
+    // The strategy layer reads the live schema by bare table name for existence
+    // checks (shared-temp-default safety, FK/unique probes), so it takes one
+    // per-schema namespace node — never the whole tree root, and never a flat
+    // merge of every namespace (which would collide same-named tables across
+    // schemas). Probing more than one namespace at once is future work.
+    const relationalSchema = relationalNamespaceNode(options.schema, schemaName);
 
     // Input-side control-policy partition. `external` / `observed` subjects
     // — and non-creation issues for `tolerated` subjects — are dropped from
@@ -166,8 +247,8 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       issues: schemaIssues,
       contract: options.contract,
       resolveControlPolicySubject: (issue) =>
-        resolvePostgresIssueControlPolicySubject(issue, options.contract),
-      resolveCreationFactoryName: resolvePostgresIssueCreationFactoryName,
+        resolvePostgresNodeIssueControlPolicySubject(issue, options.contract),
+      resolveCreationFactoryName: resolvePostgresNodeIssueCreationFactoryName,
       formatSubjectLabel: (factoryName, subject) =>
         formatPostgresControlPolicySubjectLabel(factoryName, subject, options.contract),
     });
@@ -179,12 +260,12 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       // `db update` / `db init`, which means data-safety strategies needing
       // from/to comparisons (unsafe type change, nullable tightening) are
       // inapplicable there — reconciliation falls through to
-      // `mapIssueToCall`'s direct destructive handlers.
+      // `mapNodeIssueToCall`'s direct destructive handlers.
       fromContract: options.fromContract,
       schemaName,
       codecHooks,
       storageTypes,
-      schema: options.schema,
+      ...ifDefined('schema', relationalSchema),
       policy: options.policy,
       frameworkComponents: options.frameworkComponents,
       strategies: postgresPlannerStrategies,
@@ -194,6 +275,17 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       return plannerFailure(result.failure);
     }
 
+    const schemaDiffCalls = this.planPostgresSchemaDiff(options, policyDiffIssues);
+    const schemaDiffPartition = partitionCallsByControlPolicy({
+      calls: schemaDiffCalls,
+      contract: options.contract,
+      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
     // ordering is `structural → added → dropped → altered`, with
     // within-group sorting by `(tableName, fieldName)` so re-emits are
@@ -219,9 +311,10 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       formatSubjectLabel: (factoryName, subject) =>
         formatPostgresControlPolicySubjectLabel(factoryName, subject, options.contract),
     });
-    const calls = [...result.value.calls, ...fieldEventPartition.kept];
+    const calls = [...result.value.calls, ...schemaDiffPartition.kept, ...fieldEventPartition.kept];
     const warnings: SqlPlannerConflict[] = [
       ...issuePartition.warnings,
+      ...schemaDiffPartition.warnings,
       ...fieldEventPartition.warnings,
     ];
 
@@ -240,6 +333,59 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
     });
   }
 
+  /**
+   * Maps the RLS policy presence findings of the one combined tree diff
+   * (`buildPostgresPlanDiff`, already ownership-filtered) into `ENABLE RLS`
+   * / `CREATE POLICY` / `DROP POLICY` ops. It does not re-diff — it consumes
+   * exactly the policy-node subset of the shared diff's issues.
+   */
+  private planPostgresSchemaDiff(
+    options: PlannerOptionsWithComponents,
+    filteredDiffIssues: readonly SchemaDiffIssue<SqlSchemaDiffNode>[],
+  ): readonly PostgresOpFactoryCall[] {
+    const allowsDestructive = options.policy.allowedOperationClasses.includes('destructive');
+    const calls: PostgresOpFactoryCall[] = [];
+    const seenEnableTables = new Set<string>();
+
+    for (const issue of filteredDiffIssues) {
+      // 'not-equal' is unreachable for content-addressed policies: the wire name
+      // encodes the body hash, so two policies sharing a local key (same name)
+      // are always equal and isEqualTo never returns false.
+      if (issue.reason === 'not-found') {
+        const expected = issue.expected;
+        PostgresPolicySchemaNode.assert(expected);
+        // expected.namespaceId is the DDL schema name (resolved during projection);
+        // this re-resolution is a no-op as long as PostgresSchema.ddlSchemaName() returns this.id.
+        const schemaForTable = resolveDdlSchemaForNamespaceStorage(
+          options.contract.storage,
+          expected.namespaceId,
+        );
+        const tableKey = `${schemaForTable}.${expected.tableName}`;
+        if (!seenEnableTables.has(tableKey)) {
+          seenEnableTables.add(tableKey);
+          calls.push(new EnableRowLevelSecurityCall(schemaForTable, expected.tableName));
+        }
+        calls.push(
+          new CreatePostgresRlsPolicyCall(
+            schemaForTable,
+            expected.tableName,
+            policyNodeToContractPolicy(expected),
+          ),
+        );
+      } else if (issue.reason === 'not-expected' && allowsDestructive) {
+        const actual = issue.actual;
+        PostgresPolicySchemaNode.assert(actual);
+        const schemaForTable = resolveDdlSchemaForNamespaceStorage(
+          options.contract.storage,
+          actual.namespaceId,
+        );
+        calls.push(new DropPostgresRlsPolicyCall(schemaForTable, actual.tableName, actual.name));
+      }
+    }
+
+    return calls;
+  }
+
   private ensureAdditivePolicy(policy: MigrationOperationPolicy) {
     if (!policy.allowedOperationClasses.includes('additive')) {
       return plannerFailure([
@@ -252,35 +398,127 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
     }
     return null;
   }
+}
 
-  private collectSchemaIssues(options: PlannerOptionsWithComponents): readonly SchemaIssue[] {
-    // `db init` uses additive-only policy and intentionally ignores extra
-    // schema objects. Any reconciliation-capable policy (widening or
-    // destructive) must inspect extras to reconcile strict equality.
-    const allowed = options.policy.allowedOperationClasses;
-    const strict = allowed.includes('widening') || allowed.includes('destructive');
-    const verifyOptions: VerifySqlSchemaOptionsWithComponents = {
-      contract: options.contract,
-      schema: options.schema,
-      strict,
-      typeMetadataRegistry: new Map(),
-      frameworkComponents: options.frameworkComponents,
-      normalizeDefault: parsePostgresDefault,
-      normalizeNativeType: normalizeSchemaNativeType,
-    };
-    const verifyResult = verifySqlSchema(verifyOptions);
-    // Schema presence is a Postgres-specific concern (no equivalent in
-    // SQLite / Mongo), so the issue emission lives in the target layer
-    // rather than in the family verifier. Stitch it in here so a single
-    // `SchemaIssue[]` flows through `planIssues` and the planner emits
-    // CREATE SCHEMA in the dep bucket before any CreateTableCall.
-    const namespaceIssues = verifyPostgresNamespacePresence({
-      contract: options.contract,
-      schema: options.schema,
-    });
-    if (namespaceIssues.length === 0) {
-      return verifyResult.schema.issues;
-    }
-    return [...namespaceIssues, ...verifyResult.schema.issues];
-  }
+/**
+ * A diff issue whose node is an RLS policy — the structural half of the one
+ * combined tree diff, routed to `planPostgresSchemaDiff` instead of
+ * `planIssues`.
+ */
+function isPolicyDiffIssue(issue: SchemaDiffIssue<SqlSchemaDiffNode>): boolean {
+  const node = issue.expected ?? issue.actual;
+  return node !== undefined && PostgresPolicySchemaNode.is(node);
+}
+
+/**
+ * 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).
+ */
+function retainUnownedExtras(
+  issues: readonly SchemaDiffIssue<SqlSchemaDiffNode>[],
+  ownership: SchemaOwnership | undefined,
+  contract: Contract<SqlStorage>,
+): readonly SchemaDiffIssue<SqlSchemaDiffNode>[] {
+  if (ownership === undefined) return issues;
+  return issues.filter((issue) => {
+    if (issue.reason !== 'not-expected') return true;
+    const node = issueNode(issue);
+    if (node === undefined || node.nodeKind !== PostgresSchemaNodeKind.table) return true;
+    const ddlSchemaName = issueSchemaName(issue);
+    const tableName = issueTableName(issue);
+    if (ddlSchemaName === undefined || tableName === undefined) return true;
+    const namespaceId = resolveNamespaceIdForDdlSchema(contract, ddlSchemaName);
+    return !ownership.declaresEntity({ namespaceId, entityKind: 'table', entityName: tableName });
+  });
+}
+
+/**
+ * Returns the one namespace node the relational strategy layer probes for
+ * live-table existence and reads codec-hook context off — the namespace
+ * matching the planner's resolved schema name, or the first namespace when
+ * none matches. `undefined` when the tree has no namespaces, so the strategy
+ * context uses its empty-schema default.
+ *
+ * The relational strategies key tables by bare name, so they can only probe one
+ * namespace at a time; probing across every namespace at once is future work.
+ *
+ * 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
+ * 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
+ * structurally-`SqlSchemaIR`-shaped value.
+ */
+function relationalNamespaceNode(
+  schema: PostgresDatabaseSchemaNode,
+  schemaName: string,
+): SqlSchemaIR | undefined {
+  const namespaceNodes = Object.values(schema.namespaces);
+  const namespaceNode =
+    namespaceNodes.find((node) => node.schemaName === schemaName) ?? namespaceNodes[0];
+  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'
+  >(namespaceNode);
+}
+
+/**
+ * Rebuilds the `PostgresRlsPolicy` contract entity `CreatePostgresRlsPolicyCall`
+ * carries (its `renderTypeScript`/`createRlsPolicy` paths serialize the whole
+ * entity, `namespaceId` included). This reconstructs rather than looking the
+ * original up in the contract on purpose: the diff node's `namespaceId` is the
+ * *resolved DDL schema* (set when the expected tree was built), which is the
+ * value the emitted op must carry; the contract-stored entity holds the raw,
+ * pre-resolution coordinate, so a lookup would change the migration output.
+ */
+function policyNodeToContractPolicy(node: PostgresPolicySchemaNode): PostgresRlsPolicy {
+  return new PostgresRlsPolicy({
+    name: node.name,
+    prefix: node.prefix,
+    tableName: node.tableName,
+    namespaceId: node.namespaceId,
+    operation: node.operation,
+    roles: [...node.roles],
+    ...ifDefined('using', node.using),
+    ...ifDefined('withCheck', node.withCheck),
+    permissive: node.permissive,
+  });
 }

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

@@ -3,9 +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 { MigrationContractViews } from '@prisma-next/migration-tools/migration';
 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 { PostgresContractView } from '../postgres-contract-view';
 import {
   AddCheckConstraintCall,
   AddColumnCall,
@@ -60,10 +62,10 @@ import type { PostgresPlanTargetDetails } from './planner-target-details';
  * is an antipattern in a migration. (The unbound/unspecified namespace concept
  * remains for SQLite, which has no schemas, and for Mongo's connection `db`.)
  */
-export abstract class PostgresMigration extends SqlMigration<
-  PostgresPlanTargetDetails,
-  'postgres'
-> {
+export abstract class PostgresMigration<
+  Start extends Contract<SqlStorage> = Contract<SqlStorage>,
+  End extends Contract<SqlStorage> = Contract<SqlStorage>,
+> extends SqlMigration<PostgresPlanTargetDetails, 'postgres', Start, End> {
   readonly targetId = 'postgres' as const;
 
   /**
@@ -74,6 +76,17 @@ export abstract class PostgresMigration extends SqlMigration<
    */
   protected readonly controlAdapter: SqlControlAdapter<'postgres'> | undefined;
 
+  #endView = new MigrationContractViews<PostgresContractView<End>>(
+    this,
+    'PostgresMigration',
+    (json) => PostgresContractView.fromJson<End>(json),
+  );
+  #startView = new MigrationContractViews<PostgresContractView<Start>>(
+    this,
+    'PostgresMigration',
+    (json) => PostgresContractView.fromJson<Start>(json),
+  );
+
   constructor(stack?: ControlStack<'sql', 'postgres'>) {
     super(stack);
     // The descriptor `create()` is typed as the wider `ControlAdapterInstance`;
@@ -84,6 +97,23 @@ export abstract class PostgresMigration extends SqlMigration<
       : undefined;
   }
 
+  /**
+   * The typed, schema-qualified Postgres view over this migration's end-state
+   * contract — `this.endContract.namespace.<schema>.table.<name>`, etc. Throws
+   * if no `endContractJson` was provided.
+   */
+  get endContract(): PostgresContractView<End> {
+    return this.#endView.endContract;
+  }
+
+  /**
+   * The typed Postgres view over this migration's start-state contract, or
+   * `null` for a baseline migration (no `startContractJson`).
+   */
+  get startContract(): PostgresContractView<Start> | null {
+    return this.#startView.startContract;
+  }
+
   /**
    * Instance-method wrapper around the free `dataTransform` factory that
    * supplies the stored control adapter. Authors call this from inside

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

@@ -45,15 +45,19 @@ export function renderCallsToTypeScript(
   calls: ReadonlyArray<OpFactoryCall>,
   meta: RenderMigrationMeta,
 ): string {
-  const imports = buildImports(calls);
+  const imports = buildImports(calls, meta);
   const operationsBody = calls.map((c) => renderCall(c)).join(',\n');
+  const hasStart = meta.from !== null;
+  const startField = hasStart ? ['  override readonly startContractJson = startContract;'] : [];
 
   return [
     shebangLineFor(detectScaffoldRuntime()),
     imports,
     '',
-    'export default class M extends Migration {',
-    buildDescribeMethod(meta),
+    `export default class M extends Migration<${hasStart ? 'Start' : 'never'}, End> {`,
+    ...startField,
+    '  override readonly endContractJson = endContract;',
+    '',
     '  override get operations() {',
     '    return [',
     indent(operationsBody, 6),
@@ -70,8 +74,8 @@ function renderCall(call: OpFactoryCall): string {
   return call.renderTypeScript();
 }
 
-function buildImports(calls: ReadonlyArray<OpFactoryCall>): string {
-  const requirements: ImportRequirement[] = [...BASE_IMPORTS];
+function buildImports(calls: ReadonlyArray<OpFactoryCall>, meta: RenderMigrationMeta): string {
+  const requirements: ImportRequirement[] = [...BASE_IMPORTS, ...contractImports(meta)];
   for (const call of calls) {
     for (const req of call.importRequirements()) {
       requirements.push(req);
@@ -80,16 +84,39 @@ function buildImports(calls: ReadonlyArray<OpFactoryCall>): string {
   return renderImports(requirements);
 }
 
-function buildDescribeMethod(meta: RenderMigrationMeta): string {
-  const lines: string[] = [];
-  lines.push('  override describe() {');
-  lines.push('    return {');
-  lines.push(`      from: ${JSON.stringify(meta.from)},`);
-  lines.push(`      to: ${JSON.stringify(meta.to)},`);
-  lines.push('    };');
-  lines.push('  }');
-  lines.push('');
-  return lines.join('\n');
+/**
+ * The committed contract-JSON imports the scaffold reads its from/to identity
+ * from. `end-contract.json` is always present; `start-contract.json` is added
+ * only for a non-baseline migration (`meta.from !== null`). The matching
+ * `Contract` type imports (aliased `Start`/`End`) feed the
+ * `Migration<Start, End>` generics. Baseline emits `Migration<never, End>` with
+ * no start imports — `never` is the honest "no prior contract" Start.
+ */
+function contractImports(meta: RenderMigrationMeta): readonly ImportRequirement[] {
+  const reqs: ImportRequirement[] = [
+    {
+      moduleSpecifier: './end-contract.json',
+      symbol: 'endContract',
+      kind: 'default',
+      attributes: { type: 'json' },
+    },
+    { moduleSpecifier: './end-contract', symbol: 'Contract', alias: 'End', typeOnly: true },
+  ];
+  if (meta.from !== null) {
+    reqs.push({
+      moduleSpecifier: './start-contract.json',
+      symbol: 'startContract',
+      kind: 'default',
+      attributes: { type: 'json' },
+    });
+    reqs.push({
+      moduleSpecifier: './start-contract',
+      symbol: 'Contract',
+      alias: 'Start',
+      typeOnly: true,
+    });
+  }
+  return reqs;
 }
 
 function indent(text: string, spaces: number): string {

package/src/core/migrations/resolve-ddl-schema.ts

@@ -0,0 +1,26 @@
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import { DEFAULT_NAMESPACE_ID } from '../namespace-ids';
+import { isPostgresSchema } from '../postgres-schema';
+
+/**
+ * Given the contract's storage and a namespace id, returns the live Postgres
+ * DDL schema name that namespace maps to. A named Postgres namespace dispatches
+ * to its `ddlSchemaName(storage)`; the unbound sentinel resolves to
+ * `DEFAULT_NAMESPACE_ID` (the search-path default for offline planning); a
+ * bare object payload (used by some tests) falls back to the namespace id
+ * itself.
+ */
+export function resolveDdlSchemaForNamespaceStorage(
+  storage: SqlStorage,
+  namespaceId: string,
+): string {
+  if (namespaceId === UNBOUND_NAMESPACE_ID) {
+    return DEFAULT_NAMESPACE_ID;
+  }
+  const namespace = storage.namespaces[namespaceId];
+  if (namespace && isPostgresSchema(namespace)) {
+    return namespace.ddlSchemaName(storage);
+  }
+  return namespaceId;
+}