@prisma-next/cli 0.14.0-dev.5 → 0.14.0-dev.50

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

@@ -45,10 +45,11 @@ export interface RunMigrationInputs<TFamilyId extends string, TTargetId extends
   readonly aggregate: ContractSpaceAggregate;
   /**
    * Per-space plans, keyed by `spaceId`. Produced by either the full
-   * {@link planMigration} pipeline (`db init` / `db update` — synth
-   * for the app, graph-walk for extensions) or by direct
-   * {@link graphWalkStrategy} calls (`migrate` — graph-walk
-   * for every member). Either way, the runner consumes the same shape.
+   * {@link planMigration} pipeline (`db init` / `db update` —
+   * `planFromDiff` for the app, `resolveRecordedPath` for extensions) or
+   * by direct {@link resolveRecordedPath} calls (`migrate` — resolves
+   * the recorded path for every contract space). Either way, the runner
+   * consumes the same shape.
    */
   readonly perSpacePlans: ReadonlyMap<string, PerSpacePlan>;
   /**
@@ -229,7 +230,7 @@ export function buildPerSpaceBreakdown(
 
 /**
  * Materialise the `applyOrder` ordering into resolved per-space
- * entries. Throws if the planner output is missing a member listed
+ * entries. Throws if the planner output is missing a contract space listed
  * in `applyOrder` — a wiring bug that should never reach runtime.
  *
  * Exported so callers building their own success envelopes after a

package/src/control-api/types.ts

@@ -545,7 +545,7 @@ export type EmitResult = Result<EmitSuccess, EmitFailure>;
  *
  * The control-api operation is responsible for: loading the
  * contract-space aggregate, reading per-space marker rows from the
- * live database, plotting per-space paths via `graphWalkStrategy`
+ * live database, plotting per-space paths via `resolveRecordedPath`
  * (replay-only — no synth, no introspection), and dispatching
  * through the shared `runMigration` primitive. The CLI command
  * just resolves the descriptor surface (config, refs, contract
@@ -557,9 +557,9 @@ export interface MigrateOptions {
   /** Migrations root directory (`migrations/` under the project). */
   readonly migrationsDir: string;
   /**
-   * Optional app-space ref override. When provided, the app member's
+   * Optional app-space ref override. When provided, the app space's
    * graph-walk targets this hash instead of `contract.storage.storageHash`.
-   * Extension members always walk to their own `headRef.hash`.
+   * Extension spaces always walk to their own `headRef.hash`.
    */
   readonly refHash?: string;
   /**
@@ -631,17 +631,17 @@ export interface MigrateRanEntry {
 
 /**
  * Successful migrate result. Carries both the top-level fields
- * (`markerHash` is the **app member's** post-migrate marker) and the
+ * (`markerHash` is the **app space's** post-migrate marker) and the
  * per-space breakdown (`perSpace` — markers / operations in canonical
  * schedule order).
  */
 /**
- * Path-decision summary for the **app member** post-migrate. Surfaced
+ * Path-decision summary for the **app space** post-migrate. Surfaced
  * at the top level (and consumed by the cli-journeys suite, which
  * inspects `requiredInvariants`/`satisfiedInvariants`/
  * `selectedPath` to validate invariant routing).
  *
- * Per-space path decisions for extension members are not surfaced —
+ * Per-space path decisions for extension spaces are not surfaced —
  * extensions own their own ref/invariant control.
  */
 export interface MigratePathDecision {
@@ -673,7 +673,7 @@ export interface MigrateSuccess {
    */
   readonly perSpace: ReadonlyArray<PerSpaceExecutionEntry>;
   /**
-   * Path-decision data for the app member. Present whenever the
+   * Path-decision data for the app space. Present whenever the
    * graph-walk strategy ran for the app (i.e. always for the
    * aggregate-walking migrate path). Absent only for the no-op
    * "Already up to date" early return when the app has no plan.
@@ -864,7 +864,7 @@ export interface ControlClient {
    *   markers, and (unless `skipSchema` is true) per-space schema
    *   verification with pre-projection (closes F23).
    *
-   * @returns Result pattern: per-space schema results on success;
+   * @returns Result pattern: per-space verify results on success;
    *          structured CLI error on marker / loader failure.
    * @throws If not connected or infrastructure failure
    */

package/src/utils/combine-verify-results.ts

@@ -0,0 +1,94 @@
+import type { VerifyDatabaseSchemaResult } from '@prisma-next/framework-components/control';
+
+/**
+ * The combined per-space contract-satisfaction result plus the standalone
+ * unclaimed-elements list, reported once. The CLI renders
+ * both; `unclaimed` is never folded into the combined tree or its issues.
+ */
+export interface CombinedVerifyResult {
+  readonly result: VerifyDatabaseSchemaResult;
+  readonly unclaimed: readonly string[];
+}
+
+/**
+ * Collapse the aggregate verifier's per-space contract-satisfaction results
+ * into a single {@link VerifyDatabaseSchemaResult} for the CLI display
+ * surface, and carry the deduplicated unclaimed-elements list alongside it.
+ * Concatenates the issue lists across spaces; uses the app space's result as
+ * the structural envelope (storage hash, target). Extras are already
+ * stripped from each per-space result, so nothing here duplicates an
+ * unclaimed element per space.
+ *
+ * **Unclaimed disposition.** In strict mode a non-empty `unclaimed` list fails
+ * the combined verdict (`ok: false`); in lenient mode it is carried for
+ * informational rendering only. The list itself is returned unchanged for the
+ * renderer.
+ *
+ * **Summary policy.** Preserve the per-family phrasing whenever the
+ * combined `ok` flag agrees with the app space's `ok` flag — this is
+ * the common case (single-family deployments, single-app deployments)
+ * and the family's "satisfies / does not satisfy contract" phrasing
+ * stays user-visible. When the app passes but an extension fails (or
+ * vice versa) the app's summary contradicts the envelope, so fall back
+ * to the first failing space's summary. This keeps family phrasing
+ * intact and the envelope internally consistent (`ok: false` ↔ failure
+ * summary).
+ */
+export function combineVerifyResults(
+  perSpace: ReadonlyMap<string, VerifyDatabaseSchemaResult>,
+  appSpaceId: string,
+  strict: boolean,
+  unclaimed: readonly string[],
+): CombinedVerifyResult {
+  const appResult = perSpace.get(appSpaceId) ?? perSpace.values().next().value;
+  if (appResult === undefined) {
+    throw new Error(
+      'Aggregate verifier returned no per-space verify results — this is a wiring bug.',
+    );
+  }
+
+  let okAll = true;
+  let firstFailure: VerifyDatabaseSchemaResult | undefined;
+  let issues: VerifyDatabaseSchemaResult['schema']['issues'] = [];
+  let warningIssues: VerifyDatabaseSchemaResult['schema']['issues'] = [];
+  for (const [, result] of perSpace) {
+    if (!result.ok) {
+      okAll = false;
+      if (firstFailure === undefined) firstFailure = result;
+    }
+    issues = [...issues, ...result.schema.issues];
+    warningIssues = [...warningIssues, ...(result.schema.warnings?.issues ?? [])];
+  }
+
+  const unclaimedFails = strict && unclaimed.length > 0;
+  const ok = okAll && !unclaimedFails;
+
+  // Prefer a failing space's family phrasing; else, when only the unclaimed list
+  // fails the verdict, say so; else keep the app space's phrasing. When `okAll`
+  // is false the loop assigned `firstFailure`, so the `?? appResult.summary`
+  // fallback is unreachable — it exists only to keep the read cast-free.
+  const summary = okAll
+    ? unclaimedFails
+      ? `Database schema has ${unclaimed.length} unclaimed element${unclaimed.length === 1 ? '' : 's'} (not in any contract)`
+      : appResult.summary
+    : appResult.ok
+      ? (firstFailure?.summary ?? appResult.summary)
+      : appResult.summary;
+
+  return {
+    result: {
+      ok,
+      ...(ok ? {} : { code: appResult.code ?? 'PN-RUN-3010' }),
+      summary,
+      contract: appResult.contract,
+      target: appResult.target,
+      schema: {
+        issues,
+        warnings: { issues: warningIssues },
+      },
+      meta: { strict },
+      timings: { total: 0 },
+    },
+    unclaimed,
+  };
+}

package/src/utils/extension-pack-inputs.ts

@@ -111,7 +111,7 @@ export function toExtensionInputs(
  * {@link import('./contract-space-aggregate-loader').buildContractSpaceAggregate}.
  *
  * Codec-only extensions (no `contractSpace` declaration) are filtered
- * out: they are not contract-space members, so the aggregate loader
+ * out: they contribute no contract space, so the aggregate loader
  * has nothing to do with them. Filtering happens at this descriptor-
  * import boundary so the loader stays oblivious to that distinction —
  * every entry it sees expects an on-disk `migrations/<id>/` directory.

package/src/utils/formatters/errors.ts

@@ -48,9 +48,17 @@ export function formatErrorOutput(error: CliErrorEnvelope, flags: GlobalFlags):
       }
     }
   }
-  // Show issues list if present (always show a short list; show full list when verbose)
+  // Show issues list if present (always show a short list; show full list when verbose).
+  // `issues` is a shared error-envelope field: PSL interpretation diagnostics stamp
+  // `kind` with their diagnostic code (e.g. `PSL_ORPHANED_BACKRELATION_LIST`); schema-diff
+  // issues carry no `kind` and stamp `reason` instead (e.g. `not-found`). Prefer whichever
+  // the producer supplied.
   if (error.meta?.['issues']) {
-    const issues = error.meta['issues'] as readonly { kind?: string; message?: string }[];
+    const issues = error.meta['issues'] as readonly {
+      kind?: string;
+      reason?: string;
+      message?: string;
+    }[];
     if (issues.length > 0) {
       const maxToShow = isVerbose(flags, 1) ? issues.length : Math.min(3, issues.length);
       const header = isVerbose(flags, 1)
@@ -58,9 +66,9 @@ export function formatErrorOutput(error: CliErrorEnvelope, flags: GlobalFlags):
         : `  Issues (showing ${maxToShow} of ${issues.length}):`;
       lines.push(`${formatDimText(header)}`);
       for (const issue of issues.slice(0, maxToShow)) {
-        const kind = issue.kind ?? 'issue';
+        const label = issue.kind ?? issue.reason ?? 'issue';
         const message = issue.message ?? '';
-        lines.push(`${formatDimText(`    - [${kind}] ${message}`)}`);
+        lines.push(`${formatDimText(`    - [${label}] ${message}`)}`);
       }
       if (!isVerbose(flags, 1) && issues.length > maxToShow) {
         lines.push(`${formatDimText('  Re-run with -v/--verbose to see all issues')}`);

package/src/utils/formatters/verify.ts

@@ -1,8 +1,9 @@
 import type {
   CoreSchemaView,
+  ExpectationFailureReason,
   IntrospectSchemaResult,
+  SchemaDiffIssue,
   SchemaTreeNode,
-  SchemaVerificationNode,
   SignDatabaseResult,
   VerifyDatabaseResult,
   VerifyDatabaseSchemaResult,
@@ -12,6 +13,23 @@ import { bold, cyan, dim, green, magenta, red, yellow } from 'colorette';
 import type { GlobalFlags } from '../global-flags';
 import { createColorFormatter, formatDim, isVerbose } from './helpers';
 
+/** Human-readable label for each failure reason, prefixed onto an issue's message for display. */
+const REASON_LABEL: Record<ExpectationFailureReason, string> = {
+  'not-found': 'missing',
+  'not-expected': 'extra',
+  'not-equal': 'mismatch',
+};
+
+/**
+ * The issue's display text: its own message (the differ's `path`), prefixed
+ * with a human label for why it's flagged. Turning `reason` into a label is
+ * this formatter's job, not the differ's — the differ's issue is data
+ * (`path` + `reason` + nodes), not prose.
+ */
+function formatIssueMessage(issue: SchemaDiffIssue): string {
+  return `${REASON_LABEL[issue.reason]}: ${issue.message}`;
+}
+
 // ============================================================================
 // Verify Output Formatters
 // ============================================================================
@@ -27,9 +45,20 @@ export interface DbVerifyCommandSuccessResult {
   readonly codecCoverageSkipped?: VerifyDatabaseResult['codecCoverageSkipped'];
   readonly schema?: {
     readonly summary: string;
-    readonly counts: VerifyDatabaseSchemaResult['schema']['counts'];
     readonly strict: boolean;
+    /**
+     * Warn-graded finding messages (observed-policy drift). Informational —
+     * present on a passing verify; the full-mode result summarizes them as a
+     * flat message list.
+     */
+    readonly warnings?: readonly string[];
   };
+  /**
+   * Live element names no contract space declares. In full success this is
+   * only ever non-empty in lenient mode — strict mode fails on it — and is
+   * rendered informationally.
+   */
+  readonly unclaimed?: readonly string[];
   readonly warning?: string;
   readonly meta?:
     | (NonNullable<VerifyDatabaseResult['meta']> & {
@@ -71,11 +100,22 @@ export function formatVerifyOutput(
   if (result.contract.profileHash) {
     lines.push(`${formatDimText(`  profileHash: ${result.contract.profileHash}`)}`);
   }
-  if (result.mode === 'full' && result.schema && isVerbose(flags, 1)) {
-    lines.push(
-      `${formatDimText(`  schema: pass=${result.schema.counts.pass} warn=${result.schema.counts.warn} fail=${result.schema.counts.fail}`)}`,
-    );
+  if (result.schema?.warnings && result.schema.warnings.length > 0) {
+    lines.push('');
+    lines.push(formatYellow('Schema warnings:'));
+    for (const message of result.schema.warnings) {
+      lines.push(`  ${formatYellow('⚠')} ${message}`);
+    }
   }
+
+  if (result.unclaimed && result.unclaimed.length > 0) {
+    lines.push('');
+    lines.push(formatYellow('Unclaimed elements (declared by no contract):'));
+    for (const name of result.unclaimed) {
+      lines.push(`  ${formatYellow('⚠')} ${name}`);
+    }
+  }
+
   if (result.warning) {
     lines.push('');
     lines.push(`${formatYellow('⚠')} ${result.warning}`);
@@ -107,6 +147,7 @@ export function formatVerifyJson(result: DbVerifyCommandSuccessResult): string {
     ...ifDefined('missingCodecs', result.missingCodecs),
     ...ifDefined('codecCoverageSkipped', result.codecCoverageSkipped),
     ...ifDefined('schema', result.schema),
+    unclaimed: result.unclaimed ?? [],
     ...ifDefined('warning', result.warning),
     ...ifDefined('meta', result.meta),
     timings: result.timings,
@@ -124,7 +165,7 @@ export function formatIntrospectJson(result: IntrospectSchemaResult<unknown>): s
 
 /**
  * Renders a schema tree structure from CoreSchemaView.
- * Matches the style of renderSchemaVerificationTree for consistency.
+ * Status-glyph tree styling shared with the retired verification-tree renderer.
  */
 function renderSchemaTree(
   node: SchemaTreeNode,
@@ -310,213 +351,13 @@ export function formatIntrospectOutput(
   return lines.join('\n');
 }
 
-/**
- * Renders a schema verification tree structure from SchemaVerificationNode.
- * Similar to renderSchemaTree but for verification nodes with status-based colors and glyphs.
- */
-function renderSchemaVerificationTree(
-  node: SchemaVerificationNode,
-  flags: GlobalFlags,
-  options: {
-    readonly isLast: boolean;
-    readonly prefix: string;
-    readonly useColor: boolean;
-    readonly formatDimText: (text: string) => string;
-    readonly isRoot?: boolean;
-  },
-): string[] {
-  const { isLast, prefix, useColor, formatDimText, isRoot = false } = options;
-  const lines: string[] = [];
-
-  // Format status glyph and color based on status
-  let statusGlyph = '';
-  let statusColor: (text: string) => string = (text) => text;
-  if (useColor) {
-    switch (node.status) {
-      case 'pass':
-        statusGlyph = '✔';
-        statusColor = green;
-        break;
-      case 'warn':
-        statusGlyph = '⚠';
-        statusColor = (text) => (useColor ? yellow(text) : text);
-        break;
-      case 'fail':
-        statusGlyph = '✖';
-        statusColor = red;
-        break;
-    }
-  } else {
-    switch (node.status) {
-      case 'pass':
-        statusGlyph = '✔';
-        break;
-      case 'warn':
-        statusGlyph = '⚠';
-        break;
-      case 'fail':
-        statusGlyph = '✖';
-        break;
-    }
-  }
-
-  // Format node label with color based on kind
-  // For column nodes, we need to parse the name to color code different parts
-  let labelColor: (text: string) => string = (text) => text;
-  let formattedLabel: string = node.name;
-
-  if (useColor) {
-    switch (node.kind) {
-      case 'contract':
-      case 'schema':
-        labelColor = bold;
-        formattedLabel = labelColor(node.name);
-        break;
-      case 'table': {
-        // Parse "table tableName" format - color "table" dim, tableName cyan
-        const tableMatch = node.name.match(/^table\s+(.+)$/);
-        if (tableMatch?.[1]) {
-          const tableName = tableMatch[1];
-          formattedLabel = `${dim('table')} ${cyan(tableName)}`;
-        } else {
-          formattedLabel = dim(node.name);
-        }
-        break;
-      }
-      case 'columns':
-        labelColor = dim;
-        formattedLabel = labelColor(node.name);
-        break;
-      case 'column': {
-        // Parse column name format: "columnName: contractType -> nativeType (nullability)"
-        // Color code: column name (cyan), contract type (default), native type (dim), nullability (dim)
-        const columnMatch = node.name.match(/^([^:]+):\s*(.+)$/);
-        if (columnMatch?.[1] && columnMatch[2]) {
-          const columnName = columnMatch[1];
-          const rest = columnMatch[2];
-          // Parse rest: "contractType -> nativeType (nullability)"
-          // Match contract type (can contain /, @, etc.), arrow, native type, then nullability in parentheses
-          const typeMatch = rest.match(/^([^\s→]+)\s*→\s*([^\s(]+)\s*(\([^)]+\))$/);
-          if (typeMatch?.[1] && typeMatch[2] && typeMatch[3]) {
-            const contractType = typeMatch[1];
-            const nativeType = typeMatch[2];
-            const nullability = typeMatch[3];
-            formattedLabel = `${cyan(columnName)}: ${contractType} → ${dim(nativeType)} ${dim(nullability)}`;
-          } else {
-            // Fallback if format doesn't match (e.g., no native type or no nullability)
-            formattedLabel = `${cyan(columnName)}: ${rest}`;
-          }
-        } else {
-          formattedLabel = node.name;
-        }
-        break;
-      }
-      case 'type':
-      case 'nullability':
-        labelColor = (text) => text; // Default color
-        formattedLabel = labelColor(node.name);
-        break;
-      case 'primaryKey': {
-        // Parse "primary key: columnName" format - color "primary key" dim, columnName cyan
-        const pkMatch = node.name.match(/^primary key:\s*(.+)$/);
-        if (pkMatch?.[1]) {
-          const columnNames = pkMatch[1];
-          formattedLabel = `${dim('primary key')}: ${cyan(columnNames)}`;
-        } else {
-          formattedLabel = dim(node.name);
-        }
-        break;
-      }
-      case 'foreignKey':
-      case 'unique':
-      case 'index':
-        labelColor = dim;
-        formattedLabel = labelColor(node.name);
-        break;
-      case 'dependency': {
-        // Parse specific extension message formats
-        // "database is postgres" -> dim "database is", cyan "postgres"
-        const dbMatch = node.name.match(/^database is\s+(.+)$/);
-        if (dbMatch?.[1]) {
-          const dbName = dbMatch[1];
-          formattedLabel = `${dim('database is')} ${cyan(dbName)}`;
-        } else {
-          // "vector extension is enabled" -> dim everything except extension name
-          // Match pattern: "extensionName extension is enabled"
-          const extMatch = node.name.match(/^([^\s]+)\s+(extension is enabled)$/);
-          if (extMatch?.[1] && extMatch[2]) {
-            const extName = extMatch[1];
-            const rest = extMatch[2];
-            formattedLabel = `${cyan(extName)} ${dim(rest)}`;
-          } else {
-            // Fallback: color entire name with magenta
-            labelColor = magenta;
-            formattedLabel = labelColor(node.name);
-          }
-        }
-        break;
-      }
-      default:
-        formattedLabel = node.name;
-        break;
-    }
-  } else {
-    formattedLabel = node.name;
-  }
-
-  const statusGlyphColored = statusColor(statusGlyph);
-
-  // Build the label with optional message for failure/warn nodes
-  let nodeLabel = formattedLabel;
-  if (
-    (node.status === 'fail' || node.status === 'warn') &&
-    node.message &&
-    node.message.length > 0
-  ) {
-    // Always show message for failure/warn nodes - it provides crucial context
-    // For parent nodes, the message summarizes child failures
-    // For leaf nodes, the message explains the specific issue
-    const messageText = formatDimText(`(${node.message})`);
-    nodeLabel = `${formattedLabel} ${messageText}`;
-  }
-
-  // Root node renders without tree characters or | prefix
-  // Root node renders without tree characters or prefix
-  if (isRoot) {
-    lines.push(`${statusGlyphColored} ${nodeLabel}`);
-  } else {
-    const treeChar = isLast ? '└' : '├';
-    const treePrefix = `${formatDimText(treeChar)}─ `;
-    lines.push(`${prefix}${treePrefix}${statusGlyphColored} ${nodeLabel}`);
-  }
-
-  // Render children if present
-  if (node.children && node.children.length > 0) {
-    const childPrefix = isRoot ? '' : `${prefix}${isLast ? '   ' : `${formatDimText('│')}  `}`;
-    for (let i = 0; i < node.children.length; i++) {
-      const child = node.children[i];
-      if (!child) continue;
-      const isLastChild = i === node.children.length - 1;
-      const childLines = renderSchemaVerificationTree(child, flags, {
-        isLast: isLastChild,
-        prefix: childPrefix,
-        useColor,
-        formatDimText,
-        isRoot: false,
-      });
-      lines.push(...childLines);
-    }
-  }
-
-  return lines;
-}
-
 /**
  * Formats human-readable output for database schema verification.
  */
 export function formatSchemaVerifyOutput(
   result: VerifyDatabaseSchemaResult,
   flags: GlobalFlags,
+  unclaimed: readonly string[] = [],
 ): string {
   if (flags.quiet) {
     return '';
@@ -527,30 +368,45 @@ export function formatSchemaVerifyOutput(
   const useColor = flags.color !== false;
   const formatGreen = createColorFormatter(useColor, green);
   const formatRed = createColorFormatter(useColor, red);
+  const formatYellow = createColorFormatter(useColor, yellow);
   const formatDimText = (text: string) => formatDim(useColor, text);
 
-  // Render verification tree first
-  const treeLines = renderSchemaVerificationTree(result.schema.root, flags, {
-    isLast: true,
-    prefix: '',
-    useColor,
-    formatDimText,
-    isRoot: true,
-  });
-  lines.push(...treeLines);
-
-  // Add counts and timings in verbose mode
-  if (isVerbose(flags, 1)) {
-    lines.push(`${formatDimText(`  Total time: ${result.timings.total}ms`)}`);
+  const issueMessages = result.schema.issues.map(formatIssueMessage);
+  if (issueMessages.length > 0) {
+    lines.push(formatRed('Schema issues:'));
+    for (const message of issueMessages) {
+      lines.push(`  ${formatRed('✖')} ${message}`);
+    }
+  }
+
+  const warningMessages = (result.schema.warnings?.issues ?? []).map(formatIssueMessage);
+  if (warningMessages.length > 0) {
+    if (lines.length > 0) lines.push('');
+    lines.push(formatYellow('Schema warnings:'));
+    for (const message of warningMessages) {
+      lines.push(`  ${formatYellow('⚠')} ${message}`);
+    }
+  }
+
+  if (unclaimed.length > 0) {
+    const strict = result.meta?.strict ?? false;
+    if (lines.length > 0) lines.push('');
     lines.push(
-      `${formatDimText(`  pass=${result.schema.counts.pass} warn=${result.schema.counts.warn} fail=${result.schema.counts.fail}`)}`,
+      (strict ? formatRed : formatYellow)('Unclaimed elements (declared by no contract):'),
     );
+    for (const name of unclaimed) {
+      lines.push(`  ${(strict ? formatRed : formatYellow)(strict ? '✖' : '⚠')} ${name}`);
+    }
+  }
+
+  if (isVerbose(flags, 1)) {
+    lines.push(`${formatDimText(`  Total time: ${result.timings.total}ms`)}`);
   }
 
   // Blank line before summary
-  lines.push('');
+  if (lines.length > 0) lines.push('');
 
-  // Summary line at the end: summary with status glyph
+  // Summary line at the end: verdict with status glyph
   if (result.ok) {
     lines.push(`${formatGreen('✔')} ${result.summary}`);
   } else {
@@ -562,10 +418,15 @@ export function formatSchemaVerifyOutput(
 }
 
 /**
- * Formats JSON output for database schema verification.
+ * Formats JSON output for database schema verification. The unclaimed-elements
+ * list is a top-level field alongside the combined result, reported once for
+ * the whole database.
  */
-export function formatSchemaVerifyJson(result: VerifyDatabaseSchemaResult): string {
-  return JSON.stringify(result, null, 2);
+export function formatSchemaVerifyJson(
+  result: VerifyDatabaseSchemaResult,
+  unclaimed: readonly string[] = [],
+): string {
+  return JSON.stringify({ ...result, unclaimed }, null, 2);
 }
 
 // ============================================================================