@prisma-next/mongo-runtime 0.5.0-dev.6 → 0.5.0-dev.61

package/README.md

@@ -2,18 +2,89 @@
 
 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.
+
+## 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 `codecs` slot returns the codec descriptors; `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)`), 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-codec` (`MongoCodecRegistry` for decode)
   - `@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, `RuntimeAdapterDescriptor` / `ExecutionStack` for the stack composition model)
 - **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.
+
+`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
+  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,30 +1,158 @@
-import { AfterExecuteResult, AsyncIterableResult, RuntimeMiddleware, RuntimeMiddlewareContext } from "@prisma-next/framework-components/runtime";
-import { MongoQueryPlan } from "@prisma-next/mongo-query-ast/execution";
+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";
 
+//#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.
+ */
+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 {}
-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
+/**
+ * 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 RuntimeMiddleware[];
+  readonly middleware?: readonly MongoMiddleware[];
   readonly mode?: 'strict' | 'permissive';
 }
 interface MongoRuntime {
-  execute<Row>(plan: MongoQueryPlan<Row>): AsyncIterableResult<Row>;
+  /**
+   * Execute a `MongoQueryPlan` and return an async iterable of rows.
+   *
+   * The optional `options.signal` is threaded through
+   * `lower → adapter.lower → resolveValue → codec.encode` so codec authors
+   * who forward the signal to their underlying SDK get true cancellation
+   * of in-flight network calls. The runtime additionally observes the
+   * signal at two boundaries:
+   *
+   * - **Already-aborted at entry** — first `next()` throws
+   *   `RUNTIME.ABORTED { phase: 'stream' }` before any work is done.
+   *   (Inherited from `RuntimeCore.execute`.)
+   * - **Mid-encode abort** — surfaces as
+   *   `RUNTIME.ABORTED { phase: 'encode' }` from inside `resolveValue`'s
+   *   per-level `Promise.all` race.
+   *
+   * 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 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-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-execution-stack.ts","../src/mongo-middleware.ts","../src/mongo-runtime.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/index.mjs

@@ -1,77 +1,244 @@
-import { AsyncIterableResult, 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 { newMongoCodecRegistry } from "@prisma-next/mongo-codec";
+import { ifDefined } from "@prisma-next/utils/defined";
+import { canonicalStringify } from "@prisma-next/utils/canonical-stringify";
+import { hashContent } from "@prisma-next/utils/hash-content";
 
+//#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 = newMongoCodecRegistry();
+	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/content-hash.ts
+/**
+* Computes a stable content hash for a lowered Mongo execution plan.
+*
+* Internally builds an unambiguous canonical-stringified preimage from
+* two components:
+*
+* 1. `meta.storageHash` — discriminates by schema. A migration changes the
+*    storage hash, which invalidates cached entries automatically (no
+*    per-app invalidation logic needed for schema changes).
+* 2. `exec.command` — the wire command. `canonicalStringify` produces a
+*    deterministic serialization that is stable across object key
+*    insertion order and that distinguishes types JSON would otherwise
+*    conflate (e.g. `BigInt(1)` vs `1`, `Date` vs ISO string, `Buffer`
+*    vs number array). The spread converts the frozen wire-command
+*    class instance (`InsertOneWireCommand`, `AggregateWireCommand`, …)
+*    into a plain object exposing its own enumerable properties
+*    (`kind`, `collection`, plus the payload-specific fields like
+*    `document`/`filter`/`update`/`pipeline`/…), which is what
+*    `canonicalStringify` accepts; class instances are rejected
+*    outright to prevent silent collisions.
+*
+* Unlike SQL, there is no separate "rendered statement" component because
+* a Mongo `MongoExecutionPlan.command` is the wire command itself —
+* canonicalizing it captures both structure and parameters in one pass.
+*
+* The components are wrapped in an object and canonicalized as a single
+* unit (rather than concatenated with a delimiter) so component
+* boundaries are unambiguous and cannot collide with a different split
+* of the same characters.
+*
+* The canonical string is then piped through `hashContent` to produce a
+* bounded, opaque digest. See `@prisma-next/utils/hash-content` for the
+* rationale.
+*
+* @internal
+*/
+function computeMongoContentHash(exec) {
+	return hashContent(canonicalStringify({
+		storageHash: exec.meta.storageHash,
+		command: { ...exec.command }
+	}));
+}
+
+//#endregion
 //#region src/mongo-runtime.ts
 function noop() {}
-function now() {
-	return Date.now();
-}
-var MongoRuntimeImpl = class {
+var MongoRuntimeImpl = class extends RuntimeCore {
 	#adapter;
 	#driver;
-	#middleware;
-	#middlewareContext;
+	#codecs;
 	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 = {
-			contract: options.contract,
+		const targetId = options.context.stack.target.targetId;
+		for (const mw of middleware) checkMiddlewareCompatibility(mw, "mongo", targetId);
+		const ctx = {
+			contract: options.context.contract,
 			mode: options.mode ?? "strict",
-			now,
+			now: () => Date.now(),
 			log: {
 				info: noop,
 				warn: noop,
 				error: noop
-			}
+			},
+			contentHash: (exec) => computeMongoContentHash(exec)
 		};
+		super({
+			middleware,
+			ctx
+		});
+		this.#adapter = options.context.stack.adapter.create(options.context.stack);
+		this.#driver = options.driver;
+		this.#codecs = options.context.codecs;
 	}
-	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 = 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, ctx) {
+		return {
+			command: await this.#adapter.lower(plan, ctx),
+			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(iterator());
+		return new AsyncIterableResult(generator());
 	}
 	async close() {
 		await this.#driver.close();
@@ -82,5 +249,5 @@ function createMongoRuntime(options) {
 }
 
 //#endregion
-export { createMongoRuntime };
+export { createMongoExecutionContext, createMongoExecutionStack, createMongoRuntime };
 //# sourceMappingURL=index.mjs.map