@prisma-next/cli 0.12.0-dev.6 → 0.12.0-dev.60

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,4 +1,8 @@
-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 { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
@@ -29,7 +33,7 @@ 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 +47,8 @@ import type {
   EmitOptions,
   EmitResult,
   IntrospectOptions,
-  MigrationApplyOptions,
-  MigrationApplyResult,
+  MigrateOptions,
+  MigrateResult,
   OnControlProgress,
   SchemaVerifyOptions,
   SignOptions,
@@ -447,9 +451,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 +474,7 @@ class ControlClientImpl implements ControlClient {
       throw new ContractValidationError(message, error);
     }
 
-    return executeMigrationApply({
+    return executeMigrate({
       driver,
       familyInstance,
       contract,
@@ -644,8 +654,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 +674,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

@@ -247,7 +247,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 +260,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

@@ -8,14 +8,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`
@@ -68,7 +68,7 @@ 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,
     familyInstance: options.familyInstance,
     contract: options.contract,

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

@@ -1,3 +1,7 @@
+/**
+ * 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 {
@@ -5,6 +9,7 @@ import type {
   ControlExtensionDescriptor,
   ControlFamilyInstance,
   MigrationOperationPolicy,
+  MigrationPlannerConflict,
   MigrationPlanOperation,
   OperationPreview,
   TargetMigrationsCapability,
@@ -12,9 +17,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 +39,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,13 +60,13 @@ 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 familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
   readonly contract: Contract;
@@ -92,8 +104,8 @@ 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,
@@ -147,7 +159,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
@@ -175,6 +190,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 +218,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 +245,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 +264,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 +333,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 +368,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 +382,7 @@ function wrapPlanResult(args: {
     },
     perSpace: args.perSpace,
     summary: args.summary,
+    ...ifDefined('warnings', args.warnings),
   };
   return ok(success);
 }
@@ -363,6 +394,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 +412,7 @@ function wrapApplyResult(args: {
       : { storageHash: args.destination.storageHash },
     perSpace: args.perSpace,
     summary: args.summary,
+    ...ifDefined('warnings', args.warnings),
   };
   return ok(success);
 }
@@ -388,6 +421,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 +429,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));
 }

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

@@ -9,7 +9,7 @@ import type {
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk } from '@prisma-next/utils/result';
 import type { DbUpdateResult, OnControlProgress } from '../types';
-import { executeApply } from './db-apply';
+import { executeRun } from './db-run';
 
 const DB_UPDATE_POLICY = {
   allowedOperationClasses: ['additive', 'widening', 'destructive'] as const,
@@ -71,7 +71,7 @@ export async function executeDbUpdate<TFamilyId extends string, TTargetId extend
     const gate = await guardDestructiveChanges<TFamilyId, TTargetId>(sharedInputs);
     if (gate !== null) return gate;
   }
-  return (await executeApply<TFamilyId, TTargetId>({
+  return (await executeRun<TFamilyId, TTargetId>({
     ...sharedInputs,
     mode: options.mode,
   })) as DbUpdateResult;
@@ -85,9 +85,9 @@ export async function executeDbUpdate<TFamilyId extends string, TTargetId extend
  * run.
  */
 async function guardDestructiveChanges<TFamilyId extends string, TTargetId extends string>(
-  sharedInputs: Omit<Parameters<typeof executeApply<TFamilyId, TTargetId>>[0], 'mode'>,
+  sharedInputs: Omit<Parameters<typeof executeRun<TFamilyId, TTargetId>>[0], 'mode'>,
 ): Promise<DbUpdateResult | null> {
-  const planResult = (await executeApply<TFamilyId, TTargetId>({
+  const planResult = (await executeRun<TFamilyId, TTargetId>({
     ...sharedInputs,
     mode: 'plan',
   })) as DbUpdateResult;

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

@@ -8,11 +8,12 @@ import type {
 } from '@prisma-next/framework-components/control';
 import {
   type ContractSpaceMember,
+  collectAggregateNamespaces,
   requireHeadRef,
   type VerifierOutput,
   verifyMigration,
 } from '@prisma-next/migration-tools/aggregate';
-import { castAs } from '@prisma-next/utils/casts';
+import { blindCast, castAs } from '@prisma-next/utils/casts';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { CliStructuredError } from '../../utils/cli-errors';
 import {
@@ -101,7 +102,12 @@ export async function executeDbVerify<TFamilyId extends string, TTargetId extend
   const markersBySpaceId = await familyInstance.readAllMarkers({ driver });
   const schemaIntrospection = skipSchema
     ? null
-    : await runIntrospection({ driver, familyInstance, onProgress });
+    : await runIntrospection({
+        driver,
+        familyInstance,
+        onProgress,
+        contract: collectAggregateNamespaces(aggregate),
+      });
 
   emitVerifySpan(onProgress, 'spanStart');
   const verifyResult = verifyMigration({
@@ -130,8 +136,9 @@ async function runIntrospection<TFamilyId extends string, TTargetId extends stri
   driver: ControlDriverInstance<TFamilyId, TTargetId>;
   familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
   onProgress: OnControlProgress | undefined;
+  contract: unknown;
 }): Promise<unknown> {
-  const { driver, familyInstance, onProgress } = args;
+  const { driver, familyInstance, onProgress, contract } = args;
   onProgress?.({
     action: 'dbVerify',
     kind: 'spanStart',
@@ -139,7 +146,7 @@ async function runIntrospection<TFamilyId extends string, TTargetId extends stri
     label: 'Introspecting database schema',
   });
   try {
-    const result = await familyInstance.introspect({ driver });
+    const result = await familyInstance.introspect({ driver, contract });
     onProgress?.({
       action: 'dbVerify',
       kind: 'spanEnd',
@@ -179,7 +186,10 @@ export function createPerMemberVerifier<TFamilyId extends string, TTargetId exte
       // 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,
+      schema: blindCast<
+        never,
+        'family TSchemaIR is opaque to migration-tools; projectedSchema is passed straight through'
+      >(projectedSchema),
       strict: verifyMode === 'strict',
       frameworkComponents,
     });