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

package/src/aggregate/verifier.ts

@@ -0,0 +1,230 @@
+import type { Result } from '@prisma-next/utils/result';
+import { notOk, ok } from '@prisma-next/utils/result';
+import type { ContractMarkerRecordLike } from './marker-types';
+import { projectSchemaToSpace } from './project-schema-to-space';
+import type { ContractSpaceAggregate, ContractSpaceMember } from './types';
+
+/**
+ * Caller policy for the aggregate verifier. Today's only knob is
+ * `mode`: `strict` treats orphan elements (live tables not claimed by
+ * any aggregate member) as errors; `lenient` treats them as
+ * informational. Maps directly to `db verify --strict`.
+ */
+export interface AggregateVerifierInput<TSchemaResult> {
+  readonly aggregate: ContractSpaceAggregate;
+  readonly markersBySpaceId: ReadonlyMap<string, ContractMarkerRecordLike | null>;
+  readonly schemaIntrospection: unknown;
+  readonly mode: 'strict' | 'lenient';
+  /**
+   * Caller-supplied per-space schema verifier. The CLI wires this to
+   * the family's `verifySqlSchema` (SQL) / equivalent (other
+   * families). The aggregate verifier projects the schema to the
+   * member's slice via {@link projectSchemaToSpace} before invoking
+   * the callback, so single-contract semantics are preserved.
+   *
+   * Typed structurally with a generic `TSchemaResult` so the
+   * migration-tools layer doesn't depend on the SQL family's
+   * `VerifySqlSchemaResult`. CLI callers pass the family's type
+   * through unchanged.
+   */
+  readonly verifySchemaForMember: (
+    projectedSchema: unknown,
+    member: ContractSpaceMember,
+    mode: 'strict' | 'lenient',
+  ) => TSchemaResult;
+}
+
+/**
+ * Marker-check result per member. Mirrors the four cases the
+ * `verifyContractSpaces` primitive surfaces today, plus an `'absent'`
+ * case for greenfield spaces (no marker row written yet — `db init`
+ * not run).
+ */
+export type MarkerCheckResult =
+  | { readonly kind: 'ok' }
+  | { readonly kind: 'absent' }
+  | {
+      readonly kind: 'hashMismatch';
+      readonly markerHash: string;
+      readonly expected: string;
+    }
+  | { readonly kind: 'missingInvariants'; readonly missing: readonly string[] };
+
+export interface MarkerCheckSection {
+  readonly perSpace: ReadonlyMap<string, MarkerCheckResult>;
+  readonly orphanMarkers: readonly {
+    readonly spaceId: string;
+    readonly row: ContractMarkerRecordLike;
+  }[];
+}
+
+/**
+ * A live storage element (today: a top-level table) not claimed by any
+ * member of the aggregate. The aggregate verifier always reports these;
+ * the caller decides what to do — `db verify --strict` treats them as
+ * errors, the lenient default treats them as informational.
+ *
+ * Today only `kind: 'table'` exists. The discriminated shape leaves
+ * room for orphan columns / indexes / sequences in the future without
+ * breaking the type contract.
+ */
+export type OrphanElement = { readonly kind: 'table'; readonly name: string };
+
+export interface SchemaCheckSection<TSchemaResult> {
+  readonly perSpace: ReadonlyMap<string, TSchemaResult>;
+  /**
+   * Live elements present in the introspected schema that are not
+   * claimed by **any** aggregate member. Sorted alphabetically by name.
+   */
+  readonly orphanElements: readonly OrphanElement[];
+}
+
+export interface AggregateVerifierSuccess<TSchemaResult> {
+  readonly markerCheck: MarkerCheckSection;
+  readonly schemaCheck: SchemaCheckSection<TSchemaResult>;
+}
+
+export type AggregateVerifierError = {
+  readonly kind: 'introspectionFailure';
+  readonly detail: string;
+};
+
+export type AggregateVerifierOutput<TSchemaResult> = Result<
+  AggregateVerifierSuccess<TSchemaResult>,
+  AggregateVerifierError
+>;
+
+/**
+ * Verify a {@link ContractSpaceAggregate} against the live database
+ * state. Bundles two checks:
+ *
+ * - `markerCheck` per member: compare the live marker row against the
+ *   member's `headRef.hash` + `headRef.invariants`. Absence is a
+ *   distinct kind, not an error (callers — `db verify` strict vs
+ *   `db init` precondition — choose how to interpret it).
+ * - `schemaCheck` per member: project the live schema to the slice
+ *   the member claims via {@link projectSchemaToSpace}, then delegate
+ *   to the caller-supplied `verifySchemaForMember`. The pre-projection
+ *   means the family's single-contract verifier no longer sees other
+ *   members' tables as `extras`, so a multi-member deployment never
+ *   surfaces cross-member tables as orphaned schema elements.
+ *
+ * `markerCheck.orphanMarkers` lists every marker row whose `space` is
+ * not a member of the aggregate. `db verify` callers reject orphans;
+ * future tooling may not.
+ *
+ * Pure synchronous function; no I/O. The caller (CLI) gathers
+ * `markersBySpaceId` and `schemaIntrospection` ahead of the call.
+ */
+export function verifyAggregate<TSchemaResult>(
+  input: AggregateVerifierInput<TSchemaResult>,
+): AggregateVerifierOutput<TSchemaResult> {
+  try {
+    return runVerifyAggregate(input);
+  } catch (error) {
+    return notOk({
+      kind: 'introspectionFailure',
+      detail: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+function runVerifyAggregate<TSchemaResult>(
+  input: AggregateVerifierInput<TSchemaResult>,
+): AggregateVerifierOutput<TSchemaResult> {
+  const { aggregate, markersBySpaceId, schemaIntrospection, mode, verifySchemaForMember } = input;
+  const allMembers: ReadonlyArray<ContractSpaceMember> = [aggregate.app, ...aggregate.extensions];
+  const memberSpaceIds = new Set(allMembers.map((m) => m.spaceId));
+
+  // Marker check per member.
+  const markerPerSpace = new Map<string, MarkerCheckResult>();
+  for (const member of allMembers) {
+    const marker = markersBySpaceId.get(member.spaceId) ?? null;
+    if (marker === null) {
+      markerPerSpace.set(member.spaceId, { kind: 'absent' });
+      continue;
+    }
+    if (marker.storageHash !== member.headRef.hash) {
+      markerPerSpace.set(member.spaceId, {
+        kind: 'hashMismatch',
+        markerHash: marker.storageHash,
+        expected: member.headRef.hash,
+      });
+      continue;
+    }
+    const markerInvariants = new Set(marker.invariants);
+    const missing = member.headRef.invariants.filter((id) => !markerInvariants.has(id));
+    if (missing.length > 0) {
+      markerPerSpace.set(member.spaceId, {
+        kind: 'missingInvariants',
+        missing: [...missing].sort(),
+      });
+      continue;
+    }
+    markerPerSpace.set(member.spaceId, { kind: 'ok' });
+  }
+
+  // Orphan markers: entries in markersBySpaceId whose spaceId is not a
+  // member of the aggregate.
+  const orphanMarkers: { spaceId: string; row: ContractMarkerRecordLike }[] = [];
+  for (const [spaceId, row] of markersBySpaceId) {
+    if (row !== null && !memberSpaceIds.has(spaceId)) {
+      orphanMarkers.push({ spaceId, row });
+    }
+  }
+  orphanMarkers.sort((a, b) => a.spaceId.localeCompare(b.spaceId));
+
+  // Schema check per member (with per-space pre-projection).
+  const schemaPerSpace = new Map<string, TSchemaResult>();
+  for (const member of allMembers) {
+    const others = allMembers.filter((m) => m.spaceId !== member.spaceId);
+    const projected = projectSchemaToSpace(schemaIntrospection, member, others);
+    schemaPerSpace.set(member.spaceId, verifySchemaForMember(projected, member, mode));
+  }
+
+  return ok({
+    markerCheck: {
+      perSpace: markerPerSpace,
+      orphanMarkers,
+    },
+    schemaCheck: {
+      perSpace: schemaPerSpace,
+      orphanElements: detectOrphanElements(schemaIntrospection, allMembers),
+    },
+  });
+}
+
+/**
+ * Live tables not claimed by any aggregate member. Duck-typed against
+ * the introspected schema's `tables` map; schemas whose shape doesn't
+ * match return an empty list (consistent with
+ * {@link projectSchemaToSpace}'s fall-through).
+ */
+function detectOrphanElements(
+  schemaIntrospection: unknown,
+  members: ReadonlyArray<ContractSpaceMember>,
+): readonly OrphanElement[] {
+  if (typeof schemaIntrospection !== 'object' || schemaIntrospection === null) return [];
+  const liveTables = (schemaIntrospection as { readonly tables?: unknown }).tables;
+  if (typeof liveTables !== 'object' || liveTables === null) return [];
+
+  const claimedTables = new Set<string>();
+  for (const member of members) {
+    const storage = (member.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>)) {
+      claimedTables.add(tableName);
+    }
+  }
+
+  const orphans: OrphanElement[] = [];
+  for (const tableName of Object.keys(liveTables as Record<string, unknown>)) {
+    if (!claimedTables.has(tableName)) {
+      orphans.push({ kind: 'table', name: tableName });
+    }
+  }
+  orphans.sort((a, b) => a.name.localeCompare(b.name));
+  return orphans;
+}

package/src/assert-descriptor-self-consistency.ts

@@ -0,0 +1,70 @@
+import { computeStorageHash } from '@prisma-next/contract/hashing';
+import { errorDescriptorHeadHashMismatch } from './errors';
+
+/**
+ * Inputs the helper needs to recompute the descriptor's storage hash and
+ * compare it to the published `headRef.hash`. Kept structural so the SQL
+ * family (and any future target family) can compose the check without
+ * coupling to its own descriptor types.
+ */
+export interface DescriptorSelfConsistencyInputs {
+  readonly extensionId: string;
+  readonly target: string;
+  readonly targetFamily: string;
+  /**
+   * Family-specific storage object. Typed as `unknown` so callers can
+   * pass their own narrow storage shape (e.g. `SqlStorage`) without an
+   * inline cast — the helper canonicalises through `JSON.stringify`
+   * inside {@link computeStorageHash} and only requires a plain
+   * record-shaped value at runtime.
+   */
+  readonly storage: unknown;
+  readonly headRefHash: string;
+}
+
+/**
+ * Assert that an extension descriptor is self-consistent: the
+ * `headRef.hash` it publishes must match the canonical hash recomputed
+ * from its `contractSpace.contractJson`.
+ *
+ * Recomputes via {@link computeStorageHash} — the same canonical-JSON
+ * pipeline the descriptor's own emit pipeline produced the hash with —
+ * over `(target, targetFamily, storage)`. Mismatch indicates the
+ * extension author bumped `contractJson` without rerunning emit, leaving
+ * the descriptor's `headRef.hash` stale; the consumer-side helpers
+ * (drift detection, on-disk artefact emission, runner marker writes) all
+ * trust `headRef.hash` as the canonical identity, so a stale value would
+ * silently corrupt every downstream boundary.
+ *
+ * Synchronous, pure, no I/O. Throws
+ * `MIGRATION.DESCRIPTOR_HEAD_HASH_MISMATCH` on failure with both the
+ * recomputed and published hashes in `details` so callers can surface a
+ * clear remediation hint without re-deriving them.
+ */
+export function assertDescriptorSelfConsistency(inputs: DescriptorSelfConsistencyInputs): void {
+  // The published `storage.storageHash` is the *output* of the production
+  // emit pipeline's `computeStorageHash` call, computed over a storage
+  // object that did not yet carry `storageHash`. Recomputing against the
+  // published storage as-is would feed the result back into its own input
+  // and produce a different digest. Strip `storageHash` before
+  // recomputing so the helper sees the same canonical shape the
+  // descriptor's authoring pipeline saw.
+  // The helper requires only a plain record-shaped storage value at
+  // runtime; a single cast here keeps the public input type
+  // family-agnostic (`unknown`) while still letting us strip the
+  // descriptor-published `storageHash` before re-canonicalising.
+  const storageRecord = inputs.storage as Record<string, unknown>;
+  const { storageHash: _stripped, ...storageWithoutHash } = storageRecord;
+  const recomputed = computeStorageHash({
+    target: inputs.target,
+    targetFamily: inputs.targetFamily,
+    storage: storageWithoutHash,
+  });
+  if (recomputed !== inputs.headRefHash) {
+    throw errorDescriptorHeadHashMismatch({
+      extensionId: inputs.extensionId,
+      recomputedHash: recomputed,
+      headRefHash: inputs.headRefHash,
+    });
+  }
+}

package/src/compute-extension-space-apply-path.ts

@@ -0,0 +1,152 @@
+import { EMPTY_CONTRACT_HASH } from './constants';
+import { readMigrationsDir } from './io';
+import { findPathWithDecision, reconstructGraph } from './migration-graph';
+import type { MigrationOps } from './package';
+import {
+  type ContractSpaceHeadRef,
+  readContractSpaceHeadRef,
+} from './read-contract-space-head-ref';
+import { spaceMigrationDirectory } from './space-layout';
+
+/**
+ * Outcome of {@link computeExtensionSpaceApplyPath} — a discriminated union
+ * mirroring {@link import('./migration-graph').FindPathOutcome} so callers
+ * can map structural / invariant failures to their preferred CLI envelope
+ * without re-running pathfinding.
+ */
+export type ExtensionSpaceApplyPathOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly contractSpaceHeadRef: ContractSpaceHeadRef;
+      /**
+       * Sorted, deduplicated invariant ids covered by the walked path.
+       * Mirrors the on-disk `providedInvariants` summed across edges and
+       * canonicalised — what the runner stamps on the marker after apply.
+       */
+      readonly providedInvariants: readonly string[];
+      /**
+       * Path operations in apply order. Empty when the marker is already
+       * at the recorded head (no-op).
+       */
+      readonly pathOps: MigrationOps;
+      /**
+       * Migration directory names walked, in order. Mirrors `pathOps`'s
+       * structure but at the package granularity — useful for surfacing
+       * "applied N migration(s)" messages.
+       */
+      readonly walkedMigrationDirs: readonly string[];
+    }
+  | { readonly kind: 'unreachable'; readonly contractSpaceHeadRef: ContractSpaceHeadRef }
+  | {
+      readonly kind: 'unsatisfiable';
+      readonly contractSpaceHeadRef: ContractSpaceHeadRef;
+      readonly missing: readonly string[];
+      readonly structuralPath: readonly { readonly dirName: string; readonly to: string }[];
+    }
+  | { readonly kind: 'contractSpaceHeadRefMissing' };
+
+/**
+ * Inputs to {@link computeExtensionSpaceApplyPath}. The helper is
+ * deliberately framework-neutral and consumes only on-disk state:
+ *
+ * - `projectMigrationsDir` is the project's top-level `migrations/` dir.
+ * - `spaceId` selects the per-space subdirectory under it.
+ * - `currentMarkerHash` / `currentMarkerInvariants` come from the live
+ *   marker row keyed by `space = <spaceId>`. `null` hash = no marker yet
+ *   (the pathfinder treats this as the empty-contract sentinel per ADR
+ *   208).
+ */
+export interface ComputeExtensionSpaceApplyPathInputs {
+  readonly projectMigrationsDir: string;
+  readonly spaceId: string;
+  readonly currentMarkerHash: string | null;
+  readonly currentMarkerInvariants: readonly string[];
+}
+
+/**
+ * Compute the apply path for an extension contract space — the shortest
+ * sequence of on-disk migration packages that walks the live marker
+ * forward to the on-disk head ref hash, covering every required
+ * invariant.
+ *
+ * Reads only on-disk artefacts (`migrations/<spaceId>/refs/head.json`
+ * and the per-space migration packages). **Does not import any
+ * extension descriptor module** — `db init` / `db update` must remain
+ * runnable without the descriptor source on disk.
+ *
+ * Behaviour:
+ * - Returns `{ kind: 'ok', pathOps: [], … }` when the marker is already
+ *   at the recorded head and no required invariants are missing.
+ * - Returns `{ kind: 'unreachable' }` when the marker hash is not
+ *   structurally connected to the recorded head in the graph.
+ * - Returns `{ kind: 'unsatisfiable', missing, … }` when the marker is
+ *   reachable but no path covers the required invariants.
+ * - Returns `{ kind: 'contractSpaceHeadRefMissing' }` when the per-space
+ *   `refs/head.json` is absent — the precheck verifier should already
+ *   have rejected this case, but the helper is defensive so callers can
+ *   surface a coherent error rather than throw.
+ */
+export async function computeExtensionSpaceApplyPath(
+  inputs: ComputeExtensionSpaceApplyPathInputs,
+): Promise<ExtensionSpaceApplyPathOutcome> {
+  const { projectMigrationsDir, spaceId, currentMarkerHash, currentMarkerInvariants } = inputs;
+
+  const contractSpaceHeadRef = await readContractSpaceHeadRef(projectMigrationsDir, spaceId);
+  if (contractSpaceHeadRef === null) {
+    return { kind: 'contractSpaceHeadRefMissing' };
+  }
+
+  const spaceDir = spaceMigrationDirectory(projectMigrationsDir, spaceId);
+  const packages = await readMigrationsDir(spaceDir);
+  const graph = reconstructGraph(packages);
+
+  // Live-marker layer encodes "no prior state" as EMPTY_CONTRACT_HASH;
+  // mirror the `migration apply` flow so a fresh-marker initial walk
+  // hits the baseline migration whose `from` is EMPTY_CONTRACT_HASH.
+  const fromHash = currentMarkerHash ?? EMPTY_CONTRACT_HASH;
+  const required = new Set(
+    contractSpaceHeadRef.invariants.filter((id) => !currentMarkerInvariants.includes(id)),
+  );
+
+  const outcome = findPathWithDecision(graph, fromHash, contractSpaceHeadRef.hash, { required });
+
+  if (outcome.kind === 'unreachable') {
+    return { kind: 'unreachable', contractSpaceHeadRef };
+  }
+  if (outcome.kind === 'unsatisfiable') {
+    return {
+      kind: 'unsatisfiable',
+      contractSpaceHeadRef,
+      missing: outcome.missing,
+      structuralPath: outcome.structuralPath.map(({ dirName, to }) => ({ dirName, to })),
+    };
+  }
+
+  const packagesByHash = new Map(packages.map((pkg) => [pkg.metadata.migrationHash, pkg]));
+
+  const pathOps: MigrationOps[number][] = [];
+  const walkedMigrationDirs: string[] = [];
+  const providedInvariantsSet = new Set<string>();
+  for (const edge of outcome.decision.selectedPath) {
+    const pkg = packagesByHash.get(edge.migrationHash);
+    if (!pkg) {
+      // Path edges always come from the same `packages` array, so this
+      // is only reachable when the graph is internally inconsistent —
+      // surface it loudly rather than silently truncating the path.
+      throw new Error(
+        `Migration package missing for edge ${edge.migrationHash} in space "${spaceId}"`,
+      );
+    }
+    walkedMigrationDirs.push(pkg.dirName);
+    for (const op of pkg.ops) pathOps.push(op);
+    for (const invariant of pkg.metadata.providedInvariants) providedInvariantsSet.add(invariant);
+  }
+
+  return {
+    kind: 'ok',
+    contractSpaceHeadRef,
+    providedInvariants: [...providedInvariantsSet].sort(),
+    pathOps,
+    walkedMigrationDirs,
+  };
+}

package/src/concatenate-space-apply-inputs.ts

@@ -0,0 +1,90 @@
+import { errorDuplicateSpaceId } from './errors';
+import { APP_SPACE_ID } from './space-layout';
+
+/**
+ * Per-space input the runner consumes when applying a migration.
+ *
+ * The shape is target-agnostic: callers (today the SQL family; later
+ * any other family) bind `TOp` to their own per-target operation type
+ * (e.g. `SqlMigrationPlanOperation<TTargetDetails>` for the SQL family)
+ * and the helper preserves it through the concatenation.
+ *
+ * - `migrationDirectory` is the on-disk migration directory for the
+ *   space — `<projectRoot>/migrations/<space-id>` (uniform; the app
+ *   subspaces under its own `<APP_SPACE_ID>/` directory).
+ * - `currentMarkerHash` and `currentMarkerInvariants` are the values
+ *   read from the `prisma_contract.marker` row keyed by `space = <space-id>`
+ *   (T1.1). `null` hash = no marker row yet.
+ * - `path` is the per-space operation list resolved from
+ *   `findPathWithDecision(currentMarker, ref.hash, effectiveRequired)`
+ *   per ADR 208, materialised against the on-disk migration packages.
+ *
+ * @see specs/framework-mechanism.spec.md § 4 — Runner.
+ */
+export interface SpaceApplyInput<TOp> {
+  readonly spaceId: string;
+  readonly migrationDirectory: string;
+  readonly currentMarkerHash: string | null;
+  readonly currentMarkerInvariants: readonly string[];
+  readonly path: readonly TOp[];
+}
+
+/**
+ * Order a set of per-space apply inputs into the canonical cross-space
+ * sequence the runner applies under a single transaction.
+ *
+ * Cross-space ordering convention (sub-spec § 4):
+ *
+ * 1. **Extension spaces first**, alphabetically by `spaceId`.
+ * 2. **App space last** — only one `'app'` entry expected, at most.
+ *
+ * Rationale: extensions install their own structural objects (types,
+ * functions, helper tables) before the app's structural ops reference
+ * them. Putting app-space last lets app-space ops freely depend on any
+ * extension-space declaration in the same transaction.
+ *
+ * Determinism (NFR6): the output order is independent of the input
+ * order, so two callers with the same set of `extensionPacks` produce
+ * identical apply sequences.
+ *
+ * Atomicity: rejects duplicate `spaceId`s with
+ * `MIGRATION.DUPLICATE_SPACE_ID` before producing any output. This
+ * mirrors {@link import('./plan-all-spaces').planAllSpaces} so the
+ * planner-side and runner-side helpers reject malformed inputs the same
+ * way (callers don't need a separate dedup pass).
+ *
+ * Synchronous, pure, no I/O: callers resolve marker rows and `path`
+ * before invoking this helper. The actual DB application — driving the
+ * transaction, committing marker writes, recording the per-space marker
+ * rows — happens at the SQL-family consumption site (per the
+ * helper-location convention from R3).
+ */
+export function concatenateSpaceApplyInputs<TOp>(
+  inputs: readonly SpaceApplyInput<TOp>[],
+): readonly SpaceApplyInput<TOp>[] {
+  const seen = new Set<string>();
+  for (const input of inputs) {
+    if (seen.has(input.spaceId)) {
+      throw errorDuplicateSpaceId(input.spaceId);
+    }
+    seen.add(input.spaceId);
+  }
+
+  const extensions: SpaceApplyInput<TOp>[] = [];
+  let appSpace: SpaceApplyInput<TOp> | undefined;
+  for (const input of inputs) {
+    if (input.spaceId === APP_SPACE_ID) {
+      appSpace = input;
+    } else {
+      extensions.push(input);
+    }
+  }
+
+  extensions.sort((a, b) => {
+    if (a.spaceId < b.spaceId) return -1;
+    if (a.spaceId > b.spaceId) return 1;
+    return 0;
+  });
+
+  return appSpace ? [...extensions, appSpace] : extensions;
+}

package/src/detect-space-contract-drift.ts

@@ -0,0 +1,91 @@
+/**
+ * Inputs for {@link detectSpaceContractDrift}.
+ *
+ * Both hashes are produced by the caller (the SQL-family wiring at the
+ * consumption site) using the canonical contract hashing pipeline.
+ * Keeping the helper pure lets `migration-tools` stay framework-neutral
+ * — the SQL family already speaks `Contract<SqlStorage>`, the Mongo
+ * family speaks its own contract type, and both reduce to a hash string
+ * before drift detection runs.
+ *
+ * `priorHeadHash` is `null` when no `contract.json` exists yet on disk for
+ * the space (the descriptor declares an extension that has never been
+ * emitted into the user's repo). That's the "first emit" case — no
+ * drift to surface; the migrate emit will create the on-disk artefacts.
+ */
+export interface DetectSpaceContractDriftInputs {
+  readonly descriptorHash: string;
+  readonly priorHeadHash: string | null;
+}
+
+/**
+ * Result discriminant for {@link detectSpaceContractDrift}.
+ *
+ * - `noDrift`: descriptor hash and on-disk head hash agree byte-for-byte.
+ *   The migrate emit can proceed with no warning.
+ * - `firstEmit`: no on-disk `contract.json` on disk yet. The extension
+ *   was just added to `extensionPacks`; this run will create the
+ *   on-disk artefacts. No warning either — the user's intent is to install
+ *   the extension, not to "drift" from a state they haven't recorded.
+ * - `drift`: descriptor hash differs from on-disk head hash. The caller
+ *   surfaces a non-fatal warning naming the extension and the
+ *   diff direction (descriptor → on-disk head). The migrate emit proceeds
+ *   normally so the bump is materialised this run; the warning just
+ *   confirms the bump is being captured.
+ *
+ * `spaceId`, `descriptorHash`, and `priorHeadHash` are threaded through
+ * verbatim so the caller (logger / TerminalUI / strict-mode envelope)
+ * has everything it needs to format the warning message without
+ * re-reading the descriptor or the on-disk artefact.
+ */
+export type SpaceContractDriftResult = {
+  readonly kind: 'noDrift' | 'firstEmit' | 'drift';
+  readonly spaceId: string;
+  readonly descriptorHash: string;
+  readonly priorHeadHash: string | null;
+};
+
+/**
+ * Pure drift-detection primitive for a single contract space.
+ *
+ * Runs once per loaded extension space, just before computing the
+ * `priorContract` that feeds {@link import('./plan-all-spaces').planAllSpaces}.
+ * Hash equality is byte-for-byte (no normalisation) — both sides are
+ * already canonical hashes produced by the same pipeline, so any
+ * difference is meaningful drift.
+ *
+ * Synchronous, pure, no I/O. The caller (SQL family) reads the on-disk
+ * `contract.json` and computes its hash, then invokes this helper
+ * alongside the descriptor's `headRef.hash`. Composes naturally with
+ * {@link import('./read-contract-space-head-ref').readContractSpaceHeadRef}
+ * which provides the read-side primitive.
+ *
+ * The drift warning surfaces the extension name and the diff direction.
+ */
+export function detectSpaceContractDrift(
+  spaceId: string,
+  inputs: DetectSpaceContractDriftInputs,
+): SpaceContractDriftResult {
+  if (inputs.priorHeadHash === null) {
+    return {
+      kind: 'firstEmit',
+      spaceId,
+      descriptorHash: inputs.descriptorHash,
+      priorHeadHash: null,
+    };
+  }
+  if (inputs.descriptorHash === inputs.priorHeadHash) {
+    return {
+      kind: 'noDrift',
+      spaceId,
+      descriptorHash: inputs.descriptorHash,
+      priorHeadHash: inputs.priorHeadHash,
+    };
+  }
+  return {
+    kind: 'drift',
+    spaceId,
+    descriptorHash: inputs.descriptorHash,
+    priorHeadHash: inputs.priorHeadHash,
+  };
+}