@prisma-next/family-mongo 0.7.0 → 0.8.0-dev.10

package/src/core/schema-verify/canonicalize-introspection.ts

@@ -0,0 +1,389 @@
+/**
+ * Canonicalizes a live (introspected) `MongoSchemaIR` against the expected
+ * (contract-built) IR before diffing. MongoDB applies server-side defaults
+ * to several option/index families that are absent from authored contracts,
+ * which would otherwise cause `verifyMongoSchema` to report false-positive
+ * drift on a fresh `migrate` run.
+ *
+ * The normalization is contract-aware where it has to be: server defaults
+ * are stripped from the live IR for fields the contract did not specify, so
+ * a contract that *does* specify a value still gets compared faithfully.
+ *
+ * Symmetric defaults — like `changeStreamPreAndPostImages: { enabled: false }`,
+ * which is equivalent to "absent" on both sides — are stripped from both IRs
+ * so either authoring style verifies.
+ */
+
+import type {
+  MongoSchemaCollection,
+  MongoSchemaCollectionOptions,
+  MongoSchemaIndex,
+  MongoSchemaIR,
+} from '@prisma-next/mongo-schema-ir';
+import {
+  MongoSchemaCollection as MongoSchemaCollectionCtor,
+  MongoSchemaCollectionOptions as MongoSchemaCollectionOptionsCtor,
+  MongoSchemaIndex as MongoSchemaIndexCtor,
+  MongoSchemaIR as MongoSchemaIRCtor,
+} from '@prisma-next/mongo-schema-ir';
+import { ifDefined } from '@prisma-next/utils/defined';
+
+export interface CanonicalizedSchemas {
+  readonly live: MongoSchemaIR;
+  readonly expected: MongoSchemaIR;
+}
+
+export function canonicalizeSchemasForVerification(
+  live: MongoSchemaIR,
+  expected: MongoSchemaIR,
+): CanonicalizedSchemas {
+  const expectedByName = new Map<string, MongoSchemaCollection>();
+  for (const c of expected.collections) expectedByName.set(c.name, c);
+
+  const liveByName = new Map<string, MongoSchemaCollection>();
+  for (const c of live.collections) liveByName.set(c.name, c);
+
+  const canonicalLive = live.collections.map((c) =>
+    canonicalizeLiveCollection(c, expectedByName.get(c.name)),
+  );
+  const canonicalExpected = expected.collections.map((c) =>
+    canonicalizeExpectedCollection(c, liveByName.get(c.name)),
+  );
+
+  return {
+    live: new MongoSchemaIRCtor(canonicalLive),
+    expected: new MongoSchemaIRCtor(canonicalExpected),
+  };
+}
+
+function canonicalizeLiveCollection(
+  liveColl: MongoSchemaCollection,
+  expectedColl: MongoSchemaCollection | undefined,
+): MongoSchemaCollection {
+  const expectedIndexes = expectedColl?.indexes ?? [];
+  const indexes = liveColl.indexes.map((idx) =>
+    canonicalizeLiveIndex(idx, findExpectedIndexCounterpart(idx, expectedIndexes)),
+  );
+
+  const options = liveColl.options
+    ? canonicalizeLiveOptions(liveColl.options, expectedColl?.options)
+    : undefined;
+
+  return new MongoSchemaCollectionCtor({
+    name: liveColl.name,
+    indexes,
+    ...ifDefined('validator', liveColl.validator),
+    ...ifDefined('options', options),
+  });
+}
+
+function canonicalizeExpectedCollection(
+  expectedColl: MongoSchemaCollection,
+  liveColl: MongoSchemaCollection | undefined,
+): MongoSchemaCollection {
+  // Symmetric text-index key ordering: a contract-shaped text index preserves
+  // the user-authored field order, but the introspected counterpart comes
+  // back from MongoDB with `weights` keys in alphabetical order, so we
+  // canonicalize both sides to alphabetical text-key order. The order of
+  // text fields within the text block is semantically irrelevant — relevance
+  // is governed by `weights`, not key order.
+  const indexes = expectedColl.indexes.map(canonicalizeTextIndexKeyOrder);
+
+  const options = expectedColl.options
+    ? canonicalizeExpectedOptions(expectedColl.options, liveColl?.options)
+    : undefined;
+
+  return new MongoSchemaCollectionCtor({
+    name: expectedColl.name,
+    indexes,
+    ...ifDefined('validator', expectedColl.validator),
+    ...ifDefined('options', options),
+  });
+}
+
+function canonicalizeTextIndexKeyOrder(index: MongoSchemaIndex): MongoSchemaIndex {
+  const hasTextKey = index.keys.some((k) => k.direction === 'text');
+  if (!hasTextKey) return index;
+  return new MongoSchemaIndexCtor({
+    keys: sortTextKeys(index.keys),
+    unique: index.unique,
+    ...ifDefined('sparse', index.sparse),
+    ...ifDefined('expireAfterSeconds', index.expireAfterSeconds),
+    ...ifDefined('partialFilterExpression', index.partialFilterExpression),
+    ...ifDefined('wildcardProjection', index.wildcardProjection),
+    ...ifDefined('collation', index.collation),
+    ...ifDefined('weights', index.weights),
+    ...ifDefined('default_language', index.default_language),
+    ...ifDefined('language_override', index.language_override),
+  });
+}
+
+/**
+ * Returns a copy of `keys` with text-direction entries sorted alphabetically
+ * while preserving the relative position of non-text entries. Compound text
+ * indexes (`{a: 1, _fts: 'text', _ftsx: 1, b: 1}`) keep their scalar
+ * prefix/suffix layout; only the contiguous text block is reordered.
+ */
+function sortTextKeys(
+  keys: ReadonlyArray<{
+    readonly field: string;
+    readonly direction: 'text' | 1 | -1 | '2dsphere' | '2d' | 'hashed';
+  }>,
+): ReadonlyArray<{
+  readonly field: string;
+  readonly direction: 'text' | 1 | -1 | '2dsphere' | '2d' | 'hashed';
+}> {
+  const textEntries = keys.filter((k) => k.direction === 'text');
+  if (textEntries.length <= 1) return keys;
+  const sortedText = [...textEntries].sort((a, b) => a.field.localeCompare(b.field));
+  let textIdx = 0;
+  return keys.map((k) => {
+    if (k.direction !== 'text') return k;
+    const next = sortedText[textIdx++];
+    /* v8 ignore next 3 -- @preserve invariant guard: textIdx is always < sortedText.length here because we only consume sortedText for text-direction entries and sortedText is built from the same filter. */
+    if (next === undefined) {
+      throw new Error('sortTextKeys: text-key counts mismatched');
+    }
+    return next;
+  });
+}
+
+function canonicalizeLiveIndex(
+  liveIndex: MongoSchemaIndex,
+  expectedIndex: MongoSchemaIndex | undefined,
+): MongoSchemaIndex {
+  const projectedKeys = sortTextKeys(projectTextIndexKeys(liveIndex));
+  const collation = liveIndex.collation
+    ? stripUnspecifiedFields(liveIndex.collation, expectedIndex?.collation)
+    : liveIndex.collation;
+
+  // Text-index server defaults: when the contract did not set
+  // `weights`/`default_language`/`language_override`, MongoDB applies
+  // `weights = {<field>: 1, ...}` (uniform), `'english'`, and `'language'`
+  // respectively. Strip them from live *only* when the live value matches
+  // those defaults — preserving non-default live values lets the verifier
+  // surface drift when the live index is tampered (e.g. weights tuned
+  // out-of-band, custom `default_language`/`language_override`) even though
+  // the contract authored neither.
+  const weights =
+    expectedIndex?.weights === undefined && hasDefaultTextWeights(projectedKeys, liveIndex.weights)
+      ? undefined
+      : liveIndex.weights;
+  const default_language =
+    expectedIndex?.default_language === undefined && liveIndex.default_language === 'english'
+      ? undefined
+      : liveIndex.default_language;
+  const language_override =
+    expectedIndex?.language_override === undefined && liveIndex.language_override === 'language'
+      ? undefined
+      : liveIndex.language_override;
+
+  return new MongoSchemaIndexCtor({
+    keys: projectedKeys,
+    unique: liveIndex.unique,
+    ...ifDefined('sparse', liveIndex.sparse),
+    ...ifDefined('expireAfterSeconds', liveIndex.expireAfterSeconds),
+    ...ifDefined('partialFilterExpression', liveIndex.partialFilterExpression),
+    ...ifDefined('wildcardProjection', liveIndex.wildcardProjection),
+    ...ifDefined('collation', collation),
+    ...ifDefined('weights', weights),
+    ...ifDefined('default_language', default_language),
+    ...ifDefined('language_override', language_override),
+  });
+}
+
+/**
+ * Locate the contract-side index that corresponds to a live index for the
+ * purpose of contract-aware normalization. We deliberately match by the
+ * *projected* (contract-shaped) key list — so a live `_fts/_ftsx` index
+ * resolves to a contract `{title: 'text', body: 'text'}` index — and pick
+ * the first match. Contracts very rarely contain duplicate-key indexes; if
+ * we have no counterpart we fall back to no normalization for that index.
+ */
+function findExpectedIndexCounterpart(
+  liveIndex: MongoSchemaIndex,
+  expectedIndexes: ReadonlyArray<MongoSchemaIndex>,
+): MongoSchemaIndex | undefined {
+  const projectedLiveKeys = sortTextKeys(projectTextIndexKeys(liveIndex));
+  const liveKeySig = projectedLiveKeys.map((k) => `${k.field}:${k.direction}`).join(',');
+  for (const expected of expectedIndexes) {
+    const expectedKeySig = sortTextKeys(expected.keys)
+      .map((k) => `${k.field}:${k.direction}`)
+      .join(',');
+    if (expectedKeySig === liveKeySig) return expected;
+  }
+  return undefined;
+}
+
+/**
+ * MongoDB expands a contract-shaped text index like
+ * `[{title: 'text'}, {body: 'text'}]` into its internal weighted vector
+ * representation `[{_fts: 'text'}, {_ftsx: 1}]`. We project back to
+ * contract-shaped keys via `weights`, iterating in whatever order MongoDB
+ * returns them (alphabetical, in practice). `sortTextKeys` is applied
+ * downstream to canonicalize the order on both sides, so this projection
+ * does not depend on a specific iteration order.
+ */
+function projectTextIndexKeys(liveIndex: MongoSchemaIndex): ReadonlyArray<{
+  readonly field: string;
+  readonly direction: 'text' | 1 | -1 | '2dsphere' | '2d' | 'hashed';
+}> {
+  const isTextIndex =
+    liveIndex.keys.length >= 1 &&
+    liveIndex.keys.some((k) => k.field === '_fts' && k.direction === 'text');
+
+  if (!isTextIndex || !liveIndex.weights) return liveIndex.keys;
+
+  const textKeys = Object.keys(liveIndex.weights).map((field) => ({
+    field,
+    direction: 'text' as const,
+  }));
+
+  // Splice the projected text fields into the original `_fts/_ftsx` slot so
+  // compound text indexes that mix scalar prefixes *and* suffixes — e.g.
+  // `[prefix, _fts, _ftsx, suffix]` — keep their original layout. Flattening
+  // scalars first would yield `[prefix, suffix, ...text]`, which `sortTextKeys`
+  // (downstream) cannot recover because it only reorders text-direction
+  // entries within their existing positions. MongoDB always emits exactly one
+  // `_fts`/`_ftsx` pair per index, so we don't need to guard against
+  // duplicates.
+  type IndexKey = (typeof liveIndex.keys)[number];
+  const projectedKeys: IndexKey[] = [];
+  for (const key of liveIndex.keys) {
+    if (key.field === '_ftsx') continue;
+    if (key.field === '_fts') {
+      projectedKeys.push(...textKeys);
+      continue;
+    }
+    projectedKeys.push(key);
+  }
+  return projectedKeys;
+}
+
+/**
+ * MongoDB's server-default `weights` for an authored-without-weights text
+ * index assigns `1` to every text-direction field. Returns `true` only when
+ * `liveWeights` is exactly that uniform shape (every projected text-direction
+ * key weighted at `1`) so the canonicalizer leaves non-default weights —
+ * including out-of-band relevance tweaks — visible to the verifier.
+ *
+ * `projectTextIndexKeys` derives text-direction keys from the live weights
+ * map, so the count is guaranteed to match; we only have to check the value
+ * shape.
+ */
+function hasDefaultTextWeights(
+  projectedKeys: ReadonlyArray<{
+    readonly field: string;
+    readonly direction: 'text' | 1 | -1 | '2dsphere' | '2d' | 'hashed';
+  }>,
+  liveWeights: MongoSchemaIndex['weights'],
+): boolean {
+  if (liveWeights === undefined) return false;
+  const textFields = projectedKeys.filter((k) => k.direction === 'text').map((k) => k.field);
+  return textFields.every((field) => liveWeights[field] === 1);
+}
+
+function canonicalizeLiveOptions(
+  liveOptions: MongoSchemaCollectionOptions,
+  expectedOptions: MongoSchemaCollectionOptions | undefined,
+): MongoSchemaCollectionOptions | undefined {
+  const collation = liveOptions.collation
+    ? stripUnspecifiedFields(liveOptions.collation, expectedOptions?.collation)
+    : undefined;
+
+  // Timeseries: drop `bucketMaxSpanSeconds` (and any other server-applied
+  // extras) when the contract did not specify them.
+  const timeseries = liveOptions.timeseries
+    ? (stripUnspecifiedFields(
+        liveOptions.timeseries as Record<string, unknown>,
+        expectedOptions?.timeseries as Record<string, unknown> | undefined,
+      ) as MongoSchemaCollectionOptions['timeseries'])
+    : undefined;
+
+  // ClusteredIndex: drop `key`, `unique`, `v` and any other server-applied
+  // extras when the contract did not specify them.
+  const clusteredIndex = liveOptions.clusteredIndex
+    ? (stripUnspecifiedFields(
+        liveOptions.clusteredIndex as Record<string, unknown>,
+        expectedOptions?.clusteredIndex as Record<string, unknown> | undefined,
+      ) as MongoSchemaCollectionOptions['clusteredIndex'])
+    : undefined;
+
+  // changeStreamPreAndPostImages: `{enabled: false}` is equivalent to
+  // "absent". Strip it from live so it round-trips with a contract that
+  // omits the field, and is symmetric with the expected-side stripping.
+  const changeStreamPreAndPostImages = isDisabledChangeStream(
+    liveOptions.changeStreamPreAndPostImages,
+  )
+    ? undefined
+    : liveOptions.changeStreamPreAndPostImages;
+
+  const hasMeaningful =
+    liveOptions.capped || timeseries || collation || changeStreamPreAndPostImages || clusteredIndex;
+  if (!hasMeaningful) return undefined;
+
+  return new MongoSchemaCollectionOptionsCtor({
+    ...ifDefined('capped', liveOptions.capped),
+    ...ifDefined('timeseries', timeseries),
+    ...ifDefined('collation', collation),
+    ...ifDefined('changeStreamPreAndPostImages', changeStreamPreAndPostImages),
+    ...ifDefined('clusteredIndex', clusteredIndex),
+  });
+}
+
+function canonicalizeExpectedOptions(
+  expectedOptions: MongoSchemaCollectionOptions,
+  _liveOptions: MongoSchemaCollectionOptions | undefined,
+): MongoSchemaCollectionOptions | undefined {
+  // Symmetric: a contract `{enabled: false}` is equivalent to absent.
+  const changeStreamPreAndPostImages = isDisabledChangeStream(
+    expectedOptions.changeStreamPreAndPostImages,
+  )
+    ? undefined
+    : expectedOptions.changeStreamPreAndPostImages;
+
+  const hasMeaningful =
+    expectedOptions.capped ||
+    expectedOptions.timeseries ||
+    expectedOptions.collation ||
+    changeStreamPreAndPostImages ||
+    expectedOptions.clusteredIndex;
+  if (!hasMeaningful) return undefined;
+
+  return new MongoSchemaCollectionOptionsCtor({
+    ...ifDefined('capped', expectedOptions.capped),
+    ...ifDefined('timeseries', expectedOptions.timeseries),
+    ...ifDefined('collation', expectedOptions.collation),
+    ...ifDefined('changeStreamPreAndPostImages', changeStreamPreAndPostImages),
+    ...ifDefined('clusteredIndex', expectedOptions.clusteredIndex),
+  });
+}
+
+function isDisabledChangeStream(value: { enabled: boolean } | undefined): boolean {
+  return value !== undefined && value.enabled === false;
+}
+
+/**
+ * Returns a copy of `live` containing only the keys that `expected` defines.
+ * Used for option families whose individual sub-fields are server-extended
+ * with platform defaults (collation, timeseries, clusteredIndex), so the
+ * verifier should compare only what the contract actually authored.
+ *
+ * When `expected` is `undefined` — i.e. the contract authored nothing for
+ * this whole option family but the live IR has it — we return `live`
+ * unchanged so the verifier still sees the entire live block and can
+ * surface it as drift. (Returning `undefined` here would silently strip a
+ * server-attached collation/timeseries/clusteredIndex that the contract
+ * never asked for, hiding real drift.)
+ */
+function stripUnspecifiedFields(
+  live: Record<string, unknown>,
+  expected: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  if (expected === undefined) return live;
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(expected)) {
+    if (Object.hasOwn(live, key)) out[key] = live[key];
+  }
+  return out;
+}

package/src/core/schema-verify/verify-mongo-schema.ts

@@ -0,0 +1,60 @@
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type {
+  OperationContext,
+  VerifyDatabaseSchemaResult,
+} from '@prisma-next/framework-components/control';
+import { VERIFY_CODE_SCHEMA_FAILURE } from '@prisma-next/framework-components/control';
+import type { MongoContract } from '@prisma-next/mongo-contract';
+import type { MongoSchemaIR } from '@prisma-next/mongo-schema-ir';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { contractToMongoSchemaIR } from '../contract-to-schema';
+import { diffMongoSchemas } from '../schema-diff';
+import { canonicalizeSchemasForVerification } from './canonicalize-introspection';
+
+export interface VerifyMongoSchemaOptions {
+  readonly contract: MongoContract;
+  readonly schema: MongoSchemaIR;
+  readonly strict: boolean;
+  readonly context?: OperationContext;
+  /**
+   * Active framework components participating in this composition. Mongo
+   * verification does not currently consult them, but the parameter exists
+   * for parity with `verifySqlSchema` so callers can pass the same envelope.
+   */
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'mongo', string>>;
+}
+
+export function verifyMongoSchema(options: VerifyMongoSchemaOptions): VerifyDatabaseSchemaResult {
+  const { contract, schema, strict, context } = options;
+  const startTime = Date.now();
+
+  const expectedIR = contractToMongoSchemaIR(contract);
+  // Strip server-applied defaults (and authored equivalents) before diffing so
+  // the verifier compares like-with-like — see `canonicalize-introspection.ts`.
+  const { live: canonicalLive, expected: canonicalExpected } = canonicalizeSchemasForVerification(
+    schema,
+    expectedIR,
+  );
+  const { root, issues, counts } = diffMongoSchemas(canonicalLive, canonicalExpected, strict);
+
+  const ok = counts.fail === 0;
+  const profileHash = typeof contract.profileHash === 'string' ? contract.profileHash : '';
+
+  return {
+    ok,
+    ...ifDefined('code', ok ? undefined : VERIFY_CODE_SCHEMA_FAILURE),
+    summary: ok ? 'Schema matches contract' : `Schema verification found ${counts.fail} issue(s)`,
+    contract: {
+      storageHash: contract.storage.storageHash,
+      ...(profileHash ? { profileHash } : {}),
+    },
+    target: { expected: contract.target },
+    schema: { issues, root, counts },
+    meta: {
+      strict,
+      ...ifDefined('contractPath', context?.contractPath),
+      ...ifDefined('configPath', context?.configPath),
+    },
+    timings: { total: Date.now() - startTime },
+  };
+}

package/src/exports/control-adapter.ts

@@ -0,0 +1 @@
+export type { MongoControlAdapter, MongoControlAdapterDescriptor } from '../core/control-adapter';

package/src/exports/control.ts

@@ -1,7 +1,14 @@
+export { contractToMongoSchemaIR } from '../core/contract-to-schema';
 export { mongoFamilyDescriptor } from '../core/control-descriptor';
 export {
   createMongoFamilyInstance,
   type MongoControlFamilyInstance,
 } from '../core/control-instance';
+export type { MongoControlTargetDescriptor } from '../core/control-target-descriptor';
 export type { MongoControlExtensionDescriptor } from '../core/control-types';
-export { mongoTargetDescriptor } from '../core/mongo-target-descriptor';
+export {
+  formatMongoOperations,
+  mongoOperationsToPreview,
+} from '../core/operation-preview';
+export { diffMongoSchemas } from '../core/schema-diff';
+export { canonicalizeSchemasForVerification } from '../core/schema-verify/canonicalize-introspection';

package/src/exports/ir.ts

@@ -0,0 +1,3 @@
+export { MongoContractSerializer } from '../core/ir/mongo-contract-serializer';
+export { MongoContractSerializerBase } from '../core/ir/mongo-contract-serializer-base';
+export { MongoSchemaVerifierBase } from '../core/ir/mongo-schema-verifier-base';

package/src/exports/schema-verify.ts

@@ -1,2 +1,4 @@
-export type { VerifyMongoSchemaOptions } from '@prisma-next/target-mongo/schema-verify';
-export { verifyMongoSchema } from '@prisma-next/target-mongo/schema-verify';
+export {
+  type VerifyMongoSchemaOptions,
+  verifyMongoSchema,
+} from '../core/schema-verify/verify-mongo-schema';

package/src/core/mongo-target-descriptor.ts

@@ -1,180 +0,0 @@
-import { createMongoRunnerDeps, extractDb } from '@prisma-next/adapter-mongo/control';
-import type { Contract } from '@prisma-next/contract/types';
-import { MongoDriverImpl } from '@prisma-next/driver-mongo';
-import type {
-  MigratableTargetDescriptor,
-  MigrationRunner,
-  MigrationRunnerResult,
-  MigrationRunnerSuccessValue,
-  MultiSpaceCapableRunner,
-  MultiSpaceRunnerFailure,
-  MultiSpaceRunnerPerSpaceOptions,
-  MultiSpaceRunnerResult,
-} from '@prisma-next/framework-components/control';
-import {
-  type ContractSpaceMember,
-  projectSchemaToSpace,
-} from '@prisma-next/migration-tools/aggregate';
-import type { MongoContract } from '@prisma-next/mongo-contract';
-import type { MongoSchemaCollection } from '@prisma-next/mongo-schema-ir';
-import { MongoSchemaIR } from '@prisma-next/mongo-schema-ir';
-import {
-  contractToMongoSchemaIR,
-  MongoMigrationPlanner,
-  MongoMigrationRunner,
-  type MongoMigrationRunnerExecuteOptions,
-  type MongoRunnerDependencies,
-} from '@prisma-next/target-mongo/control';
-import mongoTargetDescriptorMeta from '@prisma-next/target-mongo/pack';
-import { notOk, ok } from '@prisma-next/utils/result';
-import type { MongoControlFamilyInstance } from './control-instance';
-
-/**
- * `migration.ts` default-exports a `Migration` subclass whose `operations`
- * getter returns the ordered list of operations and whose `describe()`
- * returns the manifest identity metadata. `MongoMigrationPlanner.plan()`
- * returns a `MigrationPlanWithAuthoringSurface` that knows how to render
- * itself back to such a file; `MongoMigrationPlanner.emptyMigration()`
- * returns the same shape for `migration new`. Users run the scaffolded
- * `migration.ts` directly (via `node migration.ts`) to self-emit
- * `ops.json` and attest the `migrationHash`.
- */
-export const mongoTargetDescriptor: MigratableTargetDescriptor<
-  'mongo',
-  'mongo',
-  MongoControlFamilyInstance
-> = {
-  ...mongoTargetDescriptorMeta,
-  migrations: {
-    createPlanner(_family: MongoControlFamilyInstance) {
-      return new MongoMigrationPlanner();
-    },
-    createRunner(family: MongoControlFamilyInstance) {
-      // Deps are bound to the first driver passed to execute() and cached for
-      // subsequent calls. Callers must not change the driver between calls.
-      let cachedDeps: MongoRunnerDependencies | undefined;
-
-      const runMongo = async (
-        driver: Parameters<MigrationRunner<'mongo', 'mongo'>['execute']>[0]['driver'],
-        runnerOptions: Omit<MongoMigrationRunnerExecuteOptions, 'destinationContract'> & {
-          readonly destinationContract: unknown;
-        },
-      ): Promise<MigrationRunnerResult> => {
-        cachedDeps ??= createMongoRunnerDeps(
-          driver,
-          MongoDriverImpl.fromDb(extractDb(driver)),
-          family,
-        );
-        // The framework `MigrationRunner` interface types `destinationContract`
-        // as `unknown`; the Mongo runner narrows to `MongoContract`. Validation
-        // happens upstream — `migration apply` calls
-        // `familyInstance.validateContract(migration.toContract)` before
-        // routing the contract here, so this cast preserves the framework
-        // signature without weakening the runner's typed surface.
-        return new MongoMigrationRunner(cachedDeps).execute({
-          ...runnerOptions,
-          destinationContract: runnerOptions.destinationContract as MongoContract,
-        });
-      };
-
-      const runner: MigrationRunner<'mongo', 'mongo'> & MultiSpaceCapableRunner<'mongo', 'mongo'> =
-        {
-          async execute(options) {
-            const { driver, ...runnerOptions } = options;
-            return runMongo(driver, runnerOptions);
-          },
-          // Mongo cannot wrap DDL ops in a session transaction (createCollection,
-          // createIndex, collMod, setValidation all bypass transactions even on
-          // replica sets), so the cross-space envelope is *resumable* rather than
-          // transactional. Per-space-internal verify-gated marker atomicity
-          // already lives in `runner.execute`: ops apply, schema is introspected
-          // and verified, and the marker advances only on verify-pass. This loop
-          // composes that guarantee across spaces — earlier-advanced markers are
-          // not rolled back when a later space fails. Re-running reads each
-          // marker, finds spaces 1..N−1 at-head (no-op skip), retries N onward.
-          //
-          // Per-space verify is sliced via `projectSchemaToSpace`: the live DB
-          // holds collections owned by sibling spaces, but each space's verify
-          // only sees the slice that space's contract actually claims. Without
-          // the projection an aggregate of two spaces could not pass strict
-          // verify (every other-space collection would look like an extra).
-          //
-          // See `docs/architecture docs/subsystems/10. MongoDB Family.md` §
-          // Contract spaces and ADR 212 — Contract spaces.
-          async executeAcrossSpaces({ driver, perSpaceOptions }): Promise<MultiSpaceRunnerResult> {
-            const members = perSpaceOptions.map(toSpaceMember);
-            const perSpaceResults: Array<{
-              space: string;
-              value: MigrationRunnerSuccessValue;
-            }> = [];
-            for (let i = 0; i < perSpaceOptions.length; i++) {
-              const spaceOptions = perSpaceOptions[i];
-              if (!spaceOptions) continue;
-              const member = members[i];
-              if (!member) continue;
-              const others = members.filter((_, j) => j !== i);
-              const projectSchema = (schema: MongoSchemaIR): MongoSchemaIR => {
-                // `projectSchemaToSpace` returns a plain object
-                // `{...schemaIR, collections: prunedArray}` (not a
-                // `MongoSchemaIR` instance), so the descriptor rewraps
-                // the pruned collections into a fresh `MongoSchemaIR`
-                // before handing it to `verifyMongoSchema` (which
-                // depends on the class's `collectionNames` /
-                // `collection(name)` accessors).
-                const projected = projectSchemaToSpace(schema, member, others) as {
-                  readonly collections: ReadonlyArray<MongoSchemaCollection>;
-                };
-                return new MongoSchemaIR(projected.collections);
-              };
-              const result = await runMongo(driver, { ...spaceOptions, projectSchema });
-              if (!result.ok) {
-                return notOk<MultiSpaceRunnerFailure>({
-                  ...result.failure,
-                  failingSpace: spaceOptions.space,
-                });
-              }
-              perSpaceResults.push({ space: spaceOptions.space, value: result.value });
-            }
-            return ok({ perSpaceResults });
-          },
-        };
-      return runner;
-    },
-    contractToSchema(contract: Contract | null) {
-      return contractToMongoSchemaIR(contract as MongoContract | null);
-    },
-  },
-  create() {
-    return { familyId: 'mongo' as const, targetId: 'mongo' as const };
-  },
-};
-
-/**
- * Synthesise the minimum {@link projectSchemaToSpace}-compatible
- * `ContractSpaceMember` shape from a per-space option entry. The
- * projector only reads `spaceId` and `contract.storage`; the rest of
- * `ContractSpaceMember` (head ref invariants, hydrated migration
- * graph) is irrelevant at runner time and stubbed with sentinels.
- *
- * The `as unknown as ContractSpaceMember` cast is the load-bearing bit
- * — the projector duck-types its members so a sentinel-shaped graph
- * never gets read, but the framework type carries a richer shape.
- */
-function toSpaceMember(
-  opts: MultiSpaceRunnerPerSpaceOptions<'mongo', 'mongo'>,
-): ContractSpaceMember {
-  return {
-    spaceId: opts.space,
-    contract: opts.destinationContract as Contract,
-    headRef: { hash: '', invariants: [] },
-    migrations: {
-      graph: {
-        nodes: new Set<string>(),
-        forwardChain: new Map(),
-        reverseChain: new Map(),
-        migrationByHash: new Map(),
-      },
-      packagesByMigrationHash: new Map(),
-    },
-  } as unknown as ContractSpaceMember;
-}