@prisma-next/migration-tools 0.11.0 → 0.12.0

package/dist/exports/aggregate.d.mts

@@ -1,220 +1,344 @@
-import { n as OnDiskMigrationPackage } from "../package-DZj8YvD0.mjs";
-import { n as MigrationGraph } from "../graph-BrLXqoUc.mjs";
-import { t as PathDecision } from "../migration-graph-De0dUZoC.mjs";
+import { n as OnDiskMigrationPackage } from "../package-Ca-J_z_0.mjs";
+import { i as Refs, r as RefLoadProblem } from "../refs-C7wuYFqZ.mjs";
+import { t as ContractSpaceHeadRecord } from "../verify-contract-spaces-BdysZdQk.mjs";
+import { n as MigrationGraph } from "../graph-3dLMZp5l.mjs";
+import { t as PackageLoadProblem } from "../io-BH4G3F-i.mjs";
+import { t as PathDecision } from "../migration-graph-CWEM2SLR.mjs";
 import { Result } from "@prisma-next/utils/result";
 import { ControlFamilyInstance, MigrationOperationPolicy, MigrationPlan, MigrationPlanOperation, MigrationPlannerConflict, TargetMigrationsCapability } from "@prisma-next/framework-components/control";
 import { Contract } from "@prisma-next/contract/types";
 import { TargetBoundComponentDescriptor } from "@prisma-next/framework-components/components";
 
-//#region src/aggregate/types.d.ts
+//#region src/integrity-violation.d.ts
+/**
+ * Every structural problem the migration model can carry.
+ *
+ * Violations come in three groups:
+ *
+ * - **Recoverable**: the package or space is retained in the model;
+ *   the violation is surfaced for policy (report, refuse, or ignore
+ *   depending on the command).
+ * - **Config/contract-dependent**: produced only when the matching
+ *   `IntegrityQueryOptions` opt is set (declaredExtensions /
+ *   checkContracts). The model is built without them; they surface
+ *   when the caller explicitly asks for the broader integrity view.
+ * - **Unloadable**: the package is omitted from the model entirely
+ *   (its on-disk content cannot be parsed into an `OnDiskMigrationPackage`).
+ *
+ * `checkIntegrity()` on `ContractSpaceAggregate` returns the full set —
+ * all violations across all spaces — never bailing at the first hit.
+ */
+type IntegrityViolation = {
+  readonly kind: 'sameSourceAndTarget';
+  readonly spaceId: string;
+  readonly dirName: string;
+  readonly hash: string;
+} | {
+  readonly kind: 'hashMismatch';
+  readonly spaceId: string;
+  readonly dirName: string;
+  readonly stored: string;
+  readonly computed: string;
+} | {
+  readonly kind: 'providedInvariantsMismatch';
+  readonly spaceId: string;
+  readonly dirName: string;
+} | {
+  readonly kind: 'headRefMissing';
+  readonly spaceId: string;
+} | {
+  readonly kind: 'headRefNotInGraph';
+  readonly spaceId: string;
+  readonly hash: string;
+} | {
+  readonly kind: 'duplicateMigrationHash';
+  readonly spaceId: string;
+  readonly migrationHash: string;
+  readonly dirNames: readonly string[];
+} | {
+  readonly kind: 'refUnreadable';
+  readonly spaceId: string;
+  readonly refName: string;
+  readonly detail: string;
+} | {
+  readonly kind: 'orphanSpaceDir';
+  readonly spaceId: string;
+} | {
+  readonly kind: 'declaredButUnmigrated';
+  readonly spaceId: string;
+} | {
+  readonly kind: 'targetMismatch';
+  readonly spaceId: string;
+  readonly expected: string;
+  readonly actual: string;
+} | {
+  readonly kind: 'disjointness';
+  readonly element: string;
+  readonly claimedBy: readonly string[];
+} | {
+  readonly kind: 'contractUnreadable';
+  readonly spaceId: string;
+  readonly detail: string;
+} | {
+  readonly kind: 'packageUnloadable';
+  readonly spaceId: string;
+  readonly dirName: string;
+  readonly detail: string;
+};
+/**
+ * One declared extension entry, drawn from `Config.extensionPacks`.
+ *
+ * The integrity layer needs only:
+ *
+ * - `id` — the space id (also the directory name under `migrations/`),
+ *   used for the layout-drift checks (`orphanSpaceDir` /
+ *   `declaredButUnmigrated`).
+ * - `targetId` — the target the declaring extension was configured for.
+ *
+ * Typed structurally so the migration-tools layer stays framework-neutral.
+ */
+interface DeclaredExtensionEntry {
+  readonly id: string;
+  readonly targetId: string;
+}
 /**
- * Hydrated migration graph for a single contract space.
- *
- * `graph` is the structural shortest-path graph (forward / reverse chain,
- * deterministic tie-break order) reconstructed from a set of on-disk
- * migration packages. `packagesByMigrationHash` is the lookup table the
- * graph-walk strategy uses to resolve a path's edge sequence back to the
- * concrete `OnDiskMigrationPackage` (and therefore the operation list) for
- * apply.
- *
- * Eagerly hydrated by the loader. Once a `ContractSpaceAggregate` exists,
- * downstream consumers do **not** touch the filesystem to walk graphs or
- * resolve packages — the aggregate is the boundary.
+ * Options controlling which config/contract-dependent violation checks
+ * `checkIntegrity()` runs.
+ *
+ * Both opts default to disabled: a caller without the app contract or
+ * declared extensions still gets the structurally-derivable violations
+ * (hashMismatch, providedInvariantsMismatch, headRefMissing,
+ * headRefNotInGraph, refUnreadable, sameSourceAndTarget, packageUnloadable).
  */
-interface HydratedMigrationGraph {
-  readonly graph: MigrationGraph;
-  readonly packagesByMigrationHash: ReadonlyMap<string, OnDiskMigrationPackage>;
+interface IntegrityQueryOptions {
+  /**
+   * When provided, enables layout-drift checks: `orphanSpaceDir`
+   * (a directory exists on disk for an extension not in the list) and
+   * `declaredButUnmigrated` (an extension in the list has no on-disk dir).
+   */
+  readonly declaredExtensions?: readonly DeclaredExtensionEntry[];
+  /**
+   * When true, enables contract/disjointness/target checks:
+   * `contractUnreadable`, `targetMismatch`, `disjointness`.
+   */
+  readonly checkContracts?: boolean;
+}
+//#endregion
+//#region src/aggregate/types.d.ts
+interface ContractAtOptions {
+  readonly refName?: string;
 }
+type ContractAtResult = {
+  readonly provenance: 'snapshot';
+  readonly hash: string;
+  readonly contractJson: unknown;
+  readonly contractDts: string;
+  readonly contract: Contract;
+} | {
+  readonly provenance: 'graph-node';
+  readonly sourceDir: string;
+  readonly hash: string;
+  readonly contractJson: unknown;
+  readonly contractDts: string;
+  readonly contract: Contract;
+};
 /**
  * One contract space — app or extension — as a member of a
  * {@link ContractSpaceAggregate}. Every member has the same shape.
  *
+ * A member is a tolerant snapshot of one space's on-disk state, not a
+ * validated value: `packages` is the raw migration-package list as read
+ * from disk (a hash- or invariants-mismatched package is retained here;
+ * a genuinely unparseable one is omitted), and integrity is judged
+ * separately by {@link ContractSpaceAggregate.checkIntegrity}.
+ *
  * - `spaceId`: `'app'` for the application, otherwise the extension's
  *   id (validated against `[a-z][a-z0-9_-]{0,63}`).
- * - `contract`: the validated contract value for this member. For the
- *   app, the user's authored contract; for an extension, the on-disk
- *   `migrations/<spaceId>/contract.json`. Both have already passed the
- *   family's `deserializeContract` at the loader boundary.
- * - `headRef.hash`: the storage hash this member is targeting. For the
- *   app, equals `contract.storage.storageHash`. For extensions, the
- *   on-disk `refs/head.json.hash`.
- * - `headRef.invariants`: alphabetically sorted, deduplicated invariant
- *   ids declared on the head ref. Empty for the app member (the app's
- *   plan is synthesised from the contract IR, no invariants required).
- * - `migrations`: the hydrated migration graph for this space. Possibly
- *   empty (an extension whose on-disk head ref points at the
- *   empty-contract sentinel and ships no migrations yet, or the app
- *   when the user hasn't authored any).
+ * - `packages`: raw on-disk migration packages, as read; never
+ *   integrity-validated at load.
+ * - `refs`: the user-authored refs under `migrations/<spaceId>/refs/*.json`.
+ * - `headRef`: the system head ref read from
+ *   `migrations/<spaceId>/refs/head.json`, or `null` when absent
+ *   (represented as a `headRefMissing` violation, never fatal). The app
+ *   member's head ref is always synthesised from its live contract's
+ *   storage hash, so it is never `null`.
+ * - `graph()`: the migration graph this space's packages induce —
+ *   lazily reconstructed on first call and memoised. Pure structure: a
+ *   `from === to` self-edge is represented, not rejected.
+ * - `contract()`: the deserialized contract for this member — lazily
+ *   produced on first call and memoised. For the app it is the live
+ *   contract the caller supplied; for an extension it is the on-disk
+ *   `migrations/<spaceId>/contract.json` run through the family's
+ *   `deserializeContract`. Throws if the on-disk contract is missing or
+ *   undeserializable (surfaced as `contractUnreadable` by `checkIntegrity`
+ *   under `checkContracts`); callers gate before querying it.
+ * - `contractAt(hash, opts?)`: materializes the contract at an arbitrary
+ *   graph node — when `opts.refName` is set, prefer the ref's paired
+ *   snapshot; else find the package whose `metadata.to === hash` and read
+ *   its `end-contract.*`. Lazy per `(hash, refName?)` memoisation; throws
+ *   typed {@link MigrationToolsError} values compatible with CLI mappers.
  */
 interface ContractSpaceMember {
   readonly spaceId: string;
-  readonly contract: Contract;
-  readonly headRef: {
-    readonly hash: string;
-    readonly invariants: readonly string[];
-  };
-  readonly migrations: HydratedMigrationGraph;
+  readonly packages: readonly OnDiskMigrationPackage[];
+  readonly refs: Refs;
+  readonly headRef: ContractSpaceHeadRecord | null;
+  graph(): MigrationGraph;
+  contract(): Contract;
+  contractAt(hash: string, opts?: ContractAtOptions): Promise<ContractAtResult>;
 }
 /**
- * Typed value carrying the user's app contract plus every loaded
- * extension contract space, fully hydrated and internally consistent.
+ * Tolerant, queryable snapshot of a project's on-disk migration state:
+ * the app contract space plus every extension contract space, each a
+ * {@link ContractSpaceMember}.
  *
  * Produced once per CLI invocation by `loadContractSpaceAggregate`.
- * Every downstream component (planner, verifier, runner adapter)
- * consumes this value rather than rebuilding state from disk.
- *
- * Invariants the loader enforces at construction:
- *
- * 1. `targetId` is consistent across every member (`contract.target`
- *    matches `aggregate.targetId`). The aggregate's `targetId` is the
- *    `Config.adapter.targetId` value the loader was told to use.
- * 2. `aggregate.extensions` is sorted alphabetically by `spaceId`.
- *    Mirrors {@link import('../concatenate-space-apply-inputs').concatenateSpaceApplyInputs}'s
- *    extension ordering convention so downstream apply order matches
- *    today's behaviour byte-for-byte.
- * 3. No two members claim the same storage element (table / type / etc.).
- * 4. For each extension member: `member.headRef.hash` is reachable from
- *    the empty-contract sentinel in `member.migrations.graph` (or the
- *    graph is empty and `member.headRef.hash === EMPTY_CONTRACT_HASH`).
- * 5. For the app member: `member.headRef.hash` equals
- *    `member.contract.storage.storageHash`. The app's `migrations`
- *    is hydrated from the user's authored `migrations/` (or empty if
- *    none).
- *
- * The aggregate is **type-uniform** post-construction: app/extension
- * distinguishability survives only at the caller-policy layer
- * (`ignoreGraphFor: new Set([appSpaceId])`), not on member shape.
+ * Building the aggregate never throws on disk content; every consumer
+ * obtains spaces / packages / refs / graphs from this one value rather
+ * than re-deriving them from disk.
+ *
+ * - `targetId`: the app contract's target; every member is expected to
+ *   share it (a mismatch surfaces as a `targetMismatch` violation under
+ *   `checkContracts`).
+ * - `app` / `extensions`: retained as fields for the existing planner /
+ *   verifier / runner consumers. `extensions` is sorted alphabetically
+ *   by `spaceId` (the apply-ordering convention).
+ * - `listSpaces()` / `hasSpace()` / `space()` / `spaces()`: the query
+ *   surface the read commands consume — `app` first, then extension ids
+ *   lex-ascending.
+ * - `checkIntegrity()`: judges the loaded model and returns every
+ *   violation (never bailing at the first). Config/contract-dependent
+ *   checks run only when the matching {@link IntegrityQueryOptions} opt
+ *   is set.
  */
 interface ContractSpaceAggregate {
   readonly targetId: string;
   readonly app: ContractSpaceMember;
   readonly extensions: readonly ContractSpaceMember[];
+  listSpaces(): readonly string[];
+  hasSpace(id: string): boolean;
+  space(id: string): ContractSpaceMember | undefined;
+  spaces(): readonly ContractSpaceMember[];
+  checkIntegrity(opts?: IntegrityQueryOptions): readonly IntegrityViolation[];
 }
 //#endregion
-//#region src/aggregate/loader.d.ts
+//#region src/aggregate/aggregate.d.ts
 /**
- * Single declared extension entry the loader needs from `Config.extensionPacks`.
- *
- * Only the subset of fields the loader operates on:
- *
- * - `id` — the space id (also the directory name under `migrations/`).
- * - `targetId` — the configured `Config.adapter.targetId` value the
- *   declaring extension declared. The loader rejects mismatches against
- *   the aggregate's `targetId` with `targetMismatch`.
- *
- * Whether the descriptor declares a contract space is decided by whether
- * its corresponding `migrations/<id>/` directory exists on disk
- * (materialised by the seed phase before the loader runs); the loader
- * never reads the descriptor's `contractJson` itself. That makes the
- * aggregate's apply / verify paths byte-for-byte independent of the
- * descriptor module — `db verify` succeeds even if the descriptor's
- * `contractJson` is a throwing getter.
- *
- * Typed structurally so the migration-tools layer stays framework-neutral.
+ * Resolve a member's head ref, asserting it is present. The apply/verify
+ * engine only runs after `checkIntegrity` has refused on `headRefMissing`,
+ * so a member reaching the planner / verifier without a head ref is a
+ * programming error (the integrity gate was skipped), not a user-facing
+ * state. The app member's head ref is always synthesised, so this only
+ * ever guards an ungated extension space.
  */
-interface DeclaredExtensionEntry {
-  readonly id: string;
-  readonly targetId: string;
-}
+declare function requireHeadRef(member: ContractSpaceMember): ContractSpaceHeadRecord;
 /**
- * Inputs for {@link loadContractSpaceAggregate}.
- *
- * The loader is the **sole** descriptor-import boundary in the M2.5
- * pipeline: callers gather the descriptor data (already-validated app
- * contract, declared extension entries) and pass it through. Once the
- * loader returns, no descriptor module is imported again for this
- * aggregate's lifetime.
+ * Build a {@link ContractSpaceMember} with lazily-memoised `graph()`,
+ * `contract()`, and `contractAt()` facets.
+ *
+ * `graph()` reconstructs the migration graph from `packages` on first
+ * call and caches it. `contract()` calls `resolveContract` on first call
+ * and caches the result; a throwing `resolveContract` (e.g. a missing or
+ * undeserializable on-disk contract) re-throws on each call rather than
+ * caching a value — `checkIntegrity` surfaces that as `contractUnreadable`.
+ * `contractAt()` materializes the contract at an arbitrary graph node with
+ * the same resolution order as plan-time ref resolution: ref snapshot first
+ * (when `opts.refName` is set), else the matching package's `end-contract.*`.
  */
-interface LoadAggregateInput {
+declare function createContractSpaceMember(args: {
+  readonly spaceId: string;
+  readonly packages: readonly OnDiskMigrationPackage[];
+  readonly refs: Refs;
+  readonly headRef: ContractSpaceHeadRecord | null;
+  readonly refsDir: string;
+  readonly resolveContract: () => Contract;
+  readonly deserializeContract: (raw: unknown) => Contract;
+}): ContractSpaceMember;
+/**
+ * Assemble a {@link ContractSpaceAggregate} value from its members and a
+ * `checkIntegrity` implementation. The query methods (`listSpaces` /
+ * `hasSpace` / `space` / `spaces`) are derived here so every aggregate —
+ * loader-built or test-built — shares one query surface: `app` first,
+ * then `extensions` in the order supplied (the loader sorts them
+ * lex-ascending by `spaceId`).
+ */
+declare function createContractSpaceAggregate(args: {
   readonly targetId: string;
-  readonly migrationsDir: string;
-  readonly appContract: Contract;
-  readonly declaredExtensions: ReadonlyArray<DeclaredExtensionEntry>;
-  readonly deserializeContract: (contractJson: unknown) => Contract;
+  readonly app: ContractSpaceMember;
+  readonly extensions: readonly ContractSpaceMember[];
+  readonly checkIntegrity: (opts?: IntegrityQueryOptions) => readonly IntegrityViolation[];
+}): ContractSpaceAggregate;
+//#endregion
+//#region src/aggregate/check-integrity.d.ts
+/**
+ * One space's load-time facts that `checkIntegrity` judges: the loaded
+ * member, the load-time problems `readMigrationsDir` surfaced for it, and
+ * whether it is the app space (the app head ref is synthesised, so the
+ * head-ref checks are skipped for it).
+ */
+interface IntegritySpaceState {
+  readonly member: ContractSpaceMember;
+  readonly problems: readonly PackageLoadProblem[];
+  /** Per-ref problems: a user ref `*.json` that exists but is unparseable. */
+  readonly refProblems: readonly RefLoadProblem[];
   /**
-   * Hydrated migration graph for the **app member**.
-   *
-   * The framework-neutral migration-tools layer doesn't know how to read
-   * the user's authored `migrations/` directory (the app member's
-   * migration-package layout is family-aware: ops.json shape, manifest
-   * keys, etc.). Callers — the SQL family today — read the user's
-   * `migrations/` and hand the resulting `OnDiskMigrationPackage[]` through.
-   *
-   * Passing `[]` is valid (greenfield project, no authored migrations).
-   * Equivalent to `migrations/` not existing or being empty.
+   * The space's `refs/head.json` problem when it exists but is unparseable.
+   * `null` means the head ref was read cleanly or is genuinely absent —
+   * the absent case is judged `headRefMissing`, the corrupt case here is
+   * judged `refUnreadable` (and suppresses `headRefMissing`).
    */
-  readonly appMigrationPackages: ReadonlyArray<OnDiskMigrationPackage>;
+  readonly headRefProblem: RefLoadProblem | null;
+  readonly isApp: boolean;
+}
+interface IntegrityComputationInput {
+  readonly targetId: string;
+  readonly spaces: readonly IntegritySpaceState[];
 }
 /**
- * Discriminated failure variants the loader emits.
- *
- * Every variant short-circuits at first hit; the loader does not keep
- * collecting after the first violation in any phase except for layout
- * (where every layout offence is bundled into one `layoutViolation`).
+ * Walk the loaded model and return **every** integrity violation — never
+ * bailing at the first. Structurally-derivable violations (load-time
+ * problems, self-edges, missing / unreachable head refs) are always
+ * produced; layout-drift checks require `declaredExtensions`, and
+ * contract / target / disjointness checks require `checkContracts`.
  */
-type LoadAggregateError = {
-  readonly kind: 'layoutViolation';
-  readonly violations: readonly LayoutViolation[];
-} | {
-  readonly kind: 'integrityFailure';
-  readonly spaceId: string;
-  readonly detail: string;
-} | {
-  readonly kind: 'validationFailure';
-  readonly spaceId: string;
-  readonly detail: string;
-} | {
-  readonly kind: 'disjointnessViolation';
-  readonly element: string;
-  readonly claimedBy: readonly string[];
-} | {
-  readonly kind: 'targetMismatch';
-  readonly spaceId: string;
-  readonly expected: string;
-  readonly actual: string;
-};
+declare function computeIntegrityViolations(input: IntegrityComputationInput, opts?: IntegrityQueryOptions): readonly IntegrityViolation[];
+declare function loadProblemToViolation(spaceId: string, problem: PackageLoadProblem): IntegrityViolation;
+//#endregion
+//#region src/aggregate/loader.d.ts
 /**
- * Single layout violation; bundled into a `layoutViolation` error so
- * users see every layout offence at once rather than fixing them one
- * at a time across re-runs.
- *
- * - `declaredButUnmigrated`: extension declared in `extensionPacks` with
- *   a `contractSpace` but no contract-space dir on disk. Remediation:
- *   `prisma-next migrate`.
- * - `orphanSpaceDir`: contract-space dir under `migrations/` for an extension
- *   not in `extensionPacks`. Remediation: remove the directory, or
- *   re-add the extension to `extensionPacks`.
+ * Inputs for {@link loadContractSpaceAggregate}.
+ *
+ * Construction reads migration **state** from disk (`migrations/<space>/`
+ * packages + refs + head refs). The app's *live* contract is not a disk
+ * artefact — in Prisma Next it is always compiled from the project's
+ * central contract, so the caller always has it and threads it in as
+ * `appContract`. `deserializeContract` is held and called lazily only for
+ * the on-disk extension contracts (`migrations/<ext>/contract.json`).
  */
-type LayoutViolation = {
-  readonly kind: 'declaredButUnmigrated';
-  readonly spaceId: string;
-} | {
-  readonly kind: 'orphanSpaceDir';
-  readonly spaceId: string;
-};
-type LoadAggregateOutput = Result<{
-  readonly aggregate: ContractSpaceAggregate;
-}, LoadAggregateError>;
+interface LoadAggregateInput {
+  readonly migrationsDir: string;
+  readonly deserializeContract: (raw: unknown) => Contract;
+  readonly appContract: Contract;
+}
 /**
- * Hydrate a {@link ContractSpaceAggregate} from on-disk state and
- * the app contract value the caller supplies.
- *
- * The loader is the **only** descriptor-import boundary at apply /
- * verify time, but it intentionally does **not** read the extension
- * descriptor's `contractJson` value. Each extension space's contract
- * is read from its on-disk `migrations/<id>/contract.json` mirror; the
- * descriptor's role is exhausted by the seed phase that wrote that
- * mirror in the first place. The loader composes existing
- * migration-tools primitives — layout precheck (via
- * {@link listContractSpaceDirectories}), integrity checks (via
- * {@link readMigrationsDir} / {@link readContractSpaceHeadRef} /
- * {@link readContractSpaceContract} / `deserializeContract`), and
- * disjointness — into a single typed value.
- *
- * Failure semantics: every failure variant in {@link LoadAggregateError}
- * short-circuits the load.
+ * Build a tolerant, queryable {@link ContractSpaceAggregate} from on-disk
+ * migration state plus the caller's live app contract.
+ *
+ * Building **never throws on disk content**: a hash- or
+ * invariants-mismatched package is retained, an unparseable package is
+ * omitted, a missing extension head ref leaves `headRef: null`, and an
+ * unreadable on-disk contract defers its failure to `member.contract()`.
+ * Every such problem is judged by {@link ContractSpaceAggregate.checkIntegrity}
+ * rather than aborting the load. The only rejections are catastrophic I/O
+ * (a `migrations/` that exists but is unreadable for reasons other than
+ * absence).
+ *
+ * The app space's head ref is synthesised from the live contract's
+ * storage hash (the app contract is authored independently of the
+ * migration graph), and `app.contract()` returns the supplied contract.
+ * Extension spaces read their contract, refs, and head ref from disk.
  */
-declare function loadContractSpaceAggregate(input: LoadAggregateInput): Promise<LoadAggregateOutput>;
+declare function loadContractSpaceAggregate(input: LoadAggregateInput): Promise<ContractSpaceAggregate>;
 //#endregion
 //#region src/aggregate/marker-types.d.ts
 /**
@@ -236,7 +360,7 @@ interface ContractMarkerRecordLike {
 //#endregion
 //#region src/aggregate/planner-types.d.ts
 /**
- * Caller-provided policy for {@link planAggregate}. Today this carries
+ * Caller-provided policy for {@link planMigration}. Today this carries
  * just one knob:
  *
  * - `ignoreGraphFor`: `Set<spaceId>`. For listed members, the planner
@@ -275,7 +399,7 @@ interface AggregateCurrentDBState {
   readonly schemaIntrospection: unknown;
 }
 /**
- * Inputs to {@link planAggregate}.
+ * Inputs to {@link planMigration}.
  *
  * The planner is target-agnostic but family-aware: per-member synth
  * delegates to the family's `createPlanner(familyInstance).plan(...)`,
@@ -284,11 +408,11 @@ interface AggregateCurrentDBState {
  * threaded through. (`frameworkComponents` is passed verbatim into
  * `planner.plan(...)` per ADR 212; the planner does not interpret it.)
  *
- * The aggregate planner does **not** receive a `targetId` separately —
+ * The planner does **not** receive a `targetId` separately —
  * it reads `aggregate.targetId` and stamps it onto every emitted
  * `MigrationPlan` from construction. No placeholder, no patch step.
  */
-interface AggregatePlannerInput<TFamilyId extends string, TTargetId extends string> {
+interface PlannerInput<TFamilyId extends string, TTargetId extends string> {
   readonly aggregate: ContractSpaceAggregate;
   readonly currentDBState: AggregateCurrentDBState;
   readonly familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
@@ -298,7 +422,7 @@ interface AggregatePlannerInput<TFamilyId extends string, TTargetId extends stri
   readonly operationPolicy: MigrationOperationPolicy;
 }
 /**
- * Per-member output of the aggregate planner. The runner ingests this
+ * Per-member output of the planner. The runner ingests this
  * shape directly via a thin `toRunnerInput` adapter at the CLI.
  *
  * - `plan`: ready-to-execute `MigrationPlan` with `targetId` already
@@ -314,8 +438,8 @@ interface AggregatePlannerInput<TFamilyId extends string, TTargetId extends stri
 /**
  * Per-edge metadata for the chain assembled by the graph-walk
  * strategy. Lets `migrate` surface a per-migration `applied[]`
- * entry (preserving the single-space `migrationsApplied` count
- * semantics) without re-walking the graph.
+ * entry (preserving the `migrationsApplied` count semantics) without
+ * re-walking the graph.
  *
  * `synth`-produced plans leave this absent — synthesised plans don't
  * have authored edges to surface.
@@ -327,7 +451,7 @@ interface AggregateMigrationEdgeRef {
   readonly to: string;
   readonly operationCount: number;
 }
-interface AggregatePerSpacePlan {
+interface PerSpacePlan {
   readonly plan: MigrationPlan;
   readonly displayOps: readonly MigrationPlanOperation[];
   readonly destinationContract: Contract;
@@ -349,24 +473,24 @@ interface AggregatePerSpacePlan {
    */
   readonly pathDecision?: PathDecision;
 }
-interface AggregatePlannerSuccess {
-  readonly perSpace: ReadonlyMap<string, AggregatePerSpacePlan>;
+interface PlannerSuccess {
+  readonly perSpace: ReadonlyMap<string, PerSpacePlan>;
   /**
    * `applyOrder` is the order the runner must walk per-space inputs.
    * Mirrors the existing `concatenateSpaceApplyInputs` convention:
    * extensions alphabetically by `spaceId`, then the app. Tests assert
-   * on `MultiSpaceRunnerFailure.failingSpace`, which is positional in
+   * on `MigrationRunnerFailure.failingSpace`, which is positional in
    * the runner's input array — preserving the literal ordering keeps
    * `failingSpace` attribution byte-for-byte.
    */
   readonly applyOrder: readonly string[];
 }
 /**
- * Discriminated failure variants for {@link planAggregate}. Each
+ * Discriminated failure variants for {@link planMigration}. Each
  * variant short-circuits the plan; per-member errors carry the
  * `spaceId` so the CLI can surface a precise envelope.
  */
-type AggregatePlannerError = {
+type PlannerError = {
   readonly kind: 'extensionPathUnreachable';
   readonly spaceId: string;
   readonly target: string;
@@ -383,7 +507,7 @@ type AggregatePlannerError = {
   readonly spaceId: string;
   readonly detail: string;
 };
-type AggregatePlannerOutput = Result<AggregatePlannerSuccess, AggregatePlannerError>;
+type PlannerOutput = Result<PlannerSuccess, PlannerError>;
 //#endregion
 //#region src/aggregate/planner.d.ts
 /**
@@ -394,7 +518,7 @@ type AggregatePlannerOutput = Result<AggregatePlannerSuccess, AggregatePlannerEr
  * 1. If `callerPolicy.ignoreGraphFor.has(member.spaceId)`:
  *    - If `member.headRef.invariants` is empty → synth.
  *    - Else → `policyConflict` (synth cannot satisfy authored invariants).
- * 2. Else if `member.migrations.graph` is non-empty AND graph-walk
+ * 2. Else if `member.graph()` is non-empty AND graph-walk
  *    succeeds → graph-walk.
  * 3. Else if `member.headRef.invariants` is empty → synth.
  * 4. Else → graph-walk failure → `extensionPathUnreachable` /
@@ -403,12 +527,12 @@ type AggregatePlannerOutput = Result<AggregatePlannerSuccess, AggregatePlannerEr
  * Output `applyOrder` is `[...aggregate.extensions.map(spaceId), aggregate.app.spaceId]`
  * — extensions alphabetical, then app — matching today's
  * `concatenateSpaceApplyInputs` ordering. This preserves
- * `MultiSpaceRunnerFailure.failingSpace` attribution byte-for-byte.
+ * `MigrationRunnerFailure.failingSpace` attribution byte-for-byte.
  *
  * Every emitted `MigrationPlan` has `targetId = aggregate.targetId`.
  * No placeholder cast; no patch step.
  */
-declare function planAggregate<TFamilyId extends string, TTargetId extends string>(input: AggregatePlannerInput<TFamilyId, TTargetId>): Promise<AggregatePlannerOutput>;
+declare function planMigration<TFamilyId extends string, TTargetId extends string>(input: PlannerInput<TFamilyId, TTargetId>): Promise<PlannerOutput>;
 //#endregion
 //#region src/aggregate/project-schema-to-space.d.ts
 /**
@@ -471,14 +595,14 @@ declare function projectSchemaToSpace(schema: unknown, member: ContractSpaceMemb
 /**
  * Outcome variants for the graph-walk strategy. Mirrors
  * {@link import('../../compute-extension-space-apply-path').ExtensionSpaceApplyPathOutcome}
- * but operates against the **already-hydrated** `member.migrations.graph`
+ * but operates against the member's lazily-reconstructed `graph()`
  * instead of re-reading from disk. The aggregate planner converts
- * these into {@link import('../planner-types').AggregatePlannerError}
+ * these into {@link import('../planner-types').PlannerError}
  * variants.
  */
 type GraphWalkOutcome = {
   readonly kind: 'ok';
-  readonly result: AggregatePerSpacePlan;
+  readonly result: PerSpacePlan;
 } | {
   readonly kind: 'unreachable';
 } | {
@@ -516,12 +640,12 @@ declare function graphWalkStrategy(input: GraphWalkStrategyInputs): GraphWalkOut
 //#endregion
 //#region src/aggregate/verifier.d.ts
 /**
- * Caller policy for the aggregate verifier. Today's only knob is
+ * Caller policy for the 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`.
  */
-interface AggregateVerifierInput<TSchemaResult> {
+interface VerifierInput<TSchemaResult> {
   readonly aggregate: ContractSpaceAggregate;
   readonly markersBySpaceId: ReadonlyMap<string, ContractMarkerRecordLike | null>;
   readonly schemaIntrospection: unknown;
@@ -529,7 +653,7 @@ interface AggregateVerifierInput<TSchemaResult> {
   /**
    * 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
+   * families). The verifier projects the schema to the
    * member's slice via {@link projectSchemaToSpace} before invoking
    * the callback, so single-contract semantics are preserved.
    *
@@ -567,7 +691,7 @@ interface MarkerCheckSection {
 }
 /**
  * A live storage element (today: a top-level table) not claimed by any
- * member of the aggregate. The aggregate verifier always reports these;
+ * member of the aggregate. The verifier always reports these;
  * the caller decides what to do — `db verify --strict` treats them as
  * errors, the lenient default treats them as informational.
  *
@@ -587,15 +711,15 @@ interface SchemaCheckSection<TSchemaResult> {
    */
   readonly orphanElements: readonly OrphanElement[];
 }
-interface AggregateVerifierSuccess<TSchemaResult> {
+interface VerifierSuccess<TSchemaResult> {
   readonly markerCheck: MarkerCheckSection;
   readonly schemaCheck: SchemaCheckSection<TSchemaResult>;
 }
-type AggregateVerifierError = {
+type VerifierError = {
   readonly kind: 'introspectionFailure';
   readonly detail: string;
 };
-type AggregateVerifierOutput<TSchemaResult> = Result<AggregateVerifierSuccess<TSchemaResult>, AggregateVerifierError>;
+type VerifierOutput<TSchemaResult> = Result<VerifierSuccess<TSchemaResult>, VerifierError>;
 /**
  * Verify a {@link ContractSpaceAggregate} against the live database
  * state. Bundles two checks:
@@ -618,7 +742,7 @@ type AggregateVerifierOutput<TSchemaResult> = Result<AggregateVerifierSuccess<TS
  * Pure synchronous function; no I/O. The caller (CLI) gathers
  * `markersBySpaceId` and `schemaIntrospection` ahead of the call.
  */
-declare function verifyAggregate<TSchemaResult>(input: AggregateVerifierInput<TSchemaResult>): AggregateVerifierOutput<TSchemaResult>;
+declare function verifyMigration<TSchemaResult>(input: VerifierInput<TSchemaResult>): VerifierOutput<TSchemaResult>;
 //#endregion
-export { type AggregateCurrentDBState, type AggregateMigrationEdgeRef, type AggregatePerSpacePlan, type AggregatePlannerError, type AggregatePlannerInput, type AggregatePlannerOutput, type AggregatePlannerSuccess, type AggregateVerifierError, type AggregateVerifierInput, type AggregateVerifierOutput, type AggregateVerifierSuccess, type CallerPolicy, type ContractMarkerRecordLike, type ContractSpaceAggregate, type ContractSpaceMember, type DeclaredExtensionEntry, type GraphWalkOutcome, type GraphWalkStrategyInputs, type HydratedMigrationGraph, type LayoutViolation, type LoadAggregateError, type LoadAggregateInput, type LoadAggregateOutput, type MarkerCheckResult, type MarkerCheckSection, type OrphanElement, type SchemaCheckSection, graphWalkStrategy, loadContractSpaceAggregate, planAggregate, projectSchemaToSpace, verifyAggregate };
+export { type AggregateCurrentDBState, type AggregateMigrationEdgeRef, type CallerPolicy, type ContractAtOptions, type ContractAtResult, type ContractMarkerRecordLike, type ContractSpaceAggregate, type ContractSpaceMember, type DeclaredExtensionEntry, type GraphWalkOutcome, type GraphWalkStrategyInputs, type IntegrityComputationInput, type IntegrityQueryOptions, type IntegritySpaceState, type IntegrityViolation, type LoadAggregateInput, type MarkerCheckResult, type MarkerCheckSection, type OrphanElement, type PerSpacePlan, type PlannerError, type PlannerInput, type PlannerOutput, type PlannerSuccess, type SchemaCheckSection, type VerifierError, type VerifierInput, type VerifierOutput, type VerifierSuccess, computeIntegrityViolations, createContractSpaceAggregate, createContractSpaceMember, graphWalkStrategy, loadContractSpaceAggregate, loadProblemToViolation, planMigration, projectSchemaToSpace, requireHeadRef, verifyMigration };
 //# sourceMappingURL=aggregate.d.mts.map