(TML-2397) M2 — Contract-space framework: codec hooks, db init/update, aggregate refactor, uniform on-disk layout

.cursor/rules/doc-maintenance.mdc

@@ -9,4 +9,5 @@ alwaysApply: true
   - **User-facing packages**: keep `README.md` focused on what the package does, when to use it, and a few concrete examples. Avoid internal implementation detail unless it materially affects usage.
   - **Contributor details**: put responsibilities/dependencies/architecture diagrams/internal exports in `DEVELOPING.md` (or `CONTRIBUTING.md`) within that package, and add a short link from `README.md`.
 - Docs must not link to transient project artifacts under `projects/` (link to durable `docs/` or package READMEs instead)
+- **Source-code comments must not reference transient project artefacts.** This includes: `projects/<x>/...` paths, milestone-task IDs (e.g. `T1.7`, `T2.5.3`, `R4 design choice`), milestone-named acceptance criteria (e.g. `AM12`, `AC-13`), and prose attributions like "M2 review", "out of scope", "sub-spec § 4", "sub-spec OQ3". When a comment needs to explain *why* something is the way it is, describe the constraint or behaviour itself; do not attribute it to the transient project artefact that introduced it. After close-out, durable docs under `docs/architecture docs/` can be linked. Stable references (Linear ticket IDs like `TML-2397`, ADR numbers like `ADR 211`) are fine.
 - If you establish a new design decision, update the architecture docs in `docs/architecture docs`

examples/mongo-demo/test/manual-migration.test.ts

@@ -10,7 +10,7 @@ import { type Db, MongoClient } from 'mongodb';
 import { MongoMemoryReplSet } from 'mongodb-memory-server';
 import { resolve } from 'pathe';
 import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
-import AddPostsAuthorIndex from '../migrations/20260415_add-posts-author-index/migration';
+import AddPostsAuthorIndex from '../migrations/app/20260415_add-posts-author-index/migration';
 
 const ALL_POLICY = {
   allowedOperationClasses: ['additive', 'widening', 'destructive'] as const,
@@ -23,7 +23,10 @@ function makeFamily(): ReturnType<typeof createMongoFamilyInstance> {
   );
 }
 
-const migrationDir = resolve(import.meta.dirname, '../migrations/20260415_add-posts-author-index');
+const migrationDir = resolve(
+  import.meta.dirname,
+  '../migrations/app/20260415_add-posts-author-index',
+);
 
 describe(
   'hand-authored migration (20260415_add-posts-author-index)',

examples/prisma-next-demo/test/utils/control-client.ts

@@ -49,11 +49,22 @@ export function createPrismaNextControlClient(options: TestControlClientOptions)
 export async function initTestDatabase(options: {
   readonly connection: string;
   readonly contract: unknown;
+  /**
+   * On-disk migrations directory. The demo app does not declare any
+   * extension contract spaces, so the per-space `db init` flow runs
+   * with the n=1 (app-only) resolver list and does not actually read
+   * from this path — but `migrationsDir` is required by the API.
+   */
+  readonly migrationsDir?: string;
 }): Promise<void> {
   const client = createPrismaNextControlClient({ connection: options.connection });
 
   try {
-    const initResult = await client.dbInit({ contract: options.contract, mode: 'apply' });
+    const initResult = await client.dbInit({
+      contract: options.contract,
+      mode: 'apply',
+      migrationsDir: options.migrationsDir ?? '/tmp/__prisma-next-test-migrations',
+    });
     if (!initResult.ok) {
       throw new Error(
         `dbInit failed: ${initResult.failure.summary}\n\n${JSON.stringify(initResult.failure, null, 2)}`,

examples/retail-store/test/manual-migration.test.ts

@@ -10,7 +10,7 @@ import { type Db, MongoClient } from 'mongodb';
 import { MongoMemoryReplSet } from 'mongodb-memory-server';
 import { resolve } from 'pathe';
 import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
-import AddProductValidation from '../migrations/20260415_add-product-validation/migration';
+import AddProductValidation from '../migrations/app/20260415_add-product-validation/migration';
 
 const ALL_POLICY = {
   allowedOperationClasses: ['additive', 'widening', 'destructive'] as const,
@@ -23,7 +23,10 @@ function makeFamily(): ReturnType<typeof createMongoFamilyInstance> {
   );
 }
 
-const migrationDir = resolve(import.meta.dirname, '../migrations/20260415_add-product-validation');
+const migrationDir = resolve(
+  import.meta.dirname,
+  '../migrations/app/20260415_add-product-validation',
+);
 
 describe(
   'hand-authored migration (20260415_add-product-validation)',

packages/1-framework/1-core/framework-components/src/control/control-capabilities.ts

@@ -1,6 +1,11 @@
 import type { ControlTargetDescriptor } from './control-descriptors';
 import type { ControlFamilyInstance } from './control-instances';
-import type { MigrationPlanOperation, TargetMigrationsCapability } from './control-migration-types';
+import type {
+  MigrationPlanOperation,
+  MigrationRunner,
+  MultiSpaceCapableRunner,
+  TargetMigrationsCapability,
+} from './control-migration-types';
 import type { OperationPreview } from './control-operation-preview';
 import type { CoreSchemaView } from './control-schema-view';
 import type { PslDocumentAst } from './psl-ast';
@@ -69,3 +74,22 @@ export function hasOperationPreview<TFamilyId extends string, TSchemaIR>(
     typeof (instance as Record<string, unknown>)['toOperationPreview'] === 'function'
   );
 }
+
+/**
+ * Capability declaring that a runner can apply per-space plans inside a
+ * single outer transaction. Today's only implementer is the SQL family
+ * (`SqlMigrationRunner`); Mongo per-space is a non-goal per the project
+ * spec for extension contract spaces (TML-2397).
+ *
+ * The CLI uses this guard to route `db init` / `db update` through a
+ * per-space wiring when extensions expose a `contractSpace`, falling back
+ * to the single-space path when no multi-space capability is present.
+ */
+export function hasMultiSpaceRunner<TFamilyId extends string, TTargetId extends string>(
+  runner: MigrationRunner<TFamilyId, TTargetId>,
+): runner is MigrationRunner<TFamilyId, TTargetId> & MultiSpaceCapableRunner<TFamilyId, TTargetId> {
+  return (
+    'executeAcrossSpaces' in runner &&
+    typeof (runner as Record<string, unknown>)['executeAcrossSpaces'] === 'function'
+  );
+}

packages/1-framework/1-core/framework-components/src/control/control-instances.ts

@@ -34,6 +34,24 @@ export interface ControlFamilyInstance<TFamilyId extends string, TSchemaIR>
     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;
@@ -64,6 +82,15 @@ export interface ControlFamilyInstance<TFamilyId extends string, TSchemaIR>
     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;

packages/1-framework/1-core/framework-components/src/control/control-migration-types.ts

@@ -164,6 +164,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.
@@ -425,6 +435,71 @@ 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.
+ *
+ * Today's only implementer is the SQL family (`SqlMigrationRunner`); Mongo
+ * per-space is a non-goal per the project spec. The capability is declared
+ * at the framework layer so CLI utilities can route through it without
+ * importing the SQL 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
 // ============================================================================

packages/1-framework/1-core/framework-components/src/control/control-spaces.ts

@@ -23,7 +23,7 @@ import type { MigrationMetadata, MigrationPlanOperation } from './control-migrat
 export const APP_SPACE_ID = 'app' as const;
 
 /**
- * Pinned head ref for a contract space — the `(hash, invariants)` tuple
+ * 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

packages/1-framework/1-core/framework-components/src/exports/control.ts

@@ -6,6 +6,7 @@ export type {
 } from '../control/control-capabilities';
 export {
   hasMigrations,
+  hasMultiSpaceRunner,
   hasOperationPreview,
   hasPslContractInfer,
   hasSchemaView,
@@ -43,6 +44,11 @@ export type {
   MigrationRunnerResult,
   MigrationRunnerSuccessValue,
   MigrationScaffoldContext,
+  MultiSpaceCapableRunner,
+  MultiSpaceRunnerFailure,
+  MultiSpaceRunnerPerSpaceOptions,
+  MultiSpaceRunnerResult,
+  MultiSpaceRunnerSuccessValue,
   OpFactoryCall,
   SerializedQueryPlan,
   TargetMigrationsCapability,

packages/1-framework/1-core/framework-components/test/codec-call-context.types.test-d.ts

@@ -46,7 +46,7 @@ test('encode/decode call sites accept an explicit ctx (signal optional inside th
   void decodeWithEmptyCtx;
 });
 
-// ADR 204 walk-back constraints — pinned here so future refactors cannot reintroduce a `TRuntime` generic, a discriminator field, conditional return types, or other shape complications on the public Codec.
+// ADR 204 walk-back constraints — captured here so future refactors cannot reintroduce a `TRuntime` generic, a discriminator field, conditional return types, or other shape complications on the public Codec.
 
 test('Codec carries no `runtime` or `kind` discriminator field', () => {
   type CodecKeys = keyof Codec;

packages/1-framework/1-core/framework-components/test/codec.test.ts

@@ -110,7 +110,7 @@ test('CodecImpl.id proxies through descriptor.codecId (parameterized)', ({ expec
 });
 
 test('alias descriptor produces codec whose id reads the alias codecId', ({ expect }) => {
-  // Spec § Class hierarchy aliasing: an alias descriptor instantiates the same concrete codec class (`Int4FixtureCodec`) but passes itself as the descriptor reference. `CodecImpl.id` proxies through `this.descriptor.codecId`, so the runtime id reads the alias's id even though the codec class hardcodes `'demo/int4@1'` in its type-level `Id` parameter. This test pins that regression vector — a future change that pinned `id` to the codec class's `Id` type literal would silently break aliasing.
+  // Spec § Class hierarchy aliasing: an alias descriptor instantiates the same concrete codec class (`Int4FixtureCodec`) but passes itself as the descriptor reference. `CodecImpl.id` proxies through `this.descriptor.codecId`, so the runtime id reads the alias's id even though the codec class hardcodes `'demo/int4@1'` in its type-level `Id` parameter. This test locks that regression vector — a future change that locked `id` to the codec class's `Id` type literal would silently break aliasing.
   //
   // The alias extends `CodecDescriptorImpl<void>` directly (not `Int4FixtureDescriptor`) because `Int4FixtureDescriptor.codecId` is narrowed to the literal `'demo/int4@1'`; subclasses can't override it with a different literal under TypeScript's structural overrides.
   class AliasedInt4Descriptor extends CodecDescriptorImpl<void> {

packages/1-framework/3-tooling/cli/src/commands/db-init.ts

@@ -13,6 +13,7 @@ import {
 } from '../utils/cli-errors';
 import type { MigrationCommandOptions } from '../utils/command-helpers';
 import {
+  resolveMigrationPaths,
   sanitizeErrorMessage,
   setCommandDescriptions,
   setCommandExamples,
@@ -111,14 +112,23 @@ async function executeDbInitCommand(
   if (!ctxResult.ok) {
     return ctxResult;
   }
-  const { client, contractJson, dbConnection, onProgress, contractPathAbsolute } = ctxResult.value;
+  const { client, config, contractJson, dbConnection, onProgress, contractPathAbsolute } =
+    ctxResult.value;
+
+  // The aggregate loader (loader → planner → runner pipeline) catches
+  // layout / drift / disjointness violations on its own; the legacy
+  // per-space precheck + marker-check helpers are no longer needed at
+  // this surface. Marker-vs-on-disk drift surfaces through the planner's
+  // graph-walk strategy.
+  const { migrationsDir } = resolveMigrationPaths(options.config, config);
 
   try {
-    // Call dbInit with connection and progress callback
+    await client.connect(dbConnection);
+
     const result = await client.dbInit({
       contract: contractJson,
       mode: options.dryRun ? 'plan' : 'apply',
-      connection: dbConnection,
+      migrationsDir,
       onProgress,
     });
 

packages/1-framework/3-tooling/cli/src/commands/db-update.ts

@@ -14,6 +14,7 @@ import {
 } from '../utils/cli-errors';
 import type { MigrationCommandOptions } from '../utils/command-helpers';
 import {
+  resolveMigrationPaths,
   sanitizeErrorMessage,
   setCommandDescriptions,
   setCommandExamples,
@@ -80,14 +81,17 @@ async function executeDbUpdateCommand(
   if (!ctxResult.ok) {
     return ctxResult;
   }
-  const { client, contractJson, dbConnection, onProgress, contractPathAbsolute } = ctxResult.value;
+  const { client, config, contractJson, dbConnection, onProgress, contractPathAbsolute } =
+    ctxResult.value;
+  const { migrationsDir } = resolveMigrationPaths(options.config, config);
 
   try {
-    // Call dbUpdate with connection and progress callback
+    await client.connect(dbConnection);
+
     const result = await client.dbUpdate({
       contract: contractJson,
       mode: options.dryRun ? 'plan' : 'apply',
-      connection: dbConnection,
+      migrationsDir,
       ...(flags.yes ? { acceptDataLoss: true } : {}),
       onProgress,
     });