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

package/dist/exports/spaces.d.mts

@@ -1,7 +1,148 @@
-import { APP_SPACE_ID } from "@prisma-next/framework-components/control";
+import { t as MigrationOps } from "../package-BjiZ7KDy.mjs";
+import { APP_SPACE_ID, ContractSpaceHeadRef } from "@prisma-next/framework-components/control";
 
+//#region src/assert-descriptor-self-consistency.d.ts
+/**
+ * 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.
+ */
+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.
+ */
+declare function assertDescriptorSelfConsistency(inputs: DescriptorSelfConsistencyInputs): void;
+//#endregion
+//#region src/read-contract-space-head-ref.d.ts
+/**
+ * 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.
+ */
+declare function readContractSpaceHeadRef(projectMigrationsDir: string, spaceId: string): Promise<ContractSpaceHeadRef | null>;
+//#endregion
+//#region src/compute-extension-space-apply-path.d.ts
+/**
+ * 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.
+ */
+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).
+ */
+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.
+ */
+declare function computeExtensionSpaceApplyPath(inputs: ComputeExtensionSpaceApplyPathInputs): Promise<ExtensionSpaceApplyPathOutcome>;
+//#endregion
 //#region src/concatenate-space-apply-inputs.d.ts
-
 /**
  * Per-space input the runner consumes when applying a migration.
  *
@@ -11,8 +152,8 @@ import { APP_SPACE_ID } from "@prisma-next/framework-components/control";
  * 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.
@@ -29,37 +170,6 @@ interface SpaceApplyInput<TOp> {
   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).
- */
-declare function concatenateSpaceApplyInputs<TOp>(inputs: readonly SpaceApplyInput<TOp>[]): readonly SpaceApplyInput<TOp>[];
 //#endregion
 //#region src/detect-space-contract-drift.d.ts
 /**
@@ -72,42 +182,40 @@ declare function concatenateSpaceApplyInputs<TOp>(inputs: readonly SpaceApplyInp
  * 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.
  */
 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.
  */
 type SpaceContractDriftResult = {
   readonly kind: 'noDrift' | 'firstEmit' | 'drift';
   readonly spaceId: string;
   readonly descriptorHash: string;
-  readonly pinnedHash: string | null;
+  readonly priorHeadHash: string | null;
 };
 /**
  * Pure drift-detection primitive for a single contract space.
@@ -118,30 +226,19 @@ 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.
  */
 declare function detectSpaceContractDrift(spaceId: string, inputs: DetectSpaceContractDriftInputs): SpaceContractDriftResult;
 //#endregion
-//#region src/emit-pinned-space-artefacts.d.ts
+//#region src/emit-contract-space-artefacts.d.ts
 /**
- * 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.
- */
-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
@@ -155,18 +252,18 @@ 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`.
  */
-interface PinnedSpaceArtefactInputs {
+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`
@@ -174,144 +271,20 @@ 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).
- */
-declare function emitPinnedSpaceArtefacts(projectMigrationsDir: string, spaceId: string, inputs: PinnedSpaceArtefactInputs): Promise<void>;
-//#endregion
-//#region src/plan-all-spaces.d.ts
-/**
- * Per-space input for {@link planAllSpaces}. One entry per loaded
- * contract space (the application's `'app'` plus each extension that
- * exposes a `contractSpace`).
- *
- * - `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.
- * - `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.
- */
-interface SpacePlanInput<TContract> {
-  readonly spaceId: string;
-  readonly priorContract: TContract | null;
-  readonly newContract: TContract;
-}
-interface SpacePlanOutput<TPackage> {
-  readonly spaceId: string;
-  readonly migrationPackages: readonly TPackage[];
-}
-/**
- * Iterate the per-space planner across a set of loaded contract spaces
- * and return a deterministic shape regardless of declaration order.
- *
- * Behaviour:
- *
- * - The output is sorted alphabetically by `spaceId` (AM3). 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
- *   input, in alphabetical-by-spaceId order. Its return value is
- *   attached to the corresponding output entry verbatim.
- * - Duplicate `spaceId`s in the input array throw
- *   `MIGRATION.DUPLICATE_SPACE_ID` before any `planSpace` call runs,
- *   keeping the planner pure when the input is malformed.
- *
- * The signature is generic over `TContract` and `TPackage` because the
- * shape is framework-neutral (SQL family today, Mongo family
- * eventually). Callers wire in whatever contract value and migration
- * package shape their family already speaks.
- *
- * 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 it before calling `planAllSpaces` and pass the materialised
- * inputs through.
- *
- * @see specs/framework-mechanism.spec.md § 3 — Per-space planner (T1.3).
- */
-declare function planAllSpaces<TContract, TPackage>(inputs: readonly SpacePlanInput<TContract>[], planSpace: (input: SpacePlanInput<TContract>) => readonly TPackage[]): readonly SpacePlanOutput<TPackage>[];
-//#endregion
-//#region src/read-pinned-contract-hash.d.ts
-/**
- * Read the pinned head hash for an extension space.
- *
- * Returns the `hash` field of `<projectMigrationsDir>/<spaceId>/refs/head.json`
- * — i.e. the canonical contract hash the framework wrote on the last
- * `migrate` for this space. Returns `null` when the file does not exist
- * (or the migrations directory is missing entirely), which is the
- * "first emit" signal {@link import('./detect-space-contract-drift').detectSpaceContractDrift}
- * uses to distinguish a brand-new extension from drift.
- *
- * Pure I/O (read + parse). The "comparison hash" is stored on disk by
- * {@link import('./emit-pinned-space-artefacts').emitPinnedSpaceArtefacts}
- * via the descriptor's `headRef.hash`, so reading it back here matches
- * the descriptor's hashing pipeline by construction — neither side
- * recomputes anything.
- *
- * Validation:
- *
- * - Rejects the app space — pinned head refs are an extension-space
- *   concept; the app space's contract-of-record lives at the project
- *   root, not under `migrations/`.
- * - Validates the space id against the same `[a-z][a-z0-9_-]{0,63}`
- *   pattern as the rest of the per-space helpers.
- * - Surfaces `MIGRATION.INVALID_JSON` / `MIGRATION.INVALID_REF_FILE`
- *   on a corrupt `refs/head.json` so callers can distinguish "no
- *   pinned file" (returns `null`) from "pinned file but unreadable"
- *   (throws).
- *
- * @see specs/framework-mechanism.spec.md § 3 — Drift detection (T1.9).
- */
-declare function readPinnedContractHash(projectMigrationsDir: string, spaceId: string): Promise<string | null>;
-//#endregion
-//#region src/space-layout.d.ts
-/**
- * Branded string carrying a compile-time guarantee that the value has
- * been validated by {@link assertValidSpaceId}. Downstream filesystem
- * helpers (e.g. {@link spaceMigrationDirectory}) accept this type to
- * make "validated" tracking visible at the type level rather than
- * relying purely on a runtime check.
  */
-type ValidSpaceId = string & {
-  readonly __brand: 'ValidSpaceId';
-};
-declare function isValidSpaceId(spaceId: string): spaceId is ValidSpaceId;
-declare function assertValidSpaceId(spaceId: string): asserts spaceId is ValidSpaceId;
-/**
- * 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.
- *
- * `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`.
- */
-declare function spaceMigrationDirectory(projectMigrationsDir: string, spaceId: string): string;
+declare function emitContractSpaceArtefacts(projectMigrationsDir: string, spaceId: string, inputs: ContractSpaceArtefactInputs): Promise<void>;
 //#endregion
 //#region src/verify-contract-spaces.d.ts
 /**
- * List the per-space pinned subdirectories under
+ * List the per-space subdirectories under
  * `<projectRoot>/migrations/`. Returns space-id directory names (sorted
  * alphabetically) — i.e. any non-dot-prefixed subdirectory whose root
  * does **not** contain a `migration.json` manifest. The manifest is the
@@ -325,24 +298,22 @@ declare function spaceMigrationDirectory(projectMigrationsDir: string, spaceId:
  * Reads only the user's repo. **No descriptor import.** The caller
  * (verifier) feeds the result into {@link verifyContractSpaces} alongside
  * the loaded-space set and the marker rows.
- *
- * @see specs/framework-mechanism.spec.md § 4 — Verifier (steps 5–6).
  */
-declare function listPinnedSpaceDirectories(projectMigrationsDir: string): Promise<readonly string[]>;
+declare function listContractSpaceDirectories(projectMigrationsDir: string): Promise<readonly string[]>;
 /**
- * Pinned head value (`(hash, invariants)`) for one contract space.
+ * On-disk head value (`(hash, invariants)`) for one contract space.
  * The verifier compares this against the marker row for the same space
  * to detect drift between the user-emitted artefacts and the live DB
  * marker.
  */
-interface SpacePinnedHashRecord {
+interface ContractSpaceHeadRecord {
   readonly hash: string;
   readonly invariants: readonly string[];
 }
 /**
  * Marker row read from `prisma_contract.marker` (one per `space`).
- * Caller resolves these via the family runtime's marker reader (T1.1)
- * before invoking {@link verifyContractSpaces}.
+ * Caller resolves these via the family runtime's marker reader before
+ * invoking {@link verifyContractSpaces}.
  */
 interface SpaceMarkerRecord {
   readonly hash: string;
@@ -358,19 +329,19 @@ interface VerifyContractSpacesInputs {
    */
   readonly loadedSpaces: ReadonlySet<string>;
   /**
-   * Pinned per-space subdirectories observed under
+   * Per-space subdirectories observed under
    * `<projectRoot>/migrations/`. Resolved via
-   * {@link listPinnedSpaceDirectories}.
+   * {@link listContractSpaceDirectories}.
    */
-  readonly pinnedDirsOnDisk: readonly string[];
+  readonly spaceDirsOnDisk: readonly string[];
   /**
-   * Pinned head ref per space, keyed by space id. Caller reads
+   * Head ref per space, keyed by space id. Caller reads
    * `<projectRoot>/migrations/<space-id>/contract.json` and
-   * `refs/head.json` (or, for app-space if its pinned shape ever moves
-   * under `migrations/`, the equivalent files) to construct this map.
-   * Spaces with no pinned dir on disk simply omit a map entry.
+   * `<projectRoot>/migrations/<space-id>/refs/head.json` to construct
+   * this map. Spaces with no contract-space dir on disk simply omit a
+   * map entry.
    */
-  readonly pinnedHashesBySpace: ReadonlyMap<string, SpacePinnedHashRecord>;
+  readonly headRefsBySpace: ReadonlyMap<string, ContractSpaceHeadRecord>;
   /**
    * Marker rows keyed by `space`. Caller reads them from the
    * `prisma_contract.marker` table.
@@ -386,19 +357,19 @@ type SpaceVerifierViolation = {
   readonly spaceId: string;
   readonly remediation: string;
 } | {
-  readonly kind: 'orphanPinnedDir';
+  readonly kind: 'orphanSpaceDir';
   readonly spaceId: string;
   readonly remediation: string;
 } | {
   readonly kind: 'hashMismatch';
   readonly spaceId: string;
-  readonly pinnedHash: string;
+  readonly priorHeadHash: string;
   readonly markerHash: string;
   readonly remediation: string;
 } | {
   readonly kind: 'invariantsMismatch';
   readonly spaceId: string;
-  readonly pinnedInvariants: readonly string[];
+  readonly onDiskInvariants: readonly string[];
   readonly markerInvariants: readonly string[];
   readonly remediation: string;
 };
@@ -410,38 +381,170 @@ type VerifyContractSpacesResult = {
 };
 /**
  * Pure structural verifier for the per-space mechanism. Aggregates the
- * three orphan / missing checks (FR6 cases a–c) plus per-space hash and
- * invariant comparison.
+ * three orphan / missing checks plus per-space hash and invariant
+ * comparison.
  *
- * Algorithm (sub-spec § 4):
+ * Algorithm:
  *
  * - For every extension space declared in `loadedSpaces` (`'app'`
- *   excluded — its pinned `contract.json` lives at the project root):
- *   - If no pinned dir on disk → `declaredButUnmigrated`.
+ *   excluded — the per-space verifier is scoped to extension members;
+ *   the app is verified through the aggregate path):
+ *   - If no contract-space dir on disk → `declaredButUnmigrated`.
  *   - Else if `markerRowsBySpace` lacks an entry → no violation here;
- *     the live-DB compare in step 8 (out of scope of this helper) is
- *     where the absence shows up.
- *   - Else compare marker hash / invariants vs. pinned hash /
+ *     the live-DB compare done outside this helper is where the
+ *     absence shows up.
+ *   - Else compare marker hash / invariants vs. on-disk head hash /
  *     invariants → `hashMismatch` / `invariantsMismatch` on drift.
- * - For every pinned dir on disk that is not in `loadedSpaces` →
- *   `orphanPinnedDir`.
+ * - For every contract-space dir on disk that is not in `loadedSpaces` →
+ *   `orphanSpaceDir`.
  * - For every marker row whose `space` is not in `loadedSpaces` →
  *   `orphanMarker`. The app-space marker is always loaded (`'app'` is
  *   in `loadedSpaces` by definition).
  *
- * Output is deterministic (NFR6): violations are sorted first by `kind`
- * (`declaredButUnmigrated` → `orphanMarker` → `orphanPinnedDir` →
+ * Output is deterministic: violations are sorted first by `kind`
+ * (`declaredButUnmigrated` → `orphanMarker` → `orphanSpaceDir` →
  * `hashMismatch` → `invariantsMismatch`) then by `spaceId`. Two callers
  * passing equivalent inputs see byte-identical violation lists.
  *
  * Synchronous, pure, no I/O. **Does not import the extension descriptor**
- * (the inputs are pre-resolved by the caller). This is the property
- * AC-15 / AC-26 ("verifier reads only the user repo, not
- * `node_modules`") locks in.
- *
- * @see specs/framework-mechanism.spec.md § 4 — Verifier (T1.5).
+ * (the inputs are pre-resolved by the caller); the verifier reads only
+ * the user repo, not `node_modules`.
  */
 declare function verifyContractSpaces(inputs: VerifyContractSpacesInputs): VerifyContractSpacesResult;
 //#endregion
-export { APP_SPACE_ID, type DetectSpaceContractDriftInputs, type PinnedSpaceArtefactInputs, type PinnedSpaceHeadRef, type SpaceApplyInput, type SpaceContractDriftResult, type SpaceMarkerRecord, type SpacePinnedHashRecord, type SpacePlanInput, type SpacePlanOutput, type SpaceVerifierViolation, type ValidSpaceId, type VerifyContractSpacesInputs, type VerifyContractSpacesResult, assertValidSpaceId, concatenateSpaceApplyInputs, detectSpaceContractDrift, emitPinnedSpaceArtefacts, isValidSpaceId, listPinnedSpaceDirectories, planAllSpaces, readPinnedContractHash, spaceMigrationDirectory, verifyContractSpaces };
+//#region src/gather-disk-contract-space-state.d.ts
+/**
+ * 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.
+ */
+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`.
+ */
+declare 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>;
+//#endregion
+//#region src/plan-all-spaces.d.ts
+/**
+ * Per-space input for {@link planAllSpaces}. One entry per loaded
+ * contract space (the application's `'app'` plus each extension that
+ * exposes a `contractSpace`).
+ *
+ * - `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 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`.
+ */
+interface SpacePlanInput<TContract> {
+  readonly spaceId: string;
+  readonly priorContract: TContract | null;
+  readonly newContract: TContract;
+}
+interface SpacePlanOutput<TPackage> {
+  readonly spaceId: string;
+  readonly migrationPackages: readonly TPackage[];
+}
+/**
+ * Iterate the per-space planner across a set of loaded contract spaces
+ * and return a deterministic shape regardless of declaration order.
+ *
+ * Behaviour:
+ *
+ * - 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
+ *   input, in alphabetical-by-spaceId order. Its return value is
+ *   attached to the corresponding output entry verbatim.
+ * - Duplicate `spaceId`s in the input array throw
+ *   `MIGRATION.DUPLICATE_SPACE_ID` before any `planSpace` call runs,
+ *   keeping the planner pure when the input is malformed.
+ *
+ * The signature is generic over `TContract` and `TPackage` because the
+ * shape is framework-neutral (SQL family today, Mongo family
+ * eventually). Callers wire in whatever contract value and migration
+ * package shape their family already speaks.
+ *
+ * Synchronous: the underlying per-space planner (target's
+ * `MigrationPlanner.plan(...)`) is synchronous; callers that need to
+ * resolve async I/O (e.g. reading on-disk `contract.json` from disk)
+ * resolve it before calling `planAllSpaces` and pass the materialised
+ * inputs through.
+ */
+declare function planAllSpaces<TContract, TPackage>(inputs: readonly SpacePlanInput<TContract>[], planSpace: (input: SpacePlanInput<TContract>) => readonly TPackage[]): readonly SpacePlanOutput<TPackage>[];
+//#endregion
+//#region src/read-contract-space-contract.d.ts
+/**
+ * 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.
+ */
+declare function readContractSpaceContract(projectMigrationsDir: string, spaceId: string): Promise<unknown>;
+//#endregion
+//#region src/space-layout.d.ts
+/**
+ * Branded string carrying a compile-time guarantee that the value has
+ * been validated by {@link assertValidSpaceId}. Downstream filesystem
+ * helpers (e.g. {@link spaceMigrationDirectory}) accept this type to
+ * make "validated" tracking visible at the type level rather than
+ * relying purely on a runtime check.
+ */
+type ValidSpaceId = string & {
+  readonly __brand: 'ValidSpaceId';
+};
+declare function isValidSpaceId(spaceId: string): spaceId is ValidSpaceId;
+declare function assertValidSpaceId(spaceId: string): asserts spaceId is ValidSpaceId;
+/**
+ * Resolve the migrations subdirectory for a given contract space.
+ *
+ * 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`.
+ */
+declare function spaceMigrationDirectory(projectMigrationsDir: string, spaceId: string): string;
+//#endregion
+export { APP_SPACE_ID, type ComputeExtensionSpaceApplyPathInputs, type ContractSpaceArtefactInputs, type ContractSpaceHeadRecord, type ContractSpaceHeadRef, type DescriptorSelfConsistencyInputs, type DetectSpaceContractDriftInputs, type DiskContractSpaceState, type ExtensionSpaceApplyPathOutcome, type SpaceApplyInput, type SpaceContractDriftResult, type SpaceMarkerRecord, type SpacePlanInput, type SpacePlanOutput, type SpaceVerifierViolation, type ValidSpaceId, type VerifyContractSpacesInputs, type VerifyContractSpacesResult, assertDescriptorSelfConsistency, assertValidSpaceId, computeExtensionSpaceApplyPath, detectSpaceContractDrift, emitContractSpaceArtefacts, gatherDiskContractSpaceState, isValidSpaceId, listContractSpaceDirectories, planAllSpaces, readContractSpaceContract, readContractSpaceHeadRef, spaceMigrationDirectory, verifyContractSpaces };
 //# sourceMappingURL=spaces.d.mts.map