@prisma-next/migration-tools 0.5.0-dev.8 → 0.5.0-dev.80

package/src/aggregate/loader.ts

@@ -0,0 +1,409 @@
+import type { Contract } from '@prisma-next/contract/types';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { EMPTY_CONTRACT_HASH } from '../constants';
+import { detectSpaceContractDrift } from '../detect-space-contract-drift';
+import { readMigrationsDir } from '../io';
+import { reconstructGraph } from '../migration-graph';
+import type { OnDiskMigrationPackage } from '../package';
+import { readContractSpaceContract } from '../read-contract-space-contract';
+import { readContractSpaceHeadRef } from '../read-contract-space-head-ref';
+import { APP_SPACE_ID, spaceMigrationDirectory } from '../space-layout';
+import { listContractSpaceDirectories } from '../verify-contract-spaces';
+import type { ContractSpaceAggregate, ContractSpaceMember, HydratedMigrationGraph } from './types';
+
+/**
+ * Hash function used by drift detection. Defaults to a canonical-JSON +
+ * SHA-256 pipeline that mirrors the framework's contract-hash convention,
+ * but the loader accepts a callback so SQL-family callers can pass their
+ * `coreHash` / `storageHash` derivation through unchanged.
+ *
+ * The contract value passed in is the framework-neutral `unknown` form;
+ * callers that have already validated typed contracts can simply hand
+ * the validated value back through.
+ */
+export type AggregateContractHasher = (contract: unknown) => string;
+
+/**
+ * Single declared extension entry the loader needs from `Config.extensionPacks`.
+ *
+ * Only the subset of fields the loader operates on:
+ *
+ * - `id` — the space id (also the directory name under `migrations/`).
+ * - `targetId` — the configured `Config.adapter.targetId` value the
+ *   declaring extension declared. The loader rejects mismatches against
+ *   the aggregate's `targetId` with `targetMismatch`.
+ * - `contractSpace` — present iff the descriptor declares a contract
+ *   space (extensions can ship without one and remain runtime-only /
+ *   codec-only). Drift detection compares the descriptor's
+ *   `contractJson` hash against the on-disk on-disk head hash; the loader
+ *   rejects drift fatally.
+ *
+ * Typed structurally so the migration-tools layer stays framework-neutral.
+ */
+export interface DeclaredExtensionEntry {
+  readonly id: string;
+  readonly targetId: string;
+  readonly contractSpace?: {
+    readonly contractJson: unknown;
+  };
+}
+
+/**
+ * Inputs for {@link loadContractSpaceAggregate}.
+ *
+ * The loader is the **sole** descriptor-import boundary in the M2.5
+ * pipeline: callers gather the descriptor data (already-validated app
+ * contract, declared extension entries) and pass it through. Once the
+ * loader returns, no descriptor module is imported again for this
+ * aggregate's lifetime.
+ */
+export interface LoadAggregateInput {
+  readonly targetId: string;
+  readonly migrationsDir: string;
+  readonly appContract: Contract;
+  readonly declaredExtensions: ReadonlyArray<DeclaredExtensionEntry>;
+  readonly validateContract: (contractJson: unknown) => Contract;
+  readonly hashContract: AggregateContractHasher;
+  /**
+   * Hydrated migration graph for the **app member**.
+   *
+   * The framework-neutral migration-tools layer doesn't know how to read
+   * the user's authored `migrations/` directory (the app member's
+   * migration-package layout is family-aware: ops.json shape, manifest
+   * keys, etc.). Callers — the SQL family today — read the user's
+   * `migrations/` and hand the resulting `OnDiskMigrationPackage[]` through.
+   *
+   * Passing `[]` is valid (greenfield project, no authored migrations).
+   * Equivalent to `migrations/` not existing or being empty.
+   */
+  readonly appMigrationPackages: ReadonlyArray<OnDiskMigrationPackage>;
+}
+
+/**
+ * Discriminated failure variants the loader emits.
+ *
+ * Every variant short-circuits at first hit; the loader does not keep
+ * collecting after the first violation in any phase except for layout
+ * (where every layout offence is bundled into one `layoutViolation`).
+ */
+export type LoadAggregateError =
+  | { readonly kind: 'layoutViolation'; readonly violations: readonly LayoutViolation[] }
+  | { readonly kind: 'integrityFailure'; readonly spaceId: string; readonly detail: string }
+  | { readonly kind: 'validationFailure'; readonly spaceId: string; readonly detail: string }
+  | {
+      readonly kind: 'driftViolation';
+      readonly spaceId: string;
+      readonly priorHeadHash: string;
+      readonly liveHash: string;
+    }
+  | {
+      readonly kind: 'disjointnessViolation';
+      readonly element: string;
+      readonly claimedBy: readonly string[];
+    }
+  | {
+      readonly kind: 'targetMismatch';
+      readonly spaceId: string;
+      readonly expected: string;
+      readonly actual: string;
+    };
+
+/**
+ * Single layout violation; bundled into a `layoutViolation` error so
+ * users see every layout offence at once rather than fixing them one
+ * at a time across re-runs.
+ *
+ * - `declaredButUnmigrated`: extension declared in `extensionPacks` with
+ *   a `contractSpace` but no contract-space dir on disk. Remediation:
+ *   `prisma-next migrate`.
+ * - `orphanSpaceDir`: contract-space dir under `migrations/` for an extension
+ *   not in `extensionPacks`. Remediation: remove the directory, or
+ *   re-add the extension to `extensionPacks`.
+ */
+export type LayoutViolation =
+  | { readonly kind: 'declaredButUnmigrated'; readonly spaceId: string }
+  | { readonly kind: 'orphanSpaceDir'; readonly spaceId: string };
+
+export type LoadAggregateOutput = Result<
+  { readonly aggregate: ContractSpaceAggregate },
+  LoadAggregateError
+>;
+
+interface LoadedExtensionState {
+  readonly entry: DeclaredExtensionEntry;
+  readonly contract: Contract;
+  readonly headRefHash: string;
+  readonly headRefInvariants: readonly string[];
+  readonly migrations: HydratedMigrationGraph;
+}
+
+/**
+ * Hydrate a {@link ContractSpaceAggregate} from on-disk state and
+ * caller-provided descriptor data.
+ *
+ * This is the **only** descriptor-import boundary in the post-M2.5
+ * pipeline: callers read `extensionPacks` from `Config`, validate the
+ * app contract, and pass everything through. The loader composes
+ * existing migration-tools primitives — layout precheck (via
+ * {@link listContractSpaceDirectories}), integrity checks (via
+ * {@link readMigrationsDir} / {@link readContractSpaceHeadRef} /
+ * {@link readContractSpaceContract} / `validateContract`), drift detection
+ * (via {@link detectSpaceContractDrift}), and disjointness — into a
+ * single typed value.
+ *
+ * Failure semantics: every failure variant in {@link LoadAggregateError}
+ * short-circuits the load. Drift is fatal (M2.5 spec § Loader, step 5).
+ */
+export async function loadContractSpaceAggregate(
+  input: LoadAggregateInput,
+): Promise<LoadAggregateOutput> {
+  // 1. Validate target consistency on the app contract.
+  const appContractTarget = input.appContract.target;
+  if (appContractTarget !== input.targetId) {
+    return notOk({
+      kind: 'targetMismatch',
+      spaceId: APP_SPACE_ID,
+      expected: input.targetId,
+      actual: appContractTarget,
+    });
+  }
+
+  for (const entry of input.declaredExtensions) {
+    if (entry.targetId !== input.targetId) {
+      return notOk({
+        kind: 'targetMismatch',
+        spaceId: entry.id,
+        expected: input.targetId,
+        actual: entry.targetId,
+      });
+    }
+  }
+
+  // 2. Layout precheck: bundle every layout offence at once.
+  const declaredWithSpace = input.declaredExtensions.filter((e) => e.contractSpace !== undefined);
+  const declaredSpaceIds = new Set(declaredWithSpace.map((e) => e.id));
+  const allDirs = await listContractSpaceDirectories(input.migrationsDir);
+  // The app member is implicitly declared (it is always part of the
+  // aggregate); its `migrations/<APP_SPACE_ID>/` directory may exist or
+  // not (greenfield projects start with neither). Filter it out of the
+  // orphan / declared-but-unmigrated checks so the layout precheck is
+  // about extensions only.
+  const extensionDirsOnDisk = allDirs.filter((d) => d !== APP_SPACE_ID);
+  const spaceDirSet = new Set(extensionDirsOnDisk);
+
+  const layoutViolations: LayoutViolation[] = [];
+  for (const dir of extensionDirsOnDisk) {
+    if (!declaredSpaceIds.has(dir)) {
+      layoutViolations.push({ kind: 'orphanSpaceDir', spaceId: dir });
+    }
+  }
+  for (const id of [...declaredSpaceIds].sort()) {
+    if (!spaceDirSet.has(id)) {
+      layoutViolations.push({ kind: 'declaredButUnmigrated', spaceId: id });
+    }
+  }
+  if (layoutViolations.length > 0) {
+    return notOk({ kind: 'layoutViolation', violations: layoutViolations });
+  }
+
+  // 3-5. Per-extension: read + validate + integrity-check + drift.
+  const loadedExtensions: LoadedExtensionState[] = [];
+  for (const entry of [...declaredWithSpace].sort((a, b) => a.id.localeCompare(b.id))) {
+    const headRef = await readContractSpaceHeadRef(input.migrationsDir, entry.id);
+    if (headRef === null) {
+      return notOk({
+        kind: 'integrityFailure',
+        spaceId: entry.id,
+        detail: `Head ref \`refs/head.json\` is missing for extension space "${entry.id}".`,
+      });
+    }
+
+    let spaceContractRaw: unknown;
+    try {
+      spaceContractRaw = await readContractSpaceContract(input.migrationsDir, entry.id);
+    } catch (error) {
+      return notOk({
+        kind: 'integrityFailure',
+        spaceId: entry.id,
+        detail: error instanceof Error ? error.message : String(error),
+      });
+    }
+
+    let spaceContract: Contract;
+    try {
+      spaceContract = input.validateContract(spaceContractRaw);
+    } catch (error) {
+      return notOk({
+        kind: 'validationFailure',
+        spaceId: entry.id,
+        detail: error instanceof Error ? error.message : String(error),
+      });
+    }
+
+    if (spaceContract.target !== input.targetId) {
+      return notOk({
+        kind: 'targetMismatch',
+        spaceId: entry.id,
+        expected: input.targetId,
+        actual: spaceContract.target,
+      });
+    }
+
+    // Drift: compare descriptor's live `contractJson` to on-disk
+    // `refs/head.json.hash`.
+    if (entry.contractSpace) {
+      const liveHash = input.hashContract(entry.contractSpace.contractJson);
+      const drift = detectSpaceContractDrift(entry.id, {
+        descriptorHash: liveHash,
+        priorHeadHash: headRef.hash,
+      });
+      if (drift.kind === 'drift') {
+        return notOk({
+          kind: 'driftViolation',
+          spaceId: entry.id,
+          priorHeadHash: drift.priorHeadHash ?? '',
+          liveHash: drift.descriptorHash,
+        });
+      }
+    }
+
+    // Read + integrity-check the migration packages. `readMigrationsDir`
+    // re-derives `providedInvariants` and verifies migrationHash for
+    // every package.
+    let packages: readonly OnDiskMigrationPackage[];
+    try {
+      packages = await readMigrationsDir(spaceMigrationDirectory(input.migrationsDir, entry.id));
+    } catch (error) {
+      return notOk({
+        kind: 'integrityFailure',
+        spaceId: entry.id,
+        detail: error instanceof Error ? error.message : String(error),
+      });
+    }
+
+    let graph: ReturnType<typeof reconstructGraph>;
+    try {
+      graph = reconstructGraph(packages);
+    } catch (error) {
+      return notOk({
+        kind: 'integrityFailure',
+        spaceId: entry.id,
+        detail: error instanceof Error ? error.message : String(error),
+      });
+    }
+
+    // The on-disk head ref must be reachable in the graph. Empty graphs
+    // are tolerated only when the head ref points at the empty-contract
+    // sentinel (a never-emitted extension space; not a typical scenario
+    // because the layout precheck would have flagged the missing
+    // dir, but defensible).
+    if (graph.nodes.size === 0) {
+      if (headRef.hash !== EMPTY_CONTRACT_HASH) {
+        return notOk({
+          kind: 'integrityFailure',
+          spaceId: entry.id,
+          detail: `Head ref "${headRef.hash}" is not present in the (empty) on-disk migration graph.`,
+        });
+      }
+    } else if (!graph.nodes.has(headRef.hash)) {
+      return notOk({
+        kind: 'integrityFailure',
+        spaceId: entry.id,
+        detail: `Head ref "${headRef.hash}" is not present in the on-disk migration graph.`,
+      });
+    }
+
+    const packagesByMigrationHash = new Map<string, OnDiskMigrationPackage>(
+      packages.map((p) => [p.metadata.migrationHash, p]),
+    );
+
+    loadedExtensions.push({
+      entry,
+      contract: spaceContract,
+      headRefHash: headRef.hash,
+      headRefInvariants: [...headRef.invariants].sort(),
+      migrations: { graph, packagesByMigrationHash },
+    });
+  }
+
+  // 6. Build app member with hydrated graph from caller-supplied packages.
+  let appGraph: ReturnType<typeof reconstructGraph>;
+  try {
+    appGraph = reconstructGraph(input.appMigrationPackages);
+  } catch (error) {
+    return notOk({
+      kind: 'integrityFailure',
+      spaceId: APP_SPACE_ID,
+      detail: error instanceof Error ? error.message : String(error),
+    });
+  }
+  const appPackagesByMigrationHash = new Map<string, OnDiskMigrationPackage>(
+    input.appMigrationPackages.map((p) => [p.metadata.migrationHash, p]),
+  );
+
+  const appMember: ContractSpaceMember = {
+    spaceId: APP_SPACE_ID,
+    contract: input.appContract,
+    headRef: {
+      hash: input.appContract.storage.storageHash,
+      invariants: [],
+    },
+    migrations: {
+      graph: appGraph,
+      packagesByMigrationHash: appPackagesByMigrationHash,
+    },
+  };
+
+  const extensionMembers: ContractSpaceMember[] = loadedExtensions.map((s) => ({
+    spaceId: s.entry.id,
+    contract: s.contract,
+    headRef: {
+      hash: s.headRefHash,
+      invariants: s.headRefInvariants,
+    },
+    migrations: s.migrations,
+  }));
+
+  // 7. Disjointness: no two members claim the same storage element.
+  const elementClaimedBy = new Map<string, string[]>();
+  for (const member of [appMember, ...extensionMembers]) {
+    const tables = extractTableNames(member.contract);
+    for (const tableName of tables) {
+      const claimers = elementClaimedBy.get(tableName);
+      if (claimers) claimers.push(member.spaceId);
+      else elementClaimedBy.set(tableName, [member.spaceId]);
+    }
+  }
+  for (const [element, claimedBy] of elementClaimedBy) {
+    if (claimedBy.length > 1) {
+      return notOk({
+        kind: 'disjointnessViolation',
+        element,
+        claimedBy: [...claimedBy].sort(),
+      });
+    }
+  }
+
+  return ok({
+    aggregate: {
+      targetId: input.targetId,
+      app: appMember,
+      extensions: extensionMembers,
+    },
+  });
+}
+
+/**
+ * Extract the set of top-level storage table names from a contract.
+ * Duck-typed: returns `[]` if the contract's storage shape doesn't
+ * match the canonical `storage.tables: Record<string, ...>` form. A
+ * future family with a different storage shape gets disjointness
+ * effectively disabled (not enforced) rather than a hard failure.
+ */
+function extractTableNames(contract: Contract): readonly string[] {
+  const storage = (contract as { readonly storage?: unknown }).storage;
+  if (typeof storage !== 'object' || storage === null) return [];
+  const tables = (storage as { readonly tables?: unknown }).tables;
+  if (typeof tables !== 'object' || tables === null) return [];
+  return Object.keys(tables as Record<string, unknown>);
+}

package/src/aggregate/marker-types.ts

@@ -0,0 +1,16 @@
+/**
+ * Structural shape the aggregate planner / verifier accept for marker
+ * rows. Mirrors `family.readAllMarkers(...)` outputs across SQL and
+ * Mongo families: a `(storageHash, invariants)` pair plus an optional
+ * `profileHash` the verifier uses to align the marker with the
+ * destination contract's profile envelope.
+ *
+ * Typed structurally so `migration-tools` stays framework-neutral; SQL
+ * and Mongo families pass their typed `ContractMarkerRecord` through
+ * unchanged.
+ */
+export interface ContractMarkerRecordLike {
+  readonly storageHash: string;
+  readonly invariants: readonly string[];
+  readonly profileHash?: string;
+}

package/src/aggregate/planner-types.ts

@@ -0,0 +1,171 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type {
+  ControlFamilyInstance,
+  MigrationOperationPolicy,
+  MigrationPlan,
+  MigrationPlannerConflict,
+  MigrationPlanOperation,
+  TargetMigrationsCapability,
+} from '@prisma-next/framework-components/control';
+import type { Result } from '@prisma-next/utils/result';
+import type { PathDecision } from '../migration-graph';
+import type { ContractMarkerRecordLike } from './marker-types';
+import type { ContractSpaceAggregate } from './types';
+
+/**
+ * Caller-provided policy for {@link planAggregate}. Today this carries
+ * just one knob:
+ *
+ * - `ignoreGraphFor`: `Set<spaceId>`. For listed members, the planner
+ *   forces the **synth** strategy (synthesise a plan from the contract
+ *   IR via `familyInstance.createPlanner(...).plan(...)`) regardless of
+ *   whether a graph is available. The CLI's daily-driver `db init` /
+ *   `db update` pipelines pass `new Set([aggregate.app.spaceId])` to
+ *   keep today's app-space behaviour: the user's authored
+ *   `migrations/` directory is **not** walked for the app member, the
+ *   plan is synthesised on the fly. Extension members are walked.
+ *
+ *   Listing a member here whose `headRef.invariants` is non-empty is
+ *   a `policyConflict` — synth cannot satisfy authored invariants.
+ */
+export interface CallerPolicy {
+  readonly ignoreGraphFor: ReadonlySet<string>;
+}
+
+/**
+ * Snapshot of the live database state the planner needs to drive
+ * strategy selection.
+ *
+ * - `markersBySpaceId`: per-space marker rows. Absent entry = no
+ *   marker yet (greenfield space). The planner treats the marker's
+ *   `storageHash` as the graph-walk's `from` node, falling back to
+ *   {@link import('../constants').EMPTY_CONTRACT_HASH} when absent.
+ * - `schemaIntrospection`: the family's full live schema IR. Fed into
+ *   the synth strategy after per-space pre-projection via
+ *   {@link import('./project-schema-to-space').projectSchemaToSpace}.
+ *
+ * Callers (CLI commands) gather this via the family's
+ * `readAllMarkers` + `introspect` calls before invoking the planner.
+ * The planner itself does not touch the database.
+ */
+export interface AggregateCurrentDBState {
+  readonly markersBySpaceId: ReadonlyMap<string, ContractMarkerRecordLike | null>;
+  readonly schemaIntrospection: unknown;
+}
+
+/**
+ * Inputs to {@link planAggregate}.
+ *
+ * The planner is target-agnostic but family-aware: per-member synth
+ * delegates to the family's `createPlanner(familyInstance).plan(...)`,
+ * which is why `familyInstance`, `migrations` (the
+ * `TargetMigrationsCapability`), and `frameworkComponents` are all
+ * threaded through. (`frameworkComponents` is passed verbatim into
+ * `planner.plan(...)` per ADR 212; the planner does not interpret it.)
+ *
+ * The aggregate planner does **not** receive a `targetId` separately —
+ * it reads `aggregate.targetId` and stamps it onto every emitted
+ * `MigrationPlan` from construction. No placeholder, no patch step.
+ */
+export interface AggregatePlannerInput<TFamilyId extends string, TTargetId extends string> {
+  readonly aggregate: ContractSpaceAggregate;
+  readonly currentDBState: AggregateCurrentDBState;
+  readonly familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
+  readonly migrations: TargetMigrationsCapability<
+    TFamilyId,
+    TTargetId,
+    ControlFamilyInstance<TFamilyId, unknown>
+  >;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  readonly callerPolicy: CallerPolicy;
+  readonly operationPolicy: MigrationOperationPolicy;
+}
+
+/**
+ * Per-member output of the aggregate planner. The runner ingests this
+ * shape directly via a thin `toRunnerInput` adapter at the CLI.
+ *
+ * - `plan`: ready-to-execute `MigrationPlan` with `targetId` already
+ *   set from `aggregate.targetId`.
+ * - `displayOps`: same operation list, surfaced separately so plan-mode
+ *   output can render without touching the runner-bound `plan`.
+ * - `destinationContract`: the typed contract value the runner uses
+ *   for post-apply verification. For the app member, the user's
+ *   contract; for extension members, the on-disk `contract.json`.
+ * - `strategy`: which strategy produced this plan (`'graph-walk'` or
+ *   `'synth'`). Surfaced for diagnostics; not consumed by the runner.
+ */
+/**
+ * Per-edge metadata for the chain assembled by the graph-walk
+ * strategy. Lets `migration apply` surface a per-migration `applied[]`
+ * entry (preserving the single-space `migrationsApplied` count
+ * semantics) without re-walking the graph.
+ *
+ * `synth`-produced plans leave this absent — synthesised plans don't
+ * have authored edges to surface.
+ */
+export interface AggregateMigrationEdgeRef {
+  readonly migrationHash: string;
+  readonly dirName: string;
+  readonly from: string;
+  readonly to: string;
+  readonly operationCount: number;
+}
+
+export interface AggregatePerSpacePlan {
+  readonly plan: MigrationPlan;
+  readonly displayOps: readonly MigrationPlanOperation[];
+  readonly destinationContract: Contract;
+  readonly strategy: 'graph-walk' | 'synth';
+  /**
+   * Per-edge breakdown of the chain. Populated by the graph-walk
+   * strategy; absent for synth-produced plans.
+   */
+  readonly migrationEdges?: readonly AggregateMigrationEdgeRef[];
+  /**
+   * Path decision data the strategy used to select the chain
+   * (alternative count, tie-break reasons, required/satisfied
+   * invariants, per-edge invariants). Populated by the graph-walk
+   * strategy; absent for synth-produced plans.
+   *
+   * `migration apply` surfaces this for the app member as
+   * `MigrationApplySuccess.pathDecision` (back-compat with single-
+   * space callers).
+   */
+  readonly pathDecision?: PathDecision;
+}
+
+export interface AggregatePlannerSuccess {
+  readonly perSpace: ReadonlyMap<string, AggregatePerSpacePlan>;
+  /**
+   * `applyOrder` is the order the runner must walk per-space inputs.
+   * Mirrors the existing `concatenateSpaceApplyInputs` convention:
+   * extensions alphabetically by `spaceId`, then the app. Tests assert
+   * on `MultiSpaceRunnerFailure.failingSpace`, which is positional in
+   * the runner's input array — preserving the literal ordering keeps
+   * `failingSpace` attribution byte-for-byte.
+   */
+  readonly applyOrder: readonly string[];
+}
+
+/**
+ * Discriminated failure variants for {@link planAggregate}. Each
+ * variant short-circuits the plan; per-member errors carry the
+ * `spaceId` so the CLI can surface a precise envelope.
+ */
+export type AggregatePlannerError =
+  | { readonly kind: 'extensionPathUnreachable'; readonly spaceId: string; readonly target: string }
+  | {
+      readonly kind: 'extensionPathUnsatisfiable';
+      readonly spaceId: string;
+      readonly missingInvariants: readonly string[];
+    }
+  | {
+      readonly kind: 'appSynthFailure';
+      readonly spaceId: string;
+      readonly conflicts: readonly MigrationPlannerConflict[];
+    }
+  | { readonly kind: 'policyConflict'; readonly spaceId: string; readonly detail: string };
+
+export type AggregatePlannerOutput = Result<AggregatePlannerSuccess, AggregatePlannerError>;