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

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,48 @@ 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 { parseRlsPolicyWireName } from '../rls/wire-name';
+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,
+  RenamePostgresRlsPolicyCall,
+} 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 +67,6 @@ type PlannerOptionsWithComponents = SqlMigrationPlannerPlanOptions & {
   readonly frameworkComponents: PlannerFrameworkComponents;
 };
 
-type VerifySqlSchemaOptionsWithComponents = Parameters<typeof verifySqlSchema>[0] & {
-  readonly frameworkComponents: PlannerFrameworkComponents;
-};
-
 export function createPostgresMigrationPlanner(
   lowerer: ExecuteRequestLowerer,
 ): PostgresMigrationPlanner {
@@ -75,18 +91,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 +140,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 +174,73 @@ 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));
+    // Role diff issues resolve to the `external` control policy (see
+    // `resolvePostgresNodeIssueControlPolicySubject`'s role branch), so the
+    // control-policy partition below suppresses them to zero ops on its own,
+    // before `mapNodeIssueToCall` ever sees them — no separate exclusion
+    // needed here.
+    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 +253,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 +266,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 +281,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 +317,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 +339,142 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
     });
   }
 
+  /**
+   * Maps the RLS policy presence findings of the one combined tree diff
+   * (`buildPostgresPlanDiff`, already ownership-filtered) into
+   * `CREATE POLICY` / `DROP POLICY` / `ALTER POLICY … RENAME TO` ops. It
+   * does not re-diff — it consumes exactly the policy-node subset of the
+   * shared diff's issues. Enablement is NOT decided here: `ENABLE`/`DISABLE
+   * ROW LEVEL SECURITY` derive from the table's marker-driven `rlsEnabled`
+   * attribute diff on the relational side.
+   *
+   * Rename post-pass: a `not-found` and a `not-expected` policy on the SAME
+   * table whose wire-name content hashes match but prefixes differ are one
+   * prefix-only rename, collapsed into a single non-destructive
+   * `RenamePostgresRlsPolicyCall`. Multi-candidate hash groups pair
+   * deterministically by sorted wire name; leftovers proceed as
+   * create/drop. Unparseable wire names never pair.
+   *
+   * The pairing runs only when the policy allows `widening` (rename's
+   * class). Without it (db-init's additive-only set), pairing degrades
+   * deliberately to the additive half: the new name is CREATEd and the old
+   * policy survives live until a widening/destructive-allowed plan runs —
+   * emitting an ungated widening rename would only fail at the runner's
+   * class re-enforcement.
+   */
+  private planPostgresSchemaDiff(
+    options: PlannerOptionsWithComponents,
+    filteredDiffIssues: readonly SchemaDiffIssue<SqlSchemaDiffNode>[],
+  ): readonly PostgresOpFactoryCall[] {
+    const allowsDestructive = options.policy.allowedOperationClasses.includes('destructive');
+    const allowsWidening = options.policy.allowedOperationClasses.includes('widening');
+
+    interface PolicyFinding {
+      readonly node: PostgresPolicySchemaNode;
+      readonly schemaForTable: string;
+    }
+    const missing: PolicyFinding[] = [];
+    const extra: PolicyFinding[] = [];
+
+    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.
+        missing.push({
+          node: expected,
+          schemaForTable: resolveDdlSchemaForNamespaceStorage(
+            options.contract.storage,
+            expected.namespaceId,
+          ),
+        });
+      } else if (issue.reason === 'not-expected') {
+        const actual = issue.actual;
+        PostgresPolicySchemaNode.assert(actual);
+        extra.push({
+          node: actual,
+          schemaForTable: resolveDdlSchemaForNamespaceStorage(
+            options.contract.storage,
+            actual.namespaceId,
+          ),
+        });
+      }
+    }
+
+    const calls: PostgresOpFactoryCall[] = [];
+    const renamedExtras = new Set<PolicyFinding>();
+    const renamedMissing = new Set<PolicyFinding>();
+    const pairingKey = (finding: PolicyFinding, hash: string): string =>
+      JSON.stringify([finding.schemaForTable, finding.node.tableName, hash]);
+
+    if (allowsWidening) {
+      const extrasByGroup = new Map<string, PolicyFinding[]>();
+      for (const finding of extra) {
+        const parsed = parseRlsPolicyWireName(finding.node.name);
+        if (parsed === undefined) continue;
+        const key = pairingKey(finding, parsed.hash);
+        const group = extrasByGroup.get(key) ?? [];
+        group.push(finding);
+        extrasByGroup.set(key, group);
+      }
+      for (const group of extrasByGroup.values()) {
+        group.sort((a, b) => (a.node.name < b.node.name ? -1 : a.node.name > b.node.name ? 1 : 0));
+      }
+
+      const sortedMissing = [...missing].sort((a, b) =>
+        a.node.name < b.node.name ? -1 : a.node.name > b.node.name ? 1 : 0,
+      );
+      for (const missingFinding of sortedMissing) {
+        const parsed = parseRlsPolicyWireName(missingFinding.node.name);
+        if (parsed === undefined) continue;
+        const candidates = extrasByGroup.get(pairingKey(missingFinding, parsed.hash));
+        const candidate = candidates?.shift();
+        if (candidate === undefined) continue;
+        // Same name would never surface as missing+extra (the differ pairs by
+        // name), so a matched candidate always differs in prefix only.
+        renamedExtras.add(candidate);
+        renamedMissing.add(missingFinding);
+        calls.push(
+          new RenamePostgresRlsPolicyCall(
+            missingFinding.schemaForTable,
+            missingFinding.node.tableName,
+            candidate.node.name,
+            missingFinding.node.name,
+          ),
+        );
+      }
+    }
+
+    for (const finding of missing) {
+      if (renamedMissing.has(finding)) continue;
+      calls.push(
+        new CreatePostgresRlsPolicyCall(
+          finding.schemaForTable,
+          finding.node.tableName,
+          policyNodeToContractPolicy(finding.node),
+        ),
+      );
+    }
+    if (allowsDestructive) {
+      for (const finding of extra) {
+        if (renamedExtras.has(finding)) continue;
+        calls.push(
+          new DropPostgresRlsPolicyCall(
+            finding.schemaForTable,
+            finding.node.tableName,
+            finding.node.name,
+          ),
+        );
+      }
+    }
+
+    return calls;
+  }
+
   private ensureAdditivePolicy(policy: MigrationOperationPolicy) {
     if (!policy.allowedOperationClasses.includes('additive')) {
       return plannerFailure([
@@ -252,35 +487,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,
+  });
 }