@prisma-next/mongo-runtime 0.11.0 → 0.12.0

package/dist/index.d.mts

@@ -1,9 +1,10 @@
 import { RuntimeAdapterDescriptor, RuntimeAdapterInstance, RuntimeDriverDescriptor, RuntimeDriverInstance, RuntimeExtensionDescriptor, RuntimeExtensionInstance, RuntimeTargetDescriptor, RuntimeTargetInstance, RuntimeTargetInstance as RuntimeTargetInstance$1 } from "@prisma-next/framework-components/execution";
 import { AfterExecuteResult, AsyncIterableResult, ExecutionPlan, ParamRefMutator, RuntimeExecuteOptions, RuntimeMiddleware, RuntimeMiddlewareContext } from "@prisma-next/framework-components/runtime";
 import { MongoCodec, MongoCodecRegistry } from "@prisma-next/mongo-codec";
+import { MongoParamRef } from "@prisma-next/mongo-value";
 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 { MongoAdapter, MongoDriver, MongoLoweredDraft } from "@prisma-next/mongo-lowering";
 
 //#region src/mongo-execution-plan.d.ts
 /**
@@ -11,8 +12,8 @@ import { MongoAdapter, MongoDriver } from "@prisma-next/mongo-lowering";
  * that a Mongo driver can run.
  *
  * The plan carries:
- * - `command` — the wire command (e.g. `InsertOneWireCommand`,
- *   `AggregateWireCommand`) produced by `MongoAdapter.lower(plan)`
+ * - `command` — dual lifecycle (see field JSDoc): unresolved draft during
+ *   `beforeExecute`, frozen wire command afterward
  * - `meta` — family-agnostic plan metadata (target, lane, hashes, ...)
  * - `_row` — phantom row type, propagated from the originating
  *   `MongoQueryPlan`
@@ -27,6 +28,14 @@ import { MongoAdapter, MongoDriver } from "@prisma-next/mongo-lowering";
  * cannot depend on.
  */
 interface MongoExecutionPlan<Row = unknown> extends ExecutionPlan<Row> {
+  /**
+   * Lowered command payload. **Lifecycle:** during `beforeExecute` this slot
+   * holds the unresolved `MongoLoweredDraft` (plain object, `MongoParamRef`
+   * leaves intact). After `resolveParams` and in later middleware hooks
+   * (`afterExecute`, `onRow`, intercept-after-resolve) it is the frozen wire
+   * command (`InsertOneWireCommand`, `AggregateWireCommand`, …). Do not read
+   * `command` structurally in `beforeExecute` — use the `params` mutator.
+   */
   readonly command: AnyMongoWireCommand;
   readonly resultShape?: MongoResultShape;
 }
@@ -88,8 +97,116 @@ declare function createMongoExecutionContext<TTargetId extends string = 'mongo'>
   readonly stack: MongoExecutionStack<TTargetId>;
 }): MongoExecutionContext<TTargetId>;
 //#endregion
+//#region src/param-ref-mutator.d.ts
+/**
+ * Phantom brand on {@link MongoParamRefHandle} so handles produced by
+ * {@link MongoParamRefMutator.entries} are distinguishable at the type level
+ * from user-constructed `MongoParamRef` instances. There is no runtime token —
+ * the handle IS the underlying `MongoParamRef` instance, cast through the brand.
+ */
+declare const mongoParamRefHandleBrand: unique symbol;
+/**
+ * Opaque token identifying a single `MongoParamRef` in the draft tree.
+ * Produced by {@link MongoParamRefMutator.entries}; consumed by
+ * `replaceValue` / `replaceValues`. The `TCodecId` phantom parameter
+ * records the codec id so typed overloads can route replacement values
+ * through a `TCodecMap`.
+ */
+interface MongoParamRefHandle<TCodecId extends string | undefined = string | undefined> {
+  readonly [mongoParamRefHandleBrand]: TCodecId;
+}
+/**
+ * One outbound `MongoParamRef` slot in the draft exposed to middleware.
+ * `value` is the current effective value (post any prior mutations);
+ * `codecId` is the codec id declared on the underlying `MongoParamRef`.
+ */
+interface MongoParamRefEntry<TCodecId extends string | undefined = string | undefined> {
+  readonly ref: MongoParamRefHandle<TCodecId>;
+  readonly value: unknown;
+  readonly codecId: TCodecId;
+}
+/**
+ * Discriminated entry union over a codec map. For each `K` in `TCodecMap`,
+ * `entries()` may yield a `MongoParamRefEntry<K>`; refs with no codec id (or
+ * an unrecognised codec id) yield `MongoParamRefEntry<undefined>`. Pattern-
+ * matching on `entry.codecId` narrows `entry.ref` to `MongoParamRefHandle<K>`.
+ */
+type MongoParamRefEntryUnion<TCodecMap extends Record<string, unknown>> = { [K in keyof TCodecMap & string]: MongoParamRefEntry<K> }[keyof TCodecMap & string] | MongoParamRefEntry<undefined>;
+/**
+ * Mongo-family mutator threaded into `MongoMiddleware.beforeExecute` as
+ * `params`. Scope is `MongoParamRef.value` slots only — middleware cannot
+ * insert or remove refs, rewrite the filter shape, or modify the pipeline
+ * structure. The phantom `MongoParamRefHandle` brand and the typed
+ * `replaceValue` overload enforce this at compile time.
+ *
+ * `entries()` performs a flat walk over the `MongoLoweredDraft` tree via
+ * {@link flattenMongoParamRefs}, yielding every `MongoParamRef` leaf in
+ * document fields, array elements, filter predicates, update operators, and
+ * pipeline stages. The walk matches `resolveDraftSlot` in the Mongo adapter
+ * (plain-object and array slots only; `Date` and other non-plain objects are
+ * leaves in both paths).
+ *
+ * Allocation discipline: the working-overrides map is only allocated on the
+ * first `replaceValue` / `replaceValues` call. If no middleware mutates,
+ * `currentDraft()` returns the original draft by reference identity without
+ * allocating a new tree (the AC-MUT5 fast path).
+ */
+interface MongoParamRefMutator<TCodecMap extends Record<string, unknown> = Record<string, unknown>> extends ParamRefMutator {
+  entries(): IterableIterator<MongoParamRefEntryUnion<TCodecMap>>;
+  replaceValue<TCodecId extends keyof TCodecMap & string>(ref: MongoParamRefHandle<TCodecId>, newValue: TCodecMap[TCodecId]): void;
+  replaceValue(ref: MongoParamRefHandle<undefined>, newValue: unknown): void;
+  replaceValues(updates: Iterable<{
+    readonly ref: MongoParamRefHandle<(keyof TCodecMap & string) | undefined>;
+    readonly newValue: unknown;
+  }>): void;
+}
+/**
+ * Internal-only view that exposes `currentDraft()` to the Mongo runtime.
+ * The runtime calls this after the `beforeExecute` chain; the result is the
+ * original draft by reference if nothing was mutated, otherwise a new tree
+ * with the mutations applied. `MongoMiddleware` consumers never see this
+ * shape; they receive the public `MongoParamRefMutator` view.
+ */
+interface MongoParamRefMutatorInternal<TCodecMap extends Record<string, unknown> = Record<string, unknown>> extends MongoParamRefMutator<TCodecMap> {
+  currentDraft(): MongoLoweredDraft;
+}
+/**
+ * Flat walk over a `MongoLoweredDraft` yielding every `MongoParamRef` leaf
+ * regardless of nesting — object values, array elements, filter predicate
+ * values, update operator values, and pipeline stage values. Raw command
+ * variants carry no `MongoParamRef` nodes so they yield zero entries.
+ *
+ * **Walk parity:** slot traversal matches `resolveDraftSlot` / `resolveParams`
+ * — refs appear only in plain-object and array containers; `Date` and other
+ * non-plain objects are leaves (not descended into), so middleware sees every
+ * ref the resolve pass will encode.
+ */
+declare function flattenMongoParamRefs(draft: MongoLoweredDraft): Generator<MongoParamRef>;
+/**
+ * Build a {@link MongoParamRefMutatorInternal} for the given lowered draft.
+ *
+ * The mutator captures the draft by reference and uses `flattenMongoParamRefs`
+ * on demand to produce `entries()`. Replacements are stored in a lazily-
+ * allocated `Map`; the fast path (no replacements) preserves bit-for-bit
+ * reference identity to the original draft in `currentDraft()`.
+ */
+declare function createMongoParamRefMutator<TCodecMap extends Record<string, unknown> = Record<string, unknown>>(draft: MongoLoweredDraft): MongoParamRefMutatorInternal<TCodecMap>;
+//#endregion
 //#region src/mongo-middleware.d.ts
-interface MongoMiddlewareContext extends RuntimeMiddlewareContext {}
+/**
+ * Per-execute middleware context for Mongo. See {@link MongoMiddleware} for
+ * plan/command lifecycle during `beforeExecute` vs later hooks.
+ */
+interface MongoMiddlewareContext extends RuntimeMiddlewareContext {
+  /**
+   * Stable digest of `meta.storageHash` plus the **resolved** wire command.
+   * Valid only on post-resolution plans (typically `afterExecute` or intercept
+   * after `resolveParams`). Calling this from `beforeExecute` throws
+   * `RUNTIME.CONTENT_HASH_REQUIRES_RESOLVED_COMMAND` because `plan.command`
+   * is still an unresolved draft at that point.
+   */
+  contentHash(exec: MongoExecutionPlan): Promise<string>;
+}
 /**
  * Mongo-domain middleware. Extends the framework `RuntimeMiddleware`
  * parameterized over `MongoExecutionPlan` because `runWithMiddleware`
@@ -100,10 +217,21 @@ interface MongoMiddlewareContext extends RuntimeMiddlewareContext {}
  * telemetry) — which carry no `familyId` — remain assignable. When
  * present, it must be `'mongo'`; the runtime rejects mismatches at
  * construction time via `checkMiddlewareCompatibility`.
+ *
+ * **Pre-resolve `beforeExecute` contract:** `plan.command` holds the
+ * unresolved `MongoLoweredDraft`, not a wire command. Observe and mutate
+ * parameters via `params.entries()` / `replaceValue` / `replaceValues` only.
+ * Do not inspect `plan.command` structurally or call `ctx.contentHash` in
+ * this hook. After the chain, `resolveParams` produces the frozen wire
+ * command used in `afterExecute` and for `contentHash`.
  */
 interface MongoMiddleware extends RuntimeMiddleware<MongoExecutionPlan> {
   readonly familyId?: 'mongo';
-  beforeExecute?(plan: MongoExecutionPlan, ctx: MongoMiddlewareContext, params?: ParamRefMutator): void | Promise<void>;
+  /**
+   * Runs after structural lower, before `resolveParams`. `plan.command` is the
+   * unresolved draft; use `params` for param-ref access, not `plan.command`.
+   */
+  beforeExecute?(plan: MongoExecutionPlan, ctx: MongoMiddlewareContext, params?: MongoParamRefMutator): void | Promise<void>;
   onRow?(row: Record<string, unknown>, plan: MongoExecutionPlan, ctx: MongoMiddlewareContext): Promise<void>;
   afterExecute?(plan: MongoExecutionPlan, result: AfterExecuteResult, ctx: MongoMiddlewareContext): Promise<void>;
 }
@@ -153,5 +281,5 @@ interface MongoRuntime {
 }
 declare function createMongoRuntime(options: MongoRuntimeOptions): MongoRuntime;
 //#endregion
-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 };
+export { type MongoCodecLookup, type MongoExecutionContext, type MongoExecutionPlan, type MongoExecutionStack, type MongoMiddleware, type MongoMiddlewareContext, type MongoParamRefEntry, type MongoParamRefEntryUnion, type MongoParamRefHandle, type MongoParamRefMutator, type MongoParamRefMutatorInternal, type MongoRuntime, type MongoRuntimeAdapterDescriptor, type MongoRuntimeAdapterInstance, type MongoRuntimeExtensionDescriptor, type MongoRuntimeExtensionInstance, type MongoRuntimeOptions, type MongoRuntimeTargetDescriptor, type MongoStaticContributions, type RuntimeTargetInstance, createMongoExecutionContext, createMongoExecutionStack, createMongoParamRefMutator, createMongoRuntime, flattenMongoParamRefs };
 //# 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-execution-stack.ts","../src/mongo-middleware.ts","../src/mongo-runtime.ts"],"mappings":";;;;;;;;;;;;;AAwBA;;;;;;;;;;;;;;;UAAiB,kBAAA,wBAA0C,aAAA,CAAc,GAAA;EAAA,SAC9D,OAAA,EAAS,mBAAA;EAAA,SACT,WAAA,GAAc,gBAAA;AAAA;;;;;;;AAFzB;UCFiB,wBAAA;EAAA,SACN,MAAA,QAAc,kBAAA;AAAA;AAAA,UAGR,4BAAA,6DAES,uBAAA,UAA+B,SAAA,IAAa,uBAAA,UAElE,SAAA,WAEM,uBAAA,UAAiC,SAAA,EAAW,eAAA,GAClD,wBAAA;AAAA,UAEa,2BAAA,6CACP,sBAAA,UAAgC,SAAA,GACtC,YAAA;AAAA,UAEa,6BAAA,8DAEU,sBAAA,UAEvB,SAAA,IACE,2BAAA,CAA4B,SAAA,WACxB,wBAAA,UAAkC,SAAA,EAAW,gBAAA,GACnD,wBAAA;AAAA,UAEa,6BAAA,6CACP,wBAAA,UAAkC,SAAA;AAAA,UAE3B,+BAAA,6CACP,0BAAA,UAAoC,SAAA,EAAW,6BAAA,CAA8B,SAAA,IACnF,wBAAA;EACF,MAAA,IAAU,6BAAA,CAA8B,SAAA;AAAA;;;;UAMzB,mBAAA;EAAA,SACN,MAAA,EAAQ,4BAAA,CAA6B,SAAA;EAAA,SACrC,OAAA,EAAS,6BAAA,CAA8B,SAAA;EAAA,SACvC,MAAA,EACL,uBAAA,UAEE,SAAA,WAEA,qBAAA,UAA+B,SAAA;EAAA,SAG5B,cAAA,WAAyB,+BAAA,CAAgC,SAAA;AAAA;AAAA,iBAGpD,yBAAA,oCAAA,CAA8D,OAAA;EAAA,SACnE,MAAA,EAAQ,4BAAA,CAA6B,SAAA;EAAA,SACrC,OAAA,EAAS,6BAAA,CAA8B,SAAA;EAAA,SACvC,MAAA,GACL,uBAAA,UAEE,SAAA,WAEA,qBAAA,UAA+B,SAAA;EAAA,SAG5B,cAAA,YAA0B,+BAAA,CAAgC,SAAA;AAAA,IACjE,mBAAA,CAAoB,SAAA;;;;;;UAeP,gBAAA;EACf,GAAA,CAAI,EAAA,WAAa,UAAA;EACjB,GAAA,CAAI,EAAA;AAAA;;;;;;;;UAUW,qBAAA;EAAA,SACN,QAAA;EAAA,SACA,MAAA,EAAQ,gBAAA;EAAA,SACR,KAAA,EAAO,mBAAA,CAAoB,SAAA;AAAA;AAAA,iBAGtB,2BAAA,oCAAA,CAAgE,OAAA;EAAA,SACrE,QAAA;EAAA,SACA,KAAA,EAAO,mBAAA,CAAoB,SAAA;AAAA,IAClC,qBAAA,CAAsB,SAAA;;;UClHT,sBAAA,SAA+B,wBAAA;;;;;AFgBhD;;;;;;;UEHiB,eAAA,SAAwB,iBAAA,CAAkB,kBAAA;EAAA,SAChD,QAAA;EACT,aAAA,EACE,IAAA,EAAM,kBAAA,EACN,GAAA,EAAK,sBAAA,EACL,MAAA,GAAS,eAAA,UACD,OAAA;EACV,KAAA,EACE,GAAA,EAAK,MAAA,mBACL,IAAA,EAAM,kBAAA,EACN,GAAA,EAAK,sBAAA,GACJ,OAAA;EACH,YAAA,EACE,IAAA,EAAM,kBAAA,EACN,MAAA,EAAQ,kBAAA,EACR,GAAA,EAAK,sBAAA,GACJ,OAAA;AAAA;;;;;;AFbL;;;;;;;;UGQiB,mBAAA;EAAA,SACN,OAAA,EAAS,qBAAA;EAAA,SACT,MAAA,EAAQ,WAAA;EAAA,SACR,UAAA,YAAsB,eAAA;EAAA,SACtB,IAAA;AAAA;AAAA,UAGM,YAAA;EHbQ;;;;;;ACJzB;;;;;AAIA;;;;;;;;;;EEmCE,OAAA,MACE,IAAA,EAAM,cAAA,CAAe,GAAA,GACrB,OAAA,GAAU,qBAAA,GACT,mBAAA,CAAoB,GAAA;EACvB,KAAA,IAAS,OAAA;AAAA;AAAA,iBAsGK,kBAAA,CAAmB,OAAA,EAAS,mBAAA,GAAsB,YAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/mongo-execution-plan.ts","../src/mongo-execution-stack.ts","../src/param-ref-mutator.ts","../src/mongo-middleware.ts","../src/mongo-runtime.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -1,9 +1,11 @@
 import { createExecutionStack } from "@prisma-next/framework-components/execution";
 import { AsyncIterableResult, RuntimeCore, checkAborted, checkMiddlewareCompatibility, runBeforeExecuteChain, runWithMiddleware, runtimeError } from "@prisma-next/framework-components/runtime";
 import { newMongoCodecRegistry } from "@prisma-next/mongo-codec";
+import { blindCast } from "@prisma-next/utils/casts";
 import { ifDefined } from "@prisma-next/utils/defined";
 import { canonicalStringify } from "@prisma-next/utils/canonical-stringify";
 import { hashContent } from "@prisma-next/utils/hash-content";
+import { MongoParamRef } from "@prisma-next/mongo-value";
 //#region src/mongo-execution-stack.ts
 function createMongoExecutionStack(options) {
 	return createExecutionStack({
@@ -140,6 +142,22 @@ async function decodeMongoRow(row, shape, registry, collection, ctx = {}) {
 }
 //#endregion
 //#region src/content-hash.ts
+/** @internal */
+const RUNTIME_CONTENT_HASH_REQUIRES_RESOLVED_COMMAND = "RUNTIME.CONTENT_HASH_REQUIRES_RESOLVED_COMMAND";
+/**
+* Resolved wire commands are frozen class instances (`InsertOneWireCommand`, …);
+* pre-resolve `beforeExecute` plans hold a plain-object `MongoLoweredDraft` in the
+* command slot. O(1) prototype check — no tree walk on the hot path.
+*/
+function isResolvedMongoWireCommand(command) {
+	if (command === null || typeof command !== "object") return false;
+	const proto = Object.getPrototypeOf(command);
+	return proto !== null && proto !== Object.prototype;
+}
+function assertContentHashOnResolvedCommand(command) {
+	if (isResolvedMongoWireCommand(command)) return;
+	throw runtimeError(RUNTIME_CONTENT_HASH_REQUIRES_RESOLVED_COMMAND, "contentHash and computeMongoContentHash are only valid on a resolved wire command (after param resolution, e.g. from afterExecute). During beforeExecute, plan.command holds an unresolved MongoLoweredDraft — use params.entries() and the param mutator instead of contentHash or structural reads of plan.command.", { phase: "beforeExecute" });
+}
 /**
 * Computes a stable content hash for a lowered Mongo execution plan.
 *
@@ -174,15 +192,262 @@ async function decodeMongoRow(row, shape, registry, collection, ctx = {}) {
 * bounded, opaque digest. See `@prisma-next/utils/hash-content` for the
 * rationale.
 *
+* @throws {RuntimeErrorEnvelope} {@link RUNTIME_CONTENT_HASH_REQUIRES_RESOLVED_COMMAND}
+* when `exec.command` is still a pre-resolve draft (plain object), e.g. when
+* `contentHash` is called from `beforeExecute`.
+*
 * @internal
 */
 function computeMongoContentHash(exec) {
+	assertContentHashOnResolvedCommand(exec.command);
 	return hashContent(canonicalStringify({
 		storageHash: exec.meta.storageHash,
 		command: { ...exec.command }
 	}));
 }
 //#endregion
+//#region src/param-ref-mutator.ts
+function isPlainRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function* flattenDraftSlot(value) {
+	if (value instanceof MongoParamRef) {
+		yield value;
+		return;
+	}
+	if (Array.isArray(value)) {
+		for (const item of value) yield* flattenDraftSlot(item);
+		return;
+	}
+	if (isPlainRecord(value)) for (const v of Object.values(value)) yield* flattenDraftSlot(v);
+}
+/**
+* Flat walk over a `MongoLoweredDraft` yielding every `MongoParamRef` leaf
+* regardless of nesting — object values, array elements, filter predicate
+* values, update operator values, and pipeline stage values. Raw command
+* variants carry no `MongoParamRef` nodes so they yield zero entries.
+*
+* **Walk parity:** slot traversal matches `resolveDraftSlot` / `resolveParams`
+* — refs appear only in plain-object and array containers; `Date` and other
+* non-plain objects are leaves (not descended into), so middleware sees every
+* ref the resolve pass will encode.
+*/
+function* flattenMongoParamRefs(draft) {
+	switch (draft.kind) {
+		case "insertOne":
+		case "rawInsertOne":
+			yield* flattenDraftSlot(draft.document);
+			break;
+		case "insertMany":
+		case "rawInsertMany":
+			for (const doc of draft.documents) yield* flattenDraftSlot(doc);
+			break;
+		case "updateOne":
+		case "updateMany":
+		case "rawUpdateOne":
+		case "rawUpdateMany":
+			yield* flattenDraftSlot(draft.filter);
+			yield* flattenDraftSlot(draft.update);
+			break;
+		case "findOneAndUpdate":
+		case "rawFindOneAndUpdate":
+			yield* flattenDraftSlot(draft.filter);
+			yield* flattenDraftSlot(draft.update);
+			break;
+		case "deleteOne":
+		case "deleteMany":
+		case "rawDeleteOne":
+		case "rawDeleteMany":
+			yield* flattenDraftSlot(draft.filter);
+			break;
+		case "findOneAndDelete":
+		case "rawFindOneAndDelete":
+			yield* flattenDraftSlot(draft.filter);
+			break;
+		case "aggregate":
+		case "rawAggregate":
+			for (const stage of draft.pipeline) yield* flattenDraftSlot(stage);
+			break;
+	}
+}
+function substituteSlot(value, overrides) {
+	if (value instanceof MongoParamRef) {
+		if (overrides.has(value)) {
+			const opts = {};
+			if (value.name !== void 0) opts.name = value.name;
+			if (value.codecId !== void 0) opts.codecId = value.codecId;
+			return new MongoParamRef(overrides.get(value), opts);
+		}
+		return value;
+	}
+	if (Array.isArray(value)) return value.map((item) => substituteSlot(item, overrides));
+	if (isPlainRecord(value)) {
+		const out = {};
+		for (const [k, v] of Object.entries(value)) out[k] = substituteSlot(v, overrides);
+		return out;
+	}
+	return value;
+}
+function substituteDoc(doc, overrides) {
+	return blindCast(substituteSlot(doc, overrides));
+}
+function isUpdatePipeline(update) {
+	return Array.isArray(update);
+}
+function substituteUpdate(update, overrides) {
+	if (isUpdatePipeline(update)) return update.map((stage) => substituteDoc(stage, overrides));
+	return substituteDoc(update, overrides);
+}
+function buildMutatedDraft(draft, overrides) {
+	switch (draft.kind) {
+		case "insertOne": return {
+			kind: "insertOne",
+			collection: draft.collection,
+			document: substituteDoc(draft.document, overrides)
+		};
+		case "rawInsertOne": return {
+			kind: "rawInsertOne",
+			collection: draft.collection,
+			document: substituteDoc(draft.document, overrides)
+		};
+		case "insertMany": return {
+			kind: "insertMany",
+			collection: draft.collection,
+			documents: draft.documents.map((d) => substituteDoc(d, overrides))
+		};
+		case "rawInsertMany": return {
+			kind: "rawInsertMany",
+			collection: draft.collection,
+			documents: draft.documents.map((d) => substituteDoc(d, overrides))
+		};
+		case "updateOne": return {
+			kind: "updateOne",
+			collection: draft.collection,
+			filter: substituteDoc(draft.filter, overrides),
+			update: substituteUpdate(draft.update, overrides),
+			upsert: draft.upsert
+		};
+		case "updateMany": return {
+			kind: "updateMany",
+			collection: draft.collection,
+			filter: substituteDoc(draft.filter, overrides),
+			update: substituteUpdate(draft.update, overrides),
+			upsert: draft.upsert
+		};
+		case "rawUpdateOne": return {
+			kind: "rawUpdateOne",
+			collection: draft.collection,
+			filter: substituteDoc(draft.filter, overrides),
+			update: substituteUpdate(draft.update, overrides)
+		};
+		case "rawUpdateMany": return {
+			kind: "rawUpdateMany",
+			collection: draft.collection,
+			filter: substituteDoc(draft.filter, overrides),
+			update: substituteUpdate(draft.update, overrides)
+		};
+		case "deleteOne": return {
+			kind: "deleteOne",
+			collection: draft.collection,
+			filter: substituteDoc(draft.filter, overrides)
+		};
+		case "deleteMany": return {
+			kind: "deleteMany",
+			collection: draft.collection,
+			filter: substituteDoc(draft.filter, overrides)
+		};
+		case "rawDeleteOne": return {
+			kind: "rawDeleteOne",
+			collection: draft.collection,
+			filter: substituteDoc(draft.filter, overrides)
+		};
+		case "rawDeleteMany": return {
+			kind: "rawDeleteMany",
+			collection: draft.collection,
+			filter: substituteDoc(draft.filter, overrides)
+		};
+		case "findOneAndUpdate": return {
+			kind: "findOneAndUpdate",
+			collection: draft.collection,
+			filter: substituteDoc(draft.filter, overrides),
+			update: substituteUpdate(draft.update, overrides),
+			upsert: draft.upsert,
+			sort: draft.sort,
+			returnDocument: draft.returnDocument
+		};
+		case "rawFindOneAndUpdate": return {
+			kind: "rawFindOneAndUpdate",
+			collection: draft.collection,
+			filter: substituteDoc(draft.filter, overrides),
+			update: substituteUpdate(draft.update, overrides),
+			upsert: draft.upsert,
+			sort: draft.sort,
+			returnDocument: draft.returnDocument
+		};
+		case "findOneAndDelete": return {
+			kind: "findOneAndDelete",
+			collection: draft.collection,
+			filter: substituteDoc(draft.filter, overrides),
+			sort: draft.sort
+		};
+		case "rawFindOneAndDelete": return {
+			kind: "rawFindOneAndDelete",
+			collection: draft.collection,
+			filter: substituteDoc(draft.filter, overrides),
+			sort: draft.sort
+		};
+		case "aggregate": return {
+			kind: "aggregate",
+			collection: draft.collection,
+			pipeline: draft.pipeline.map((s) => substituteDoc(s, overrides))
+		};
+		case "rawAggregate": return {
+			kind: "rawAggregate",
+			collection: draft.collection,
+			pipeline: draft.pipeline.map((s) => substituteDoc(s, overrides))
+		};
+	}
+}
+/**
+* Build a {@link MongoParamRefMutatorInternal} for the given lowered draft.
+*
+* The mutator captures the draft by reference and uses `flattenMongoParamRefs`
+* on demand to produce `entries()`. Replacements are stored in a lazily-
+* allocated `Map`; the fast path (no replacements) preserves bit-for-bit
+* reference identity to the original draft in `currentDraft()`.
+*/
+function createMongoParamRefMutator(draft) {
+	const originalDraft = draft;
+	let overrides;
+	const ensureOverrides = () => {
+		if (!overrides) overrides = /* @__PURE__ */ new Map();
+		return overrides;
+	};
+	function* entries() {
+		for (const ref of flattenMongoParamRefs(originalDraft)) yield blindCast({
+			ref: blindCast(ref),
+			value: overrides?.has(ref) ? overrides.get(ref) : ref.value,
+			codecId: ref.codecId
+		});
+	}
+	function replaceValue(handle, newValue) {
+		ensureOverrides().set(blindCast(handle), newValue);
+	}
+	function replaceValues(updates) {
+		const map = ensureOverrides();
+		for (const { ref, newValue } of updates) map.set(blindCast(ref), newValue);
+	}
+	return {
+		entries,
+		replaceValue: blindCast(replaceValue),
+		replaceValues,
+		currentDraft() {
+			if (!overrides || overrides.size === 0) return originalDraft;
+			return buildMutatedDraft(originalDraft, overrides);
+		}
+	};
+}
+//#endregion
 //#region src/mongo-runtime.ts
 function noop() {}
 var MongoRuntimeImpl = class extends RuntimeCore {
@@ -202,8 +467,9 @@ var MongoRuntimeImpl = class extends RuntimeCore {
 				warn: noop,
 				error: noop
 			},
-			contentHash: (exec) => computeMongoContentHash(exec),
-			scope: "runtime"
+			contentHash: (exec) => computeMongoContentHash(blindCast(exec)),
+			scope: "runtime",
+			planExecutionId: ""
 		};
 		super({
 			middleware,
@@ -214,6 +480,7 @@ var MongoRuntimeImpl = class extends RuntimeCore {
 		this.#driver = options.driver;
 		this.#codecs = options.context.codecs;
 	}
+	/* v8 ignore start -- one-phase lower satisfies RuntimeCore; execute uses structuralLower + resolveParams */
 	async lower(plan, ctx) {
 		return {
 			command: await this.#adapter.lower(plan, ctx),
@@ -221,6 +488,7 @@ var MongoRuntimeImpl = class extends RuntimeCore {
 			...ifDefined("resultShape", plan.resultShape)
 		};
 	}
+	/* v8 ignore stop */
 	runDriver(exec) {
 		return this.#driver.execute(exec.command);
 	}
@@ -228,14 +496,29 @@ var MongoRuntimeImpl = class extends RuntimeCore {
 		const self = this;
 		const signal = options?.signal;
 		const codecCtx = signal === void 0 ? {} : { signal };
+		const execCtx = {
+			...self.ctx,
+			planExecutionId: crypto.randomUUID()
+		};
 		const generator = async function* () {
 			checkAborted(codecCtx, "stream");
 			const compiled = await self.runBeforeCompile(plan);
-			const exec = await self.lower(compiled, codecCtx);
-			await runBeforeExecuteChain(exec, self.middleware, self.ctx);
-			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);
+			const draft = self.#adapter.structuralLower(compiled);
+			const mutator = createMongoParamRefMutator(draft);
+			await runBeforeExecuteChain({
+				meta: compiled.meta,
+				...ifDefined("resultShape", compiled.resultShape),
+				command: blindCast(draft)
+			}, self.middleware, execCtx, mutator);
+			const resolvedCommand = await self.#adapter.resolveParams(mutator.currentDraft(), codecCtx);
+			const exec = {
+				meta: compiled.meta,
+				...ifDefined("resultShape", compiled.resultShape),
+				command: resolvedCommand
+			};
+			const stream = runWithMiddleware(exec, self.middleware, execCtx, () => self.runDriver(exec));
+			for await (const rawRow of stream) if (exec.resultShape === void 0) yield blindCast(rawRow);
+			else yield blindCast(await decodeMongoRow(rawRow, exec.resultShape, self.#codecs, exec.command.collection, codecCtx));
 		};
 		return new AsyncIterableResult(generator());
 	}
@@ -247,6 +530,6 @@ function createMongoRuntime(options) {
 	return new MongoRuntimeImpl(options);
 }
 //#endregion
-export { createMongoExecutionContext, createMongoExecutionStack, createMongoRuntime };
+export { createMongoExecutionContext, createMongoExecutionStack, createMongoParamRefMutator, createMongoRuntime, flattenMongoParamRefs };
 
 //# sourceMappingURL=index.mjs.map