@prisma-next/migration-tools 0.5.0-dev.67 → 0.5.0-dev.68

package/src/errors.ts

@@ -160,13 +160,19 @@ export function errorInvalidSpaceId(spaceId: string): MigrationToolsError {
   );
 }
 
-export function errorPinnedArtefactsAppSpace(): MigrationToolsError {
+export function errorDescriptorHeadHashMismatch(args: {
+  readonly extensionId: string;
+  readonly recomputedHash: string;
+  readonly headRefHash: string;
+}): MigrationToolsError {
+  const { extensionId, recomputedHash, headRefHash } = args;
   return new MigrationToolsError(
-    'MIGRATION.PINNED_ARTEFACTS_APP_SPACE',
-    'Pinned per-space artefacts do not apply to the app space',
+    'MIGRATION.DESCRIPTOR_HEAD_HASH_MISMATCH',
+    "Extension descriptor's headRef.hash does not match its contractJson",
     {
-      why: "Pinned `contract.json`/`contract.d.ts`/`refs/head.json` files only exist for extension spaces under `migrations/<space-id>/`. The app space's canonical contract lives at the project root (`contract.json`) — `emitPinnedSpaceArtefacts` is the wrong helper for it.",
-      fix: 'Pass an extension space id, or use the app-space contract emit pipeline for the project-root `contract.json` / `contract.d.ts`.',
+      why: `Extension "${extensionId}" publishes a \`contractSpace\` whose \`headRef.hash\` (${headRefHash}) does not match the canonical hash recomputed from \`contractSpace.contractJson\` (${recomputedHash}). This means the extension descriptor was published with stale \`headRef.hash\` — typically because the contract was bumped without rerunning the extension's emit pipeline.`,
+      fix: 'Re-run the extension authoring pipeline so `contractJson.storage.storageHash` and `headRef.hash` agree, then republish the extension. If you are the extension author and you intentionally bumped `contractJson`, recompute and update `headRef.hash` (and refresh any on-disk migration metadata that derives from it).',
+      details: { extensionId, recomputedHash, headRefHash },
     },
   );
 }

package/src/exports/aggregate.ts

@@ -0,0 +1,37 @@
+export {
+  type AggregateContractHasher,
+  type DeclaredExtensionEntry,
+  type LayoutViolation,
+  type LoadAggregateError,
+  type LoadAggregateInput,
+  type LoadAggregateOutput,
+  loadContractSpaceAggregate,
+} from '../aggregate/loader';
+export type { ContractMarkerRecordLike } from '../aggregate/marker-types';
+export {
+  type AggregateCurrentDBState,
+  type AggregatePerSpacePlan,
+  type AggregatePlannerError,
+  type AggregatePlannerInput,
+  type AggregatePlannerOutput,
+  type AggregatePlannerSuccess,
+  type CallerPolicy,
+  planAggregate,
+} from '../aggregate/planner';
+export { projectSchemaToSpace } from '../aggregate/project-schema-to-space';
+export type {
+  ContractSpaceAggregate,
+  ContractSpaceMember,
+  HydratedMigrationGraph,
+} from '../aggregate/types';
+export {
+  type AggregateVerifierError,
+  type AggregateVerifierInput,
+  type AggregateVerifierOutput,
+  type AggregateVerifierSuccess,
+  type MarkerCheckResult,
+  type MarkerCheckSection,
+  type OrphanElement,
+  type SchemaCheckSection,
+  verifyAggregate,
+} from '../aggregate/verifier';

package/src/exports/errors.ts

@@ -1,4 +1,5 @@
 export {
+  errorDescriptorHeadHashMismatch,
   errorInvalidJson,
   errorNoInvariantPath,
   errorUnknownInvariant,

package/src/exports/io.ts

@@ -1,6 +1,7 @@
 export {
   copyFilesWithRename,
   formatMigrationDirName,
+  materialiseExtensionMigrationPackageIfMissing,
   materialiseMigrationPackage,
   readMigrationPackage,
   readMigrationsDir,

package/src/exports/spaces.ts

@@ -1,23 +1,36 @@
 export {
-  concatenateSpaceApplyInputs,
-  type SpaceApplyInput,
-} from '../concatenate-space-apply-inputs';
+  assertDescriptorSelfConsistency,
+  type DescriptorSelfConsistencyInputs,
+} from '../assert-descriptor-self-consistency';
+export {
+  type ComputeExtensionSpaceApplyPathInputs,
+  computeExtensionSpaceApplyPath,
+  type ExtensionSpaceApplyPathOutcome,
+} from '../compute-extension-space-apply-path';
+export type { SpaceApplyInput } from '../concatenate-space-apply-inputs';
 export {
   type DetectSpaceContractDriftInputs,
   detectSpaceContractDrift,
   type SpaceContractDriftResult,
 } from '../detect-space-contract-drift';
 export {
-  emitPinnedSpaceArtefacts,
-  type PinnedSpaceArtefactInputs,
-  type PinnedSpaceHeadRef,
-} from '../emit-pinned-space-artefacts';
+  type ContractSpaceArtefactInputs,
+  emitContractSpaceArtefacts,
+} from '../emit-contract-space-artefacts';
+export {
+  type DiskContractSpaceState,
+  gatherDiskContractSpaceState,
+} from '../gather-disk-contract-space-state';
 export {
   planAllSpaces,
   type SpacePlanInput,
   type SpacePlanOutput,
 } from '../plan-all-spaces';
-export { readPinnedContractHash } from '../read-pinned-contract-hash';
+export { readContractSpaceContract } from '../read-contract-space-contract';
+export {
+  type ContractSpaceHeadRef,
+  readContractSpaceHeadRef,
+} from '../read-contract-space-head-ref';
 export {
   APP_SPACE_ID,
   assertValidSpaceId,
@@ -26,9 +39,9 @@ export {
   type ValidSpaceId,
 } from '../space-layout';
 export {
-  listPinnedSpaceDirectories,
+  type ContractSpaceHeadRecord,
+  listContractSpaceDirectories,
   type SpaceMarkerRecord,
-  type SpacePinnedHashRecord,
   type SpaceVerifierViolation,
   type VerifyContractSpacesInputs,
   type VerifyContractSpacesResult,

package/src/gather-disk-contract-space-state.ts

@@ -0,0 +1,62 @@
+import { readContractSpaceHeadRef } from './read-contract-space-head-ref';
+import { APP_SPACE_ID } from './space-layout';
+import {
+  type ContractSpaceHeadRecord,
+  listContractSpaceDirectories,
+} from './verify-contract-spaces';
+
+/**
+ * Disk-side inputs to {@link import('./verify-contract-spaces').verifyContractSpaces}
+ * — gathered without touching the live database. The caller composes
+ * this with the marker rows it reads from the runtime to invoke the
+ * verifier.
+ */
+export interface DiskContractSpaceState {
+  /** Contract-space directory names observed under `<projectMigrationsDir>/`. */
+  readonly spaceDirsOnDisk: readonly string[];
+  /** Head-ref `(hash, invariants)` per extension space. */
+  readonly headRefsBySpace: ReadonlyMap<string, ContractSpaceHeadRecord>;
+}
+
+/**
+ * Read the on-disk state the per-space verifier needs:
+ *
+ * - The list of contract-space directories under
+ *   `<projectMigrationsDir>/` (via
+ *   {@link import('./verify-contract-spaces').listContractSpaceDirectories}).
+ * - The on-disk head ref `(hash, invariants)` for each declared extension space
+ *   (via {@link readContractSpaceHeadRef}; missing on-disk artefacts are simply
+ *   omitted — the verifier reports them as `declaredButUnmigrated`).
+ *
+ * Synchronous in spirit but async due to filesystem reads. Reads only
+ * the user's repo. **Does not import any extension descriptor module.**
+ *
+ * Composition convention: pure target-agnostic primitive in
+ * `1-framework`; the SQL family (and any future target family) wires
+ * it into its `dbInit` / `verify` flows alongside its own marker-row
+ * read before invoking `verifyContractSpaces`.
+ */
+export async function gatherDiskContractSpaceState(args: {
+  readonly projectMigrationsDir: string;
+  /**
+   * Set of space ids the project declares: `'app'` plus each entry in
+   * `extensionPacks` whose descriptor exposes a `contractSpace`. The
+   * helper reads on-disk head data only for the extension members.
+   */
+  readonly loadedSpaceIds: ReadonlySet<string>;
+}): Promise<DiskContractSpaceState> {
+  const { projectMigrationsDir, loadedSpaceIds } = args;
+
+  const spaceDirsOnDisk = await listContractSpaceDirectories(projectMigrationsDir);
+
+  const headRefsBySpace = new Map<string, ContractSpaceHeadRecord>();
+  for (const spaceId of loadedSpaceIds) {
+    if (spaceId === APP_SPACE_ID) continue;
+    const head = await readContractSpaceHeadRef(projectMigrationsDir, spaceId);
+    if (head !== null) {
+      headRefsBySpace.set(spaceId, head);
+    }
+  }
+
+  return { spaceDirsOnDisk, headRefsBySpace };
+}

package/src/invariants.ts

@@ -16,8 +16,19 @@ export function validateInvariantId(invariantId: string): boolean {
 /**
  * Walk a migration's operations and produce its `providedInvariants`
  * aggregate: the sorted, deduplicated list of `invariantId`s declared
- * by data-transform ops. Ops without `operationClass === 'data'` are
- * skipped; data ops without an `invariantId` are skipped.
+ * by ops in the migration. Ops without an `invariantId` are skipped.
+ *
+ * Both `data`-class ops (data-transforms, e.g. backfills) and
+ * `additive`-class opaque DDL (e.g. cipherstash's vendored EQL bundle
+ * via `installEqlBundleOp`) may declare invariantIds: the
+ * `operationClass` axis classifies *policy gating* (which kinds of ops
+ * a `db init` / `db update` policy permits), while `invariantId`
+ * classifies *marker bookkeeping* (which named bundles of work a
+ * future regeneration knows to skip). The two concerns are
+ * intentionally orthogonal — an extension can ship additive
+ * non-IR-derivable DDL (the only way the planner can know the bundle
+ * is already applied is via the invariantId on the marker) without
+ * needing to mis-classify it as `data`-class.
  *
  * Throws `MIGRATION.INVALID_INVARIANT_ID` on a malformed id and
  * `MIGRATION.DUPLICATE_INVARIANT_IN_EDGE` on duplicates.
@@ -39,7 +50,7 @@ export function deriveProvidedInvariants(ops: MigrationOps): readonly string[] {
 }
 
 function readInvariantId(op: MigrationPlanOperation): string | undefined {
-  if (op.operationClass !== 'data') return undefined;
+  if (!Object.hasOwn(op, 'invariantId')) return undefined;
   const candidate = (op as { invariantId?: unknown }).invariantId;
   return typeof candidate === 'string' ? candidate : undefined;
 }

package/src/io.ts

@@ -124,6 +124,48 @@ export async function materialiseMigrationPackage(
   });
 }
 
+/**
+ * Idempotent variant of {@link materialiseMigrationPackage}: writes the
+ * package only if `<targetDir>/<pkg.dirName>/` does not already exist on
+ * disk as a directory; returns `{ written: false }` when the package
+ * directory is present (no rewrite, no comparison — by-existence skip).
+ *
+ * Concretely:
+ *   - existing directory → skip silently, return `{ written: false }`.
+ *   - missing path → write three files via {@link materialiseMigrationPackage},
+ *     return `{ written: true }`.
+ *   - path exists but is not a directory (file/symlink) → treated as
+ *     missing; {@link materialiseMigrationPackage} will attempt creation
+ *     and fail with an appropriate OS error.
+ *   - any other I/O error from `stat` → propagated unchanged.
+ *
+ * Used by the CLI's `runContractSpaceExtensionMigrationsPass` to
+ * materialise extension migration packages into a project's
+ * `migrations/<spaceId>/` directory, and by extension-package tests
+ * that mirror the same idempotent-rematerialise property locally
+ * without taking a CLI dependency.
+ */
+export async function materialiseExtensionMigrationPackageIfMissing(
+  targetDir: string,
+  pkg: MigrationPackage,
+): Promise<{ readonly written: boolean }> {
+  const pkgDir = join(targetDir, pkg.dirName);
+  if (await directoryExists(pkgDir)) {
+    return { written: false };
+  }
+  await materialiseMigrationPackage(targetDir, pkg);
+  return { written: true };
+}
+
+async function directoryExists(p: string): Promise<boolean> {
+  try {
+    return (await stat(p)).isDirectory();
+  } catch (error) {
+    if (hasErrnoCode(error, 'ENOENT')) return false;
+    throw error;
+  }
+}
+
 /**
  * Copy a list of files into `destDir`, optionally renaming each one.
  *

package/src/plan-all-spaces.ts

@@ -7,13 +7,11 @@ import { errorDuplicateSpaceId } from './errors';
  *
  * - `priorContract` is `null` for a space that has never been emitted
  *   (no `migrations/<space-id>/contract.json` on disk yet); otherwise it
- *   is the canonical contract value pinned for that space.
+ *   is the canonical contract value emitted for that space.
  * - `newContract` is the canonical contract value the planner is about
  *   to emit for that space — for app-space, the just-emitted root
  *   `contract.json`; for an extension space, the descriptor's
  *   `contractSpace.contractJson`.
- *
- * @see specs/framework-mechanism.spec.md § 3.
  */
 export interface SpacePlanInput<TContract> {
   readonly spaceId: string;
@@ -32,7 +30,7 @@ export interface SpacePlanOutput<TPackage> {
  *
  * Behaviour:
  *
- * - The output is sorted alphabetically by `spaceId` (AM3). Two callers
+ * - The output is sorted alphabetically by `spaceId`. Two callers
  *   passing the same set of inputs in different orders observe
  *   byte-identical outputs.
  * - The per-space planner (`planSpace`) is called exactly once per
@@ -49,11 +47,9 @@ export interface SpacePlanOutput<TPackage> {
  *
  * Synchronous: the underlying per-space planner (target's
  * `MigrationPlanner.plan(...)`) is synchronous; callers that need to
- * resolve async I/O (e.g. reading pinned `contract.json` from disk)
+ * resolve async I/O (e.g. reading on-disk `contract.json` from disk)
  * resolve it before calling `planAllSpaces` and pass the materialised
  * inputs through.
- *
- * @see specs/framework-mechanism.spec.md § 3 — Per-space planner (T1.3).
  */
 export function planAllSpaces<TContract, TPackage>(
   inputs: readonly SpacePlanInput<TContract>[],

package/src/read-contract-space-contract.ts

@@ -0,0 +1,44 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'pathe';
+import { errorInvalidJson, errorMissingFile } from './errors';
+import { assertValidSpaceId } from './space-layout';
+
+function hasErrnoCode(error: unknown, code: string): boolean {
+  return error instanceof Error && (error as { code?: string }).code === code;
+}
+
+/**
+ * Read the on-disk contract value for a contract space
+ * (`<projectMigrationsDir>/<spaceId>/contract.json`). Returns the parsed
+ * JSON value as `unknown` — callers that need a typed contract validate
+ * via their family's `validateContract` to surface schema issues.
+ *
+ * Companion to {@link import('./read-contract-space-head-ref').readContractSpaceHeadRef}
+ * — same ENOENT-throws / corrupt-file-error semantics. Returns the
+ * canonical-JSON value the framework wrote during emit, so re-running
+ * this helper across machines / runs yields a byte-identical value.
+ */
+export async function readContractSpaceContract(
+  projectMigrationsDir: string,
+  spaceId: string,
+): Promise<unknown> {
+  assertValidSpaceId(spaceId);
+
+  const filePath = join(projectMigrationsDir, spaceId, 'contract.json');
+
+  let raw: string;
+  try {
+    raw = await readFile(filePath, 'utf-8');
+  } catch (error) {
+    if (hasErrnoCode(error, 'ENOENT')) {
+      throw errorMissingFile('contract.json', join(projectMigrationsDir, spaceId));
+    }
+    throw error;
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw errorInvalidJson(filePath, e instanceof Error ? e.message : String(e));
+  }
+}

package/src/read-contract-space-head-ref.ts

@@ -0,0 +1,63 @@
+import { readFile } from 'node:fs/promises';
+import type { ContractSpaceHeadRef } from '@prisma-next/framework-components/control';
+import { join } from 'pathe';
+import { errorInvalidJson, errorInvalidRefFile } from './errors';
+import { assertValidSpaceId } from './space-layout';
+
+export type { ContractSpaceHeadRef };
+
+function hasErrnoCode(error: unknown, code: string): boolean {
+  return error instanceof Error && (error as { code?: string }).code === code;
+}
+
+/**
+ * Read the head ref (`hash` + `invariants`) for a contract space from
+ * `<projectMigrationsDir>/<spaceId>/refs/head.json`.
+ *
+ * Returns `null` when the file does not exist (first emit). Surfaces
+ * `MIGRATION.INVALID_JSON` / `MIGRATION.INVALID_REF_FILE` on a corrupt
+ * `refs/head.json` so callers can distinguish "no head ref on disk"
+ * (returns `null`) from "head ref present but unreadable" (throws).
+ *
+ * Validates the space id against `[a-z][a-z0-9_-]{0,63}` for the same
+ * filesystem-safety reasons as the rest of the per-space helpers. The
+ * helper is uniform across the app and extension spaces.
+ */
+export async function readContractSpaceHeadRef(
+  projectMigrationsDir: string,
+  spaceId: string,
+): Promise<ContractSpaceHeadRef | null> {
+  assertValidSpaceId(spaceId);
+
+  const filePath = join(projectMigrationsDir, spaceId, 'refs', 'head.json');
+
+  let raw: string;
+  try {
+    raw = await readFile(filePath, 'utf-8');
+  } catch (error) {
+    if (hasErrnoCode(error, 'ENOENT')) {
+      return null;
+    }
+    throw error;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw errorInvalidJson(filePath, e instanceof Error ? e.message : String(e));
+  }
+
+  if (typeof parsed !== 'object' || parsed === null) {
+    throw errorInvalidRefFile(filePath, 'expected an object');
+  }
+  const obj = parsed as { hash?: unknown; invariants?: unknown };
+  if (typeof obj.hash !== 'string') {
+    throw errorInvalidRefFile(filePath, 'expected an object with a string `hash` field');
+  }
+  if (!Array.isArray(obj.invariants) || obj.invariants.some((value) => typeof value !== 'string')) {
+    throw errorInvalidRefFile(filePath, 'expected an object with an `invariants` array of strings');
+  }
+
+  return { hash: obj.hash, invariants: obj.invariants as readonly string[] };
+}

package/src/space-layout.ts

@@ -17,8 +17,6 @@ export type ValidSpaceId = string & { readonly __brand: 'ValidSpaceId' };
  * Pattern a contract-space identifier must match. The constraint is
  * filesystem-friendly: lowercase letters / digits / hyphen / underscore,
  * starts with a letter, max 64 characters.
- *
- * @see specs/framework-mechanism.spec.md § 3.
  */
 const SPACE_ID_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
 
@@ -35,21 +33,16 @@ export function assertValidSpaceId(spaceId: string): asserts spaceId is ValidSpa
 /**
  * Resolve the migrations subdirectory for a given contract space.
  *
- * - **App space** (`spaceId === APP_SPACE_ID`) keeps today's layout: the
- *   project's `migrations/` directory is the migrations directory, no
- *   subdirectory.
- * - **Extension space** lands under `<projectMigrationsDir>/<spaceId>/`.
- *   The space id is validated against {@link SPACE_ID_PATTERN} because
- *   it becomes a filesystem directory name verbatim.
+ * Every contract space — including the app space (default `'app'`) —
+ * lands under `<projectMigrationsDir>/<spaceId>/`. The space id is
+ * validated against {@link SPACE_ID_PATTERN} because it becomes a
+ * filesystem directory name verbatim.
  *
  * `projectMigrationsDir` is the project's top-level `migrations/`
  * directory; the helper does not assume anything about its absolute /
  * relative shape and is symmetric with `pathe.join`.
  */
 export function spaceMigrationDirectory(projectMigrationsDir: string, spaceId: string): string {
-  if (spaceId === APP_SPACE_ID) {
-    return projectMigrationsDir;
-  }
   assertValidSpaceId(spaceId);
   return join(projectMigrationsDir, spaceId);
 }