@prisma-next/adapter-mongo 0.5.0-dev.9 → 0.5.0

package/package.json

@@ -1,34 +1,37 @@
 {
   "name": "@prisma-next/adapter-mongo",
-  "version": "0.5.0-dev.9",
+  "version": "0.5.0",
+  "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "MongoDB adapter for Prisma Next (lowers commands to wire format)",
   "dependencies": {
     "arktype": "^2.1.29",
     "mongodb": "^6.16.0",
-    "@prisma-next/contract": "0.5.0-dev.9",
-    "@prisma-next/target-mongo": "0.5.0-dev.9",
-    "@prisma-next/framework-components": "0.5.0-dev.9",
-    "@prisma-next/mongo-codec": "0.5.0-dev.9",
-    "@prisma-next/config": "0.5.0-dev.9",
-    "@prisma-next/mongo-contract": "0.5.0-dev.9",
-    "@prisma-next/mongo-lowering": "0.5.0-dev.9",
-    "@prisma-next/mongo-schema-ir": "0.5.0-dev.9",
-    "@prisma-next/mongo-query-ast": "0.5.0-dev.9",
-    "@prisma-next/mongo-value": "0.5.0-dev.9",
-    "@prisma-next/mongo-wire": "0.5.0-dev.9",
-    "@prisma-next/operations": "0.5.0-dev.9",
-    "@prisma-next/utils": "0.5.0-dev.9"
+    "@prisma-next/config": "0.5.0",
+    "@prisma-next/target-mongo": "0.5.0",
+    "@prisma-next/contract": "0.5.0",
+    "@prisma-next/framework-components": "0.5.0",
+    "@prisma-next/mongo-contract": "0.5.0",
+    "@prisma-next/mongo-codec": "0.5.0",
+    "@prisma-next/mongo-lowering": "0.5.0",
+    "@prisma-next/mongo-query-ast": "0.5.0",
+    "@prisma-next/mongo-schema-ir": "0.5.0",
+    "@prisma-next/mongo-wire": "0.5.0",
+    "@prisma-next/operations": "0.5.0",
+    "@prisma-next/utils": "0.5.0",
+    "@prisma-next/mongo-value": "0.5.0"
   },
   "devDependencies": {
-    "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/test-utils": "0.0.1",
-    "@prisma-next/driver-mongo": "0.5.0-dev.9",
+    "vitest": "4.1.5",
+    "@prisma-next/driver-mongo": "0.5.0",
+    "@prisma-next/mongo-contract-psl": "0.5.0",
+    "@prisma-next/psl-parser": "0.5.0",
     "@prisma-next/tsconfig": "0.0.0",
+    "@prisma-next/test-utils": "0.0.1",
     "@prisma-next/tsdown": "0.0.0"
   },
   "files": [
@@ -39,6 +42,7 @@
     ".": "./dist/index.mjs",
     "./codec-types": "./dist/codec-types.mjs",
     "./control": "./dist/control.mjs",
+    "./runtime": "./dist/runtime.mjs",
     "./package.json": "./package.json"
   },
   "main": "./dist/index.mjs",

package/src/core/codecs.ts

@@ -1,4 +1,11 @@
-import { mongoCodec } from '@prisma-next/mongo-codec';
+import type { CodecDescriptor, CodecTrait } from '@prisma-next/framework-components/codec';
+import { voidParamsSchema } from '@prisma-next/framework-components/codec';
+import {
+  type MongoCodec,
+  type MongoCodecRegistry,
+  mongoCodec,
+  newMongoCodecRegistry,
+} from '@prisma-next/mongo-codec';
 import { ObjectId } from 'mongodb';
 import {
   MONGO_BOOLEAN_CODEC_ID,
@@ -12,48 +19,36 @@ import {
 
 export const mongoObjectIdCodec = mongoCodec({
   typeId: MONGO_OBJECTID_CODEC_ID,
-  targetTypes: ['objectId'],
-  traits: ['equality'],
   decode: (wire: ObjectId) => wire.toHexString(),
   encode: (value: string) => new ObjectId(value),
 });
 
 export const mongoStringCodec = mongoCodec({
   typeId: MONGO_STRING_CODEC_ID,
-  targetTypes: ['string'],
-  traits: ['equality', 'order', 'textual'],
   decode: (wire: string) => wire,
   encode: (value: string) => value,
 });
 
 export const mongoDoubleCodec = mongoCodec({
   typeId: MONGO_DOUBLE_CODEC_ID,
-  targetTypes: ['double'],
-  traits: ['equality', 'order', 'numeric'],
   decode: (wire: number) => wire,
   encode: (value: number) => value,
 });
 
 export const mongoInt32Codec = mongoCodec({
   typeId: MONGO_INT32_CODEC_ID,
-  targetTypes: ['int'],
-  traits: ['equality', 'order', 'numeric'],
   decode: (wire: number) => wire,
   encode: (value: number) => value,
 });
 
 export const mongoBooleanCodec = mongoCodec({
   typeId: MONGO_BOOLEAN_CODEC_ID,
-  targetTypes: ['bool'],
-  traits: ['equality', 'boolean'],
   decode: (wire: boolean) => wire,
   encode: (value: boolean) => value,
 });
 
 export const mongoDateCodec = mongoCodec({
   typeId: MONGO_DATE_CODEC_ID,
-  targetTypes: ['date'],
-  traits: ['equality', 'order'],
   decode: (wire: Date) => wire,
   encode: (value: Date) => value,
   encodeJson: (value: Date) => value.toISOString(),
@@ -65,16 +60,109 @@ export const mongoDateCodec = mongoCodec({
 
 export const mongoVectorCodec = mongoCodec({
   typeId: MONGO_VECTOR_CODEC_ID,
-  targetTypes: ['vector'],
-  traits: ['equality'],
   decode: (wire: readonly number[]) => wire,
   encode: (value: readonly number[]) => value,
-  renderOutputType: (typeParams) => {
-    const length = typeParams['length'];
-    if (length === undefined) return undefined;
-    if (typeof length !== 'number' || !Number.isFinite(length) || !Number.isInteger(length)) {
-      throw new Error('renderOutputType: expected positive integer "length" for Vector');
-    }
-    return `Vector<${length}>`;
-  },
 });
+
+/**
+ * The canonical set of Mongo wire-type codecs.
+ *
+ * Single source of truth for both control- and runtime-plane adapter descriptors. Don't duplicate this list — import it.
+ */
+export const mongoStandardCodecs = [
+  mongoObjectIdCodec,
+  mongoStringCodec,
+  mongoDoubleCodec,
+  mongoInt32Codec,
+  mongoBooleanCodec,
+  mongoDateCodec,
+  mongoVectorCodec,
+] as const;
+
+/**
+ * Build a {@link CodecDescriptor} for a Mongo wire-type codec.
+ *
+ * Wraps an existing {@link MongoCodec} instance into a descriptor whose factory hands out the same shared codec. Mongo's full migration to descriptor-first authoring is tracked under TML-2324; for now the descriptor view is composed from the existing `mongoCodec()` outputs.
+ */
+function descriptorFor<Id extends string>(
+  codec: MongoCodec<Id, readonly CodecTrait[]>,
+  metadata: {
+    readonly traits: readonly CodecTrait[];
+    readonly targetTypes: readonly string[];
+    readonly renderOutputType?: (typeParams: Record<string, unknown>) => string | undefined;
+  },
+): CodecDescriptor {
+  // The descriptor's `P` is structurally `Record<string, unknown>` for codecs that take params (Mongo `vector`); non-parameterized codecs ignore the slot. Cast through `unknown` to fit the `CodecDescriptor` slot's `(params: P) => …` typing without leaking a per-codec `P` into the heterogeneous descriptor list.
+  const renderOutputType = metadata.renderOutputType as
+    | CodecDescriptor['renderOutputType']
+    | undefined;
+  return {
+    codecId: codec.id,
+    traits: metadata.traits,
+    targetTypes: metadata.targetTypes,
+    paramsSchema: voidParamsSchema as CodecDescriptor['paramsSchema'],
+    isParameterized: false,
+    factory: (() => () => codec) as CodecDescriptor['factory'],
+    ...(renderOutputType !== undefined ? { renderOutputType } : {}),
+  };
+}
+
+const renderVectorOutputType = (typeParams: Record<string, unknown>): string | undefined => {
+  const length = typeParams['length'];
+  if (length === undefined) return undefined;
+  if (
+    typeof length !== 'number' ||
+    !Number.isFinite(length) ||
+    !Number.isInteger(length) ||
+    length <= 0
+  ) {
+    throw new Error('renderOutputType: expected positive integer "length" for Vector');
+  }
+  return `Vector<${length}>`;
+};
+
+/**
+ * Mongo wire-type codec descriptors. Static metadata for `traits`, `targetTypes`, and `renderOutputType` lives here (the descriptor shape) — `MongoCodec` itself is narrow and only carries the four conversion methods (TML-2357).
+ */
+export const mongoCodecDescriptors: ReadonlyArray<CodecDescriptor> = [
+  descriptorFor(mongoObjectIdCodec, { traits: ['equality'], targetTypes: ['objectId'] }),
+  descriptorFor(mongoStringCodec, {
+    traits: ['equality', 'order', 'textual'],
+    targetTypes: ['string'],
+  }),
+  descriptorFor(mongoDoubleCodec, {
+    traits: ['equality', 'order', 'numeric'],
+    targetTypes: ['double'],
+  }),
+  descriptorFor(mongoInt32Codec, {
+    traits: ['equality', 'order', 'numeric'],
+    targetTypes: ['int'],
+  }),
+  descriptorFor(mongoBooleanCodec, { traits: ['equality', 'boolean'], targetTypes: ['bool'] }),
+  descriptorFor(mongoDateCodec, { traits: ['equality', 'order'], targetTypes: ['date'] }),
+  descriptorFor(mongoVectorCodec, {
+    traits: ['equality'],
+    targetTypes: ['vector'],
+    renderOutputType: renderVectorOutputType,
+  }),
+];
+
+/**
+ * Lookup descriptor metadata by codec id — used by tests and for descriptor-side reads of static metadata.
+ */
+export function mongoDescriptorById(codecId: string): CodecDescriptor | undefined {
+  return mongoCodecDescriptors.find((d) => d.codecId === codecId);
+}
+
+/**
+ * Build a {@link MongoCodecRegistry} preloaded with the standard Mongo wire-type codecs.
+ *
+ * Single point of truth for adapter-side codec construction: used by the legacy synchronous `createMongoAdapter()` factory and by the runtime adapter descriptor's `codecs()` getter. Userland code obtains a registry via the framework's execution-stack composition (see `createMongoExecutionContext`) instead of calling this directly.
+ */
+export function buildStandardCodecRegistry(): MongoCodecRegistry {
+  const registry = newMongoCodecRegistry();
+  for (const codec of mongoStandardCodecs) {
+    registry.register(codec);
+  }
+  return registry;
+}

package/src/core/introspect-schema.ts

@@ -18,7 +18,12 @@ function parseIndexKeys(keySpec: Record<string, unknown>): MongoIndexKey[] {
   return keys;
 }
 
-function isDefaultIdIndex(doc: Document): boolean {
+/**
+ * Exported for unit tests to exercise the defensive `!key` guard; not part of
+ * the public API. Callers in this package use it via the `introspectSchema`
+ * pipeline only.
+ */
+export function isDefaultIdIndex(doc: Document): boolean {
   const key = doc['key'] as Record<string, unknown> | undefined;
   if (!key) return false;
   const entries = Object.entries(key);

package/src/core/operations.ts

@@ -1,12 +1,11 @@
-import type { OperationDescriptor } from '@prisma-next/operations';
-import { MONGO_INT32_CODEC_ID, MONGO_VECTOR_CODEC_ID } from './codec-ids';
+import type { OperationDescriptor, OperationDescriptors } from '@prisma-next/operations';
+import { MONGO_VECTOR_CODEC_ID } from './codec-ids';
 
-export const mongoVectorNearOperation = Object.freeze({
-  method: 'near',
-  args: [{ codecId: MONGO_VECTOR_CODEC_ID, nullable: false }],
-  returns: { codecId: MONGO_INT32_CODEC_ID, nullable: false },
-}) satisfies OperationDescriptor;
+export const mongoVectorNearOperation: OperationDescriptor = Object.freeze({
+  self: { codecId: MONGO_VECTOR_CODEC_ID },
+  impl: () => undefined as never,
+});
 
-export const mongoVectorOperationDescriptors: readonly OperationDescriptor[] = [
-  mongoVectorNearOperation,
-];
+export const mongoVectorOperationDescriptors: OperationDescriptors = {
+  near: mongoVectorNearOperation,
+};

package/src/exports/control.ts

@@ -8,15 +8,7 @@ export {
 } from '../core/mongo-control-driver';
 export { createMongoRunnerDeps, extractDb } from '../core/runner-deps';
 
-import {
-  mongoBooleanCodec,
-  mongoDateCodec,
-  mongoDoubleCodec,
-  mongoInt32Codec,
-  mongoObjectIdCodec,
-  mongoStringCodec,
-  mongoVectorCodec,
-} from '../core/codecs';
+import { mongoCodecDescriptors } from '../core/codecs';
 
 const mongoAdapterDescriptor: ControlAdapterDescriptor<'mongo', 'mongo'> = {
   kind: 'adapter',
@@ -34,15 +26,7 @@ const mongoAdapterDescriptor: ControlAdapterDescriptor<'mongo', 'mongo'> = {
   ]),
   types: {
     codecTypes: {
-      codecInstances: [
-        mongoObjectIdCodec,
-        mongoStringCodec,
-        mongoDoubleCodec,
-        mongoInt32Codec,
-        mongoBooleanCodec,
-        mongoDateCodec,
-        mongoVectorCodec,
-      ],
+      codecDescriptors: mongoCodecDescriptors,
       import: {
         package: '@prisma-next/adapter-mongo/codec-types',
         named: 'CodecTypes',

package/src/exports/runtime.ts

@@ -0,0 +1,48 @@
+import type {
+  ExecutionStack,
+  RuntimeAdapterDescriptor,
+  RuntimeAdapterInstance,
+} from '@prisma-next/framework-components/execution';
+import type { MongoCodecRegistry } from '@prisma-next/mongo-codec';
+import type { MongoAdapter } from '@prisma-next/mongo-lowering';
+import { buildStandardCodecRegistry, mongoCodecDescriptors } from '../core/codecs';
+import { createMongoAdapter } from '../mongo-adapter';
+
+/**
+ * adapter-mongo deliberately does NOT import the `MongoRuntimeAdapterDescriptor` type alias from `@prisma-next/mongo-runtime`. The adapter package is downstream of the Mongo runtime package only conceptually; introducing a hard import would create a workspace dependency cycle (`mongo-runtime` consumes the runtime descriptor's `create(stack)` factory; `adapter-mongo` would then need `mongo-runtime` to type the
+ * descriptor). The descriptor is shaped to satisfy the framework's `RuntimeAdapterDescriptor` plus the structural `MongoStaticContributions` (`codecs()`) that `@prisma-next/mongo-runtime` narrows to at composition time. This mirrors the `target-postgres` ↔ `sql-runtime` decoupling pattern.
+ */
+
+interface MongoRuntimeAdapterInstance
+  extends RuntimeAdapterInstance<'mongo', 'mongo'>,
+    MongoAdapter {}
+
+const mongoRuntimeAdapterDescriptor: RuntimeAdapterDescriptor<
+  'mongo',
+  'mongo',
+  MongoRuntimeAdapterInstance
+> & {
+  readonly codecs: () => MongoCodecRegistry;
+} = {
+  kind: 'adapter',
+  id: 'mongo',
+  familyId: 'mongo',
+  targetId: 'mongo',
+  version: '0.0.1',
+  types: {
+    codecTypes: {
+      codecDescriptors: mongoCodecDescriptors,
+    },
+  },
+  codecs: buildStandardCodecRegistry,
+  create(_stack: ExecutionStack<'mongo', 'mongo'>): MongoRuntimeAdapterInstance {
+    const adapter = createMongoAdapter();
+    return {
+      familyId: 'mongo' as const,
+      targetId: 'mongo' as const,
+      lower: adapter.lower.bind(adapter),
+    };
+  },
+};
+
+export default mongoRuntimeAdapterDescriptor;

package/src/lowering.ts

@@ -1,3 +1,4 @@
+import type { CodecCallContext } from '@prisma-next/framework-components/codec';
 import type { MongoCodecRegistry } from '@prisma-next/mongo-codec';
 import type {
   MongoAggExpr,
@@ -139,17 +140,18 @@ export function lowerAggExpr(expr: MongoAggExpr): unknown {
 
 export async function lowerFilter(
   filter: MongoFilterExpr,
-  codecs?: MongoCodecRegistry,
+  codecs: MongoCodecRegistry,
+  ctx: CodecCallContext,
 ): Promise<Document> {
   switch (filter.kind) {
     case 'field':
-      return { [filter.field]: { [filter.op]: await resolveValue(filter.value, codecs) } };
+      return { [filter.field]: { [filter.op]: await resolveValue(filter.value, codecs, ctx) } };
     case 'and':
-      return { $and: await Promise.all(filter.exprs.map((e) => lowerFilter(e, codecs))) };
+      return { $and: await Promise.all(filter.exprs.map((e) => lowerFilter(e, codecs, ctx))) };
     case 'or':
-      return { $or: await Promise.all(filter.exprs.map((e) => lowerFilter(e, codecs))) };
+      return { $or: await Promise.all(filter.exprs.map((e) => lowerFilter(e, codecs, ctx))) };
     case 'not':
-      return { $nor: [await lowerFilter(filter.expr, codecs)] };
+      return { $nor: [await lowerFilter(filter.expr, codecs, ctx)] };
     case 'exists':
       return { [filter.field]: { $exists: filter.exists } };
     case 'expr':
@@ -204,11 +206,12 @@ function lowerWindowField(wf: MongoWindowField): Record<string, unknown> {
 
 export async function lowerStage(
   stage: MongoPipelineStage,
-  codecs?: MongoCodecRegistry,
+  codecs: MongoCodecRegistry,
+  ctx: CodecCallContext,
 ): Promise<Record<string, unknown>> {
   switch (stage.kind) {
     case 'match':
-      return { $match: await lowerFilter(stage.filter, codecs) };
+      return { $match: await lowerFilter(stage.filter, codecs, ctx) };
     case 'project': {
       const projection: Record<string, unknown> = {};
       for (const [key, val] of Object.entries(stage.projection)) {
@@ -230,7 +233,9 @@ export async function lowerStage(
       if (stage.localField !== undefined) lookup['localField'] = stage.localField;
       if (stage.foreignField !== undefined) lookup['foreignField'] = stage.foreignField;
       if (stage.pipeline) {
-        lookup['pipeline'] = await Promise.all(stage.pipeline.map((s) => lowerStage(s, codecs)));
+        lookup['pipeline'] = await Promise.all(
+          stage.pipeline.map((s) => lowerStage(s, codecs, ctx)),
+        );
       }
       if (stage.let_) {
         lookup['let'] = lowerExprRecord(stage.let_);
@@ -271,7 +276,9 @@ export async function lowerStage(
     case 'unionWith': {
       const unionWith: Record<string, unknown> = { coll: stage.collection };
       if (stage.pipeline) {
-        unionWith['pipeline'] = await Promise.all(stage.pipeline.map((s) => lowerStage(s, codecs)));
+        unionWith['pipeline'] = await Promise.all(
+          stage.pipeline.map((s) => lowerStage(s, codecs, ctx)),
+        );
       }
       return { $unionWith: unionWith };
     }
@@ -301,7 +308,7 @@ export async function lowerStage(
       if (stage.spherical !== undefined) geoNear['spherical'] = stage.spherical;
       if (stage.maxDistance !== undefined) geoNear['maxDistance'] = stage.maxDistance;
       if (stage.minDistance !== undefined) geoNear['minDistance'] = stage.minDistance;
-      if (stage.query) geoNear['query'] = await lowerFilter(stage.query, codecs);
+      if (stage.query) geoNear['query'] = await lowerFilter(stage.query, codecs, ctx);
       if (stage.key !== undefined) geoNear['key'] = stage.key;
       if (stage.distanceMultiplier !== undefined)
         geoNear['distanceMultiplier'] = stage.distanceMultiplier;
@@ -311,7 +318,9 @@ export async function lowerStage(
     case 'facet': {
       const facetEntries = Object.entries(stage.facets);
       const facetPipelines = await Promise.all(
-        facetEntries.map(([, pipeline]) => Promise.all(pipeline.map((s) => lowerStage(s, codecs)))),
+        facetEntries.map(([, pipeline]) =>
+          Promise.all(pipeline.map((s) => lowerStage(s, codecs, ctx))),
+        ),
       );
       const facet: Record<string, unknown> = {};
       for (let i = 0; i < facetEntries.length; i++) {
@@ -336,6 +345,7 @@ export async function lowerStage(
         graphLookup['restrictSearchWithMatch'] = await lowerFilter(
           stage.restrictSearchWithMatch,
           codecs,
+          ctx,
         );
       return { $graphLookup: graphLookup };
     }
@@ -344,7 +354,7 @@ export async function lowerStage(
       if (stage.on !== undefined) merge['on'] = stage.on;
       if (stage.whenMatched !== undefined) {
         merge['whenMatched'] = Array.isArray(stage.whenMatched)
-          ? await Promise.all(stage.whenMatched.map((s) => lowerStage(s, codecs)))
+          ? await Promise.all(stage.whenMatched.map((s) => lowerStage(s, codecs, ctx)))
           : stage.whenMatched;
       }
       if (stage.whenNotMatched !== undefined) merge['whenNotMatched'] = stage.whenNotMatched;
@@ -414,7 +424,8 @@ export async function lowerStage(
 
 export async function lowerPipeline(
   stages: ReadonlyArray<MongoPipelineStage>,
-  codecs?: MongoCodecRegistry,
+  codecs: MongoCodecRegistry,
+  ctx: CodecCallContext,
 ): Promise<Array<Record<string, unknown>>> {
-  return Promise.all(stages.map((s) => lowerStage(s, codecs)));
+  return Promise.all(stages.map((s) => lowerStage(s, codecs, ctx)));
 }

package/src/mongo-adapter.ts

@@ -1,4 +1,5 @@
-import { createMongoCodecRegistry, type MongoCodecRegistry } from '@prisma-next/mongo-codec';
+import type { CodecCallContext } from '@prisma-next/framework-components/codec';
+import type { MongoCodecRegistry } from '@prisma-next/mongo-codec';
 import type { MongoAdapter } from '@prisma-next/mongo-lowering';
 import type {
   MongoQueryPlan,
@@ -18,6 +19,7 @@ import {
   UpdateManyWireCommand,
   UpdateOneWireCommand,
 } from '@prisma-next/mongo-wire';
+import { buildStandardCodecRegistry } from './core/codecs';
 import { lowerFilter, lowerPipeline, lowerStage } from './lowering';
 import { resolveValue } from './resolve-value';
 
@@ -28,15 +30,17 @@ function isUpdatePipeline(
 }
 
 class MongoAdapterImpl implements MongoAdapter {
-  readonly #codecs: MongoCodecRegistry | undefined;
+  readonly #codecs: MongoCodecRegistry;
 
-  constructor(codecs?: MongoCodecRegistry) {
+  constructor(codecs: MongoCodecRegistry) {
     this.#codecs = codecs;
   }
 
-  async #resolveDocument(expr: MongoExpr): Promise<Document> {
+  async #resolveDocument(expr: MongoExpr, ctx: CodecCallContext): Promise<Document> {
     const entries = Object.entries(expr);
-    const resolved = await Promise.all(entries.map(([, val]) => resolveValue(val, this.#codecs)));
+    const resolved = await Promise.all(
+      entries.map(([, val]) => resolveValue(val, this.#codecs, ctx)),
+    );
     const result: Record<string, unknown> = {};
     for (let i = 0; i < entries.length; i++) {
       const entry = entries[i];
@@ -47,54 +51,57 @@ class MongoAdapterImpl implements MongoAdapter {
     return result;
   }
 
-  async #lowerUpdate(update: MongoUpdateSpec): Promise<Document | ReadonlyArray<Document>> {
+  async #lowerUpdate(
+    update: MongoUpdateSpec,
+    ctx: CodecCallContext,
+  ): Promise<Document | ReadonlyArray<Document>> {
     if (isUpdatePipeline(update)) {
-      return Promise.all(update.map((stage) => lowerStage(stage, this.#codecs)));
+      return Promise.all(update.map((stage) => lowerStage(stage, this.#codecs, ctx)));
     }
-    return this.#resolveDocument(update);
+    return this.#resolveDocument(update, ctx);
   }
 
-  async lower(plan: MongoQueryPlan): Promise<AnyMongoWireCommand> {
+  async lower(plan: MongoQueryPlan, ctx: CodecCallContext): Promise<AnyMongoWireCommand> {
     const { command } = plan;
     switch (command.kind) {
       case 'insertOne':
         return new InsertOneWireCommand(
           command.collection,
-          await this.#resolveDocument(command.document),
+          await this.#resolveDocument(command.document, ctx),
         );
       case 'updateOne': {
         const [filter, update] = await Promise.all([
-          lowerFilter(command.filter, this.#codecs),
-          this.#lowerUpdate(command.update),
+          lowerFilter(command.filter, this.#codecs, ctx),
+          this.#lowerUpdate(command.update, ctx),
         ]);
         return new UpdateOneWireCommand(command.collection, filter, update, command.upsert);
       }
       case 'insertMany':
         return new InsertManyWireCommand(
           command.collection,
-          await Promise.all(command.documents.map((doc) => this.#resolveDocument(doc))),
+          await Promise.all(command.documents.map((doc) => this.#resolveDocument(doc, ctx))),
         );
       case 'updateMany': {
         const [filter, update] = await Promise.all([
-          lowerFilter(command.filter, this.#codecs),
-          this.#lowerUpdate(command.update),
+          lowerFilter(command.filter, this.#codecs, ctx),
+          this.#lowerUpdate(command.update, ctx),
         ]);
         return new UpdateManyWireCommand(command.collection, filter, update, command.upsert);
       }
       case 'deleteOne':
         return new DeleteOneWireCommand(
           command.collection,
-          await lowerFilter(command.filter, this.#codecs),
+          await lowerFilter(command.filter, this.#codecs, ctx),
         );
       case 'deleteMany':
         return new DeleteManyWireCommand(
           command.collection,
-          await lowerFilter(command.filter, this.#codecs),
+          await lowerFilter(command.filter, this.#codecs, ctx),
         );
       case 'findOneAndUpdate': {
         const [filter, update] = await Promise.all([
-          lowerFilter(command.filter, this.#codecs),
-          this.#lowerUpdate(command.update),
+          lowerFilter(command.filter, this.#codecs, ctx),
+          this.#lowerUpdate(command.update, ctx),
         ]);
         return new FindOneAndUpdateWireCommand(
           command.collection,
@@ -108,13 +115,13 @@ class MongoAdapterImpl implements MongoAdapter {
       case 'findOneAndDelete':
         return new FindOneAndDeleteWireCommand(
           command.collection,
-          await lowerFilter(command.filter, this.#codecs),
+          await lowerFilter(command.filter, this.#codecs, ctx),
           command.sort,
         );
       case 'aggregate':
         return new AggregateWireCommand(
           command.collection,
-          await lowerPipeline(command.pipeline, this.#codecs),
+          await lowerPipeline(command.pipeline, this.#codecs, ctx),
         );
       case 'rawAggregate':
         return new AggregateWireCommand(command.collection, command.pipeline);
@@ -150,32 +157,26 @@ class MongoAdapterImpl implements MongoAdapter {
   }
 }
 
-import {
-  mongoBooleanCodec,
-  mongoDateCodec,
-  mongoDoubleCodec,
-  mongoInt32Codec,
-  mongoObjectIdCodec,
-  mongoStringCodec,
-  mongoVectorCodec,
-} from './core/codecs';
-
-function defaultCodecRegistry(): MongoCodecRegistry {
-  const registry = createMongoCodecRegistry();
-  for (const codec of [
-    mongoObjectIdCodec,
-    mongoStringCodec,
-    mongoDoubleCodec,
-    mongoInt32Codec,
-    mongoBooleanCodec,
-    mongoDateCodec,
-    mongoVectorCodec,
-  ]) {
-    registry.register(codec);
-  }
-  return registry;
+/**
+ * Construct a Mongo adapter with the standard wire-type codecs registered
+ * for encode-side dispatch (`MongoParamRef.codecId` lookups).
+ *
+ * The runtime-side codec registry the runtime decodes against is composed
+ * separately by `createMongoExecutionContext`. This factory exists for
+ * direct adapter use (the runtime descriptor's `create(stack)` calls
+ * through it). User code should compose a stack/context instead.
+ */
+export function createMongoAdapter(): MongoAdapter {
+  return new MongoAdapterImpl(buildStandardCodecRegistry());
 }
 
-export function createMongoAdapter(codecs?: MongoCodecRegistry): MongoAdapter {
-  return new MongoAdapterImpl(codecs ?? defaultCodecRegistry());
+/**
+ * Internal escape hatch — direct adapter construction with a caller-supplied
+ * codec registry, used only by adapter unit tests that exercise the
+ * encode-side codec-dispatch path with synthetic codecs. Not re-exported
+ * from the package's public surface and not for production use; production
+ * callers compose a `MongoExecutionStack` and `MongoExecutionContext`.
+ */
+export function _unstable_createMongoAdapterWithCodecs(codecs: MongoCodecRegistry): MongoAdapter {
+  return new MongoAdapterImpl(codecs);
 }