@prisma-next/framework-components 0.5.0-dev.8 → 0.5.0-dev.81

package/src/{control-migration-types.ts → control/control-migration-types.ts}

@@ -10,9 +10,65 @@
  */
 
 import type { Contract } from '@prisma-next/contract/types';
+import type { ImportRequirement } from '@prisma-next/ts-render';
 import type { Result } from '@prisma-next/utils/result';
+import type { TargetBoundComponentDescriptor } from '../shared/framework-components';
 import type { ControlDriverInstance, ControlFamilyInstance } from './control-instances';
-import type { TargetBoundComponentDescriptor } from './framework-components';
+
+// ============================================================================
+// Migration Package Metadata
+// ============================================================================
+
+/**
+ * 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.
+ */
+export 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`).
+ */
+export 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;
+}
 
 // ============================================================================
 // Operation Classes and Policy
@@ -28,61 +84,23 @@ import type { TargetBoundComponentDescriptor } from './framework-components';
 export type MigrationOperationClass = 'additive' | 'widening' | 'destructive' | 'data';
 
 // ============================================================================
-// Data Transform Operation
+// Serialized Query Plan
 // ============================================================================
 
 /**
  * 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.
  */
 export 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.
- */
-export 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.
  */
@@ -105,6 +123,17 @@ export 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;
 }
 
 // ============================================================================
@@ -112,9 +141,33 @@ export interface MigrationPlanOperation {
 // ============================================================================
 
 /**
- * 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>`).
  *
- * @see ADR 195
+ * 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 — Planner IR with two renderers.
  */
 export interface OpFactoryCall {
   /** The name of the factory that would produce this call's runtime op. */
@@ -123,6 +176,26 @@ export 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[];
+  /**
+   * 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;
 }
 
 // ============================================================================
@@ -136,6 +209,16 @@ export interface OpFactoryCall {
 export 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.
@@ -151,6 +234,17 @@ export 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[];
 }
 
 /**
@@ -289,21 +383,23 @@ export interface MigrationPlanner<
     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.
@@ -312,6 +408,13 @@ export interface MigrationPlanner<
     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;
 
   /**
@@ -320,8 +423,15 @@ export interface MigrationPlanner<
    * 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;
 }
 
 /**
@@ -335,6 +445,16 @@ export 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>;
@@ -360,6 +480,73 @@ export interface MigrationRunner<
   }): Promise<MigrationRunnerResult>;
 }
 
+// ============================================================================
+// Multi-space runner protocol (extension contract spaces, TML-2397)
+// ============================================================================
+
+/**
+ * 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.
+ */
+export 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>>;
+}
+
+export interface MultiSpaceRunnerSuccessValue {
+  readonly perSpaceResults: ReadonlyArray<{
+    readonly space: string;
+    readonly value: MigrationRunnerSuccessValue;
+  }>;
+}
+
+export interface MultiSpaceRunnerFailure extends MigrationRunnerFailure {
+  /** Identifier of the space whose plan caused the rollback. */
+  readonly failingSpace: string;
+}
+
+export 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.
+ */
+export 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>;
+}
+
 // ============================================================================
 // Target Migrations Capability
 // ============================================================================
@@ -414,11 +601,12 @@ export 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

package/src/control/control-operation-preview.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+
+export interface OperationPreviewStatement {
+  readonly text: string;
+  /** Dialect identifier, e.g. `'sql'`, `'mongodb-shell'`. Free-form by design (OQ-3). */
+  readonly language: string;
+}
+
+export interface OperationPreview {
+  readonly statements: readonly OperationPreviewStatement[];
+}

package/src/control/control-spaces.ts

@@ -0,0 +1,82 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { MigrationMetadata, MigrationPlanOperation } from './control-migration-types';
+
+/**
+ * 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 (γ).
+ */
+export const APP_SPACE_ID = 'app' as const;
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export interface ContractSpace<TContract extends Contract = Contract> {
+  readonly contractJson: TContract;
+  readonly migrations: readonly MigrationPackage[];
+  readonly headRef: ContractSpaceHeadRef;
+}