@prisma-next/mongo-query-builder 0.5.0-dev.53 → 0.5.0-dev.54

package/package.json

@@ -1,22 +1,22 @@
 {
   "name": "@prisma-next/mongo-query-builder",
-  "version": "0.5.0-dev.53",
+  "version": "0.5.0-dev.54",
   "type": "module",
   "sideEffects": false,
   "description": "Type-safe MongoDB query builder (reads, writes, find-and-modify, pipeline-terminal writes) with document shape tracking",
   "dependencies": {
-    "@prisma-next/mongo-contract": "0.5.0-dev.53",
-    "@prisma-next/contract": "0.5.0-dev.53",
-    "@prisma-next/mongo-query-ast": "0.5.0-dev.53",
-    "@prisma-next/utils": "0.5.0-dev.53",
-    "@prisma-next/mongo-value": "0.5.0-dev.53"
+    "@prisma-next/contract": "0.5.0-dev.54",
+    "@prisma-next/mongo-contract": "0.5.0-dev.54",
+    "@prisma-next/mongo-query-ast": "0.5.0-dev.54",
+    "@prisma-next/mongo-value": "0.5.0-dev.54",
+    "@prisma-next/utils": "0.5.0-dev.54"
   },
   "devDependencies": {
     "tsdown": "0.18.4",
     "typescript": "5.9.3",
     "vitest": "4.0.17",
-    "@prisma-next/tsconfig": "0.0.0",
-    "@prisma-next/tsdown": "0.0.0"
+    "@prisma-next/tsdown": "0.0.0",
+    "@prisma-next/tsconfig": "0.0.0"
   },
   "files": [
     "dist",

package/src/builder.ts

@@ -58,9 +58,15 @@ import {
 } from '@prisma-next/mongo-query-ast/execution';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { createFieldAccessor, type Expression, type FieldAccessor } from './field-accessor';
+import {
+  createLookupFrom,
+  extractLookupResult,
+  type LookupFrom,
+  type LookupResult,
+} from './lookup-builder';
 import type { FindAndModifyEnabled, LeadingMatch, UpdateEnabled } from './markers';
 import { pipelineSupportsFlatResultShape } from './pipeline-result-shape';
-import type { NestedDocShape } from './resolve-path';
+import type { ModelArrayField, NestedDocShape } from './resolve-path';
 import { contractModelToMongoResultShape } from './result-shape';
 import type {
   DocField,
@@ -265,40 +271,39 @@ export class PipelineChain<
    * 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<
+  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, { readonly codecId: 'mongo/array@1'; readonly nullable: false }>,
+    Shape & Record<As, ModelArrayField<ModelName>>,
     'update-cleared',
     'fam-cleared',
     'past-leading',
     N
   > {
-    const contract: MongoContract = this.#contract;
-    const modelName = contract.roots[options.from];
-    if (!modelName) {
-      const validRoots = Object.keys(contract.roots).join(', ');
-      throw new Error(`lookup() unknown root: "${options.from}". Valid roots: ${validRoots}`);
-    }
-    const model = contract.models[modelName];
-    const collectionName = model?.storage?.collection ?? options.from;
+    const fromCallable = createLookupFrom<TContract, Shape, N>(this.#contract);
+    const result = fn(fromCallable);
+    const extracted = extractLookupResult(result, this.#contract);
     return this.#withStage<
-      Shape & Record<As, { readonly codecId: 'mongo/array@1'; readonly nullable: false }>,
+      Shape & Record<As, ModelArrayField<ModelName>>,
       'update-cleared',
       'fam-cleared',
       'past-leading',
       N
     >(
       new MongoLookupStage({
-        from: collectionName,
-        localField: options.localField,
-        foreignField: options.foreignField,
-        as: options.as,
+        from: extracted.foreignCollection,
+        localField: extracted.localField,
+        foreignField: extracted.foreignField,
+        as: extracted.as,
       }),
     );
   }
@@ -752,7 +757,7 @@ export class PipelineChain<
     updaterFn: (fields: FieldAccessor<Shape, N>) => UpdaterResult,
     opts: { readonly upsert?: boolean; readonly returnDocument?: 'before' | 'after' } = {},
   ): MongoQueryPlan<
-    ResolveRow<Shape, ExtractMongoCodecTypes<TContract>> | null,
+    ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, TContract> | null,
     FindOneAndUpdateCommand
   > {
     const { filter, sort } = deconstructFindAndModifyChain(this.#state.stages);
@@ -782,7 +787,7 @@ export class PipelineChain<
   findOneAndDelete(
     this: PipelineChain<TContract, Shape, U, 'fam-ok', L, N>,
   ): MongoQueryPlan<
-    ResolveRow<Shape, ExtractMongoCodecTypes<TContract>> | null,
+    ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, TContract> | null,
     FindOneAndDeleteCommand
   > {
     const { filter, sort } = deconstructFindAndModifyChain(this.#state.stages);
@@ -800,7 +805,10 @@ export class PipelineChain<
   /**
    * Materialise the chain as a `MongoQueryPlan` wrapping an `AggregateCommand`.
    */
-  build(): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>>, AggregateCommand> {
+  build(): MongoQueryPlan<
+    ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, TContract>,
+    AggregateCommand
+  > {
     const command = new AggregateCommand(this.#state.collection, this.#state.stages);
     const meta: PlanMeta = {
       target: 'mongo',
@@ -830,7 +838,7 @@ export class PipelineChain<
    * Alias for `build()` — surfaces the read intent at the call site.
    */
   aggregate(): MongoQueryPlan<
-    ResolveRow<Shape, ExtractMongoCodecTypes<TContract>>,
+    ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, TContract>,
     AggregateCommand
   > {
     return this.build();

package/src/exports/index.ts

@@ -14,10 +14,19 @@ export type {
   ObjectExpression,
 } from '../field-accessor';
 export { createFieldAccessor } from '../field-accessor';
+export type {
+  LookupBuilder,
+  LookupBuilderWithKey,
+  LookupFrom,
+  LookupOnResult,
+  LookupResult,
+  ModelOf,
+} from '../lookup-builder';
 export type { FindAndModifyEnabled, UpdateEnabled } from '../markers';
 export type { QueryRoot } from '../query';
 export { mongoQuery } from '../query';
 export type {
+  ModelArrayField,
   ModelNestedShape,
   NestedDocShape,
   ObjectField,

package/src/lookup-builder.ts

@@ -0,0 +1,272 @@
+import type { MongoContract } from '@prisma-next/mongo-contract';
+import { createFieldAccessor, type FieldAccessor, type LeafExpression } from './field-accessor';
+import type { ModelNestedShape } from './resolve-path';
+import type { DocField, DocShape, ModelToDocShape } from './types';
+
+/**
+ * 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']`).
+ */
+export 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).
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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)`.
+ */
+export 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).
+ */
+export 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>>;
+
+/**
+ * Construct the `from` callable for `PipelineChain.lookup`. The contract
+ * is captured so `from(name)` can resolve `roots[name]` to the foreign
+ * model name at runtime, look up the foreign collection name from
+ * `models[modelName].storage.collection`, and assemble a `LookupResult`
+ * for the outer `lookup` to consume.
+ *
+ * The `Shape`/`Nested` generics are erased at runtime — they exist only
+ * to type the local accessor inside the user's `on(...)` callback. The
+ * contract value at runtime carries the real model lookup table.
+ */
+export function createLookupFrom<
+  TContract extends MongoContract,
+  Shape extends DocShape,
+  Nested extends Record<string, DocField>,
+>(contract: TContract): LookupFrom<TContract, Shape, Nested> {
+  const callable = ((rootName) => {
+    const modelName = contract.roots[rootName];
+    if (!modelName) {
+      const validRoots = Object.keys(contract.roots).join(', ');
+      throw new Error(`lookup() unknown root: "${rootName}". Valid roots: ${validRoots}`);
+    }
+    const model = contract.models[modelName];
+    const foreignCollection = model?.storage?.collection ?? rootName;
+    return createLookupBuilder({
+      rootName,
+      modelName,
+      foreignCollection,
+    });
+    // The runtime callable accepts a single `string` and returns a
+    // generic `LookupBuilder`; the literal `RootName` / `ModelName`
+    // generics on `LookupFrom` are erased at runtime and re-asserted
+    // here so the surface contract is what the consumer actually sees.
+  }) as LookupFrom<TContract, Shape, Nested>;
+  return callable;
+}
+
+interface LookupBuilderRuntimeState {
+  readonly rootName: string;
+  readonly modelName: string;
+  readonly foreignCollection: string;
+}
+
+function createLookupBuilder<
+  TContract extends MongoContract,
+  Shape extends DocShape,
+  Nested extends Record<string, DocField>,
+  RootName extends string,
+  ModelName extends string,
+>(state: LookupBuilderRuntimeState): LookupBuilder<TContract, Shape, Nested, RootName, ModelName> {
+  return {
+    on(cb) {
+      const localAccessor = createFieldAccessor<Shape, Nested>();
+      // Foreign accessor is built unparameterised at runtime — the codec
+      // metadata is type-only, and `_path` (the only thing we read off
+      // either side) is filled by property access regardless of the
+      // generic parameters. The narrow generic on the callback signature
+      // is what gives the user the foreign model's keys at compile time.
+      const foreignAccessor = createFieldAccessor<DocShape, Record<string, DocField>>();
+      const result = cb(localAccessor, foreignAccessor as Parameters<typeof cb>[1]);
+      assertLeafExpression(result.local, 'local');
+      assertLeafExpression(result.foreign, 'foreign');
+      return createLookupBuilderWithKey<RootName, ModelName>({
+        ...state,
+        localField: result.local._path,
+        foreignField: result.foreign._path,
+      });
+    },
+  };
+}
+
+interface LookupBuilderWithKeyRuntimeState extends LookupBuilderRuntimeState {
+  readonly localField: string;
+  readonly foreignField: string;
+}
+
+function createLookupBuilderWithKey<RootName extends string, ModelName extends string>(
+  state: LookupBuilderWithKeyRuntimeState,
+): LookupBuilderWithKey<RootName, ModelName> {
+  return {
+    as<As extends string>(name: As): LookupResult<RootName, ModelName, As> {
+      return {
+        _brand: 'mongo-query-builder/lookup-result@1',
+        // The `RootName` / `ModelName` literal generics are erased at
+        // runtime; the runtime state holds the same strings as plain
+        // `string`. Re-brand so consumers (the lookup-stage builder)
+        // can read the literals back without a downstream cast.
+        _root: state.rootName as RootName,
+        _model: state.modelName as ModelName,
+        _localField: state.localField,
+        _foreignField: state.foreignField,
+        _as: name,
+      };
+    },
+  };
+}
+
+/**
+ * Defensive runtime guard catching the case where a user returns a
+ * non-`LeafExpression` from the `on(...)` callback (e.g. by casting
+ * around the type system, or threading a value in from outside the
+ * callback). Compile-time gating via `LookupOnResult`'s `LeafExpression`
+ * type already rejects `fn.<op>(…)` returns at the type level — this
+ * guard is the runtime backstop matching the defensive style of
+ * `deconstructFindAndModifyChain` in builder.ts.
+ */
+function assertLeafExpression(
+  value: LeafExpression<DocField>,
+  side: 'local' | 'foreign',
+): asserts value is LeafExpression<DocField> {
+  if (!value || typeof value._path !== 'string' || value._path.length === 0) {
+    throw new Error(
+      `lookup().on() ${side} side must return a leaf field reference (e.g. \`${side}.<field>\`). ` +
+        'Aggregation expressions and computed values are not supported.',
+    );
+  }
+}
+
+/**
+ * Extract the runtime metadata from a `LookupResult` for `PipelineChain
+ * .lookup` to construct the `MongoLookupStage`. The internal fields are
+ * intentionally underscore-prefixed and brand-checked here so user code
+ * cannot synthesise a fake spec; this is the single ingress point.
+ */
+export function extractLookupResult(
+  result: LookupResult<string, string, string>,
+  contract: MongoContract,
+): {
+  readonly foreignCollection: string;
+  readonly localField: string;
+  readonly foreignField: string;
+  readonly as: string;
+  readonly modelName: string;
+} {
+  if (!result || result._brand !== 'mongo-query-builder/lookup-result@1') {
+    throw new Error(
+      'lookup() callback must return the result of `from(name).on(cb).as(name)`. ' +
+        'Returning a hand-rolled options object is not supported.',
+    );
+  }
+  const model = contract.models[result._model];
+  const foreignCollection = model?.storage?.collection ?? result._root;
+  return {
+    foreignCollection,
+    localField: result._localField,
+    foreignField: result._foreignField,
+    as: result._as,
+    modelName: result._model,
+  };
+}

package/src/resolve-path.ts

@@ -23,6 +23,60 @@ export interface ObjectField<N extends NestedDocShape> extends DocField {
   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.
+ */
+export 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.
+ */
+export declare const ModelOriginBrand: unique symbol;
+export 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>`.
+ */
+export type ModelOriginBranded<ModelName extends string> = {
+  readonly [ModelOriginBrand]?: ModelName;
+};
+
 /**
  * Document shape that carries nested value-object sub-shapes.
  *

package/src/state-classes.ts

@@ -546,7 +546,11 @@ export class FilteredCollection<
     ) => UpdaterResult,
     opts: { readonly upsert?: boolean; readonly returnDocument?: 'before' | 'after' } = {},
   ): MongoQueryPlan<
-    ResolveRow<ModelToDocShape<TContract, ModelName>, ExtractMongoCodecTypes<TContract>> | null,
+    ResolveRow<
+      ModelToDocShape<TContract, ModelName>,
+      ExtractMongoCodecTypes<TContract>,
+      TContract
+    > | null,
     FindOneAndUpdateCommand
   > {
     const update = resolveUpdaterCallback<
@@ -573,7 +577,11 @@ export class FilteredCollection<
    * document via the row stream.
    */
   override findOneAndDelete(): MongoQueryPlan<
-    ResolveRow<ModelToDocShape<TContract, ModelName>, ExtractMongoCodecTypes<TContract>> | null,
+    ResolveRow<
+      ModelToDocShape<TContract, ModelName>,
+      ExtractMongoCodecTypes<TContract>,
+      TContract
+    > | null,
     FindOneAndDeleteCommand
   > {
     const command = new FindOneAndDeleteCommand(this.#ctx.collection, this.#foldedFilter());

package/src/types.ts

@@ -1,5 +1,12 @@
-import type { MongoContract } from '@prisma-next/mongo-contract';
+import type {
+  ExtractMongoTypeMaps,
+  InferModelRow,
+  MongoContract,
+  MongoContractWithTypeMaps,
+  MongoTypeMaps,
+} from '@prisma-next/mongo-contract';
 import type { MongoAggAccumulator, MongoAggExpr } from '@prisma-next/mongo-query-ast/execution';
+import type { ModelArrayField, ModelOriginBrand, ModelOriginBranded } from './resolve-path';
 
 export interface DocField {
   readonly codecId: string;
@@ -40,19 +47,103 @@ export type ModelToDocShape<
     readonly codecId: ExtractCodecId<TContract['models'][ModelName]['fields'][K]>;
     readonly nullable: TContract['models'][ModelName]['fields'][K]['nullable'];
   };
-};
+} & ModelOriginBranded<ModelName>;
 
-export type ResolveRow<
+/**
+ * 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]['codecId'] extends keyof CodecTypes
-    ? Shape[K]['nullable'] extends true
-      ? CodecTypes[Shape[K]['codecId']]['output'] | null
-      : CodecTypes[Shape[K]['codecId']]['output']
-    : unknown;
+  -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;
+
+export 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>;
+
 export interface TypedAggExpr<F extends DocField> {
   readonly _field: F;
   readonly node: MongoAggExpr;
@@ -108,6 +199,16 @@ export type GroupedDocShape<Spec extends GroupSpec> = {
  */
 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.
+ */
 export 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);