@prisma-next/family-mongo 0.8.0 → 0.9.0-dev.2

package/README.md

@@ -6,7 +6,9 @@ Mongo family descriptor and family pack for Prisma Next.
 
 This package is the Mongo family integration point for both control-plane assembly and authoring-time pack composition. It provides:
 
-- the Mongo `ControlFamilyDescriptor` and `mongoTargetDescriptor` used by configs and CLI flows
+- the Mongo `ControlFamilyDescriptor` used by configs and CLI flows
+- the `MongoControlAdapter` SPI that lets adapters supply wire-level marker-ledger and introspection implementations
+- family-shared verification and operation-preview helpers (`verifyMongoSchema`, `formatMongoOperations`)
 - the pure-data Mongo family pack ref used by `contract.ts` authoring
 - a cohesive dependency surface for the Mongo family, including `@prisma-next/mongo-contract-ts`
 
@@ -14,16 +16,19 @@ This package is the Mongo family integration point for both control-plane assemb
 
 - **Control-plane assembly**: Exposes `mongoFamilyDescriptor` and `createMongoFamilyInstance()` for validation and emission flows.
 - **Family hook integration**: Wires `mongoEmission` from `@prisma-next/mongo-emitter` into the family descriptor.
-- **Target bridge**: Exposes a `mongoTargetDescriptor` built from `@prisma-next/target-mongo/pack` metadata for control-plane stacks.
+- **Adapter SPI**: Defines `MongoControlAdapter` — the contract `@prisma-next/adapter-mongo` implements for marker-ledger CAS, ledger appends, and schema introspection. `MongoControlFamilyInstance` resolves the adapter from the control stack and dispatches wire-level work through it.
+- **Family-shared verification**: Owns `verifyMongoSchema` (the structural diff against introspected `MongoSchemaIR`) and the `MongoSchemaVerifierBase` walk used by per-target verifiers.
 - **Authoring-time family pack**: Exposes `@prisma-next/family-mongo/pack` so `defineContract(...)` can bind a Mongo contract to the Mongo family without importing control-plane code.
 - **Validation and emission**: Delegates Mongo contract validation to `@prisma-next/mongo-contract` and contract emission to the shared emitter pipeline.
 
 ## Entrypoints
 
-- `./control`: control-plane entrypoint exporting `mongoFamilyDescriptor`, `mongoTargetDescriptor`, `createMongoFamilyInstance`, and `MongoControlFamilyInstance`
+- `./control`: control-plane entrypoint exporting `mongoFamilyDescriptor`, `createMongoFamilyInstance`, `MongoControlFamilyInstance`, and family-shared helpers (`contractToMongoSchemaIR`, `formatMongoOperations`, `diffMongoSchemas`)
+- `./control-adapter`: SPI surface — `MongoControlAdapter` and `MongoControlAdapterDescriptor`, implemented by `@prisma-next/adapter-mongo`
+- `./ir`: Mongo family IR abstract bases (`MongoContractSerializerBase`, `MongoSchemaVerifierBase`) extended by target packages. The concrete `MongoStorage` storage class lives in the foundation package `@prisma-next/mongo-contract`.
 - `./migration`: migration authoring — `Migration` class, factory functions, and strategies (re-exported from `@prisma-next/target-mongo/migration`)
 - `./pack`: pure pack ref for TypeScript authoring flows such as `@prisma-next/mongo-contract-ts/contract-builder`
-- `./schema-verify`: re-exports the pure `verifyMongoSchema(...)` from `@prisma-next/target-mongo/schema-verify`. `MongoFamilyInstance.schemaVerify` (i.e. `db verify --schema-only`) and the `MongoMigrationRunner` post-apply verify step both call into this shared verifier, so both surfaces agree on "matches the contract" by construction
+- `./schema-verify`: family-shared `verifyMongoSchema(...)`. The CLI `db verify --schema-only` path and the `MongoMigrationRunner` post-apply verify step both call into this shared verifier, so both surfaces agree on "matches the contract" by construction
 
 ## Usage
 
@@ -31,7 +36,8 @@ This package is the Mongo family integration point for both control-plane assemb
 
 ```typescript
 import { createControlStack } from '@prisma-next/framework-components/control';
-import { mongoFamilyDescriptor, mongoTargetDescriptor } from '@prisma-next/family-mongo/control';
+import { mongoFamilyDescriptor } from '@prisma-next/family-mongo/control';
+import { mongoTargetDescriptor } from '@prisma-next/target-mongo/control';
 
 const stack = createControlStack({
   family: mongoFamilyDescriptor,
@@ -40,7 +46,7 @@ const stack = createControlStack({
 
 const familyInstance = mongoFamilyDescriptor.create(stack);
 
-const contract = familyInstance.validateContract(contractJson);
+const contract = familyInstance.deserializeContract(contractJson);
 const result = await familyInstance.emitContract({ contract });
 ```
 
@@ -129,13 +135,19 @@ Run `node migration.ts` to produce `ops.json` and `migration.json`. Use `--dry-r
 ## Package Structure
 
 - `src/core/control-descriptor.ts`: `MongoFamilyDescriptor` implementation
-- `src/core/control-instance.ts`: `createMongoFamilyInstance()` and `MongoControlFamilyInstance`
-- `src/core/mongo-target-descriptor.ts`: pre-built control target descriptor derived from `@prisma-next/target-mongo/pack`
+- `src/core/control-instance.ts`: `createMongoFamilyInstance()` and `MongoControlFamilyInstance` — resolves the `MongoControlAdapter` from the control stack and dispatches wire-level work through it
+- `src/core/control-adapter.ts`: `MongoControlAdapter` SPI definition
+- `src/core/control-target-descriptor.ts`: `MongoControlTargetDescriptor` interface (concrete `mongoTargetDescriptor` lives in `@prisma-next/target-mongo`)
+- `src/core/ir/`: Mongo family IR abstract bases (`MongoContractSerializerBase`, `MongoSchemaVerifierBase`); the concrete `MongoStorage` class lives at `@prisma-next/mongo-contract/ir/mongo-storage.ts`
+- `src/core/operation-preview.ts`: family-shared `formatMongoOperations` / `mongoOperationsToPreview`
+- `src/core/schema-verify/verify-mongo-schema.ts`: family-shared `verifyMongoSchema(...)`
 - `src/core/mongo-migration.ts`: `MongoMigration` class (fixes the `Migration<TOperation>` type parameter to `MongoMigrationPlanOperation`)
 - `src/exports/control.ts`: control-plane entrypoint
+- `src/exports/control-adapter.ts`: adapter SPI entrypoint
+- `src/exports/ir.ts`: IR abstract base entrypoint
 - `src/exports/migration.ts`: migration authoring entrypoint
 - `src/exports/pack.ts`: authoring-time family pack ref
-- `src/exports/schema-verify.ts`: schema-verify entrypoint that re-exports from `@prisma-next/target-mongo/schema-verify`
+- `src/exports/schema-verify.ts`: schema-verify entrypoint exposing the family-shared `verifyMongoSchema`
 
 ## Dependencies
 
@@ -145,4 +157,5 @@ Run `node migration.ts` to produce `ops.json` and `migration.json`. Use `--dry-r
 - `@prisma-next/mongo-contract-ts`: Mongo `contract.ts` authoring surface
 - `@prisma-next/mongo-emitter`: Mongo family emission hook
 - `@prisma-next/mongo-query-ast`: Mongo command AST types (`MongoMigrationPlanOperation`)
-- `@prisma-next/target-mongo`: Mongo target pack metadata and migration factories
+
+This package carries no runtime dependency on `@prisma-next/target-mongo`, `@prisma-next/adapter-mongo`, or `@prisma-next/driver-mongo` — those lower layers depend on the family and adapter SPI defined here, matching the layering used by the SQL family.

package/dist/control-adapter.d.mts

@@ -0,0 +1,75 @@
+import { MongoSchemaIR } from "@prisma-next/mongo-schema-ir";
+import { ControlAdapterDescriptor, ControlAdapterInstance, ControlDriverInstance } from "@prisma-next/framework-components/control";
+import { ContractMarkerRecord } from "@prisma-next/contract/types";
+
+//#region src/core/control-adapter.d.ts
+/**
+ * Mongo control adapter interface for control-plane operations.
+ * Implemented by target-specific adapters (e.g. `@prisma-next/adapter-mongo`).
+ *
+ * Mirrors `SqlControlAdapter` so the family layer dispatches every
+ * driver-bound wire operation through a single SPI surface instead of
+ * importing target-package internals directly. The adapter is the
+ * natural home for these method bodies because it owns both the
+ * `ControlDriverInstance` (which exposes the underlying `Db`) and the
+ * Mongo command vocabulary used to talk to it.
+ *
+ * @template TTarget - The target ID (today only `'mongo'`).
+ */
+interface MongoControlAdapter<TTarget extends string = string> extends ControlAdapterInstance<'mongo', TTarget> {
+  /**
+   * Reads the contract marker document for `space`, or returns `null`
+   * if no marker document has been written for that space yet. Each
+   * space owns one document keyed by `_id: <space>` in the
+   * `_prisma_migrations` collection.
+   */
+  readMarker(driver: ControlDriverInstance<'mongo', TTarget>, space: string): Promise<ContractMarkerRecord | null>;
+  /**
+   * Reads every marker document (one per contract space) and returns
+   * them keyed by `space`. Used by the per-space verifier to detect
+   * marker-vs-on-disk drift and orphan marker rows. Returns an empty
+   * map when no marker documents exist yet.
+   */
+  readAllMarkers(driver: ControlDriverInstance<'mongo', TTarget>): Promise<ReadonlyMap<string, ContractMarkerRecord>>;
+  /**
+   * Inserts an initial marker document for the given space.
+   */
+  initMarker(driver: ControlDriverInstance<'mongo', TTarget>, space: string, destination: {
+    readonly storageHash: string;
+    readonly profileHash: string;
+    readonly invariants?: readonly string[];
+  }): Promise<void>;
+  /**
+   * Atomically updates the marker document for `space` (CAS on
+   * `expectedFrom`). Returns `true` when the CAS succeeded, `false`
+   * when another process advanced the marker first.
+   */
+  updateMarker(driver: ControlDriverInstance<'mongo', TTarget>, space: string, expectedFrom: string, destination: {
+    readonly storageHash: string;
+    readonly profileHash: string;
+    readonly invariants?: readonly string[];
+  }): Promise<boolean>;
+  /**
+   * Appends a ledger entry for the given space. Ledger entries co-exist
+   * with marker documents in the same collection; their key shape
+   * distinguishes them at read time.
+   */
+  writeLedgerEntry(driver: ControlDriverInstance<'mongo', TTarget>, space: string, entry: {
+    readonly edgeId: string;
+    readonly from: string;
+    readonly to: string;
+  }): Promise<void>;
+  /**
+   * Introspects the live database and returns a `MongoSchemaIR`.
+   */
+  introspectSchema(driver: ControlDriverInstance<'mongo', TTarget>): Promise<MongoSchemaIR>;
+}
+/**
+ * Mongo control adapter descriptor. Mirrors `SqlControlAdapterDescriptor`:
+ * extends the framework's `ControlAdapterDescriptor` and narrows the
+ * `create()` return to a `MongoControlAdapter<TTarget>`.
+ */
+interface MongoControlAdapterDescriptor<TTarget extends string = string> extends ControlAdapterDescriptor<'mongo', TTarget, MongoControlAdapter<TTarget>> {}
+//#endregion
+export { type MongoControlAdapter, type MongoControlAdapterDescriptor };
+//# sourceMappingURL=control-adapter.d.mts.map

package/dist/control-adapter.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-adapter.d.mts","names":[],"sources":["../src/core/control-adapter.ts"],"mappings":";;;;;;;AAqBA;;;;;;;;;;;UAAiB,mBAAA,0CACP,sBAAA,UAAgC,OAAA;EAoBrC;;;;;;EAbH,UAAA,CACE,MAAA,EAAQ,qBAAA,UAA+B,OAAA,GACvC,KAAA,WACC,OAAA,CAAQ,oBAAA;EA+C8B;;;;;;EAvCzC,cAAA,CACE,MAAA,EAAQ,qBAAA,UAA+B,OAAA,IACtC,OAAA,CAAQ,WAAA,SAAoB,oBAAA;EApBvB;;;EAyBR,UAAA,CACE,MAAA,EAAQ,qBAAA,UAA+B,OAAA,GACvC,KAAA,UACA,WAAA;IAAA,SACW,WAAA;IAAA,SACA,WAAA;IAAA,SACA,UAAA;EAAA,IAEV,OAAA;EAzBsC;;;;;EAgCzC,YAAA,CACE,MAAA,EAAQ,qBAAA,UAA+B,OAAA,GACvC,KAAA,UACA,YAAA,UACA,WAAA;IAAA,SACW,WAAA;IAAA,SACA,WAAA;IAAA,SACA,UAAA;EAAA,IAEV,OAAA;EA7BQ;;;;;EAoCX,gBAAA,CACE,MAAA,EAAQ,qBAAA,UAA+B,OAAA,GACvC,KAAA,UACA,KAAA;IAAA,SAAkB,MAAA;IAAA,SAAyB,IAAA;IAAA,SAAuB,EAAA;EAAA,IACjE,OAAA;EAhCD;;;EAqCF,gBAAA,CAAiB,MAAA,EAAQ,qBAAA,UAA+B,OAAA,IAAW,OAAA,CAAQ,aAAA;AAAA;;;;;;UAQ5D,6BAAA,0CACP,wBAAA,UAAkC,OAAA,EAAS,mBAAA,CAAoB,OAAA"}

package/dist/control-adapter.mjs

@@ -0,0 +1 @@
+export {};

package/dist/control.d.mts

@@ -1,17 +1,48 @@
-import { ContractSpace, ControlExtensionDescriptor, ControlFamilyDescriptor, ControlFamilyInstance, ControlStack, MigratableTargetDescriptor, OperationPreviewCapable, SchemaViewCapable } from "@prisma-next/framework-components/control";
-import { MongoContract, MongoStorage } from "@prisma-next/mongo-contract";
 import { MongoSchemaIR } from "@prisma-next/mongo-schema-ir";
+import { ContractSerializer, ContractSpace, ControlExtensionDescriptor, ControlFamilyDescriptor, ControlFamilyInstance, ControlStack, MigratableTargetDescriptor, MigrationPlanOperation, OperationPreview, OperationPreviewCapable, SchemaIssue, SchemaVerificationNode, SchemaVerifier, SchemaViewCapable } from "@prisma-next/framework-components/control";
+import { MongoContract, MongoStorageShape } from "@prisma-next/mongo-contract";
 import { Contract } from "@prisma-next/contract/types";
 
+//#region src/core/contract-to-schema.d.ts
+declare function contractToMongoSchemaIR(contract: MongoContract | null): MongoSchemaIR;
+//#endregion
 //#region src/core/control-instance.d.ts
 interface MongoControlFamilyInstance extends ControlFamilyInstance<'mongo', MongoSchemaIR>, SchemaViewCapable<MongoSchemaIR>, OperationPreviewCapable {
-  validateContract(contractJson: unknown): Contract;
+  /**
+   * The family seam-of-record for on-disk contract reads. Structurally
+   * validates the JSON envelope, then casts to the framework `Contract`
+   * shape; the per-target serializer (held on the Mongo target
+   * descriptor) does the class-form wrap for downstream consumers, so
+   * the family only needs the validated data. The single named entry
+   * point every CLI on-disk read crosses (TML-2536) — `as Contract`
+   * casts in production package sources are a serializer-bypass smell
+   * guarded by `pnpm lint:no-contract-cast`.
+   */
+  deserializeContract(contractJson: unknown): Contract;
 }
 declare function createMongoFamilyInstance(controlStack: ControlStack): MongoControlFamilyInstance;
 //#endregion
 //#region src/core/control-descriptor.d.ts
 declare const mongoFamilyDescriptor: ControlFamilyDescriptor<'mongo', MongoControlFamilyInstance>;
 //#endregion
+//#region src/core/control-target-descriptor.d.ts
+/**
+ * Mongo target control descriptor type. Extends the framework's
+ * `MigratableTargetDescriptor` with two named SPI properties next to
+ * the existing `migrations` capability:
+ *
+ * - `contractSerializer` — JSON to class boundary for Mongo contracts.
+ * - `schemaVerifier` — per-target verifier walking the family contract
+ *   against `MongoSchemaIR`.
+ *
+ * The descriptor itself is the aggregator; no extra `Target<TContract,
+ * TSchema>` interface is introduced.
+ */
+interface MongoControlTargetDescriptor<TContract extends MongoContract = MongoContract> extends MigratableTargetDescriptor<'mongo', 'mongo', MongoControlFamilyInstance> {
+  readonly contractSerializer: ContractSerializer<TContract>;
+  readonly schemaVerifier: SchemaVerifier<TContract, MongoSchemaIR>;
+}
+//#endregion
 //#region src/core/control-types.d.ts
 /**
  * Mongo-family extension descriptor.
@@ -23,25 +54,42 @@ declare const mongoFamilyDescriptor: ControlFamilyDescriptor<'mongo', MongoContr
  * The shape comes from `@prisma-next/framework-components/control`
  * (`ContractSpace`) — contract-space identity is a framework concept,
  * not a Mongo-specific one. The Mongo family specialises the generic
- * to `MongoContract<MongoStorage>` so descriptor authors continue to
- * see a typed contract value. Mirrors `SqlControlExtensionDescriptor`.
+ * to `MongoContract<MongoStorageShape>` so descriptor authors see a
+ * typed contract value over the raw-JSON envelope shape; the runtime
+ * in-memory class `MongoStorage` structurally satisfies the shape.
+ * Mirrors `SqlControlExtensionDescriptor`.
  */
 interface MongoControlExtensionDescriptor extends ControlExtensionDescriptor<'mongo', 'mongo'> {
-  readonly contractSpace?: ContractSpace<MongoContract<MongoStorage>>;
+  readonly contractSpace?: ContractSpace<MongoContract<MongoStorageShape>>;
 }
 //#endregion
-//#region src/core/mongo-target-descriptor.d.ts
+//#region src/core/operation-preview.d.ts
+declare function formatMongoOperations(operations: readonly MigrationPlanOperation[]): string[];
 /**
- * `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`.
+ * Wraps `formatMongoOperations` into the family-agnostic
+ * `OperationPreview` shape. Each statement carries
+ * `language: 'mongodb-shell'`. Mirrors `sqlOperationsToPreview`.
  */
-declare const mongoTargetDescriptor: MigratableTargetDescriptor<'mongo', 'mongo', MongoControlFamilyInstance>;
+declare function mongoOperationsToPreview(operations: readonly MigrationPlanOperation[]): OperationPreview;
+//#endregion
+//#region src/core/schema-diff.d.ts
+declare function diffMongoSchemas(live: MongoSchemaIR, expected: MongoSchemaIR, strict: boolean): {
+  root: SchemaVerificationNode;
+  issues: SchemaIssue[];
+  counts: {
+    pass: number;
+    warn: number;
+    fail: number;
+    totalNodes: number;
+  };
+};
+//#endregion
+//#region src/core/schema-verify/canonicalize-introspection.d.ts
+interface CanonicalizedSchemas {
+  readonly live: MongoSchemaIR;
+  readonly expected: MongoSchemaIR;
+}
+declare function canonicalizeSchemasForVerification(live: MongoSchemaIR, expected: MongoSchemaIR): CanonicalizedSchemas;
 //#endregion
-export { type MongoControlExtensionDescriptor, type MongoControlFamilyInstance, createMongoFamilyInstance, mongoFamilyDescriptor, mongoTargetDescriptor };
+export { type MongoControlExtensionDescriptor, type MongoControlFamilyInstance, type MongoControlTargetDescriptor, canonicalizeSchemasForVerification, contractToMongoSchemaIR, createMongoFamilyInstance, diffMongoSchemas, formatMongoOperations, mongoFamilyDescriptor, mongoOperationsToPreview };
 //# sourceMappingURL=control.d.mts.map

package/dist/control.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"control.d.mts","names":[],"sources":["../src/core/control-instance.ts","../src/core/control-descriptor.ts","../src/core/control-types.ts","../src/core/mongo-target-descriptor.ts"],"mappings":";;;;;;UAuCiB,0BAAA,SACP,qBAAA,UAA+B,aAAA,GACrC,iBAAA,CAAkB,aAAA,GAClB,uBAAA;EACF,gBAAA,CAAiB,YAAA,YAAwB,QAAA;AAAA;AAAA,iBAmT3B,yBAAA,CAA0B,YAAA,EAAc,YAAA,GAAe,0BAAA;;;cCvU1D,qBAAA,EAAuB,uBAAA,UAAiC,0BAAA;;;;;;;ADgBrE;;;;;;;;;UEpBiB,+BAAA,SACP,0BAAA;EAAA,SACC,aAAA,GAAgB,aAAA,CAAc,aAAA,CAAc,YAAA;AAAA;;;;;;;AFkBvD;;;;;;cGEa,qBAAA,EAAuB,0BAAA,mBAGlC,0BAAA"}
+{"version":3,"file":"control.d.mts","names":[],"sources":["../src/core/contract-to-schema.ts","../src/core/control-instance.ts","../src/core/control-descriptor.ts","../src/core/control-target-descriptor.ts","../src/core/control-types.ts","../src/core/operation-preview.ts","../src/core/schema-diff.ts","../src/core/schema-verify/canonicalize-introspection.ts"],"mappings":";;;;;;iBAyEgB,uBAAA,CAAwB,QAAA,EAAU,aAAA,UAAuB,aAAA;;;UCzCxD,0BAAA,SACP,qBAAA,UAA+B,aAAA,GACrC,iBAAA,CAAkB,aAAA,GAClB,uBAAA;;;ADsCJ;;;;;;;;EC3BE,mBAAA,CAAoB,YAAA,YAAwB,QAAA;AAAA;AAAA,iBAmF9B,yBAAA,CAA0B,YAAA,EAAc,YAAA,GAAe,0BAAA;;;cC1G1D,qBAAA,EAAuB,uBAAA,UAAiC,0BAAA;;;;;AFkDrE;;;;;;;;;;UGpDiB,4BAAA,mBAA+C,aAAA,GAAgB,aAAA,UACtE,0BAAA,mBAA6C,0BAAA;EAAA,SAC5C,kBAAA,EAAoB,kBAAA,CAAmB,SAAA;EAAA,SACvC,cAAA,EAAgB,cAAA,CAAe,SAAA,EAAW,aAAA;AAAA;;;;;;;AHiDrD;;;;;;;;;;;UIpDiB,+BAAA,SACP,0BAAA;EAAA,SACC,aAAA,GAAgB,aAAA,CAAc,aAAA,CAAc,iBAAA;AAAA;;;iBC6EvC,qBAAA,CAAsB,UAAA,WAAqB,sBAAA;;;;;AL3B3D;iBKgDgB,wBAAA,CACd,UAAA,WAAqB,sBAAA,KACpB,gBAAA;;;iBChHa,gBAAA,CACd,IAAA,EAAM,aAAA,EACN,QAAA,EAAU,aAAA,EACV,MAAA;EAEA,IAAA,EAAM,sBAAA;EACN,MAAA,EAAQ,WAAA;EACR,MAAA;IAAU,IAAA;IAAc,IAAA;IAAc,IAAA;IAAc,UAAA;EAAA;AAAA;;;UCYrC,oBAAA;EAAA,SACN,IAAA,EAAM,aAAA;EAAA,SACN,QAAA,EAAU,aAAA;AAAA;AAAA,iBAGL,kCAAA,CACd,IAAA,EAAM,aAAA,EACN,QAAA,EAAU,aAAA,GACT,oBAAA"}