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

package/dist/index.d.mts

@@ -1,146 +1,10 @@
-import { AggregateCommand, AnyMongoCommand, DeleteManyCommand, DeleteOneCommand, DeleteResult, DeleteResult as DeleteResult$1, FindOneAndDeleteCommand, FindOneAndUpdateCommand, InsertManyCommand, InsertManyResult, InsertManyResult as InsertManyResult$1, InsertOneCommand, InsertOneResult, InsertOneResult as InsertOneResult$1, MongoAggAccumulator, MongoAggExpr, MongoDensifyRange, MongoFillOutput, MongoFilterExpr, MongoPipelineStage, MongoQueryPlan, MongoUpdatePipelineStage, MongoWindowField, UpdateManyCommand, UpdateOneCommand, UpdateResult, UpdateResult as UpdateResult$1 } from "@prisma-next/mongo-query-ast/execution";
-import { ExtractMongoCodecTypes, MongoContract, MongoContractWithTypeMaps, MongoTypeMaps } from "@prisma-next/mongo-contract";
+import { AggregateCommand, AnyMongoCommand, DeleteManyCommand, DeleteOneCommand, DeleteResult, DeleteResult as DeleteResult$1, FindOneAndDeleteCommand, FindOneAndUpdateCommand, InsertManyCommand, InsertManyResult, InsertManyResult as InsertManyResult$1, InsertOneCommand, InsertOneResult, InsertOneResult as InsertOneResult$1, MongoAggAccumulator, MongoAggExpr, MongoDensifyRange, MongoFieldShape, MongoFillOutput, MongoFilterExpr, MongoPipelineStage, MongoQueryPlan, MongoResultShape, MongoUpdatePipelineStage, MongoWindowField, UpdateManyCommand, UpdateOneCommand, UpdateResult, UpdateResult as UpdateResult$1 } from "@prisma-next/mongo-query-ast/execution";
+import { ExtractMongoCodecTypes, ExtractMongoTypeMaps, InferModelRow, MongoContract, MongoContractWithTypeMaps, MongoModelDefinition, MongoTypeMaps } from "@prisma-next/mongo-contract";
 import { MongoValue } from "@prisma-next/mongo-value";
+import { ContractField } from "@prisma-next/contract/types";
 
-//#region src/types.d.ts
-interface DocField {
-  readonly codecId: string;
-  readonly nullable: boolean;
-}
-type NumericField = {
-  readonly codecId: 'mongo/double@1';
-  readonly nullable: false;
-};
-type NullableNumericField = {
-  readonly codecId: 'mongo/double@1';
-  readonly nullable: true;
-};
-type StringField = {
-  readonly codecId: 'mongo/string@1';
-  readonly nullable: false;
-};
-type ArrayField = {
-  readonly codecId: 'mongo/array@1';
-  readonly nullable: false;
-};
-type BooleanField = {
-  readonly codecId: 'mongo/bool@1';
-  readonly nullable: false;
-};
-type DateField = {
-  readonly codecId: 'mongo/date@1';
-  readonly nullable: false;
-};
-type NullableDocField = {
-  readonly codecId: string;
-  readonly nullable: true;
-};
-type LiteralValue<F extends DocField> = F extends StringField ? string : F extends NumericField ? number : F extends BooleanField ? boolean : F extends DateField ? Date : unknown;
-type DocShape = Record<string, DocField>;
-type ExtractCodecId<F> = F extends {
-  type: {
-    kind: 'scalar';
-    codecId: infer C;
-  };
-} ? C : F extends {
-  codecId: infer C extends string;
-} ? C : string;
-type ModelToDocShape<TContract extends MongoContract, ModelName extends string & keyof TContract['models']> = { [K in keyof TContract['models'][ModelName]['fields'] & string]: {
-  readonly codecId: ExtractCodecId<TContract['models'][ModelName]['fields'][K]>;
-  readonly nullable: TContract['models'][ModelName]['fields'][K]['nullable'];
-} };
-type ResolveRow<Shape extends DocShape, CodecTypes extends Record<string, {
-  readonly output: unknown;
-}>> = { -readonly [K in keyof Shape & string]: Shape[K]['codecId'] extends keyof CodecTypes ? Shape[K]['nullable'] extends true ? CodecTypes[Shape[K]['codecId']]['output'] | null : CodecTypes[Shape[K]['codecId']]['output'] : unknown };
-interface TypedAggExpr<F extends DocField> {
-  readonly _field: F;
-  readonly node: MongoAggExpr;
-}
-interface TypedAccumulatorExpr<F extends DocField> {
-  readonly _field: F;
-  readonly node: MongoAggAccumulator;
-}
-type ExtractDocShape<T extends Record<string, TypedAggExpr<DocField>>> = { [K in keyof T & string]: T[K]['_field'] };
-type SortSpec<S extends DocShape> = Partial<Record<keyof S & string, 1 | -1>>;
-type ProjectedShape<Shape extends DocShape, Spec extends Record<string, 1 | TypedAggExpr<DocField>>> = { [K in keyof Spec & string]: Spec[K] extends 1 ? K extends keyof Shape ? Shape[K] : DocField : Spec[K] extends TypedAggExpr<infer F> ? F : DocField } & ('_id' extends keyof Shape ? '_id' extends keyof Spec ? Record<keyof never, never> : Pick<Shape, '_id'> : Record<keyof never, never>);
-type GroupSpec = {
-  _id: TypedAggExpr<DocField> | null;
-  [key: string]: TypedAggExpr<DocField> | TypedAccumulatorExpr<DocField> | null;
-};
-type GroupedDocShape<Spec extends GroupSpec> = { [K in keyof Spec & string]: Spec[K] extends TypedAggExpr<infer F> ? F : Spec[K] extends TypedAccumulatorExpr<infer F> ? F : Spec[K] extends null ? {
-  readonly codecId: 'mongo/null@1';
-  readonly nullable: true;
-} : DocField };
-/**
- * Intentionally identity — full array element type extraction is deferred.
- * Used by `UnwoundShape` so the unwind result shape can be refined later
- * without changing the public API.
- */
-type UnwrapArrayDocField<F extends DocField> = F;
-type UnwoundShape<S extends DocShape, K$1 extends keyof S & string> = { [P in keyof S & string]: P extends K$1 ? UnwrapArrayDocField<S[P]> : S[P] };
-//#endregion
-//#region src/accumulator-helpers.d.ts
-declare const acc: {
-  sum<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<F>;
-  avg(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<NullableNumericField>;
-  min<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
-    readonly codecId: F["codecId"];
-    readonly nullable: true;
-  }>;
-  max<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
-    readonly codecId: F["codecId"];
-    readonly nullable: true;
-  }>;
-  first<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
-    readonly codecId: F["codecId"];
-    readonly nullable: true;
-  }>;
-  last<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
-    readonly codecId: F["codecId"];
-    readonly nullable: true;
-  }>;
-  push(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<ArrayField>;
-  addToSet(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<ArrayField>;
-  count(): TypedAccumulatorExpr<NumericField>;
-  stdDevPop(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<NullableNumericField>;
-  stdDevSamp(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<NullableNumericField>;
-  firstN(args: {
-    input: TypedAggExpr<DocField>;
-    n: TypedAggExpr<NumericField>;
-  }): TypedAccumulatorExpr<ArrayField>;
-  lastN(args: {
-    input: TypedAggExpr<DocField>;
-    n: TypedAggExpr<NumericField>;
-  }): TypedAccumulatorExpr<ArrayField>;
-  maxN(args: {
-    input: TypedAggExpr<DocField>;
-    n: TypedAggExpr<NumericField>;
-  }): TypedAccumulatorExpr<ArrayField>;
-  minN(args: {
-    input: TypedAggExpr<DocField>;
-    n: TypedAggExpr<NumericField>;
-  }): TypedAccumulatorExpr<ArrayField>;
-  top(args: {
-    output: TypedAggExpr<DocField>;
-    sortBy: Readonly<Record<string, 1 | -1>>;
-  }): TypedAccumulatorExpr<DocField>;
-  bottom(args: {
-    output: TypedAggExpr<DocField>;
-    sortBy: Readonly<Record<string, 1 | -1>>;
-  }): TypedAccumulatorExpr<DocField>;
-  topN(args: {
-    output: TypedAggExpr<DocField>;
-    sortBy: Readonly<Record<string, 1 | -1>>;
-    n: TypedAggExpr<NumericField>;
-  }): TypedAccumulatorExpr<ArrayField>;
-  bottomN(args: {
-    output: TypedAggExpr<DocField>;
-    sortBy: Readonly<Record<string, 1 | -1>>;
-    n: TypedAggExpr<NumericField>;
-  }): TypedAccumulatorExpr<ArrayField>;
-};
-//#endregion
 //#region src/resolve-path.d.ts
+
 /**
  * Marker `DocField` variant representing a non-leaf (value-object) path in
  * a [NestedDocShape]. Extends `DocField` with a `fields` property carrying
@@ -162,6 +26,57 @@ interface ObjectField<N$1 extends NestedDocShape> extends DocField {
   readonly nullable: boolean;
   readonly fields: N$1;
 }
+/**
+ * Marker `DocField` variant representing "an array of foreign-model rows"
+ * — the result of a `$lookup` whose foreign side was selected via the
+ * typed `col` accessor. `ModelName` is the literal foreign model name
+ * (e.g. `'User'`), preserved in the type so `ResolveRow` can resolve the
+ * field to `ResolveRow<ModelToDocShape<TC, ModelName>, …>[]` rather than
+ * the opaque `unknown[]` produced by the legacy `mongo/array@1` sentinel.
+ *
+ * Like `ObjectField`, the codec id is a purely type-level sentinel —
+ * there is no runtime codec entry for `'prisma/modelArray@1'`. The
+ * surrounding pipeline emits the standard `MongoLookupStage` whose
+ * runtime shape is unchanged; the marker exists solely to thread the
+ * foreign element type through the result-row resolver.
+ */
+interface ModelArrayField<ModelName$1 extends string> extends DocField {
+  readonly codecId: 'prisma/modelArray@1';
+  readonly nullable: false;
+  readonly model: ModelName$1;
+}
+/**
+ * Phantom-symbol brand placed on `ModelToDocShape`'s output (and inherited
+ * through shape-extending stages like `addFields`, `match`, `lookup`) so
+ * `ResolveRow` can route value-object resolution through `InferModelRow`
+ * — which walks the contract's `valueObjects` registry and resolves
+ * nested types — instead of falling through the codec-lookup branch to
+ * `unknown`.
+ *
+ * The brand is keyed on a `unique symbol` rather than a string so it is
+ * invisible to every `keyof Shape & string` walk in the package
+ * (`SortSpec`, `ProjectedShape`, `GroupedDocShape`, the field accessor's
+ * `Object.keys` iteration, etc.). Field accessors do not surface a
+ * `__modelOrigin` autocomplete entry; sorts cannot key on it; projections
+ * cannot reference it.
+ *
+ * Shape-extending stages preserve the brand because intersection types
+ * (`Shape & NewFields`) carry through symbol-keyed properties. Shape-
+ * replacing stages (`replaceRoot`, `group`, `project`) construct fresh
+ * `DocShape`s from scratch, naturally dropping the brand — which is the
+ * intended behaviour, since those stages legitimately leave model
+ * territory.
+ */
+declare const ModelOriginBrand: unique symbol;
+type ModelOriginBrand = typeof ModelOriginBrand;
+/**
+ * Brand carrier — a Shape whose row type should be resolved via
+ * `InferModelRow<TContract, ModelName>` rather than the per-field codec
+ * walk. Use as `ModelToDocShape<TC, ModelName> & ModelOriginBranded<ModelName>`.
+ */
+type ModelOriginBranded<ModelName$1 extends string> = {
+  readonly [ModelOriginBrand]?: ModelName$1;
+};
 /**
  * Document shape that carries nested value-object sub-shapes.
  *
@@ -254,7 +169,7 @@ type VONestedShape<TContract extends ContractHasValueObjects, VOName$1 extends s
  * literal field record collapses `keyof` to `string` and the result hover
  * degrades to `{ readonly [x: string]: any }`.
  */
-type ModelNestedShape<TContract extends MongoContract, ModelName extends string & keyof TContract['models']> = { readonly [K in keyof TContract['models'][ModelName]['fields'] & string]: TranslateField<TContract & ContractHasValueObjects, TContract['models'][ModelName]['fields'][K]> };
+type ModelNestedShape<TContract extends MongoContract, ModelName$1 extends string & keyof TContract['models']> = { readonly [K in keyof TContract['models'][ModelName$1]['fields'] & string]: TranslateField<TContract & ContractHasValueObjects, TContract['models'][ModelName$1]['fields'][K]> };
 /**
  * Resolve a dot-path against a `NestedDocShape`. Returns:
  *  - the leaf `DocField` when `Path` terminates on a scalar/array leaf,
@@ -296,6 +211,208 @@ type ValidPaths<N$1 extends NestedDocShape> = string extends keyof N$1 ? never :
  */
 type PathCompletions<N$1 extends NestedDocShape> = ValidPaths<N$1>;
 //#endregion
+//#region src/types.d.ts
+interface DocField {
+  readonly codecId: string;
+  readonly nullable: boolean;
+}
+type NumericField = {
+  readonly codecId: 'mongo/double@1';
+  readonly nullable: false;
+};
+type NullableNumericField = {
+  readonly codecId: 'mongo/double@1';
+  readonly nullable: true;
+};
+type StringField = {
+  readonly codecId: 'mongo/string@1';
+  readonly nullable: false;
+};
+type ArrayField = {
+  readonly codecId: 'mongo/array@1';
+  readonly nullable: false;
+};
+type BooleanField = {
+  readonly codecId: 'mongo/bool@1';
+  readonly nullable: false;
+};
+type DateField = {
+  readonly codecId: 'mongo/date@1';
+  readonly nullable: false;
+};
+type NullableDocField = {
+  readonly codecId: string;
+  readonly nullable: true;
+};
+type LiteralValue<F extends DocField> = F extends StringField ? string : F extends NumericField ? number : F extends BooleanField ? boolean : F extends DateField ? Date : unknown;
+type DocShape = Record<string, DocField>;
+type ExtractCodecId<F> = F extends {
+  type: {
+    kind: 'scalar';
+    codecId: infer C;
+  };
+} ? C : F extends {
+  codecId: infer C extends string;
+} ? C : string;
+type ModelToDocShape<TContract extends MongoContract, ModelName$1 extends string & keyof TContract['models']> = { [K in keyof TContract['models'][ModelName$1]['fields'] & string]: {
+  readonly codecId: ExtractCodecId<TContract['models'][ModelName$1]['fields'][K]>;
+  readonly nullable: TContract['models'][ModelName$1]['fields'][K]['nullable'];
+} } & ModelOriginBranded<ModelName$1>;
+/**
+ * Per-field resolver. Walks `Shape`'s string keys, routing
+ * `ModelArrayField` (the lookup marker) through `InferModelRow` and
+ * everything else through the codec-lookup branch.
+ *
+ * Internal helper — public callers should use `ResolveRow`, which adds
+ * the model-origin brand detection on top.
+ */
+type ResolveFields<Shape extends DocShape, CodecTypes extends Record<string, {
+  readonly output: unknown;
+}>, TContract extends MongoContract> = { -readonly [K in keyof Shape & string]: Shape[K] extends ModelArrayField<infer ModelName> ? IsConcreteContract<TContract> extends true ? TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps> ? ModelName extends string & keyof TContract['models'] ? Array<InferModelRow<TContract, ModelName>> : unknown[] : unknown[] : unknown[] : Shape[K]['codecId'] extends keyof CodecTypes ? Shape[K]['nullable'] extends true ? CodecTypes[Shape[K]['codecId']]['output'] | null : CodecTypes[Shape[K]['codecId']]['output'] : unknown };
+/**
+ * Resolve a `DocShape` to a concrete row object type.
+ *
+ * The optional `TContract` parameter exists so the resolver can:
+ *
+ *  1. Detect the `ModelOriginBrand` on `Shape` — the phantom symbol
+ *     placed by `ModelToDocShape`. When present (and the contract has
+ *     type maps), the row is resolved via `InferModelRow<TC, M>` from
+ *     `@prisma-next/mongo-contract`, which walks scalar / valueObject /
+ *     union field kinds (handling nested value-objects and `many: true`).
+ *     This makes entry-point reads (`q.from('users').build()`) and
+ *     shape-extending stages (`match`, `addFields`) resolve value-object
+ *     fields to their concrete nested types instead of `unknown`.
+ *
+ *  2. Detect the per-field `ModelArrayField<ModelName>` marker produced
+ *     by `lookup()` and resolve it to `Array<InferModelRow<TC, M>>` so
+ *     lookup rows carry the same fully-typed foreign rows.
+ *
+ * When the contract is not threaded through (or lacks the type-map
+ * phantom), both branches fall back to `unknown` / `unknown[]` —
+ * preserving the legacy resolver shape for call sites that do not need
+ * model-row resolution.
+ */
+/**
+ * Flatten an intersection `A & B` into a single object literal so callers
+ * (and `expectTypeOf().toEqualTypeOf<…>()`) see one homogeneous record
+ * rather than the intersection form. Vitest's strict equality check
+ * treats `A & B` as distinct from the structurally-equivalent flat
+ * record, even when assignability is bidirectional, so the
+ * `ResolveRow` brand-positive branch normalises its result through this.
+ */
+type Flatten<T> = T extends infer U ? { [K in keyof U]: U[K] } : never;
+/**
+ * Decide whether to route a brand-positive `ResolveRow` through
+ * `InferModelRow`. The default `MongoContract` (no concrete models)
+ * still satisfies `MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>`
+ * because the phantom key is optional, but `InferModelRow<MongoContract, …>`
+ * collapses to an empty/unknown row. Gate on the presence of the
+ * type-maps phantom: a concrete contract attaches concrete `TestTypeMaps`-
+ * shaped maps, while the default `MongoContract` has no phantom and
+ * `ExtractMongoTypeMaps` resolves to `never`.
+ */
+type IsConcreteContract<TContract> = [ExtractMongoTypeMaps<TContract>] extends [never] ? false : true;
+type ResolveRow<Shape extends DocShape, CodecTypes extends Record<string, {
+  readonly output: unknown;
+}>, TContract extends MongoContract = MongoContract> = Shape extends {
+  readonly [ModelOriginBrand]?: infer ModelName extends string;
+} ? IsConcreteContract<TContract> extends true ? TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps> ? ModelName extends string & keyof TContract['models'] ? Flatten<InferModelRow<TContract, ModelName> & Omit<ResolveFields<Shape, CodecTypes, TContract>, keyof InferModelRow<TContract, ModelName>>> : ResolveFields<Shape, CodecTypes, TContract> : ResolveFields<Shape, CodecTypes, TContract> : ResolveFields<Shape, CodecTypes, TContract> : ResolveFields<Shape, CodecTypes, TContract>;
+interface TypedAggExpr<F extends DocField> {
+  readonly _field: F;
+  readonly node: MongoAggExpr;
+}
+interface TypedAccumulatorExpr<F extends DocField> {
+  readonly _field: F;
+  readonly node: MongoAggAccumulator;
+}
+type ExtractDocShape<T extends Record<string, TypedAggExpr<DocField>>> = { [K in keyof T & string]: T[K]['_field'] };
+type SortSpec<S extends DocShape> = Partial<Record<keyof S & string, 1 | -1>>;
+type ProjectedShape<Shape extends DocShape, Spec extends Record<string, 1 | TypedAggExpr<DocField>>> = { [K in keyof Spec & string]: Spec[K] extends 1 ? K extends keyof Shape ? Shape[K] : DocField : Spec[K] extends TypedAggExpr<infer F> ? F : DocField } & ('_id' extends keyof Shape ? '_id' extends keyof Spec ? Record<keyof never, never> : Pick<Shape, '_id'> : Record<keyof never, never>);
+type GroupSpec = {
+  _id: TypedAggExpr<DocField> | null;
+  [key: string]: TypedAggExpr<DocField> | TypedAccumulatorExpr<DocField> | null;
+};
+type GroupedDocShape<Spec extends GroupSpec> = { [K in keyof Spec & string]: Spec[K] extends TypedAggExpr<infer F> ? F : Spec[K] extends TypedAccumulatorExpr<infer F> ? F : Spec[K] extends null ? {
+  readonly codecId: 'mongo/null@1';
+  readonly nullable: true;
+} : DocField };
+/**
+ * Intentionally identity — full array element type extraction is deferred.
+ * Used by `UnwoundShape` so the unwind result shape can be refined later
+ * without changing the public API.
+ */
+type UnwrapArrayDocField<F extends DocField> = F;
+/**
+ * `$unwind` reshapes the array slot but leaves the rest of the document
+ * structurally intact. The mapped iteration is keyed on `keyof S & string`,
+ * which discards the symbol-keyed `ModelOriginBrand` carried by
+ * model-rooted shapes. Preserve the brand explicitly so post-unwind
+ * `ResolveRow` still routes through `InferModelRow` and value-object
+ * fields keep their concrete nested types.
+ */
+type UnwoundShape<S extends DocShape, K$1 extends keyof S & string> = { [P in keyof S & string]: P extends K$1 ? UnwrapArrayDocField<S[P]> : S[P] } & (S extends ModelOriginBranded<infer ModelName extends string> ? ModelOriginBranded<ModelName> : unknown);
+//#endregion
+//#region src/accumulator-helpers.d.ts
+declare const acc: {
+  sum<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<F>;
+  avg(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<NullableNumericField>;
+  min<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
+    readonly codecId: F["codecId"];
+    readonly nullable: true;
+  }>;
+  max<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
+    readonly codecId: F["codecId"];
+    readonly nullable: true;
+  }>;
+  first<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
+    readonly codecId: F["codecId"];
+    readonly nullable: true;
+  }>;
+  last<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
+    readonly codecId: F["codecId"];
+    readonly nullable: true;
+  }>;
+  push(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<ArrayField>;
+  addToSet(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<ArrayField>;
+  count(): TypedAccumulatorExpr<NumericField>;
+  stdDevPop(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<NullableNumericField>;
+  stdDevSamp(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<NullableNumericField>;
+  firstN(args: {
+    input: TypedAggExpr<DocField>;
+    n: TypedAggExpr<NumericField>;
+  }): TypedAccumulatorExpr<ArrayField>;
+  lastN(args: {
+    input: TypedAggExpr<DocField>;
+    n: TypedAggExpr<NumericField>;
+  }): TypedAccumulatorExpr<ArrayField>;
+  maxN(args: {
+    input: TypedAggExpr<DocField>;
+    n: TypedAggExpr<NumericField>;
+  }): TypedAccumulatorExpr<ArrayField>;
+  minN(args: {
+    input: TypedAggExpr<DocField>;
+    n: TypedAggExpr<NumericField>;
+  }): TypedAccumulatorExpr<ArrayField>;
+  top(args: {
+    output: TypedAggExpr<DocField>;
+    sortBy: Readonly<Record<string, 1 | -1>>;
+  }): TypedAccumulatorExpr<DocField>;
+  bottom(args: {
+    output: TypedAggExpr<DocField>;
+    sortBy: Readonly<Record<string, 1 | -1>>;
+  }): TypedAccumulatorExpr<DocField>;
+  topN(args: {
+    output: TypedAggExpr<DocField>;
+    sortBy: Readonly<Record<string, 1 | -1>>;
+    n: TypedAggExpr<NumericField>;
+  }): TypedAccumulatorExpr<ArrayField>;
+  bottomN(args: {
+    output: TypedAggExpr<DocField>;
+    sortBy: Readonly<Record<string, 1 | -1>>;
+    n: TypedAggExpr<NumericField>;
+  }): TypedAccumulatorExpr<ArrayField>;
+};
+//#endregion
 //#region src/update-ops.d.ts
 /**
  * Per-field update operations produced by `Expression`'s update methods
@@ -519,6 +636,89 @@ type FieldAccessor<S extends DocShape, N$1 extends NestedDocShape = Record<strin
  */
 declare function createFieldAccessor<S extends DocShape, N$1 extends NestedDocShape = Record<string, never>>(): FieldAccessor<S, N$1>;
 //#endregion
+//#region src/lookup-builder.d.ts
+/**
+ * Resolved foreign-model name for a contract root. Looks `RootName` up
+ * through `TContract['roots']` and intersects the result back with
+ * `keyof TContract['models']` so it can be used as a `ModelName` index
+ * into `models`. Resolves to `never` when the root is not present (this
+ * surface should never be reachable through normal use because `from()`
+ * constrains its `R` parameter to `keyof TContract['roots']`).
+ */
+type ModelOf<TContract extends MongoContract, RootName extends keyof TContract['roots'] & string> = TContract['roots'][RootName] & string & keyof TContract['models'];
+/**
+ * Object returned by the user from the `on(...)` callback. Each side is
+ * a `LeafExpression` produced by property access on the corresponding
+ * `FieldAccessor` (`local._id`, `foreign.customerId`, etc.). Carrying
+ * `LeafExpression` rather than the broader `TypedAggExpr` is what makes
+ * non-leaf returns (e.g. `fn.toUpper(local._id)`) a compile-time error
+ * without per-field operator gating — `LeafExpression` carries `_path`,
+ * `TypedAggExpr` does not (see field-accessor.ts L47–L82).
+ */
+interface LookupOnResult {
+  readonly local: LeafExpression<DocField>;
+  readonly foreign: LeafExpression<DocField>;
+}
+/**
+ * Marker brand on the captured spec returned by the `lookup(...)`
+ * callback. The phantom `_brand` literal lets `PipelineChain.lookup`
+ * accept the result of `from(...).on(...).as(...)` without exposing the
+ * internal field shape to user code, and prevents accidental
+ * construction of a malformed spec by hand.
+ */
+type LookupResultBrand = 'mongo-query-builder/lookup-result@1';
+/**
+ * Captured output of the inner `from(name).on(cb).as(name)` chain. The
+ * contract is consumed by `PipelineChain.lookup` to construct the
+ * `MongoLookupStage` (collection name comes from `models[ModelName]
+ * .storage.collection`) and to thread `ModelArrayField<ModelName>` into
+ * the resulting `Shape` so the resolver yields `Array<ForeignRow>`.
+ *
+ * Type parameters carry the foreign-root literal `RootName`, the
+ * resolved foreign model name `ModelName`, and the `As` literal so
+ * `PipelineChain.lookup`'s return type can encode the result-row
+ * promotion precisely.
+ */
+interface LookupResult<RootName extends string, ModelName$1 extends string, As extends string> {
+  readonly _brand: LookupResultBrand;
+  readonly _root: RootName;
+  readonly _model: ModelName$1;
+  readonly _localField: string;
+  readonly _foreignField: string;
+  readonly _as: As;
+}
+/**
+ * Builder returned by `from(name).on(cb)`. Carries the foreign root /
+ * model literals plus the captured local / foreign paths, and exposes
+ * `.as(name)` to finalise the spec with the user-chosen field name.
+ */
+interface LookupBuilderWithKey<RootName extends string, ModelName$1 extends string> {
+  as<As extends string>(name: As): LookupResult<RootName, ModelName$1, As>;
+}
+/**
+ * Builder returned by `from(name)`. Carries the foreign root / model
+ * literals and the local pipeline's `Shape` / nested shape so the
+ * `on(...)` callback's `local` and `foreign` accessors are typed
+ * narrowly.
+ *
+ * `on(cb)` runs the user's callback to capture the leaf paths and
+ * returns a `LookupBuilderWithKey` that exposes `.as(name)`.
+ */
+interface LookupBuilder<TContract extends MongoContract, Shape extends DocShape, Nested extends Record<string, DocField>, RootName extends string, ModelName$1 extends string> {
+  on(cb: (local: FieldAccessor<Shape, Nested>, foreign: ModelName$1 extends keyof TContract['models'] & string ? FieldAccessor<ModelToDocShape<TContract, ModelName$1>, ModelNestedShape<TContract, ModelName$1>> : never) => LookupOnResult): LookupBuilderWithKey<RootName, ModelName$1>;
+}
+/**
+ * Type of the `from` callable passed to `PipelineChain.lookup`'s outer
+ * callback. The generic argument is inferred from a string-literal
+ * argument (the same pattern as `mongoQuery<TC>(...).from('orders')`),
+ * which grounds `RootName` into the returned `LookupBuilder` *before*
+ * the inner `on(...)` callback is type-checked. This sequential
+ * inference is what makes `foreign` resolve narrowly to the foreign
+ * model's `FieldAccessor` (verified in the R1.5 spike — see spec § Open
+ * Questions / Resolved decisions).
+ */
+type LookupFrom<TContract extends MongoContract, Shape extends DocShape, Nested extends Record<string, DocField>> = <RootName extends keyof TContract['roots'] & string>(name: RootName) => LookupBuilder<TContract, Shape, Nested, RootName, ModelOf<TContract, RootName>>;
+//#endregion
 //#region src/markers.d.ts
 /**
  * Phantom capability markers for `PipelineChain`.
@@ -551,6 +751,7 @@ interface PipelineChainState {
   readonly collection: string;
   readonly stages: ReadonlyArray<MongoPipelineStage>;
   readonly storageHash: string;
+  readonly modelName?: string;
 }
 /**
  * The pipeline state in the query-builder state machine.
@@ -576,9 +777,9 @@ interface PipelineChainState {
  * marker table (and rationale per row) in
  * `docs/architecture docs/adrs/ADR 201 - State-machine pattern for typed DSL builders.md`.
  */
-declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>, Shape extends DocShape, U extends UpdateEnabled = 'update-ok', F extends FindAndModifyEnabled = 'fam-ok', L extends LeadingMatch = 'leading', N$1 extends NestedDocShape = Record<string, never>> {
+declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>, Shape extends DocShape, U$1 extends UpdateEnabled = 'update-ok', F extends FindAndModifyEnabled = 'fam-ok', L extends LeadingMatch = 'leading', N$1 extends NestedDocShape = Record<string, never>> {
   #private;
-  readonly __updateCompat: U;
+  readonly __updateCompat: U$1;
   readonly __findAndModifyCompat: F;
   readonly __leadingMatch: L;
   constructor(contract: TContract, state: PipelineChainState);
@@ -590,8 +791,8 @@ declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoCon
    * `deconstructUpdateChain` can only peel leading `$match` stages into the
    * wire-command filter.
    */
-  match(filter: MongoFilterExpr): PipelineChain<TContract, Shape, L extends 'leading' ? U : 'update-cleared', F, L, N$1>;
-  match(fn: (fields: FieldAccessor<Shape, N$1>) => MongoFilterExpr): PipelineChain<TContract, Shape, L extends 'leading' ? U : 'update-cleared', F, L, N$1>;
+  match(filter: MongoFilterExpr): PipelineChain<TContract, Shape, L extends 'leading' ? U$1 : 'update-cleared', F, L, N$1>;
+  match(fn: (fields: FieldAccessor<Shape, N$1>) => MongoFilterExpr): PipelineChain<TContract, Shape, L extends 'leading' ? U$1 : 'update-cleared', F, L, N$1>;
   /**
    * `$sort`. Clears `UpdateEnabled` (`update` has no per-document sort) but
    * preserves `FindAndModifyEnabled` (`findAndModify` has a `sort` slot).
@@ -618,22 +819,21 @@ declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoCon
    * preserved — newly added flat fields are reachable via property access
    * (`f.newField`) but do not themselves carry nested structure.
    */
-  addFields<NewFields extends Record<string, TypedAggExpr<DocField>>>(fn: (fields: FieldAccessor<Shape, N$1>) => NewFields): PipelineChain<TContract, Shape & ExtractDocShape<NewFields>, U, 'fam-cleared', 'past-leading', N$1>;
+  addFields<NewFields extends Record<string, TypedAggExpr<DocField>>>(fn: (fields: FieldAccessor<Shape, N$1>) => NewFields): PipelineChain<TContract, Shape & ExtractDocShape<NewFields>, U$1, 'fam-cleared', 'past-leading', N$1>;
   /**
    * `$lookup`. Clears both markers — joins are not representable in either
    * the `update` or `findAndModify` wire commands. The original document's
    * nested-path shape `N` is preserved (the lookup adds a sidecar array
    * field; existing keys are untouched).
+   *
+   * The single callback receives a `from` callable that grounds the
+   * foreign-root literal sequentially before the inner `on(...)`
+   * callback is type-checked — see `lookup-builder.ts`. The resulting
+   * `Shape` gains the `As` key as a `ModelArrayField<ModelName>` so
+   * `ResolveRow` produces `Array<ForeignRow>` (with concrete leaf
+   * types) instead of the legacy `unknown[]`.
    */
-  lookup<ForeignRoot extends keyof TContract['roots'] & string, As extends string>(options: {
-    from: ForeignRoot;
-    localField: keyof Shape & string;
-    foreignField: string;
-    as: As;
-  }): PipelineChain<TContract, Shape & Record<As, {
-    readonly codecId: 'mongo/array@1';
-    readonly nullable: false;
-  }>, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  lookup<RootName extends string, ModelName$1 extends string, As extends string>(fn: (from: LookupFrom<TContract, Shape, N$1>) => LookupResult<RootName, ModelName$1, As>): PipelineChain<TContract, Shape & Record<As, ModelArrayField<ModelName$1>>, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
   /**
    * `$project`. Preserves `UpdateEnabled` (representable as update-with-pipeline
    * `$project` / `$unset`); clears `FindAndModifyEnabled` (use `.project()` on
@@ -644,8 +844,8 @@ declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoCon
    * fundamentally rewrites the document, so dot-paths into the *source*
    * document are no longer meaningful downstream.
    */
-  project<K$1 extends keyof Shape & string>(...keys: K$1[]): PipelineChain<TContract, Pick<Shape, K$1 | ('_id' extends keyof Shape ? '_id' : never)>, U, 'fam-cleared', 'past-leading'>;
-  project<Spec extends Record<string, 1 | TypedAggExpr<DocField>>>(fn: (fields: FieldAccessor<Shape, N$1>) => Spec): PipelineChain<TContract, ProjectedShape<Shape, Spec>, U, 'fam-cleared', 'past-leading'>;
+  project<K$1 extends keyof Shape & string>(...keys: K$1[]): PipelineChain<TContract, Pick<Shape, K$1 | ('_id' extends keyof Shape ? '_id' : never)>, U$1, 'fam-cleared', 'past-leading'>;
+  project<Spec extends Record<string, 1 | TypedAggExpr<DocField>>>(fn: (fields: FieldAccessor<Shape, N$1>) => Spec): PipelineChain<TContract, ProjectedShape<Shape, Spec>, U$1, 'fam-cleared', 'past-leading'>;
   /**
    * `$unwind`. Clears both markers — array unrolling produces multiple output
    * documents per input, incompatible with both single-document update and
@@ -668,7 +868,7 @@ declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoCon
    * Nested path shape is reset — the replaced root has no relation to
    * the original document structure.
    */
-  replaceRoot<NewShape extends DocShape>(fn: (fields: FieldAccessor<Shape, N$1>) => Expression<DocField> | TypedAggExpr<DocField>): PipelineChain<TContract, NewShape, U, 'fam-cleared', 'past-leading'>;
+  replaceRoot<NewShape extends DocShape>(fn: (fields: FieldAccessor<Shape, N$1>) => Expression<DocField> | TypedAggExpr<DocField>): PipelineChain<TContract, NewShape, U$1, 'fam-cleared', 'past-leading'>;
   count<Field extends string>(field: Field): PipelineChain<TContract, Record<Field, {
     readonly codecId: 'mongo/double@1';
     readonly nullable: false;
@@ -684,7 +884,7 @@ declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoCon
    * `$redact`. Preserves `UpdateEnabled`; clears `FindAndModifyEnabled`.
    * Shape- and nested-path-preserving (the document tree is unchanged).
    */
-  redact(fn: (fields: FieldAccessor<Shape, N$1>) => Expression<DocField> | TypedAggExpr<DocField>): PipelineChain<TContract, Shape, U, 'fam-cleared', 'past-leading', N$1>;
+  redact(fn: (fields: FieldAccessor<Shape, N$1>) => Expression<DocField> | TypedAggExpr<DocField>): PipelineChain<TContract, Shape, U$1, 'fam-cleared', 'past-leading', N$1>;
   /**
    * `$out` write terminal. Materialises the pipeline output into
    * `collection` (optionally in `db`), replacing any prior contents. Unlike
@@ -816,23 +1016,23 @@ declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoCon
    * runtime error is thrown as a defensive check (the type system should
    * prevent this).
    */
-  findOneAndUpdate(this: PipelineChain<TContract, Shape, U, 'fam-ok', L, N$1>, updaterFn: (fields: FieldAccessor<Shape, N$1>) => UpdaterResult, opts?: {
+  findOneAndUpdate(this: PipelineChain<TContract, Shape, U$1, 'fam-ok', L, N$1>, updaterFn: (fields: FieldAccessor<Shape, N$1>) => UpdaterResult, opts?: {
     readonly upsert?: boolean;
     readonly returnDocument?: 'before' | 'after';
-  }): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>> | null, FindOneAndUpdateCommand>;
+  }): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, TContract> | null, FindOneAndUpdateCommand>;
   /**
    * Find a single document matching the accumulated pipeline and delete it.
    * Same marker gating and deconstruction as `findOneAndUpdate`.
    */
-  findOneAndDelete(this: PipelineChain<TContract, Shape, U, 'fam-ok', L, N$1>): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>> | null, FindOneAndDeleteCommand>;
+  findOneAndDelete(this: PipelineChain<TContract, Shape, U$1, 'fam-ok', L, N$1>): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, TContract> | null, FindOneAndDeleteCommand>;
   /**
    * Materialise the chain as a `MongoQueryPlan` wrapping an `AggregateCommand`.
    */
-  build(): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>>, AggregateCommand>;
+  build(): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, TContract>, AggregateCommand>;
   /**
    * Alias for `build()` — surfaces the read intent at the call site.
    */
-  aggregate(): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>>, AggregateCommand>;
+  aggregate(): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, TContract>, AggregateCommand>;
 }
 //#endregion
 //#region src/expression-helpers.d.ts
@@ -1014,14 +1214,14 @@ declare const fn: {
  *    accidentally produce an unqualified write by forgetting to `.match(...)`
  *    later in the chain. Bodies land in M2.
  */
-declare class CollectionHandle<TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>, ModelName extends keyof TContract['models'] & string> extends PipelineChain<TContract, ModelToDocShape<TContract, ModelName>, 'update-cleared', 'fam-cleared', 'leading', ModelNestedShape<TContract, ModelName>> {
+declare class CollectionHandle<TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>, ModelName$1 extends keyof TContract['models'] & string> extends PipelineChain<TContract, ModelToDocShape<TContract, ModelName$1>, 'update-cleared', 'fam-cleared', 'leading', ModelNestedShape<TContract, ModelName$1>> {
   #private;
-  constructor(ctx: BindingContext<TContract>, modelName: ModelName);
+  constructor(ctx: BindingContext<TContract>, modelName: ModelName$1);
   /**
    * Bound model name. Exposed so type tests can assert the binding without
    * flipping into a pipeline. Not part of the public-API contract.
    */
-  get _modelName(): ModelName;
+  get _modelName(): ModelName$1;
   /**
    * Begin accumulating a filter. Transitions to `FilteredCollection`.
    *
@@ -1031,8 +1231,8 @@ declare class CollectionHandle<TContract extends MongoContractWithTypeMaps<Mongo
    * Mongo — but `FilteredCollection` makes the accumulated filter
    * addressable for the write/find-and-modify terminals landing in M2/M3.
    */
-  match(filter: MongoFilterExpr): FilteredCollection<TContract, ModelName>;
-  match(fn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => MongoFilterExpr): FilteredCollection<TContract, ModelName>;
+  match(filter: MongoFilterExpr): FilteredCollection<TContract, ModelName$1>;
+  match(fn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName$1>, ModelNestedShape<TContract, ModelName$1>>) => MongoFilterExpr): FilteredCollection<TContract, ModelName$1>;
   /**
    * Insert a single document. Document fields are passed straight through to
    * the wire `InsertOneCommand` — codec normalisation happens at the
@@ -1055,7 +1255,7 @@ declare class CollectionHandle<TContract extends MongoContractWithTypeMaps<Mongo
    * unqualified write by forgetting to `.match(...)` first. Pair with
    * `.match(...).updateMany(...)` for the filtered case.
    */
-  updateAll(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateManyCommand>;
+  updateAll(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName$1>, ModelNestedShape<TContract, ModelName$1>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateManyCommand>;
   /**
    * Delete *every* document in the collection. See `updateAll` for the
    * rationale around the unqualified-write surface being limited to this
@@ -1072,7 +1272,7 @@ declare class CollectionHandle<TContract extends MongoContractWithTypeMaps<Mongo
    * new document derived from the filter equality fields plus the update
    * spec when no match is found; otherwise updates the matched document.
    */
-  upsertOne(filterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => MongoFilterExpr, updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateOneCommand>;
+  upsertOne(filterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName$1>, ModelNestedShape<TContract, ModelName$1>>) => MongoFilterExpr, updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName$1>, ModelNestedShape<TContract, ModelName$1>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateOneCommand>;
 }
 /**
  * State reached after one or more `.match(...)` calls on `CollectionHandle`.
@@ -1098,10 +1298,10 @@ declare class CollectionHandle<TContract extends MongoContractWithTypeMaps<Mongo
  * — those are insert or unqualified-write operations that are nonsense
  * after a filter has been applied.
  */
-declare class FilteredCollection<TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>, ModelName extends keyof TContract['models'] & string> extends PipelineChain<TContract, ModelToDocShape<TContract, ModelName>, 'update-cleared', 'fam-cleared', 'leading', ModelNestedShape<TContract, ModelName>> {
+declare class FilteredCollection<TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>, ModelName$1 extends keyof TContract['models'] & string> extends PipelineChain<TContract, ModelToDocShape<TContract, ModelName$1>, 'update-cleared', 'fam-cleared', 'leading', ModelNestedShape<TContract, ModelName$1>> {
   #private;
-  constructor(ctx: BindingContext<TContract>, modelName: ModelName, filters: ReadonlyArray<MongoFilterExpr>);
-  get _modelName(): ModelName;
+  constructor(ctx: BindingContext<TContract>, modelName: ModelName$1, filters: ReadonlyArray<MongoFilterExpr>);
+  get _modelName(): ModelName$1;
   /**
    * Accumulated filter list. Exposed for the M2/M3 write/find-and-modify
    * terminals to splat into wire-command `filter` slots; not part of the
@@ -1115,8 +1315,8 @@ declare class FilteredCollection<TContract extends MongoContractWithTypeMaps<Mon
    * second `$match` stage), so the write/find-and-modify terminals see a
    * single authoritative filter expression.
    */
-  match(filter: MongoFilterExpr): FilteredCollection<TContract, ModelName>;
-  match(fn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => MongoFilterExpr): FilteredCollection<TContract, ModelName>;
+  match(filter: MongoFilterExpr): FilteredCollection<TContract, ModelName$1>;
+  match(fn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName$1>, ModelNestedShape<TContract, ModelName$1>>) => MongoFilterExpr): FilteredCollection<TContract, ModelName$1>;
   /**
    * Update every matching document. `updaterFn` receives a `FieldAccessor`
    * and returns an array of `TypedUpdateOp` (e.g. `[f.amount.inc(1),
@@ -1124,14 +1324,14 @@ declare class FilteredCollection<TContract extends MongoContractWithTypeMaps<Mon
    * update spec by `foldUpdateOps`, which throws on operator+path
    * collisions.
    */
-  updateMany(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateManyCommand>;
+  updateMany(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName$1>, ModelNestedShape<TContract, ModelName$1>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateManyCommand>;
   /**
    * Update at most one matching document. The driver picks the document
    * (typically the first one matched by the underlying scan); no ordering
    * guarantee is implied — chain `.sort(...)` and use the M3
    * `.findOneAndUpdate(...)` terminal when ordering matters.
    */
-  updateOne(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateOneCommand>;
+  updateOne(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName$1>, ModelNestedShape<TContract, ModelName$1>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateOneCommand>;
   /**
    * Delete every matching document.
    */
@@ -1147,7 +1347,7 @@ declare class FilteredCollection<TContract extends MongoContractWithTypeMaps<Mon
    * `CollectionHandle.upsertOne(f => filter, updaterFn)` but reuses the
    * already-accumulated `.match(...)` filter chain.
    */
-  upsertOne(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateOneCommand>;
+  upsertOne(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName$1>, ModelNestedShape<TContract, ModelName$1>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateOneCommand>;
   /**
    * Find a single matching document and apply `updaterFn` to it.
    *
@@ -1155,15 +1355,15 @@ declare class FilteredCollection<TContract extends MongoContractWithTypeMaps<Mon
    * `opts.returnDocument` (default `'after'`) controls whether the row
    * stream yields the document as it was before or after the update.
    */
-  findOneAndUpdate(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult, opts?: {
+  findOneAndUpdate(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName$1>, ModelNestedShape<TContract, ModelName$1>>) => UpdaterResult, opts?: {
     readonly upsert?: boolean;
     readonly returnDocument?: 'before' | 'after';
-  }): MongoQueryPlan<ResolveRow<ModelToDocShape<TContract, ModelName>, ExtractMongoCodecTypes<TContract>> | null, FindOneAndUpdateCommand>;
+  }): MongoQueryPlan<ResolveRow<ModelToDocShape<TContract, ModelName$1>, ExtractMongoCodecTypes<TContract>, TContract> | null, FindOneAndUpdateCommand>;
   /**
    * Find a single matching document and delete it. Returns the deleted
    * document via the row stream.
    */
-  findOneAndDelete(): MongoQueryPlan<ResolveRow<ModelToDocShape<TContract, ModelName>, ExtractMongoCodecTypes<TContract>> | null, FindOneAndDeleteCommand>;
+  findOneAndDelete(): MongoQueryPlan<ResolveRow<ModelToDocShape<TContract, ModelName$1>, ExtractMongoCodecTypes<TContract>, TContract> | null, FindOneAndDeleteCommand>;
 }
 /**
  * Bound execution context shared across the three state classes.
@@ -1194,5 +1394,12 @@ declare function mongoQuery<TContract extends MongoContractWithTypeMaps<MongoCon
   contractJson: unknown;
 }): QueryRoot<TContract>;
 //#endregion
-export { type ArrayField, type BooleanField, CollectionHandle, type DateField, type DeleteResult, type DocField, type DocShape, type Expression, type ExtractDocShape, type FieldAccessor, FilteredCollection, type FindAndModifyEnabled, type GroupSpec, type GroupedDocShape, type InsertManyResult, type InsertOneResult, type LeafExpression, type LiteralValue, type ModelNestedShape, type ModelToDocShape, type NestedDocShape, type NullableDocField, type NullableNumericField, type NumericField, type ObjectExpression, type ObjectField, type PathCompletions, PipelineChain, type ProjectedShape, type QueryRoot, type ResolvePath, type ResolveRow, type SortSpec, type StringField, type TypedAccumulatorExpr, type TypedAggExpr, type TypedUpdateOp, type UnwoundShape, type UpdateEnabled, type UpdateResult, type UpdaterResult, type ValidPaths, acc, createFieldAccessor, fn, mongoQuery };
+//#region src/result-shape.d.ts
+declare function contractFieldToMongoFieldShape(field: ContractField): MongoFieldShape;
+declare function contractModelToMongoResultShape(model: MongoModelDefinition, options?: {
+  readonly selection?: readonly string[];
+  readonly includeRelationNames?: readonly string[];
+}): MongoResultShape;
+//#endregion
+export { type ArrayField, type BooleanField, CollectionHandle, type DateField, type DeleteResult, type DocField, type DocShape, type Expression, type ExtractDocShape, type FieldAccessor, FilteredCollection, type FindAndModifyEnabled, type GroupSpec, type GroupedDocShape, type InsertManyResult, type InsertOneResult, type LeafExpression, type LiteralValue, type LookupBuilder, type LookupBuilderWithKey, type LookupFrom, type LookupOnResult, type LookupResult, type ModelArrayField, type ModelNestedShape, type ModelOf, type ModelToDocShape, type NestedDocShape, type NullableDocField, type NullableNumericField, type NumericField, type ObjectExpression, type ObjectField, type PathCompletions, PipelineChain, type ProjectedShape, type QueryRoot, type ResolvePath, type ResolveRow, type SortSpec, type StringField, type TypedAccumulatorExpr, type TypedAggExpr, type TypedUpdateOp, type UnwoundShape, type UpdateEnabled, type UpdateResult, type UpdaterResult, type ValidPaths, acc, contractFieldToMongoFieldShape, contractModelToMongoResultShape, createFieldAccessor, fn, mongoQuery };
 //# sourceMappingURL=index.d.mts.map