refactor(postgres): schema-node tree restructure — database→namespace→table→policy diff tree

docs/architecture docs/subsystems/7. Migration System.md

@@ -596,7 +596,7 @@ After plain `migrate`, refresh a stale `db` ref with `db update` (no-op on DB wh
 
 `ContractSpaceAggregate` is the single in-memory model of a project's on-disk migration state — the contract spaces, each with its migration packages, its refs, and the graph those packages induce. Every command that reads migration state loads it **once** and queries it; none re-derives that state from disk afterwards. The model and its loader live in `@prisma-next/migration-tools` ([`src/aggregate/`](../../../packages/1-framework/3-tooling/migration/src/aggregate/)). It is the in-memory realisation of the contract-space concept defined in [ADR 212 — Contract spaces](../adrs/ADR%20212%20-%20Contract%20spaces.md).
 
-The aggregate exposes the application member plus the extension members (`ContractSpaceMember`, one per space) and query methods over them — `listSpaces()`, `hasSpace(id)`, `space(id)`, `spaces()`. Each member carries its raw on-disk `packages`, its user-authored `refs`, and a nullable `headRef`, plus two lazy memoised facets: `graph()` (the reconstructed `MigrationGraph`) and `contract()` (the deserialised contract).
+The aggregate exposes the application space plus the extension spaces (`AggregateContractSpace`, one per contract space) and query methods over them — `listSpaces()`, `hasSpace(id)`, `space(id)`, `spaces()`. Each space carries its raw on-disk `packages`, its user-authored `refs`, and a nullable `headRef`, plus two lazy memoised facets: `graph()` (the reconstructed `MigrationGraph`) and `contract()` (the deserialised contract).
 
 ### Build / query / judge are separate responsibilities
 

packages/1-framework/1-core/framework-components/src/control/control-instances.ts

@@ -38,14 +38,13 @@ export interface ControlFamilyInstance<TFamilyId extends string, TSchemaIR>
   }): Promise<VerifyDatabaseResult>;
 
   /**
-   * Verify a contract against an already-introspected schema slice.
+   * Verify a contract against an already-introspected schema.
    *
    * Callers that need to verify against the live database compose
-   * {@link introspect} + `verifySchema` directly; the family
-   * interface deliberately exposes the introspection step so callers
-   * can pre-project the schema (e.g. the aggregate verifier projects
-   * each member's claimed slice via
-   * {@link import('@prisma-next/migration-tools/aggregate').projectSchemaToSpace}).
+   * {@link introspect} + `verifySchema` directly. The aggregate verifier
+   * verifies each member against the full introspected schema and scopes the
+   * result to that member's contract space afterwards — it never prunes the
+   * schema up front.
    *
    * Synchronous — no I/O. Idempotent.
    */

packages/1-framework/1-core/framework-components/src/control/control-migration-types.ts

@@ -19,6 +19,7 @@ import type {
   ControlFamilyInstance,
 } from './control-instances';
 import type { OperationContext } from './control-result-types';
+import type { DiffIssue } from './schema-diff';
 
 // ============================================================================
 // Migration Package Metadata
@@ -407,6 +408,16 @@ export interface MigrationPlanner<
      * per-extension callers pass the extension's space id.
      */
     readonly spaceId: string;
+    /**
+     * Caller-supplied keep-predicate the planner applies to its schema diff
+     * (via `SchemaDiff.filter`) before building operations. The orchestration
+     * constructs it so the diff findings reaching op-building are exactly the
+     * contract space's own — e.g. dropping the `extra` findings for elements
+     * a sibling contract space declares, so the planner never emits DROP ops
+     * against another space's tables. The planner applies it blindly and
+     * holds no ownership logic. Absent for single-space plans.
+     */
+    readonly keepDiffIssue?: (issue: DiffIssue) => boolean;
   }): MigrationPlannerResult;
 
   /**

packages/1-framework/1-core/framework-components/src/control/schema-diff.ts

@@ -1,14 +1,16 @@
+import type { SchemaIssue } from './control-result-types';
+
 export type SchemaDiffOutcome = 'missing' | 'extra' | 'mismatch';
 
-export interface SchemaDiffIssue {
+export interface SchemaDiffIssue<TNode extends DiffableNode = DiffableNode> {
   /** Path from the root node down to the diffed node, as a sequence of local keys. */
   readonly path: readonly string[];
   readonly outcome: SchemaDiffOutcome;
   readonly message: string;
   /** The expected (contract-side) node, when available. Absent for `extra` outcomes. */
-  readonly expected?: DiffableNode;
+  readonly expected?: TNode;
   /** The actual (live-DB-side) node, when available. Absent for `missing` outcomes. */
-  readonly actual?: DiffableNode;
+  readonly actual?: TNode;
 }
 
 /**
@@ -130,3 +132,49 @@ function diffChildren(
 
   return issues;
 }
+
+/**
+ * The two issue representations a `SchemaDiff` carries: `SchemaIssue` from the
+ * legacy relational differ (coordinate-based) and `SchemaDiffIssue` from the
+ * generic node differ (carrying the schema-IR node it concerns).
+ */
+export type DiffIssue<TNode extends DiffableNode = DiffableNode> =
+  | SchemaIssue
+  | SchemaDiffIssue<TNode>;
+
+/**
+ * The result of diffing a contract's expected schema against the introspected
+ * actual schema: two issue lists, kept distinct because two diffing mechanisms
+ * produce them (the relational check and the generic node differ). Carries no
+ * verdict, verification tree, or counts — those are the verifier's own
+ * presentation, built from the same underlying comparison.
+ *
+ * `TNode` is the concrete schema-IR node the `schemaDiffIssues` carry; it
+ * defaults to `DiffableNode`, so this is purely additive — a caller that wants
+ * the concrete node opts in (the Postgres planner uses the concrete node type),
+ * everyone else keeps the default unchanged.
+ */
+export class SchemaDiff<TNode extends DiffableNode = DiffableNode> {
+  readonly issues: readonly SchemaIssue[];
+  readonly schemaDiffIssues: readonly SchemaDiffIssue<TNode>[];
+
+  constructor(issues: readonly SchemaIssue[], schemaDiffIssues: readonly SchemaDiffIssue<TNode>[]) {
+    this.issues = issues;
+    this.schemaDiffIssues = schemaDiffIssues;
+  }
+
+  /** Fans `keep` across both issue lists, returning a new `SchemaDiff` narrowed to the survivors. */
+  filter(keep: (issue: DiffIssue<TNode>) => boolean): SchemaDiff<TNode> {
+    return new SchemaDiff(this.issues.filter(keep), this.schemaDiffIssues.filter(keep));
+  }
+}
+
+/**
+ * The SPI a SQL target implements to compare a contract's expected schema
+ * against the introspected actual schema. How the comparison is computed —
+ * relational check, generic node differ, namespace pairing — is private to
+ * the implementer; verify and plan consume only the returned `SchemaDiff`.
+ */
+export interface SchemaDiffer<TInput> {
+  diff(input: TInput): SchemaDiff;
+}

packages/1-framework/1-core/framework-components/src/exports/control.ts

@@ -103,10 +103,12 @@ export {
 } from '../control/control-stack';
 export type {
   DiffableNode,
+  DiffIssue,
+  SchemaDiffer,
   SchemaDiffIssue,
   SchemaDiffOutcome,
 } from '../control/schema-diff';
-export { diffSchemas } from '../control/schema-diff';
+export { diffSchemas, SchemaDiff } from '../control/schema-diff';
 export type {
   SchemaVerifier,
   SchemaVerifyOptions,

packages/1-framework/1-core/framework-components/test/schema-diff.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
-import type { DiffableNode, SchemaDiffIssue } from '../src/control/schema-diff';
-import { diffSchemas } from '../src/control/schema-diff';
+import type { SchemaIssue } from '../src/control/control-result-types';
+import type { DiffableNode, DiffIssue, SchemaDiffIssue } from '../src/control/schema-diff';
+import { diffSchemas, SchemaDiff } from '../src/control/schema-diff';
 
 /** A synthetic root node whose `isEqualTo` is always true — used to wrap flat node lists. */
 function rootOf(nodes: readonly DiffableNode[]): DiffableNode {
@@ -237,3 +238,55 @@ describe('diffSchemas', () => {
     expect(issues[0]).toMatchObject({ outcome: 'missing', path: ['root', 'lone_leaf'] });
   });
 });
+
+function makeSchemaIssue(table: string): SchemaIssue {
+  return { kind: 'extra_table', table, message: `Extra table "${table}"` };
+}
+
+function makeSchemaDiffIssue(path: readonly string[]): SchemaDiffIssue {
+  return { path, outcome: 'extra', message: outcomeMessageFor(path) };
+}
+
+function outcomeMessageFor(path: readonly string[]): string {
+  return `extra: ${path.join('/')}`;
+}
+
+describe('SchemaDiff', () => {
+  it('exposes the issues and schemaDiffIssues it was constructed with', () => {
+    const issues = [makeSchemaIssue('a')];
+    const schemaDiffIssues = [makeSchemaDiffIssue(['root', 'p'])];
+    const diff = new SchemaDiff(issues, schemaDiffIssues);
+    expect(diff.issues).toBe(issues);
+    expect(diff.schemaDiffIssues).toBe(schemaDiffIssues);
+  });
+
+  it('filter narrows both issue lists using one predicate over the union', () => {
+    const keep = makeSchemaIssue('keep');
+    const drop = makeSchemaIssue('drop');
+    const keepDiff = makeSchemaDiffIssue(['root', 'keep']);
+    const dropDiff = makeSchemaDiffIssue(['root', 'drop']);
+    const diff = new SchemaDiff([keep, drop], [keepDiff, dropDiff]);
+
+    const keepPredicate = (issue: DiffIssue): boolean =>
+      'outcome' in issue ? issue.path.includes('keep') : 'table' in issue && issue.table === 'keep';
+    const filtered = diff.filter(keepPredicate);
+
+    expect(filtered.issues).toEqual([keep]);
+    expect(filtered.schemaDiffIssues).toEqual([keepDiff]);
+  });
+
+  it('filter returns a new SchemaDiff, not a mutation of the original', () => {
+    const diff = new SchemaDiff([makeSchemaIssue('a')], []);
+    const filtered = diff.filter(() => false);
+    expect(filtered).not.toBe(diff);
+    expect(diff.issues).toHaveLength(1);
+    expect(filtered.issues).toHaveLength(0);
+  });
+
+  it('filter on an empty diff returns an empty diff', () => {
+    const diff = new SchemaDiff([], []);
+    const filtered = diff.filter(() => true);
+    expect(filtered.issues).toEqual([]);
+    expect(filtered.schemaDiffIssues).toEqual([]);
+  });
+});

packages/1-framework/3-tooling/cli/src/commands/db-verify.ts

@@ -1,10 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { loadConfig } from '@prisma-next/config-loader';
 import type { Contract } from '@prisma-next/contract/types';
-import type {
-  VerifyDatabaseResult,
-  VerifyDatabaseSchemaResult,
-} from '@prisma-next/framework-components/control';
+import type { VerifyDatabaseResult } from '@prisma-next/framework-components/control';
 import {
   createControlStack,
   VERIFY_CODE_HASH_MISMATCH,
@@ -29,7 +26,7 @@ import {
   errorTargetMismatch,
   errorUnexpected,
 } from '../utils/cli-errors';
-import { combineSchemaResults } from '../utils/combine-schema-results';
+import { type CombinedVerifyResult, combineVerifyResults } from '../utils/combine-verify-results';
 import {
   addGlobalOptions,
   maskConnectionUrl,
@@ -103,7 +100,7 @@ function mapVerifyFailure(verifyResult: VerifyDatabaseResult): CliStructuredErro
   return errorRuntime(verifyResult.summary);
 }
 
-type DbVerifyFailure = CliStructuredError | VerifyDatabaseSchemaResult;
+type DbVerifyFailure = CliStructuredError | CombinedVerifyResult;
 
 function errorInvalidVerifyMode(options: {
   readonly why: string;
@@ -419,12 +416,13 @@ async function executeDbVerifyCommand(
       });
     }
 
-    const combined = combineSchemaResults(
+    const combined = combineVerifyResults(
       aggregateResult.value.schemaResults,
       aggregateResult.value.appSpaceId,
       options.strict ?? false,
+      aggregateResult.value.unclaimed,
     );
-    if (!combined.ok) {
+    if (!combined.result.ok) {
       return notOk(combined);
     }
 
@@ -438,10 +436,11 @@ async function executeDbVerifyCommand(
       ...ifDefined('missingCodecs', verifyResult.missingCodecs),
       ...ifDefined('codecCoverageSkipped', verifyResult.codecCoverageSkipped),
       schema: {
-        summary: combined.summary,
-        counts: combined.schema.counts,
-        strict: combined.meta?.strict ?? false,
+        summary: combined.result.summary,
+        counts: combined.result.schema.counts,
+        strict: combined.result.meta?.strict ?? false,
       },
+      unclaimed: combined.unclaimed,
       meta: {
         ...(verifyResult.meta ?? {}),
         schemaVerification: 'performed',
@@ -459,7 +458,7 @@ async function executeDbSchemaOnlyVerifyCommand(
   options: DbVerifyOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
-): Promise<Result<VerifyDatabaseSchemaResult, CliStructuredError>> {
+): Promise<Result<CombinedVerifyResult, CliStructuredError>> {
   const paths = await resolveVerifyPaths(options);
   renderVerifyHeader(paths, options, 'schema-only', flags, ui);
 
@@ -484,10 +483,11 @@ async function executeDbSchemaOnlyVerifyCommand(
     if (!aggregateResult.ok) return notOk(aggregateResult.failure);
 
     return ok(
-      combineSchemaResults(
+      combineVerifyResults(
         aggregateResult.value.schemaResults,
         aggregateResult.value.appSpaceId,
         options.strict ?? false,
+        aggregateResult.value.unclaimed,
       ),
     );
   } catch (error) {
@@ -542,18 +542,18 @@ export function createDbVerifyCommand(): Command {
 
       if (mode === 'schema-only') {
         const result = await executeDbSchemaOnlyVerifyCommand(options, flags, ui);
-        const exitCode = handleResult(result, flags, ui, (schemaVerifyResult) => {
+        const exitCode = handleResult(result, flags, ui, (combined) => {
           if (flags.json) {
-            ui.output(formatSchemaVerifyJson(schemaVerifyResult));
+            ui.output(formatSchemaVerifyJson(combined.result, combined.unclaimed));
           } else {
-            const output = formatSchemaVerifyOutput(schemaVerifyResult, flags);
+            const output = formatSchemaVerifyOutput(combined.result, flags, combined.unclaimed);
             if (output) {
               ui.log(output);
             }
           }
         });
 
-        if (result.ok && !result.value.ok) {
+        if (result.ok && !result.value.result.ok) {
           process.exit(1);
         }
 
@@ -580,11 +580,15 @@ export function createDbVerifyCommand(): Command {
       }
 
       if (flags.json) {
-        ui.output(formatSchemaVerifyJson(result.failure));
+        ui.output(formatSchemaVerifyJson(result.failure.result, result.failure.unclaimed));
       } else {
         // Always show schema-drift failures, even in quiet mode — exiting 1 without
         // diagnostics is unhelpful.
-        const output = formatSchemaVerifyOutput(result.failure, { ...flags, quiet: false });
+        const output = formatSchemaVerifyOutput(
+          result.failure.result,
+          { ...flags, quiet: false },
+          result.failure.unclaimed,
+        );
         if (output) {
           ui.log(output);
         }