@prisma-next/migration-tools 0.5.0-dev.9 → 0.5.0

package/src/aggregate/planner.ts

@@ -0,0 +1,158 @@
+import { notOk, ok } from '@prisma-next/utils/result';
+import type {
+  AggregatePerSpacePlan,
+  AggregatePlannerError,
+  AggregatePlannerInput,
+  AggregatePlannerOutput,
+} from './planner-types';
+import { graphWalkStrategy } from './strategies/graph-walk';
+import { synthStrategy } from './strategies/synth';
+import type { ContractSpaceMember } from './types';
+
+export type {
+  AggregateCurrentDBState,
+  AggregatePerSpacePlan,
+  AggregatePlannerError,
+  AggregatePlannerInput,
+  AggregatePlannerOutput,
+  AggregatePlannerSuccess,
+  CallerPolicy,
+} from './planner-types';
+
+/**
+ * Plan a migration across every member of a {@link ContractSpaceAggregate}.
+ *
+ * Strategy selection per member, in order; first match wins:
+ *
+ * 1. If `callerPolicy.ignoreGraphFor.has(member.spaceId)`:
+ *    - If `member.headRef.invariants` is empty → synth.
+ *    - Else → `policyConflict` (synth cannot satisfy authored invariants).
+ * 2. Else if `member.migrations.graph` is non-empty AND graph-walk
+ *    succeeds → graph-walk.
+ * 3. Else if `member.headRef.invariants` is empty → synth.
+ * 4. Else → graph-walk failure → `extensionPathUnreachable` /
+ *    `extensionPathUnsatisfiable`.
+ *
+ * Output `applyOrder` is `[...aggregate.extensions.map(spaceId), aggregate.app.spaceId]`
+ * — extensions alphabetical, then app — matching today's
+ * `concatenateSpaceApplyInputs` ordering. This preserves
+ * `MultiSpaceRunnerFailure.failingSpace` attribution byte-for-byte.
+ *
+ * Every emitted `MigrationPlan` has `targetId = aggregate.targetId`.
+ * No placeholder cast; no patch step.
+ */
+export async function planAggregate<TFamilyId extends string, TTargetId extends string>(
+  input: AggregatePlannerInput<TFamilyId, TTargetId>,
+): Promise<AggregatePlannerOutput> {
+  const { aggregate, currentDBState, callerPolicy } = input;
+  const allMembers: ReadonlyArray<ContractSpaceMember> = [aggregate.app, ...aggregate.extensions];
+
+  const perSpace = new Map<string, AggregatePerSpacePlan>();
+
+  // Iterate in apply order so a per-member error short-circuits the
+  // walk in the same order the runner would walk inputs.
+  const orderedMembers: ReadonlyArray<ContractSpaceMember> = [
+    ...aggregate.extensions,
+    aggregate.app,
+  ];
+
+  for (const member of orderedMembers) {
+    const otherMembers = allMembers.filter((m) => m.spaceId !== member.spaceId);
+    const currentMarker = currentDBState.markersBySpaceId.get(member.spaceId) ?? null;
+
+    const ignoreGraph = callerPolicy.ignoreGraphFor.has(member.spaceId);
+    const invariantsRequired = member.headRef.invariants.length > 0;
+
+    if (ignoreGraph && invariantsRequired) {
+      const conflict: AggregatePlannerError = {
+        kind: 'policyConflict',
+        spaceId: member.spaceId,
+        detail: `\`callerPolicy.ignoreGraphFor\` requested for space "${member.spaceId}", but the member declares non-empty head-ref invariants (${member.headRef.invariants.join(', ')}). Synthesising a plan from the contract IR cannot satisfy authored invariants — the graph must be walked. Either remove "${member.spaceId}" from \`ignoreGraphFor\` or amend the on-disk head ref to declare zero invariants.`,
+      };
+      return notOk(conflict);
+    }
+
+    if (ignoreGraph) {
+      const synthOutcome = await synthStrategy({
+        aggregateTargetId: aggregate.targetId,
+        member,
+        otherMembers,
+        schemaIntrospection: currentDBState.schemaIntrospection,
+        familyInstance: input.familyInstance,
+        migrations: input.migrations,
+        frameworkComponents: input.frameworkComponents,
+        operationPolicy: input.operationPolicy,
+      });
+      if (synthOutcome.kind === 'failure') {
+        return notOk({
+          kind: 'appSynthFailure',
+          spaceId: member.spaceId,
+          conflicts: synthOutcome.conflicts,
+        });
+      }
+      perSpace.set(member.spaceId, synthOutcome.result);
+      continue;
+    }
+
+    // Try graph-walk first when the graph has nodes; fall back to synth
+    // when the graph is empty AND no invariants are required.
+    if (member.migrations.graph.nodes.size > 0) {
+      const walked = graphWalkStrategy({
+        aggregateTargetId: aggregate.targetId,
+        member,
+        currentMarker,
+      });
+      if (walked.kind === 'ok') {
+        perSpace.set(member.spaceId, walked.result);
+        continue;
+      }
+      if (walked.kind === 'unreachable') {
+        return notOk({
+          kind: 'extensionPathUnreachable',
+          spaceId: member.spaceId,
+          target: member.headRef.hash,
+        });
+      }
+      // unsatisfiable — surface
+      return notOk({
+        kind: 'extensionPathUnsatisfiable',
+        spaceId: member.spaceId,
+        missingInvariants: walked.missing,
+      });
+    }
+
+    // Empty graph: synth is the only option, and it can only satisfy
+    // empty-invariant members.
+    if (invariantsRequired) {
+      return notOk({
+        kind: 'extensionPathUnsatisfiable',
+        spaceId: member.spaceId,
+        missingInvariants: [...member.headRef.invariants].sort(),
+      });
+    }
+
+    const synthOutcome = await synthStrategy({
+      aggregateTargetId: aggregate.targetId,
+      member,
+      otherMembers,
+      schemaIntrospection: currentDBState.schemaIntrospection,
+      familyInstance: input.familyInstance,
+      migrations: input.migrations,
+      frameworkComponents: input.frameworkComponents,
+      operationPolicy: input.operationPolicy,
+    });
+    if (synthOutcome.kind === 'failure') {
+      return notOk({
+        kind: 'appSynthFailure',
+        spaceId: member.spaceId,
+        conflicts: synthOutcome.conflicts,
+      });
+    }
+    perSpace.set(member.spaceId, synthOutcome.result);
+  }
+
+  return ok({
+    perSpace,
+    applyOrder: [...aggregate.extensions.map((m) => m.spaceId), aggregate.app.spaceId],
+  });
+}

package/src/aggregate/project-schema-to-space.ts

@@ -0,0 +1,64 @@
+import type { ContractSpaceMember } from './types';
+
+/**
+ * Project the introspected live schema to the slice claimed by a single
+ * contract-space member.
+ *
+ * Returns the same `schema` value with every top-level table claimed by
+ * **other** members of the aggregate removed. Tables not claimed by any
+ * member flow through unchanged — the planner / verifier sees them as
+ * orphans (extras in strict mode).
+ *
+ * Used by:
+ *
+ * - The aggregate planner's **synth strategy**: when synthesising a
+ *   plan against a member's contract, the live schema must be projected
+ *   to that member's slice so the planner doesn't treat tables claimed
+ *   by other members as "extras" and emit destructive ops to drop
+ *   them.
+ * - The aggregate verifier's **schemaCheck**: projects per member so the
+ *   single-contract `verifySqlSchema` only sees the slice claimed by
+ *   the member it is checking. Closes the F23 architectural concern
+ *   (multi-member deployments where each member's tables look like
+ *   extras to every other member's verify pass).
+ *
+ * **Duck-typing semantics**: the helper operates on `unknown` for the
+ * schema and falls through structurally if the shape doesn't match.
+ * Every family today exposes `storage.tables: Record<string, ...>` and
+ * the introspected schema mirrors the same shape; a future family with
+ * a different storage shape gets the schema returned unchanged rather
+ * than blowing up the aggregate planner.
+ */
+export function projectSchemaToSpace(
+  schema: unknown,
+  member: ContractSpaceMember,
+  otherMembers: ReadonlyArray<ContractSpaceMember>,
+): unknown {
+  if (typeof schema !== 'object' || schema === null) return schema;
+  const schemaObj = schema as { readonly tables?: unknown };
+  if (typeof schemaObj.tables !== 'object' || schemaObj.tables === null) return schema;
+  const schemaTables = schemaObj.tables as Record<string, unknown>;
+
+  const ownedByOthers = new Set<string>();
+  for (const other of otherMembers) {
+    if (other.spaceId === member.spaceId) continue;
+    const storage = (other.contract as { readonly storage?: unknown }).storage;
+    if (typeof storage !== 'object' || storage === null) continue;
+    const tables = (storage as { readonly tables?: unknown }).tables;
+    if (typeof tables !== 'object' || tables === null) continue;
+    for (const tableName of Object.keys(tables as Record<string, unknown>)) {
+      ownedByOthers.add(tableName);
+    }
+  }
+
+  if (ownedByOthers.size === 0) return schema;
+
+  const prunedTables: Record<string, unknown> = {};
+  for (const [name, table] of Object.entries(schemaTables)) {
+    if (!ownedByOthers.has(name)) {
+      prunedTables[name] = table;
+    }
+  }
+
+  return { ...schemaObj, tables: prunedTables };
+}

package/src/aggregate/strategies/graph-walk.ts

@@ -0,0 +1,118 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { MigrationPlan } from '@prisma-next/framework-components/control';
+import { EMPTY_CONTRACT_HASH } from '../../constants';
+import { findPathWithDecision } from '../../migration-graph';
+import type { MigrationOps } from '../../package';
+import type { ContractMarkerRecordLike } from '../marker-types';
+import type { AggregatePerSpacePlan } from '../planner-types';
+import type { ContractSpaceMember } from '../types';
+
+/**
+ * Outcome variants for the graph-walk strategy. Mirrors
+ * {@link import('../../compute-extension-space-apply-path').ExtensionSpaceApplyPathOutcome}
+ * but operates against the **already-hydrated** `member.migrations.graph`
+ * instead of re-reading from disk. The aggregate planner converts
+ * these into {@link import('../planner-types').AggregatePlannerError}
+ * variants.
+ */
+export type GraphWalkOutcome =
+  | { readonly kind: 'ok'; readonly result: AggregatePerSpacePlan }
+  | { readonly kind: 'unreachable' }
+  | { readonly kind: 'unsatisfiable'; readonly missing: readonly string[] };
+
+export interface GraphWalkStrategyInputs {
+  readonly aggregateTargetId: string;
+  readonly member: ContractSpaceMember;
+  readonly currentMarker: ContractMarkerRecordLike | null;
+  /**
+   * Optional ref name to decorate the resulting `PathDecision`. Used by
+   * `migration apply` to surface the user-supplied `--ref <name>` in
+   * structured-progress events and invariant-path error envelopes. The
+   * strategy itself does not interpret it.
+   */
+  readonly refName?: string;
+}
+
+/**
+ * Walk a member's hydrated migration graph from the live marker to
+ * `member.headRef.hash`, covering every required invariant.
+ *
+ * Pure synchronous function — no I/O. The aggregate's loader has
+ * already integrity-checked every package and reconstructed the graph;
+ * this strategy just looks up ops by `migrationHash` and assembles a
+ * `MigrationPlan` with `targetId` set from the aggregate (no
+ * placeholder cast).
+ *
+ * Required invariants are computed as `headRef.invariants \ marker.invariants`
+ * — the marker already declares some invariants satisfied; the path
+ * only needs to provide the remainder. Mirrors today's
+ * `computeExtensionSpaceApplyPath` semantics.
+ */
+export function graphWalkStrategy(input: GraphWalkStrategyInputs): GraphWalkOutcome {
+  const { aggregateTargetId, member, currentMarker, refName } = input;
+  const { graph, packagesByMigrationHash } = member.migrations;
+
+  const fromHash = currentMarker?.storageHash ?? EMPTY_CONTRACT_HASH;
+  const markerInvariants = new Set(currentMarker?.invariants ?? []);
+  const required = new Set(member.headRef.invariants.filter((id) => !markerInvariants.has(id)));
+
+  const outcome = findPathWithDecision(graph, fromHash, member.headRef.hash, {
+    required,
+    ...(refName !== undefined ? { refName } : {}),
+  });
+
+  if (outcome.kind === 'unreachable') {
+    return { kind: 'unreachable' };
+  }
+  if (outcome.kind === 'unsatisfiable') {
+    return { kind: 'unsatisfiable', missing: outcome.missing };
+  }
+
+  const pathOps: MigrationOps[number][] = [];
+  const providedInvariantsSet = new Set<string>();
+  const edgeRefs: Array<{
+    migrationHash: string;
+    dirName: string;
+    from: string;
+    to: string;
+    operationCount: number;
+  }> = [];
+  for (const edge of outcome.decision.selectedPath) {
+    const pkg = packagesByMigrationHash.get(edge.migrationHash);
+    if (!pkg) {
+      throw new Error(
+        `Migration package missing for edge ${edge.migrationHash} in space "${member.spaceId}". The hydrated migration graph and packagesByMigrationHash map are out of sync — this should be unreachable; report.`,
+      );
+    }
+    for (const op of pkg.ops) pathOps.push(op);
+    for (const invariant of pkg.metadata.providedInvariants) providedInvariantsSet.add(invariant);
+    edgeRefs.push({
+      migrationHash: edge.migrationHash,
+      dirName: edge.dirName,
+      from: edge.from,
+      to: edge.to,
+      operationCount: pkg.ops.length,
+    });
+  }
+
+  const plan: MigrationPlan = {
+    targetId: aggregateTargetId,
+    spaceId: member.spaceId,
+    origin: currentMarker === null ? null : { storageHash: currentMarker.storageHash },
+    destination: { storageHash: member.headRef.hash },
+    operations: pathOps,
+    providedInvariants: [...providedInvariantsSet].sort(),
+  };
+
+  return {
+    kind: 'ok',
+    result: {
+      plan,
+      displayOps: pathOps,
+      destinationContract: member.contract as Contract,
+      strategy: 'graph-walk',
+      migrationEdges: edgeRefs,
+      pathDecision: outcome.decision,
+    },
+  };
+}

package/src/aggregate/strategies/synth.ts

@@ -0,0 +1,122 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type {
+  ControlFamilyInstance,
+  MigrationOperationPolicy,
+  MigrationPlan,
+  MigrationPlannerConflict,
+  MigrationPlannerResult,
+  TargetMigrationsCapability,
+} from '@prisma-next/framework-components/control';
+import type { AggregatePerSpacePlan } from '../planner-types';
+import { projectSchemaToSpace } from '../project-schema-to-space';
+import type { ContractSpaceMember } from '../types';
+
+export interface SynthStrategyInputs<TFamilyId extends string, TTargetId extends string> {
+  readonly aggregateTargetId: string;
+  readonly member: ContractSpaceMember;
+  readonly otherMembers: ReadonlyArray<ContractSpaceMember>;
+  readonly schemaIntrospection: unknown;
+  readonly familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
+  readonly migrations: TargetMigrationsCapability<
+    TFamilyId,
+    TTargetId,
+    ControlFamilyInstance<TFamilyId, unknown>
+  >;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  readonly operationPolicy: MigrationOperationPolicy;
+}
+
+export type SynthStrategyOutcome =
+  | { readonly kind: 'ok'; readonly result: AggregatePerSpacePlan }
+  | { readonly kind: 'failure'; readonly conflicts: readonly MigrationPlannerConflict[] };
+
+/**
+ * The {@link MigrationPlanner.plan} interface is declared as synchronous,
+ * but historical and test fixture call sites have always invoked it
+ * with `await` (see prior `db-apply-per-space.ts`). Tolerating a
+ * Promise here keeps existing test mocks working without changing the
+ * declared family SPI.
+ */
+type MaybeAsyncPlannerResult = MigrationPlannerResult | Promise<MigrationPlannerResult>;
+
+/**
+ * Synthesise a migration plan for a single member by projecting the
+ * live schema down to that member's claimed slice and delegating to
+ * the family's `createPlanner(...).plan(...)`.
+ *
+ * Pre-projection (via {@link projectSchemaToSpace}) closes the F23
+ * concern: without it, the family's planner sees other members'
+ * tables as "extras" and emits destructive ops to drop them. With it,
+ * the planner only sees the slice this member claims.
+ *
+ * The synthesised plan's `targetId` is set from `aggregateTargetId`
+ * (the aggregate's ambient target). The family's planner does not
+ * stamp `targetId` on the produced plan; the aggregate planner is
+ * the single point that knows the target.
+ *
+ * Used by:
+ *
+ * - The app member by default (CLI policy
+ *   `ignoreGraphFor: { app.spaceId }`).
+ * - Any extension member whose `headRef.invariants` is empty (the
+ *   strategy selector falls back to synth when graph-walk isn't
+ *   required).
+ */
+export async function synthStrategy<TFamilyId extends string, TTargetId extends string>(
+  input: SynthStrategyInputs<TFamilyId, TTargetId>,
+): Promise<SynthStrategyOutcome> {
+  const projectedSchema = projectSchemaToSpace(
+    input.schemaIntrospection,
+    input.member,
+    input.otherMembers,
+  );
+
+  const planner = input.migrations.createPlanner(input.familyInstance);
+  const plannerResult: MigrationPlannerResult = await (planner.plan({
+    contract: input.member.contract,
+    schema: projectedSchema,
+    policy: input.operationPolicy,
+    fromContract: null,
+    frameworkComponents: input.frameworkComponents,
+    spaceId: input.member.spaceId,
+  }) as MaybeAsyncPlannerResult);
+
+  if (plannerResult.kind === 'failure') {
+    return { kind: 'failure', conflicts: plannerResult.conflicts };
+  }
+
+  const synthedPlan = plannerResult.plan;
+  // The family planner returns a class-instance-shaped plan whose
+  // `destination` / `operations` are accessors on the prototype, often
+  // backed by private fields. A naive spread (`{ ...synthedPlan }`)
+  // would lose those accessors and produce a plan with
+  // `destination: undefined`; rebinding the prototype on a plain
+  // object would break private-field access. We instead wrap the plan
+  // in a Proxy that forwards every read except `targetId`, which is
+  // stamped from the aggregate's ambient target. This preserves the
+  // planner's class semantics while keeping the aggregate the single
+  // source of truth for `targetId`.
+  const plan: MigrationPlan = new Proxy(synthedPlan, {
+    get(target, prop) {
+      if (prop === 'targetId') return input.aggregateTargetId;
+      // Forward `this` as the original target so prototype-bound
+      // private fields (#destination, #operations, …) resolve.
+      return Reflect.get(target, prop, target);
+    },
+    has(target, prop) {
+      if (prop === 'targetId') return true;
+      return Reflect.has(target, prop);
+    },
+  });
+
+  return {
+    kind: 'ok',
+    result: {
+      plan,
+      displayOps: synthedPlan.operations,
+      destinationContract: input.member.contract as Contract,
+      strategy: 'synth',
+    },
+  };
+}

package/src/aggregate/types.ts

@@ -0,0 +1,89 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { MigrationGraph } from '../graph';
+import type { OnDiskMigrationPackage } from '../package';
+
+/**
+ * Hydrated migration graph for a single contract space.
+ *
+ * `graph` is the structural shortest-path graph (forward / reverse chain,
+ * deterministic tie-break order) reconstructed from a set of on-disk
+ * migration packages. `packagesByMigrationHash` is the lookup table the
+ * graph-walk strategy uses to resolve a path's edge sequence back to the
+ * concrete `OnDiskMigrationPackage` (and therefore the operation list) for
+ * apply.
+ *
+ * Eagerly hydrated by the loader. Once a `ContractSpaceAggregate` exists,
+ * downstream consumers do **not** touch the filesystem to walk graphs or
+ * resolve packages — the aggregate is the boundary.
+ */
+export interface HydratedMigrationGraph {
+  readonly graph: MigrationGraph;
+  readonly packagesByMigrationHash: ReadonlyMap<string, OnDiskMigrationPackage>;
+}
+
+/**
+ * One contract space — app or extension — as a member of a
+ * {@link ContractSpaceAggregate}. Every member has the same shape.
+ *
+ * - `spaceId`: `'app'` for the application, otherwise the extension's
+ *   id (validated against `[a-z][a-z0-9_-]{0,63}`).
+ * - `contract`: the validated contract value for this member. For the
+ *   app, the user's authored contract; for an extension, the on-disk
+ *   `migrations/<spaceId>/contract.json`. Both have already passed the
+ *   family's `validateContract` at the loader boundary.
+ * - `headRef.hash`: the storage hash this member is targeting. For the
+ *   app, equals `contract.storage.storageHash`. For extensions, the
+ *   on-disk `refs/head.json.hash`.
+ * - `headRef.invariants`: alphabetically sorted, deduplicated invariant
+ *   ids declared on the head ref. Empty for the app member (the app's
+ *   plan is synthesised from the contract IR, no invariants required).
+ * - `migrations`: the hydrated migration graph for this space. Possibly
+ *   empty (an extension whose on-disk head ref points at the
+ *   empty-contract sentinel and ships no migrations yet, or the app
+ *   when the user hasn't authored any).
+ */
+export interface ContractSpaceMember {
+  readonly spaceId: string;
+  readonly contract: Contract;
+  readonly headRef: {
+    readonly hash: string;
+    readonly invariants: readonly string[];
+  };
+  readonly migrations: HydratedMigrationGraph;
+}
+
+/**
+ * Typed value carrying the user's app contract plus every loaded
+ * extension contract space, fully hydrated and internally consistent.
+ *
+ * Produced once per CLI invocation by `loadContractSpaceAggregate`.
+ * Every downstream component (planner, verifier, runner adapter)
+ * consumes this value rather than rebuilding state from disk.
+ *
+ * Invariants the loader enforces at construction:
+ *
+ * 1. `targetId` is consistent across every member (`contract.target`
+ *    matches `aggregate.targetId`). The aggregate's `targetId` is the
+ *    `Config.adapter.targetId` value the loader was told to use.
+ * 2. `aggregate.extensions` is sorted alphabetically by `spaceId`.
+ *    Mirrors {@link import('../concatenate-space-apply-inputs').concatenateSpaceApplyInputs}'s
+ *    extension ordering convention so downstream apply order matches
+ *    today's behaviour byte-for-byte.
+ * 3. No two members claim the same storage element (table / type / etc.).
+ * 4. For each extension member: `member.headRef.hash` is reachable from
+ *    the empty-contract sentinel in `member.migrations.graph` (or the
+ *    graph is empty and `member.headRef.hash === EMPTY_CONTRACT_HASH`).
+ * 5. For the app member: `member.headRef.hash` equals
+ *    `member.contract.storage.storageHash`. The app's `migrations`
+ *    is hydrated from the user's authored `migrations/` (or empty if
+ *    none).
+ *
+ * The aggregate is **type-uniform** post-construction: app/extension
+ * distinguishability survives only at the caller-policy layer
+ * (`ignoreGraphFor: new Set([appSpaceId])`), not on member shape.
+ */
+export interface ContractSpaceAggregate {
+  readonly targetId: string;
+  readonly app: ContractSpaceMember;
+  readonly extensions: readonly ContractSpaceMember[];
+}