@prisma-next/cli 0.5.0-dev.7 → 0.5.0-dev.71

package/src/control-api/operations/db-verify.ts

@@ -0,0 +1,342 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type {
+  ControlDriverInstance,
+  ControlExtensionDescriptor,
+  ControlFamilyInstance,
+  VerifyDatabaseSchemaResult,
+} from '@prisma-next/framework-components/control';
+import {
+  type AggregateVerifierOutput,
+  type ContractSpaceMember,
+  verifyAggregate,
+} from '@prisma-next/migration-tools/aggregate';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { CliStructuredError } from '../../utils/cli-errors';
+import {
+  type BuildAggregateInputs,
+  buildContractSpaceAggregate,
+} from '../../utils/contract-space-aggregate-loader';
+import type { OnControlProgress } from '../types';
+
+/**
+ * Span IDs emitted via `onProgress` during the aggregate verify flow.
+ * Mirrors the span identifiers used by the legacy precheck / marker-check
+ * helpers so structured-output renderers and progress tests keep working.
+ */
+const SPAN_IDS = {
+  introspect: 'introspect',
+  verify: 'verify',
+} as const;
+
+/**
+ * Inputs for the aggregate `db verify` operation.
+ *
+ * Loader → verifier pipeline. The loader (sole descriptor-import
+ * boundary) builds a {@link import('@prisma-next/migration-tools/aggregate').ContractSpaceAggregate};
+ * the aggregate verifier bundles `markerCheck` + per-space pre-projected
+ * `schemaCheck`. `mode: 'strict' | 'lenient'` maps directly to the user
+ * facing `--strict` flag.
+ */
+export interface ExecuteDbVerifyOptions<TFamilyId extends string, TTargetId extends string> {
+  readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+  readonly familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
+  readonly contract: Contract;
+  readonly migrationsDir: string;
+  readonly targetId: TTargetId;
+  readonly extensionPacks: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  readonly mode: 'strict' | 'lenient';
+  readonly skipSchema: boolean;
+  readonly skipMarker: boolean;
+  readonly onProgress?: OnControlProgress;
+}
+
+/**
+ * Result of the aggregate verify operation.
+ *
+ * Marker-check failures are surfaced as a {@link CliStructuredError}
+ * (same envelope code `5002` the legacy `runContractSpaceVerifierMarkerCheck`
+ * emitted, so downstream tooling and integration tests assert on the
+ * same shape).
+ *
+ * On success, the per-space schema results are returned for the CLI to
+ * render. When `skipSchema` is true (`--marker-only`), the schema map
+ * is empty.
+ */
+export interface ExecuteDbVerifySuccess {
+  readonly schemaResults: ReadonlyMap<string, VerifyDatabaseSchemaResult>;
+  readonly memberOrder: readonly string[];
+  readonly appSpaceId: string;
+}
+
+export type ExecuteDbVerifyResult = Result<ExecuteDbVerifySuccess, CliStructuredError>;
+
+/**
+ * Loader → verifier pipeline shared by `db verify` modes (`full`,
+ * `marker-only`, `schema-only`).
+ *
+ * 1. **Load**: build a {@link import('@prisma-next/migration-tools/aggregate').ContractSpaceAggregate}
+ *    from descriptors + on-disk on-disk artefacts. Layout / drift /
+ *    integrity / disjointness violations short-circuit with a
+ *    structured CLI error.
+ * 2. **Read DB state**: marker rows + (when `skipSchema` is `false`)
+ *    schema introspection.
+ * 3. **Verify**: {@link verifyAggregate} returns per-space
+ *    `markerCheck` + per-space pre-projected `schemaCheck` (closes F23).
+ *    Marker mismatches map to `CliStructuredError` (code `5002`) so
+ *    callers (CLI command) can render and exit. Schema results are
+ *    returned to the caller verbatim.
+ */
+export async function executeDbVerify<TFamilyId extends string, TTargetId extends string>(
+  options: ExecuteDbVerifyOptions<TFamilyId, TTargetId>,
+): Promise<ExecuteDbVerifyResult> {
+  const { driver, familyInstance, onProgress, skipSchema, skipMarker } = options;
+  const loaded = await buildContractSpaceAggregate(buildLoadInputs(options));
+  if (!loaded.ok) return notOk(loaded.failure);
+  const aggregate = loaded.value;
+
+  const markersBySpaceId = await familyInstance.readAllMarkers({ driver });
+  const schemaIntrospection = skipSchema
+    ? null
+    : await runIntrospection({ driver, familyInstance, onProgress });
+
+  emitVerifySpan(onProgress, 'spanStart');
+  const verifyResult = verifyAggregate({
+    aggregate,
+    markersBySpaceId,
+    schemaIntrospection,
+    mode: options.mode,
+    verifySchemaForMember: createPerMemberVerifier(options),
+  });
+  return finaliseVerifyResult({ verifyResult, aggregate, skipMarker, onProgress });
+}
+
+function buildLoadInputs<TFamilyId extends string, TTargetId extends string>(
+  options: ExecuteDbVerifyOptions<TFamilyId, TTargetId>,
+): BuildAggregateInputs<TFamilyId, TTargetId> {
+  return {
+    targetId: options.targetId,
+    migrationsDir: options.migrationsDir,
+    appContract: options.contract,
+    extensionPacks: options.extensionPacks,
+    validateContract: (json) => options.familyInstance.validateContract(json),
+  };
+}
+
+async function runIntrospection<TFamilyId extends string, TTargetId extends string>(args: {
+  driver: ControlDriverInstance<TFamilyId, TTargetId>;
+  familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
+  onProgress: OnControlProgress | undefined;
+}): Promise<unknown> {
+  const { driver, familyInstance, onProgress } = args;
+  onProgress?.({
+    action: 'dbVerify',
+    kind: 'spanStart',
+    spanId: SPAN_IDS.introspect,
+    label: 'Introspecting database schema',
+  });
+  try {
+    const result = await familyInstance.introspect({ driver });
+    onProgress?.({
+      action: 'dbVerify',
+      kind: 'spanEnd',
+      spanId: SPAN_IDS.introspect,
+      outcome: 'ok',
+    });
+    return result;
+  } catch (error) {
+    onProgress?.({
+      action: 'dbVerify',
+      kind: 'spanEnd',
+      spanId: SPAN_IDS.introspect,
+      outcome: 'error',
+    });
+    throw error;
+  }
+}
+
+/**
+ * Build the per-member schema callback handed to the aggregate verifier.
+ * When `skipSchema` is true the callback short-circuits with a synthetic
+ * `ok` result so the verifier still runs the (cheap) schemaCheck loop
+ * without invoking the family's verification path.
+ */
+function createPerMemberVerifier<TFamilyId extends string, TTargetId extends string>(
+  options: ExecuteDbVerifyOptions<TFamilyId, TTargetId>,
+): (
+  projectedSchema: unknown,
+  member: ContractSpaceMember,
+  verifyMode: 'strict' | 'lenient',
+) => VerifyDatabaseSchemaResult {
+  const { skipSchema, familyInstance, frameworkComponents } = options;
+  return (projectedSchema, member, verifyMode) => {
+    if (skipSchema) return buildSkippedSchemaResult(member);
+    return familyInstance.schemaVerifyAgainstSchema({
+      contract: member.contract,
+      // The family's `TSchemaIR` is opaque to migration-tools; the
+      // aggregate verifier passes through whatever we hand it. The
+      // family expects its own IR shape on the way back.
+      schema: projectedSchema as never,
+      strict: verifyMode === 'strict',
+      frameworkComponents,
+    });
+  };
+}
+
+function emitVerifySpan(
+  onProgress: OnControlProgress | undefined,
+  kind: 'spanStart' | 'spanEndOk' | 'spanEndError',
+): void {
+  if (kind === 'spanStart') {
+    onProgress?.({
+      action: 'dbVerify',
+      kind: 'spanStart',
+      spanId: SPAN_IDS.verify,
+      label: 'Verifying contract spaces',
+    });
+    return;
+  }
+  onProgress?.({
+    action: 'dbVerify',
+    kind: 'spanEnd',
+    spanId: SPAN_IDS.verify,
+    outcome: kind === 'spanEndOk' ? 'ok' : 'error',
+  });
+}
+
+/**
+ * Map an {@link AggregateVerifierOutput} to the operation's
+ * {@link ExecuteDbVerifyResult}, applying the `skipMarker` policy used
+ * by the CLI's `--schema-only` mode.
+ */
+function finaliseVerifyResult(args: {
+  verifyResult: AggregateVerifierOutput<VerifyDatabaseSchemaResult>;
+  aggregate: {
+    readonly app: { readonly spaceId: string };
+    readonly extensions: ReadonlyArray<{ readonly spaceId: string }>;
+  };
+  skipMarker: boolean;
+  onProgress: OnControlProgress | undefined;
+}): ExecuteDbVerifyResult {
+  const { verifyResult, aggregate, skipMarker, onProgress } = args;
+  if (!verifyResult.ok) {
+    emitVerifySpan(onProgress, 'spanEndError');
+    return notOk(
+      new CliStructuredError('5002', 'Aggregate verifier introspection failed', {
+        domain: 'MIG',
+        why: verifyResult.failure.detail,
+        fix: 'Check database connectivity and the introspection tooling.',
+        docsUrl: 'https://pris.ly/contract-spaces',
+      }),
+    );
+  }
+  const markerError = skipMarker
+    ? null
+    : mapMarkerCheckFailures(aggregate.app.spaceId, verifyResult.value.markerCheck);
+  if (markerError !== null) {
+    emitVerifySpan(onProgress, 'spanEndError');
+    return notOk(markerError);
+  }
+  emitVerifySpan(onProgress, 'spanEndOk');
+  return ok({
+    schemaResults: verifyResult.value.schemaCheck.perSpace,
+    memberOrder: [aggregate.app.spaceId, ...aggregate.extensions.map((e) => e.spaceId)],
+    appSpaceId: aggregate.app.spaceId,
+  });
+}
+
+function buildSkippedSchemaResult(member: ContractSpaceMember): VerifyDatabaseSchemaResult {
+  const profileHash = (member.contract as { profileHash?: string }).profileHash;
+  return {
+    ok: true,
+    summary: 'Schema verification skipped',
+    contract: {
+      storageHash: member.headRef.hash,
+      ...(profileHash ? { profileHash } : {}),
+    },
+    target: { expected: member.contract.target },
+    schema: {
+      issues: [],
+      root: {
+        status: 'pass',
+        kind: 'skipped',
+        name: member.spaceId,
+        contractPath: '',
+        code: 'SKIPPED',
+        message: 'Schema verification skipped',
+        expected: undefined,
+        actual: undefined,
+        children: [],
+      },
+      counts: { pass: 0, warn: 0, fail: 0, totalNodes: 0 },
+    },
+    timings: { total: 0 },
+  };
+}
+
+/**
+ * Translate per-space marker check failures and orphan markers into a
+ * single CLI structured error envelope. Preserves the legacy code
+ * `5002` (was emitted by `runContractSpaceVerifierMarkerCheck`).
+ */
+function mapMarkerCheckFailures(
+  appSpaceId: string,
+  section: {
+    readonly perSpace: ReadonlyMap<
+      string,
+      | { readonly kind: 'ok' }
+      | { readonly kind: 'absent' }
+      | { readonly kind: 'hashMismatch'; readonly markerHash: string; readonly expected: string }
+      | { readonly kind: 'missingInvariants'; readonly missing: readonly string[] }
+    >;
+    readonly orphanMarkers: readonly { readonly spaceId: string; readonly row: unknown }[];
+  },
+): CliStructuredError | null {
+  const violations: Array<{
+    kind: string;
+    spaceId: string;
+    remediation: string;
+  }> = [];
+  for (const [spaceId, result] of section.perSpace) {
+    if (result.kind === 'ok' || result.kind === 'absent') continue;
+    if (result.kind === 'hashMismatch') {
+      violations.push({
+        kind: 'hashMismatch',
+        spaceId,
+        remediation:
+          spaceId === appSpaceId
+            ? 'Run `prisma-next db update` to advance the marker, or roll the database back to the recorded hash.'
+            : `Apply on-disk migrations under \`migrations/${spaceId}/\` to advance the marker, or remove the conflicting marker row.`,
+      });
+      continue;
+    }
+    if (result.kind === 'missingInvariants') {
+      violations.push({
+        kind: 'invariantsMismatch',
+        spaceId,
+        remediation: `Re-apply the migrations under \`migrations/${spaceId}/\` so the marker carries invariants: ${result.missing.join(', ')}.`,
+      });
+    }
+  }
+  for (const orphan of section.orphanMarkers) {
+    violations.push({
+      kind: 'orphanMarker',
+      spaceId: orphan.spaceId,
+      remediation: `Add the corresponding extension to \`extensionPacks\` in \`prisma-next.config.ts\`, or delete the orphan marker row for "${orphan.spaceId}".`,
+    });
+  }
+  if (violations.length === 0) return null;
+  const lines = violations.map((v) => `- [${v.kind}] ${v.spaceId}: ${v.remediation}`);
+  const summary =
+    violations.length === 1
+      ? 'Contract-space verifier found a violation'
+      : `Contract-space verifier found violations (${violations.length})`;
+  return new CliStructuredError('5002', summary, {
+    domain: 'MIG',
+    why: `The on-disk \`migrations/\` directory, the \`extensionPacks\` declaration, and the live database marker rows are not in agreement.\n${lines.join('\n')}`,
+    fix: violations[0]?.remediation ?? 'Review and reconcile the violations listed above.',
+    docsUrl: 'https://pris.ly/contract-spaces',
+    meta: { violations },
+  });
+}

package/src/control-api/operations/migration-apply.ts

@@ -5,6 +5,7 @@ import type {
   MigrationRunnerResult,
   TargetMigrationsCapability,
 } from '@prisma-next/framework-components/control';
+import { APP_SPACE_ID } from '@prisma-next/framework-components/control';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import { notOk, ok } from '@prisma-next/utils/result';
 import type {
@@ -30,6 +31,21 @@ export interface ExecuteMigrationApplyOptions<TFamilyId extends string, TTargetI
   readonly onProgress?: OnControlProgress;
 }
 
+/**
+ * Apply a sequence of migration packages against the configured driver.
+ *
+ * Validates the path's continuity (origin → ... → destination, no gaps),
+ * then drives the family/target's migration runner over each package's
+ * operations in order, surfacing per-migration progress through `onProgress`.
+ *
+ * The `pendingMigrations` parameter is trusted input. Callers are responsible
+ * for upstream verification of the originating migration packages — typically
+ * by loading them via `readMigrationPackage` from
+ * `@prisma-next/migration-tools/io`, which performs hash-integrity checks at
+ * the load boundary. This operation does not re-verify the packages and
+ * assumes the `(metadata, ops)` pairs on disk have not been tampered with
+ * since emit.
+ */
 export async function executeMigrationApply<TFamilyId extends string, TTargetId extends string>(
   options: ExecuteMigrationApplyOptions<TFamilyId, TTargetId>,
 ): Promise<MigrationApplyResult> {
@@ -64,15 +80,19 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
 
   const firstMigration = pendingMigrations[0]!;
   const lastMigration = pendingMigrations[pendingMigrations.length - 1]!;
-  if (firstMigration.from !== originHash || lastMigration.to !== destinationHash) {
+  // Manifest `from` is `string | null` (null = baseline). The live-marker
+  // layer encodes "no prior state" as EMPTY_CONTRACT_HASH; bridge here so the
+  // string comparisons below work uniformly.
+  const firstFromMarker = firstMigration.from ?? EMPTY_CONTRACT_HASH;
+  if (firstFromMarker !== originHash || lastMigration.to !== destinationHash) {
     return notOk({
       code: 'MIGRATION_PATH_NOT_FOUND' as const,
       summary: 'Migration apply path does not match requested origin and destination',
-      why: `Path resolved as ${firstMigration.from} -> ${lastMigration.to}, but requested ${originHash} -> ${destinationHash}`,
+      why: `Path resolved as ${firstFromMarker} -> ${lastMigration.to}, but requested ${originHash} -> ${destinationHash}`,
       meta: {
         originHash,
         destinationHash,
-        pathOrigin: firstMigration.from,
+        pathOrigin: firstFromMarker,
         pathDestination: lastMigration.to,
       },
     });
@@ -81,18 +101,19 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
   for (let i = 1; i < pendingMigrations.length; i++) {
     const previous = pendingMigrations[i - 1]!;
     const current = pendingMigrations[i]!;
-    if (previous.to !== current.from) {
+    const currentFromMarker = current.from ?? EMPTY_CONTRACT_HASH;
+    if (previous.to !== currentFromMarker) {
       return notOk({
         code: 'MIGRATION_PATH_NOT_FOUND' as const,
         summary: 'Migration apply path contains a discontinuity between adjacent migrations',
-        why: `Migration "${previous.dirName}" ends at ${previous.to}, but next migration "${current.dirName}" starts at ${current.from}`,
+        why: `Migration "${previous.dirName}" ends at ${previous.to}, but next migration "${current.dirName}" starts at ${currentFromMarker}`,
         meta: {
           originHash,
           destinationHash,
           previousDirName: previous.dirName,
           previousTo: previous.to,
           currentDirName: current.dirName,
-          currentFrom: current.from,
+          currentFrom: currentFromMarker,
           discontinuityIndex: i,
         },
       });
@@ -120,13 +141,20 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
       allowedOperationClasses: ['additive', 'widening', 'destructive', 'data'] as const,
     };
 
-    // EMPTY_CONTRACT_HASH means "no prior state" — the runner expects origin: null
-    // for a fresh database (no marker present).
+    // Manifest `from === null` means "no prior state" — the runner expects
+    // `origin: null` for a fresh database (no marker present).
+    //
+    // M3 will thread the package's owning space id through `MigrationApplyStep`
+    // and use it here. Until then, all on-disk migration packages live under
+    // the app's `migrations/` directory, so this path is exclusively app-scope
+    // and we pass `APP_SPACE_ID` explicitly.
     const plan = {
       targetId,
-      origin: migration.from === EMPTY_CONTRACT_HASH ? null : { storageHash: migration.from },
+      spaceId: APP_SPACE_ID,
+      origin: migration.from === null ? null : { storageHash: migration.from },
       destination: { storageHash: migration.to },
       operations,
+      providedInvariants: migration.providedInvariants,
     };
 
     const destinationContract = familyInstance.validateContract(migration.toContract);

package/src/control-api/types.ts

@@ -12,11 +12,14 @@ import type {
   CoreSchemaView,
   MigrationPlannerConflict,
   MigrationPlanOperation,
+  OperationPreview,
   SignDatabaseResult,
   VerifyDatabaseResult,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
+import type { PslDocumentAst } from '@prisma-next/framework-components/psl-ast';
 import type { Result } from '@prisma-next/utils/result';
+import type { ExecuteDbVerifyResult } from './operations/db-verify';
 
 // ============================================================================
 // Client Options
@@ -63,6 +66,7 @@ export interface ControlClientOptions {
 export type ControlActionName =
   | 'dbInit'
   | 'dbUpdate'
+  | 'dbVerify'
   | 'migrationApply'
   | 'verify'
   | 'schemaVerify'
@@ -189,6 +193,13 @@ export interface DbInitOptions {
    * The type is driver-specific (e.g., string URL for Postgres).
    */
   readonly connection?: unknown;
+  /**
+   * On-disk migrations directory. Always required — every `db init`
+   * routes through the per-space flow, which reads on-disk
+   * `refs/head.json` and extension destination contracts from this
+   * root.
+   */
+  readonly migrationsDir: string;
   /** Optional progress callback for observing operation progress */
   readonly onProgress?: OnControlProgress;
 }
@@ -219,10 +230,35 @@ export interface DbUpdateOptions {
    * or re-run with -y/--yes.
    */
   readonly acceptDataLoss?: boolean;
+  /**
+   * On-disk migrations directory. Always required — every `db update`
+   * routes through the per-space flow, which reads on-disk
+   * `refs/head.json` and extension destination contracts from this
+   * root.
+   */
+  readonly migrationsDir: string;
   /** Optional progress callback for observing operation progress */
   readonly onProgress?: OnControlProgress;
 }
 
+/**
+ * Options for the dbVerify operation.
+ *
+ * Drives the loader → aggregate-verifier pipeline. `strict` maps to
+ * `verifyAggregate({ mode: 'strict' | 'lenient' })`; `skipSchema`
+ * mirrors the `--marker-only` CLI flag and short-circuits the schema
+ * portion of the verifier.
+ */
+export interface DbVerifyOptions {
+  readonly contract: unknown;
+  readonly migrationsDir: string;
+  readonly strict: boolean;
+  readonly skipSchema: boolean;
+  readonly skipMarker: boolean;
+  readonly connection?: unknown;
+  readonly onProgress?: OnControlProgress;
+}
+
 /**
  * Options for the introspect operation.
  */
@@ -283,7 +319,14 @@ export interface DbInitSuccess {
       readonly label: string;
       readonly operationClass: string;
     }>;
-    readonly sql?: ReadonlyArray<string>;
+    /**
+     * Family-agnostic textual preview of the planned operations, e.g.
+     * `language: 'sql'` for SQL families and `language: 'mongodb-shell'`
+     * for the Mongo family. Replaces the previous `sql?: readonly string[]`
+     * field; consumers that previously read `plan.sql` should read
+     * `plan.preview?.statements.map((s) => s.text)`.
+     */
+    readonly preview?: OperationPreview;
   };
   readonly destination: {
     readonly storageHash: string;
@@ -341,7 +384,14 @@ export interface DbUpdateSuccess {
       readonly label: string;
       readonly operationClass: string;
     }>;
-    readonly sql?: ReadonlyArray<string>;
+    /**
+     * Family-agnostic textual preview of the planned operations, e.g.
+     * `language: 'sql'` for SQL families and `language: 'mongodb-shell'`
+     * for the Mongo family. Replaces the previous `sql?: readonly string[]`
+     * field; consumers that previously read `plan.sql` should read
+     * `plan.preview?.statements.map((s) => s.text)`.
+     */
+    readonly preview?: OperationPreview;
   };
   readonly destination: {
     readonly storageHash: string;
@@ -432,10 +482,18 @@ export type EmitResult = Result<EmitSuccess, EmitFailure>;
  */
 export interface MigrationApplyStep {
   readonly dirName: string;
-  readonly from: string;
+  readonly from: string | null;
   readonly to: string;
   readonly toContract: Contract;
   readonly operations: readonly MigrationPlanOperation[];
+  /**
+   * Sorted, deduplicated invariant ids from `migration.json.providedInvariants`.
+   * Verified at load time by `readMigrationPackage` (manifest copy must equal
+   * the value derived from `ops.json`). The control-api passes this through
+   * to the runner via `MigrationPlan.providedInvariants` so target runners
+   * read the canonical set instead of re-deriving from `operations`.
+   */
+  readonly providedInvariants: readonly string[];
 }
 
 /**
@@ -471,7 +529,7 @@ export interface MigrationApplyOptions {
  */
 export interface MigrationApplyAppliedEntry {
   readonly dirName: string;
-  readonly from: string;
+  readonly from: string | null;
   readonly to: string;
   readonly operationsExecuted: number;
 }
@@ -512,18 +570,31 @@ export type MigrationApplyResult = Result<MigrationApplySuccess, MigrationApplyF
 
 /**
  * Options for the standalone executeContractEmit function.
- * Used by tooling (e.g., Vite plugin) that needs to emit contracts
- * without the full ControlClient infrastructure.
+ *
+ * `executeContractEmit` is the canonical publication path for both the
+ * `prisma-next contract emit` CLI command and the `@prisma-next/vite-plugin-contract-emit`
+ * Vite plugin. Do not duplicate the load → emit → publish dance elsewhere; if a
+ * caller needs additional behavior, extend this options shape and update the
+ * single implementation rather than building a parallel publication path.
+ *
+ * Concurrent calls for the same output JSON path are serialized per-output via
+ * a FIFO queue; concurrent calls for distinct outputs run in parallel.
  */
 export interface ContractEmitOptions {
   /** Path to the prisma-next.config.ts file */
   readonly configPath: string;
-  /** Optional AbortSignal for cancellation support */
+  /** Optional AbortSignal for cancelling the in-flight emit */
   readonly signal?: AbortSignal;
+  /** Optional progress callback for observing source-resolution and emit spans */
+  readonly onProgress?: OnControlProgress;
 }
 
 /**
  * Result from the standalone executeContractEmit function.
+ *
+ * Always describes the bytes that were just published to disk. Failures throw
+ * (config / source-resolution / emit / publish) — callers do not need to
+ * branch on a result discriminator.
  */
 export interface ContractEmitResult {
   /** Hash of the storage contract (schema-level) */
@@ -539,6 +610,12 @@ export interface ContractEmitResult {
     /** Path to the emitted contract.d.ts file */
     readonly dts: string;
   };
+  /**
+   * Warning surfaced by `validateContractDeps` after a successful publication.
+   * Callers (CLI, Vite plugin) decide how to render this; the operation does
+   * not write to stderr itself. Undefined when no warning was raised.
+   */
+  readonly validationWarning?: string;
 }
 
 // ============================================================================
@@ -634,6 +711,21 @@ export interface ControlClient {
    */
   dbUpdate(options: DbUpdateOptions): Promise<DbUpdateResult>;
 
+  /**
+   * Verifies the database against every contract space (app + extensions).
+   *
+   * Loader → aggregate-verifier pipeline:
+   * - The loader catches layout / drift / disjointness violations.
+   * - The aggregate verifier surfaces marker-vs-on-disk drift and orphan
+   *   markers, and (unless `skipSchema` is true) per-space schema
+   *   verification with pre-projection (closes F23).
+   *
+   * @returns Result pattern: per-space schema results on success;
+   *          structured CLI error on marker / loader failure.
+   * @throws If not connected or infrastructure failure
+   */
+  dbVerify(options: DbVerifyOptions): Promise<ExecuteDbVerifyResult>;
+
   /**
    * Reads the contract marker from the database.
    * Returns null if no marker exists (fresh database).
@@ -642,6 +734,13 @@ export interface ControlClient {
    */
   readMarker(): Promise<ContractMarkerRecord | null>;
 
+  /**
+   * Reads every marker row (one per contract space). Used by the
+   * per-space verifier to detect orphan marker rows and marker-vs-on-disk
+   * drift after a database connection has been established.
+   */
+  readAllMarkers(): Promise<ReadonlyMap<string, ContractMarkerRecord>>;
+
   /**
    * Applies pre-planned on-disk migrations to the database.
    * Each migration runs in its own transaction with full execution checks.
@@ -672,6 +771,25 @@ export interface ControlClient {
    */
   toSchemaView(schemaIR: unknown): CoreSchemaView | undefined;
 
+  /**
+   * Infers a PSL contract AST from an introspected schema IR.
+   * Delegates to the family instance's inferPslContract method.
+   *
+   * @param schemaIR - The schema IR from introspect()
+   * @returns PslDocumentAst if the family supports the capability, undefined otherwise
+   */
+  inferPslContract(schemaIR: unknown): PslDocumentAst | undefined;
+
+  /**
+   * Renders a textual preview of a migration plan's operations for the CLI's
+   * "DDL preview" output. Delegates to the family instance's
+   * `toOperationPreview` method.
+   *
+   * @param operations - The migration plan operations to render
+   * @returns OperationPreview if the family supports the capability, undefined otherwise
+   */
+  toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview | undefined;
+
   /**
    * Emits the contract to JSON and TypeScript declarations.
    * This is an offline operation that does NOT require a database connection.