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

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

@@ -10,8 +10,8 @@ import { APP_SPACE_ID } from './space-layout';
  * and the helper preserves it through the concatenation.
  *
  * - `migrationDirectory` is the on-disk migration directory for the
- *   space — `<projectRoot>/migrations` for `'app'` and
- *   `<projectRoot>/migrations/<space-id>` for an extension space.
+ *   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.

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

@@ -8,43 +8,41 @@
  * family speaks its own contract type, and both reduce to a hash string
  * before drift detection runs.
  *
- * `pinnedHash` is `null` when no pinned `contract.json` exists yet for
+ * `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 pinned files.
- *
- * @see specs/framework-mechanism.spec.md § 3 — Drift detection (T1.9).
+ * drift to surface; the migrate emit will create the on-disk artefacts.
  */
 export interface DetectSpaceContractDriftInputs {
   readonly descriptorHash: string;
-  readonly pinnedHash: string | null;
+  readonly priorHeadHash: string | null;
 }
 
 /**
  * Result discriminant for {@link detectSpaceContractDrift}.
  *
- * - `noDrift`: descriptor hash and pinned hash agree byte-for-byte.
+ * - `noDrift`: descriptor hash and on-disk head hash agree byte-for-byte.
  *   The migrate emit can proceed with no warning.
- * - `firstEmit`: no pinned `contract.json` on disk yet. The extension
+ * - `firstEmit`: no on-disk `contract.json` on disk yet. The extension
  *   was just added to `extensionPacks`; this run will create the
- *   pinned files. No warning either — the user's intent is to install
- *   the extension, not to "drift" from a state they haven't pinned.
- * - `drift`: descriptor hash differs from pinned hash. The caller
+ *   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 → pinned). The migrate emit proceeds
+ *   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 `pinnedHash` are threaded through
+ * `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 pinned file.
+ * re-reading the descriptor or the on-disk artefact.
  */
 export type SpaceContractDriftResult = {
   readonly kind: 'noDrift' | 'firstEmit' | 'drift';
   readonly spaceId: string;
   readonly descriptorHash: string;
-  readonly pinnedHash: string | null;
+  readonly priorHeadHash: string | null;
 };
 
 /**
@@ -56,40 +54,38 @@ export type SpaceContractDriftResult = {
  * already canonical hashes produced by the same pipeline, so any
  * difference is meaningful drift.
  *
- * Synchronous, pure, no I/O. The caller (SQL family in M2 R1) reads
- * the pinned `contract.json` and computes its hash, then invokes this
- * helper alongside the descriptor's `headRef.hash`. Composes naturally
- * with {@link import('./read-pinned-contract-hash').readPinnedContractHash}
+ * 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.
  *
- * @see specs/framework-mechanism.spec.md § 3 — Drift detection (T1.9).
- * @see specs/framework-mechanism.spec.md AM7 — drift warning surfaces
- *   the extension name and the diff direction.
+ * The drift warning surfaces the extension name and the diff direction.
  */
 export function detectSpaceContractDrift(
   spaceId: string,
   inputs: DetectSpaceContractDriftInputs,
 ): SpaceContractDriftResult {
-  if (inputs.pinnedHash === null) {
+  if (inputs.priorHeadHash === null) {
     return {
       kind: 'firstEmit',
       spaceId,
       descriptorHash: inputs.descriptorHash,
-      pinnedHash: null,
+      priorHeadHash: null,
     };
   }
-  if (inputs.descriptorHash === inputs.pinnedHash) {
+  if (inputs.descriptorHash === inputs.priorHeadHash) {
     return {
       kind: 'noDrift',
       spaceId,
       descriptorHash: inputs.descriptorHash,
-      pinnedHash: inputs.pinnedHash,
+      priorHeadHash: inputs.priorHeadHash,
     };
   }
   return {
     kind: 'drift',
     spaceId,
     descriptorHash: inputs.descriptorHash,
-    pinnedHash: inputs.pinnedHash,
+    priorHeadHash: inputs.priorHeadHash,
   };
 }

package/src/{emit-pinned-space-artefacts.ts → emit-contract-space-artefacts.ts}

@@ -1,21 +1,11 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'pathe';
 import { canonicalizeJson } from './canonicalize-json';
-import { errorPinnedArtefactsAppSpace } from './errors';
-import { APP_SPACE_ID, assertValidSpaceId } from './space-layout';
+import type { ContractSpaceHeadRef } from './read-contract-space-head-ref';
+import { assertValidSpaceId } from './space-layout';
 
 /**
- * Pinned head reference for a contract space — `(hash, invariants)`.
- * Mirrors {@link import('./refs').RefEntry} but is redeclared locally so
- * callers can construct the input without depending on the refs module.
- */
-export interface PinnedSpaceHeadRef {
-  readonly hash: string;
-  readonly invariants: readonly string[];
-}
-
-/**
- * Inputs for {@link emitPinnedSpaceArtefacts}.
+ * Inputs for {@link emitContractSpaceArtefacts}.
  *
  * - `contract` is the canonical contract value the framework just emitted
  *   for the space; it is serialised through {@link canonicalizeJson}, so
@@ -29,19 +19,19 @@ export interface PinnedSpaceHeadRef {
  *   needs), so this helper accepts the text verbatim and writes it out
  *   without further transformation.
  *
- * - `headRef` is the pinned head reference for the space.
+ * - `headRef` is the head reference for the space.
  *   `invariants` are sorted alphabetically before serialisation so two
  *   callers passing the same set in different orders produce
  *   byte-identical `refs/head.json`.
  */
-export interface PinnedSpaceArtefactInputs {
+export interface ContractSpaceArtefactInputs {
   readonly contract: unknown;
   readonly contractDts: string;
-  readonly headRef: PinnedSpaceHeadRef;
+  readonly headRef: ContractSpaceHeadRef;
 }
 
 /**
- * Emit the pinned per-space artefacts (`contract.json`, `contract.d.ts`,
+ * Emit the per-space artefacts (`contract.json`, `contract.d.ts`,
  * `refs/head.json`) under `<projectMigrationsDir>/<spaceId>/`.
  *
  * Always-overwrite: the framework owns these files; running `migrate`
@@ -49,29 +39,20 @@ export interface PinnedSpaceArtefactInputs {
  * helper does not check pre-existing contents — re-emit always wins.
  *
  * Path layout matches the convention in
- * [`spaceMigrationDirectory`](./space-layout.ts), with two restrictions
- * specific to pinned artefacts:
- *
- * - Rejects the app space (`spaceId === APP_SPACE_ID`): the app space's
- *   canonical `contract.json` lives at the project root, not under
- *   `migrations/`. Callers that want to emit it use the app-space
- *   contract emit pipeline.
- * - Validates `spaceId` against `[a-z][a-z0-9_-]{0,63}` via
- *   {@link assertValidSpaceId} for the same filesystem-safety reasons.
+ * [`spaceMigrationDirectory`](./space-layout.ts). The space id is
+ * validated against `[a-z][a-z0-9_-]{0,63}` via
+ * {@link assertValidSpaceId} for filesystem-safety reasons; the helper
+ * accepts every space uniformly (including the app space, default
+ * `'app'`).
  *
  * The migrations directory and space subdirectory are created if they
  * do not yet exist (`mkdir { recursive: true }`).
- *
- * @see specs/framework-mechanism.spec.md § 3 — Pinned artefact emission (T1.8).
  */
-export async function emitPinnedSpaceArtefacts(
+export async function emitContractSpaceArtefacts(
   projectMigrationsDir: string,
   spaceId: string,
-  inputs: PinnedSpaceArtefactInputs,
+  inputs: ContractSpaceArtefactInputs,
 ): Promise<void> {
-  if (spaceId === APP_SPACE_ID) {
-    throw errorPinnedArtefactsAppSpace();
-  }
   assertValidSpaceId(spaceId);
 
   const dir = join(projectMigrationsDir, spaceId);