@prisma-next/adapter-mongo 0.12.0 → 0.13.0-dev.2

package/package.json

@@ -1,40 +1,42 @@
 {
   "name": "@prisma-next/adapter-mongo",
-  "version": "0.12.0",
+  "version": "0.13.0-dev.2",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "MongoDB adapter for Prisma Next (lowers commands to wire format)",
   "dependencies": {
-    "@prisma-next/config": "0.12.0",
-    "@prisma-next/contract": "0.12.0",
-    "@prisma-next/errors": "0.12.0",
-    "@prisma-next/family-mongo": "0.12.0",
-    "@prisma-next/framework-components": "0.12.0",
-    "@prisma-next/mongo-codec": "0.12.0",
-    "@prisma-next/mongo-contract": "0.12.0",
-    "@prisma-next/mongo-lowering": "0.12.0",
-    "@prisma-next/mongo-query-ast": "0.12.0",
-    "@prisma-next/mongo-schema-ir": "0.12.0",
-    "@prisma-next/mongo-value": "0.12.0",
-    "@prisma-next/mongo-wire": "0.12.0",
-    "@prisma-next/operations": "0.12.0",
-    "@prisma-next/utils": "0.12.0",
+    "@prisma-next/config": "0.13.0-dev.2",
+    "@prisma-next/contract": "0.13.0-dev.2",
+    "@prisma-next/errors": "0.13.0-dev.2",
+    "@prisma-next/family-mongo": "0.13.0-dev.2",
+    "@prisma-next/framework-components": "0.13.0-dev.2",
+    "@prisma-next/migration-tools": "0.13.0-dev.2",
+    "@prisma-next/mongo-codec": "0.13.0-dev.2",
+    "@prisma-next/mongo-contract": "0.13.0-dev.2",
+    "@prisma-next/mongo-lowering": "0.13.0-dev.2",
+    "@prisma-next/mongo-query-ast": "0.13.0-dev.2",
+    "@prisma-next/mongo-query-builder": "0.13.0-dev.2",
+    "@prisma-next/mongo-schema-ir": "0.13.0-dev.2",
+    "@prisma-next/mongo-value": "0.13.0-dev.2",
+    "@prisma-next/mongo-wire": "0.13.0-dev.2",
+    "@prisma-next/operations": "0.13.0-dev.2",
+    "@prisma-next/utils": "0.13.0-dev.2",
     "arktype": "^2.2.0"
   },
   "devDependencies": {
     "mongodb": "^7.2.0",
-    "@prisma-next/driver-mongo": "0.12.0",
-    "@prisma-next/errors": "0.12.0",
-    "@prisma-next/mongo-contract-psl": "0.12.0",
-    "@prisma-next/psl-parser": "0.12.0",
-    "@prisma-next/test-utils": "0.12.0",
-    "@prisma-next/tsconfig": "0.12.0",
-    "@prisma-next/tsdown": "0.12.0",
-    "mongodb-memory-server": "11.1.0",
-    "tsdown": "0.22.0",
+    "@prisma-next/driver-mongo": "0.13.0-dev.2",
+    "@prisma-next/errors": "0.13.0-dev.2",
+    "@prisma-next/mongo-contract-psl": "0.13.0-dev.2",
+    "@prisma-next/psl-parser": "0.13.0-dev.2",
+    "@prisma-next/test-utils": "0.13.0-dev.2",
+    "@prisma-next/tsconfig": "0.13.0-dev.2",
+    "@prisma-next/tsdown": "0.13.0-dev.2",
+    "mongodb-memory-server": "11.2.0",
+    "tsdown": "0.22.1",
     "typescript": "5.9.3",
-    "vitest": "4.1.6"
+    "vitest": "4.1.8"
   },
   "peerDependencies": {
     "mongodb": "^7.0.0",

package/src/core/marker-ledger-collection.ts

@@ -0,0 +1,32 @@
+/**
+ * Document shape of the `_prisma_migrations` collection, which stores both the
+ * per-space contract **markers** (`space` / `storageHash` / … / `invariants`)
+ * and the migration **ledger** entries (`type` / `edgeId` / … / `appliedAt`) —
+ * so the shape is their union. Declared once so the contract-free field
+ * accessor is typed without threading a contract, codecs, or paths at the call
+ * sites.
+ */
+export type MarkerLedgerDocShape = {
+  readonly _id: { readonly codecId: 'mongo/string@1'; readonly nullable: false };
+  // Marker fields
+  readonly space: { readonly codecId: 'mongo/string@1'; readonly nullable: false };
+  readonly storageHash: { readonly codecId: 'mongo/string@1'; readonly nullable: false };
+  readonly profileHash: { readonly codecId: 'mongo/string@1'; readonly nullable: false };
+  readonly contractJson: { readonly codecId: 'mongo/string@1'; readonly nullable: true };
+  readonly canonicalVersion: { readonly codecId: 'mongo/double@1'; readonly nullable: true };
+  readonly updatedAt: { readonly codecId: 'mongo/date@1'; readonly nullable: false };
+  readonly appTag: { readonly codecId: 'mongo/string@1'; readonly nullable: true };
+  readonly meta: { readonly codecId: 'mongo/document@1'; readonly nullable: true };
+  readonly invariants: { readonly codecId: 'mongo/array@1'; readonly nullable: false };
+  // Ledger fields
+  readonly type: { readonly codecId: 'mongo/string@1'; readonly nullable: false };
+  readonly edgeId: { readonly codecId: 'mongo/string@1'; readonly nullable: false };
+  readonly from: { readonly codecId: 'mongo/string@1'; readonly nullable: false };
+  readonly to: { readonly codecId: 'mongo/string@1'; readonly nullable: false };
+  readonly migrationName: { readonly codecId: 'mongo/string@1'; readonly nullable: false };
+  readonly migrationHash: { readonly codecId: 'mongo/string@1'; readonly nullable: false };
+  readonly operations: { readonly codecId: 'mongo/array@1'; readonly nullable: false };
+  readonly appliedAt: { readonly codecId: 'mongo/date@1'; readonly nullable: false };
+};
+
+export const MARKER_LEDGER_COLLECTION = '_prisma_migrations';

package/src/core/marker-ledger.ts

@@ -1,27 +1,11 @@
 import type { ContractMarkerRecord } from '@prisma-next/contract/types';
-import { parseMarkerRowSafely, withMarkerReadErrorHandling } from '@prisma-next/errors/execution';
-import {
-  RawAggregateCommand,
-  RawFindOneAndUpdateCommand,
-  RawInsertOneCommand,
-} from '@prisma-next/mongo-query-ast/execution';
+import { parseMarkerRowSafely } from '@prisma-next/errors/execution';
 import { type } from 'arktype';
-import type { Db, Document, UpdateFilter } from 'mongodb';
 
-const COLLECTION = '_prisma_migrations';
-const MONGO_MARKER_COLLECTION = `_prisma_migrations marker documents in ${COLLECTION}`;
+export const COLLECTION = '_prisma_migrations';
+export const MONGO_MARKER_COLLECTION = `_prisma_migrations marker documents in ${COLLECTION}`;
+export const MONGO_LEDGER_COLLECTION = `_prisma_migrations ledger documents in ${COLLECTION}`;
 
-/**
- * Marker doc shape.
- *
- * Same fields as the SQL marker row but camelCase + Mongo-native types:
- * `Date` is BSON-hydrated, `meta` is a native object (not JSON-stringified),
- * `_id` and any extension fields are tolerated. `invariants?` is optional —
- * absent reads as `[]` (schemaless default); present-but-malformed throws.
- *
- * `space` is required: every marker doc is keyed by its space id (`_id`)
- * and stamped with a matching `space` field for partitioned reads.
- */
 const MongoMarkerDocSchema = type({
   space: 'string',
   storageHash: 'string',
@@ -35,7 +19,7 @@ const MongoMarkerDocSchema = type({
   '+': 'delete',
 });
 
-function parseMongoMarkerDoc(doc: unknown): ContractMarkerRecord {
+export function parseMongoMarkerDoc(doc: unknown): ContractMarkerRecord {
   const result = MongoMarkerDocSchema(doc);
   if (result instanceof type.errors) {
     throw new Error(`Invalid marker doc on ${COLLECTION}: ${result.summary}`);
@@ -47,206 +31,14 @@ function parseMongoMarkerDoc(doc: unknown): ContractMarkerRecord {
     canonicalVersion: result.canonicalVersion ?? null,
     updatedAt: result.updatedAt ?? new Date(),
     appTag: result.appTag ?? null,
-    meta: (result.meta as Record<string, unknown> | null) ?? {},
+    meta: result.meta ?? {},
     invariants: result.invariants ?? [],
   };
 }
 
-function parseMongoMarkerDocSafely(doc: unknown, space: string): ContractMarkerRecord {
+export function parseMongoMarkerDocSafely(doc: unknown, space: string): ContractMarkerRecord {
   return parseMarkerRowSafely(doc, parseMongoMarkerDoc, {
     space,
     markerLocation: MONGO_MARKER_COLLECTION,
   });
 }
-
-async function executeAggregate(db: Db, cmd: RawAggregateCommand): Promise<Document[]> {
-  return db
-    .collection(cmd.collection)
-    .aggregate(cmd.pipeline as Record<string, unknown>[])
-    .toArray();
-}
-
-async function executeInsertOne(db: Db, cmd: RawInsertOneCommand): Promise<void> {
-  await db.collection(cmd.collection).insertOne(cmd.document);
-}
-
-async function executeFindOneAndUpdate(
-  db: Db,
-  cmd: RawFindOneAndUpdateCommand,
-): Promise<Document | null> {
-  // `cmd.update` is `Document | ReadonlyArray<Document>` per the AST. The
-  // MongoDB driver's `findOneAndUpdate` accepts the same shape under the
-  // type `UpdateFilter<T> | Document[]`. The driver's runtime path handles
-  // both forms identically — pipelines (array) and update docs (object).
-  // One cast to that union keeps the call single-arm.
-  return db
-    .collection(cmd.collection)
-    .findOneAndUpdate(cmd.filter, cmd.update as UpdateFilter<Document> | Document[], {
-      upsert: cmd.upsert,
-    });
-}
-
-/**
- * Reads the marker document for the given contract space, or returns
- * `null` if no marker has been written for that space yet. Each space
- * owns one row keyed by `_id: <space>` — see ADR 212 for the per-space
- * mechanism this enables.
- */
-export async function readMarker(db: Db, space: string): Promise<ContractMarkerRecord | null> {
-  const markerContext = { space, markerLocation: MONGO_MARKER_COLLECTION };
-  const docs = await withMarkerReadErrorHandling(
-    () =>
-      executeAggregate(
-        db,
-        new RawAggregateCommand(COLLECTION, [{ $match: { _id: space, space } }, { $limit: 1 }]),
-      ),
-    markerContext,
-  );
-  const doc = docs[0];
-  if (!doc) return null;
-  return parseMongoMarkerDocSafely(doc, space);
-}
-
-/**
- * Reads every marker doc in the collection (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 docs have been written yet.
- *
- * Marker docs are keyed by `_id: <space>` (string); ledger entries
- * live in the same collection but use a driver-generated `ObjectId`
- * `_id` plus `type: 'ledger'`. The filter selects string-keyed docs
- * with a `space` field, which excludes ledger entries by construction.
- */
-export async function readAllMarkers(db: Db): Promise<ReadonlyMap<string, ContractMarkerRecord>> {
-  const markerContext = { space: 'app', markerLocation: MONGO_MARKER_COLLECTION };
-  const docs = await withMarkerReadErrorHandling(
-    () =>
-      executeAggregate(
-        db,
-        new RawAggregateCommand(COLLECTION, [
-          {
-            $match: {
-              _id: { $type: 'string' },
-              space: { $type: 'string' },
-              $expr: { $eq: ['$_id', '$space'] },
-            },
-          },
-        ]),
-      ),
-    markerContext,
-  );
-  const out = new Map<string, ContractMarkerRecord>();
-  for (const doc of docs) {
-    const space = doc['space'];
-    /* v8 ignore next -- @preserve type-narrowing guard: the $match stage above filters on `space: { $type: 'string' }`, so this branch is unreachable at runtime. The check exists so the `out.set(space, ...)` call below can accept `string`. */
-    if (typeof space !== 'string') continue;
-    out.set(space, parseMongoMarkerDocSafely(doc, space));
-  }
-  return out;
-}
-
-export async function initMarker(
-  db: Db,
-  space: string,
-  destination: {
-    readonly storageHash: string;
-    readonly profileHash: string;
-    readonly invariants?: readonly string[];
-  },
-): Promise<void> {
-  const cmd = new RawInsertOneCommand(COLLECTION, {
-    _id: space,
-    space,
-    storageHash: destination.storageHash,
-    profileHash: destination.profileHash,
-    contractJson: null,
-    canonicalVersion: null,
-    updatedAt: new Date(),
-    appTag: null,
-    meta: {},
-    invariants: destination.invariants ?? [],
-  });
-  await executeInsertOne(db, cmd);
-}
-
-/**
- * Updates the marker doc for the given space atomically (CAS on
- * `expectedFrom`).
- *
- * `destination.invariants`:
- * - `undefined` → existing field left untouched.
- * - explicit value → merged into the existing field server-side via an
- *   aggregation pipeline (`$setUnion + $sortArray`), atomic at the
- *   document level. `[]` is a no-op merge.
- */
-export async function updateMarker(
-  db: Db,
-  space: string,
-  expectedFrom: string,
-  destination: {
-    readonly storageHash: string;
-    readonly profileHash: string;
-    readonly invariants?: readonly string[];
-  },
-): Promise<boolean> {
-  const setBase: Record<string, unknown> = {
-    storageHash: destination.storageHash,
-    profileHash: destination.profileHash,
-    updatedAt: new Date(),
-  };
-  // When invariants is supplied, use an aggregation pipeline so the
-  // merge runs server-side against the doc's current value (atomic, no
-  // read-then-write window). When omitted, a regular update doc keeps
-  // the field untouched.
-  const update: Document | Document[] =
-    destination.invariants === undefined
-      ? { $set: setBase }
-      : [
-          {
-            $set: {
-              ...setBase,
-              invariants: {
-                $sortArray: {
-                  input: { $setUnion: [{ $ifNull: ['$invariants', []] }, destination.invariants] },
-                  sortBy: 1,
-                },
-              },
-            },
-          },
-        ];
-  const cmd = new RawFindOneAndUpdateCommand(
-    COLLECTION,
-    { _id: space, space, storageHash: expectedFrom },
-    update,
-    false,
-  );
-  const result = await executeFindOneAndUpdate(db, cmd);
-  return result !== null;
-}
-
-/**
- * Appends a ledger entry for the given space. Ledger entries co-exist
- * with marker docs in the same collection; marker docs use `_id: <space>`
- * (string), ledger entries use `type: 'ledger'` plus a driver-generated
- * ObjectId. Reads partition the two by filter shape.
- *
- * The same `edgeId` may legitimately recur across different spaces (e.g.
- * a synthetic ∅→head edge on first apply), so the ledger key is
- * `(space, edgeId)` — the doc carries `space` for partitioned reads.
- */
-export async function writeLedgerEntry(
-  db: Db,
-  space: string,
-  entry: { readonly edgeId: string; readonly from: string; readonly to: string },
-): Promise<void> {
-  const cmd = new RawInsertOneCommand(COLLECTION, {
-    type: 'ledger',
-    space,
-    edgeId: entry.edgeId,
-    from: entry.from,
-    to: entry.to,
-    appliedAt: new Date(),
-  });
-  await executeInsertOne(db, cmd);
-}

package/src/core/mongo-control-adapter.ts

@@ -1,38 +1,143 @@
-import type { ContractMarkerRecord } from '@prisma-next/contract/types';
+import type { ContractMarkerRecord, LedgerEntryRecord } from '@prisma-next/contract/types';
+import { withMarkerReadErrorHandling } from '@prisma-next/errors/execution';
 import type { MongoControlAdapter } from '@prisma-next/family-mongo/control-adapter';
 import type { ControlDriverInstance } from '@prisma-next/framework-components/control';
+import { ledgerOriginFromStored } from '@prisma-next/migration-tools/ledger-origin';
+import type { MongoAdapter } from '@prisma-next/mongo-lowering';
+import {
+  type AnyMongoCommand,
+  MongoAggFieldRef,
+  MongoAggLiteral,
+  MongoAggOperator,
+  type MongoQueryPlan,
+} from '@prisma-next/mongo-query-ast/execution';
+import { expr, fn } from '@prisma-next/mongo-query-builder';
+import { collection } from '@prisma-next/mongo-query-builder/contract-free';
 import type { MongoSchemaIR } from '@prisma-next/mongo-schema-ir';
+import type { MongoValue } from '@prisma-next/mongo-value';
+import { blindCast } from '@prisma-next/utils/casts';
+import type { Document } from 'mongodb';
+import { createMongoAdapter } from '../mongo-adapter';
 import { introspectSchema } from './introspect-schema';
 import {
-  initMarker,
-  readAllMarkers,
-  readMarker,
-  updateMarker,
-  writeLedgerEntry,
+  MONGO_LEDGER_COLLECTION,
+  MONGO_MARKER_COLLECTION,
+  parseMongoMarkerDocSafely,
 } from './marker-ledger';
+import { MARKER_LEDGER_COLLECTION, type MarkerLedgerDocShape } from './marker-ledger-collection';
+import { isMongoControlDriver } from './mongo-control-driver';
 import { extractDb } from './runner-deps';
 
 /**
  * Mongo control adapter for control-plane operations like introspection
  * and marker-ledger CAS. Implements the family-level `MongoControlAdapter`
- * SPI by extracting the underlying `Db` from the framework-shaped driver
- * and forwarding to the wire-level helpers in this package.
+ * SPI. Every marker/ledger operation builds a canonical command inline via
+ * the contract-free fluent builder and dispatches it through the family
+ * adapter's lowering path (`createMongoAdapter().lower(plan, {})`) onto the
+ * Mongo wire transport (`driver.execute(wireCommand)`) — the same route SQL
+ * marker/ledger ops take through `adapter.lower()` → `driver.query()`.
  */
 export class MongoControlAdapterImpl implements MongoControlAdapter<'mongo'> {
   readonly familyId = 'mongo' as const;
   readonly targetId = 'mongo' as const;
+  readonly #adapter: MongoAdapter = createMongoAdapter();
+  readonly #markerLedgerCollection = collection<MarkerLedgerDocShape>(MARKER_LEDGER_COLLECTION);
+
+  async #execute(
+    driver: ControlDriverInstance<'mongo', 'mongo'>,
+    command: AnyMongoCommand,
+  ): Promise<Document[]> {
+    const plan: MongoQueryPlan = {
+      collection: MARKER_LEDGER_COLLECTION,
+      command,
+      meta: { target: 'mongo', targetFamily: 'mongo', storageHash: '', lane: 'control' },
+    };
+    const wireCommand = await this.#adapter.lower(plan, {});
+    if (!isMongoControlDriver(driver)) {
+      throw new Error(
+        'Mongo control adapter requires a Mongo control driver with an execute() transport. ' +
+          'Provide a MongoControlDriver from `@prisma-next/driver-mongo/control`.',
+      );
+    }
+    const rows: Document[] = [];
+    for await (const row of driver.execute<Document>(wireCommand)) {
+      rows.push(row);
+    }
+    return rows;
+  }
+
+  /**
+   * Server-side invariant-merge aggregation expression:
+   * `$sortArray({ input: $setUnion([$ifNull('$invariants', []), incoming]), sortBy: 1 })`.
+   *
+   * Built through the typed agg-expr layer — `fn.setUnion` plus the generic
+   * `MongoAggOperator` for `$ifNull` / `$sortArray` (neither has a named `fn`
+   * helper). Returns a `MongoAggOperator` that is passed directly to
+   * `f.stage.set({ invariants: ... })` in the update pipeline.
+   */
+  #invariantMergeExpr(incoming: readonly string[]): MongoAggOperator {
+    const existingOrEmpty = MongoAggOperator.of('$ifNull', [
+      MongoAggFieldRef.of('invariants'),
+      MongoAggLiteral.of([]),
+    ]);
+    const merged = fn.setUnion(
+      { _field: { codecId: 'mongo/array@1', nullable: false }, node: existingOrEmpty },
+      {
+        _field: { codecId: 'mongo/array@1', nullable: false },
+        node: MongoAggLiteral.of([...incoming]),
+      },
+    );
+    return MongoAggOperator.of('$sortArray', { input: merged.node, sortBy: MongoAggLiteral.of(1) });
+  }
 
   async readMarker(
     driver: ControlDriverInstance<'mongo', 'mongo'>,
     space: string,
   ): Promise<ContractMarkerRecord | null> {
-    return readMarker(extractDb(driver), space);
+    const markerContext = { space, markerLocation: MONGO_MARKER_COLLECTION };
+    const docs = await withMarkerReadErrorHandling(
+      () =>
+        this.#execute(
+          driver,
+          this.#markerLedgerCollection
+            .aggregate()
+            .match((f) => f._id.eq(space))
+            .match((f) => f.space.eq(space))
+            .limit(1)
+            .build(),
+        ),
+      markerContext,
+    );
+    const doc = docs[0];
+    if (!doc) return null;
+    return parseMongoMarkerDocSafely(doc, space);
   }
 
   async readAllMarkers(
     driver: ControlDriverInstance<'mongo', 'mongo'>,
   ): Promise<ReadonlyMap<string, ContractMarkerRecord>> {
-    return readAllMarkers(extractDb(driver));
+    const markerContext = { space: 'app', markerLocation: MONGO_MARKER_COLLECTION };
+    const docs = await withMarkerReadErrorHandling(
+      () =>
+        this.#execute(
+          driver,
+          this.#markerLedgerCollection
+            .aggregate()
+            .match((f) => f._id.type('string'))
+            .match((f) => f.space.type('string'))
+            .match((f) => expr(fn.eq(f._id, f.space)))
+            .build(),
+        ),
+      markerContext,
+    );
+    const out = new Map<string, ContractMarkerRecord>();
+    for (const doc of docs) {
+      const space = doc['space'];
+      /* v8 ignore next -- @preserve type-narrowing guard: the $match stage above filters on `space: { $type: 'string' }`, so this branch is unreachable at runtime. The check exists so the `out.set(space, ...)` call below can accept `string`. */
+      if (typeof space !== 'string') continue;
+      out.set(space, parseMongoMarkerDocSafely(doc, space));
+    }
+    return out;
   }
 
   async initMarker(
@@ -44,7 +149,19 @@ export class MongoControlAdapterImpl implements MongoControlAdapter<'mongo'> {
       readonly invariants?: readonly string[];
     },
   ): Promise<void> {
-    await initMarker(extractDb(driver), space, destination);
+    const document: Record<string, MongoValue> = {
+      _id: space,
+      space,
+      storageHash: destination.storageHash,
+      profileHash: destination.profileHash,
+      contractJson: null,
+      canonicalVersion: null,
+      updatedAt: new Date(),
+      appTag: null,
+      meta: {},
+      invariants: [...(destination.invariants ?? [])],
+    };
+    await this.#execute(driver, this.#markerLedgerCollection.insertOne(document));
   }
 
   async updateMarker(
@@ -57,15 +174,118 @@ export class MongoControlAdapterImpl implements MongoControlAdapter<'mongo'> {
       readonly invariants?: readonly string[];
     },
   ): Promise<boolean> {
-    return updateMarker(extractDb(driver), space, expectedFrom, destination);
+    const { invariants } = destination;
+    const docs = await this.#execute(
+      driver,
+      this.#markerLedgerCollection
+        .match((f) => f._id.eq(space))
+        .match((f) => f.space.eq(space))
+        .match((f) => f.storageHash.eq(expectedFrom))
+        .findOneAndUpdate(
+          (f) => [
+            f.stage.set(
+              invariants === undefined
+                ? {
+                    storageHash: MongoAggLiteral.of(destination.storageHash),
+                    profileHash: MongoAggLiteral.of(destination.profileHash),
+                    updatedAt: MongoAggLiteral.of(new Date()),
+                  }
+                : {
+                    storageHash: MongoAggLiteral.of(destination.storageHash),
+                    profileHash: MongoAggLiteral.of(destination.profileHash),
+                    updatedAt: MongoAggLiteral.of(new Date()),
+                    invariants: this.#invariantMergeExpr(invariants),
+                  },
+            ),
+          ],
+          { upsert: false },
+        ),
+    );
+    return docs.length > 0;
   }
 
   async writeLedgerEntry(
     driver: ControlDriverInstance<'mongo', 'mongo'>,
     space: string,
-    entry: { readonly edgeId: string; readonly from: string; readonly to: string },
+    entry: {
+      readonly edgeId: string;
+      readonly from: string;
+      readonly to: string;
+      readonly migrationName: string;
+      readonly migrationHash: string;
+      readonly operations: readonly unknown[];
+    },
   ): Promise<void> {
-    await writeLedgerEntry(extractDb(driver), space, entry);
+    const document: Record<string, MongoValue> = {
+      type: 'ledger',
+      space,
+      edgeId: entry.edgeId,
+      from: entry.from,
+      to: entry.to,
+      migrationName: entry.migrationName,
+      migrationHash: entry.migrationHash,
+      operations: blindCast<ReadonlyArray<MongoValue>, 'ledger operation docs are BSON values'>(
+        entry.operations,
+      ),
+      appliedAt: new Date(),
+    };
+    await this.#execute(driver, this.#markerLedgerCollection.insertOne(document));
+  }
+
+  async readLedger(
+    driver: ControlDriverInstance<'mongo', 'mongo'>,
+    space?: string,
+  ): Promise<readonly LedgerEntryRecord[]> {
+    const ledgerContext = { space: space ?? '*', markerLocation: MONGO_LEDGER_COLLECTION };
+    const chain = this.#markerLedgerCollection.aggregate().match((f) => f.type.eq('ledger'));
+    const command =
+      space === undefined
+        ? chain.sort({ _id: 1 }).build()
+        : chain
+            .match((f) => f.space.eq(space))
+            .sort({ _id: 1 })
+            .build();
+    const docs = await withMarkerReadErrorHandling(
+      () => this.#execute(driver, command),
+      ledgerContext,
+    );
+
+    const entries: LedgerEntryRecord[] = [];
+    for (const doc of docs) {
+      const migrationName = doc['migrationName'];
+      const migrationHash = doc['migrationHash'];
+      const from = doc['from'];
+      const to = doc['to'];
+      const docSpace = doc['space'];
+      if (typeof migrationName !== 'string' || typeof migrationHash !== 'string') {
+        continue;
+      }
+      if (typeof from !== 'string' || typeof to !== 'string') {
+        continue;
+      }
+      if (typeof docSpace !== 'string') {
+        continue;
+      }
+      const appliedAt = doc['appliedAt'];
+      const appliedAtDate =
+        appliedAt instanceof Date
+          ? appliedAt
+          : appliedAt !== undefined
+            ? new Date(String(appliedAt))
+            : new Date();
+      const operations = doc['operations'];
+      const opList = Array.isArray(operations) ? operations : [];
+      entries.push({
+        space: docSpace,
+        migrationName,
+        migrationHash,
+        from: ledgerOriginFromStored(from),
+        to,
+        appliedAt: appliedAtDate,
+        operationCount: opList.length,
+      });
+    }
+    return entries;
   }
 
   async introspectSchema(driver: ControlDriverInstance<'mongo', 'mongo'>): Promise<MongoSchemaIR> {