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

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["#adapter","#driver","#middleware","#middlewareContext"],"sources":["../src/mongo-runtime.ts"],"sourcesContent":["import type {\n  RuntimeMiddleware,\n  RuntimeMiddlewareContext,\n} from '@prisma-next/framework-components/runtime';\nimport {\n  AsyncIterableResult,\n  checkMiddlewareCompatibility,\n} from '@prisma-next/framework-components/runtime';\nimport type { MongoAdapter, MongoDriver } from '@prisma-next/mongo-lowering';\nimport type { MongoQueryPlan } from '@prisma-next/mongo-query-ast/execution';\n\nfunction noop() {}\nfunction now() {\n  return Date.now();\n}\n\nexport interface MongoRuntimeOptions {\n  readonly adapter: MongoAdapter;\n  readonly driver: MongoDriver;\n  readonly contract: unknown;\n  readonly targetId: string;\n  readonly middleware?: readonly RuntimeMiddleware[];\n  readonly mode?: 'strict' | 'permissive';\n}\n\nexport interface MongoRuntime {\n  execute<Row>(plan: MongoQueryPlan<Row>): AsyncIterableResult<Row>;\n  close(): Promise<void>;\n}\n\nclass MongoRuntimeImpl implements MongoRuntime {\n  readonly #adapter: MongoAdapter;\n  readonly #driver: MongoDriver;\n  readonly #middleware: readonly RuntimeMiddleware[];\n  readonly #middlewareContext: RuntimeMiddlewareContext;\n\n  constructor(options: MongoRuntimeOptions) {\n    this.#adapter = options.adapter;\n    this.#driver = options.driver;\n\n    const middleware = options.middleware ? [...options.middleware] : [];\n    for (const mw of middleware) {\n      checkMiddlewareCompatibility(mw, 'mongo', options.targetId);\n    }\n    this.#middleware = middleware;\n\n    this.#middlewareContext = {\n      contract: options.contract,\n      mode: options.mode ?? 'strict',\n      now,\n      log: { info: noop, warn: noop, error: noop },\n    };\n  }\n\n  execute<Row>(plan: MongoQueryPlan<Row>): AsyncIterableResult<Row> {\n    const adapter = this.#adapter;\n    const driver = this.#driver;\n    const middleware = this.#middleware;\n    const ctx = this.#middlewareContext;\n\n    const iterator = async function* (): AsyncGenerator<Row, void, unknown> {\n      const startedAt = ctx.now();\n      let rowCount = 0;\n      let completed = false;\n      let failed = false;\n\n      try {\n        for (const mw of middleware) {\n          if (mw.beforeExecute) {\n            await mw.beforeExecute(plan, ctx);\n          }\n        }\n\n        const wireCommand = await adapter.lower(plan);\n\n        for await (const row of driver.execute<Row>(wireCommand)) {\n          for (const mw of middleware) {\n            if (mw.onRow) {\n              await mw.onRow(row as Record<string, unknown>, plan, ctx);\n            }\n          }\n          rowCount++;\n          yield row;\n        }\n\n        completed = true;\n      } catch (error) {\n        failed = true;\n        throw error;\n      } finally {\n        const latencyMs = ctx.now() - startedAt;\n        for (const mw of middleware) {\n          if (!mw.afterExecute) continue;\n\n          if (failed) {\n            try {\n              await mw.afterExecute(plan, { rowCount, latencyMs, completed }, ctx);\n            } catch {\n              // Ignore errors from afterExecute during error handling\n            }\n            continue;\n          }\n\n          await mw.afterExecute(plan, { rowCount, latencyMs, completed }, ctx);\n        }\n      }\n    };\n\n    return new AsyncIterableResult(iterator());\n  }\n\n  async close(): Promise<void> {\n    await this.#driver.close();\n  }\n}\n\nexport function createMongoRuntime(options: MongoRuntimeOptions): MongoRuntime {\n  return new MongoRuntimeImpl(options);\n}\n"],"mappings":";;;AAWA,SAAS,OAAO;AAChB,SAAS,MAAM;AACb,QAAO,KAAK,KAAK;;AAiBnB,IAAM,mBAAN,MAA+C;CAC7C,CAASA;CACT,CAASC;CACT,CAASC;CACT,CAASC;CAET,YAAY,SAA8B;AACxC,QAAKH,UAAW,QAAQ;AACxB,QAAKC,SAAU,QAAQ;EAEvB,MAAM,aAAa,QAAQ,aAAa,CAAC,GAAG,QAAQ,WAAW,GAAG,EAAE;AACpE,OAAK,MAAM,MAAM,WACf,8BAA6B,IAAI,SAAS,QAAQ,SAAS;AAE7D,QAAKC,aAAc;AAEnB,QAAKC,oBAAqB;GACxB,UAAU,QAAQ;GAClB,MAAM,QAAQ,QAAQ;GACtB;GACA,KAAK;IAAE,MAAM;IAAM,MAAM;IAAM,OAAO;IAAM;GAC7C;;CAGH,QAAa,MAAqD;EAChE,MAAM,UAAU,MAAKH;EACrB,MAAM,SAAS,MAAKC;EACpB,MAAM,aAAa,MAAKC;EACxB,MAAM,MAAM,MAAKC;EAEjB,MAAM,WAAW,mBAAuD;GACtE,MAAM,YAAY,IAAI,KAAK;GAC3B,IAAI,WAAW;GACf,IAAI,YAAY;GAChB,IAAI,SAAS;AAEb,OAAI;AACF,SAAK,MAAM,MAAM,WACf,KAAI,GAAG,cACL,OAAM,GAAG,cAAc,MAAM,IAAI;IAIrC,MAAM,cAAc,MAAM,QAAQ,MAAM,KAAK;AAE7C,eAAW,MAAM,OAAO,OAAO,QAAa,YAAY,EAAE;AACxD,UAAK,MAAM,MAAM,WACf,KAAI,GAAG,MACL,OAAM,GAAG,MAAM,KAAgC,MAAM,IAAI;AAG7D;AACA,WAAM;;AAGR,gBAAY;YACL,OAAO;AACd,aAAS;AACT,UAAM;aACE;IACR,MAAM,YAAY,IAAI,KAAK,GAAG;AAC9B,SAAK,MAAM,MAAM,YAAY;AAC3B,SAAI,CAAC,GAAG,aAAc;AAEtB,SAAI,QAAQ;AACV,UAAI;AACF,aAAM,GAAG,aAAa,MAAM;QAAE;QAAU;QAAW;QAAW,EAAE,IAAI;cAC9D;AAGR;;AAGF,WAAM,GAAG,aAAa,MAAM;MAAE;MAAU;MAAW;MAAW,EAAE,IAAI;;;;AAK1E,SAAO,IAAI,oBAAoB,UAAU,CAAC;;CAG5C,MAAM,QAAuB;AAC3B,QAAM,MAAKF,OAAQ,OAAO;;;AAI9B,SAAgB,mBAAmB,SAA4C;AAC7E,QAAO,IAAI,iBAAiB,QAAQ"}
+{"version":3,"file":"index.mjs","names":["#adapter","#driver","#codecs"],"sources":["../src/mongo-execution-stack.ts","../src/codecs/decoding.ts","../src/content-hash.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 { type MongoCodecRegistry, newMongoCodecRegistry } 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 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.\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 packs. Mirrors `SqlExecutionStack`. Constructed via `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 mutate the per-execution codec registry. Internal aggregation in `createMongoExecutionContext` keeps using the full `MongoCodecRegistry` (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 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.\n *\n * 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.\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 = newMongoCodecRegistry();\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 { canonicalStringify } from '@prisma-next/utils/canonical-stringify';\nimport { hashContent } from '@prisma-next/utils/hash-content';\nimport type { MongoExecutionPlan } from './mongo-execution-plan';\n\n/**\n * Computes a stable content hash for a lowered Mongo execution plan.\n *\n * Internally builds an unambiguous canonical-stringified preimage from\n * two components:\n *\n * 1. `meta.storageHash` — discriminates by schema. A migration changes the\n *    storage hash, which invalidates cached entries automatically (no\n *    per-app invalidation logic needed for schema changes).\n * 2. `exec.command` — the wire command. `canonicalStringify` produces a\n *    deterministic serialization that is stable across object key\n *    insertion order and that distinguishes types JSON would otherwise\n *    conflate (e.g. `BigInt(1)` vs `1`, `Date` vs ISO string, `Buffer`\n *    vs number array). The spread converts the frozen wire-command\n *    class instance (`InsertOneWireCommand`, `AggregateWireCommand`, …)\n *    into a plain object exposing its own enumerable properties\n *    (`kind`, `collection`, plus the payload-specific fields like\n *    `document`/`filter`/`update`/`pipeline`/…), which is what\n *    `canonicalStringify` accepts; class instances are rejected\n *    outright to prevent silent collisions.\n *\n * Unlike SQL, there is no separate \"rendered statement\" component because\n * a Mongo `MongoExecutionPlan.command` is the wire command itself —\n * canonicalizing it captures both structure and parameters in one pass.\n *\n * The components are wrapped in an object and canonicalized as a single\n * unit (rather than concatenated with a delimiter) so component\n * boundaries are unambiguous and cannot collide with a different split\n * of the same characters.\n *\n * The canonical string is then piped through `hashContent` to produce a\n * bounded, opaque digest. See `@prisma-next/utils/hash-content` for the\n * rationale.\n *\n * @internal\n */\nexport function computeMongoContentHash(exec: MongoExecutionPlan): Promise<string> {\n  // Spread `exec.command` to a plain object: `canonicalStringify`\n  // rejects class instances by design (so `Map`/`Set`/class instances\n  // cannot collapse to `{}` and silently collide). All wire-command\n  // data lives on own enumerable properties, so this preserves the\n  // same canonical form and therefore the same hash.\n  return hashContent(\n    canonicalStringify({\n      storageHash: exec.meta.storageHash,\n      command: { ...exec.command },\n    }),\n  );\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 { computeMongoContentHash } from './content-hash';\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      // ctx is only invoked by runWithMiddleware with execs this runtime lowered;\n      // the framework parameter type is the cross-family base.\n      contentHash: (exec) => computeMongoContentHash(exec as MongoExecutionPlan),\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":";;;;;;;AA0EA,SAAgB,0BAA8D,SAY3C;CAOjC,OANc,qBAAqB;EACjC,QAAQ,QAAQ;EAChB,SAAS,QAAQ;EACjB,QAAQ,QAAQ;EAChB,gBAAgB,QAAQ;EACzB,CACW;;AA0Bd,SAAgB,4BAAgE,SAG3C;CACnC,MAAM,WAAW,uBAAuB;CACxC,MAAM,yBAAS,IAAI,KAAqB;CAExC,MAAM,eAAkF;EACtF,QAAQ,MAAM;EACd,QAAQ,MAAM;EACd,GAAG,QAAQ,MAAM;EAClB;CAED,KAAK,MAAM,eAAe,cAAc;EACtC,MAAM,cAAc,YAAY,QAAQ;EACxC,KAAK,MAAM,SAAS,cAAc,YAAY,EAAE;GAC9C,MAAM,gBAAgB,OAAO,IAAI,MAAM,GAAG;GAC1C,IAAI,kBAAkB,KAAA,GACpB,MAAM,aACJ,2BACA,6BAA6B,MAAM,GAAG,oBAAoB,YAAY,GAAG,4BAA4B,cAAc,MACnH;IAAE,SAAS,MAAM;IAAI;IAAe,eAAe,YAAY;IAAI,CACpE;GAEH,SAAS,SAAS,MAAM;GACxB,OAAO,IAAI,MAAM,IAAI,YAAY,GAAG;;;CAIxC,OAAO,OAAO,OAAO;EACnB,UAAU,QAAQ;EAClB,QAAQ;EACR,OAAO,QAAQ;EAChB,CAAC;;AAGJ,UAAU,cAAc,UAA4D;CAClF,OAAO,SAAS,QAAQ;;;;ACvJ1B,MAAM,qBAAqB;AAE3B,SAAS,iBAAiB,WAA4B;CACpD,IAAI,OAAO,cAAc,UACvB,OAAO,UAAU,SAAS,qBACtB,GAAG,UAAU,UAAU,GAAG,mBAAmB,CAAC,OAC9C;CAEN,OAAO,OAAO,UAAU,CAAC,UAAU,GAAG,mBAAmB;;AAG3D,SAAS,kBACP,OACA,YACA,MACA,SACA,WACO;CAEP,MAAM,UAAU,aACd,yBACA,0BAA0B,KAAK,kBAAkB,WAAW,gBAAgB,QAAQ,KAHtE,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,IAIpE;EACE;EACA;EACA,OAAO;EACP,aAAa,iBAAiB,UAAU;EACzC,CACF;CACD,QAAQ,QAAQ;CAChB,MAAM;;AAGR,eAAsB,eACpB,KACA,OACA,UACA,YACA,MAAwB,EAAE,EACR;CAClB,IAAI,MAAM,SAAS,WACjB,OAAO;CAET,IAAI,OAAO,QAAQ,YAAY,QAAQ,MACrC,OAAO;CAET,MAAM,SAAS;CACf,MAAM,MAA+B,EAAE;CACvC,MAAM,QAA8B,EAAE;CAEtC,SAAS,aACP,MACA,SACA,MACA,QACM;EACN,MAAM,QAAQ,SAAS,IAAI,QAAQ;EACnC,IAAI,CAAC,OAAO;GACV,OAAO,KAAK;GACZ;;EAEF,MAAM,MACH,YAAY;GACX,IAAI;IACF,OAAO,MAAM,MAAM,OAAO,MAAM,IAAI,CAAC;YAC9B,OAAO;IACd,kBAAkB,OAAO,YAAY,MAAM,SAAS,KAAK;;MAEzD,CACL;;CAGH,SAAS,UACP,OACA,YACA,MACA,QACM;EAIN,QAAQ,WAAW,MAAnB;GACE,KAAK;IACH,OAAO,MAAM;IACb;GACF,KAAK;IACH,IAAI,UAAU,QAAQ,UAAU,KAAA,GAAW;KACzC,OAAO,MAAM;KACb;;IAEF,aAAa,MAAM,WAAW,SAAS,OAAO,OAAO;IACrD;GACF,KAAK,YAAY;IACf,IAAI,UAAU,QAAQ,UAAU,KAAA,GAAW;KACzC,OAAO,MAAM;KACb;;IAEF,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,MAAM,EAAE;KACvE,OAAO,MAAM;KACb;;IAEF,MAAM,OAAO;IAMb,MAAM,SAAkC,EAAE,GAAG,MAAM;IACnD,OAAO,OAAO;IACd,KAAK,MAAM,CAAC,IAAI,WAAW,OAAO,QAAQ,WAAW,OAAO,EAC1D,UAAU,KAAK,KAAK,QAAQ,GAAG,KAAK,GAAG,OAAO,MAAM;KAClD,OAAO,MAAM;MACb;IAEJ;;GAEF,KAAK,SAAS;IACZ,IAAI,UAAU,QAAQ,UAAU,KAAA,GAAW;KACzC,OAAO,MAAM;KACb;;IAEF,IAAI,CAAC,MAAM,QAAQ,MAAM,EAAE;KACzB,OAAO,MAAM;KACb;;IAEF,MAAM,MAAiB,EAAE;IACzB,OAAO,IAAI;IACX,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;KACrC,MAAM,KAAK,MAAM;KACjB,UAAU,IAAI,WAAW,SAAS,GAAG,KAAK,GAAG,MAAM,MAAM;MACvD,IAAI,KAAK;OACT;;IAEJ;;;;;CAWN,KAAK,MAAM,CAAC,GAAG,WAAW,OAAO,QAAQ,MAAM,OAAO,EACpD,UAAU,OAAO,IAAI,QAAQ,IAAI,MAAM;EACrC,IAAI,KAAK;GACT;CASJ,KAAK,MAAM,KAAK,OAAO,KAAK,OAAO,EACjC,IAAI,CAAC,OAAO,OAAO,MAAM,QAAQ,EAAE,EACjC,IAAI,KAAK,OAAO;CAIpB,MAAM,QAAQ,IAAI,MAAM;CACxB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AChIT,SAAgB,wBAAwB,MAA2C;CAMjF,OAAO,YACL,mBAAmB;EACjB,aAAa,KAAK,KAAK;EACvB,SAAS,EAAE,GAAG,KAAK,SAAS;EAC7B,CAAC,CACH;;;;ACjCH,SAAS,OAAO;AAiDhB,IAAM,mBAAN,cACU,YAEV;CACE;CACA;CACA;CAEA,YAAY,SAA8B;EACxC,MAAM,aAAa,QAAQ,aAAa,CAAC,GAAG,QAAQ,WAAW,GAAG,EAAE;EACpE,MAAM,WAAW,QAAQ,QAAQ,MAAM,OAAO;EAC9C,KAAK,MAAM,MAAM,YACf,6BAA6B,IAAI,SAAS,SAAS;EAGrD,MAAM,MAA8B;GAClC,UAAU,QAAQ,QAAQ;GAC1B,MAAM,QAAQ,QAAQ;GACtB,WAAW,KAAK,KAAK;GACrB,KAAK;IAAE,MAAM;IAAM,MAAM;IAAM,OAAO;IAAM;GAG5C,cAAc,SAAS,wBAAwB,KAA2B;GAC3E;EAED,MAAM;GAAE;GAAY;GAAK,CAAC;EAG1B,MAAM,kBADoB,QAAQ,QAAQ,MAAM,QACN,OAAO,QAAQ,QAAQ,MAAM;EACvE,KAAKA,WAAW;EAChB,KAAKC,UAAU,QAAQ;EACvB,KAAKC,UAAU,QAAQ,QAAQ;;CAGjC,MAAyB,MACvB,MACA,KAC6B;EAC7B,OAAO;GACL,SAAS,MAAM,KAAKF,SAAS,MAAM,MAAM,IAAI;GAC7C,MAAM,KAAK;GACX,GAAG,UAAU,eAAe,KAAK,YAAY;GAC9C;;CAGH,UAA6B,MAAkE;EAC7F,OAAO,KAAKC,QAAQ,QAAiC,KAAK,QAAQ;;CAGpE,QACE,MACA,SAC0B;EAC1B,MAAM,OAAO;EACb,MAAM,SAAS,SAAS;EACxB,MAAM,WAA6B,WAAW,KAAA,IAAY,EAAE,GAAG,EAAE,QAAQ;EACzE,MAAM,YAAY,mBAAuD;GACvE,aAAa,UAAU,SAAS;GAChC,MAAM,WAAW,MAAM,KAAK,iBAAiB,KAAK;GAClD,MAAM,OAAO,MAAM,KAAK,MAAM,UAAU,SAAS;GACjD,MAAM,SAAS,kBACb,MACA,KAAK,YACL,KAAK,WACC,KAAK,UAAU,KAAK,CAC3B;GACD,WAAW,MAAM,UAAU,QACzB,IAAI,KAAK,gBAAgB,KAAA,GACvB,MAAM;QAcN,MAAM,MAPgB,eACpB,QACA,KAAK,aACL,KAAKC,SACL,KAAK,QAAQ,YACb,SACD;;EAKP,OAAO,IAAI,oBAAoB,WAAW,CAAC;;CAG7C,MAAe,QAAuB;EACpC,MAAM,KAAKD,QAAQ,OAAO;;;AAI9B,SAAgB,mBAAmB,SAA4C;CAC7E,OAAO,IAAI,iBAAiB,QAAQ"}

package/package.json

@@ -1,34 +1,37 @@
 {
   "name": "@prisma-next/mongo-runtime",
-  "version": "0.5.0-dev.8",
+  "version": "0.5.0-dev.81",
+  "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "MongoDB runtime implementation for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.5.0-dev.8",
-    "@prisma-next/framework-components": "0.5.0-dev.8",
-    "@prisma-next/mongo-lowering": "0.5.0-dev.8",
-    "@prisma-next/mongo-query-ast": "0.5.0-dev.8"
+    "@prisma-next/contract": "0.5.0-dev.81",
+    "@prisma-next/framework-components": "0.5.0-dev.81",
+    "@prisma-next/mongo-lowering": "0.5.0-dev.81",
+    "@prisma-next/mongo-wire": "0.5.0-dev.81",
+    "@prisma-next/mongo-codec": "0.5.0-dev.81",
+    "@prisma-next/utils": "0.5.0-dev.81",
+    "@prisma-next/mongo-query-ast": "0.5.0-dev.81"
   },
   "devDependencies": {
     "mongodb": "^6.16.0",
-    "mongodb-memory-server": "10.4.3",
-    "tsdown": "0.18.4",
+    "mongodb-memory-server": "11.0.1",
+    "tsdown": "0.22.0",
     "typescript": "5.9.3",
-    "vitest": "4.0.17",
-    "@prisma-next/adapter-mongo": "0.5.0-dev.8",
-    "@prisma-next/middleware-telemetry": "0.5.0-dev.8",
-    "@prisma-next/mongo-contract-ts": "0.5.0-dev.8",
-    "@prisma-next/family-mongo": "0.5.0-dev.8",
-    "@prisma-next/runtime-executor": "0.5.0-dev.8",
-    "@prisma-next/mongo-value": "0.5.0-dev.8",
-    "@prisma-next/driver-mongo": "0.5.0-dev.8",
-    "@prisma-next/mongo-query-builder": "0.5.0-dev.8",
-    "@prisma-next/target-mongo": "0.5.0-dev.8",
-    "@prisma-next/mongo-contract": "0.5.0-dev.8",
+    "vitest": "4.1.5",
+    "@prisma-next/middleware-telemetry": "0.5.0-dev.81",
+    "@prisma-next/adapter-mongo": "0.5.0-dev.81",
+    "@prisma-next/mongo-contract-ts": "0.5.0-dev.81",
+    "@prisma-next/family-mongo": "0.5.0-dev.81",
+    "@prisma-next/mongo-value": "0.5.0-dev.81",
+    "@prisma-next/driver-mongo": "0.5.0-dev.81",
+    "@prisma-next/target-mongo": "0.5.0-dev.81",
     "@prisma-next/test-utils": "0.0.1",
+    "@prisma-next/tsconfig": "0.0.0",
+    "@prisma-next/mongo-contract": "0.5.0-dev.81",
     "@prisma-next/tsdown": "0.0.0",
-    "@prisma-next/tsconfig": "0.0.0"
+    "@prisma-next/mongo-query-builder": "0.5.0-dev.81"
   },
   "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/content-hash.ts

@@ -0,0 +1,53 @@
+import { canonicalStringify } from '@prisma-next/utils/canonical-stringify';
+import { hashContent } from '@prisma-next/utils/hash-content';
+import type { MongoExecutionPlan } from './mongo-execution-plan';
+
+/**
+ * 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
+ */
+export function computeMongoContentHash(exec: MongoExecutionPlan): Promise<string> {
+  // Spread `exec.command` to a plain object: `canonicalStringify`
+  // rejects class instances by design (so `Map`/`Set`/class instances
+  // cannot collapse to `{}` and silently collide). All wire-command
+  // data lives on own enumerable properties, so this preserves the
+  // same canonical form and therefore the same hash.
+  return hashContent(
+    canonicalStringify({
+      storageHash: exec.meta.storageHash,
+      command: { ...exec.command },
+    }),
+  );
+}

package/src/exports/index.ts

@@ -1,3 +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

@@ -0,0 +1,28 @@
+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';
+
+/**
+ * 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.
+ */
+export interface MongoExecutionPlan<Row = unknown> extends ExecutionPlan<Row> {
+  readonly command: AnyMongoWireCommand;
+  readonly resultShape?: MongoResultShape;
+}

package/src/mongo-execution-stack.ts

@@ -0,0 +1,158 @@
+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 { type MongoCodecRegistry, newMongoCodecRegistry } 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 = newMongoCodecRegistry();
+  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-middleware.ts

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