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

package/package.json

@@ -1,21 +1,23 @@
 {
   "name": "@prisma-next/mongo-query-builder",
-  "version": "0.5.0-dev.9",
+  "version": "0.6.0-dev.1",
+  "license": "Apache-2.0",
   "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/contract": "0.5.0-dev.9",
-    "@prisma-next/mongo-contract": "0.5.0-dev.9",
-    "@prisma-next/mongo-query-ast": "0.5.0-dev.9",
-    "@prisma-next/mongo-value": "0.5.0-dev.9"
+    "@prisma-next/contract": "0.6.0-dev.1",
+    "@prisma-next/mongo-value": "0.6.0-dev.1",
+    "@prisma-next/mongo-contract": "0.6.0-dev.1",
+    "@prisma-next/utils": "0.6.0-dev.1",
+    "@prisma-next/mongo-query-ast": "0.6.0-dev.1"
   },
   "devDependencies": {
-    "tsdown": "0.18.4",
+    "tsdown": "0.22.0",
     "typescript": "5.9.3",
-    "vitest": "4.0.17",
-    "@prisma-next/tsdown": "0.0.0",
-    "@prisma-next/tsconfig": "0.0.0"
+    "vitest": "4.1.5",
+    "@prisma-next/tsconfig": "0.0.0",
+    "@prisma-next/tsdown": "0.0.0"
   },
   "files": [
     "dist",

package/src/builder.ts

@@ -3,6 +3,7 @@ import type {
   ExtractMongoCodecTypes,
   MongoContract,
   MongoContractWithTypeMaps,
+  MongoModelDefinition,
   MongoTypeMaps,
 } from '@prisma-next/mongo-contract';
 import type {
@@ -14,6 +15,7 @@ import type {
   MongoPipelineStage,
   MongoProjectionValue,
   MongoQueryPlan,
+  MongoResultShape,
   MongoUpdatePipelineStage,
   MongoWindowField,
   UpdateResult,
@@ -54,9 +56,18 @@ import {
   UpdateManyCommand,
   UpdateOneCommand,
 } 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 type { NestedDocShape } from './resolve-path';
+import { pipelineSupportsFlatResultShape } from './pipeline-result-shape';
+import type { ModelArrayField, NestedDocShape } from './resolve-path';
+import { contractModelToMongoResultShape } from './result-shape';
 import type {
   DocField,
   DocShape,
@@ -75,6 +86,7 @@ interface PipelineChainState {
   readonly collection: string;
   readonly stages: ReadonlyArray<MongoPipelineStage>;
   readonly storageHash: string;
+  readonly modelName?: string;
 }
 
 /**
@@ -148,7 +160,6 @@ export class PipelineChain<
       target: 'mongo',
       storageHash: this.#state.storageHash,
       lane: 'mongo-query',
-      paramDescriptors: [],
     };
   }
 
@@ -260,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,
       }),
     );
   }
@@ -509,7 +519,6 @@ export class PipelineChain<
       target: 'mongo',
       storageHash: this.#state.storageHash,
       lane: 'mongo-query',
-      paramDescriptors: [],
     };
     return { collection: this.#state.collection, command, meta };
   }
@@ -748,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);
@@ -767,7 +776,6 @@ export class PipelineChain<
       target: 'mongo',
       storageHash: this.#state.storageHash,
       lane: 'mongo-query',
-      paramDescriptors: [],
     };
     return { collection: this.#state.collection, command, meta };
   }
@@ -779,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);
@@ -788,7 +796,6 @@ export class PipelineChain<
       target: 'mongo',
       storageHash: this.#state.storageHash,
       lane: 'mongo-query',
-      paramDescriptors: [],
     };
     return { collection: this.#state.collection, command, meta };
   }
@@ -798,22 +805,40 @@ 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',
       storageHash: this.#state.storageHash,
       lane: 'mongo-query',
-      paramDescriptors: [],
     };
-    return { collection: this.#state.collection, command, meta };
+    const modelName = this.#state.modelName;
+    const contractNarrow = this.#contract as MongoContract;
+    let resultShape: MongoResultShape | undefined;
+    if (modelName !== undefined) {
+      if (pipelineSupportsFlatResultShape(this.#state.stages)) {
+        const model = contractNarrow.models[modelName] as MongoModelDefinition | undefined;
+        resultShape = model ? contractModelToMongoResultShape(model) : { kind: 'unknown' as const };
+      } else {
+        resultShape = { kind: 'unknown' as const };
+      }
+    }
+    return {
+      collection: this.#state.collection,
+      command,
+      meta,
+      ...ifDefined('resultShape', resultShape),
+    };
   }
 
   /**
    * 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,
@@ -25,6 +34,10 @@ export type {
   ResolvePath,
   ValidPaths,
 } from '../resolve-path';
+export {
+  contractFieldToMongoFieldShape,
+  contractModelToMongoResultShape,
+} from '../result-shape';
 export { CollectionHandle, FilteredCollection } from '../state-classes';
 export type {
   ArrayField,

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/pipeline-result-shape.ts

@@ -0,0 +1,15 @@
+import type { MongoPipelineStage } from '@prisma-next/mongo-query-ast/execution';
+
+const identityStageKinds = new Set(['match', 'sort', 'limit', 'skip', 'sample']);
+
+export function pipelineSupportsFlatResultShape(
+  stages: ReadonlyArray<MongoPipelineStage>,
+): boolean {
+  for (const stage of stages) {
+    const k = stage.kind;
+    if (!identityStageKinds.has(k)) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/query.ts

@@ -47,7 +47,6 @@ export function mongoQuery<
         target: 'mongo',
         storageHash: String(storageHash),
         lane: 'mongo-query',
-        paramDescriptors: [],
       };
       return { collection: command.collection, command, meta };
     },

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/result-shape.ts

@@ -0,0 +1,63 @@
+import type { ContractField } from '@prisma-next/contract/types';
+import type { MongoModelDefinition } from '@prisma-next/mongo-contract';
+import type { MongoFieldShape, MongoResultShape } from '@prisma-next/mongo-query-ast/execution';
+import {
+  freezeMongoFieldShape,
+  freezeMongoResultShape,
+} from '@prisma-next/mongo-query-ast/execution';
+
+export function contractFieldToMongoFieldShape(field: ContractField): MongoFieldShape {
+  const { type, nullable, many } = field;
+  if (type.kind === 'valueObject' || type.kind === 'union') {
+    return Object.freeze({ kind: 'unknown' as const });
+  }
+  if (type.kind !== 'scalar') {
+    return Object.freeze({ kind: 'unknown' as const });
+  }
+  if (field.dict === true) {
+    return Object.freeze({ kind: 'unknown' as const });
+  }
+  if (many === true) {
+    return freezeMongoFieldShape({
+      kind: 'array',
+      nullable,
+      element: { kind: 'leaf', codecId: type.codecId, nullable: false },
+    });
+  }
+  return freezeMongoFieldShape({
+    kind: 'leaf',
+    codecId: type.codecId,
+    nullable,
+  });
+}
+
+export function contractModelToMongoResultShape(
+  model: MongoModelDefinition,
+  options?: {
+    readonly selection?: readonly string[];
+    readonly includeRelationNames?: readonly string[];
+  },
+): MongoResultShape {
+  const fields: Record<string, MongoFieldShape> = {};
+  for (const rel of options?.includeRelationNames ?? []) {
+    fields[rel] = Object.freeze({ kind: 'unknown' as const });
+  }
+  const modelFields = model.fields;
+  // An explicit empty selection is honored as-is (returns a document shape
+  // with no fields). Only the absence of a selection falls back to the model's
+  // full field set.
+  const keys = options?.selection !== undefined ? options.selection : Object.keys(modelFields);
+
+  for (const key of keys) {
+    if (Object.hasOwn(fields, key)) {
+      continue;
+    }
+    const cf = modelFields[key];
+    if (!cf) {
+      fields[key] = Object.freeze({ kind: 'unknown' as const });
+      continue;
+    }
+    fields[key] = contractFieldToMongoFieldShape(cf);
+  }
+  return freezeMongoResultShape({ kind: 'document', fields });
+}