@prisma-next/cli 0.5.0-dev.66 → 0.5.0-dev.68

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

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

package/src/control-api/types.ts

@@ -19,6 +19,7 @@ import type {
 } from '@prisma-next/framework-components/control';
 import type { PslDocumentAst } from '@prisma-next/framework-components/psl-ast';
 import type { Result } from '@prisma-next/utils/result';
+import type { ExecuteDbVerifyResult } from './operations/db-verify';
 
 // ============================================================================
 // Client Options
@@ -65,6 +66,7 @@ export interface ControlClientOptions {
 export type ControlActionName =
   | 'dbInit'
   | 'dbUpdate'
+  | 'dbVerify'
   | 'migrationApply'
   | 'verify'
   | 'schemaVerify'
@@ -191,6 +193,13 @@ export interface DbInitOptions {
    * The type is driver-specific (e.g., string URL for Postgres).
    */
   readonly connection?: unknown;
+  /**
+   * On-disk migrations directory. Always required — every `db init`
+   * routes through the per-space flow, which reads on-disk
+   * `refs/head.json` and extension destination contracts from this
+   * root.
+   */
+  readonly migrationsDir: string;
   /** Optional progress callback for observing operation progress */
   readonly onProgress?: OnControlProgress;
 }
@@ -221,10 +230,35 @@ export interface DbUpdateOptions {
    * or re-run with -y/--yes.
    */
   readonly acceptDataLoss?: boolean;
+  /**
+   * On-disk migrations directory. Always required — every `db update`
+   * routes through the per-space flow, which reads on-disk
+   * `refs/head.json` and extension destination contracts from this
+   * root.
+   */
+  readonly migrationsDir: string;
   /** Optional progress callback for observing operation progress */
   readonly onProgress?: OnControlProgress;
 }
 
+/**
+ * Options for the dbVerify operation.
+ *
+ * Drives the loader → aggregate-verifier pipeline. `strict` maps to
+ * `verifyAggregate({ mode: 'strict' | 'lenient' })`; `skipSchema`
+ * mirrors the `--marker-only` CLI flag and short-circuits the schema
+ * portion of the verifier.
+ */
+export interface DbVerifyOptions {
+  readonly contract: unknown;
+  readonly migrationsDir: string;
+  readonly strict: boolean;
+  readonly skipSchema: boolean;
+  readonly skipMarker: boolean;
+  readonly connection?: unknown;
+  readonly onProgress?: OnControlProgress;
+}
+
 /**
  * Options for the introspect operation.
  */
@@ -677,6 +711,21 @@ export interface ControlClient {
    */
   dbUpdate(options: DbUpdateOptions): Promise<DbUpdateResult>;
 
+  /**
+   * Verifies the database against every contract space (app + extensions).
+   *
+   * Loader → aggregate-verifier pipeline:
+   * - The loader catches layout / drift / disjointness violations.
+   * - The aggregate verifier surfaces marker-vs-on-disk drift and orphan
+   *   markers, and (unless `skipSchema` is true) per-space schema
+   *   verification with pre-projection (closes F23).
+   *
+   * @returns Result pattern: per-space schema results on success;
+   *          structured CLI error on marker / loader failure.
+   * @throws If not connected or infrastructure failure
+   */
+  dbVerify(options: DbVerifyOptions): Promise<ExecuteDbVerifyResult>;
+
   /**
    * Reads the contract marker from the database.
    * Returns null if no marker exists (fresh database).
@@ -685,6 +734,13 @@ export interface ControlClient {
    */
   readMarker(): Promise<ContractMarkerRecord | null>;
 
+  /**
+   * Reads every marker row (one per contract space). Used by the
+   * per-space verifier to detect orphan marker rows and marker-vs-on-disk
+   * drift after a database connection has been established.
+   */
+  readAllMarkers(): Promise<ReadonlyMap<string, ContractMarkerRecord>>;
+
   /**
    * Applies pre-planned on-disk migrations to the database.
    * Each migration runs in its own transaction with full execution checks.

package/src/exports/control-api.ts

@@ -20,9 +20,20 @@ export { createControlClient } from '../control-api/client';
 
 // Contract enrichment (merges framework-derived capabilities and extension pack metadata)
 export { enrichContract } from '../control-api/contract-enrichment';
-
-// Standalone operations (for tooling that doesn't need full client)
 export { executeContractEmit } from '../control-api/operations/contract-emit';
+// Standalone operations (for tooling that doesn't need full client).
+// These drive the aggregate-pipeline `db init` / `db update` / `db verify`
+// flow against a loaded contract-space aggregate.
+export { type ExecuteDbInitOptions, executeDbInit } from '../control-api/operations/db-init';
+export {
+  type ExecuteDbUpdateOptions,
+  executeDbUpdate,
+} from '../control-api/operations/db-update';
+export {
+  type ExecuteDbVerifyOptions,
+  type ExecuteDbVerifyResult,
+  executeDbVerify,
+} from '../control-api/operations/db-verify';
 // CLI-specific types
 export type {
   ContractEmitOptions,

package/src/load-ts-contract.ts

@@ -4,7 +4,7 @@ import { pathToFileURL } from 'node:url';
 import type { Contract } from '@prisma-next/contract/types';
 import type { Plugin } from 'esbuild';
 import { build } from 'esbuild';
-import { join } from 'pathe';
+import { join, resolve as resolvePath } from 'pathe';
 
 export interface LoadTsContractOptions {
   readonly allowlist?: ReadonlyArray<string>;
@@ -78,7 +78,21 @@ function validatePurity(value: unknown): void {
   }
 }
 
-function createImportAllowlistPlugin(allowlist: ReadonlyArray<string>, entryPath: string): Plugin {
+function createImportAllowlistPlugin(
+  allowlist: ReadonlyArray<string>,
+  entryPath: string,
+  collected: Set<string>,
+): Plugin {
+  // Match against several path forms that esbuild may use as the importer:
+  // the absolute resolved entry, the value the caller passed (which may be
+  // relative), and the conventional `<stdin>` placeholder. This is more
+  // forgiving than `===` against a single form, which broke when esbuild
+  // resolved the entry to an absolute path while the caller passed a
+  // relative one (or vice versa).
+  const entryAbs = resolvePath(entryPath);
+  function isFromEntry(importer: string): boolean {
+    return importer === entryAbs || importer === entryPath || importer === '<stdin>';
+  }
   return {
     name: 'import-allowlist',
     setup(build) {
@@ -89,8 +103,8 @@ function createImportAllowlistPlugin(allowlist: ReadonlyArray<string>, entryPath
         if (args.path.startsWith('.') || args.path.startsWith('/')) {
           return undefined;
         }
-        const isFromEntryPoint = args.importer === entryPath || args.importer === '<stdin>';
-        if (isFromEntryPoint && !isAllowedImport(args.path, allowlist)) {
+        if (isFromEntry(args.importer) && !isAllowedImport(args.path, allowlist)) {
+          collected.add(args.path);
           return {
             path: args.path,
             external: true,
@@ -132,6 +146,13 @@ export async function loadContractFromTs(
     `prisma-next-contract-${Date.now()}-${Math.random().toString(36).slice(2)}.mjs`,
   );
 
+  // Disallowed imports are collected by the allowlist resolver plugin itself,
+  // which has the `importer` context to distinguish entry-direct imports from
+  // transitive imports made inside allowlisted (`@prisma-next/*`) dependencies.
+  // The metafile is intentionally not re-walked: it would surface internal
+  // `node:*` imports inside framework code as false positives.
+  const disallowedFromEntry = new Set<string>();
+
   try {
     const result = await build({
       entryPoints: [entryPath],
@@ -142,7 +163,7 @@ export async function loadContractFromTs(
       outfile: tempFile,
       write: false,
       metafile: true,
-      plugins: [createImportAllowlistPlugin(allowlist, entryPath)],
+      plugins: [createImportAllowlistPlugin(allowlist, entryPath, disallowedFromEntry)],
       logLevel: 'error',
     });
 
@@ -155,28 +176,9 @@ export async function loadContractFromTs(
       throw new Error('No output files generated from bundling');
     }
 
-    const disallowedImports: string[] = [];
-    if (result.metafile) {
-      const inputs = result.metafile.inputs;
-      for (const [, inputData] of Object.entries(inputs)) {
-        const imports =
-          (inputData as { imports?: Array<{ path: string; external?: boolean }> }).imports || [];
-        for (const imp of imports) {
-          if (
-            imp.external &&
-            !imp.path.startsWith('.') &&
-            !imp.path.startsWith('/') &&
-            !isAllowedImport(imp.path, allowlist)
-          ) {
-            disallowedImports.push(imp.path);
-          }
-        }
-      }
-    }
-
-    if (disallowedImports.length > 0) {
+    if (disallowedFromEntry.size > 0) {
       throw new Error(
-        `Disallowed imports detected. Only imports matching the allowlist are permitted:\n  Allowlist: ${allowlist.join(', ')}\n  Disallowed imports: ${disallowedImports.join(', ')}\n\nOnly @prisma-next/* packages are allowed in contract files.`,
+        `Disallowed imports detected. Only imports matching the allowlist are permitted:\n  Allowlist: ${allowlist.join(', ')}\n  Disallowed imports: ${[...disallowedFromEntry].join(', ')}`,
       );
     }
 

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

@@ -0,0 +1,84 @@
+import type { VerifyDatabaseSchemaResult } from '@prisma-next/framework-components/control';
+
+/**
+ * Collapse the aggregate verifier's per-space schema results into a
+ * single {@link VerifyDatabaseSchemaResult} for the existing CLI
+ * display surface. Concatenates issues across members; sums counts;
+ * uses the app member's result as the structural envelope (storage
+ * hash, target).
+ *
+ * **Summary policy.** Preserve the per-family phrasing whenever the
+ * combined `ok` flag agrees with the app member'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 member's summary. This keeps family phrasing
+ * intact and the envelope internally consistent (`ok: false` ↔ failure
+ * summary).
+ */
+export function combineSchemaResults(
+  perSpace: ReadonlyMap<string, VerifyDatabaseSchemaResult>,
+  appSpaceId: string,
+  strict: boolean,
+): VerifyDatabaseSchemaResult {
+  const appResult = perSpace.get(appSpaceId) ?? perSpace.values().next().value;
+  if (appResult === undefined) {
+    throw new Error('Aggregate verifier returned no schema results — this is a wiring bug.');
+  }
+
+  let okAll = true;
+  let firstFailure: VerifyDatabaseSchemaResult | undefined;
+  let issues: VerifyDatabaseSchemaResult['schema']['issues'] = [];
+  const counts = { pass: 0, warn: 0, fail: 0, totalNodes: 0 };
+  const childRoots: Array<VerifyDatabaseSchemaResult['schema']['root']> = [];
+  for (const [, result] of perSpace) {
+    if (!result.ok) {
+      okAll = false;
+      if (firstFailure === undefined) firstFailure = result;
+    }
+    issues = [...issues, ...result.schema.issues];
+    counts.pass += result.schema.counts.pass;
+    counts.warn += result.schema.counts.warn;
+    counts.fail += result.schema.counts.fail;
+    counts.totalNodes += result.schema.counts.totalNodes;
+    childRoots.push(result.schema.root);
+  }
+
+  // When `okAll !== appResult.ok`, exactly one shape is reachable: app passes
+  // (`appResult.ok === true`) and at least one other member failed
+  // (`okAll === false`). In that shape the failure was assigned to
+  // `firstFailure` during iteration, so non-null assertion is safe. The mirror
+  // shape (app fails while every member passes) is impossible because
+  // `appResult` either *is* a member of `perSpace` or is the first iterator
+  // value; either way its `ok` flag participates in `okAll`.
+  const summary =
+    okAll === appResult.ok
+      ? appResult.summary
+      : (firstFailure as VerifyDatabaseSchemaResult).summary;
+
+  return {
+    ok: okAll,
+    ...(okAll ? {} : { code: appResult.code ?? 'PN-RUN-3010' }),
+    summary,
+    contract: appResult.contract,
+    target: appResult.target,
+    schema: {
+      issues,
+      root: {
+        status: okAll ? 'pass' : 'fail',
+        kind: 'aggregate',
+        name: 'aggregate',
+        contractPath: '',
+        code: 'AGGREGATE',
+        message: okAll ? 'Aggregate schema matches' : 'Aggregate schema mismatch',
+        expected: undefined,
+        actual: undefined,
+        children: childRoots,
+      },
+      counts,
+    },
+    meta: { strict },
+    timings: { total: 0 },
+  };
+}