@prisma-next/mongo-query-builder 0.5.0-dev.9 → 0.6.0-dev.1

package/dist/index.d.mts

@@ -1,145 +1,8 @@
-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
@@ -157,11 +20,62 @@ declare const acc: {
  * nullable parent resolves to the leaf's own `nullable` — matching how
  * MongoDB treats missing intermediate documents).
  */
-interface ObjectField<N$1 extends NestedDocShape> extends DocField {
+interface ObjectField<N extends NestedDocShape> extends DocField {
   readonly codecId: 'prisma/object@1';
   readonly nullable: boolean;
-  readonly fields: N$1;
+  readonly fields: N;
+}
+/**
+ * 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 extends string> extends DocField {
+  readonly codecId: 'prisma/modelArray@1';
+  readonly nullable: false;
+  readonly model: ModelName;
 }
+/**
+ * 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 extends string> = {
+  readonly [ModelOriginBrand]?: ModelName;
+};
 /**
  * Document shape that carries nested value-object sub-shapes.
  *
@@ -235,11 +149,11 @@ type TranslateField<TContract extends ContractHasValueObjects, F> = F extends {
  * `VOs[VOName]['fields']` is preserved and the hover / indexed-access
  * surface stays concrete at instantiation time.
  */
-type VONestedShape<TContract extends ContractHasValueObjects, VOName$1 extends string> = TContract extends {
+type VONestedShape<TContract extends ContractHasValueObjects, VOName extends string> = TContract extends {
   readonly valueObjects: infer VOs extends Record<string, {
     readonly fields: Record<string, unknown>;
   }>;
-} ? VOName$1 extends keyof VOs ? { readonly [K in keyof VOs[VOName$1]['fields'] & string]: TranslateField<TContract, VOs[VOName$1]['fields'][K]> } : never : never;
+} ? VOName extends keyof VOs ? { readonly [K in keyof VOs[VOName]['fields'] & string]: TranslateField<TContract, VOs[VOName]['fields'][K]> } : never : never;
 /**
  * Build the `NestedDocShape` for a model. Scalar leaves resolve to their
  * concrete codec id; value-object fields recurse into the referenced
@@ -268,7 +182,7 @@ type ModelNestedShape<TContract extends MongoContract, ModelName extends string
  * rejects bad paths with a clear error instead of silently resolving to
  * `never`.
  */
-type ResolvePath<N$1 extends NestedDocShape, Path extends string> = Path extends `${infer Head}.${infer Rest}` ? Head extends keyof N$1 & string ? N$1[Head] extends ObjectField<infer Sub> ? ResolvePath<Sub, Rest> : never : never : Path extends keyof N$1 & string ? N$1[Path] : never;
+type ResolvePath<N extends NestedDocShape, Path extends string> = Path extends `${infer Head}.${infer Rest}` ? Head extends keyof N & string ? N[Head] extends ObjectField<infer Sub> ? ResolvePath<Sub, Rest> : never : never : Path extends keyof N & string ? N[Path] : never;
 /**
  * Union of every valid dot-path within a `NestedDocShape`. Includes
  * top-level keys (scalar leaves *and* value-object roots) and every
@@ -287,14 +201,216 @@ type ResolvePath<N$1 extends NestedDocShape, Path extends string> = Path extends
  * open-ended `keyof` cannot resolve a specific literal path, so the
  * callable form must be disabled at the type level.
  */
-type ValidPaths<N$1 extends NestedDocShape> = string extends keyof N$1 ? never : { [K in keyof N$1 & string]: N$1[K] extends ObjectField<infer Sub> ? K | `${K}.${ValidPaths<Sub>}` : K }[keyof N$1 & string];
+type ValidPaths<N extends NestedDocShape> = string extends keyof N ? never : { [K in keyof N & string]: N[K] extends ObjectField<infer Sub> ? K | `${K}.${ValidPaths<Sub>}` : K }[keyof N & string];
 /**
  * IDE-oriented alias for `ValidPaths`. Kept as a separate export so future
  * refinements (e.g. ArkType-style lazy expansion for very deep shapes) can
  * diverge from the strict `ValidPaths` constraint without breaking
  * downstream consumers. For now the two are intentionally equivalent.
  */
-type PathCompletions<N$1 extends NestedDocShape> = ValidPaths<N$1>;
+type PathCompletions<N extends NestedDocShape> = ValidPaths<N>;
+//#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 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'];
+} } & ModelOriginBranded<ModelName>;
+/**
+ * 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 extends keyof S & string> = { [P in keyof S & string]: P extends K ? 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
 /**
@@ -420,7 +536,7 @@ interface LeafExpression<F extends DocField> extends TypedAggExpr<F> {
  * so the value object can be piped through `$addFields` /
  * `$replaceRoot` / etc. as-is.
  */
-interface ObjectExpression<N$1 extends NestedDocShape> extends TypedAggExpr<ObjectField<N$1>> {
+interface ObjectExpression<N extends NestedDocShape> extends TypedAggExpr<ObjectField<N>> {
   readonly _path: string;
   exists(flag?: boolean): MongoFilterExpr;
   eq(value: null): MongoFilterExpr;
@@ -489,7 +605,7 @@ interface StageEmitters {
  * `f.rawPath(...)` remains available in that state for callers that need
  * an explicit unvalidated path.
  */
-type FieldAccessor<S extends DocShape, N$1 extends NestedDocShape = Record<string, never>> = { readonly [K in keyof S & string]: Expression<S[K]> } & (<P$1 extends ValidPaths<N$1>>(path: P$1) => Expression<ResolvePath<N$1, P$1>>) & {
+type FieldAccessor<S extends DocShape, N extends NestedDocShape = Record<string, never>> = { readonly [K in keyof S & string]: Expression<S[K]> } & (<P extends ValidPaths<N>>(path: P) => Expression<ResolvePath<N, P>>) & {
   readonly stage: StageEmitters;
   /**
    * Escape hatch: build a `LeafExpression<F>` for an unvalidated string
@@ -517,7 +633,90 @@ type FieldAccessor<S extends DocShape, N$1 extends NestedDocShape = Record<strin
  * `undefined` to keep accidental coercion behaviour unsurprising —
  * matching the previous `FieldProxy` / `FilterProxy` semantics.
  */
-declare function createFieldAccessor<S extends DocShape, N$1 extends NestedDocShape = Record<string, never>>(): FieldAccessor<S, N$1>;
+declare function createFieldAccessor<S extends DocShape, N extends NestedDocShape = Record<string, never>>(): FieldAccessor<S, N>;
+//#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 extends string, As extends string> {
+  readonly _brand: LookupResultBrand;
+  readonly _root: RootName;
+  readonly _model: ModelName;
+  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 extends string> {
+  as<As extends string>(name: As): LookupResult<RootName, ModelName, 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 extends string> {
+  on(cb: (local: FieldAccessor<Shape, Nested>, foreign: ModelName extends keyof TContract['models'] & string ? FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>> : never) => LookupOnResult): LookupBuilderWithKey<RootName, ModelName>;
+}
+/**
+ * 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
 /**
@@ -551,6 +750,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,7 +776,7 @@ 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 extends UpdateEnabled = 'update-ok', F extends FindAndModifyEnabled = 'fam-ok', L extends LeadingMatch = 'leading', N extends NestedDocShape = Record<string, never>> {
   #private;
   readonly __updateCompat: U;
   readonly __findAndModifyCompat: F;
@@ -590,27 +790,27 @@ 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 : 'update-cleared', F, L, N>;
+  match(fn: (fields: FieldAccessor<Shape, N>) => MongoFilterExpr): PipelineChain<TContract, Shape, L extends 'leading' ? U : 'update-cleared', F, L, N>;
   /**
    * `$sort`. Clears `UpdateEnabled` (`update` has no per-document sort) but
    * preserves `FindAndModifyEnabled` (`findAndModify` has a `sort` slot).
    */
-  sort(spec: SortSpec<Shape>): PipelineChain<TContract, Shape, 'update-cleared', F, 'past-leading', N$1>;
+  sort(spec: SortSpec<Shape>): PipelineChain<TContract, Shape, 'update-cleared', F, 'past-leading', N>;
   /**
    * `$limit`. Clears both markers — `limit` is incompatible with the `update`
    * wire command, and `findAndModify` already implies single-document
    * semantics (so `.limit(...)` adds no meaning, only ambiguity).
    */
-  limit(n: number): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  limit(n: number): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
   /**
    * `$skip`. Clears both markers — MongoDB's `findAndModify` wire command
    * has no `skip` slot, so `deconstructFindAndModifyChain` rejects any
    * `$skip` at runtime; keeping the marker `fam-cleared` makes the type
    * system reflect the same constraint (see ADR 201 marker table).
    */
-  skip(n: number): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
-  sample(n: number): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  skip(n: number): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
+  sample(n: number): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
   /**
    * `$addFields`. Preserves `UpdateEnabled` (representable as
    * update-with-pipeline `$set`); clears `FindAndModifyEnabled` (no analogue
@@ -618,22 +818,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>) => NewFields): PipelineChain<TContract, Shape & ExtractDocShape<NewFields>, U, 'fam-cleared', 'past-leading', N>;
   /**
    * `$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 extends string, As extends string>(fn: (from: LookupFrom<TContract, Shape, N>) => LookupResult<RootName, ModelName, As>): PipelineChain<TContract, Shape & Record<As, ModelArrayField<ModelName>>, 'update-cleared', 'fam-cleared', 'past-leading', N>;
   /**
    * `$project`. Preserves `UpdateEnabled` (representable as update-with-pipeline
    * `$project` / `$unset`); clears `FindAndModifyEnabled` (use `.project()` on
@@ -644,8 +843,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 extends keyof Shape & string>(...keys: K[]): PipelineChain<TContract, Pick<Shape, K | ('_id' extends keyof Shape ? '_id' : never)>, U, 'fam-cleared', 'past-leading'>;
+  project<Spec extends Record<string, 1 | TypedAggExpr<DocField>>>(fn: (fields: FieldAccessor<Shape, N>) => Spec): PipelineChain<TContract, ProjectedShape<Shape, Spec>, U, 'fam-cleared', 'past-leading'>;
   /**
    * `$unwind`. Clears both markers — array unrolling produces multiple output
    * documents per input, incompatible with both single-document update and
@@ -653,27 +852,27 @@ declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoCon
    * replaces the unwound array slot with its element but leaves the rest
    * of the document structurally intact.
    */
-  unwind<K$1 extends keyof Shape & string>(field: K$1, options?: {
+  unwind<K extends keyof Shape & string>(field: K, options?: {
     preserveNullAndEmptyArrays?: boolean;
-  }): PipelineChain<TContract, UnwoundShape<Shape, K$1>, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  }): PipelineChain<TContract, UnwoundShape<Shape, K>, 'update-cleared', 'fam-cleared', 'past-leading', N>;
   /**
    * `$group`. Clears both markers — group output bears no relation to source
    * documents; neither `update` nor `findAndModify` can consume it. Nested
    * path shape is reset (the source document's path tree is gone).
    */
-  group<Spec extends GroupSpec>(fn: (fields: FieldAccessor<Shape, N$1>) => Spec): PipelineChain<TContract, GroupedDocShape<Spec>, 'update-cleared', 'fam-cleared', 'past-leading'>;
+  group<Spec extends GroupSpec>(fn: (fields: FieldAccessor<Shape, N>) => Spec): PipelineChain<TContract, GroupedDocShape<Spec>, 'update-cleared', 'fam-cleared', 'past-leading'>;
   /**
    * `$replaceRoot`. Preserves `UpdateEnabled` (representable as
    * update-with-pipeline `$replaceRoot`); clears `FindAndModifyEnabled`.
    * 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>) => Expression<DocField> | TypedAggExpr<DocField>): PipelineChain<TContract, NewShape, U, 'fam-cleared', 'past-leading'>;
   count<Field extends string>(field: Field): PipelineChain<TContract, Record<Field, {
     readonly codecId: 'mongo/double@1';
     readonly nullable: false;
   }>, 'update-cleared', 'fam-cleared', 'past-leading'>;
-  sortByCount<F2 extends DocField>(fn: (fields: FieldAccessor<Shape, N$1>) => Expression<F2> | TypedAggExpr<F2>): PipelineChain<TContract, {
+  sortByCount<F2 extends DocField>(fn: (fields: FieldAccessor<Shape, N>) => Expression<F2> | TypedAggExpr<F2>): PipelineChain<TContract, {
     _id: F2;
     count: {
       readonly codecId: 'mongo/double@1';
@@ -684,7 +883,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>) => Expression<DocField> | TypedAggExpr<DocField>): PipelineChain<TContract, Shape, U, 'fam-cleared', 'past-leading', N>;
   /**
    * `$out` write terminal. Materialises the pipeline output into
    * `collection` (optionally in `db`), replacing any prior contents. Unlike
@@ -714,7 +913,7 @@ declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoCon
     whenMatched?: string | ReadonlyArray<MongoUpdatePipelineStage>;
     whenNotMatched?: string;
   }): MongoQueryPlan<unknown, AggregateCommand>;
-  unionWith(collection: string, pipeline?: ReadonlyArray<MongoPipelineStage>): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  unionWith(collection: string, pipeline?: ReadonlyArray<MongoPipelineStage>): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
   bucket(options: {
     groupBy: MongoAggExpr;
     boundaries: ReadonlyArray<unknown>;
@@ -758,14 +957,14 @@ declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoCon
     field: string;
     partitionByFields?: ReadonlyArray<string>;
     range: MongoDensifyRange;
-  }): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  }): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
   fill(options: {
     partitionBy?: MongoAggExpr;
     partitionByFields?: ReadonlyArray<string>;
     sortBy?: Record<string, 1 | -1>;
     output: Record<string, MongoFillOutput>;
-  }): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
-  search(config: Record<string, unknown>, index?: string): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  }): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
+  search(config: Record<string, unknown>, index?: string): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
   searchMeta(config: Record<string, unknown>, index?: string): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
   vectorSearch(options: {
     index: string;
@@ -774,7 +973,7 @@ declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoCon
     numCandidates: number;
     limit: number;
     filter?: Record<string, unknown>;
-  }): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  }): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
   pipe(stage: MongoPipelineStage): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading'>;
   pipe<NewShape extends DocShape>(stage: MongoPipelineStage): PipelineChain<TContract, NewShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
   /**
@@ -795,14 +994,14 @@ declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoCon
    * code. See `docs/architecture docs/adrs/ADR 201 - State-machine
    * pattern for typed DSL builders.md` for the marker-transition table.
    */
-  updateMany(this: PipelineChain<TContract, Shape, 'update-ok', F, L, N$1>, updaterFn?: (fields: FieldAccessor<Shape, N$1>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateManyCommand>;
+  updateMany(this: PipelineChain<TContract, Shape, 'update-ok', F, L, N>, updaterFn?: (fields: FieldAccessor<Shape, N>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateManyCommand>;
   /**
    * No-arg `updateOne()`: same as `updateMany()` but maps to a single-doc
    * update. Carries the same optional-callback/subclass-compat caveat
    * documented above — the callback form is reachable only via forced
    * casts in internal tests.
    */
-  updateOne(this: PipelineChain<TContract, Shape, 'update-ok', F, L, N$1>, updaterFn?: (fields: FieldAccessor<Shape, N$1>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateOneCommand>;
+  updateOne(this: PipelineChain<TContract, Shape, 'update-ok', F, L, N>, updaterFn?: (fields: FieldAccessor<Shape, N>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateOneCommand>;
   /**
    * Find a single document matching the accumulated pipeline (which must
    * consist solely of leading `$match` stages followed by at most one
@@ -816,23 +1015,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, 'fam-ok', L, N>, updaterFn: (fields: FieldAccessor<Shape, N>) => 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, 'fam-ok', L, N>): 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
@@ -1158,12 +1357,12 @@ declare class FilteredCollection<TContract extends MongoContractWithTypeMaps<Mon
   findOneAndUpdate(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult, opts?: {
     readonly upsert?: boolean;
     readonly returnDocument?: 'before' | 'after';
-  }): MongoQueryPlan<ResolveRow<ModelToDocShape<TContract, ModelName>, ExtractMongoCodecTypes<TContract>> | null, FindOneAndUpdateCommand>;
+  }): MongoQueryPlan<ResolveRow<ModelToDocShape<TContract, ModelName>, 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>, ExtractMongoCodecTypes<TContract>, TContract> | null, FindOneAndDeleteCommand>;
 }
 /**
  * Bound execution context shared across the three state classes.
@@ -1187,12 +1386,19 @@ interface BindingContext<TContract extends MongoContractWithTypeMaps<MongoContra
  * cannot know what the caller's command yields.
  */
 interface QueryRoot<TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>> {
-  from<K$1 extends keyof TContract['roots'] & string>(rootName: K$1): CollectionHandle<TContract, TContract['roots'][K$1] & string & keyof TContract['models']>;
-  rawCommand<C$1 extends AnyMongoCommand>(command: C$1): MongoQueryPlan<unknown, C$1>;
+  from<K extends keyof TContract['roots'] & string>(rootName: K): CollectionHandle<TContract, TContract['roots'][K] & string & keyof TContract['models']>;
+  rawCommand<C extends AnyMongoCommand>(command: C): MongoQueryPlan<unknown, C>;
 }
 declare function mongoQuery<TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>>(options: {
   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