@prisma-next/framework-components 0.5.0-dev.9 → 0.5.1

package/dist/control.d.mts

@@ -1,12 +1,14 @@
-import { a as AuthoringFieldNamespace, d as AuthoringTypeNamespace, i as AuthoringContributions } from "./framework-authoring-D1-JZ37B.mjs";
-import { n as CodecLookup } from "./codec-types-DQ1Agjom.mjs";
-import { A as LoweredDefaultResult, C as ControlMutationDefaultEntry, D as DefaultFunctionLoweringHandler, E as DefaultFunctionLoweringContext, F as SourceSpan, M as MutationDefaultGeneratorDescriptor, N as ParsedDefaultFunctionCall, O as DefaultFunctionRegistry, P as SourceDiagnostic, T as ControlMutationDefaults, a as ComponentMetadata, b as TargetInstance, c as DriverDescriptor, d as ExtensionDescriptor, f as ExtensionInstance, h as FamilyInstance, j as LoweredDefaultValue, k as DefaultFunctionRegistryEntry, l as DriverInstance, m as FamilyDescriptor, n as AdapterInstance, t as AdapterDescriptor, v as TargetBoundComponentDescriptor, w as ControlMutationDefaultRegistry, y as TargetDescriptor } from "./framework-components-DFZMi2h7.mjs";
-import { t as TypesImportSpec } from "./types-import-spec-C4sc7wbb.mjs";
-import { t as EmissionSpi } from "./emission-types-BPAALJbF.mjs";
+import { a as AuthoringFieldNamespace, d as AuthoringTypeNamespace, i as AuthoringContributions } from "./framework-authoring-DGIQbNPt.mjs";
+import { c as CodecLookup } from "./codec-m_-FAyQn.mjs";
+import { A as LoweredDefaultResult, C as ControlMutationDefaultEntry, D as DefaultFunctionLoweringHandler, E as DefaultFunctionLoweringContext, F as SourceSpan, M as MutationDefaultGeneratorDescriptor, N as ParsedDefaultFunctionCall, O as DefaultFunctionRegistry, P as SourceDiagnostic, T as ControlMutationDefaults, a as ComponentMetadata, b as TargetInstance, c as DriverDescriptor, d as ExtensionDescriptor, f as ExtensionInstance, h as FamilyInstance, j as LoweredDefaultValue, k as DefaultFunctionRegistryEntry, l as DriverInstance, m as FamilyDescriptor, n as AdapterInstance, t as AdapterDescriptor, v as TargetBoundComponentDescriptor, w as ControlMutationDefaultRegistry, y as TargetDescriptor } from "./framework-components-CHuBHXQN.mjs";
+import { t as TypesImportSpec } from "./types-import-spec-BxI5cSQy.mjs";
+import { t as EmissionSpi } from "./emission-types-CMv_053d.mjs";
+import { m as PslDocumentAst } from "./psl-ast-Ckn_G-jv.mjs";
 import { Contract, ContractMarkerRecord } from "@prisma-next/contract/types";
+import { ImportRequirement, ImportRequirement as ImportRequirement$1 } from "@prisma-next/ts-render";
 import { Result } from "@prisma-next/utils/result";
 
-//#region src/control-result-types.d.ts
+//#region src/control/control-result-types.d.ts
 declare const VERIFY_CODE_MARKER_MISSING = "PN-RUN-3001";
 declare const VERIFY_CODE_HASH_MISMATCH = "PN-RUN-3002";
 declare const VERIFY_CODE_TARGET_MISMATCH = "PN-RUN-3003";
@@ -43,12 +45,11 @@ interface VerifyDatabaseResult {
   };
 }
 interface BaseSchemaIssue {
-  readonly kind: 'missing_table' | 'missing_column' | 'extra_table' | 'extra_column' | 'extra_primary_key' | 'extra_foreign_key' | 'extra_unique_constraint' | 'extra_index' | 'extra_validator' | 'type_mismatch' | 'type_missing' | 'type_values_mismatch' | 'nullability_mismatch' | 'primary_key_mismatch' | 'foreign_key_mismatch' | 'unique_constraint_mismatch' | 'index_mismatch' | 'dependency_missing' | 'default_missing' | 'default_mismatch' | 'extra_default';
+  readonly kind: 'missing_table' | 'missing_column' | 'extra_table' | 'extra_column' | 'extra_primary_key' | 'extra_foreign_key' | 'extra_unique_constraint' | 'extra_index' | 'extra_validator' | 'type_mismatch' | 'type_missing' | 'type_values_mismatch' | 'nullability_mismatch' | 'primary_key_mismatch' | 'foreign_key_mismatch' | 'unique_constraint_mismatch' | 'index_mismatch' | 'default_missing' | 'default_mismatch' | 'extra_default';
   readonly table?: string;
   readonly column?: string;
   readonly indexOrConstraint?: string;
   readonly typeName?: string;
-  readonly dependencyId?: string;
   readonly expected?: string;
   readonly actual?: string;
   readonly message: string;
@@ -154,7 +155,7 @@ interface SignDatabaseResult {
   };
 }
 //#endregion
-//#region src/control-instances.d.ts
+//#region src/control/control-instances.d.ts
 interface ControlFamilyInstance<TFamilyId extends string, TSchemaIR> extends FamilyInstance<TFamilyId> {
   validateContract(contractJson: unknown): Contract;
   verify(options: {
@@ -172,15 +173,59 @@ interface ControlFamilyInstance<TFamilyId extends string, TSchemaIR> extends Fam
     readonly configPath?: string;
     readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, string>>;
   }): Promise<VerifyDatabaseSchemaResult>;
+  /**
+   * Verify a contract against an already-introspected schema slice.
+   *
+   * Difference from {@link schemaVerify}: no `driver`, no introspection
+   * — the caller hands over the schema directly. Used by the aggregate
+   * verifier to invoke the family's verification logic per member,
+   * with the schema **pre-projected** to that member's claimed slice
+   * via {@link import('@prisma-next/migration-tools/aggregate').projectSchemaToSpace}.
+   *
+   * Synchronous — no I/O. Idempotent.
+   */
+  schemaVerifyAgainstSchema(options: {
+    readonly contract: unknown;
+    readonly schema: TSchemaIR;
+    readonly strict: boolean;
+    readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, string>>;
+  }): VerifyDatabaseSchemaResult;
   sign(options: {
     readonly driver: ControlDriverInstance<TFamilyId, string>;
     readonly contract: unknown;
     readonly contractPath: string;
     readonly configPath?: string;
   }): Promise<SignDatabaseResult>;
+  /**
+   * Reads the contract marker for `space` from the database, returning
+   * `null` if no marker row exists for that space (or if the marker
+   * table itself is missing).
+   *
+   * `space` is required at every call site so the type system surfaces
+   * every place that needs to thread the value: callers in single-app
+   * paths pass {@link import('./control-spaces').APP_SPACE_ID}
+   * (`'app'`); per-extension callers pass the extension's space id.
+   * Defaulting at the family-interface level was a silent bug door —
+   * it let multi-space-aware callers forget to pass `space` and
+   * collapse onto the app's marker row.
+   *
+   * Families whose underlying storage doesn't yet support per-space
+   * markers (Mongo, today) accept `space` for interface conformance and
+   * reject any non-`APP_SPACE_ID` value rather than silently ignoring
+   * it; see the family-specific implementation for details.
+   */
   readMarker(options: {
     readonly driver: ControlDriverInstance<TFamilyId, string>;
+    readonly space: string;
   }): Promise<ContractMarkerRecord | null>;
+  /**
+   * Reads every marker row keyed by `space`. Used by the per-space
+   * verifier to detect orphan marker rows and marker-vs-on-disk drift.
+   * Returns an empty map when the marker table does not yet exist.
+   */
+  readAllMarkers(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+  }): Promise<ReadonlyMap<string, ContractMarkerRecord>>;
   introspect(options: {
     readonly driver: ControlDriverInstance<TFamilyId, string>;
     readonly contract?: unknown;
@@ -196,7 +241,7 @@ interface ControlDriverInstance<TFamilyId extends string, TTargetId extends stri
 }
 interface ControlExtensionInstance<TFamilyId extends string, TTargetId extends string> extends ExtensionInstance<TFamilyId, TTargetId> {}
 //#endregion
-//#region src/control-stack.d.ts
+//#region src/control/control-stack.d.ts
 interface AssembledAuthoringContributions {
   readonly field: AuthoringFieldNamespace;
   readonly type: AuthoringTypeNamespace;
@@ -208,7 +253,6 @@ interface ControlStack<TFamilyId extends string = string, TTargetId extends stri
   readonly driver?: ControlDriverDescriptor<TFamilyId, TTargetId> | undefined;
   readonly extensionPacks: readonly ControlExtensionDescriptor<TFamilyId, TTargetId>[];
   readonly codecTypeImports: ReadonlyArray<TypesImportSpec>;
-  readonly operationTypeImports: ReadonlyArray<TypesImportSpec>;
   readonly queryOperationTypeImports: ReadonlyArray<TypesImportSpec>;
   readonly extensionIds: ReadonlyArray<string>;
   readonly codecLookup: CodecLookup;
@@ -231,7 +275,6 @@ declare function assertUniqueCodecOwner(options: {
   readonly entityOwnershipLabel: string;
 }): void;
 declare function extractCodecTypeImports(descriptors: ReadonlyArray<Pick<ComponentMetadata, 'types'>>): ReadonlyArray<TypesImportSpec>;
-declare function extractOperationTypeImports(descriptors: ReadonlyArray<Pick<ComponentMetadata, 'types'>>): ReadonlyArray<TypesImportSpec>;
 declare function extractQueryOperationTypeImports(descriptors: ReadonlyArray<Pick<ComponentMetadata, 'types'>>): ReadonlyArray<TypesImportSpec>;
 declare function extractComponentIds(family: {
   readonly id: string;
@@ -252,11 +295,11 @@ declare function assembleControlMutationDefaults(descriptors: ReadonlyArray<Pick
   readonly id?: string;
 }>): ControlMutationDefaults;
 declare function extractCodecLookup(descriptors: ReadonlyArray<Pick<ComponentMetadata & {
-  id?: string;
+  id: string;
 }, 'types' | 'id'>>): CodecLookup;
 declare function createControlStack<TFamilyId extends string, TTargetId extends string>(input: CreateControlStackInput<TFamilyId, TTargetId>): ControlStack<TFamilyId, TTargetId>;
 //#endregion
-//#region src/control-descriptors.d.ts
+//#region src/control/control-descriptors.d.ts
 interface ControlFamilyDescriptor<TFamilyId extends string, TFamilyInstance extends ControlFamilyInstance<TFamilyId, unknown> = ControlFamilyInstance<TFamilyId, unknown>> extends FamilyDescriptor<TFamilyId> {
   readonly emission: EmissionSpi;
   create<TTargetId extends string>(stack: ControlStack<TFamilyId, TTargetId>): TFamilyInstance;
@@ -281,7 +324,62 @@ interface ControlExtensionDescriptor<TFamilyId extends string, TTargetId extends
   create(): TExtensionInstance;
 }
 //#endregion
-//#region src/control-migration-types.d.ts
+//#region src/control/control-migration-types.d.ts
+/**
+ * Planner provenance recorded inside {@link MigrationMetadata}.
+ *
+ * `used` / `applied` track which migration hints the planner consulted
+ * vs. which it actually applied during emission; `plannerVersion`
+ * pins the planner build that produced the migration so future
+ * verification passes can recognise plans authored against an older
+ * planner.
+ */
+interface MigrationHints {
+  readonly used: readonly string[];
+  readonly applied: readonly string[];
+  readonly plannerVersion: string;
+}
+/**
+ * In-memory migration metadata envelope. Every migration is
+ * content-addressed: the `migrationHash` is a hash over the metadata
+ * envelope plus the operations list, computed at write time. There is no
+ * draft state — a migration directory either exists with fully attested
+ * metadata or it does not.
+ *
+ * When the planner cannot lower an operation because of an unfilled
+ * `placeholder(...)` slot, the migration is still written with
+ * `migrationHash` hashed over `ops: []`. Re-running self-emit after the
+ * user fills the placeholder produces a *different* `migrationHash`
+ * (committed to the real ops); this is intentional.
+ *
+ * The on-disk JSON shape in `migration.json` matches this type
+ * field-for-field — `JSON.stringify(metadata, null, 2)` is the canonical
+ * writer output (defined in `@prisma-next/migration-tools/io`).
+ */
+interface MigrationMetadata {
+  readonly migrationHash: string;
+  readonly from: string | null;
+  readonly to: string;
+  readonly fromContract: Contract | null;
+  readonly toContract: Contract;
+  readonly hints: MigrationHints;
+  readonly labels: readonly string[];
+  /**
+   * Sorted, deduplicated list of `invariantId`s declared by the
+   * migration's data-transform ops. Always present; an empty array
+   * means the migration has no routing-visible data transforms.
+   */
+  readonly providedInvariants: readonly string[];
+  readonly authorship?: {
+    readonly author?: string;
+    readonly email?: string;
+  };
+  readonly signature?: {
+    readonly keyId: string;
+    readonly value: string;
+  } | null;
+  readonly createdAt: string;
+}
 /**
  * Migration operation classes define the safety level of an operation.
  * - 'additive': Adds new structures without modifying existing ones (safe)
@@ -294,52 +392,15 @@ type MigrationOperationClass = 'additive' | 'widening' | 'destructive' | 'data';
  * A lowered query statement as stored in ops.json.
  * Contains the SQL string and parameter values — ready for execution.
  * Lowering from query builder AST to SQL happens at verify time.
+ *
+ * The Postgres `dataTransform` factory uses this shape internally to
+ * carry the user's lowered `check`/`run` plans before wrapping them
+ * into precheck/execute/postcheck steps on the unified migration op.
  */
 interface SerializedQueryPlan {
   readonly sql: string;
   readonly params: readonly unknown[];
 }
-/**
- * A data transform operation within a migration edge.
- *
- * Data transforms are authored in TypeScript using the query builder,
- * serialized to JSON ASTs at verification time, and rendered to SQL
- * by the target adapter at apply time.
- *
- * The `name` serves as the invariant identity — it's recorded in the
- * ledger and used for invariant-aware routing via environment refs.
- *
- * In draft state (before verification), `check` and `run` are null.
- * After verification, they contain the serialized query ASTs.
- */
-interface DataTransformOperation extends MigrationPlanOperation {
-  readonly operationClass: 'data';
-  /**
-   * The invariant name for this data transform.
-   * Recorded in the ledger on successful edge completion.
-   * Used by environment refs to declare required invariants.
-   */
-  readonly name: string;
-  /**
-   * Path to the TypeScript source file that produced this operation.
-   * Not part of edgeId computation — for traceability only.
-   */
-  readonly source: string;
-  /**
-   * Serialized check query plan, or a boolean literal.
-   * - SerializedQueryPlan: describes violations; empty result = already applied.
-   * - false: always run (no check).
-   * - true: always skip.
-   * - null: not yet serialized (draft state).
-   */
-  readonly check: SerializedQueryPlan | boolean | null;
-  /**
-   * Serialized run query plans.
-   * - Array of serialized query plans to execute sequentially.
-   * - null: not yet serialized (draft state).
-   */
-  readonly run: readonly SerializedQueryPlan[] | null;
-}
 /**
  * Policy defining which operation classes are allowed during a migration.
  */
@@ -357,11 +418,46 @@ interface MigrationPlanOperation {
   readonly label: string;
   /** The class of operation (additive, widening, destructive). */
   readonly operationClass: MigrationOperationClass;
+  /**
+   * Optional opt-in routing identity for data-transform operations.
+   * Presence opts the transform into invariant-aware routing; absence
+   * means it is path-dependent and not referenceable from refs.
+   *
+   * Lives on the base op so the manifest emitter and
+   * `deriveProvidedInvariants` can read it without depending on a
+   * target-specific shape. Schema-DDL ops (additive / widening /
+   * destructive) leave it undefined.
+   */
+  readonly invariantId?: string;
 }
 /**
- * Framework-level contract for a single factory call in a target's planner IR.
+ * Framework-level contract for a single factory call in a target's planner
+ * IR — the canonical shape for any node participating in the two-renderer
+ * pattern (source-text rendering for `migration.ts` + runtime-op derivation
+ * for `ops.json`).
+ *
+ * Implementations declare:
+ *
+ *   - **Identity / display metadata** (`factoryName`, `operationClass`,
+ *     `label`) used by CLI summaries and the issue planner.
+ *   - **`renderTypeScript()`** — emit the call as a TypeScript expression
+ *     suitable for inclusion in a generated `migration.ts`. Polymorphic
+ *     across postgres / mongo / sqlite / extension-owned calls.
+ *   - **`importRequirements()`** — the symbols this rendered expression
+ *     pulls in. Aggregated and deduplicated by the top-level renderer
+ *     into a single import block per file.
+ *   - **`toOp()`** — lower the call to a runtime
+ *     `MigrationPlanOperation`. Returns the framework base; concrete
+ *     implementations narrow via covariant return (e.g. SQL targets
+ *     return `SqlMigrationPlanOperation<TTargetDetails>`).
+ *
+ * Each domain (target, extension) defines its own set of concrete `*Call`
+ * classes that implement this interface — typically by extending
+ * {@link import('@prisma-next/ts-render').TsExpression} and adding the
+ * concrete `toOp()` body. Extensions can implement the interface
+ * directly without depending on a target's package-private base.
  *
- * @see ADR 195
+ * @see ADR 195 — Planner IR with two renderers.
  */
 interface OpFactoryCall {
   /** The name of the factory that would produce this call's runtime op. */
@@ -370,6 +466,26 @@ interface OpFactoryCall {
   readonly operationClass: MigrationOperationClass;
   /** Human-readable label for CLI output and diagnostics. */
   readonly label: string;
+  /**
+   * Render this call as a TypeScript expression suitable for inclusion in
+   * a generated `migration.ts`. The output is composed alongside other
+   * calls' rendered expressions inside the migration's `operations`
+   * array.
+   */
+  renderTypeScript(): string;
+  /**
+   * Import requirements pulled in by the rendered TypeScript expression.
+   * Aggregated and deduplicated across all calls into a single import
+   * block per file.
+   */
+  importRequirements(): readonly ImportRequirement$1[];
+  /**
+   * Lower this call to a runtime migration plan operation suitable for
+   * execution / inclusion in `ops.json`. Concrete implementations narrow
+   * the return type via covariant return (e.g. SQL targets return
+   * `SqlMigrationPlanOperation<TTargetDetails>`).
+   */
+  toOp(): MigrationPlanOperation;
 }
 /**
  * A migration plan for display purposes.
@@ -378,6 +494,16 @@ interface OpFactoryCall {
 interface MigrationPlan {
   /** The target ID this plan is for (e.g., 'postgres'). */
   readonly targetId: string;
+  /**
+   * Contract space this plan applies to. Runners cross-check
+   * `options.space` against `plan.spaceId` so the marker row gets keyed
+   * by the right space when applying via `executeAcrossSpaces`.
+   *
+   * Optional for backward compatibility with single-space callers that
+   * pre-date the contract-space aggregate; when present, runners
+   * enforce that it matches `options.space`.
+   */
+  readonly spaceId?: string;
   /**
    * Origin contract identity that the plan expects the database to currently be at.
    * If omitted or null, the runner skips origin validation entirely.
@@ -393,6 +519,17 @@ interface MigrationPlan {
   };
   /** Ordered list of operations to execute. */
   readonly operations: readonly MigrationPlanOperation[];
+  /**
+   * Sorted, deduplicated invariant ids declared by this plan's data-transform
+   * ops. Authored migrations carry the canonical value from
+   * `migration.json.providedInvariants`; planner-built plans (`db init`,
+   * `db update`) omit it (the runner treats it as `[]`). Runners read this
+   * field for marker writes and self-edge no-op detection rather than
+   * re-deriving from `operations`, since the manifest is the canonical
+   * source for the invariant set across all runners (postgres, sqlite,
+   * mongo).
+   */
+  readonly providedInvariants?: readonly string[];
 }
 /**
  * A migration plan that can also render itself back to user-editable
@@ -502,27 +639,36 @@ interface MigrationPlanner<TFamilyId extends string = string, TTargetId extends
     readonly contract: unknown;
     readonly schema: unknown;
     readonly policy: MigrationOperationPolicy;
-    /**
-     * Storage hash of the "from" contract (the state the planner assumes the
-     * database starts at). Planners use this to populate `describe()` on the
-     * produced plan so the rendered `migration.ts` has correct `from`/`to`
-     * metadata.
-     */
-    readonly fromHash: string;
     /**
      * The "from" contract (the state the planner assumes the database starts
-     * at). Planners pass this to data-safety strategies so they can compare
-     * `from` and `to` column shapes (e.g. to detect unsafe type changes).
-     * `db update` / `db init` reconcile against the live schema and have no
-     * "from" contract; only `migration plan` provides one.
+     * at), or `null` for a baseline plan with no prior state.
+     *
+     * Planners derive any "from" identity they need to stamp onto the
+     * produced plan's `describe()` from `fromContract?.storage.storageHash
+     * ?? null`. They also pass this to data-safety strategies so they can
+     * compare `from` and `to` column shapes (e.g. to detect unsafe type
+     * changes).
+     *
+     * Required at every call site to make the structural fact "I have a
+     * prior contract / I don't" visible in the type. Reconciliation
+     * commands (`db init`, `db update`) introspect a live schema and pass
+     * `null`; authoring commands (`migration plan`) pass the previous
+     * bundle's `metadata.toContract`.
      */
-    readonly fromContract?: unknown;
+    readonly fromContract: Contract | null;
     /**
      * Active framework components participating in this composition.
      * Families/targets can interpret this list to derive family-specific metadata.
      * All components must have matching familyId and targetId.
      */
     readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+    /**
+     * Contract space this plan applies to. Stamped onto the produced
+     * plan so the runner keys the marker row by the right space when
+     * executing. App-plan callers pass `APP_SPACE_ID` (`'app'`);
+     * per-extension callers pass the extension's space id.
+     */
+    readonly spaceId: string;
   }): MigrationPlannerResult;
   /**
    * Produce an empty migration with the target's authoring conventions.
@@ -530,8 +676,12 @@ interface MigrationPlanner<TFamilyId extends string = string, TTargetId extends
    * Used by `migration new` to scaffold a fresh `migration.ts`. The
    * returned plan has no operations; its `renderTypeScript()` yields a
    * stub the user can edit.
+   *
+   * `spaceId` is stamped onto the produced plan; reconciliation flows
+   * (`db init`, `db update`) and authoring flows (`migration new`) all
+   * pass it explicitly.
    */
-  emptyMigration(context: MigrationScaffoldContext): MigrationPlanWithAuthoringSurface;
+  emptyMigration(context: MigrationScaffoldContext, spaceId: string): MigrationPlanWithAuthoringSurface;
 }
 /**
  * Migration runner interface for executing migration plans.
@@ -541,6 +691,16 @@ interface MigrationPlanner<TFamilyId extends string = string, TTargetId extends
  * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
  */
 interface MigrationRunner<TFamilyId extends string = string, TTargetId extends string = string> {
+  /**
+   * Execute a migration plan against the configured driver.
+   *
+   * The `plan` parameter is trusted input. Callers are responsible for
+   * upstream verification of the originating migration package — typically
+   * by obtaining the package via `readMigrationPackage` from
+   * `@prisma-next/migration-tools/io`, which performs hash-integrity checks
+   * at the load boundary. Runners do not re-verify the plan and assume the
+   * `(metadata, ops)` pair on disk has not been tampered with since emit.
+   */
   execute(options: {
     readonly plan: MigrationPlan;
     readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
@@ -563,6 +723,58 @@ interface MigrationRunner<TFamilyId extends string = string, TTargetId extends s
     readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
   }): Promise<MigrationRunnerResult>;
 }
+/**
+ * Per-space input for {@link MultiSpaceCapableRunner.executeAcrossSpaces}.
+ *
+ * Mirrors the single-space `MigrationRunner.execute` options, extended with a
+ * required `space` identifier. Each entry's `driver` must reference the same
+ * connection the outer transaction is opened on (typically the same value as
+ * the top-level `driver` on `executeAcrossSpaces`).
+ *
+ * Family-specific runners (e.g. the SQL family's `SqlMigrationRunner`) define
+ * a richer per-space option shape that is structurally compatible with this
+ * one — additional optional fields (e.g. SQL's `strictVerification`,
+ * `schemaName`, `callbacks`) are tolerated by the underlying runner without
+ * affecting cross-target wiring.
+ */
+interface MultiSpaceRunnerPerSpaceOptions<TFamilyId extends string = string, TTargetId extends string = string> {
+  readonly space: string;
+  readonly plan: MigrationPlan;
+  readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+  readonly destinationContract: unknown;
+  readonly policy: MigrationOperationPolicy;
+  readonly executionChecks?: MigrationRunnerExecutionChecks;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+}
+interface MultiSpaceRunnerSuccessValue {
+  readonly perSpaceResults: ReadonlyArray<{
+    readonly space: string;
+    readonly value: MigrationRunnerSuccessValue;
+  }>;
+}
+interface MultiSpaceRunnerFailure extends MigrationRunnerFailure {
+  /** Identifier of the space whose plan caused the rollback. */
+  readonly failingSpace: string;
+}
+type MultiSpaceRunnerResult = Result<MultiSpaceRunnerSuccessValue, MultiSpaceRunnerFailure>;
+/**
+ * Optional capability for runners that can apply a list of per-space plans
+ * inside a single outer transaction. A failure on any space rolls back every
+ * space's writes.
+ *
+ * The SQL family (`SqlMigrationRunner`) implements this with a true outer
+ * transaction across every space. The Mongo family implements a degenerate
+ * single-space shim (per-space is a non-goal per the extension-contract-spaces
+ * project spec — Mongo aggregates are always single-member). The capability
+ * is declared at the framework layer so CLI utilities can route through it
+ * without importing any specific family directly.
+ */
+interface MultiSpaceCapableRunner<TFamilyId extends string = string, TTargetId extends string = string> {
+  executeAcrossSpaces(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+    readonly perSpaceOptions: ReadonlyArray<MultiSpaceRunnerPerSpaceOptions<TFamilyId, TTargetId>>;
+  }): Promise<MultiSpaceRunnerResult>;
+}
 /**
  * Optional capability interface for targets that support migrations.
  * Targets that implement migrations expose this via their descriptor.
@@ -598,11 +810,12 @@ interface MigrationScaffoldContext {
   /** Absolute path to the contract.json file, if one exists. Used by targets that emit typed-contract imports. */
   readonly contractJsonPath?: string;
   /**
-   * Storage hash of the "from" contract. Targets use this to populate
-   * `describe()` on the rendered empty migration so that identity metadata
-   * is correctly populated.
+   * Storage hash of the "from" contract, or `null` for a baseline scaffold
+   * with no prior state. Targets use this to populate `describe()` on the
+   * rendered empty migration so that identity metadata is correctly
+   * populated.
    */
-  readonly fromHash: string;
+  readonly fromHash: string | null;
   /**
    * Storage hash of the "to" contract. Same purpose as `fromHash` — threaded
    * through so the rendered class's `describe()` declares the correct
@@ -611,7 +824,30 @@ interface MigrationScaffoldContext {
   readonly toHash: string;
 }
 //#endregion
-//#region src/control-schema-view.d.ts
+//#region src/control/control-operation-preview.d.ts
+/**
+ * Family-agnostic textual preview of a migration plan, used by the CLI to
+ * render a "DDL preview" section for `db init` / `db update` / `migration plan`
+ * / `migration show`. Each statement carries a free-form `language` tag so
+ * formatters can suffix `;` for SQL but render Mongo shell lines verbatim.
+ *
+ * Producers are family-specific: SQL emits `language: 'sql'` (existing DDL
+ * extraction); Mongo emits `language: 'mongodb-shell'` via the
+ * `MongoDdlCommandFormatter` visitor.
+ *
+ * The capability `OperationPreviewCapable` (declared in
+ * `./control-capabilities`) is how a family announces it can produce these.
+ */
+interface OperationPreviewStatement {
+  readonly text: string;
+  /** Dialect identifier, e.g. `'sql'`, `'mongodb-shell'`. Free-form by design (OQ-3). */
+  readonly language: string;
+}
+interface OperationPreview {
+  readonly statements: readonly OperationPreviewStatement[];
+}
+//#endregion
+//#region src/control/control-schema-view.d.ts
 /**
  * Core schema view types for family-agnostic schema visualization.
  *
@@ -649,7 +885,7 @@ interface CoreSchemaView {
   readonly root: SchemaTreeNode;
 }
 //#endregion
-//#region src/control-capabilities.d.ts
+//#region src/control/control-capabilities.d.ts
 interface MigratableTargetDescriptor<TFamilyId extends string, TTargetId extends string, TFamilyInstance extends ControlFamilyInstance<TFamilyId, unknown> = ControlFamilyInstance<TFamilyId, unknown>> extends ControlTargetDescriptor<TFamilyId, TTargetId> {
   readonly migrations: TargetMigrationsCapability<TFamilyId, TTargetId, TFamilyInstance>;
 }
@@ -658,6 +894,113 @@ interface SchemaViewCapable<TSchemaIR = unknown> {
   toSchemaView(schema: TSchemaIR): CoreSchemaView;
 }
 declare function hasSchemaView<TFamilyId extends string, TSchemaIR>(instance: ControlFamilyInstance<TFamilyId, TSchemaIR>): instance is ControlFamilyInstance<TFamilyId, TSchemaIR> & SchemaViewCapable<TSchemaIR>;
+/**
+ * Capability declaring that a family can infer a PSL contract AST from its
+ * opaque introspected schema IR. Consumed by `prisma-next contract infer`.
+ */
+interface PslContractInferCapable<TSchemaIR = unknown> {
+  inferPslContract(schemaIR: TSchemaIR): PslDocumentAst;
+}
+declare function hasPslContractInfer<TFamilyId extends string, TSchemaIR>(instance: ControlFamilyInstance<TFamilyId, TSchemaIR>): instance is ControlFamilyInstance<TFamilyId, TSchemaIR> & PslContractInferCapable<TSchemaIR>;
+/**
+ * Capability declaring that a family can render a textual preview of migration
+ * operations for the CLI's "DDL preview" output. SQL families emit
+ * `language: 'sql'` statements; Mongo families emit `language: 'mongodb-shell'`.
+ */
+interface OperationPreviewCapable {
+  toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview;
+}
+declare function hasOperationPreview<TFamilyId extends string, TSchemaIR>(instance: ControlFamilyInstance<TFamilyId, TSchemaIR>): instance is ControlFamilyInstance<TFamilyId, TSchemaIR> & OperationPreviewCapable;
+/**
+ * Capability declaring that a runner can apply per-space plans inside a
+ * single outer transaction. The SQL family (`SqlMigrationRunner`) implements
+ * this with a true outer transaction. The Mongo family implements a
+ * degenerate single-space shim (Mongo per-space is a non-goal per the
+ * extension-contract-spaces project spec — TML-2397).
+ *
+ * The CLI's shared `applyAggregate` primitive uses this guard so that
+ * `db init` / `db update` / `migration apply` route uniformly through one
+ * dispatch path regardless of family.
+ */
+declare function hasMultiSpaceRunner<TFamilyId extends string, TTargetId extends string>(runner: MigrationRunner<TFamilyId, TTargetId>): runner is MigrationRunner<TFamilyId, TTargetId> & MultiSpaceCapableRunner<TFamilyId, TTargetId>;
+//#endregion
+//#region src/control/control-spaces.d.ts
+/**
+ * Canonical control-plane identifiers for contract spaces.
+ *
+ * A contract space is the disjoint `(contract.json, migration-graph)` unit
+ * the per-space planner / runner / verifier (project: extension contract
+ * spaces, TML-2397) operates on. The application owns one well-known
+ * space — the value below — and each loaded extension that contributes
+ * schema owns a uniquely-named space.
+ *
+ * Lives in `framework-components/control` so every layer that has to
+ * reason about space identity (the migration tooling, the SQL runtime's
+ * marker reader, target-side statement builders, target-side adapters)
+ * can import a single value rather than duplicating the literal. Raw
+ * `'app'` string literals in framework / target / runtime / adapter
+ * source code are forbidden and policed by
+ * `scripts/lint-app-space-id.mjs` (wired into `pnpm lint:deps`).
+ *
+ * @see specs/framework-mechanism.spec.md § 3 — Layout convention (γ).
+ */
+declare const APP_SPACE_ID: "app";
+/**
+ * Head ref for a contract space — the `(hash, invariants)` tuple
+ * a runner targets when applying that space's migration graph. Identical
+ * in shape to the on-disk `migrations/<space-id>/refs/head.json` the
+ * framework writes per loaded extension, and to the app-space
+ * `<projectRoot>/refs/head.json`. Family-agnostic: SQL, Mongo, and any
+ * future family share the same head-ref shape.
+ *
+ * @see specs/framework-mechanism.spec.md § 1.
+ */
+interface ContractSpaceHeadRef {
+  readonly hash: string;
+  readonly invariants: readonly string[];
+}
+/**
+ * Canonical structural shape of a migration package — the unit a planner
+ * produces and a runner consumes: a directory name, the ADR 197 metadata
+ * envelope (which carries the `toContract` snapshot), and the operation
+ * list.
+ *
+ * In-memory by default. Readers in `@prisma-next/migration-tools`
+ * (`readMigrationPackage` / `readMigrationsDir`) return the augmented
+ * {@link import('@prisma-next/migration-tools/package').OnDiskMigrationPackage}
+ * variant which adds `dirPath`; everything else operates against the
+ * canonical shape so the same value flows through pre-emission
+ * authoring, on-disk loading, and runner execution without conversion.
+ *
+ * @see specs/framework-mechanism.spec.md § 1.
+ */
+interface MigrationPackage {
+  readonly dirName: string;
+  readonly metadata: MigrationMetadata;
+  readonly ops: readonly MigrationPlanOperation[];
+}
+/**
+ * Canonical structural shape of a contract space — one disjoint
+ * `(contractJson, migration-graph)` unit the per-space planner / runner
+ * / verifier operates on. The application owns one well-known space
+ * ({@link APP_SPACE_ID}); each loaded extension that contributes schema
+ * owns a uniquely-named space. Whether a value is the app's space or an
+ * extension's space is a control-plane concern; the type carries no
+ * such distinction.
+ *
+ * Generic over the contract so each family pins a typed contract value
+ * at consumption time. The SQL family specialises to
+ * `ContractSpace<Contract<SqlStorage>>` at the descriptor surface;
+ * Mongo's symmetrical `ContractSpace<Contract<MongoStorage>>` will land
+ * with that family.
+ *
+ * @see specs/framework-mechanism.spec.md § 1.
+ */
+interface ContractSpace<TContract extends Contract = Contract> {
+  readonly contractJson: TContract;
+  readonly migrations: readonly MigrationPackage[];
+  readonly headRef: ContractSpaceHeadRef;
+}
 //#endregion
-export { type AssembledAuthoringContributions, type BaseSchemaIssue, type ControlAdapterDescriptor, type ControlAdapterInstance, type ControlDriverDescriptor, type ControlDriverInstance, type ControlExtensionDescriptor, type ControlExtensionInstance, type ControlFamilyDescriptor, type ControlFamilyInstance, type ControlMutationDefaultEntry, type ControlMutationDefaultRegistry, type ControlMutationDefaults, type ControlStack, type ControlTargetDescriptor, type ControlTargetInstance, type CoreSchemaView, type CreateControlStackInput, type DataTransformOperation, type DefaultFunctionLoweringContext, type DefaultFunctionLoweringHandler, type DefaultFunctionRegistry, type DefaultFunctionRegistryEntry, type EmitContractResult, type EnumValuesChangedIssue, type IntrospectSchemaResult, type LoweredDefaultResult, type LoweredDefaultValue, type MigratableTargetDescriptor, type MigrationOperationClass, type MigrationOperationPolicy, type MigrationPlan, type MigrationPlanOperation, type MigrationPlanWithAuthoringSurface, type MigrationPlanner, type MigrationPlannerConflict, type MigrationPlannerFailureResult, type MigrationPlannerResult, type MigrationPlannerSuccessResult, type MigrationRunner, type MigrationRunnerExecutionChecks, type MigrationRunnerFailure, type MigrationRunnerResult, type MigrationRunnerSuccessValue, type MigrationScaffoldContext, type MutationDefaultGeneratorDescriptor, type OpFactoryCall, type OperationContext, type ParsedDefaultFunctionCall, type SchemaIssue, type SchemaNodeKind, SchemaTreeNode, type SchemaTreeNodeOptions, type SchemaTreeVisitor, type SchemaVerificationNode, type SchemaViewCapable, type SerializedQueryPlan, type SignDatabaseResult, type SourceDiagnostic, type SourceSpan, type TargetMigrationsCapability, VERIFY_CODE_HASH_MISMATCH, VERIFY_CODE_MARKER_MISSING, VERIFY_CODE_SCHEMA_FAILURE, VERIFY_CODE_TARGET_MISMATCH, type VerifyDatabaseResult, type VerifyDatabaseSchemaResult, assembleAuthoringContributions, assembleControlMutationDefaults, assembleScalarTypeDescriptors, assertUniqueCodecOwner, createControlStack, extractCodecLookup, extractCodecTypeImports, extractComponentIds, extractOperationTypeImports, extractQueryOperationTypeImports, hasMigrations, hasSchemaView };
+export { APP_SPACE_ID, type AssembledAuthoringContributions, type BaseSchemaIssue, type ContractSpace, type ContractSpaceHeadRef, type ControlAdapterDescriptor, type ControlAdapterInstance, type ControlDriverDescriptor, type ControlDriverInstance, type ControlExtensionDescriptor, type ControlExtensionInstance, type ControlFamilyDescriptor, type ControlFamilyInstance, type ControlMutationDefaultEntry, type ControlMutationDefaultRegistry, type ControlMutationDefaults, type ControlStack, type ControlTargetDescriptor, type ControlTargetInstance, type CoreSchemaView, type CreateControlStackInput, type DefaultFunctionLoweringContext, type DefaultFunctionLoweringHandler, type DefaultFunctionRegistry, type DefaultFunctionRegistryEntry, type EmitContractResult, type EnumValuesChangedIssue, type ImportRequirement, type IntrospectSchemaResult, type LoweredDefaultResult, type LoweredDefaultValue, type MigratableTargetDescriptor, type MigrationHints, type MigrationMetadata, type MigrationOperationClass, type MigrationOperationPolicy, type MigrationPackage, type MigrationPlan, type MigrationPlanOperation, type MigrationPlanWithAuthoringSurface, type MigrationPlanner, type MigrationPlannerConflict, type MigrationPlannerFailureResult, type MigrationPlannerResult, type MigrationPlannerSuccessResult, type MigrationRunner, type MigrationRunnerExecutionChecks, type MigrationRunnerFailure, type MigrationRunnerResult, type MigrationRunnerSuccessValue, type MigrationScaffoldContext, type MultiSpaceCapableRunner, type MultiSpaceRunnerFailure, type MultiSpaceRunnerPerSpaceOptions, type MultiSpaceRunnerResult, type MultiSpaceRunnerSuccessValue, type MutationDefaultGeneratorDescriptor, type OpFactoryCall, type OperationContext, type OperationPreview, type OperationPreviewCapable, type OperationPreviewStatement, type ParsedDefaultFunctionCall, type PslContractInferCapable, type SchemaIssue, type SchemaNodeKind, SchemaTreeNode, type SchemaTreeNodeOptions, type SchemaTreeVisitor, type SchemaVerificationNode, type SchemaViewCapable, type SerializedQueryPlan, type SignDatabaseResult, type SourceDiagnostic, type SourceSpan, type TargetMigrationsCapability, VERIFY_CODE_HASH_MISMATCH, VERIFY_CODE_MARKER_MISSING, VERIFY_CODE_SCHEMA_FAILURE, VERIFY_CODE_TARGET_MISMATCH, type VerifyDatabaseResult, type VerifyDatabaseSchemaResult, assembleAuthoringContributions, assembleControlMutationDefaults, assembleScalarTypeDescriptors, assertUniqueCodecOwner, createControlStack, extractCodecLookup, extractCodecTypeImports, extractComponentIds, extractQueryOperationTypeImports, hasMigrations, hasMultiSpaceRunner, hasOperationPreview, hasPslContractInfer, hasSchemaView };
 //# sourceMappingURL=control.d.mts.map