@prisma-next/cli 0.8.0 → 0.9.0-dev.2

package/src/commands/migration-status.ts

@@ -19,8 +19,9 @@ import {
   findReachableLeaves,
 } from '@prisma-next/migration-tools/migration-graph';
 import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
+import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry, Refs } from '@prisma-next/migration-tools/refs';
-import { readRefs, resolveRef } from '@prisma-next/migration-tools/refs';
+import { readRefs } from '@prisma-next/migration-tools/refs';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { cyan, dim, magenta, yellow } from 'colorette';
@@ -33,6 +34,7 @@ import {
   errorRuntime,
   errorUnexpected,
   mapMigrationToolsError,
+  mapRefResolutionError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
@@ -43,6 +45,7 @@ import {
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
+  setCommandSeeAlso,
   toPathDecisionResult,
   toStructuralEdge,
 } from '../utils/command-helpers';
@@ -70,10 +73,8 @@ import { TerminalUI } from '../utils/terminal-ui';
 interface MigrationStatusOptions extends CommonCommandOptions {
   readonly db?: string;
   readonly config?: string;
-  readonly ref?: string;
-  readonly graph?: boolean;
-  readonly limit?: string;
-  readonly all?: boolean;
+  readonly to?: string;
+  readonly from?: string;
 }
 
 export interface MigrationStatusEntry {
@@ -94,7 +95,7 @@ export interface MigrationStatusEntry {
  *
  * - `headHash`: the on-disk head ref's hash (where the space is going).
  * - `markerHash`: the live marker hash for the space, or null if no
- *    marker has been written yet (greenfield, or pre-`migration apply`).
+ *    marker has been written yet (greenfield, or pre-`migrate`).
  * - `pendingCount`: number of migration edges between marker and head.
  *    Computed via {@link graphWalkStrategy}; 0 means the space is
  *    already at head.
@@ -420,23 +421,6 @@ function resolveDisplayChain(
   return toTarget;
 }
 
-const DEFAULT_LIMIT = 10;
-
-function determineLimit(opts: MigrationStatusOptions) {
-  if (opts.all) {
-    // No limit
-    return;
-  }
-  if (!opts.limit) {
-    return DEFAULT_LIMIT;
-  }
-  const parsed = Number.parseInt(opts.limit, 10);
-  if (Number.isNaN(parsed)) {
-    return DEFAULT_LIMIT;
-  }
-  return parsed;
-}
-
 /**
  * Build the aggregate enumeration of contract spaces for the status
  * output. Loads the aggregate from disk (lossy on failure — extension
@@ -453,15 +437,15 @@ export async function loadAggregateStatusSpaces(args: {
   readonly migrationsDir: string;
   readonly appContractRaw: unknown;
   readonly extensionPacks: BuildAggregateInputs<string, string>['extensionPacks'];
-  readonly validateContract: BuildAggregateInputs<string, string>['validateContract'];
+  readonly deserializeContract: BuildAggregateInputs<string, string>['deserializeContract'];
   readonly markersBySpace: ReadonlyMap<string, ContractMarkerRecordLike> | null;
 }): Promise<readonly MigrationStatusSpaceEntry[]> {
   const loadInputs: BuildAggregateInputs<string, string> = {
     targetId: args.targetId,
     migrationsDir: args.migrationsDir,
-    appContract: args.validateContract(args.appContractRaw),
+    appContract: args.deserializeContract(args.appContractRaw),
     extensionPacks: args.extensionPacks,
-    validateContract: args.validateContract,
+    deserializeContract: args.deserializeContract,
   };
 
   const loaded = await buildContractSpaceAggregate(loadInputs);
@@ -581,11 +565,32 @@ async function executeMigrationStatusCommand(
     throw error;
   }
 
-  if (options.ref) {
-    activeRefName = options.ref;
+  let fromOverrideHash: string | undefined;
+
+  if (options.to || options.from) {
     try {
-      activeRefEntry = resolveRef(allRefs, activeRefName);
-      activeRefHash = activeRefEntry.hash;
+      const { graph: earlyGraph } = await loadMigrationPackages(appMigrationsDir);
+
+      if (options.to) {
+        const refResult = parseContractRef(options.to, { graph: earlyGraph, refs: allRefs });
+        if (!refResult.ok) {
+          return notOk(mapRefResolutionError(refResult.failure));
+        }
+        activeRefHash = refResult.value.hash;
+        if (refResult.value.provenance.kind === 'ref') {
+          const resolvedRefName = refResult.value.provenance.refName;
+          activeRefName = resolvedRefName;
+          activeRefEntry = allRefs[resolvedRefName];
+        }
+      }
+
+      if (options.from) {
+        const fromResult = parseContractRef(options.from, { graph: earlyGraph, refs: allRefs });
+        if (!fromResult.ok) {
+          return notOk(mapRefResolutionError(fromResult.failure));
+        }
+        fromOverrideHash = fromResult.value.hash;
+      }
     } catch (error) {
       if (MigrationToolsError.is(error)) {
         return notOk(mapMigrationToolsError(error));
@@ -613,6 +618,9 @@ async function executeMigrationStatusCommand(
     if (activeRefName) {
       details.push({ label: 'ref', value: activeRefName });
     }
+    if (options.from) {
+      details.push({ label: 'from', value: options.from });
+    }
     if (activeRefEntry && activeRefEntry.invariants.length > 0) {
       details.push({
         label: 'required',
@@ -696,8 +704,8 @@ async function executeMigrationStatusCommand(
         severity: 'warn',
         message: 'There are multiple valid migration paths — you must select a target',
         hints: [
-          "Use '--ref <name>' to select a target",
-          "Or 'prisma-next migration ref set <name> <hash>' to create one",
+          "Use '--to <contract>' to select a target",
+          "Or 'prisma-next ref set <name> <hash>' to create one",
         ],
       });
     }
@@ -751,6 +759,12 @@ async function executeMigrationStatusCommand(
     }
   }
 
+  if (fromOverrideHash !== undefined) {
+    markerHash = fromOverrideHash;
+    mode = 'offline';
+    allMarkers = null;
+  }
+
   // Build the aggregate enumeration of contract spaces. Lossy on
   // failure (extensions are simply omitted) so the existing
   // single-space app pipeline below still runs even if extensions
@@ -760,7 +774,7 @@ async function executeMigrationStatusCommand(
   let aggregateSpaces: readonly MigrationStatusSpaceEntry[] = [];
   if (contractRawForAggregate !== null) {
     // The aggregate loader needs a typed-Contract producer. Build a
-    // real control stack so `validateContract` runs against a fully
+    // real control stack so `deserializeContract` runs against a fully
     // composed family instance — descriptors that read stack members
     // during construction (e.g. codec lookups) get a consistent view.
     const stack = createControlStack(config);
@@ -771,7 +785,7 @@ async function executeMigrationStatusCommand(
         migrationsDir,
         appContractRaw: contractRawForAggregate,
         extensionPacks: config.extensionPacks ?? [],
-        validateContract: (json: unknown) => familyInstance.validateContract(json),
+        deserializeContract: (json: unknown) => familyInstance.deserializeContract(json),
         markersBySpace: allMarkers,
       });
     } catch {
@@ -863,7 +877,7 @@ async function executeMigrationStatusCommand(
       code: 'MIGRATION.NO_MARKER',
       severity: 'warn',
       message: 'Database has not been initialized — no migration marker found',
-      hints: ["Run 'prisma-next migration apply' to apply pending migrations"],
+      hints: ["Run 'prisma-next migrate' to apply pending migrations"],
     });
   }
 
@@ -923,7 +937,7 @@ async function executeMigrationStatusCommand(
   let missingInvariants: readonly string[] | undefined;
   let effectiveRequired = new Set<string>();
   if (mode === 'online') {
-    // Mirrors `migration-apply.ts`: compute `effectiveRequired = required −
+    // Mirrors `migrate.ts`: compute `effectiveRequired = required −
     // marker.invariants` directly, then derive the display fields from it.
     // `appliedInvariants` is the intersection (`required ∩ marker`), which
     // is what JSON consumers see for the active ref; the unfiltered set
@@ -945,17 +959,17 @@ async function executeMigrationStatusCommand(
   if (mode === 'online') {
     if (markerHash !== undefined && !graph.nodes.has(markerHash) && markerHash === contractHash) {
       summary = `${bundles.length} migration(s) on disk`;
-    } else if (activeRefHash && markerHash !== undefined) {
-      const distance = summarizeRefDistance(graph, markerHash, activeRefHash, activeRefName!);
+    } else if (activeRefHash && activeRefName && markerHash !== undefined) {
+      const distance = summarizeRefDistance(graph, markerHash, activeRefHash, activeRefName);
       summary = hasInvariantWork ? `${distance} — missing invariant(s): ${missingList}` : distance;
     } else if (pendingCount === 0 && !hasInvariantWork) {
       summary = `Database is up to date (${appliedCount} migration${appliedCount !== 1 ? 's' : ''} applied)`;
     } else if (pendingCount === 0 && hasInvariantWork) {
-      summary = `Missing invariant(s): ${missingList} — run 'prisma-next migration apply --ref ${activeRefName ?? '<ref>'}' to apply`;
+      summary = `Missing invariant(s): ${missingList} — run 'prisma-next migrate --to ${activeRefName ?? '<ref>'}' to apply`;
     } else if (markerHash === undefined) {
       summary = `${pendingCount} pending migration(s) — database has no marker`;
     } else {
-      summary = `${pendingCount} pending migration(s) — run 'prisma-next migration apply' to apply`;
+      summary = `${pendingCount} pending migration(s) — run 'prisma-next migrate' to apply`;
     }
   } else {
     summary = `${entries.length} migration(s) on disk`;
@@ -997,8 +1011,7 @@ async function executeMigrationStatusCommand(
       diagnostics.push({
         code: 'MIGRATION.MARKER_NOT_IN_HISTORY',
         severity: 'warn',
-        message:
-          'Database matches the current contract but was updated directly (not via migration apply)',
+        message: 'Database matches the current contract but was updated directly (not via migrate)',
         hints: ["Run 'prisma-next migration plan' to plan a migration to your current contract"],
       });
     } else if (pendingCount > 0) {
@@ -1006,7 +1019,7 @@ async function executeMigrationStatusCommand(
         code: 'MIGRATION.DATABASE_BEHIND',
         severity: 'info',
         message: `${pendingCount} migration(s) pending`,
-        hints: ["Run 'prisma-next migration apply' to apply pending migrations"],
+        hints: ["Run 'prisma-next migrate' to apply pending migrations"],
       });
     } else if (hasInvariantWork) {
       diagnostics.push({
@@ -1014,7 +1027,7 @@ async function executeMigrationStatusCommand(
         severity: 'info',
         message: `Missing required invariant(s): ${missingList}`,
         hints: [
-          `Run 'prisma-next migration apply --ref ${activeRefName ?? '<ref>'}' to apply a path that covers the required invariants`,
+          `Run 'prisma-next migrate --to ${activeRefName ?? '<ref>'}' to apply a path that covers the required invariants`,
         ],
       });
     } else if (!routingUnreachable) {
@@ -1056,37 +1069,41 @@ export function createMigrationStatusCommand(): Command {
   const command = new Command('status');
   setCommandDescriptions(
     command,
-    'Show migration history and applied status',
-    'Displays the migration history in order. When a database connection\n' +
-      'is available, shows which migrations are applied and which are pending.\n' +
-      'Without a database connection, shows the history from disk only.',
+    'Show migration path and pending status',
+    'Shows which migrations are pending between the database marker and\n' +
+      'the target contract. Requires a database connection for live status.\n' +
+      'Use `migration graph` for topology, `migration log` for history,\n' +
+      'and `migration list` for on-disk enumeration.',
   );
   setCommandExamples(command, [
-    'prisma-next migration status',
     'prisma-next migration status --db $DATABASE_URL',
+    'prisma-next migration status --to production --db $DATABASE_URL',
+  ]);
+  setCommandSeeAlso(command, [
+    { verb: 'migration log', oneLiner: 'Show executed migration history' },
+    { verb: 'migration list', oneLiner: 'List on-disk migrations' },
+    { verb: 'migration graph', oneLiner: 'Show the migration graph topology' },
+    { verb: 'migration show', oneLiner: 'Display migration package contents' },
   ]);
   addGlobalOptions(command)
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
-    .option('--ref <name>', 'Target ref name from migrations/refs/')
-    .option('--graph', 'Show the full migration graph with all branches')
-    .option('--limit <n>', 'Maximum number of migrations to display (default: 10)')
-    .option('--all', 'Show full history (disables truncation)')
+    .option(
+      '--to <contract>',
+      'Target contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
+    )
+    .option(
+      '--from <contract>',
+      'Origin contract reference; same grammar as --to. Supplying --from switches to offline path computation.',
+    )
     .action(async (options: MigrationStatusOptions) => {
       const flags = parseGlobalFlags(options);
-
       const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
 
       const result = await executeMigrationStatusCommand(options, flags, ui);
 
       const exitCode = handleResult(result, flags, ui, (statusResult) => {
         if (flags.json) {
-          // Strip non-JSON-shape fields before emitting. These belong to
-          // the in-memory result so the human renderer can avoid
-          // recomputing them, but they would either bloat the wire format
-          // (graph, bundles, edgeStatuses) or expose internals
-          // (activeRefHash, activeRefName, diverged) that consumers should
-          // read off `pathDecision` / `refs` instead.
           const {
             graph: _graph,
             bundles: _bundles,
@@ -1101,7 +1118,6 @@ export function createMigrationStatusCommand(): Command {
           const colorize = flags.color !== false;
 
           if (statusResult.graph) {
-            const limit = determineLimit(options);
             const renderInput = migrationGraphToRenderInput({
               graph: statusResult.graph,
               mode: statusResult.mode,
@@ -1113,16 +1129,13 @@ export function createMigrationStatusCommand(): Command {
               edgeStatuses: statusResult.edgeStatuses,
             });
 
-            const graphToRender =
-              options.graph || statusResult.diverged
-                ? renderInput.graph
-                : extractRelevantSubgraph(renderInput.graph, renderInput.relevantPaths);
-            const dagreOptions =
-              !options.graph && isLinearGraph(graphToRender) ? { ranksep: 1 } : undefined;
+            const graphToRender = statusResult.diverged
+              ? renderInput.graph
+              : extractRelevantSubgraph(renderInput.graph, renderInput.relevantPaths);
+            const dagreOptions = isLinearGraph(graphToRender) ? { ranksep: 1 } : undefined;
             const renderOptions = {
               ...renderInput.options,
               colorize,
-              ...ifDefined('limit', limit),
               ...ifDefined('dagreOptions', dagreOptions),
             };
             const graphOutput = graphRenderer.render(graphToRender, renderOptions);
@@ -1209,7 +1222,7 @@ export function formatStatusSummary(result: MigrationStatusResult, colorize: boo
     if (total > 0) {
       lines.push('');
       lines.push(
-        `${c(yellow, '⧗')} ${total} pending migration(s) across ${result.spaces.length} space(s) — run 'prisma-next migration apply' to apply`,
+        `${c(yellow, '⧗')} ${total} pending migration(s) across ${result.spaces.length} space(s) — run 'prisma-next migrate' to apply`,
       );
     }
   }

package/src/commands/{migration-ref.ts → ref.ts}

@@ -1,8 +1,8 @@
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry } from '@prisma-next/migration-tools/refs';
 import {
   deleteRef,
-  readRef,
   readRefs,
   validateRefName,
   validateRefValue,
@@ -16,9 +16,11 @@ import {
   errorRuntime,
   errorUnexpected,
   mapMigrationToolsError,
+  mapRefResolutionError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
+  loadMigrationPackages,
   resolveMigrationPaths,
   setCommandDescriptions,
 } from '../utils/command-helpers';
@@ -34,13 +36,6 @@ interface RefSetResult {
   readonly invariants: readonly string[];
 }
 
-interface RefGetResult {
-  readonly ok: true;
-  readonly ref: string;
-  readonly hash: string;
-  readonly invariants: readonly string[];
-}
-
 interface RefDeleteResult {
   readonly ok: true;
   readonly ref: string;
@@ -66,53 +61,42 @@ function cliErrorInvalidRefName(name: string): CliStructuredError {
   });
 }
 
-function cliErrorInvalidRefValue(hash: string): CliStructuredError {
-  return errorRuntime(`Invalid contract hash "${hash}"`, {
-    why: `"${hash}" is not a valid contract hash`,
-    fix: 'Contract hashes must match the format "sha256:<64 hex chars>". Copy the hash from `prisma-next contract emit` or `migration status --json`.',
-  });
-}
-
-async function executeRefSetCommand(
+export async function executeRefSetCommand(
   name: string,
-  hash: string,
+  contractInput: string,
   options: { config?: string },
 ): Promise<Result<RefSetResult, CliStructuredError>> {
   if (!validateRefName(name)) {
     return notOk(cliErrorInvalidRefName(name));
   }
-  if (!validateRefValue(hash)) {
-    return notOk(cliErrorInvalidRefValue(hash));
-  }
 
   try {
     const config = await loadConfig(options.config);
-    const { refsDir } = resolveMigrationPaths(options.config, config);
-    const entry: RefEntry = { hash, invariants: [] };
+    const { appMigrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
+
+    let resolvedHash: string;
+    if (validateRefValue(contractInput)) {
+      resolvedHash = contractInput;
+    } else {
+      const { graph } = await loadMigrationPackages(appMigrationsDir);
+      const refs = await readRefs(refsDir);
+      const refResult = parseContractRef(contractInput, { graph, refs });
+      if (!refResult.ok) {
+        return notOk(mapRefResolutionError(refResult.failure));
+      }
+      resolvedHash = refResult.value.hash;
+    }
+
+    const entry: RefEntry = { hash: resolvedHash, invariants: [] };
     await writeRef(refsDir, name, entry);
-    return ok({ ok: true as const, ref: name, hash, invariants: [] });
-  } catch (error) {
-    if (error instanceof CliStructuredError) return notOk(error);
-    return notOk(mapError(error));
-  }
-}
-
-async function executeRefGetCommand(
-  name: string,
-  options: { config?: string },
-): Promise<Result<RefGetResult, CliStructuredError>> {
-  try {
-    const config = await loadConfig(options.config);
-    const { refsDir } = resolveMigrationPaths(options.config, config);
-    const entry = await readRef(refsDir, name);
-    return ok({ ok: true as const, ref: name, hash: entry.hash, invariants: entry.invariants });
+    return ok({ ok: true as const, ref: name, hash: resolvedHash, invariants: [] });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);
     return notOk(mapError(error));
   }
 }
 
-async function executeRefDeleteCommand(
+export async function executeRefDeleteCommand(
   name: string,
   options: { config?: string },
 ): Promise<Result<RefDeleteResult, CliStructuredError>> {
@@ -127,7 +111,7 @@ async function executeRefDeleteCommand(
   }
 }
 
-async function executeRefListCommand(options: {
+export async function executeRefListCommand(options: {
   config?: string;
 }): Promise<Result<RefListResult, CliStructuredError>> {
   try {
@@ -145,12 +129,15 @@ function createRefSetCommand(): Command {
   const command = new Command('set');
   setCommandDescriptions(
     command,
-    'Set a ref to a contract hash',
-    'Sets a named ref to point to a contract hash in migrations/refs/.',
+    'Set a ref to a contract reference',
+    'Sets a named ref to point to a resolved contract reference (hash, alias, or path) in migrations/refs/.',
   );
   addGlobalOptions(command)
     .argument('<name>', 'Ref name (e.g., staging, production)')
-    .argument('<hash>', 'Contract hash to point to')
+    .argument(
+      '<contract>',
+      'Contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
+    )
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(
       async (
@@ -174,37 +161,6 @@ function createRefSetCommand(): Command {
   return command;
 }
 
-function createRefGetCommand(): Command {
-  const command = new Command('get');
-  setCommandDescriptions(
-    command,
-    'Get the hash for a ref',
-    'Reads a named ref from migrations/refs/ and prints its contract hash.',
-  );
-  addGlobalOptions(command)
-    .argument('<name>', 'Ref name to look up')
-    .option('--config <path>', 'Path to prisma-next.config.ts')
-    .action(
-      async (
-        name: string,
-        options: { config?: string; json?: string | boolean; quiet?: boolean },
-      ) => {
-        const flags = parseGlobalFlags(options);
-        const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
-        const result = await executeRefGetCommand(name, options);
-        const exitCode = handleResult(result, flags, ui, (value) => {
-          if (flags.json) {
-            ui.output(JSON.stringify(value));
-          } else {
-            ui.output(value.hash);
-          }
-        });
-        process.exit(exitCode);
-      },
-    );
-  return command;
-}
-
 function createRefDeleteCommand(): Command {
   const command = new Command('delete');
   setCommandDescriptions(command, 'Delete a ref', 'Removes a named ref from migrations/refs/.');
@@ -262,20 +218,11 @@ function createRefListCommand(): Command {
   return command;
 }
 
-export {
-  cliErrorInvalidRefName,
-  cliErrorInvalidRefValue,
-  executeRefDeleteCommand,
-  executeRefGetCommand,
-  executeRefListCommand,
-  executeRefSetCommand,
-};
-
-export function createMigrationRefCommand(): Command {
+export function createRefCommand(): Command {
   const command = new Command('ref');
   setCommandDescriptions(
     command,
-    'Manage migration refs',
+    'Manage contract refs',
     'Manage named refs in migrations/refs/. Refs map logical environment\n' +
       'names (e.g., staging, production) to contract hashes.',
   );
@@ -284,7 +231,6 @@ export function createMigrationRefCommand(): Command {
     subcommandDescription: () => '',
   });
   command.addCommand(createRefSetCommand());
-  command.addCommand(createRefGetCommand());
   command.addCommand(createRefDeleteCommand());
   command.addCommand(createRefListCommand());
   return command;

package/src/control-api/client.ts

@@ -201,7 +201,7 @@ class ControlClientImpl implements ControlClient {
     // Validate contract using family instance
     let contract: Contract;
     try {
-      contract = familyInstance.validateContract(options.contract);
+      contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ContractValidationError(message, error);
@@ -254,7 +254,7 @@ class ControlClientImpl implements ControlClient {
     // Validate contract using family instance
     let contract: Contract;
     try {
-      contract = familyInstance.validateContract(options.contract);
+      contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ContractValidationError(message, error);
@@ -269,12 +269,15 @@ class ControlClientImpl implements ControlClient {
     });
 
     try {
-      // Delegate to family instance schemaVerify method
-      const result = await familyInstance.schemaVerify({
-        driver,
+      // Introspect the live schema, then verify the contract against
+      // it. Composing the two primitives here keeps the family
+      // interface a single synchronous verifier and gives callers
+      // (and tests) explicit control over the introspected schema.
+      const schema = await familyInstance.introspect({ driver, contract });
+      const result = familyInstance.verifySchema({
         contract,
+        schema,
         strict: options.strict ?? false,
-        contractPath: '',
         frameworkComponents,
       });
 
@@ -305,7 +308,7 @@ class ControlClientImpl implements ControlClient {
     // Validate contract using family instance
     let contract: Contract;
     try {
-      contract = familyInstance.validateContract(options.contract);
+      contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ContractValidationError(message, error);
@@ -358,7 +361,7 @@ class ControlClientImpl implements ControlClient {
 
     let contract: Contract;
     try {
-      contract = familyInstance.validateContract(options.contract);
+      contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ContractValidationError(message, error);
@@ -389,7 +392,7 @@ class ControlClientImpl implements ControlClient {
 
     let contract: Contract;
     try {
-      contract = familyInstance.validateContract(options.contract);
+      contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ContractValidationError(message, error);
@@ -415,18 +418,10 @@ class ControlClientImpl implements ControlClient {
     await this.connectWithProgress(options.connection, 'dbVerify', onProgress);
     const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
-    let contract: Contract;
-    try {
-      contract = familyInstance.validateContract(options.contract);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      throw new ContractValidationError(message, error);
-    }
-
     return executeDbVerify({
       driver,
       familyInstance,
-      contract,
+      contract: options.contract,
       migrationsDir: options.migrationsDir,
       targetId: this.options.target.targetId,
       extensionPacks: this.options.extensionPacks ?? [],
@@ -463,7 +458,7 @@ class ControlClientImpl implements ControlClient {
 
     let contract: Contract;
     try {
-      contract = familyInstance.validateContract(options.contract);
+      contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ContractValidationError(message, error);
@@ -638,10 +633,20 @@ class ControlClientImpl implements ControlClient {
     });
 
     try {
-      const enrichedIR = enrichContract(contractRaw as Contract, this.frameworkComponents ?? []);
+      // Blind cast: `contractRaw` is the unverified provider
+      // payload — `enrichContract` only adds capability + extension
+      // metadata onto whatever shape it receives. The structural
+      // check happens immediately afterwards via
+      // `familyInstance.deserializeContract(enrichedIR)`, which is
+      // the seam-of-record and the only thing that may surface
+      // structural errors to the caller.
+      const enrichedIR = enrichContract(
+        contractRaw as unknown as Contract,
+        this.frameworkComponents ?? [],
+      );
 
       try {
-        this.familyInstance.validateContract(enrichedIR);
+        this.familyInstance.deserializeContract(enrichedIR);
       } catch (error) {
         onProgress?.({
           action: 'emit',
@@ -662,6 +667,10 @@ class ControlClientImpl implements ControlClient {
         enrichedIR,
         this.stack!,
         this.options.family.emission,
+        {
+          serializeContract: (contract) =>
+            this.options.target.contractSerializer.serializeContract(contract),
+        },
       );
 
       onProgress?.({