@prisma-next/mongo-runtime 0.5.0-dev.30 → 0.5.0-dev.41

package/README.md

@@ -12,9 +12,42 @@ MongoDB runtime executor for Prisma Next.
 
 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.
 
+## Usage
+
+The runtime takes a **`MongoExecutionContext`** built from a **`MongoExecutionStack`** (target + adapter + optional driver + extension packs). The context aggregates codec contributions from each stack component into a single registry — users do not construct or thread a `MongoCodecRegistry` themselves. This mirrors the SQL pattern (see `packages/2-sql/5-runtime/src/sql-context.ts`).
+
+Typed reads that attach a **`resultShape`** on the query plan are decoded after the driver yields each row: scalars and scalar arrays run through their `codecId` entries; `kind: 'unknown'` subtrees are passed through unchanged; plans without `resultShape` (for example raw commands) leave rows as the driver returned them.
+
+Example:
+
+```ts
+import mongoRuntimeAdapter from '@prisma-next/adapter-mongo/runtime';
+import { createMongoDriver } from '@prisma-next/driver-mongo';
+import {
+  createMongoExecutionContext,
+  createMongoExecutionStack,
+  createMongoRuntime,
+} from '@prisma-next/mongo-runtime';
+import mongoRuntimeTarget from '@prisma-next/target-mongo/runtime';
+
+const stack = createMongoExecutionStack({
+  target: mongoRuntimeTarget,
+  adapter: mongoRuntimeAdapter,
+});
+const context = createMongoExecutionContext({ contract, stack });
+
+const runtime = createMongoRuntime({
+  context,
+  driver: await createMongoDriver(url, dbName),
+});
+```
+
+Custom or third-party codecs (encryption, vendor scalars) are contributed via an extension-pack descriptor whose `codecInstances` list includes them; `createMongoExecutionContext` folds them into the same registry. Duplicate codec ids across contributors throw `RUNTIME.DUPLICATE_CODEC` at composition time.
+
 ## 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.
+- **Stack/context composition**: `createMongoExecutionStack` and `createMongoExecutionContext` mirror SQL's `createSqlExecutionStack` / `createExecutionContext`. The context aggregates codec contributions from `[stack.target, stack.adapter, ...stack.extensionPacks]` into a single `MongoCodecRegistry`.
+- **Runtime executor**: `createMongoRuntime({ context, driver, ... })` composes context and driver into a `MongoRuntime` with a single `execute(plan)` entry point accepting `MongoQueryPlan<Row>` from `@prisma-next/mongo-query-ast`. The adapter is reached via `context.stack.adapter` (instantiated lazily through the stack's `create(stack)` factory). Execution lowers the plan through the adapter, runs the wire command on the driver, then **optionally decodes** each row when `plan.resultShape` is present.
 - **Unified flow**: There is no separate `execute` vs `executeCommand`; all operations use `execute(plan)`.
 - **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).
@@ -23,9 +56,10 @@ The Mongo runtime package implements the Mongo family runtime by extending the a
 ## Dependencies
 
 - **Depends on**:
+  - `@prisma-next/mongo-codec` (`MongoCodecRegistry` for decode)
   - `@prisma-next/mongo-lowering` (`MongoAdapter`, `MongoDriver` interfaces)
   - `@prisma-next/mongo-query-ast` (`MongoQueryPlan`, `AnyMongoCommand` — the typed plan shape)
-  - `@prisma-next/framework-components` (`RuntimeCore` base class, `runWithMiddleware` helper, `RuntimeMiddleware` SPI, `AsyncIterableResult` return type)
+  - `@prisma-next/framework-components` (`RuntimeCore` base class, `runWithMiddleware` helper, `RuntimeMiddleware` SPI, `AsyncIterableResult` return type, `RuntimeAdapterDescriptor` / `ExecutionStack` for the stack composition model)
 - **Depended on by**:
   - Integration tests (`test/integration/test/mongo/` and `test/integration/test/cross-package/cross-family-middleware.test.ts`)
 
@@ -37,7 +71,9 @@ The Mongo runtime package implements the Mongo family runtime by extending the a
 - `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.
+`MongoRuntimeImpl` extends `RuntimeCore` but **overrides `execute`** so that after `runWithMiddleware` yields a raw driver row, the runtime can **`decodeMongoRow`** when the lowered plan carries `resultShape`, then yield the decoded row. `lower(plan)` copies `resultShape` from the query plan onto `MongoExecutionPlan`. Middleware `onRow` still sees the raw driver row (decode happens after the middleware loop for that row, before the consumer receives the value).
+
+The execution template is: `lower` → `runWithMiddleware` (driver loop + middleware) → **per-row decode when `exec.resultShape` is set** → yield to consumer.
 
 ```mermaid
 flowchart LR

package/dist/index.d.mts

@@ -1,7 +1,9 @@
+import { RuntimeAdapterDescriptor, RuntimeAdapterInstance, RuntimeDriverDescriptor, RuntimeDriverInstance, RuntimeExtensionDescriptor, RuntimeExtensionInstance, RuntimeTargetDescriptor, RuntimeTargetInstance, RuntimeTargetInstance as RuntimeTargetInstance$1 } from "@prisma-next/framework-components/execution";
 import { AfterExecuteResult, AsyncIterableResult, ExecutionPlan, RuntimeExecuteOptions, RuntimeMiddleware, RuntimeMiddlewareContext } from "@prisma-next/framework-components/runtime";
+import { MongoCodec, MongoCodecRegistry } from "@prisma-next/mongo-codec";
+import { MongoQueryPlan, MongoResultShape } from "@prisma-next/mongo-query-ast/execution";
 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
 
@@ -23,13 +25,83 @@ import { MongoQueryPlan } from "@prisma-next/mongo-query-ast/execution";
  * 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.
+ * cannot depend on.
  */
 interface MongoExecutionPlan<Row = unknown> extends ExecutionPlan<Row> {
   readonly command: AnyMongoWireCommand;
+  readonly resultShape?: MongoResultShape;
 }
 //#endregion
+//#region src/mongo-execution-stack.d.ts
+/**
+ * Mongo-specific static contributions a runtime descriptor declares.
+ *
+ * Mirrors `SqlStaticContributions` in shape: a `codecs()` getter that yields
+ * a `MongoCodecRegistry` populated with this contributor's codecs. The
+ * registry is then walked by `createMongoExecutionContext` and folded into
+ * the single per-execution registry the runtime reads from at decode time.
+ */
+interface MongoStaticContributions {
+  readonly codecs: () => MongoCodecRegistry;
+}
+interface MongoRuntimeTargetDescriptor<TTargetId extends string = 'mongo', TTargetInstance extends RuntimeTargetInstance$1<'mongo', TTargetId> = RuntimeTargetInstance$1<'mongo', TTargetId>> extends RuntimeTargetDescriptor<'mongo', TTargetId, TTargetInstance>, MongoStaticContributions {}
+interface MongoRuntimeAdapterInstance<TTargetId extends string = 'mongo'> extends RuntimeAdapterInstance<'mongo', TTargetId>, MongoAdapter {}
+interface MongoRuntimeAdapterDescriptor<TTargetId extends string = 'mongo', TAdapterInstance extends RuntimeAdapterInstance<'mongo', TTargetId> = MongoRuntimeAdapterInstance<TTargetId>> extends RuntimeAdapterDescriptor<'mongo', TTargetId, TAdapterInstance>, MongoStaticContributions {}
+interface MongoRuntimeExtensionInstance<TTargetId extends string = 'mongo'> extends RuntimeExtensionInstance<'mongo', TTargetId> {}
+interface MongoRuntimeExtensionDescriptor<TTargetId extends string = 'mongo'> extends RuntimeExtensionDescriptor<'mongo', TTargetId, MongoRuntimeExtensionInstance<TTargetId>>, MongoStaticContributions {
+  create(): MongoRuntimeExtensionInstance<TTargetId>;
+}
+/**
+ * The Mongo execution stack: target + adapter + optional driver + extension
+ * packs. Mirrors `SqlExecutionStack`. Constructed via
+ * `createMongoExecutionStack`.
+ */
+interface MongoExecutionStack<TTargetId extends string = 'mongo'> {
+  readonly target: MongoRuntimeTargetDescriptor<TTargetId>;
+  readonly adapter: MongoRuntimeAdapterDescriptor<TTargetId>;
+  readonly driver: RuntimeDriverDescriptor<'mongo', TTargetId, unknown, RuntimeDriverInstance<'mongo', TTargetId>> | undefined;
+  readonly extensionPacks: readonly MongoRuntimeExtensionDescriptor<TTargetId>[];
+}
+declare function createMongoExecutionStack<TTargetId extends string = 'mongo'>(options: {
+  readonly target: MongoRuntimeTargetDescriptor<TTargetId>;
+  readonly adapter: MongoRuntimeAdapterDescriptor<TTargetId>;
+  readonly driver?: RuntimeDriverDescriptor<'mongo', TTargetId, unknown, RuntimeDriverInstance<'mongo', TTargetId>> | undefined;
+  readonly extensionPacks?: readonly MongoRuntimeExtensionDescriptor<TTargetId>[] | undefined;
+}): MongoExecutionStack<TTargetId>;
+/**
+ * Read-only view of the codec registry exposed on `MongoExecutionContext`.
+ *
+ * Hides `register()` and the iterator from public surface — users do not
+ * mutate the per-execution codec registry. Internal aggregation in
+ * `createMongoExecutionContext` keeps using the full `MongoCodecRegistry`
+ * (it needs `register()`).
+ */
+interface MongoCodecLookup {
+  get(id: string): MongoCodec<string> | undefined;
+  has(id: string): boolean;
+}
+/**
+ * Per-execution context aggregated from a `MongoExecutionStack`.
+ *
+ * Carries the user's contract, a read-only lookup over the codec registry
+ * composed from every stack contributor, and a back-reference to the stack
+ * itself so the runtime can reach the adapter without users threading it
+ * explicitly.
+ *
+ * Mirrors SQL's `ExecutionContext` in role; Mongo's flavour is leaner
+ * because there are no parameterised codecs, JSON-schema validators, or
+ * mutation-default generators in scope yet.
+ */
+interface MongoExecutionContext<TTargetId extends string = 'mongo'> {
+  readonly contract: unknown;
+  readonly codecs: MongoCodecLookup;
+  readonly stack: MongoExecutionStack<TTargetId>;
+}
+declare function createMongoExecutionContext<TTargetId extends string = 'mongo'>(options: {
+  readonly contract: unknown;
+  readonly stack: MongoExecutionStack<TTargetId>;
+}): MongoExecutionContext<TTargetId>;
+//#endregion
 //#region src/mongo-middleware.d.ts
 interface MongoMiddlewareContext extends RuntimeMiddlewareContext {}
 /**
@@ -51,11 +123,20 @@ interface MongoMiddleware extends RuntimeMiddleware<MongoExecutionPlan> {
 }
 //#endregion
 //#region src/mongo-runtime.d.ts
+/**
+ * Mongo runtime options.
+ *
+ * The runtime takes a {@link MongoExecutionContext} (built via
+ * `createMongoExecutionContext`) and a driver. Codec resolution flows from
+ * the context — there is no `codecs` field on this options bag. The adapter
+ * is reached via `context.stack.adapter` (instantiated lazily through the
+ * stack's `create(stack)` factory). See ADR — Mongo result-shape as a
+ * structural plan field, § Codec registry: stack aggregation, not user
+ * threading.
+ */
 interface MongoRuntimeOptions {
-  readonly adapter: MongoAdapter;
+  readonly context: MongoExecutionContext;
   readonly driver: MongoDriver;
-  readonly contract: unknown;
-  readonly targetId: string;
   readonly middleware?: readonly MongoMiddleware[];
   readonly mode?: 'strict' | 'permissive';
 }
@@ -76,13 +157,15 @@ interface MongoRuntime {
    *   `RUNTIME.ABORTED { phase: 'encode' }` from inside `resolveValue`'s
    *   per-level `Promise.all` race.
    *
-   * Mongo's read path does not go through codecs (per ADR 204), so there
-   * is no `phase: 'decode'` boundary on the Mongo side.
+   * Mongo's read path decodes rows via `resultShape` (per ADR 209). The
+   * same `CodecCallContext` is forwarded into each `codec.decode(wire, ctx)`
+   * call, so async decoders that respect the signal get cancellation; the
+   * runtime itself does not currently emit a `phase: 'decode'` envelope.
    */
   execute<Row>(plan: MongoQueryPlan<Row>, options?: RuntimeExecuteOptions): AsyncIterableResult<Row>;
   close(): Promise<void>;
 }
 declare function createMongoRuntime(options: MongoRuntimeOptions): MongoRuntime;
 //#endregion
-export { type MongoExecutionPlan, type MongoMiddleware, type MongoMiddlewareContext, type MongoRuntime, type MongoRuntimeOptions, createMongoRuntime };
+export { type MongoCodecLookup, type MongoExecutionContext, type MongoExecutionPlan, type MongoExecutionStack, type MongoMiddleware, type MongoMiddlewareContext, type MongoRuntime, type MongoRuntimeAdapterDescriptor, type MongoRuntimeAdapterInstance, type MongoRuntimeExtensionDescriptor, type MongoRuntimeExtensionInstance, type MongoRuntimeOptions, type MongoRuntimeTargetDescriptor, type MongoStaticContributions, type RuntimeTargetInstance, createMongoExecutionContext, createMongoExecutionStack, createMongoRuntime };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"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;;;;UCNxD,mBAAA;oBACG;EFOH,SAAA,MAAA,EENE,WFMgB;EAAsC,SAAA,QAAA,EAAA,OAAA;EACrD,SAAA,QAAA,EAAA,MAAA;EADuC,SAAA,UAAA,CAAA,EAAA,SEH1B,eFG0B,EAAA;EAAa,SAAA,IAAA,CAAA,EAAA,QAAA,GAAA,YAAA;;UECvD,YAAA;;ADlBjB;AAaA;;;;;;;;;;;;;;;;;qBC0BU,eAAe,gBACX,wBACT,oBAAoB;EAhCR,KAAA,EAAA,EAiCN,OAjCM,CAAA,IAAA,CAAmB;;AAEjB,iBA+EH,kBAAA,CA/EG,OAAA,EA+EyB,mBA/EzB,CAAA,EA+E+C,YA/E/C"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/mongo-execution-plan.ts","../src/mongo-execution-stack.ts","../src/mongo-middleware.ts","../src/mongo-runtime.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/index.mjs

@@ -1,15 +1,157 @@
-import { RuntimeCore, checkMiddlewareCompatibility } from "@prisma-next/framework-components/runtime";
+import { createExecutionStack } from "@prisma-next/framework-components/execution";
+import { AsyncIterableResult, RuntimeCore, checkAborted, checkMiddlewareCompatibility, runWithMiddleware, runtimeError } from "@prisma-next/framework-components/runtime";
+import { createMongoCodecRegistry } from "@prisma-next/mongo-codec";
+import { ifDefined } from "@prisma-next/utils/defined";
 
+//#region src/mongo-execution-stack.ts
+function createMongoExecutionStack(options) {
+	return createExecutionStack({
+		target: options.target,
+		adapter: options.adapter,
+		driver: options.driver,
+		extensionPacks: options.extensionPacks
+	});
+}
+function createMongoExecutionContext(options) {
+	const registry = createMongoCodecRegistry();
+	const owners = /* @__PURE__ */ new Map();
+	const contributors = [
+		options.stack.target,
+		options.stack.adapter,
+		...options.stack.extensionPacks
+	];
+	for (const contributor of contributors) {
+		const contributed = contributor.codecs();
+		for (const codec of iterateCodecs(contributed)) {
+			const existingOwner = owners.get(codec.id);
+			if (existingOwner !== void 0) throw runtimeError("RUNTIME.DUPLICATE_CODEC", `Duplicate Mongo codec id '${codec.id}' contributed by '${contributor.id}' (already registered by '${existingOwner}').`, {
+				codecId: codec.id,
+				existingOwner,
+				incomingOwner: contributor.id
+			});
+			registry.register(codec);
+			owners.set(codec.id, contributor.id);
+		}
+	}
+	return Object.freeze({
+		contract: options.contract,
+		codecs: registry,
+		stack: options.stack
+	});
+}
+function* iterateCodecs(registry) {
+	yield* registry.values();
+}
+
+//#endregion
+//#region src/codecs/decoding.ts
+const WIRE_PREVIEW_LIMIT = 100;
+function previewWireValue(wireValue) {
+	if (typeof wireValue === "string") return wireValue.length > WIRE_PREVIEW_LIMIT ? `${wireValue.substring(0, WIRE_PREVIEW_LIMIT)}...` : wireValue;
+	return String(wireValue).substring(0, WIRE_PREVIEW_LIMIT);
+}
+function wrapDecodeFailure(error, collection, path, codecId, wireValue) {
+	const wrapped = runtimeError("RUNTIME.DECODE_FAILED", `Failed to decode field ${path} in collection '${collection}' with codec '${codecId}': ${error instanceof Error ? error.message : String(error)}`, {
+		collection,
+		path,
+		codec: codecId,
+		wirePreview: previewWireValue(wireValue)
+	});
+	wrapped.cause = error;
+	throw wrapped;
+}
+async function decodeMongoRow(row, shape, registry, collection, ctx = {}) {
+	if (shape.kind === "unknown") return row;
+	if (typeof row !== "object" || row === null) return row;
+	const rowObj = row;
+	const out = {};
+	const tasks = [];
+	function scheduleLeaf(path, codecId, wire, assign) {
+		const codec = registry.get(codecId);
+		if (!codec) {
+			assign(wire);
+			return;
+		}
+		tasks.push((async () => {
+			try {
+				assign(await codec.decode(wire, ctx));
+			} catch (error) {
+				wrapDecodeFailure(error, collection, path, codecId, wire);
+			}
+		})());
+	}
+	function walkField(value, fieldShape, path, assign) {
+		switch (fieldShape.kind) {
+			case "unknown":
+				assign(value);
+				return;
+			case "leaf":
+				if (value === null || value === void 0) {
+					assign(value);
+					return;
+				}
+				scheduleLeaf(path, fieldShape.codecId, value, assign);
+				return;
+			case "document": {
+				if (value === null || value === void 0) {
+					assign(value);
+					return;
+				}
+				if (typeof value !== "object" || value === null || Array.isArray(value)) {
+					assign(value);
+					return;
+				}
+				const vObj = value;
+				const nested = { ...vObj };
+				assign(nested);
+				for (const [fk, fShape] of Object.entries(fieldShape.fields)) walkField(vObj[fk], fShape, `${path}.${fk}`, (v) => {
+					nested[fk] = v;
+				});
+				return;
+			}
+			case "array": {
+				if (value === null || value === void 0) {
+					assign(value);
+					return;
+				}
+				if (!Array.isArray(value)) {
+					assign(value);
+					return;
+				}
+				const arr = [];
+				assign(arr);
+				for (let i = 0; i < value.length; i++) {
+					const el = value[i];
+					walkField(el, fieldShape.element, `${path}.${i}`, (v) => {
+						arr[i] = v;
+					});
+				}
+				return;
+			}
+		}
+		/* v8 ignore stop */
+	}
+	for (const [k, fShape] of Object.entries(shape.fields)) walkField(rowObj[k], fShape, k, (v) => {
+		out[k] = v;
+	});
+	for (const k of Object.keys(rowObj)) if (!Object.hasOwn(shape.fields, k)) out[k] = rowObj[k];
+	await Promise.all(tasks);
+	return out;
+}
+
+//#endregion
 //#region src/mongo-runtime.ts
 function noop() {}
 var MongoRuntimeImpl = class extends RuntimeCore {
 	#adapter;
 	#driver;
+	#codecs;
 	constructor(options) {
 		const middleware = options.middleware ? [...options.middleware] : [];
-		for (const mw of middleware) checkMiddlewareCompatibility(mw, "mongo", options.targetId);
+		const targetId = options.context.stack.target.targetId;
+		for (const mw of middleware) checkMiddlewareCompatibility(mw, "mongo", targetId);
 		const ctx = {
-			contract: options.contract,
+			contract: options.context.contract,
 			mode: options.mode ?? "strict",
 			now: () => Date.now(),
 			log: {
@@ -22,18 +164,34 @@ var MongoRuntimeImpl = class extends RuntimeCore {
 			middleware,
 			ctx
 		});
-		this.#adapter = options.adapter;
+		this.#adapter = options.context.stack.adapter.create(options.context.stack);
 		this.#driver = options.driver;
+		this.#codecs = options.context.codecs;
 	}
 	async lower(plan, ctx) {
 		return {
 			command: await this.#adapter.lower(plan, ctx),
-			meta: plan.meta
+			meta: plan.meta,
+			...ifDefined("resultShape", plan.resultShape)
 		};
 	}
 	runDriver(exec) {
 		return this.#driver.execute(exec.command);
 	}
+	execute(plan, options) {
+		const self = this;
+		const signal = options?.signal;
+		const codecCtx = signal === void 0 ? {} : { signal };
+		const generator = async function* () {
+			checkAborted(codecCtx, "stream");
+			const compiled = await self.runBeforeCompile(plan);
+			const exec = await self.lower(compiled, codecCtx);
+			const stream = runWithMiddleware(exec, self.middleware, self.ctx, () => self.runDriver(exec));
+			for await (const rawRow of stream) if (exec.resultShape === void 0) yield rawRow;
+			else yield await decodeMongoRow(rawRow, exec.resultShape, self.#codecs, exec.command.collection, codecCtx);
+		};
+		return new AsyncIterableResult(generator());
+	}
 	async close() {
 		await this.#driver.close();
 	}
@@ -43,5 +201,5 @@ function createMongoRuntime(options) {
 }
 
 //#endregion
-export { createMongoRuntime };
+export { createMongoExecutionContext, createMongoExecutionStack, createMongoRuntime };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["#adapter","#driver","ctx: MongoMiddlewareContext"],"sources":["../src/mongo-runtime.ts"],"sourcesContent":["import type { CodecCallContext } from '@prisma-next/framework-components/codec';\nimport type {\n  AsyncIterableResult,\n  RuntimeExecuteOptions,\n} 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  /**\n   * Execute a `MongoQueryPlan` and return an async iterable of rows.\n   *\n   * The optional `options.signal` is threaded through\n   * `lower → adapter.lower → resolveValue → codec.encode` so codec authors\n   * who forward the signal to their underlying SDK get true cancellation\n   * of in-flight network calls. The runtime additionally observes the\n   * signal at two boundaries:\n   *\n   * - **Already-aborted at entry** — first `next()` throws\n   *   `RUNTIME.ABORTED { phase: 'stream' }` before any work is done.\n   *   (Inherited from `RuntimeCore.execute`.)\n   * - **Mid-encode abort** — surfaces as\n   *   `RUNTIME.ABORTED { phase: 'encode' }` from inside `resolveValue`'s\n   *   per-level `Promise.all` race.\n   *\n   * Mongo's read path does not go through codecs (per ADR 204), so there\n   * is no `phase: 'decode'` boundary on the Mongo side.\n   */\n  execute<Row>(\n    plan: MongoQueryPlan<Row>,\n    options?: RuntimeExecuteOptions,\n  ): 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(\n    plan: MongoQueryPlan,\n    ctx: CodecCallContext,\n  ): Promise<MongoExecutionPlan> {\n    return {\n      command: await this.#adapter.lower(plan, ctx),\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":";;;AAcA,SAAS,OAAO;AAsChB,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,MACvB,MACA,KAC6B;AAC7B,SAAO;GACL,SAAS,MAAM,MAAKD,QAAS,MAAM,MAAM,IAAI;GAC7C,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"}
+{"version":3,"file":"index.mjs","names":["contributors: ReadonlyArray<MongoStaticContributions & { readonly id: string }>","out: Record<string, unknown>","tasks: Array<Promise<void>>","nested: Record<string, unknown>","arr: unknown[]","#adapter","#driver","#codecs","ctx: MongoMiddlewareContext","codecCtx: CodecCallContext"],"sources":["../src/mongo-execution-stack.ts","../src/codecs/decoding.ts","../src/mongo-runtime.ts"],"sourcesContent":["import {\n  createExecutionStack,\n  type ExecutionStack,\n  type RuntimeAdapterDescriptor,\n  type RuntimeAdapterInstance,\n  type RuntimeDriverDescriptor,\n  type RuntimeDriverInstance,\n  type RuntimeExtensionDescriptor,\n  type RuntimeExtensionInstance,\n  type RuntimeTargetDescriptor,\n  type RuntimeTargetInstance,\n} from '@prisma-next/framework-components/execution';\nimport { runtimeError } from '@prisma-next/framework-components/runtime';\nimport type { MongoCodec } from '@prisma-next/mongo-codec';\nimport { createMongoCodecRegistry, type MongoCodecRegistry } from '@prisma-next/mongo-codec';\nimport type { MongoAdapter } from '@prisma-next/mongo-lowering';\n\n/**\n * Mongo-specific static contributions a runtime descriptor declares.\n *\n * Mirrors `SqlStaticContributions` in shape: a `codecs()` getter that yields\n * a `MongoCodecRegistry` populated with this contributor's codecs. The\n * registry is then walked by `createMongoExecutionContext` and folded into\n * the single per-execution registry the runtime reads from at decode time.\n */\nexport interface MongoStaticContributions {\n  readonly codecs: () => MongoCodecRegistry;\n}\n\nexport interface MongoRuntimeTargetDescriptor<\n  TTargetId extends string = 'mongo',\n  TTargetInstance extends RuntimeTargetInstance<'mongo', TTargetId> = RuntimeTargetInstance<\n    'mongo',\n    TTargetId\n  >,\n> extends RuntimeTargetDescriptor<'mongo', TTargetId, TTargetInstance>,\n    MongoStaticContributions {}\n\nexport interface MongoRuntimeAdapterInstance<TTargetId extends string = 'mongo'>\n  extends RuntimeAdapterInstance<'mongo', TTargetId>,\n    MongoAdapter {}\n\nexport interface MongoRuntimeAdapterDescriptor<\n  TTargetId extends string = 'mongo',\n  TAdapterInstance extends RuntimeAdapterInstance<\n    'mongo',\n    TTargetId\n  > = MongoRuntimeAdapterInstance<TTargetId>,\n> extends RuntimeAdapterDescriptor<'mongo', TTargetId, TAdapterInstance>,\n    MongoStaticContributions {}\n\nexport interface MongoRuntimeExtensionInstance<TTargetId extends string = 'mongo'>\n  extends RuntimeExtensionInstance<'mongo', TTargetId> {}\n\nexport interface MongoRuntimeExtensionDescriptor<TTargetId extends string = 'mongo'>\n  extends RuntimeExtensionDescriptor<'mongo', TTargetId, MongoRuntimeExtensionInstance<TTargetId>>,\n    MongoStaticContributions {\n  create(): MongoRuntimeExtensionInstance<TTargetId>;\n}\n\n/**\n * The Mongo execution stack: target + adapter + optional driver + extension\n * packs. Mirrors `SqlExecutionStack`. Constructed via\n * `createMongoExecutionStack`.\n */\nexport interface MongoExecutionStack<TTargetId extends string = 'mongo'> {\n  readonly target: MongoRuntimeTargetDescriptor<TTargetId>;\n  readonly adapter: MongoRuntimeAdapterDescriptor<TTargetId>;\n  readonly driver:\n    | RuntimeDriverDescriptor<\n        'mongo',\n        TTargetId,\n        unknown,\n        RuntimeDriverInstance<'mongo', TTargetId>\n      >\n    | undefined;\n  readonly extensionPacks: readonly MongoRuntimeExtensionDescriptor<TTargetId>[];\n}\n\nexport function createMongoExecutionStack<TTargetId extends string = 'mongo'>(options: {\n  readonly target: MongoRuntimeTargetDescriptor<TTargetId>;\n  readonly adapter: MongoRuntimeAdapterDescriptor<TTargetId>;\n  readonly driver?:\n    | RuntimeDriverDescriptor<\n        'mongo',\n        TTargetId,\n        unknown,\n        RuntimeDriverInstance<'mongo', TTargetId>\n      >\n    | undefined;\n  readonly extensionPacks?: readonly MongoRuntimeExtensionDescriptor<TTargetId>[] | undefined;\n}): MongoExecutionStack<TTargetId> {\n  const stack = createExecutionStack({\n    target: options.target,\n    adapter: options.adapter,\n    driver: options.driver,\n    extensionPacks: options.extensionPacks,\n  });\n  return stack as ExecutionStack<'mongo', TTargetId> as MongoExecutionStack<TTargetId>;\n}\n\n/**\n * Read-only view of the codec registry exposed on `MongoExecutionContext`.\n *\n * Hides `register()` and the iterator from public surface — users do not\n * mutate the per-execution codec registry. Internal aggregation in\n * `createMongoExecutionContext` keeps using the full `MongoCodecRegistry`\n * (it needs `register()`).\n */\nexport interface MongoCodecLookup {\n  get(id: string): MongoCodec<string> | undefined;\n  has(id: string): boolean;\n}\n\n/**\n * Per-execution context aggregated from a `MongoExecutionStack`.\n *\n * Carries the user's contract, a read-only lookup over the codec registry\n * composed from every stack contributor, and a back-reference to the stack\n * itself so the runtime can reach the adapter without users threading it\n * explicitly.\n *\n * Mirrors SQL's `ExecutionContext` in role; Mongo's flavour is leaner\n * because there are no parameterised codecs, JSON-schema validators, or\n * mutation-default generators in scope yet.\n */\nexport interface MongoExecutionContext<TTargetId extends string = 'mongo'> {\n  readonly contract: unknown;\n  readonly codecs: MongoCodecLookup;\n  readonly stack: MongoExecutionStack<TTargetId>;\n}\n\nexport function createMongoExecutionContext<TTargetId extends string = 'mongo'>(options: {\n  readonly contract: unknown;\n  readonly stack: MongoExecutionStack<TTargetId>;\n}): MongoExecutionContext<TTargetId> {\n  const registry = createMongoCodecRegistry();\n  const owners = new Map<string, string>();\n\n  const contributors: ReadonlyArray<MongoStaticContributions & { readonly id: string }> = [\n    options.stack.target,\n    options.stack.adapter,\n    ...options.stack.extensionPacks,\n  ];\n\n  for (const contributor of contributors) {\n    const contributed = contributor.codecs();\n    for (const codec of iterateCodecs(contributed)) {\n      const existingOwner = owners.get(codec.id);\n      if (existingOwner !== undefined) {\n        throw runtimeError(\n          'RUNTIME.DUPLICATE_CODEC',\n          `Duplicate Mongo codec id '${codec.id}' contributed by '${contributor.id}' (already registered by '${existingOwner}').`,\n          { codecId: codec.id, existingOwner, incomingOwner: contributor.id },\n        );\n      }\n      registry.register(codec);\n      owners.set(codec.id, contributor.id);\n    }\n  }\n\n  return Object.freeze({\n    contract: options.contract,\n    codecs: registry,\n    stack: options.stack,\n  });\n}\n\nfunction* iterateCodecs(registry: MongoCodecRegistry): Iterable<MongoCodec<string>> {\n  yield* registry.values();\n}\n","import type { CodecCallContext } from '@prisma-next/framework-components/codec';\nimport { runtimeError } from '@prisma-next/framework-components/runtime';\nimport type { MongoFieldShape, MongoResultShape } from '@prisma-next/mongo-query-ast/execution';\nimport type { MongoCodecLookup } from '../mongo-execution-stack';\n\nconst WIRE_PREVIEW_LIMIT = 100;\n\nfunction previewWireValue(wireValue: unknown): string {\n  if (typeof wireValue === 'string') {\n    return wireValue.length > WIRE_PREVIEW_LIMIT\n      ? `${wireValue.substring(0, WIRE_PREVIEW_LIMIT)}...`\n      : wireValue;\n  }\n  return String(wireValue).substring(0, WIRE_PREVIEW_LIMIT);\n}\n\nfunction wrapDecodeFailure(\n  error: unknown,\n  collection: string,\n  path: string,\n  codecId: string,\n  wireValue: unknown,\n): never {\n  const message = error instanceof Error ? error.message : String(error);\n  const wrapped = runtimeError(\n    'RUNTIME.DECODE_FAILED',\n    `Failed to decode field ${path} in collection '${collection}' with codec '${codecId}': ${message}`,\n    {\n      collection,\n      path,\n      codec: codecId,\n      wirePreview: previewWireValue(wireValue),\n    },\n  );\n  wrapped.cause = error;\n  throw wrapped;\n}\n\nexport async function decodeMongoRow(\n  row: unknown,\n  shape: MongoResultShape,\n  registry: MongoCodecLookup,\n  collection: string,\n  ctx: CodecCallContext = {},\n): Promise<unknown> {\n  if (shape.kind === 'unknown') {\n    return row;\n  }\n  if (typeof row !== 'object' || row === null) {\n    return row;\n  }\n  const rowObj = row as Record<string, unknown>;\n  const out: Record<string, unknown> = {};\n  const tasks: Array<Promise<void>> = [];\n\n  function scheduleLeaf(\n    path: string,\n    codecId: string,\n    wire: unknown,\n    assign: (v: unknown) => void,\n  ): void {\n    const codec = registry.get(codecId);\n    if (!codec) {\n      assign(wire);\n      return;\n    }\n    tasks.push(\n      (async () => {\n        try {\n          assign(await codec.decode(wire, ctx));\n        } catch (error) {\n          wrapDecodeFailure(error, collection, path, codecId, wire);\n        }\n      })(),\n    );\n  }\n\n  function walkField(\n    value: unknown,\n    fieldShape: MongoFieldShape,\n    path: string,\n    assign: (v: unknown) => void,\n  ): void {\n    // Exhaustive over `MongoFieldShape['kind']` by construction:\n    // adding a new variant must add a corresponding arm or the\n    // `satisfies never` below would error at type-check time.\n    switch (fieldShape.kind) {\n      case 'unknown':\n        assign(value);\n        return;\n      case 'leaf':\n        if (value === null || value === undefined) {\n          assign(value);\n          return;\n        }\n        scheduleLeaf(path, fieldShape.codecId, value, assign);\n        return;\n      case 'document': {\n        if (value === null || value === undefined) {\n          assign(value);\n          return;\n        }\n        if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n          assign(value);\n          return;\n        }\n        const vObj = value as Record<string, unknown>;\n        // Pre-seed with a shallow copy so unshaped subdocument keys\n        // round-trip verbatim. Subsequent walkField assignments overwrite\n        // shaped keys with their decoded values. Mirrors the top-level\n        // pass-through invariant — the decode path is structurally\n        // additive at every nesting depth, not just the root.\n        const nested: Record<string, unknown> = { ...vObj };\n        assign(nested);\n        for (const [fk, fShape] of Object.entries(fieldShape.fields)) {\n          walkField(vObj[fk], fShape, `${path}.${fk}`, (v) => {\n            nested[fk] = v;\n          });\n        }\n        return;\n      }\n      case 'array': {\n        if (value === null || value === undefined) {\n          assign(value);\n          return;\n        }\n        if (!Array.isArray(value)) {\n          assign(value);\n          return;\n        }\n        const arr: unknown[] = [];\n        assign(arr);\n        for (let i = 0; i < value.length; i++) {\n          const el = value[i];\n          walkField(el, fieldShape.element, `${path}.${i}`, (v) => {\n            arr[i] = v;\n          });\n        }\n        return;\n      }\n    }\n    // The switch above is exhaustive over `MongoFieldShape['kind']`. The\n    // `satisfies never` below is a compile-time guard that fails if a new\n    // variant is added without a corresponding arm.\n    /* v8 ignore start */\n    fieldShape satisfies never;\n    /* v8 ignore stop */\n  }\n\n  for (const [k, fShape] of Object.entries(shape.fields)) {\n    walkField(rowObj[k], fShape, k, (v) => {\n      out[k] = v;\n    });\n  }\n\n  // Pass through any row fields the shape does not describe. The shape is a\n  // partial, lane-vouched description of what the runtime knows how to decode;\n  // fields outside that description (e.g. polymorphic variant fields the base\n  // model's shape doesn't enumerate, sidecar fields a future schema migration\n  // adds) round-trip verbatim. Drop semantics belongs to explicit projection\n  // (`select` / `$project`), not to the structural decode path.\n  for (const k of Object.keys(rowObj)) {\n    if (!Object.hasOwn(shape.fields, k)) {\n      out[k] = rowObj[k];\n    }\n  }\n\n  await Promise.all(tasks);\n  return out;\n}\n","import type { CodecCallContext } from '@prisma-next/framework-components/codec';\nimport {\n  AsyncIterableResult,\n  checkAborted,\n  checkMiddlewareCompatibility,\n  RuntimeCore,\n  type RuntimeExecuteOptions,\n  runWithMiddleware,\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 { ifDefined } from '@prisma-next/utils/defined';\nimport { decodeMongoRow } from './codecs/decoding';\nimport type { MongoExecutionPlan } from './mongo-execution-plan';\nimport type { MongoCodecLookup, MongoExecutionContext } from './mongo-execution-stack';\nimport type { MongoMiddleware, MongoMiddlewareContext } from './mongo-middleware';\n\nfunction noop() {}\n\n/**\n * Mongo runtime options.\n *\n * The runtime takes a {@link MongoExecutionContext} (built via\n * `createMongoExecutionContext`) and a driver. Codec resolution flows from\n * the context — there is no `codecs` field on this options bag. The adapter\n * is reached via `context.stack.adapter` (instantiated lazily through the\n * stack's `create(stack)` factory). See ADR — Mongo result-shape as a\n * structural plan field, § Codec registry: stack aggregation, not user\n * threading.\n */\nexport interface MongoRuntimeOptions {\n  readonly context: MongoExecutionContext;\n  readonly driver: MongoDriver;\n  readonly middleware?: readonly MongoMiddleware[];\n  readonly mode?: 'strict' | 'permissive';\n}\n\nexport interface MongoRuntime {\n  /**\n   * Execute a `MongoQueryPlan` and return an async iterable of rows.\n   *\n   * The optional `options.signal` is threaded through\n   * `lower → adapter.lower → resolveValue → codec.encode` so codec authors\n   * who forward the signal to their underlying SDK get true cancellation\n   * of in-flight network calls. The runtime additionally observes the\n   * signal at two boundaries:\n   *\n   * - **Already-aborted at entry** — first `next()` throws\n   *   `RUNTIME.ABORTED { phase: 'stream' }` before any work is done.\n   *   (Inherited from `RuntimeCore.execute`.)\n   * - **Mid-encode abort** — surfaces as\n   *   `RUNTIME.ABORTED { phase: 'encode' }` from inside `resolveValue`'s\n   *   per-level `Promise.all` race.\n   *\n   * Mongo's read path decodes rows via `resultShape` (per ADR 209). The\n   * same `CodecCallContext` is forwarded into each `codec.decode(wire, ctx)`\n   * call, so async decoders that respect the signal get cancellation; the\n   * runtime itself does not currently emit a `phase: 'decode'` envelope.\n   */\n  execute<Row>(\n    plan: MongoQueryPlan<Row>,\n    options?: RuntimeExecuteOptions,\n  ): 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  readonly #codecs: MongoCodecLookup;\n\n  constructor(options: MongoRuntimeOptions) {\n    const middleware = options.middleware ? [...options.middleware] : [];\n    const targetId = options.context.stack.target.targetId;\n    for (const mw of middleware) {\n      checkMiddlewareCompatibility(mw, 'mongo', targetId);\n    }\n\n    const ctx: MongoMiddlewareContext = {\n      contract: options.context.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    const adapterDescriptor = options.context.stack.adapter;\n    const adapterInstance = adapterDescriptor.create(options.context.stack);\n    this.#adapter = adapterInstance;\n    this.#driver = options.driver;\n    this.#codecs = options.context.codecs;\n  }\n\n  protected override async lower(\n    plan: MongoQueryPlan,\n    ctx: CodecCallContext,\n  ): Promise<MongoExecutionPlan> {\n    return {\n      command: await this.#adapter.lower(plan, ctx),\n      meta: plan.meta,\n      ...ifDefined('resultShape', plan.resultShape),\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 execute<Row>(\n    plan: MongoQueryPlan & { readonly _row?: Row },\n    options?: RuntimeExecuteOptions,\n  ): AsyncIterableResult<Row> {\n    const self = this;\n    const signal = options?.signal;\n    const codecCtx: CodecCallContext = signal === undefined ? {} : { signal };\n    const generator = async function* (): AsyncGenerator<Row, void, unknown> {\n      checkAborted(codecCtx, 'stream');\n      const compiled = await self.runBeforeCompile(plan);\n      const exec = await self.lower(compiled, codecCtx);\n      const stream = runWithMiddleware<MongoExecutionPlan, Record<string, unknown>>(\n        exec,\n        self.middleware,\n        self.ctx,\n        () => self.runDriver(exec),\n      );\n      for await (const rawRow of stream) {\n        if (exec.resultShape === undefined) {\n          yield rawRow as Row;\n        } else {\n          // Source the collection from the lowered exec rather than the\n          // pre-lowering plan: a `runBeforeCompile` middleware is allowed to\n          // rewrite collection names during compilation, and the wire\n          // command carried by `exec` is always authoritative for what just\n          // ran.\n          const decoded = await decodeMongoRow(\n            rawRow,\n            exec.resultShape,\n            self.#codecs,\n            exec.command.collection,\n            codecCtx,\n          );\n          yield decoded as Row;\n        }\n      }\n    };\n    return new AsyncIterableResult(generator());\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":"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"}

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@prisma-next/mongo-runtime",
-  "version": "0.5.0-dev.30",
+  "version": "0.5.0-dev.41",
   "type": "module",
   "sideEffects": false,
   "description": "MongoDB runtime implementation for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.5.0-dev.30",
-    "@prisma-next/framework-components": "0.5.0-dev.30",
-    "@prisma-next/mongo-lowering": "0.5.0-dev.30",
-    "@prisma-next/mongo-query-ast": "0.5.0-dev.30",
-    "@prisma-next/mongo-wire": "0.5.0-dev.30"
+    "@prisma-next/mongo-codec": "0.5.0-dev.41",
+    "@prisma-next/contract": "0.5.0-dev.41",
+    "@prisma-next/mongo-lowering": "0.5.0-dev.41",
+    "@prisma-next/mongo-query-ast": "0.5.0-dev.41",
+    "@prisma-next/mongo-wire": "0.5.0-dev.41",
+    "@prisma-next/framework-components": "0.5.0-dev.41",
+    "@prisma-next/utils": "0.5.0-dev.41"
   },
   "devDependencies": {
     "mongodb": "^6.16.0",
@@ -17,18 +19,18 @@
     "tsdown": "0.18.4",
     "typescript": "5.9.3",
     "vitest": "4.0.17",
-    "@prisma-next/adapter-mongo": "0.5.0-dev.30",
-    "@prisma-next/family-mongo": "0.5.0-dev.30",
-    "@prisma-next/mongo-contract-ts": "0.5.0-dev.30",
-    "@prisma-next/middleware-telemetry": "0.5.0-dev.30",
-    "@prisma-next/mongo-value": "0.5.0-dev.30",
-    "@prisma-next/mongo-query-builder": "0.5.0-dev.30",
-    "@prisma-next/driver-mongo": "0.5.0-dev.30",
-    "@prisma-next/mongo-contract": "0.5.0-dev.30",
-    "@prisma-next/target-mongo": "0.5.0-dev.30",
-    "@prisma-next/test-utils": "0.0.1",
+    "@prisma-next/adapter-mongo": "0.5.0-dev.41",
+    "@prisma-next/middleware-telemetry": "0.5.0-dev.41",
+    "@prisma-next/mongo-contract-ts": "0.5.0-dev.41",
+    "@prisma-next/family-mongo": "0.5.0-dev.41",
+    "@prisma-next/mongo-query-builder": "0.5.0-dev.41",
+    "@prisma-next/mongo-value": "0.5.0-dev.41",
+    "@prisma-next/driver-mongo": "0.5.0-dev.41",
+    "@prisma-next/mongo-contract": "0.5.0-dev.41",
+    "@prisma-next/target-mongo": "0.5.0-dev.41",
+    "@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/codecs/decoding.ts

@@ -0,0 +1,170 @@
+import type { CodecCallContext } from '@prisma-next/framework-components/codec';
+import { runtimeError } from '@prisma-next/framework-components/runtime';
+import type { MongoFieldShape, MongoResultShape } from '@prisma-next/mongo-query-ast/execution';
+import type { MongoCodecLookup } from '../mongo-execution-stack';
+
+const WIRE_PREVIEW_LIMIT = 100;
+
+function previewWireValue(wireValue: unknown): string {
+  if (typeof wireValue === 'string') {
+    return wireValue.length > WIRE_PREVIEW_LIMIT
+      ? `${wireValue.substring(0, WIRE_PREVIEW_LIMIT)}...`
+      : wireValue;
+  }
+  return String(wireValue).substring(0, WIRE_PREVIEW_LIMIT);
+}
+
+function wrapDecodeFailure(
+  error: unknown,
+  collection: string,
+  path: string,
+  codecId: string,
+  wireValue: unknown,
+): never {
+  const message = error instanceof Error ? error.message : String(error);
+  const wrapped = runtimeError(
+    'RUNTIME.DECODE_FAILED',
+    `Failed to decode field ${path} in collection '${collection}' with codec '${codecId}': ${message}`,
+    {
+      collection,
+      path,
+      codec: codecId,
+      wirePreview: previewWireValue(wireValue),
+    },
+  );
+  wrapped.cause = error;
+  throw wrapped;
+}
+
+export async function decodeMongoRow(
+  row: unknown,
+  shape: MongoResultShape,
+  registry: MongoCodecLookup,
+  collection: string,
+  ctx: CodecCallContext = {},
+): Promise<unknown> {
+  if (shape.kind === 'unknown') {
+    return row;
+  }
+  if (typeof row !== 'object' || row === null) {
+    return row;
+  }
+  const rowObj = row as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  const tasks: Array<Promise<void>> = [];
+
+  function scheduleLeaf(
+    path: string,
+    codecId: string,
+    wire: unknown,
+    assign: (v: unknown) => void,
+  ): void {
+    const codec = registry.get(codecId);
+    if (!codec) {
+      assign(wire);
+      return;
+    }
+    tasks.push(
+      (async () => {
+        try {
+          assign(await codec.decode(wire, ctx));
+        } catch (error) {
+          wrapDecodeFailure(error, collection, path, codecId, wire);
+        }
+      })(),
+    );
+  }
+
+  function walkField(
+    value: unknown,
+    fieldShape: MongoFieldShape,
+    path: string,
+    assign: (v: unknown) => void,
+  ): void {
+    // Exhaustive over `MongoFieldShape['kind']` by construction:
+    // adding a new variant must add a corresponding arm or the
+    // `satisfies never` below would error at type-check time.
+    switch (fieldShape.kind) {
+      case 'unknown':
+        assign(value);
+        return;
+      case 'leaf':
+        if (value === null || value === undefined) {
+          assign(value);
+          return;
+        }
+        scheduleLeaf(path, fieldShape.codecId, value, assign);
+        return;
+      case 'document': {
+        if (value === null || value === undefined) {
+          assign(value);
+          return;
+        }
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+          assign(value);
+          return;
+        }
+        const vObj = value as Record<string, unknown>;
+        // Pre-seed with a shallow copy so unshaped subdocument keys
+        // round-trip verbatim. Subsequent walkField assignments overwrite
+        // shaped keys with their decoded values. Mirrors the top-level
+        // pass-through invariant — the decode path is structurally
+        // additive at every nesting depth, not just the root.
+        const nested: Record<string, unknown> = { ...vObj };
+        assign(nested);
+        for (const [fk, fShape] of Object.entries(fieldShape.fields)) {
+          walkField(vObj[fk], fShape, `${path}.${fk}`, (v) => {
+            nested[fk] = v;
+          });
+        }
+        return;
+      }
+      case 'array': {
+        if (value === null || value === undefined) {
+          assign(value);
+          return;
+        }
+        if (!Array.isArray(value)) {
+          assign(value);
+          return;
+        }
+        const arr: unknown[] = [];
+        assign(arr);
+        for (let i = 0; i < value.length; i++) {
+          const el = value[i];
+          walkField(el, fieldShape.element, `${path}.${i}`, (v) => {
+            arr[i] = v;
+          });
+        }
+        return;
+      }
+    }
+    // The switch above is exhaustive over `MongoFieldShape['kind']`. The
+    // `satisfies never` below is a compile-time guard that fails if a new
+    // variant is added without a corresponding arm.
+    /* v8 ignore start */
+    fieldShape satisfies never;
+    /* v8 ignore stop */
+  }
+
+  for (const [k, fShape] of Object.entries(shape.fields)) {
+    walkField(rowObj[k], fShape, k, (v) => {
+      out[k] = v;
+    });
+  }
+
+  // Pass through any row fields the shape does not describe. The shape is a
+  // partial, lane-vouched description of what the runtime knows how to decode;
+  // fields outside that description (e.g. polymorphic variant fields the base
+  // model's shape doesn't enumerate, sidecar fields a future schema migration
+  // adds) round-trip verbatim. Drop semantics belongs to explicit projection
+  // (`select` / `$project`), not to the structural decode path.
+  for (const k of Object.keys(rowObj)) {
+    if (!Object.hasOwn(shape.fields, k)) {
+      out[k] = rowObj[k];
+    }
+  }
+
+  await Promise.all(tasks);
+  return out;
+}

package/src/exports/index.ts

@@ -1,4 +1,20 @@
+export type { RuntimeTargetInstance } from '@prisma-next/framework-components/execution';
 export type { MongoExecutionPlan } from '../mongo-execution-plan';
+export type {
+  MongoCodecLookup,
+  MongoExecutionContext,
+  MongoExecutionStack,
+  MongoRuntimeAdapterDescriptor,
+  MongoRuntimeAdapterInstance,
+  MongoRuntimeExtensionDescriptor,
+  MongoRuntimeExtensionInstance,
+  MongoRuntimeTargetDescriptor,
+  MongoStaticContributions,
+} from '../mongo-execution-stack';
+export {
+  createMongoExecutionContext,
+  createMongoExecutionStack,
+} from '../mongo-execution-stack';
 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

@@ -1,4 +1,5 @@
 import type { ExecutionPlan } from '@prisma-next/framework-components/runtime';
+import type { MongoResultShape } from '@prisma-next/mongo-query-ast/execution';
 import type { AnyMongoWireCommand } from '@prisma-next/mongo-wire';
 
 /**
@@ -19,9 +20,9 @@ import type { AnyMongoWireCommand } from '@prisma-next/mongo-wire';
  * 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.
+ * cannot depend on.
  */
 export interface MongoExecutionPlan<Row = unknown> extends ExecutionPlan<Row> {
   readonly command: AnyMongoWireCommand;
+  readonly resultShape?: MongoResultShape;
 }

package/src/mongo-execution-stack.ts

@@ -0,0 +1,171 @@
+import {
+  createExecutionStack,
+  type ExecutionStack,
+  type RuntimeAdapterDescriptor,
+  type RuntimeAdapterInstance,
+  type RuntimeDriverDescriptor,
+  type RuntimeDriverInstance,
+  type RuntimeExtensionDescriptor,
+  type RuntimeExtensionInstance,
+  type RuntimeTargetDescriptor,
+  type RuntimeTargetInstance,
+} from '@prisma-next/framework-components/execution';
+import { runtimeError } from '@prisma-next/framework-components/runtime';
+import type { MongoCodec } from '@prisma-next/mongo-codec';
+import { createMongoCodecRegistry, type MongoCodecRegistry } from '@prisma-next/mongo-codec';
+import type { MongoAdapter } from '@prisma-next/mongo-lowering';
+
+/**
+ * Mongo-specific static contributions a runtime descriptor declares.
+ *
+ * Mirrors `SqlStaticContributions` in shape: a `codecs()` getter that yields
+ * a `MongoCodecRegistry` populated with this contributor's codecs. The
+ * registry is then walked by `createMongoExecutionContext` and folded into
+ * the single per-execution registry the runtime reads from at decode time.
+ */
+export interface MongoStaticContributions {
+  readonly codecs: () => MongoCodecRegistry;
+}
+
+export interface MongoRuntimeTargetDescriptor<
+  TTargetId extends string = 'mongo',
+  TTargetInstance extends RuntimeTargetInstance<'mongo', TTargetId> = RuntimeTargetInstance<
+    'mongo',
+    TTargetId
+  >,
+> extends RuntimeTargetDescriptor<'mongo', TTargetId, TTargetInstance>,
+    MongoStaticContributions {}
+
+export interface MongoRuntimeAdapterInstance<TTargetId extends string = 'mongo'>
+  extends RuntimeAdapterInstance<'mongo', TTargetId>,
+    MongoAdapter {}
+
+export interface MongoRuntimeAdapterDescriptor<
+  TTargetId extends string = 'mongo',
+  TAdapterInstance extends RuntimeAdapterInstance<
+    'mongo',
+    TTargetId
+  > = MongoRuntimeAdapterInstance<TTargetId>,
+> extends RuntimeAdapterDescriptor<'mongo', TTargetId, TAdapterInstance>,
+    MongoStaticContributions {}
+
+export interface MongoRuntimeExtensionInstance<TTargetId extends string = 'mongo'>
+  extends RuntimeExtensionInstance<'mongo', TTargetId> {}
+
+export interface MongoRuntimeExtensionDescriptor<TTargetId extends string = 'mongo'>
+  extends RuntimeExtensionDescriptor<'mongo', TTargetId, MongoRuntimeExtensionInstance<TTargetId>>,
+    MongoStaticContributions {
+  create(): MongoRuntimeExtensionInstance<TTargetId>;
+}
+
+/**
+ * The Mongo execution stack: target + adapter + optional driver + extension
+ * packs. Mirrors `SqlExecutionStack`. Constructed via
+ * `createMongoExecutionStack`.
+ */
+export interface MongoExecutionStack<TTargetId extends string = 'mongo'> {
+  readonly target: MongoRuntimeTargetDescriptor<TTargetId>;
+  readonly adapter: MongoRuntimeAdapterDescriptor<TTargetId>;
+  readonly driver:
+    | RuntimeDriverDescriptor<
+        'mongo',
+        TTargetId,
+        unknown,
+        RuntimeDriverInstance<'mongo', TTargetId>
+      >
+    | undefined;
+  readonly extensionPacks: readonly MongoRuntimeExtensionDescriptor<TTargetId>[];
+}
+
+export function createMongoExecutionStack<TTargetId extends string = 'mongo'>(options: {
+  readonly target: MongoRuntimeTargetDescriptor<TTargetId>;
+  readonly adapter: MongoRuntimeAdapterDescriptor<TTargetId>;
+  readonly driver?:
+    | RuntimeDriverDescriptor<
+        'mongo',
+        TTargetId,
+        unknown,
+        RuntimeDriverInstance<'mongo', TTargetId>
+      >
+    | undefined;
+  readonly extensionPacks?: readonly MongoRuntimeExtensionDescriptor<TTargetId>[] | undefined;
+}): MongoExecutionStack<TTargetId> {
+  const stack = createExecutionStack({
+    target: options.target,
+    adapter: options.adapter,
+    driver: options.driver,
+    extensionPacks: options.extensionPacks,
+  });
+  return stack as ExecutionStack<'mongo', TTargetId> as MongoExecutionStack<TTargetId>;
+}
+
+/**
+ * Read-only view of the codec registry exposed on `MongoExecutionContext`.
+ *
+ * Hides `register()` and the iterator from public surface — users do not
+ * mutate the per-execution codec registry. Internal aggregation in
+ * `createMongoExecutionContext` keeps using the full `MongoCodecRegistry`
+ * (it needs `register()`).
+ */
+export interface MongoCodecLookup {
+  get(id: string): MongoCodec<string> | undefined;
+  has(id: string): boolean;
+}
+
+/**
+ * Per-execution context aggregated from a `MongoExecutionStack`.
+ *
+ * Carries the user's contract, a read-only lookup over the codec registry
+ * composed from every stack contributor, and a back-reference to the stack
+ * itself so the runtime can reach the adapter without users threading it
+ * explicitly.
+ *
+ * Mirrors SQL's `ExecutionContext` in role; Mongo's flavour is leaner
+ * because there are no parameterised codecs, JSON-schema validators, or
+ * mutation-default generators in scope yet.
+ */
+export interface MongoExecutionContext<TTargetId extends string = 'mongo'> {
+  readonly contract: unknown;
+  readonly codecs: MongoCodecLookup;
+  readonly stack: MongoExecutionStack<TTargetId>;
+}
+
+export function createMongoExecutionContext<TTargetId extends string = 'mongo'>(options: {
+  readonly contract: unknown;
+  readonly stack: MongoExecutionStack<TTargetId>;
+}): MongoExecutionContext<TTargetId> {
+  const registry = createMongoCodecRegistry();
+  const owners = new Map<string, string>();
+
+  const contributors: ReadonlyArray<MongoStaticContributions & { readonly id: string }> = [
+    options.stack.target,
+    options.stack.adapter,
+    ...options.stack.extensionPacks,
+  ];
+
+  for (const contributor of contributors) {
+    const contributed = contributor.codecs();
+    for (const codec of iterateCodecs(contributed)) {
+      const existingOwner = owners.get(codec.id);
+      if (existingOwner !== undefined) {
+        throw runtimeError(
+          'RUNTIME.DUPLICATE_CODEC',
+          `Duplicate Mongo codec id '${codec.id}' contributed by '${contributor.id}' (already registered by '${existingOwner}').`,
+          { codecId: codec.id, existingOwner, incomingOwner: contributor.id },
+        );
+      }
+      registry.register(codec);
+      owners.set(codec.id, contributor.id);
+    }
+  }
+
+  return Object.freeze({
+    contract: options.contract,
+    codecs: registry,
+    stack: options.stack,
+  });
+}
+
+function* iterateCodecs(registry: MongoCodecRegistry): Iterable<MongoCodec<string>> {
+  yield* registry.values();
+}

package/src/mongo-runtime.ts

@@ -1,24 +1,36 @@
 import type { CodecCallContext } from '@prisma-next/framework-components/codec';
-import type {
-  AsyncIterableResult,
-  RuntimeExecuteOptions,
-} from '@prisma-next/framework-components/runtime';
 import {
+  AsyncIterableResult,
+  checkAborted,
   checkMiddlewareCompatibility,
   RuntimeCore,
+  type RuntimeExecuteOptions,
+  runWithMiddleware,
 } 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 { ifDefined } from '@prisma-next/utils/defined';
+import { decodeMongoRow } from './codecs/decoding';
 import type { MongoExecutionPlan } from './mongo-execution-plan';
+import type { MongoCodecLookup, MongoExecutionContext } from './mongo-execution-stack';
 import type { MongoMiddleware, MongoMiddlewareContext } from './mongo-middleware';
 
 function noop() {}
 
+/**
+ * Mongo runtime options.
+ *
+ * The runtime takes a {@link MongoExecutionContext} (built via
+ * `createMongoExecutionContext`) and a driver. Codec resolution flows from
+ * the context — there is no `codecs` field on this options bag. The adapter
+ * is reached via `context.stack.adapter` (instantiated lazily through the
+ * stack's `create(stack)` factory). See ADR — Mongo result-shape as a
+ * structural plan field, § Codec registry: stack aggregation, not user
+ * threading.
+ */
 export interface MongoRuntimeOptions {
-  readonly adapter: MongoAdapter;
+  readonly context: MongoExecutionContext;
   readonly driver: MongoDriver;
-  readonly contract: unknown;
-  readonly targetId: string;
   readonly middleware?: readonly MongoMiddleware[];
   readonly mode?: 'strict' | 'permissive';
 }
@@ -40,8 +52,10 @@ export interface MongoRuntime {
    *   `RUNTIME.ABORTED { phase: 'encode' }` from inside `resolveValue`'s
    *   per-level `Promise.all` race.
    *
-   * Mongo's read path does not go through codecs (per ADR 204), so there
-   * is no `phase: 'decode'` boundary on the Mongo side.
+   * Mongo's read path decodes rows via `resultShape` (per ADR 209). The
+   * same `CodecCallContext` is forwarded into each `codec.decode(wire, ctx)`
+   * call, so async decoders that respect the signal get cancellation; the
+   * runtime itself does not currently emit a `phase: 'decode'` envelope.
    */
   execute<Row>(
     plan: MongoQueryPlan<Row>,
@@ -56,15 +70,17 @@ class MongoRuntimeImpl
 {
   readonly #adapter: MongoAdapter;
   readonly #driver: MongoDriver;
+  readonly #codecs: MongoCodecLookup;
 
   constructor(options: MongoRuntimeOptions) {
     const middleware = options.middleware ? [...options.middleware] : [];
+    const targetId = options.context.stack.target.targetId;
     for (const mw of middleware) {
-      checkMiddlewareCompatibility(mw, 'mongo', options.targetId);
+      checkMiddlewareCompatibility(mw, 'mongo', targetId);
     }
 
     const ctx: MongoMiddlewareContext = {
-      contract: options.contract,
+      contract: options.context.contract,
       mode: options.mode ?? 'strict',
       now: () => Date.now(),
       log: { info: noop, warn: noop, error: noop },
@@ -72,8 +88,11 @@ class MongoRuntimeImpl
 
     super({ middleware, ctx });
 
-    this.#adapter = options.adapter;
+    const adapterDescriptor = options.context.stack.adapter;
+    const adapterInstance = adapterDescriptor.create(options.context.stack);
+    this.#adapter = adapterInstance;
     this.#driver = options.driver;
+    this.#codecs = options.context.codecs;
   }
 
   protected override async lower(
@@ -83,6 +102,7 @@ class MongoRuntimeImpl
     return {
       command: await this.#adapter.lower(plan, ctx),
       meta: plan.meta,
+      ...ifDefined('resultShape', plan.resultShape),
     };
   }
 
@@ -90,6 +110,46 @@ class MongoRuntimeImpl
     return this.#driver.execute<Record<string, unknown>>(exec.command);
   }
 
+  override execute<Row>(
+    plan: MongoQueryPlan & { readonly _row?: Row },
+    options?: RuntimeExecuteOptions,
+  ): AsyncIterableResult<Row> {
+    const self = this;
+    const signal = options?.signal;
+    const codecCtx: CodecCallContext = signal === undefined ? {} : { signal };
+    const generator = async function* (): AsyncGenerator<Row, void, unknown> {
+      checkAborted(codecCtx, 'stream');
+      const compiled = await self.runBeforeCompile(plan);
+      const exec = await self.lower(compiled, codecCtx);
+      const stream = runWithMiddleware<MongoExecutionPlan, Record<string, unknown>>(
+        exec,
+        self.middleware,
+        self.ctx,
+        () => self.runDriver(exec),
+      );
+      for await (const rawRow of stream) {
+        if (exec.resultShape === undefined) {
+          yield rawRow as Row;
+        } else {
+          // Source the collection from the lowered exec rather than the
+          // pre-lowering plan: a `runBeforeCompile` middleware is allowed to
+          // rewrite collection names during compilation, and the wire
+          // command carried by `exec` is always authoritative for what just
+          // ran.
+          const decoded = await decodeMongoRow(
+            rawRow,
+            exec.resultShape,
+            self.#codecs,
+            exec.command.collection,
+            codecCtx,
+          );
+          yield decoded as Row;
+        }
+      }
+    };
+    return new AsyncIterableResult(generator());
+  }
+
   override async close(): Promise<void> {
     await this.#driver.close();
   }