@prisma-next/mongo-runtime 0.5.0-dev.8 → 0.5.0-dev.9

package/README.md

@@ -2,18 +2,53 @@
 
 MongoDB runtime executor for Prisma Next.
 
+## Package Classification
+
+- **Domain**: mongo
+- **Layer**: runtime
+- **Plane**: runtime
+
+## Overview
+
+The Mongo runtime package implements the Mongo family runtime by extending the abstract `RuntimeCore` base class from `@prisma-next/framework-components/runtime` with Mongo-specific lowering and driver dispatch. It provides the public runtime API for MongoDB, layering Mongo concerns (adapter lowering and wire-command dispatch) on top of the shared middleware lifecycle.
+
 ## Responsibilities
 
 - **Runtime executor**: `createMongoRuntime()` composes adapter and driver into a `MongoRuntime` with a single `execute(plan)` entry point accepting `MongoQueryPlan<Row>` from `@prisma-next/mongo-query-ast`. Execution is one path for reads and writes: `adapter.lower(plan)` produces a wire command, then the driver runs it.
 - **Unified flow**: There is no separate `execute` vs `executeCommand`; all operations use `execute(plan)`.
-- **Lowering**: Happens in the adapter (`lower(plan)`), not inside the runtime.
-- **Lifecycle management**: Connection lifecycle via `close()`
+- **Lowering**: Happens in the adapter (`lower(plan)`), wrapped by the runtime's `lower` override into a `MongoExecutionPlan`.
+- **Middleware lifecycle inheritance**: `MongoRuntime` extends `RuntimeCore<MongoQueryPlan, MongoExecutionPlan, MongoMiddleware>` and inherits the `beforeExecute` / `onRow` / `afterExecute` lifecycle from the framework via `runWithMiddleware`. Mongo does **not** override `runBeforeCompile` (Mongo middleware has no `beforeCompile` hook today).
+- **Lifecycle management**: Connection lifecycle via `close()`.
 
 ## Dependencies
 
 - **Depends on**:
   - `@prisma-next/mongo-lowering` (`MongoAdapter`, `MongoDriver` interfaces)
   - `@prisma-next/mongo-query-ast` (`MongoQueryPlan`, `AnyMongoCommand` — the typed plan shape)
-  - `@prisma-next/runtime-executor` (`AsyncIterableResult` return type)
+  - `@prisma-next/framework-components` (`RuntimeCore` base class, `runWithMiddleware` helper, `RuntimeMiddleware` SPI, `AsyncIterableResult` return type)
 - **Depended on by**:
-  - Integration tests (`test/integration/test/mongo/`)
+  - Integration tests (`test/integration/test/mongo/` and `test/integration/test/cross-package/cross-family-middleware.test.ts`)
+
+## Architecture
+
+`MongoRuntimeImpl` extends `RuntimeCore<MongoQueryPlan, MongoExecutionPlan, MongoMiddleware>` and overrides:
+
+- `lower(plan)` — calls the adapter's `lower(plan)` and wraps the resulting wire command into a `MongoExecutionPlan`.
+- `runDriver(exec)` — dispatches the wire command to the Mongo driver via `driver.execute(exec.command)`.
+- `close()` — closes the underlying driver.
+
+The execution template (`execute(plan)` → `lower` → `runWithMiddleware` → `runDriver`) is inherited from `RuntimeCore`. The four inline middleware lifecycle loops (`beforeExecute`, `onRow`, `afterExecute`, plus the error-path `afterExecute`) that previously lived in `MongoRuntimeImpl.execute` are now delegated to the shared `runWithMiddleware` helper.
+
+```mermaid
+flowchart LR
+  Plan[MongoQueryPlan] --> Runtime[MongoRuntime]
+  Runtime -.extends.-> Core[RuntimeCore]
+  Runtime --> Adapter[MongoAdapter.lower]
+  Adapter --> Exec[MongoExecutionPlan]
+  Runtime --> Driver[MongoDriver.execute]
+```
+
+## Related Subsystems
+
+- **[Runtime & Middleware Framework](../../../../docs/architecture%20docs/subsystems/4.%20Runtime%20&%20Middleware%20Framework.md)** — Runtime execution pipeline
+- **[Adapters & Targets](../../../../docs/architecture%20docs/subsystems/5.%20Adapters%20&%20Targets.md)** — Adapter and driver responsibilities

package/dist/index.d.mts

@@ -1,14 +1,53 @@
-import { AfterExecuteResult, AsyncIterableResult, RuntimeMiddleware, RuntimeMiddlewareContext } from "@prisma-next/framework-components/runtime";
-import { MongoQueryPlan } from "@prisma-next/mongo-query-ast/execution";
+import { AfterExecuteResult, AsyncIterableResult, ExecutionPlan, RuntimeMiddleware, RuntimeMiddlewareContext } from "@prisma-next/framework-components/runtime";
+import { AnyMongoWireCommand } from "@prisma-next/mongo-wire";
 import { MongoAdapter, MongoDriver } from "@prisma-next/mongo-lowering";
+import { MongoQueryPlan } from "@prisma-next/mongo-query-ast/execution";
+
+//#region src/mongo-execution-plan.d.ts
 
+/**
+ * Mongo-domain execution plan: a query lowered to the wire-command shape
+ * that a Mongo driver can run.
+ *
+ * The plan carries:
+ * - `command` — the wire command (e.g. `InsertOneWireCommand`,
+ *   `AggregateWireCommand`) produced by `MongoAdapter.lower(plan)`
+ * - `meta` — family-agnostic plan metadata (target, lane, hashes, ...)
+ * - `_row` — phantom row type, propagated from the originating
+ *   `MongoQueryPlan`
+ *
+ * Extends the framework-level `ExecutionPlan<Row>` marker so generic SPIs
+ * (`RuntimeExecutor<MongoExecutionPlan>`,
+ * `RuntimeMiddleware<MongoExecutionPlan>`) can be parameterized over it.
+ *
+ * Lives in the runtime layer (alongside `MongoRuntime`) because the wire
+ * command shape lives in the transport layer (`@prisma-next/mongo-wire`),
+ * which the lanes layer (`mongo-query-ast`, where `MongoQueryPlan` lives)
+ * cannot depend on. M1 establishes this type; `MongoRuntime.execute` does
+ * not yet accept it as input — that adoption lands in M4.
+ */
+interface MongoExecutionPlan<Row = unknown> extends ExecutionPlan<Row> {
+  readonly command: AnyMongoWireCommand;
+}
+//#endregion
 //#region src/mongo-middleware.d.ts
 interface MongoMiddlewareContext extends RuntimeMiddlewareContext {}
-interface MongoMiddleware extends RuntimeMiddleware {
-  readonly familyId: 'mongo';
-  beforeExecute?(plan: MongoQueryPlan, ctx: MongoMiddlewareContext): Promise<void>;
-  onRow?(row: Record<string, unknown>, plan: MongoQueryPlan, ctx: MongoMiddlewareContext): Promise<void>;
-  afterExecute?(plan: MongoQueryPlan, result: AfterExecuteResult, ctx: MongoMiddlewareContext): Promise<void>;
+/**
+ * Mongo-domain middleware. Extends the framework `RuntimeMiddleware`
+ * parameterized over `MongoExecutionPlan` because `runWithMiddleware`
+ * (driven by `RuntimeCore`) invokes the lifecycle hooks with the
+ * post-lowering plan.
+ *
+ * `familyId` is optional so generic cross-family middleware (e.g.
+ * telemetry) — which carry no `familyId` — remain assignable. When
+ * present, it must be `'mongo'`; the runtime rejects mismatches at
+ * construction time via `checkMiddlewareCompatibility`.
+ */
+interface MongoMiddleware extends RuntimeMiddleware<MongoExecutionPlan> {
+  readonly familyId?: 'mongo';
+  beforeExecute?(plan: MongoExecutionPlan, ctx: MongoMiddlewareContext): Promise<void>;
+  onRow?(row: Record<string, unknown>, plan: MongoExecutionPlan, ctx: MongoMiddlewareContext): Promise<void>;
+  afterExecute?(plan: MongoExecutionPlan, result: AfterExecuteResult, ctx: MongoMiddlewareContext): Promise<void>;
 }
 //#endregion
 //#region src/mongo-runtime.d.ts
@@ -17,7 +56,7 @@ interface MongoRuntimeOptions {
   readonly driver: MongoDriver;
   readonly contract: unknown;
   readonly targetId: string;
-  readonly middleware?: readonly RuntimeMiddleware[];
+  readonly middleware?: readonly MongoMiddleware[];
   readonly mode?: 'strict' | 'permissive';
 }
 interface MongoRuntime {
@@ -26,5 +65,5 @@ interface MongoRuntime {
 }
 declare function createMongoRuntime(options: MongoRuntimeOptions): MongoRuntime;
 //#endregion
-export { type MongoMiddleware, type MongoMiddlewareContext, type MongoRuntime, type MongoRuntimeOptions, createMongoRuntime };
+export { type MongoExecutionPlan, type MongoMiddleware, type MongoMiddlewareContext, type MongoRuntime, type MongoRuntimeOptions, createMongoRuntime };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/mongo-middleware.ts","../src/mongo-runtime.ts"],"sourcesContent":[],"mappings":";;;;;UAOiB,sBAAA,SAA+B;UAE/B,eAAA,SAAwB;EAFxB,SAAA,QAAA,EAAA,OAAuB;EAEvB,aAAA,EAAA,IAAgB,EAEV,cAFU,EAAA,GAAA,EAEW,sBAFX,CAAA,EAEoC,OAFpC,CAAA,IAAA,CAAA;EAEV,KAAA,EAAA,GAAA,EAEd,MAFc,CAAA,MAAA,EAAA,OAAA,CAAA,EAAA,IAAA,EAGb,cAHa,EAAA,GAAA,EAId,sBAJc,CAAA,EAKlB,OALkB,CAAA,IAAA,CAAA;EAAqB,YAAA,EAAA,IAAA,EAOlC,cAPkC,EAAA,MAAA,EAQhC,kBARgC,EAAA,GAAA,EASnC,sBATmC,CAAA,EAUvC,OAVuC,CAAA,IAAA,CAAA;;;;UCK3B,mBAAA;EDTA,SAAA,OAAA,ECUG,YDVoB;EAEvB,SAAA,MAAA,ECSE,WDTc;EAEV,SAAA,QAAA,EAAA,OAAA;EAAqB,SAAA,QAAA,EAAA,MAAA;EAAyB,SAAA,UAAA,CAAA,EAAA,SCUpC,iBDVoC,EAAA;EAE5D,SAAA,IAAA,CAAA,EAAA,QAAA,GAAA,YAAA;;AAEA,UCUQ,YAAA,CDVR;EACJ,OAAA,CAAA,GAAA,CAAA,CAAA,IAAA,ECUgB,cDVhB,CCU+B,GDV/B,CAAA,CAAA,ECUsC,mBDVtC,CCU0D,GDV1D,CAAA;EAEK,KAAA,EAAA,ECSC,ODTD,CAAA,IAAA,CAAA;;AAED,iBCgGO,kBAAA,CDhGP,OAAA,ECgGmC,mBDhGnC,CAAA,ECgGyD,YDhGzD"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/mongo-execution-plan.ts","../src/mongo-middleware.ts","../src/mongo-runtime.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAwBA;;;;;;;;ACjBA;AAaA;;;;;;;;AAOK,UDHY,kBCGZ,CAAA,MAAA,OAAA,CAAA,SDHsD,aCGtD,CDHoE,GCGpE,CAAA,CAAA;EAEK,SAAA,OAAA,EDJU,mBCIV;;;;UAtBO,sBAAA,SAA+B;;;ADiBhD;;;;;;;;ACjBA;AAaiB,UAAA,eAAA,SAAwB,iBAAR,CAA0B,kBAA1B,CAAA,CAAA;EAA0B,SAAA,QAAA,CAAA,EAAA,OAAA;EAEpC,aAAA,EAAA,IAAA,EAAA,kBAAA,EAAA,GAAA,EAAyB,sBAAzB,CAAA,EAAkD,OAAlD,CAAA,IAAA,CAAA;EAAyB,KAAA,EAAA,GAAA,EAEvC,MAFuC,CAAA,MAAA,EAAA,OAAA,CAAA,EAAA,IAAA,EAGtC,kBAHsC,EAAA,GAAA,EAIvC,sBAJuC,CAAA,EAK3C,OAL2C,CAAA,IAAA,CAAA;EAAyB,YAAA,EAAA,IAAA,EAO/D,kBAP+D,EAAA,MAAA,EAQ7D,kBAR6D,EAAA,GAAA,EAShE,sBATgE,CAAA,EAUpE,OAVoE,CAAA,IAAA,CAAA;;;;UCVxD,mBAAA;oBACG;EFWH,SAAA,MAAA,EEVE,WFUgB;EAAsC,SAAA,QAAA,EAAA,OAAA;EACrD,SAAA,QAAA,EAAA,MAAA;EADuC,SAAA,UAAA,CAAA,EAAA,SEP1B,eFO0B,EAAA;EAAa,SAAA,IAAA,CAAA,EAAA,QAAA,GAAA,YAAA;;UEHvD,YAAA;qBACI,eAAe,OAAO,oBAAoB;EDf9C,KAAA,EAAA,ECgBN,ODhBM,CAAA,IAAA,CAAA;AAajB;AAA2D,iBCgD3C,kBAAA,CDhD2C,OAAA,ECgDf,mBDhDe,CAAA,ECgDO,YDhDP"}

package/dist/index.mjs

@@ -1,77 +1,38 @@
-import { AsyncIterableResult, checkMiddlewareCompatibility } from "@prisma-next/framework-components/runtime";
+import { RuntimeCore, checkMiddlewareCompatibility } from "@prisma-next/framework-components/runtime";
 
 //#region src/mongo-runtime.ts
 function noop() {}
-function now() {
-	return Date.now();
-}
-var MongoRuntimeImpl = class {
+var MongoRuntimeImpl = class extends RuntimeCore {
 	#adapter;
 	#driver;
-	#middleware;
-	#middlewareContext;
 	constructor(options) {
-		this.#adapter = options.adapter;
-		this.#driver = options.driver;
 		const middleware = options.middleware ? [...options.middleware] : [];
 		for (const mw of middleware) checkMiddlewareCompatibility(mw, "mongo", options.targetId);
-		this.#middleware = middleware;
-		this.#middlewareContext = {
+		const ctx = {
 			contract: options.contract,
 			mode: options.mode ?? "strict",
-			now,
+			now: () => Date.now(),
 			log: {
 				info: noop,
 				warn: noop,
 				error: noop
 			}
 		};
+		super({
+			middleware,
+			ctx
+		});
+		this.#adapter = options.adapter;
+		this.#driver = options.driver;
 	}
-	execute(plan) {
-		const adapter = this.#adapter;
-		const driver = this.#driver;
-		const middleware = this.#middleware;
-		const ctx = this.#middlewareContext;
-		const iterator = async function* () {
-			const startedAt = ctx.now();
-			let rowCount = 0;
-			let completed = false;
-			let failed = false;
-			try {
-				for (const mw of middleware) if (mw.beforeExecute) await mw.beforeExecute(plan, ctx);
-				const wireCommand = await adapter.lower(plan);
-				for await (const row of driver.execute(wireCommand)) {
-					for (const mw of middleware) if (mw.onRow) await mw.onRow(row, plan, ctx);
-					rowCount++;
-					yield row;
-				}
-				completed = true;
-			} catch (error) {
-				failed = true;
-				throw error;
-			} finally {
-				const latencyMs = ctx.now() - startedAt;
-				for (const mw of middleware) {
-					if (!mw.afterExecute) continue;
-					if (failed) {
-						try {
-							await mw.afterExecute(plan, {
-								rowCount,
-								latencyMs,
-								completed
-							}, ctx);
-						} catch {}
-						continue;
-					}
-					await mw.afterExecute(plan, {
-						rowCount,
-						latencyMs,
-						completed
-					}, ctx);
-				}
-			}
+	async lower(plan) {
+		return {
+			command: await this.#adapter.lower(plan),
+			meta: plan.meta
 		};
-		return new AsyncIterableResult(iterator());
+	}
+	runDriver(exec) {
+		return this.#driver.execute(exec.command);
 	}
 	async close() {
 		await this.#driver.close();

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["#adapter","#driver","#middleware","#middlewareContext"],"sources":["../src/mongo-runtime.ts"],"sourcesContent":["import type {\n  RuntimeMiddleware,\n  RuntimeMiddlewareContext,\n} from '@prisma-next/framework-components/runtime';\nimport {\n  AsyncIterableResult,\n  checkMiddlewareCompatibility,\n} from '@prisma-next/framework-components/runtime';\nimport type { MongoAdapter, MongoDriver } from '@prisma-next/mongo-lowering';\nimport type { MongoQueryPlan } from '@prisma-next/mongo-query-ast/execution';\n\nfunction noop() {}\nfunction now() {\n  return Date.now();\n}\n\nexport interface MongoRuntimeOptions {\n  readonly adapter: MongoAdapter;\n  readonly driver: MongoDriver;\n  readonly contract: unknown;\n  readonly targetId: string;\n  readonly middleware?: readonly RuntimeMiddleware[];\n  readonly mode?: 'strict' | 'permissive';\n}\n\nexport interface MongoRuntime {\n  execute<Row>(plan: MongoQueryPlan<Row>): AsyncIterableResult<Row>;\n  close(): Promise<void>;\n}\n\nclass MongoRuntimeImpl implements MongoRuntime {\n  readonly #adapter: MongoAdapter;\n  readonly #driver: MongoDriver;\n  readonly #middleware: readonly RuntimeMiddleware[];\n  readonly #middlewareContext: RuntimeMiddlewareContext;\n\n  constructor(options: MongoRuntimeOptions) {\n    this.#adapter = options.adapter;\n    this.#driver = options.driver;\n\n    const middleware = options.middleware ? [...options.middleware] : [];\n    for (const mw of middleware) {\n      checkMiddlewareCompatibility(mw, 'mongo', options.targetId);\n    }\n    this.#middleware = middleware;\n\n    this.#middlewareContext = {\n      contract: options.contract,\n      mode: options.mode ?? 'strict',\n      now,\n      log: { info: noop, warn: noop, error: noop },\n    };\n  }\n\n  execute<Row>(plan: MongoQueryPlan<Row>): AsyncIterableResult<Row> {\n    const adapter = this.#adapter;\n    const driver = this.#driver;\n    const middleware = this.#middleware;\n    const ctx = this.#middlewareContext;\n\n    const iterator = async function* (): AsyncGenerator<Row, void, unknown> {\n      const startedAt = ctx.now();\n      let rowCount = 0;\n      let completed = false;\n      let failed = false;\n\n      try {\n        for (const mw of middleware) {\n          if (mw.beforeExecute) {\n            await mw.beforeExecute(plan, ctx);\n          }\n        }\n\n        const wireCommand = await adapter.lower(plan);\n\n        for await (const row of driver.execute<Row>(wireCommand)) {\n          for (const mw of middleware) {\n            if (mw.onRow) {\n              await mw.onRow(row as Record<string, unknown>, plan, ctx);\n            }\n          }\n          rowCount++;\n          yield row;\n        }\n\n        completed = true;\n      } catch (error) {\n        failed = true;\n        throw error;\n      } finally {\n        const latencyMs = ctx.now() - startedAt;\n        for (const mw of middleware) {\n          if (!mw.afterExecute) continue;\n\n          if (failed) {\n            try {\n              await mw.afterExecute(plan, { rowCount, latencyMs, completed }, ctx);\n            } catch {\n              // Ignore errors from afterExecute during error handling\n            }\n            continue;\n          }\n\n          await mw.afterExecute(plan, { rowCount, latencyMs, completed }, ctx);\n        }\n      }\n    };\n\n    return new AsyncIterableResult(iterator());\n  }\n\n  async close(): Promise<void> {\n    await this.#driver.close();\n  }\n}\n\nexport function createMongoRuntime(options: MongoRuntimeOptions): MongoRuntime {\n  return new MongoRuntimeImpl(options);\n}\n"],"mappings":";;;AAWA,SAAS,OAAO;AAChB,SAAS,MAAM;AACb,QAAO,KAAK,KAAK;;AAiBnB,IAAM,mBAAN,MAA+C;CAC7C,CAASA;CACT,CAASC;CACT,CAASC;CACT,CAASC;CAET,YAAY,SAA8B;AACxC,QAAKH,UAAW,QAAQ;AACxB,QAAKC,SAAU,QAAQ;EAEvB,MAAM,aAAa,QAAQ,aAAa,CAAC,GAAG,QAAQ,WAAW,GAAG,EAAE;AACpE,OAAK,MAAM,MAAM,WACf,8BAA6B,IAAI,SAAS,QAAQ,SAAS;AAE7D,QAAKC,aAAc;AAEnB,QAAKC,oBAAqB;GACxB,UAAU,QAAQ;GAClB,MAAM,QAAQ,QAAQ;GACtB;GACA,KAAK;IAAE,MAAM;IAAM,MAAM;IAAM,OAAO;IAAM;GAC7C;;CAGH,QAAa,MAAqD;EAChE,MAAM,UAAU,MAAKH;EACrB,MAAM,SAAS,MAAKC;EACpB,MAAM,aAAa,MAAKC;EACxB,MAAM,MAAM,MAAKC;EAEjB,MAAM,WAAW,mBAAuD;GACtE,MAAM,YAAY,IAAI,KAAK;GAC3B,IAAI,WAAW;GACf,IAAI,YAAY;GAChB,IAAI,SAAS;AAEb,OAAI;AACF,SAAK,MAAM,MAAM,WACf,KAAI,GAAG,cACL,OAAM,GAAG,cAAc,MAAM,IAAI;IAIrC,MAAM,cAAc,MAAM,QAAQ,MAAM,KAAK;AAE7C,eAAW,MAAM,OAAO,OAAO,QAAa,YAAY,EAAE;AACxD,UAAK,MAAM,MAAM,WACf,KAAI,GAAG,MACL,OAAM,GAAG,MAAM,KAAgC,MAAM,IAAI;AAG7D;AACA,WAAM;;AAGR,gBAAY;YACL,OAAO;AACd,aAAS;AACT,UAAM;aACE;IACR,MAAM,YAAY,IAAI,KAAK,GAAG;AAC9B,SAAK,MAAM,MAAM,YAAY;AAC3B,SAAI,CAAC,GAAG,aAAc;AAEtB,SAAI,QAAQ;AACV,UAAI;AACF,aAAM,GAAG,aAAa,MAAM;QAAE;QAAU;QAAW;QAAW,EAAE,IAAI;cAC9D;AAGR;;AAGF,WAAM,GAAG,aAAa,MAAM;MAAE;MAAU;MAAW;MAAW,EAAE,IAAI;;;;AAK1E,SAAO,IAAI,oBAAoB,UAAU,CAAC;;CAG5C,MAAM,QAAuB;AAC3B,QAAM,MAAKF,OAAQ,OAAO;;;AAI9B,SAAgB,mBAAmB,SAA4C;AAC7E,QAAO,IAAI,iBAAiB,QAAQ"}
+{"version":3,"file":"index.mjs","names":["#adapter","#driver","ctx: MongoMiddlewareContext"],"sources":["../src/mongo-runtime.ts"],"sourcesContent":["import type { AsyncIterableResult } from '@prisma-next/framework-components/runtime';\nimport {\n  checkMiddlewareCompatibility,\n  RuntimeCore,\n} from '@prisma-next/framework-components/runtime';\nimport type { MongoAdapter, MongoDriver } from '@prisma-next/mongo-lowering';\nimport type { MongoQueryPlan } from '@prisma-next/mongo-query-ast/execution';\nimport type { MongoExecutionPlan } from './mongo-execution-plan';\nimport type { MongoMiddleware, MongoMiddlewareContext } from './mongo-middleware';\n\nfunction noop() {}\n\nexport interface MongoRuntimeOptions {\n  readonly adapter: MongoAdapter;\n  readonly driver: MongoDriver;\n  readonly contract: unknown;\n  readonly targetId: string;\n  readonly middleware?: readonly MongoMiddleware[];\n  readonly mode?: 'strict' | 'permissive';\n}\n\nexport interface MongoRuntime {\n  execute<Row>(plan: MongoQueryPlan<Row>): AsyncIterableResult<Row>;\n  close(): Promise<void>;\n}\n\nclass MongoRuntimeImpl\n  extends RuntimeCore<MongoQueryPlan, MongoExecutionPlan, MongoMiddleware>\n  implements MongoRuntime\n{\n  readonly #adapter: MongoAdapter;\n  readonly #driver: MongoDriver;\n\n  constructor(options: MongoRuntimeOptions) {\n    const middleware = options.middleware ? [...options.middleware] : [];\n    for (const mw of middleware) {\n      checkMiddlewareCompatibility(mw, 'mongo', options.targetId);\n    }\n\n    const ctx: MongoMiddlewareContext = {\n      contract: options.contract,\n      mode: options.mode ?? 'strict',\n      now: () => Date.now(),\n      log: { info: noop, warn: noop, error: noop },\n    };\n\n    super({ middleware, ctx });\n\n    this.#adapter = options.adapter;\n    this.#driver = options.driver;\n  }\n\n  protected override async lower(plan: MongoQueryPlan): Promise<MongoExecutionPlan> {\n    return {\n      command: await this.#adapter.lower(plan),\n      meta: plan.meta,\n    };\n  }\n\n  protected override runDriver(exec: MongoExecutionPlan): AsyncIterable<Record<string, unknown>> {\n    return this.#driver.execute<Record<string, unknown>>(exec.command);\n  }\n\n  override async close(): Promise<void> {\n    await this.#driver.close();\n  }\n}\n\nexport function createMongoRuntime(options: MongoRuntimeOptions): MongoRuntime {\n  return new MongoRuntimeImpl(options);\n}\n"],"mappings":";;;AAUA,SAAS,OAAO;AAgBhB,IAAM,mBAAN,cACU,YAEV;CACE,CAASA;CACT,CAASC;CAET,YAAY,SAA8B;EACxC,MAAM,aAAa,QAAQ,aAAa,CAAC,GAAG,QAAQ,WAAW,GAAG,EAAE;AACpE,OAAK,MAAM,MAAM,WACf,8BAA6B,IAAI,SAAS,QAAQ,SAAS;EAG7D,MAAMC,MAA8B;GAClC,UAAU,QAAQ;GAClB,MAAM,QAAQ,QAAQ;GACtB,WAAW,KAAK,KAAK;GACrB,KAAK;IAAE,MAAM;IAAM,MAAM;IAAM,OAAO;IAAM;GAC7C;AAED,QAAM;GAAE;GAAY;GAAK,CAAC;AAE1B,QAAKF,UAAW,QAAQ;AACxB,QAAKC,SAAU,QAAQ;;CAGzB,MAAyB,MAAM,MAAmD;AAChF,SAAO;GACL,SAAS,MAAM,MAAKD,QAAS,MAAM,KAAK;GACxC,MAAM,KAAK;GACZ;;CAGH,AAAmB,UAAU,MAAkE;AAC7F,SAAO,MAAKC,OAAQ,QAAiC,KAAK,QAAQ;;CAGpE,MAAe,QAAuB;AACpC,QAAM,MAAKA,OAAQ,OAAO;;;AAI9B,SAAgB,mBAAmB,SAA4C;AAC7E,QAAO,IAAI,iBAAiB,QAAQ"}

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@prisma-next/mongo-runtime",
-  "version": "0.5.0-dev.8",
+  "version": "0.5.0-dev.9",
   "type": "module",
   "sideEffects": false,
   "description": "MongoDB runtime implementation for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.5.0-dev.8",
-    "@prisma-next/framework-components": "0.5.0-dev.8",
-    "@prisma-next/mongo-lowering": "0.5.0-dev.8",
-    "@prisma-next/mongo-query-ast": "0.5.0-dev.8"
+    "@prisma-next/mongo-lowering": "0.5.0-dev.9",
+    "@prisma-next/contract": "0.5.0-dev.9",
+    "@prisma-next/framework-components": "0.5.0-dev.9",
+    "@prisma-next/mongo-query-ast": "0.5.0-dev.9",
+    "@prisma-next/mongo-wire": "0.5.0-dev.9"
   },
   "devDependencies": {
     "mongodb": "^6.16.0",
@@ -16,19 +17,18 @@
     "tsdown": "0.18.4",
     "typescript": "5.9.3",
     "vitest": "4.0.17",
-    "@prisma-next/adapter-mongo": "0.5.0-dev.8",
-    "@prisma-next/middleware-telemetry": "0.5.0-dev.8",
-    "@prisma-next/mongo-contract-ts": "0.5.0-dev.8",
-    "@prisma-next/family-mongo": "0.5.0-dev.8",
-    "@prisma-next/runtime-executor": "0.5.0-dev.8",
-    "@prisma-next/mongo-value": "0.5.0-dev.8",
-    "@prisma-next/driver-mongo": "0.5.0-dev.8",
-    "@prisma-next/mongo-query-builder": "0.5.0-dev.8",
-    "@prisma-next/target-mongo": "0.5.0-dev.8",
-    "@prisma-next/mongo-contract": "0.5.0-dev.8",
-    "@prisma-next/test-utils": "0.0.1",
+    "@prisma-next/middleware-telemetry": "0.5.0-dev.9",
+    "@prisma-next/adapter-mongo": "0.5.0-dev.9",
+    "@prisma-next/family-mongo": "0.5.0-dev.9",
+    "@prisma-next/mongo-contract-ts": "0.5.0-dev.9",
+    "@prisma-next/mongo-query-builder": "0.5.0-dev.9",
+    "@prisma-next/mongo-value": "0.5.0-dev.9",
+    "@prisma-next/driver-mongo": "0.5.0-dev.9",
+    "@prisma-next/mongo-contract": "0.5.0-dev.9",
+    "@prisma-next/target-mongo": "0.5.0-dev.9",
+    "@prisma-next/tsconfig": "0.0.0",
     "@prisma-next/tsdown": "0.0.0",
-    "@prisma-next/tsconfig": "0.0.0"
+    "@prisma-next/test-utils": "0.0.1"
   },
   "files": [
     "dist",

package/src/exports/index.ts

@@ -1,3 +1,4 @@
+export type { MongoExecutionPlan } from '../mongo-execution-plan';
 export type { MongoMiddleware, MongoMiddlewareContext } from '../mongo-middleware';
 export type { MongoRuntime, MongoRuntimeOptions } from '../mongo-runtime';
 export { createMongoRuntime } from '../mongo-runtime';

package/src/mongo-execution-plan.ts

@@ -0,0 +1,27 @@
+import type { ExecutionPlan } from '@prisma-next/framework-components/runtime';
+import type { AnyMongoWireCommand } from '@prisma-next/mongo-wire';
+
+/**
+ * Mongo-domain execution plan: a query lowered to the wire-command shape
+ * that a Mongo driver can run.
+ *
+ * The plan carries:
+ * - `command` — the wire command (e.g. `InsertOneWireCommand`,
+ *   `AggregateWireCommand`) produced by `MongoAdapter.lower(plan)`
+ * - `meta` — family-agnostic plan metadata (target, lane, hashes, ...)
+ * - `_row` — phantom row type, propagated from the originating
+ *   `MongoQueryPlan`
+ *
+ * Extends the framework-level `ExecutionPlan<Row>` marker so generic SPIs
+ * (`RuntimeExecutor<MongoExecutionPlan>`,
+ * `RuntimeMiddleware<MongoExecutionPlan>`) can be parameterized over it.
+ *
+ * Lives in the runtime layer (alongside `MongoRuntime`) because the wire
+ * command shape lives in the transport layer (`@prisma-next/mongo-wire`),
+ * which the lanes layer (`mongo-query-ast`, where `MongoQueryPlan` lives)
+ * cannot depend on. M1 establishes this type; `MongoRuntime.execute` does
+ * not yet accept it as input — that adoption lands in M4.
+ */
+export interface MongoExecutionPlan<Row = unknown> extends ExecutionPlan<Row> {
+  readonly command: AnyMongoWireCommand;
+}

package/src/mongo-middleware.ts

@@ -3,20 +3,31 @@ import type {
   RuntimeMiddleware,
   RuntimeMiddlewareContext,
 } from '@prisma-next/framework-components/runtime';
-import type { MongoQueryPlan } from '@prisma-next/mongo-query-ast/execution';
+import type { MongoExecutionPlan } from './mongo-execution-plan';
 
 export interface MongoMiddlewareContext extends RuntimeMiddlewareContext {}
 
-export interface MongoMiddleware extends RuntimeMiddleware {
-  readonly familyId: 'mongo';
-  beforeExecute?(plan: MongoQueryPlan, ctx: MongoMiddlewareContext): Promise<void>;
+/**
+ * Mongo-domain middleware. Extends the framework `RuntimeMiddleware`
+ * parameterized over `MongoExecutionPlan` because `runWithMiddleware`
+ * (driven by `RuntimeCore`) invokes the lifecycle hooks with the
+ * post-lowering plan.
+ *
+ * `familyId` is optional so generic cross-family middleware (e.g.
+ * telemetry) — which carry no `familyId` — remain assignable. When
+ * present, it must be `'mongo'`; the runtime rejects mismatches at
+ * construction time via `checkMiddlewareCompatibility`.
+ */
+export interface MongoMiddleware extends RuntimeMiddleware<MongoExecutionPlan> {
+  readonly familyId?: 'mongo';
+  beforeExecute?(plan: MongoExecutionPlan, ctx: MongoMiddlewareContext): Promise<void>;
   onRow?(
     row: Record<string, unknown>,
-    plan: MongoQueryPlan,
+    plan: MongoExecutionPlan,
     ctx: MongoMiddlewareContext,
   ): Promise<void>;
   afterExecute?(
-    plan: MongoQueryPlan,
+    plan: MongoExecutionPlan,
     result: AfterExecuteResult,
     ctx: MongoMiddlewareContext,
   ): Promise<void>;

package/src/mongo-runtime.ts

@@ -1,25 +1,21 @@
-import type {
-  RuntimeMiddleware,
-  RuntimeMiddlewareContext,
-} from '@prisma-next/framework-components/runtime';
+import type { AsyncIterableResult } from '@prisma-next/framework-components/runtime';
 import {
-  AsyncIterableResult,
   checkMiddlewareCompatibility,
+  RuntimeCore,
 } from '@prisma-next/framework-components/runtime';
 import type { MongoAdapter, MongoDriver } from '@prisma-next/mongo-lowering';
 import type { MongoQueryPlan } from '@prisma-next/mongo-query-ast/execution';
+import type { MongoExecutionPlan } from './mongo-execution-plan';
+import type { MongoMiddleware, MongoMiddlewareContext } from './mongo-middleware';
 
 function noop() {}
-function now() {
-  return Date.now();
-}
 
 export interface MongoRuntimeOptions {
   readonly adapter: MongoAdapter;
   readonly driver: MongoDriver;
   readonly contract: unknown;
   readonly targetId: string;
-  readonly middleware?: readonly RuntimeMiddleware[];
+  readonly middleware?: readonly MongoMiddleware[];
   readonly mode?: 'strict' | 'permissive';
 }
 
@@ -28,88 +24,44 @@ export interface MongoRuntime {
   close(): Promise<void>;
 }
 
-class MongoRuntimeImpl implements MongoRuntime {
+class MongoRuntimeImpl
+  extends RuntimeCore<MongoQueryPlan, MongoExecutionPlan, MongoMiddleware>
+  implements MongoRuntime
+{
   readonly #adapter: MongoAdapter;
   readonly #driver: MongoDriver;
-  readonly #middleware: readonly RuntimeMiddleware[];
-  readonly #middlewareContext: RuntimeMiddlewareContext;
 
   constructor(options: MongoRuntimeOptions) {
-    this.#adapter = options.adapter;
-    this.#driver = options.driver;
-
     const middleware = options.middleware ? [...options.middleware] : [];
     for (const mw of middleware) {
       checkMiddlewareCompatibility(mw, 'mongo', options.targetId);
     }
-    this.#middleware = middleware;
 
-    this.#middlewareContext = {
+    const ctx: MongoMiddlewareContext = {
       contract: options.contract,
       mode: options.mode ?? 'strict',
-      now,
+      now: () => Date.now(),
       log: { info: noop, warn: noop, error: noop },
     };
-  }
-
-  execute<Row>(plan: MongoQueryPlan<Row>): AsyncIterableResult<Row> {
-    const adapter = this.#adapter;
-    const driver = this.#driver;
-    const middleware = this.#middleware;
-    const ctx = this.#middlewareContext;
-
-    const iterator = async function* (): AsyncGenerator<Row, void, unknown> {
-      const startedAt = ctx.now();
-      let rowCount = 0;
-      let completed = false;
-      let failed = false;
 
-      try {
-        for (const mw of middleware) {
-          if (mw.beforeExecute) {
-            await mw.beforeExecute(plan, ctx);
-          }
-        }
+    super({ middleware, ctx });
 
-        const wireCommand = await adapter.lower(plan);
-
-        for await (const row of driver.execute<Row>(wireCommand)) {
-          for (const mw of middleware) {
-            if (mw.onRow) {
-              await mw.onRow(row as Record<string, unknown>, plan, ctx);
-            }
-          }
-          rowCount++;
-          yield row;
-        }
-
-        completed = true;
-      } catch (error) {
-        failed = true;
-        throw error;
-      } finally {
-        const latencyMs = ctx.now() - startedAt;
-        for (const mw of middleware) {
-          if (!mw.afterExecute) continue;
-
-          if (failed) {
-            try {
-              await mw.afterExecute(plan, { rowCount, latencyMs, completed }, ctx);
-            } catch {
-              // Ignore errors from afterExecute during error handling
-            }
-            continue;
-          }
+    this.#adapter = options.adapter;
+    this.#driver = options.driver;
+  }
 
-          await mw.afterExecute(plan, { rowCount, latencyMs, completed }, ctx);
-        }
-      }
+  protected override async lower(plan: MongoQueryPlan): Promise<MongoExecutionPlan> {
+    return {
+      command: await this.#adapter.lower(plan),
+      meta: plan.meta,
     };
+  }
 
-    return new AsyncIterableResult(iterator());
+  protected override runDriver(exec: MongoExecutionPlan): AsyncIterable<Record<string, unknown>> {
+    return this.#driver.execute<Record<string, unknown>>(exec.command);
   }
 
-  async close(): Promise<void> {
+  override async close(): Promise<void> {
     await this.#driver.close();
   }
 }