@prisma-next/cli 0.12.0 → 0.13.0-dev.1

package/src/commands/telemetry/index.ts

@@ -0,0 +1,107 @@
+import { userConfigPath, writeUserConfig } from '@prisma-next/cli-telemetry';
+import { Command } from 'commander';
+import {
+  addGlobalOptions,
+  setCommandDescriptions,
+  setCommandExamples,
+} from '../../utils/command-helpers';
+import { formatCommandHelp } from '../../utils/formatters/help';
+import {
+  type CommonCommandOptions,
+  parseGlobalFlags,
+  parseGlobalFlagsOrExit,
+} from '../../utils/global-flags';
+import { isCI } from '../../utils/is-ci';
+import { createTerminalUI } from '../../utils/terminal-ui';
+import { formatTelemetryStatusLines, resolveTelemetryStatus } from './status';
+
+function createTelemetryStatusCommand(): Command {
+  const command = new Command('status');
+  setCommandDescriptions(
+    command,
+    'Show whether anonymous CLI telemetry is enabled and why',
+    'Reports whether telemetry is currently enabled or disabled and the reason\n' +
+      '(default-on, stored opt-out, environment opt-out, or CI), the path to your\n' +
+      'user-level config file, and whether an installation ID has been stored.\n' +
+      'Read-only: never sends an event, never mints an ID, never writes anything.',
+  );
+  return addGlobalOptions(command).action((options: CommonCommandOptions) => {
+    const flags = parseGlobalFlagsOrExit(options);
+    const ui = createTerminalUI(flags);
+    const status = resolveTelemetryStatus({ env: process.env, inCI: isCI() });
+    if (flags.json) {
+      ui.output(JSON.stringify(status));
+    } else {
+      for (const line of formatTelemetryStatusLines(status)) {
+        ui.output(line);
+      }
+    }
+    process.exit(0);
+  });
+}
+
+function createTelemetryEnableCommand(): Command {
+  const command = new Command('enable');
+  setCommandDescriptions(
+    command,
+    'Enable anonymous CLI telemetry',
+    'Stores "enableTelemetry": true in your user-level config and mints an\n' +
+      'installation ID if one is not already stored.',
+  );
+  return addGlobalOptions(command).action((options: CommonCommandOptions) => {
+    const flags = parseGlobalFlagsOrExit(options);
+    writeUserConfig({ enableTelemetry: true });
+    const ui = createTerminalUI(flags);
+    if (flags.json) {
+      ui.output(JSON.stringify({ enableTelemetry: true, configPath: userConfigPath() }));
+    } else {
+      ui.output(`Telemetry enabled. Preference stored in ${userConfigPath()}.`);
+    }
+    process.exit(0);
+  });
+}
+
+function createTelemetryDisableCommand(): Command {
+  const command = new Command('disable');
+  setCommandDescriptions(
+    command,
+    'Disable anonymous CLI telemetry',
+    'Stores "enableTelemetry": false in your user-level config. No installation\n' +
+      'ID is minted and no event is sent.',
+  );
+  return addGlobalOptions(command).action((options: CommonCommandOptions) => {
+    const flags = parseGlobalFlagsOrExit(options);
+    writeUserConfig({ enableTelemetry: false });
+    const ui = createTerminalUI(flags);
+    if (flags.json) {
+      ui.output(JSON.stringify({ enableTelemetry: false, configPath: userConfigPath() }));
+    } else {
+      ui.output(`Telemetry disabled. Preference stored in ${userConfigPath()}.`);
+    }
+    process.exit(0);
+  });
+}
+
+export function createTelemetryCommand(): Command {
+  const command = new Command('telemetry');
+  setCommandDescriptions(
+    command,
+    'Inspect and change anonymous CLI telemetry',
+    'Show telemetry status, or enable / disable anonymous CLI usage data.\n' +
+      'Telemetry is on by default (opt-out); see https://prisma-next.dev/docs/cli/telemetry\n' +
+      'for what is collected and why.',
+  );
+  setCommandExamples(command, [
+    'prisma-next telemetry status',
+    'prisma-next telemetry disable',
+    'prisma-next telemetry enable',
+  ]);
+  command.configureHelp({
+    formatHelp: (cmd) => formatCommandHelp({ command: cmd, flags: parseGlobalFlags({}) }),
+    subcommandDescription: () => '',
+  });
+  command.addCommand(createTelemetryStatusCommand());
+  command.addCommand(createTelemetryEnableCommand());
+  command.addCommand(createTelemetryDisableCommand());
+  return command;
+}

package/src/commands/telemetry/status.ts

@@ -0,0 +1,67 @@
+import { readUserConfig, resolveGating, userConfigPath } from '@prisma-next/cli-telemetry';
+
+/**
+ * Why telemetry resolves the way it does, in the order the CLI's
+ * `resolveTelemetryGate` evaluates: CI hard-disables first, then the env
+ * opt-outs, then the stored `enableTelemetry`, then the opt-out default.
+ */
+export type TelemetryStatusReason =
+  | 'ci'
+  | 'env-opt-out'
+  | 'stored-opt-out'
+  | 'stored-opt-in'
+  | 'default-on';
+
+export interface TelemetryStatus {
+  readonly enabled: boolean;
+  readonly reason: TelemetryStatusReason;
+  readonly configPath: string;
+  readonly installationIdStored: boolean;
+}
+
+/**
+ * Resolves the same gate the runtime uses (CI check + `resolveGating`) and
+ * projects it into a user-facing status. Pure read: never mints, never
+ * writes. The `installationId` value itself is never surfaced — only its
+ * presence — so `status` discloses nothing identifying.
+ */
+export function resolveTelemetryStatus(inputs: {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly inCI: boolean;
+}): TelemetryStatus {
+  const config = readUserConfig();
+  const configPath = userConfigPath();
+  const installationIdStored =
+    typeof config.installationId === 'string' && config.installationId.length > 0;
+
+  if (inputs.inCI) {
+    return { enabled: false, reason: 'ci', configPath, installationIdStored };
+  }
+
+  const gating = resolveGating({ env: inputs.env, config });
+  if (!gating.enabled) {
+    const reason: TelemetryStatusReason =
+      gating.reason === 'env-override' ? 'env-opt-out' : 'stored-opt-out';
+    return { enabled: false, reason, configPath, installationIdStored };
+  }
+
+  const reason: TelemetryStatusReason =
+    config.enableTelemetry === true ? 'stored-opt-in' : 'default-on';
+  return { enabled: true, reason, configPath, installationIdStored };
+}
+
+const REASON_EXPLANATION: Record<TelemetryStatusReason, string> = {
+  ci: 'CI environment detected — telemetry is hard-disabled.',
+  'env-opt-out': 'an environment opt-out is set (DO_NOT_TRACK / PRISMA_NEXT_DISABLE_TELEMETRY).',
+  'stored-opt-out': '"enableTelemetry": false is stored in your config.',
+  'stored-opt-in': '"enableTelemetry": true is stored in your config.',
+  'default-on': 'no explicit choice is stored, so the opt-out default applies.',
+};
+
+export function formatTelemetryStatusLines(status: TelemetryStatus): string[] {
+  return [
+    `Telemetry is ${status.enabled ? 'enabled' : 'disabled'}: ${REASON_EXPLANATION[status.reason]}`,
+    `Config file: ${status.configPath}`,
+    `Installation ID: ${status.installationIdStored ? 'stored' : 'not stored'}`,
+  ];
+}

package/src/control-api/client.ts

@@ -1,7 +1,13 @@
-import type { Contract, ContractMarkerRecord } from '@prisma-next/contract/types';
+import type {
+  Contract,
+  ContractMarkerRecord,
+  LedgerEntryRecord,
+} from '@prisma-next/contract/types';
 import { emit as emitContractArtifacts } from '@prisma-next/emitter';
+import type { AuthoringPslBlockDescriptorNamespace } from '@prisma-next/framework-components/authoring';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
+  ControlAdapterInstance,
   ControlDriverInstance,
   ControlFamilyInstance,
   ControlStack,
@@ -21,15 +27,17 @@ import {
   hasSchemaView,
 } from '@prisma-next/framework-components/control';
 import type { PslDocumentAst } from '@prisma-next/framework-components/psl-ast';
+import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok } from '@prisma-next/utils/result';
+import { toExtensionInputs } from '../utils/extension-pack-inputs';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import { enrichContract } from './contract-enrichment';
 import { ContractValidationError } from './errors';
 import { executeDbInit } from './operations/db-init';
 import { executeDbUpdate } from './operations/db-update';
 import { type ExecuteDbVerifyResult, executeDbVerify } from './operations/db-verify';
-import { executeMigrationApply } from './operations/migration-apply';
+import { executeMigrate } from './operations/migrate';
 
 import type {
   ControlActionName,
@@ -43,8 +51,8 @@ import type {
   EmitOptions,
   EmitResult,
   IntrospectOptions,
-  MigrationApplyOptions,
-  MigrationApplyResult,
+  MigrateOptions,
+  MigrateResult,
   OnControlProgress,
   SchemaVerifyOptions,
   SignOptions,
@@ -149,6 +157,23 @@ class ControlClientImpl implements ControlClient {
     }
   }
 
+  /**
+   * Construct the control adapter once for a migration operation and return
+   * it, mirroring how the runtime plane builds the execution adapter once in
+   * `createExecutionStack`. Only `dbInit` / `dbUpdate` need it (it lowers the
+   * planner's DDL); read-only operations never build it. The descriptor is
+   * optional on the stack — targets without migrations omit it.
+   */
+  private buildControlAdapter(): ControlAdapterInstance<string, string> {
+    this.init();
+    if (!this.stack?.adapter) {
+      throw new Error(
+        `Target "${this.options.target.targetId}" requires an adapter for migrations`,
+      );
+    }
+    return this.stack.adapter.create(this.stack);
+  }
+
   private async ensureConnected(): Promise<{
     driver: ControlDriverInstance<string, string>;
     familyInstance: ControlFamilyInstance<string, unknown>;
@@ -359,6 +384,8 @@ class ControlClientImpl implements ControlClient {
       throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
     }
 
+    const adapter = this.buildControlAdapter();
+
     let contract: Contract;
     try {
       contract = familyInstance.deserializeContract(options.contract);
@@ -369,6 +396,7 @@ class ControlClientImpl implements ControlClient {
 
     return executeDbInit({
       driver,
+      adapter,
       familyInstance,
       contract,
       mode: options.mode,
@@ -390,6 +418,8 @@ class ControlClientImpl implements ControlClient {
       throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
     }
 
+    const adapter = this.buildControlAdapter();
+
     let contract: Contract;
     try {
       contract = familyInstance.deserializeContract(options.contract);
@@ -400,6 +430,7 @@ class ControlClientImpl implements ControlClient {
 
     return executeDbUpdate({
       driver,
+      adapter,
       familyInstance,
       contract,
       mode: options.mode,
@@ -447,9 +478,15 @@ class ControlClientImpl implements ControlClient {
     return familyInstance.readAllMarkers({ driver });
   }
 
-  async migrationApply(options: MigrationApplyOptions): Promise<MigrationApplyResult> {
+  /** Reads the per-migration journal; omit `space` to return every space. */
+  async readLedger(space?: string): Promise<readonly LedgerEntryRecord[]> {
+    const { driver, familyInstance } = await this.ensureConnected();
+    return familyInstance.readLedger({ driver, ...ifDefined('space', space) });
+  }
+
+  async migrate(options: MigrateOptions): Promise<MigrateResult> {
     const { onProgress } = options;
-    await this.connectWithProgress(options.connection, 'migrationApply', onProgress);
+    await this.connectWithProgress(options.connection, 'migrate', onProgress);
     const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
     if (!hasMigrations(this.options.target)) {
@@ -464,7 +501,7 @@ class ControlClientImpl implements ControlClient {
       throw new ContractValidationError(message, error);
     }
 
-    return executeMigrationApply({
+    return executeMigrate({
       driver,
       familyInstance,
       contract,
@@ -535,6 +572,11 @@ class ControlClientImpl implements ControlClient {
     return undefined;
   }
 
+  getPslBlockDescriptors(): AuthoringPslBlockDescriptorNamespace {
+    this.init();
+    return this.stack!.authoringContributions.pslBlockDescriptors;
+  }
+
   toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview | undefined {
     this.init();
     if (this.familyInstance && hasOperationPreview(this.familyInstance)) {
@@ -564,8 +606,26 @@ class ControlClientImpl implements ControlClient {
 
     try {
       const stack = this.stack!;
+      const extensionInputs = toExtensionInputs(
+        blindCast<
+          readonly unknown[],
+          'toExtensionInputs accepts readonly unknown[] per its documented structural cast boundary'
+        >(stack.extensionPacks),
+      );
+      const composedExtensionContracts = new Map<string, Contract>(
+        extensionInputs
+          .filter((p) => p.contractSpace !== undefined)
+          .map((p) => [
+            p.id,
+            blindCast<
+              Contract,
+              'contractSpace.contractJson is the typed contract for this extension space'
+            >(p.contractSpace!.contractJson),
+          ]),
+      );
       const sourceContext = {
         composedExtensionPacks: stack.extensionPacks.map((p) => p.id),
+        composedExtensionContracts,
         scalarTypeDescriptors: stack.scalarTypeDescriptors,
         authoringContributions: stack.authoringContributions,
         codecLookup: stack.codecLookup,
@@ -644,8 +704,9 @@ class ControlClientImpl implements ControlClient {
         this.frameworkComponents ?? [],
       );
 
+      let deserializedContract: Contract;
       try {
-        this.familyInstance.deserializeContract(enrichedIR);
+        deserializedContract = this.familyInstance.deserializeContract(enrichedIR);
       } catch (error) {
         onProgress?.({
           action: 'emit',
@@ -663,7 +724,7 @@ class ControlClientImpl implements ControlClient {
       }
 
       const result = await emitContractArtifacts(
-        enrichedIR,
+        deserializedContract,
         this.stack!,
         this.options.family.emission,
         {

package/src/control-api/operations/contract-emit.ts

@@ -3,12 +3,14 @@ import type { Contract } from '@prisma-next/contract/types';
 import { emit, getEmittedArtifactPaths } from '@prisma-next/emitter';
 import { createControlStack } from '@prisma-next/framework-components/control';
 import { abortable } from '@prisma-next/utils/abortable';
+import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { JsonObject } from '@prisma-next/utils/json';
 import { dirname, join } from 'pathe';
 import { loadConfig } from '../../config-loader';
 import { errorContractConfigMissing, errorRuntime } from '../../utils/cli-errors';
 import { queueEmitByOutput } from '../../utils/emit-queue';
+import { toExtensionInputs } from '../../utils/extension-pack-inputs';
 import { assertFrameworkComponentsCompatible } from '../../utils/framework-components';
 import { publishContractArtifactPair } from '../../utils/publish-contract-artifact-pair';
 import { validateContractDeps } from '../../utils/validate-contract-deps';
@@ -194,8 +196,26 @@ export async function executeContractEmit(
   return queueEmitByOutput(outputJsonPath, async () => {
     const stack = createControlStack(config);
 
+    const extensionInputs = toExtensionInputs(
+      blindCast<
+        readonly unknown[],
+        'toExtensionInputs accepts readonly unknown[] per its documented structural cast boundary'
+      >(stack.extensionPacks),
+    );
+    const composedExtensionContracts = new Map<string, Contract>(
+      extensionInputs
+        .filter((p) => p.contractSpace !== undefined)
+        .map((p) => [
+          p.id,
+          blindCast<
+            Contract,
+            'contractSpace.contractJson is the typed contract for this extension space'
+          >(p.contractSpace!.contractJson),
+        ]),
+    );
     const sourceContext = {
       composedExtensionPacks: stack.extensionPacks.map((p) => p.id),
+      composedExtensionContracts,
       scalarTypeDescriptors: stack.scalarTypeDescriptors,
       authoringContributions: stack.authoringContributions,
       codecLookup: stack.codecLookup,
@@ -247,7 +267,7 @@ export async function executeContractEmit(
         validatedContract.value as unknown as Contract,
         frameworkComponents,
       );
-      familyInstance.deserializeContract(enrichedIR);
+      const deserializedContract = familyInstance.deserializeContract(enrichedIR);
       // Each target's descriptor ships a `contractSerializer` SPI; the
       // framework canonicalizer threads its `serializeContract` so the
       // on-disk JSON envelope is constructed by target-owned code
@@ -260,7 +280,7 @@ export async function executeContractEmit(
       const serializeContract = (c: Contract): JsonObject =>
         contractSerializer.serializeContract(c);
       emitResult = await unlessAborted(
-        emit(enrichedIR, stack, config.family.emission, {
+        emit(deserializedContract, stack, config.family.emission, {
           outputJsonPath,
           serializeContract,
           ...ifDefined('shouldPreserveEmpty', contractSerializer.shouldPreserveEmpty),

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

@@ -1,6 +1,7 @@
 import type { Contract } from '@prisma-next/contract/types';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
+  ControlAdapterInstance,
   ControlDriverInstance,
   ControlExtensionDescriptor,
   ControlFamilyInstance,
@@ -8,14 +9,14 @@ import type {
 } from '@prisma-next/framework-components/control';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { DbInitResult, OnControlProgress } from '../types';
-import { executeApply } from './db-apply';
+import { executeRun } from './db-run';
 
 /**
  * Options for executing the `db init` operation.
  *
  * `db init` runs the loader → planner → runner pipeline:
  *
- * 1. {@link executeApply} loads a `ContractSpaceAggregate` via
+ * 1. {@link executeRun} loads a `ContractSpaceAggregate` via
  *    {@link import('@prisma-next/migration-tools/aggregate').loadContractSpaceAggregate}
  *    from the supplied descriptor set + on-disk on-disk artefacts.
  * 2. The aggregate planner runs with `callerPolicy.ignoreGraphFor`
@@ -29,6 +30,7 @@ import { executeApply } from './db-apply';
  */
 export interface ExecuteDbInitOptions<TFamilyId extends string, TTargetId extends string> {
   readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+  readonly adapter: ControlAdapterInstance<TFamilyId, TTargetId>;
   readonly familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
   readonly contract: Contract;
   readonly mode: 'plan' | 'apply';
@@ -68,8 +70,9 @@ export interface ExecuteDbInitOptions<TFamilyId extends string, TTargetId extend
 export async function executeDbInit<TFamilyId extends string, TTargetId extends string>(
   options: ExecuteDbInitOptions<TFamilyId, TTargetId>,
 ): Promise<DbInitResult> {
-  const result = await executeApply<TFamilyId, TTargetId>({
+  const result = await executeRun<TFamilyId, TTargetId>({
     driver: options.driver,
+    adapter: options.adapter,
     familyInstance: options.familyInstance,
     contract: options.contract,
     mode: options.mode,

package/src/control-api/operations/{db-apply.ts → db-run.ts}

@@ -1,10 +1,16 @@
+/**
+ * Backs `db init` / `db update`. Strategy: introspect → planMigration; synth-for-app + graph-walk-extensions; plan-mode + orphan-marker preflight.
+ */
+
 import type { Contract } from '@prisma-next/contract/types';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
+  ControlAdapterInstance,
   ControlDriverInstance,
   ControlExtensionDescriptor,
   ControlFamilyInstance,
   MigrationOperationPolicy,
+  MigrationPlannerConflict,
   MigrationPlanOperation,
   OperationPreview,
   TargetMigrationsCapability,
@@ -12,9 +18,11 @@ import type {
 import { hasOperationPreview } from '@prisma-next/framework-components/control';
 import {
   type ContractSpaceAggregate,
+  collectAggregateNamespaces,
   type PlannerError,
   planMigration,
 } from '@prisma-next/migration-tools/aggregate';
+import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok } from '@prisma-next/utils/result';
 import { CliStructuredError } from '../../utils/cli-errors';
@@ -32,14 +40,19 @@ import type {
   OnControlProgress,
   PerSpaceExecutionEntry,
 } from '../types';
-import { applyMigration, buildPerSpaceBreakdown, collectOrdered } from './apply';
 import { stripOperations } from './migration-helpers';
+import {
+  buildPerSpaceBreakdown,
+  collectOrdered,
+  type OrderedResolution,
+  runMigration,
+} from './run-migration';
 
 /**
- * Span IDs emitted via `onProgress` during the apply flow.
+ * Span IDs emitted via `onProgress` during the run flow.
  * Stable identifiers consumed by the structured-output renderer and by
  * tests asserting on span ids. The `apply` span itself is owned by
- * the {@link applyMigration} primitive — only the introspect / plan
+ * the {@link runMigration} primitive — only the introspect / plan
  * spans are emitted directly here.
  */
 const SPAN_IDS = {
@@ -48,14 +61,15 @@ const SPAN_IDS = {
 } as const;
 
 /**
- * Inputs shared by `db init` and `db update` apply flows.
+ * Inputs shared by `db init` and `db update` run flows.
  *
  * Accepts the already-validated app contract + descriptor list — the
  * loader gathers the rest from disk + descriptors. The CLI is the
  * descriptor-import boundary; everything downstream is descriptor-free.
  */
-export interface ExecuteApplyOptions<TFamilyId extends string, TTargetId extends string> {
+export interface ExecuteRunOptions<TFamilyId extends string, TTargetId extends string> {
   readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+  readonly adapter: ControlAdapterInstance<TFamilyId, TTargetId>;
   readonly familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
   readonly contract: Contract;
   readonly mode: 'plan' | 'apply';
@@ -92,11 +106,12 @@ export interface ExecuteApplyOptions<TFamilyId extends string, TTargetId extends
  *    transaction across every space; failure on any space rolls back
  *    every space's writes.
  */
-export async function executeApply<TFamilyId extends string, TTargetId extends string>(
-  options: ExecuteApplyOptions<TFamilyId, TTargetId>,
+export async function executeRun<TFamilyId extends string, TTargetId extends string>(
+  options: ExecuteRunOptions<TFamilyId, TTargetId>,
 ): Promise<DbInitResult | DbUpdateResult> {
   const {
     driver,
+    adapter,
     familyInstance,
     contract,
     mode,
@@ -147,7 +162,10 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
     spanId: SPAN_IDS.introspect,
     label: 'Introspecting database schema',
   });
-  const schemaIR = await familyInstance.introspect({ driver });
+  const schemaIR = await familyInstance.introspect({
+    driver,
+    contract: collectAggregateNamespaces(aggregate),
+  });
   onProgress?.({ action, kind: 'spanEnd', spanId: SPAN_IDS.introspect, outcome: 'ok' });
 
   // 3. Plan via aggregate planner. App is forced through synth (today's
@@ -162,7 +180,7 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
   const planResult = await planMigration<TFamilyId, TTargetId>({
     aggregate,
     currentDBState: { markersBySpaceId: markerRows, schemaIntrospection: schemaIR },
-    familyInstance,
+    adapter,
     migrations,
     frameworkComponents,
     callerPolicy: { ignoreGraphFor: new Set([aggregate.app.spaceId]) },
@@ -175,6 +193,7 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
   onProgress?.({ action, kind: 'spanEnd', spanId: SPAN_IDS.plan, outcome: 'ok' });
 
   const orderedResolutions = collectOrdered(planResult.value.applyOrder, planResult.value.perSpace);
+  const plannerWarnings = aggregatePlannerWarnings(orderedResolutions);
 
   // The destination's structural shape comes from the app's plan — its
   // `destination` is the storage hash users see in CLI output.
@@ -202,16 +221,17 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
       preview,
       perSpace,
       summary,
+      ...ifDefined('warnings', plannerWarnings),
     });
   }
 
-  // 5. Apply mode: hand off to the shared `applyMigration` primitive.
+  // 5. Run mode: hand off to the shared `runMigration` primitive.
   // The runner-driving tail is identical for `db init` / `db update` /
   // `migrate` — only how each caller produces `perSpacePlans`
   // differs (synth + graph-walk via planMigration here; graph-walk
   // only for migrate). Each caller produces perSpacePlans differently;
-  // this helper handles the shared apply tail.
-  const applied = await applyMigration({
+  // this helper handles the shared run tail.
+  const applied = await runMigration({
     aggregate,
     perSpacePlans: planResult.value.perSpace,
     applyOrder: planResult.value.applyOrder,
@@ -228,6 +248,7 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
       summary: applied.failure.summary,
       ...ifDefined('why', applied.failure.why),
       meta: applied.failure.meta,
+      ...ifDefined('warnings', plannerWarnings),
     });
   }
 
@@ -246,9 +267,17 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
     operationsExecuted: applied.value.totalOpsExecuted,
     perSpace: applied.value.perSpace,
     summary,
+    ...ifDefined('warnings', plannerWarnings),
   });
 }
 
+function aggregatePlannerWarnings(
+  orderedResolutions: readonly OrderedResolution[],
+): readonly MigrationPlannerConflict[] | undefined {
+  const warnings = orderedResolutions.flatMap((r) => r.entry.warnings ?? []);
+  return warnings.length > 0 ? warnings : undefined;
+}
+
 /**
  * Compare the live `_prisma_marker` rows against the aggregate's
  * declared members. Any marker row whose `space` is not a member of
@@ -307,7 +336,10 @@ function mapPlannerError(error: PlannerError): DbInitResult | DbUpdateResult {
       why: undefined,
       meta: undefined,
     };
-    return notOk(failure) as DbInitResult | DbUpdateResult;
+    return blindCast<
+      DbInitResult | DbUpdateResult,
+      'notOk(failure) is shape-compatible with both DbInitResult and DbUpdateResult; the union is the return type of the surrounding function'
+    >(notOk(failure));
   }
   if (error.kind === 'extensionPathUnreachable') {
     return buildRunnerFailure({
@@ -339,6 +371,7 @@ function wrapPlanResult(args: {
   readonly preview: OperationPreview | undefined;
   readonly perSpace: readonly PerSpaceExecutionEntry[];
   readonly summary: string;
+  readonly warnings?: readonly MigrationPlannerConflict[];
 }): DbInitResult | DbUpdateResult {
   const success: DbInitSuccess | DbUpdateSuccess = {
     mode: 'plan',
@@ -352,6 +385,7 @@ function wrapPlanResult(args: {
     },
     perSpace: args.perSpace,
     summary: args.summary,
+    ...ifDefined('warnings', args.warnings),
   };
   return ok(success);
 }
@@ -363,6 +397,7 @@ function wrapApplyResult(args: {
   readonly operationsExecuted: number;
   readonly perSpace: readonly PerSpaceExecutionEntry[];
   readonly summary: string;
+  readonly warnings?: readonly MigrationPlannerConflict[];
 }): DbInitResult | DbUpdateResult {
   const success: DbInitSuccess | DbUpdateSuccess = {
     mode: 'apply',
@@ -380,6 +415,7 @@ function wrapApplyResult(args: {
       : { storageHash: args.destination.storageHash },
     perSpace: args.perSpace,
     summary: args.summary,
+    ...ifDefined('warnings', args.warnings),
   };
   return ok(success);
 }
@@ -388,6 +424,7 @@ function buildRunnerFailure(args: {
   readonly summary: string;
   readonly why?: string;
   readonly meta: Record<string, unknown>;
+  readonly warnings?: readonly MigrationPlannerConflict[];
 }): DbInitResult | DbUpdateResult {
   const failure: DbInitFailure | DbUpdateFailure = {
     code: 'RUNNER_FAILED',
@@ -395,6 +432,10 @@ function buildRunnerFailure(args: {
     why: args.why,
     meta: args.meta,
     conflicts: undefined,
+    ...ifDefined('warnings', args.warnings),
   };
-  return notOk(failure) as DbInitResult | DbUpdateResult;
+  return blindCast<
+    DbInitResult | DbUpdateResult,
+    'notOk(failure) is shape-compatible with both DbInitResult and DbUpdateResult; the union is the return type of the surrounding function'
+  >(notOk(failure));
 }